Authenticating via SASL

If you’ve used SASL elsewhere, you can probably skip to the examples below. Otherwise, if you haven’t already registered with your network, please do so now, referring 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 this for the client-to-bouncer connection.

When you’re ready to get started, add sasl to erc-modules, like you would any other module. If unsure which mechanism to choose, stick with the default of ‘PLAIN’. Then try C-u M-x erc-tls RET, and give your account name for the ‘user’ parameter and your account password for the ‘server password’.

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 or 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.

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: ")
    (require 'erc-sasl)
    (or (let ((erc-modules (cons 'sasl erc-modules)))
          (pcase network
            ('libera
             (let ((erc-sasl-mechanism 'external))
               (erc-tls :server "irc.libera.chat"
                        :client-certificate t)))
            ('example
             (let ((erc-sasl-auth-source-function
                    #'erc-sasl-auth-source-password-as-host))
               (erc-tls :server "irc.example.net"
                        :user "alyssa"
                        :password "Example.Net")))))
        ;; Non-SASL
        (call-interactively #'erc-tls)))

  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 work around this and successfully authenticate to both networks. (Note that this example assumes you’ve removed sasl from erc-modules globally and have instead opted to add it locally when connecting to preconfigured 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.