1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc/sasl.txt	Mon Jul 13 12:55:35 2009 -0500
     1.3 @@ -0,0 +1,119 @@
     1.4 +SASL authentication
     1.5 +-------------------
     1.6 +
     1.7 +This document describes the client protocol for SASL authentication, as
     1.8 +implemented in charybdis and atheme.
     1.9 +
    1.10 +SASL authentication relies on the CAP client capability framework [1].
    1.11 +Support for SASL authentication is indicated with the "sasl" capability.
    1.12 +The client MUST enable the sasl capability before using the AUTHENTICATE
    1.13 +command defined by this specification.
    1.14 +
    1.15 +The AUTHENTICATE command
    1.16 +
    1.17 +The AUTHENTICATE command MUST be used before registration is complete and
    1.18 +with the sasl capability enabled. To enforce the former, it is RECOMMENDED
    1.19 +to only send CAP END when the SASL exchange is completed or needs to be
    1.20 +aborted. Clients SHOULD be prepared for timeouts at all times during the SASL
    1.21 +authentication.
    1.22 +
    1.23 +There are two forms of the AUTHENTICATE command: initial client message and
    1.24 +later messages.
    1.25 +
    1.26 +The initial client message specifies the SASL mechanism to be used. (When this
    1.27 +is received, the IRCD will attempt to establish an association with a SASL
    1.28 +agent.) If this fails, a 904 numeric will be sent and the session state remains
    1.29 +unchanged; the client MAY try another mechanism. Otherwise, the server sends
    1.30 +a set of regular AUTHENTICATE messages with the initial server response.
    1.31 +
    1.32 +initial-authenticate = "AUTHENTICATE" SP mechanism CRLF
    1.33 +
    1.34 +A set of regular AUTHENTICATE messages transmits a response from client to
    1.35 +server or vice versa. The server MAY intersperse other IRC protocol messages
    1.36 +between the AUTHENTICATE messages of a set. The "+" form is used for an empty
    1.37 +response. The server MAY place a limit on the total length of a response.
    1.38 +
    1.39 +regular-authenticate-set = *("AUTHENTICATE" SP 400BASE64 CRLF)
    1.40 +	"AUTHENTICATE" SP (1*399BASE64 / "+") CRLF
    1.41 +
    1.42 +The client can abort an authentication by sending an asterisk as the data.
    1.43 +The server will send a 904 numeric.
    1.44 +
    1.45 +authenticate-abort = "AUTHENTICATE" SP "*" CRLF
    1.46 +
    1.47 +If authentication fails, a 904 or 905 numeric will be sent and the
    1.48 +client MAY retry from the AUTHENTICATE <mechanism> command.
    1.49 +If authentication is successful, a 900 and 903 numeric will be sent.
    1.50 +
    1.51 +If the client attempts to issue the AUTHENTICATE command after already
    1.52 +authenticating successfully, the server MUST reject it with a 907 numeric.
    1.53 +
    1.54 +If the client completes registration (with CAP END, NICK, USER and any other
    1.55 +necessary messages) while the SASL authentication is still in progress, the
    1.56 +server SHOULD abort it and send a 906 numeric, then register the client
    1.57 +without authentication.
    1.58 +
    1.59 +This document does not specify use of the AUTHENTICATE command in
    1.60 +registered (person) state.
    1.61 +
    1.62 +Example protocol exchange
    1.63 +
    1.64 +C: indicates lines sent by the client, S: indicates lines sent by the server.
    1.65 +
    1.66 +The client is using the PLAIN SASL mechanism with authentication identity
    1.67 +jilles, authorization identity jilles and password sesame.
    1.68 +
    1.69 +C: CAP REQ :sasl
    1.70 +C: NICK jilles
    1.71 +C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
    1.72 +S: NOTICE AUTH :*** Processing connection to jaguar.test
    1.73 +S: NOTICE AUTH :*** Looking up your hostname...
    1.74 +S: NOTICE AUTH :*** Checking Ident
    1.75 +S: NOTICE AUTH :*** No Ident response
    1.76 +S: NOTICE AUTH :*** Found your hostname
    1.77 +S: :jaguar.test CAP jilles ACK :sasl 
    1.78 +C: AUTHENTICATE PLAIN
    1.79 +S: AUTHENTICATE +
    1.80 +C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
    1.81 +S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
    1.82 +S: :jaguar.test 903 jilles :SASL authentication successful
    1.83 +C: CAP END
    1.84 +S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
    1.85 +<usual welcome messages>
    1.86 +
    1.87 +Note that the CAP command sent by a server includes the user's nick or *,
    1.88 +differently from what [1] specifies.
    1.89 +
    1.90 +Alternatively the client could request the list of capabilities and enable
    1.91 +an additional capability.
    1.92 +
    1.93 +C: CAP LS
    1.94 +C: NICK jilles
    1.95 +C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
    1.96 +S: NOTICE AUTH :*** Processing connection to jaguar.test
    1.97 +S: NOTICE AUTH :*** Looking up your hostname...
    1.98 +S: NOTICE AUTH :*** Checking Ident
    1.99 +S: NOTICE AUTH :*** No Ident response
   1.100 +S: NOTICE AUTH :*** Found your hostname
   1.101 +S: :jaguar.test CAP * LS :multi-prefix sasl
   1.102 +C: CAP REQ :multi-prefix sasl
   1.103 +S: :jaguar.test CAP jilles ACK :multi-prefix sasl 
   1.104 +C: AUTHENTICATE PLAIN
   1.105 +S: AUTHENTICATE +
   1.106 +C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
   1.107 +S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
   1.108 +S: :jaguar.test 903 jilles :SASL authentication successful
   1.109 +C: CAP END
   1.110 +S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
   1.111 +<usual welcome messages>
   1.112 +
   1.113 +[1] K. Mitchell, P. Lorier (Undernet IRC Network), L. Hardy (ircd-ratbox), P.
   1.114 +Kucharski (IRCnet), IRC Client Capabilities Extension. March 2005.
   1.115 +This internet-draft has expired; it can still be found on
   1.116 +http://www.leeh.co.uk/draft-mitchell-irc-capabilities-02.html
   1.117 +
   1.118 +See also http://sasl.charybdis.be/ and
   1.119 +http://wiki.atheme.net/index.php/PR:SASL_Authentication (these links are
   1.120 +currently dead but may be resurrected in the future).
   1.121 +
   1.122 +$Id: sasl.txt 3169 2007-01-28 22:13:18Z jilles $