5.2 Authenticating via SASL

Regardless of the mechanism or the network, you’ll likely have to be registered before first use. Please refer to the network’s own instructions for details. If you’re new to IRC and using a bouncer, know that you probably won’t be needing SASL for the client-to-bouncer connection. To get started, just add sasl to erc-modules like any other module. But before that, please explore all custom options pertaining to your chosen mechanism.

User Option: erc-sasl-mechanism

The name of an SASL subprotocol type as a lowercase symbol. The value can be one of the following:

plain and scram (“password-based”)

Here, “password” refers to your account password, which is usually your ‘NickServ’ password. To make this work, customize erc-sasl-user and erc-sasl-password or specify the :user and :password keyword arguments when invoking erc-tls. Note that :user cannot be given interactively.

external (via Client TLS Certificate)

This works in conjunction with the :client-certificate keyword offered by erc-tls. Just ensure you’ve registered your fingerprint with the network beforehand. The fingerprint is usually a SHA1 or SHA256 digest in either "normalized" or "openssl" forms. The first is lowercase without delims (‘deadbeef’) and the second uppercase with colon seps (‘DE:AD:BE:EF’). These days, there’s usually a ‘CERT ADD’ command offered by NickServ that can register you automatically if you issue it while connected with a client cert. See client-certificate.

Additional considerations:

  1. Most IRCds will allow you to authenticate with a client cert but without the hassle of SASL (meaning you may not need this module).
  2. Technically, EXTERNAL merely indicates that an out-of-band mode of authentication is in effect (being deferred to), so depending on the specific application or service, there’s a remote chance your server has something else in mind.

This mechanism is quite complicated and currently requires the external ‘openssl’ executable, so please use something else if at all possible. Ignoring that, specify your key file (e.g., ‘~/pki/mykey.pem’) as the value of erc-sasl-password, and then configure your network settings. On servers running Atheme services, you can add your public key with ‘NickServ’ like so:

ERC> /msg NickServ set property \
     pubkey AgGZmlYTUjJlea/BVz7yrjJ6gysiAPaQxzeUzTH4hd5j

(You may be able to omit the ‘property’ subcommand.)

User Option: erc-sasl-user

This should be your network account username, typically the same one registered with nickname services. Specify this when your NickServ login differs from the :user you’re connecting with. See username parameter.

User Option: erc-sasl-password

As noted elsewhere, the entry-point :password param was originally intended for traditional “server passwords,” but these aren’t really used any more (see password parameter). As such, this option defaults to borrowing that parameter for its own uses, thus allowing you to call erc-tls with :password set to your NickServ password.

You can also set this to a nonemtpy string, and ERC will send that when needed, no questions asked. Or, if you’d rather use auth-source, set erc-sasl-auth-source-function to a function, and ERC will perform an auth-source query instead. In all cases, ERC will prompt you for input as a last resort.

Lastly, if your mechanism is ecdsa-nist256p-challenge, this option should instead hold the file name of your key.

User Option: erc-sasl-auth-source-function

This is nearly identical to the other ERC ‘auth-source’ function options (see auth-source functions) except that the default value here is nil, meaning you have to set it to something like erc-auth-source-search for queries to be performed. For convenience, this module provides the following as a possible value:

Function: erc-sasl-auth-source-password-as-host &rest plist

Setting erc-sasl-auth-source-function to this function tells ERC to use erc-sasl-password for the :host field when querying auth-source, even if its value is the default :password, in which case ERC knows to “resolve” it to erc-session-password and use that as long as it’s non-nil. Otherwise, ERC just defers to erc-auth-source-search to determine the :host, along with everything else.

As long as this option specifies a function, ERC will pass it the “resolved” value of erc-sasl-user for the auth-source :user param.

User Option: erc-sasl-authzid

In the rarest of circumstances, a network may want you to specify a specific role or assume an alternate identity. In most cases, this happens because the server is buggy or misconfigured. If you suspect such a thing, please contact your network operator. Otherwise, just leave this set to nil.



First and foremost, please know that ERC’s SASL offering is currently limited by a lack of support for proper IRCv3 capability negotiation. In most cases, this shouldn’t affect your ability to authenticate.

If you’re struggling, remember that your SASL password is almost always your NickServ password. When in doubt, try restoring all SASL options to their defaults and calling erc-tls with :user set to your NickServ account name and :password to your NickServ password. If you’re still having trouble, please contact us (see Getting Help and Reporting Bugs).

As you try out different settings, keep in mind that it’s best to create a fresh session for every change, for example, by calling erc-tls from scratch. More experienced users may be able to get away with cycling erc-sasl-mode and issuing a ‘/reconnect’, but that’s generally not recommended. Whatever the case, you’ll probably want to temporarily disable erc-server-auto-reconnect while experimenting.