[ViewVC] Annotation of: cvs/ermyth/doc/SASL

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

This document describes the client protocol for SASL authentication, as
implemented in charybdis and atheme.

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