=head1 SASL authentication

This document describes the client protocol for B<SASL> authentication, as
implemented in charybdis and ermyth.

B<SASL> authentication relies on the C<CAP> client capability framework [1].
Support for B<SASL> authentication is indicated with the "sasl" capability.
The client MUST enable the sasl capability before using the C<AUTHENTICATE>
command defined by this specification.

=head2 The C<AUTHENTICATE> command

The C<AUTHENTICATE> command MUST be used before registration is complete and
with the sasl capability enabled. To enforce the former, it is RECOMMENDED
to only send C<CAP END> when the B<SASL> exchange is completed or needs to be
aborted. Clients SHOULD be prepared for timeouts at all times during the B<SASL>
authentication.

There are two forms of the C<AUTHENTICATE> command: initial client message and
later messages.

The initial client message specifies the B<SASL> mechanism to be used. (When this
is received, the IRCD will attempt to establish an association with a B<SASL>
agent.) If this fails, a 904 numeric will be sent and the session state remains
unchanged; the client MAY try another mechanism. Otherwise, the server sends
a set of regular C<AUTHENTICATE> messages with the initial server response.

   initial-authenticate = "C<AUTHENTICATE>" SP mechanism CRLF

A set of regular C<AUTHENTICATE> messages transmits a response from client to
server or vice versa. The server MAY intersperse other IRC protocol messages
between the C<AUTHENTICATE> messages of a set. The "+" form is used for an empty
response. The server MAY place a limit on the total length of a response.

   regular-authenticate-set = *("AUTHENTICATE" SP 400BASE64 CRLF)
      "AUTHENTICATE" SP (1*399BASE64 / "+") CRLF

The client can abort an authentication by sending an asterisk as the data.
The server will send a 904 numeric.

   authenticate-abort = "AUTHENTICATE" SP "*" CRLF

If authentication fails, a 904 or 905 numeric will be sent and the
client MAY retry from the C<AUTHENTICATE> C<mechanism> command.
If authentication is successful, a 900 and 903 numeric will be sent.

If the client attempts to issue the C<AUTHENTICATE> command after already
authenticating successfully, the server MUST reject it with a 907 numeric.

If the client completes registration (with C<CAP END>, C<NICK>, C<USER> and any other
necessary messages) while the B<SASL> authentication is still in progress, the
server SHOULD abort it and send a 906 numeric, then register the client
without authentication.

This document does not specify use of the C<AUTHENTICATE> command in
registered (person) state.

Example protocol exchange

   C: indicates lines sent by the client, S: indicates lines sent by the server.

The client is using the PLAIN B<SASL> mechanism with authentication identity
jilles, authorization identity jilles and password sesame.

   C: CAP REQ :sasl
   C: NICK jilles
   C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
   S: NOTICE AUTH :*** Processing connection to jaguar.test
   S: NOTICE AUTH :*** Looking up your hostname...
   S: NOTICE AUTH :*** Checking Ident
   S: NOTICE AUTH :*** No Ident response
   S: NOTICE AUTH :*** Found your hostname
   S: :jaguar.test CAP jilles ACK :sasl 
   C: AUTHENTICATE PLAIN
   S: AUTHENTICATE +
   C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
   S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
   S: :jaguar.test 903 jilles :SASL authentication successful
   C: CAP END
   S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
   <usual welcome messages>

Note that the C<CAP> command sent by a server includes the user's nick or *,
differently from what [1] specifies.

Alternatively the client could request the list of capabilities and enable
an additional capability.

   C: CAP LS
   C: NICK jilles
   C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker
   S: NOTICE AUTH :*** Processing connection to jaguar.test
   S: NOTICE AUTH :*** Looking up your hostname...
   S: NOTICE AUTH :*** Checking Ident
   S: NOTICE AUTH :*** No Ident response
   S: NOTICE AUTH :*** Found your hostname
   S: :jaguar.test CAP * LS :multi-prefix sasl
   C: CAP REQ :multi-prefix sasl
   S: :jaguar.test CAP jilles ACK :multi-prefix sasl 
   C: AUTHENTICATE PLAIN
   S: AUTHENTICATE +
   C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU=
   S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles.
   S: :jaguar.test 903 jilles :SASL authentication successful
   C: CAP END
   S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles
   <usual welcome messages>

[1] K. Mitchell, P. Lorier (Undernet IRC Network), L. Hardy (ircd-ratbox), P.
Kucharski (IRCnet), IRC Client Capabilities Extension. March 2005.
This internet-draft has expired; it can still be found on
http://www.leeh.co.uk/draft-mitchell-irc-capabilities-02.html

See also http://sasl.charybdis.be/ and
http://wiki.atheme.net/index.php/PR:SASL_Authentication (these links are
currently dead but may be resurrected in the future).