]>
Commit | Line | Data |
---|---|---|
0c8f86ec JT |
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). | |
118 | ||
119 | $Id: sasl.txt 3169 2007-01-28 22:13:18Z jilles $ |