4 Note: The primary location for this document is now the IRCv3 sasl-3.1
5 specification, at address:
7 http://ircv3.atheme.org/extensions/sasl-3.1
9 This document describes the client protocol for SASL authentication, as
10 implemented in Charybdis and Atheme. The SASL protocol in general is documented
11 in RFC 4422 [2], along with the 'EXTERNAL' mechanism. The most commonly used
12 'PLAIN' mechanism is documented in RFC 4616 [3].
14 SASL authentication relies on the CAP client capability framework [1].
15 Support for SASL authentication is indicated with the "sasl" capability.
16 The client MUST enable the sasl capability before using the AUTHENTICATE
17 command defined by this specification.
19 The AUTHENTICATE command
21 The AUTHENTICATE command MUST be used before registration is complete and
22 with the sasl capability enabled. To enforce the former, it is RECOMMENDED
23 to only send CAP END when the SASL exchange is completed or needs to be
24 aborted. Clients SHOULD be prepared for timeouts at all times during the SASL
27 There are two forms of the AUTHENTICATE command: initial client message and
30 The initial client message specifies the SASL mechanism to be used. (When this
31 is received, the IRCD will attempt to establish an association with a SASL
32 agent.) If this fails, a 904 numeric will be sent and the session state remains
33 unchanged; the client MAY try another mechanism. Otherwise, the server sends
34 a set of regular AUTHENTICATE messages with the initial server response.
36 initial-authenticate = "AUTHENTICATE" SP mechanism CRLF
38 A set of regular AUTHENTICATE messages transmits a response from client to
39 server or vice versa. The server MAY intersperse other IRC protocol messages
40 between the AUTHENTICATE messages of a set. The "+" form is used for an empty
41 response. The server MAY place a limit on the total length of a response.
43 regular-authenticate-set = *("AUTHENTICATE" SP 400BASE64 CRLF)
44 "AUTHENTICATE" SP (1*399BASE64 / "+") CRLF
46 The client can abort an authentication by sending an asterisk as the data.
47 The server will send a 904 numeric.
49 authenticate-abort = "AUTHENTICATE" SP "*" CRLF
51 If authentication fails, a 904 or 905 numeric will be sent and the
52 client MAY retry from the AUTHENTICATE <mechanism> command.
53 If authentication is successful, a 900 and 903 numeric will be sent.
55 If the client attempts to issue the AUTHENTICATE command after already
56 authenticating successfully, the server MUST reject it with a 907 numeric.
58 If the client completes registration (with CAP END, NICK, USER and any other
59 necessary messages) while the SASL authentication is still in progress, the
60 server SHOULD abort it and send a 906 numeric, then register the client
61 without authentication.
63 This document does not specify use of the AUTHENTICATE command in
64 registered (person) state.
66 Example protocol exchange
68 C: indicates lines sent by the client, S: indicates lines sent by the server.
70 The client is using the PLAIN SASL mechanism with authentication identity
71 jilles, authorization identity jilles and password sesame.
75 C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
76 S: NOTICE AUTH :*** Processing connection to jaguar.test
77 S: NOTICE AUTH :*** Looking up your hostname...
78 S: NOTICE AUTH :*** Checking Ident
79 S: NOTICE AUTH :*** No Ident response
80 S: NOTICE AUTH :*** Found your hostname
81 S: :jaguar.test CAP jilles ACK :sasl
84 C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
85 S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
86 S: :jaguar.test 903 jilles :SASL authentication successful
88 S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
89 <usual welcome messages>
91 Note that the CAP command sent by a server includes the user's nick or *,
92 differently from what [1] specifies.
94 Alternatively the client could request the list of capabilities and enable
95 an additional capability.
99 C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
100 S: NOTICE AUTH :*** Processing connection to jaguar.test
101 S: NOTICE AUTH :*** Looking up your hostname...
102 S: NOTICE AUTH :*** Checking Ident
103 S: NOTICE AUTH :*** No Ident response
104 S: NOTICE AUTH :*** Found your hostname
105 S: :jaguar.test CAP * LS :multi-prefix sasl
106 C: CAP REQ :multi-prefix sasl
107 S: :jaguar.test CAP jilles ACK :multi-prefix sasl
108 C: AUTHENTICATE PLAIN
110 C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
111 S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
112 S: :jaguar.test 903 jilles :SASL authentication successful
114 S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
115 <usual welcome messages>
117 [1] K. Mitchell, P. Lorier (Undernet IRC Network), L. Hardy (ircd-ratbox), P.
118 Kucharski (IRCnet), IRC Client Capabilities Extension. March 2005.
119 This internet-draft has expired; it can still be found on
120 http://www.leeh.co.uk/draft-mitchell-irc-capabilities-02.html
122 [2] A. Melnikov (Isode Limited), K. Zeilenga (OpenLDAP Foundation), Simple Authentication and Security Layer (SASL). June 2006. <https://tools.ietf.org/html/rfc4422>
124 [3] K. Zeilenga (OpenLDAP Foundation), The PLAIN Simple Authentication and Security Layer (SASL) Mechanism. August 2006. <https://tools.ietf.org/html/rfc4616>
126 $Id: sasl.txt 3169 2007-01-28 22:13:18Z jilles $