| 1 |
SASL authentication |
| 2 |
------------------- |
| 3 |
|
| 4 |
This document describes the client protocol for SASL authentication, as |
| 5 |
implemented in charybdis and atheme. |
| 6 |
|
| 7 |
SASL authentication relies on the CAP client capability framework [1]. |
| 8 |
Support for SASL authentication is indicated with the "sasl" capability. |
| 9 |
The client MUST enable the sasl capability before using the AUTHENTICATE |
| 10 |
command defined by this specification. |
| 11 |
|
| 12 |
The AUTHENTICATE command |
| 13 |
|
| 14 |
The AUTHENTICATE command MUST be used before registration is complete and |
| 15 |
with the sasl capability enabled. To enforce the former, it is RECOMMENDED |
| 16 |
to only send CAP END when the SASL exchange is completed or needs to be |
| 17 |
aborted. Clients SHOULD be prepared for timeouts at all times during the SASL |
| 18 |
authentication. |
| 19 |
|
| 20 |
There are two forms of the AUTHENTICATE command: initial client message and |
| 21 |
later messages. |
| 22 |
|
| 23 |
The initial client message specifies the SASL mechanism to be used. (When this |
| 24 |
is received, the IRCD will attempt to establish an association with a SASL |
| 25 |
agent.) If this fails, a 904 numeric will be sent and the session state remains |
| 26 |
unchanged; the client MAY try another mechanism. Otherwise, the server sends |
| 27 |
a set of regular AUTHENTICATE messages with the initial server response. |
| 28 |
|
| 29 |
initial-authenticate = "AUTHENTICATE" SP mechanism CRLF |
| 30 |
|
| 31 |
A set of regular AUTHENTICATE messages transmits a response from client to |
| 32 |
server or vice versa. The server MAY intersperse other IRC protocol messages |
| 33 |
between the AUTHENTICATE messages of a set. The "+" form is used for an empty |
| 34 |
response. The server MAY place a limit on the total length of a response. |
| 35 |
|
| 36 |
regular-authenticate-set = *("AUTHENTICATE" SP 400BASE64 CRLF) |
| 37 |
"AUTHENTICATE" SP (1*399BASE64 / "+") CRLF |
| 38 |
|
| 39 |
The client can abort an authentication by sending an asterisk as the data. |
| 40 |
The server will send a 904 numeric. |
| 41 |
|
| 42 |
authenticate-abort = "AUTHENTICATE" SP "*" CRLF |
| 43 |
|
| 44 |
If authentication fails, a 904 or 905 numeric will be sent and the |
| 45 |
client MAY retry from the AUTHENTICATE <mechanism> command. |
| 46 |
If authentication is successful, a 900 and 903 numeric will be sent. |
| 47 |
|
| 48 |
If the client attempts to issue the AUTHENTICATE command after already |
| 49 |
authenticating successfully, the server MUST reject it with a 907 numeric. |
| 50 |
|
| 51 |
If the client completes registration (with CAP END, NICK, USER and any other |
| 52 |
necessary messages) while the SASL authentication is still in progress, the |
| 53 |
server SHOULD abort it and send a 906 numeric, then register the client |
| 54 |
without authentication. |
| 55 |
|
| 56 |
This document does not specify use of the AUTHENTICATE command in |
| 57 |
registered (person) state. |
| 58 |
|
| 59 |
Example protocol exchange |
| 60 |
|
| 61 |
C: indicates lines sent by the client, S: indicates lines sent by the server. |
| 62 |
|
| 63 |
The client is using the PLAIN SASL mechanism with authentication identity |
| 64 |
jilles, authorization identity jilles and password sesame. |
| 65 |
|
| 66 |
C: CAP REQ :sasl |
| 67 |
C: NICK jilles |
| 68 |
C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker |
| 69 |
S: NOTICE AUTH :*** Processing connection to jaguar.test |
| 70 |
S: NOTICE AUTH :*** Looking up your hostname... |
| 71 |
S: NOTICE AUTH :*** Checking Ident |
| 72 |
S: NOTICE AUTH :*** No Ident response |
| 73 |
S: NOTICE AUTH :*** Found your hostname |
| 74 |
S: :jaguar.test CAP jilles ACK :sasl |
| 75 |
C: AUTHENTICATE PLAIN |
| 76 |
S: AUTHENTICATE + |
| 77 |
C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU= |
| 78 |
S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles. |
| 79 |
S: :jaguar.test 903 jilles :SASL authentication successful |
| 80 |
C: CAP END |
| 81 |
S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles |
| 82 |
<usual welcome messages> |
| 83 |
|
| 84 |
Note that the CAP command sent by a server includes the user's nick or *, |
| 85 |
differently from what [1] specifies. |
| 86 |
|
| 87 |
Alternatively the client could request the list of capabilities and enable |
| 88 |
an additional capability. |
| 89 |
|
| 90 |
C: CAP LS |
| 91 |
C: NICK jilles |
| 92 |
C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker |
| 93 |
S: NOTICE AUTH :*** Processing connection to jaguar.test |
| 94 |
S: NOTICE AUTH :*** Looking up your hostname... |
| 95 |
S: NOTICE AUTH :*** Checking Ident |
| 96 |
S: NOTICE AUTH :*** No Ident response |
| 97 |
S: NOTICE AUTH :*** Found your hostname |
| 98 |
S: :jaguar.test CAP * LS :multi-prefix sasl |
| 99 |
C: CAP REQ :multi-prefix sasl |
| 100 |
S: :jaguar.test CAP jilles ACK :multi-prefix sasl |
| 101 |
C: AUTHENTICATE PLAIN |
| 102 |
S: AUTHENTICATE + |
| 103 |
C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU= |
| 104 |
S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles. |
| 105 |
S: :jaguar.test 903 jilles :SASL authentication successful |
| 106 |
C: CAP END |
| 107 |
S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles |
| 108 |
<usual welcome messages> |
| 109 |
|
| 110 |
[1] K. Mitchell, P. Lorier (Undernet IRC Network), L. Hardy (ircd-ratbox), P. |
| 111 |
Kucharski (IRCnet), IRC Client Capabilities Extension. March 2005. |
| 112 |
This internet-draft has expired; it can still be found on |
| 113 |
http://www.leeh.co.uk/draft-mitchell-irc-capabilities-02.html |
| 114 |
|
| 115 |
See also http://sasl.charybdis.be/ and |
| 116 |
http://wiki.atheme.net/index.php/PR:SASL_Authentication (these links are |
| 117 |
currently dead but may be resurrected in the future). |
