doc/features/sasl.txt

   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