>From 6e1ab9b95aab7d7c34552df994dc5bc2a5cec79e Mon Sep 17 00:00:00 2001 From: "F. Jason Park" Date: Wed, 30 Nov 2022 23:10:58 -0800 Subject: [PATCH] Add dedicated auth-source section in ERC manual * doc/misc/erc.texi: Move auth-source description from the Password subsection of the Connecting chapter, to the new Integrations chapter under the subheading Auth-source. * etc/ERC-NEWS: Re-link auth-source mention. * lisp/erc/erc-services.el (erc-auth-source-services-function): Re-link auth-source info node in doc string. * lisp/erc/erc.el (erc-password, erc-auth-source-server-function, erc-auth-source-join-function): Re-link auth-source info node in doc strings. --- doc/misc/erc.texi | 233 ++++++++++++++++++++++----------------- etc/ERC-NEWS | 4 +- lisp/erc/erc-services.el | 2 +- lisp/erc/erc.el | 6 +- 4 files changed, 136 insertions(+), 109 deletions(-) diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index a8d1dd7823..808a6c1832 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -687,6 +687,8 @@ Connecting @xref{Help for users,,,auth, Emacs auth-source Library}, for more on the @file{.authinfo}/@file{.netrc} backend of @code{auth-source}. +For other uses of auth-source throughout ERC, @xref{auth-source, +ERC's auth-source integration}. @end defun @subheading Server @@ -806,6 +808,24 @@ Connecting @subheading Password @cindex password +This parameter was traditionally meant to specify a @dfn{server +password} to be sent as an ``argument'' to the IRC @samp{PASS} +command. However, such passwords aren't really used these days, even +for private IRC servers. Instead, servers and networks typically +consider a server password optional and expect them, when present, to +convey other authentication information, such as account-services +(a.k.a., ``NickServ'') credentials. In the case of the latter, this +typically involves a special syntax, such as @samp{myuser:mypass}. +IRC bouncers often do something similar but include a pre-configured +network-ID component, for example, @samp{bncuser/mynet:bncpass}. + +In general, if you have @emph{not} been asked by your network or +bouncer to specify a repurposed server password, you should instead +consider setting up @samp{erc-services} or, preferably, SASL. In +addition to providing user options that supplant it entirely, both +offer a way of borrowing this parameter for their own respective mode +of authentication. @xref{SASL, SASL in ERC}. + @defopt erc-prompt-for-password If non-@code{nil} (the default), @kbd{M-x erc} and @kbd{M-x erc-tls} prompt for a server password. This only affects interactive @@ -814,109 +834,8 @@ Connecting @noindent If you prefer, you can set this option to @code{nil} and use the -@code{auth-source} mechanism to store your password. For instance, if -the option @code{auth-sources} contains @file{~/.authinfo}, put -something like the following in that file: - -@example -machine irc.example.net login mynick password sEcReT -@end example - -@noindent -For server passwords, that is, passwords sent for the IRC @samp{PASS} -command, the @samp{host} field (@w{@code{machine irc.example.net}} in -the above example) -corresponds to the @var{server} parameter used by @code{erc} and -@code{erc-tls}. Unfortunately, specifying a network, like -@samp{Libera.Chat}, or a specific network server, like -@samp{platinum.libera.chat}, won't normally work for looking up a server -password because such information isn't available during opening -introductions. (Actually, ERC @emph{can} find entries with arbitrary -@samp{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 -@samp{PASS} command altogether, something users may want when using -CertFP or engaging NickServ via ERC's ``services'' module. If that is -what you'd like to do, you can also customize the option -@code{erc-auth-source-server-function} to @code{nil} to skip -server-password lookup for all servers. Note that some networks and -IRCds may accept account-services authentication via server password -using the nonstandard @samp{mynick:sEcReT} convention. - -As just mentioned, you can also use @code{auth-source} to authenticate -to account services the traditional way, through a bot called -@samp{NickServ}. To tell ERC to do that, set -@code{erc-use-auth-source-for-nickserv-password} to @code{t}. For -these and most other queries, entries featuring custom identifiers and -networks are matched first, followed by network-specific servers and -dialed endpoints (typically, the @var{server} argument passed to -@code{erc}). The following netrc-style entries appear in order of -precedence: - -@example -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 -@end example - -@noindent -Remember that field labels vary per backend, so @samp{machine} (in -netrc's case) maps to auth-source's generalized notion of a host, -hence the @samp{:host} keyword property. Also, be sure to mind the -syntax of your chosen backend medium. For example, always quote -channel names in a netrc file. - -If this all seems overly nuanced or just plain doesn't appeal to you, -see options @code{erc-auth-source-services-function} and friends, described -below. 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: - -@lisp -(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) - pass))) -@end lisp - -Lastly, ERC also consults @code{auth-source} to find ``keys'' that may -be required by certain channels you join. When modifying a -traditional @code{auth-source} entry for this purpose, put the channel -name in the @samp{user} field (for example, @samp{login "#fsf"}, in -netrc's case). The actual key goes in the @samp{password} (or -@samp{secret}) field. - -@noindent -For details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. - -@anchor{ERC auth-source functions} -@defopt erc-auth-source-server-function -@end defopt -@defopt erc-auth-source-services-function -@end defopt -@defopt erc-auth-source-join-function - -ERC calls these functions with keyword arguments recognized by -@code{auth-source-search}, namely, those deemed most relevant to the -current context, if any. For example, with NickServ queries, -@code{:user} is the ``desired'' nickname rather than the current one. -Generalized names, like @code{:user} and @code{:host}, are always used -over back-end specific ones, like @code{:login} or @code{:machine}. -ERC expects a string to use as the secret or @code{nil}, if the search -fails. - -@findex erc-auth-source-search -The default value for all three options is the function -@code{erc-auth-source-search}. It tries to merge relevant contextual -parameters with those provided or discovered from the logical connection -or the underlying transport. Some auth-source back ends may not be -compatible; netrc, plstore, json, secrets, and pass are currently -supported. -@end defopt +@code{auth-source} mechanism to store your password. +@xref{auth-source, ERC's auth-source integration}, for more. @subheading Full name @@ -1288,6 +1207,114 @@ Integrations @noindent Users on Emacs 28 and below may need to use @code{browse-url} instead. +@subheading Auth-source +@anchor{auth-source} +@cindex auth-source + +ERC can be configured to use the built-in auth-source library for +looking up passwords. @pxref{Top,,auth-source, auth, Emacs auth-source +Library}, for general info on setting up various back ends. To get +started with the default, netrc back end, put something like the +following in a file (such as @file{~/.authinfo}) known to the option +@code{auth-sources}: + +@example +machine irc.example.net login mynick password sEcReT +@end example + +@noindent +For server passwords, that is, passwords sent for the IRC @samp{PASS} +command, the @samp{host} field (@w{@code{machine irc.example.net}} in +the above example) +corresponds to the @var{server} parameter used by @code{erc} and +@code{erc-tls}. Unfortunately, specifying a network, like +@samp{Libera.Chat}, or a specific network server, like +@samp{platinum.libera.chat}, won't normally work for looking up a server +password because such information isn't available during opening +introductions. (Actually, ERC @emph{can} find entries with arbitrary +@samp{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 +@samp{PASS} command altogether, something users may want when using +CertFP or engaging NickServ via ERC's ``services'' module. If that is +what you'd like to do, you can also customize the option +@code{erc-auth-source-server-function} to @code{nil} to skip +server-password lookup for all servers. Note that some networks and +IRCds may accept account-services authentication via server password +using the nonstandard @samp{mynick:sEcReT} convention. + +As just mentioned, you can also use @code{auth-source} to authenticate +to account services the traditional way, through a bot called +@samp{NickServ}. To tell ERC to do that, set +@code{erc-use-auth-source-for-nickserv-password} to @code{t}. For +these and most other queries, entries featuring custom identifiers and +networks are matched first, followed by network-specific servers and +dialed endpoints (typically, the @var{server} argument passed to +@code{erc}). The following netrc-style entries appear in order of +precedence: + +@example +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 +@end example + +@noindent +Remember that field labels vary per backend, so @samp{machine} (in +netrc's case) maps to auth-source's generalized notion of a host, +hence the @samp{:host} keyword property. Also, be sure to mind the +syntax of your chosen backend medium. For example, always quote +channel names in a netrc file. + +If this all seems overly nuanced or just plain doesn't appeal to you, +see options @code{erc-auth-source-services-function} and friends, described +below. 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: + +@lisp +(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) + pass))) +@end lisp + +Lastly, ERC also consults @code{auth-source} to find ``keys'' that may +be required by certain channels you join. When modifying a +traditional @code{auth-source} entry for this purpose, put the channel +name in the @samp{user} field (for example, @samp{login "#fsf"}, in +netrc's case). The actual key goes in the @samp{password} (or +@samp{secret}) field. + +@anchor{ERC auth-source functions} +@defopt erc-auth-source-server-function +@end defopt +@defopt erc-auth-source-services-function +@end defopt +@defopt erc-auth-source-join-function + +ERC calls these functions with keyword arguments recognized by +@code{auth-source-search}, namely, those deemed most relevant to the +current context, if any. For example, with NickServ queries, +@code{:user} is the ``desired'' nickname rather than the current one. +Generalized names, like @code{:user} and @code{:host}, are always +preferred over back-end specific ones, like @code{:login} or +@code{:machine}. In return, ERC expects a string if the search +succeeds or @code{nil} if it fails. + +@findex erc-auth-source-search +The default value for all three options is the function +@code{erc-auth-source-search}. It tries to merge relevant contextual +parameters with those provided or discovered from the logical connection +or the underlying transport. Some auth-source back ends may not be +compatible; netrc, plstore, json, secrets, and pass are currently +supported. +@end defopt + @node Options @section Options @cindex options diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS index d0d84d0a98..1925cc1114 100644 --- a/etc/ERC-NEWS +++ b/etc/ERC-NEWS @@ -45,8 +45,8 @@ With the overhaul of the services module temporarily shelved and the transition to SASL-based authentication still underway, users may feel left in the lurch to endure yet another release cycle of backtick hell. For some, auth-source may provide a workaround in the form of -nonstandard server passwords. See the "Connection" node in the manual -under the subheading "Password". +nonstandard server passwords. See the section titled "Auth-source" in +the Integrations chapter of ERC's manual. ** Rudimentary SASL support has arrived. A new module, 'erc-sasl', now ships with ERC 5.5. See the SASL diff --git a/lisp/erc/erc-services.el b/lisp/erc/erc-services.el index 48953288d1..c2d91ca9d6 100644 --- a/lisp/erc/erc-services.el +++ b/lisp/erc/erc-services.el @@ -180,7 +180,7 @@ erc-auth-source-services-function `auth-source-search' and relevant to authenticating to nickname services. In return, ERC expects a string to send as the password, or nil, to fall through to the next method, such as -prompting. See info node `(erc) Connecting' for details." +prompting. See info node `(erc) auth-source' for details." :package-version '(ERC . "5.4.1") ; FIXME update when publishing to ELPA :type '(choice (const erc-auth-source-search) (const nil) diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el index 268d83dc44..32103aa029 100644 --- a/lisp/erc/erc.el +++ b/lisp/erc/erc.el @@ -219,7 +219,7 @@ erc-password This variable only exists for legacy reasons. It's not customizable and is limited to a single server password. Users looking for similar functionality should consider auth-source instead. See info -node `(auth) Top' and info node `(erc) Connecting'.") +node `(auth) Top' and info node `(erc) auth-source'.") (make-obsolete-variable 'erc-password "use auth-source instead" "29.1") @@ -3208,7 +3208,7 @@ erc-auth-source-server-function password, or nil, to skip the \"PASS\" command completely. An explicit `:password' argument to entry-point commands `erc' and `erc-tls' also inhibits lookup, as does setting this option to -nil. See info node `(erc) Connecting' for details." +nil. See info node `(erc) auth-source' for details." :package-version '(ERC . "5.4.1") ; FIXME update when publishing to ELPA :group 'erc :type '(choice (const erc-auth-source-search) @@ -3223,7 +3223,7 @@ erc-auth-source-join-function \"key\", or nil to just join the channel normally. Setting the option itself to nil tells ERC to always forgo consulting auth-source for channel keys. For more information, see info -node `(erc) Connecting'." +node `(erc) auth-source'." :package-version '(ERC . "5.4.1") ; FIXME update when publishing to ELPA :group 'erc :type '(choice (const erc-auth-source-search) -- 2.38.1