]>
Commit | Line | Data |
---|---|---|
1 | SASL authentication | |
2 | ------------------- | |
3 | ||
4 | Note: The primary location for this document is now the IRCv3 sasl-3.1 | |
5 | specification, at address: | |
6 | ||
7 | http://ircv3.atheme.org/extensions/sasl-3.1 | |
8 | ||
9 | This document describes the client protocol for SASL authentication, as | |
10 | implemented in Charybdis and Atheme. The SASL protocol in general is documented | |
11 | in RFC 4422 [1], along with the 'EXTERNAL' mechanism. The most commonly used | |
12 | 'PLAIN' mechanism is documented in RFC 4616 [2]. | |
13 | ||
14 | SASL authentication relies on the CAP client capability framework [3]. | |
15 | Support for SASL authentication is indicated with the "sasl" capability. | |
16 | The client MUST enable the sasl capability before using the AUTHENTICATE | |
17 | command defined by this specification. | |
18 | ||
19 | The AUTHENTICATE command | |
20 | ||
21 | The AUTHENTICATE command MUST be used before registration is complete and | |
22 | with the sasl capability enabled. To enforce the former, it is RECOMMENDED | |
23 | to only send CAP END when the SASL exchange is completed or needs to be | |
24 | aborted. Clients SHOULD be prepared for timeouts at all times during the SASL | |
25 | authentication. | |
26 | ||
27 | There are two forms of the AUTHENTICATE command: initial client message and | |
28 | later messages. | |
29 | ||
30 | The initial client message specifies the SASL mechanism to be used. (When this | |
31 | is received, the IRCD will attempt to establish an association with a SASL | |
32 | agent.) If this fails, a 904 numeric will be sent and the session state remains | |
33 | unchanged; the client MAY try another mechanism. Otherwise, the server sends | |
34 | a set of regular AUTHENTICATE messages with the initial server response. | |
35 | ||
36 | initial-authenticate = "AUTHENTICATE" SP mechanism CRLF | |
37 | ||
38 | A set of regular AUTHENTICATE messages transmits a response from client to | |
39 | server or vice versa. The server MAY intersperse other IRC protocol messages | |
40 | between the AUTHENTICATE messages of a set. The "+" form is used for an empty | |
41 | response. The server MAY place a limit on the total length of a response. | |
42 | ||
43 | regular-authenticate-set = *("AUTHENTICATE" SP 400BASE64 CRLF) | |
44 | "AUTHENTICATE" SP (1*399BASE64 / "+") CRLF | |
45 | ||
46 | The client can abort an authentication by sending an asterisk as the data. | |
47 | The server will send a 904 numeric. | |
48 | ||
49 | authenticate-abort = "AUTHENTICATE" SP "*" CRLF | |
50 | ||
51 | If authentication fails, a 904 or 905 numeric will be sent and the | |
52 | client MAY retry from the AUTHENTICATE <mechanism> command. | |
53 | If authentication is successful, a 900 and 903 numeric will be sent. | |
54 | ||
55 | If the client attempts to issue the AUTHENTICATE command after already | |
56 | authenticating successfully, the server MUST reject it with a 907 numeric. | |
57 | ||
58 | If the client completes registration (with CAP END, NICK, USER and any other | |
59 | necessary messages) while the SASL authentication is still in progress, the | |
60 | server SHOULD abort it and send a 906 numeric, then register the client | |
61 | without authentication. | |
62 | ||
63 | This document does not specify use of the AUTHENTICATE command in | |
64 | registered (person) state. | |
65 | ||
66 | Example protocol exchange | |
67 | ||
68 | C: indicates lines sent by the client, S: indicates lines sent by the server. | |
69 | ||
70 | The client is using the PLAIN SASL mechanism with authentication identity | |
71 | jilles, authorization identity jilles and password sesame. | |
72 | ||
73 | C: CAP REQ :sasl | |
74 | C: NICK jilles | |
75 | C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker | |
76 | S: NOTICE AUTH :*** Processing connection to jaguar.test | |
77 | S: NOTICE AUTH :*** Looking up your hostname... | |
78 | S: NOTICE AUTH :*** Checking Ident | |
79 | S: NOTICE AUTH :*** No Ident response | |
80 | S: NOTICE AUTH :*** Found your hostname | |
81 | S: :jaguar.test CAP jilles ACK :sasl | |
82 | C: AUTHENTICATE PLAIN | |
83 | S: AUTHENTICATE + | |
84 | C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU= | |
85 | S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles. | |
86 | S: :jaguar.test 903 jilles :SASL authentication successful | |
87 | C: CAP END | |
88 | S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles | |
89 | <usual welcome messages> | |
90 | ||
91 | Note that the CAP command sent by a server includes the user's nick or *, | |
92 | differently from what [1] specifies. | |
93 | ||
94 | Alternatively the client could request the list of capabilities and enable | |
95 | an additional capability. | |
96 | ||
97 | C: CAP LS | |
98 | C: NICK jilles | |
99 | C: USER jilles cheetah.stack.nl 1 :Jilles Tjoelker | |
100 | S: NOTICE AUTH :*** Processing connection to jaguar.test | |
101 | S: NOTICE AUTH :*** Looking up your hostname... | |
102 | S: NOTICE AUTH :*** Checking Ident | |
103 | S: NOTICE AUTH :*** No Ident response | |
104 | S: NOTICE AUTH :*** Found your hostname | |
105 | S: :jaguar.test CAP * LS :multi-prefix sasl | |
106 | C: CAP REQ :multi-prefix sasl | |
107 | S: :jaguar.test CAP jilles ACK :multi-prefix sasl | |
108 | C: AUTHENTICATE PLAIN | |
109 | S: AUTHENTICATE + | |
110 | C: AUTHENTICATE amlsbGVzAGppbGxlcwBzZXNhbWU= | |
111 | S: :jaguar.test 900 jilles jilles!jilles@localhost.stack.nl jilles :You are now logged in as jilles. | |
112 | S: :jaguar.test 903 jilles :SASL authentication successful | |
113 | C: CAP END | |
114 | S: :jaguar.test 001 jilles :Welcome to the jillestest Internet Relay Chat Network jilles | |
115 | <usual welcome messages> | |
116 | ||
117 | [1] A. Melnikov (Isode Limited), K. Zeilenga (OpenLDAP Foundation), Simple | |
118 | Authentication and Security Layer (SASL). June 2006. | |
119 | <https://tools.ietf.org/html/rfc4422> | |
120 | ||
121 | [2] K. Zeilenga (OpenLDAP Foundation), The PLAIN Simple Authentication and | |
122 | Security Layer (SASL) Mechanism. August 2006. | |
123 | <https://tools.ietf.org/html/rfc4616> | |
124 | ||
125 | [3] K. Mitchell, P. Lorier (Undernet IRC Network), L. Hardy (ircd-ratbox), P. | |
126 | Kucharski (IRCnet), IRC Client Capabilities Extension. March 2005. | |
127 | This internet-draft has expired; it can still be found on | |
128 | http://www.leeh.co.uk/draft-mitchell-irc-capabilities-02.html | |
129 | ||
130 | $Id: sasl.txt 3169 2007-01-28 22:13:18Z jilles $ |