Copyright © 2014 Attila Molnar <firstname.lastname@example.org>
Copyright © 2015 William Pitcock <email@example.com>
Unlimited redistribution and modification of this document is allowed provided that the above copyright notice and this permission notice remains intact.
Updates: SASL v3.1
This document describes how SASL authentication
makes use of the
capability negotiation protocol updates introduced by CAP Version
and adds support for reauthentication if authentication is lost via the cap-notify
saslcapability when authentication is unavailable 🔗
Servers MUST NOT advertise the
sasl capability if the authentication layer is
sasl capability request if the authentication layer is
If a client requires pre-authentication and is unable to obtain the
then the client MUST disconnect and MAY retry the connection.
Servers SHOULD advertise the available SASL authentication mechanisms in the
value of the
sasl client capability in
The value, if present, MUST be a comma (
,) separated list of SASL
Clients MUST handle the case when there is no value for the
CAP LS even though they are attempting to use a version of the capability
negotiation protocol that allows values (i.e. 3.2).
Clients MUST handle the case when the value contains one or more mechanisms they do not understand.
sasl capability is integrated with the new
cap-notify framework, such that
cap-notify is an active capability, the client will be notified about status
changes concerning the availability of
Servers MUST advertise availability of the
sasl capability to any clients which have
Servers SHOULD allow a client, authenticated or otherwise, to reauthenticate by
sending a new
AUTHENTICATE message at any time. If reauthentication is not
available, an error appropriate to the circumstances MUST be sent (for instance,
ERR_SASLALREADY is appropriate if changing accounts is not supported).
Servers MAY disconnect ANY client at any time as a result of failed authentication, including both unregistered and registered clients, but MUST provide the reason for the authentication failure prior to disconnection.
Clients SHOULD pick a mechanism present in the
CAP LS reply they get from
the server and attempt to use that mechanism for authentication after they
Clients MUST handle the case when a mechanism they picked from the list turns out to be not available.
Example where the server only supports the EXTERNAL mechanism:
Client: CAP LS 302 Server: CAP * LS :sasl=EXTERNAL
Example where the server supports multiple authentication mechanisms and the client picks its favorite and attempts to use it:
Client: CAP LS 302 Client: NICK modernclient Client: USER modernclient 0 0 :Modern Client Server: CAP * LS :sasl=EXTERNAL,FOO,DH-AES,BAR,DH-BLOWFISH,FOOBAR,PLAIN batch cap-notify Client: CAP REQ :sasl Server: CAP modernclient ACK :sasl Client: AUTHENTICATE PLAIN Server: AUTHENTICATE + Client: AUTHENTICATE ...
Example where the server later adds support for authentication, such as regaining access to an authentication server after a netsplit:
Server: CAP modernclient NEW :sasl=PLAIN Client: CAP REQ :sasl Server: CAP modernclient ACK :sasl Client: AUTHENTICATE PLAIN Server: AUTHENTICATE + Client: AUTHENTICATE ...
Example where the server disconnects a client for excessive reauthentications:
Client: CAP REQ :sasl Server: CAP modernclient ACK :sasl Client: AUTHENTICATE PLAIN Server: AUTHENTICATE + Client: AUTHENTICATE ... Server: :irc.server.tld 904 modernclient :SASL authentication failed Client: AUTHENTICATE PLAIN Server: AUTHENTICATE + Client: AUTHENTICATE ... Server: :irc.server.tld 904 modernclient :SASL authentication failed Client: AUTHENTICATE PLAIN Server: AUTHENTICATE + Client: AUTHENTICATE ... Server: :irc.server.tld 904 modernclient :SASL authentication failed Server: ERROR :Too many SASL authentication failures
A previous version of this specification had reauthentication listed as a MUST requirement. This was weakened to SHOULD, to allow servers that cannot implement reauthentication for technical or policy reasons to be compliant.
See issue #192 for more information.
Software supporting SASL v3.2: Ergo, InspIRCd, Solanum, UnrealIRCd, AdiIRC, Ambassador, HexChat, Konversation, LimeChat, mIRC, Mozilla Thunderbird, Quassel, senpai, Srain, Textual, WeeChat, gamja, IRCCloud, Kiwi IRC, The Lounge, PIRC.pl web client, CoreIRC, Palaver, Quasseldroid, Goguma, KiwiBNC (as Server), KiwiBNC (as Client), pounce (as Server), pounce (as Client), soju (as Server), soju (as Client), BitBot, Eggdrop, Limnoria, Moon Moon, Communi, girc, irc-framework, ircrobots, Kitteh IRC Client Library, Rust irc, Warren, zIRC, BitlBee, PyLink (clientbot mode)