Before gaining any useful privileges, all IPC clients must authenticate themselves by using an auth name and a password. Two levels of authentication are available:
System authentication
Object authentication
System authentication grants an application system-level permissions, for example: the ability to access the akill database, to list private data on nicknames in NickServ, or change certain parts of a nick that ordinary authentication to the nickname doesn't allow.
Object authentication grants a client extended permissions for a particular object; for example, by knowing a nickname's password, you can authenticate to that nickname in particular and make changes that your level of system authentication doesn't otherwise allow you.
In other words: system authentication grants a client certain rights on the system overall, and object authentication grants specific access to a particular nickname, channel, or other object and potentially other rights that are associated with being authenticated to that object.
System authentication occurs in a number of steps:
Connection: upon successful connection, a client is greeted with the following:
HELO IAM services.network.net AUTH SYSTEM PID XXXX AUTH SYSTEM LOGIN irc/services
The actual information shown depends on the services session. This verifies you are connecting to services IPC.
Once services has sent its AUTH SYSTEM LOGIN message, it now expects the client to send one. This can be done with:
AUTH SYSTEM LOGIN username
Upon receiving and processing AUTH SYSTEM LOGIN, services will reply with OK AUTH SYSTEM LOGIN. This verifies that the message was accepted: errors such as ERR-BADLOGIN AUTH SYSTEM LOGIN - Invalid login are also possible, but for this to occur on AUTH SYSTEM LOGIN, a syntax error is likely, because usernames that aren't valid authenticators do not normally flag an error until later in the authentication process.
In general, errors are prefixed by ERR-cause command - informative message
If your AUTH SYSTEM LOGIN message is successful, services will additionally send you another message of type AUTH COOKIE, for example:
AUTH COOKIE 10569CC3C9
Services uses challenge-response authentication for both system and object logins. This means that if IPC were to be extended over a network, passwords would not be exposed to sniffers over the plaintext protocol.
To respond to the message, it is necessary to compute a MD5 Message digest of the cookie and the password.
The following is what you need to compute:
MD5( cookie:authenticator )
In the cause of SYSTEM LOGINs, the authenticator is the password, whereas in the case of Object logins, the authenticator is typically MD5(password)
The MD5 function here indicates the base16 (hexadecimal) representation of the message digest, also known as md5hex.
Supposing my cookie were 123 and my password abc, I would compute
MD5("123:abc") = ebecf09cd7c661306f05c7c7fa017549
And login with:
AUTH SYSTEM PASS ebecf09cd7c661306f05c7c7fa017549
Recognition
An example of the message that follows a successful SYSTEM PASS:
OK AUTH SYSTEM PASS YOU ARE www/test
Once you receive the OK AUTH SYSTEM PASS message, your connection is authenticated, and you can issue ALTER, QUERY commands or authenticate to OBJECTs if the user you've authenticated with has those privileges.
The syntax and usage for OBJECT authentication is the same as that for SYSTEM authentication with a few differences.
Instead of AUTH SYSTEM LOGIN user, the message is:
AUTH OBJECT LOGIN object type object name
Object type is one of RNICK for Registered Nickname, or RCHAN for registered channel. New types could be created as well.
The response to a valid AUTH OBJECT LOGIN message is:
AUTH COOKIE XXX
And the client is then expected to send:
AUTH OBJECT PASS response
The response is the result of applying the MD5 function, in this fashion:
MD5(cookie:MD5(secret authenticator))
For RNICKs and RCHANs, the secret authenticator is simply their password.
Successful authentication to an object results in this message:
OK AUTH OBJECT RNICK PASS