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