mirror of
https://github.com/matrix-construct/construct
synced 2024-11-18 16:00:57 +01:00
a5c46d31e4
Purge a lot of really old and obsolete documents, and merge some together where possible. Lots of efnet docs and the old ircd-ratbox manpage (lol) was purged. Reorganise everything nice and neatly as possible. Things describing features can be found in features/, and some more technical documents were moved to techinical/. Old credits file was consolidated into credits-past.txt, and a reference was added to it in the credits.
129 lines
5.3 KiB
Text
129 lines
5.3 KiB
Text
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
|
|
|