modules/m_challenge.c: log correct mechanism

[solanum.git] / doc / features / sasl.txt

SASL authentication
-------------------

Note: The primary location for this document is now the IRCv3 sasl-3.1
specification, at address:

    http://ircv3.atheme.org/extensions/sasl-3.1

This document describes the client protocol for SASL authentication, as
implemented in Charybdis and Atheme. The SASL protocol in general is documented
in RFC 4422 [1], along with the 'EXTERNAL' mechanism. The most commonly used
'PLAIN' mechanism is documented in RFC 4616 [2].

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

The AUTHENTICATE command

The 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 CAP END when the SASL exchange is completed or needs to be
aborted. Clients SHOULD be prepared for timeouts at all times during the SASL
authentication.

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

The initial client message specifies the SASL mechanism to be used. (When this
is received, the IRCD will attempt to establish an association with a 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 AUTHENTICATE messages with the initial server response.

initial-authenticate = "AUTHENTICATE" SP mechanism CRLF

A set of regular AUTHENTICATE messages transmits a response from client to
server or vice versa. The server MAY intersperse other IRC protocol messages
between the 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 AUTHENTICATE <mechanism> command.
If authentication is successful, a 900 and 903 numeric will be sent.

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

If the client completes registration (with CAP END, NICK, USER and any other
necessary messages) while the 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 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 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 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] A. Melnikov (Isode Limited), K. Zeilenga (OpenLDAP Foundation), Simple
Authentication and Security Layer (SASL). June 2006.
<https://tools.ietf.org/html/rfc4422>

[2] K. Zeilenga (OpenLDAP Foundation), The PLAIN Simple Authentication and
Security Layer (SASL) Mechanism. August 2006.
<https://tools.ietf.org/html/rfc4616>

[3] 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