---

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.

ecdsa-nist256p-challenge

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.

Examples

• Defaults

  (erc-tls :server "irc.libera.chat" :port 6697
           :nick "aph"
           :user "APHacker"
           :password "changeme")
  

  Here, after adding sasl to erc-modules via the Customize interface, you authenticate to Libera.Chat using the ‘PLAIN’ mechanism and your NickServ credentials, ‘APHacker’ and ‘changeme’.

• External

  (setopt erc-sasl-mechanism 'external)
  
  (erc-tls :server "irc.libera.chat" :port 6697 :nick "aph"
           :client-certificate
           '("/home/aph/my.key" "/home/aph/my.crt"))
  

  You decide to switch things up and try out the ‘EXTERNAL’ mechanism. You follow your network’s instructions for telling NickServ about your client-certificate’s fingerprint, and you authenticate successfully.

• Multiple networks

  # ~/.authinfo.gpg
  
  machine irc.libera.chat key /home/aph/my.key cert /home/aph/my.crt
  machine Example.Net login alyssa password sEcReT
  machine Example.Net login aph-bot password sesame
  

  ;; init.el
  
  (defun my-erc-up (network)
    (interactive "Snetwork: ")
  
    (pcase network
      ('libera
       (let ((erc-sasl-mechanism 'external))
         (erc-tls :server "irc.libera.chat" :port 6697
                  :client-certificate t)))
      ('example
       (let ((erc-sasl-auth-source-function
              #'erc-sasl-auth-source-password-as-host))
         (erc-tls :server "irc.example.net" :port 6697
                  :user "alyssa"
                  :password "Example.Net")))))
  

  You’ve started storing your credentials with auth-source and have decided to try SASL on another network as well. But there’s a catch: this network doesn’t support ‘EXTERNAL’. You use let-binding to get around this and successfully authenticate to both networks.

Troubleshooting

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.