5.4.2 auth-source

You can configure ERC to use the built-in auth-source library for looking up passwords. See auth-source in Emacs auth-source Library, for general info on setting up various backends, but keep in mind that some of these may not be compatible. Those currently supported are netrc, plstore, json, secrets, and pass. To get started with the default backend, netrc, put a line like the following in your ~/.authinfo.gpg (or any file named in the option auth-sources):

machine irc.example.net login mynick password sEcReT

Server Passwords

When retrieving passwords to accompany the IRC ‘PASS’ command (see password parameter), ERC asks auth-source to match the server parameter of erc-tls against each entry’s ‘host’ field (machine irc.example.net in the above example). Unfortunately, specifying a network, like ‘Libera.Chat’, or a specific network server, like ‘platinum.libera.chat’, won’t normally work for looking up a server password because that information isn’t available during opening introductions. (Actually, ERC can find entries with arbitrary ‘host’ values for any context, including server passwords, but that requires customizing the more advanced options below.)

If ERC can’t find a suitable server password, it will just skip the IRC ‘PASS’ command altogether, something users may want when using CertFP or engaging NickServ via ERC’s services module. If that appeals to you, consider customizing the option erc-auth-source-server-function to nil to skip server-password lookup for all servers. Note that some networks and IRCds may accept account-services authentication via server password. Also, some ERC modules may commandeer the erc-tls password parameter for their own ends, which likely don’t involve a server password.

The ‘services’ module

You can use auth-source to authenticate to account services the traditional way through a bot called ‘NickServ’. To do so, add services to erc-modules and set the option erc-use-auth-source-for-nickserv-password to t. After that, expect the ‘user’ parameter in relevant auth-source queries to be your current nickname.

Most of the time, a query’s precise contextual details (such as whether a nick was granted or forcibly assigned) shouldn’t affect how you define entries in your backend. However, if something isn’t quite working, you may want to investigate the interplay between the option erc-nickserv-identify-mode and account services. In particular, if you find yourself facing nicks suffixed with an erc-nick-uniquifier (the infamous ‘`’), check that the network’s entry in erc-nickserv-alist is up to date, and do let us know if something’s off (see Getting Help and Reporting Bugs). Of course, if you’ve had your fill of fiddling with this module, consider switching to SASL for what’s likely a more consistent auth-source experience. (See Authenticating via SASL.)

Default query behavior

When preparing entries for your backend, it may help to get a feel for how ERC and its modules conduct searches, especially when exploring a new context, such as channel keys. (Hint: in such situations, try temporarily setting the variable auth-source-debug to t and checking *Messages* periodically for insights into how auth-source is operating.) Overall, though, ERC tries to be consistent in performing queries across various authentication contexts. Here’s what to expect with respect to the ‘host’ field, which, by default, most heavily influences the fate of a query:

  1. entries featuring custom identifiers and networks are matched first (see Network Identifier)
  2. followed by network-specific servers
  3. and, finally, dialed endpoints (typically the server argument passed to erc-tls)

The following netrc-style entries appear in order of precedence:

machine Libera/cellphone login MyNick password sEcReT
machine Libera.Chat login MyNick password sEcReT
machine zirconium.libera.chat login MyNick password sEcReT
machine irc.libera.chat login MyNick password sEcReT

Remember that field labels vary per backend, so ‘machine’ (in netrc’s case) maps to auth-source’s generalized notion of a host, hence the ‘:host’ keyword parameter to auth-source-search. Also, be sure to mind the syntax of your chosen backend medium. For example, always quote channel names in a netrc file.

Lastly, if this all seems overly nuanced or just plain doesn’t appeal to you, please see options erc-auth-source-services-function and friends, described just below.

Custom query functions

These let you query auth-source your way. Most users can simply ignore the passed-in arguments and get by with something like the following:

(defun my-fancy-auth-source-func (&rest _)
  (let* ((host (read-string "host: " nil nil "default"))
         (pass (auth-source-pick-first-password :host host)))
    (if (and pass (string-search "libera" host))
        (concat "MyNick:" pass)
User Option: erc-auth-source-server-function
User Option: erc-auth-source-services-function
User Option: erc-auth-source-join-function

ERC calls these functions with keyword arguments recognized by auth-source-search, namely, those deemed most relevant to the current context, if any. For example, when identifying to services, :user contains your current nickname. Generalized parameter names, like :user and :host, are always preferred over backend specific ones, like :login or :machine. In return, ERC expects a string if the search succeeds or nil if it fails.

The default value for all three options is the function erc-auth-source-search. It tries to merge relevant contextual parameters with those provided or discovered from the logical connection or the underlying transport.

For using auth-source along with SASL, see SASL auth-source function.

Channel keys

ERC also consults auth-source to find “keys” that may be required by certain channels you join. When modifying a traditional auth-source entry for this purpose, put the channel name in the ‘user’ field (for example, ‘login "#fsf"’, in netrc’s case). The actual key goes in the ‘password’ (or ‘secret’) field.