>From 55ba649353adab81201b1b09e44073d17cf6040c Mon Sep 17 00:00:00 2001 From: "F. Jason Park" Date: Sun, 4 Dec 2022 19:16:36 -0800 Subject: [PATCH 0/1] *** NOT A PATCH *** *** BLURB HERE *** F. Jason Park (1): Add dedicated auth-source section in ERC manual doc/misc/erc.texi | 343 +++++++++++++++++++++++++-------------- etc/ERC-NEWS | 4 +- lisp/erc/erc-sasl.el | 2 +- lisp/erc/erc-services.el | 2 +- lisp/erc/erc.el | 6 +- 5 files changed, 225 insertions(+), 132 deletions(-) Interdiff: diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index f4b996f8dd..51fd47cb6d 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -570,10 +570,20 @@ Advanced Usage @menu * Connecting:: Ways of connecting to an IRC server. -* SASL:: Authenticating via SASL +* SASL:: Authenticating via SASL. * Sample Configuration:: An example configuration file. * Integrations:: Integrations available for ERC. * Options:: Options that are available for ERC. + +@detailmenu +--- Select Detailed Node Listing --- + +Integrations + +* URL:: Opening IRC URLs in ERC. +* auth-source:: Retrieving auth-source entries with ERC. + +@end detailmenu @end menu @node Connecting @@ -643,7 +653,7 @@ Connecting parameters, and some, like @code{client-certificate}, will just be @code{nil}. -@anchor{ERC client-certificate} +@anchor{client-certificate} To use a certificate with @code{erc-tls}, specify the optional @var{client-certificate} keyword argument, whose value should be as described in the documentation of @code{open-network-stream}: if @@ -687,7 +697,7 @@ 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, +For other uses of auth-source throughout ERC, @pxref{auth-source, ERC's auth-source integration}. @end defun @@ -780,9 +790,9 @@ Connecting You can manually set another nickname with the /NICK command. @end defopt -@anchor{ERC username} +@anchor{username parameter} @subheading User -@cindex user +@cindex username parameter @defun erc-compute-user &optional user Determine a suitable value to send as the first argument of the @@ -805,16 +815,16 @@ Connecting a string abiding by the rules of the network. @end defopt +@anchor{password parameter} +@anchor{server password} +@cindex password, server @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 +password} to be sent along with the IRC @samp{PASS} command. However, +such passwords aren't widely used. Instead, networks typically expect +them, when present, to convey other authentication information. In +the case of account-services (a.k.a., ``NickServ'') credentials, 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}. @@ -822,9 +832,9 @@ Connecting 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}. +addition to performing network-account authentication, these obviate +the need for this parameter completely, although both can optionally +borrow it for their own purposes. @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} @@ -834,7 +844,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. +auth-source facility to retrieve a server password, although hitting +@kbd{RET} at the prompt may achieve the same effect. @xref{auth-source, ERC's auth-source integration}, for more. @subheading Full name @@ -865,8 +876,8 @@ Connecting @end defopt -@subheading ID @anchor{Network Identifier} +@subheading ID ERC uses an abstract designation, called @dfn{network context identifier}, for referring to a connection internally. While normally @@ -921,7 +932,7 @@ SASL uppercase with colon seps (@samp{DE:AD:BE:EF}). These days, there's usually a @samp{CERT ADD} command offered by NickServ that can register you automatically if you issue it while connected with a -client cert. (@pxref{ERC client-certificate}). +client cert. @xref{client-certificate}. Additional considerations: @enumerate @@ -957,30 +968,32 @@ SASL This should be your network account username, typically the same one registered with nickname services. Specify this when your NickServ login differs from the @code{:user} you're connecting with. -(@pxref{ERC username}) +@xref{username parameter}. @end defopt @defopt erc-sasl-password -As noted elsewhere, the @code{:password} parameter for @code{erc-tls} -was originally intended for traditional ``server passwords,'' but these -aren't really used any more. As such, this option defaults to -borrowing that parameter for its own uses, thus allowing you to call -@code{erc-tls} with @code{:password} set to your NickServ password. +As noted elsewhere, the entry-point @code{:password} param was +originally intended for traditional ``server passwords,'' but these +aren't really used any more (@pxref{password parameter}). As such, +this option defaults to borrowing that parameter for its own uses, +thus allowing you to call @code{erc-tls} with @code{: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 @code{erc-sasl-auth-source-function} to a function, and ERC will -perform an auth-source query instead. As last resort in all cases, -ERC will prompt you for input. +perform an auth-source query instead. In all cases, ERC will prompt +you for input as a last resort. Lastly, if your mechanism is @code{ecdsa-nist256p-challenge}, this option should instead hold the file name of your key. @end defopt +@anchor{SASL auth-source function} @defopt erc-sasl-auth-source-function This is nearly identical to the other ERC @samp{auth-source} function -options (@pxref{ERC auth-source functions}) except that the default -value here is @code{nil}, meaning you have to set it to something like +options (@pxref{auth-source functions}) except that the default value +here is @code{nil}, meaning you have to set it to something like @code{erc-auth-source-search} for queries to be performed. For convenience, this module provides the following as a possible value: @@ -1082,9 +1095,9 @@ SASL @subheading Troubleshooting -@strong{Warning:} 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. +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 @@ -1179,12 +1192,19 @@ Integrations @section Integrations @cindex integrations -@subheading URL +@menu +* auth-source:: Retrieving auth-source entries with ERC. +@end menu + +@anchor{URL} +@subsection URL +@cindex URL + For anything to work, you'll want to set @code{url-irc-function} to @code{url-irc-erc}. As a rule of thumb, libraries relying directly on @code{url-retrieve} should be fine out the box from Emacs 29.1 onward. On older versions of Emacs, you may need to @code{(require 'erc)} -beforehand. @pxref{Retrieving URLs,,, url, URL}. +beforehand. @xref{Retrieving URLs,,, url, URL}. For other apps and libraries, such as those relying on the higher-level @code{browse-url}, you'll oftentimes be asked to specify @@ -1201,52 +1221,93 @@ Integrations @noindent Users on Emacs 28 and below may need to use @code{browse-url} instead. -@subheading Auth-source -@anchor{auth-source} +@node auth-source +@subsection 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}: +You can configure ERC to use the built-in auth-source library for +looking up passwords. @xref{Top,,auth-source, auth, Emacs auth-source +Library}, for general info on setting up various backends, but keep in +mind that some of these may not be compatible; netrc, plstore, json, +secrets, and pass are currently supported. To get started with the +default backend, netrc, put a line like the following in your +@file{~/.authinfo.gpg} (or any file named in 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 +@subsubheading Server Passwords +When retrieving passwords to accompany the IRC @samp{PASS} command +(@pxref{password parameter}), ERC asks auth-source to match the +@var{server} parameter of @code{erc-tls} against each entry's +@samp{host} field (@w{@code{machine irc.example.net}} in the above +example). 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 +@samp{platinum.libera.chat}, won't normally work for looking up a +server password because that 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 appeals to you, consider customizing 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: +IRCds may accept account-services authentication via server password. +Also, some ERC modules may commandeer the @code{erc-tls} +@var{password} parameter for their own ends, which likely don't +involve a server password. + +@subsubheading The @samp{services} module +You can use auth-source to authenticate to account services the +traditional way through a bot called @samp{NickServ}. To do so, add +@code{services} to @code{erc-modules} and set the option +@code{erc-use-auth-source-for-nickserv-password} to @code{t}. After +that, expect the @samp{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 +@code{erc-nickserv-identify-mode} and account services. In +particular, if you find yourself facing nicks suffixed with an +@code{erc-nick-uniquifier} (the infamous @samp{`}), check that the +network's entry in @code{erc-nickserv-alist} is up to date, and do let +us know if something's off (@pxref{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. (@xref{SASL}.) + +@subsubheading 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 @code{auth-source-debug} to @code{t} +and checking @samp{*Messages*} 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 @samp{host} field, which, by default, most heavily +influences the fate of a query: + +@enumerate +@item +entries featuring custom identifiers and networks are matched first +(@pxref{Network Identifier}) +@item +followed by network-specific servers +@item +and, finally, dialed endpoints (typically the @var{server} argument +passed to @code{erc-tls}) +@end enumerate + +@noindent +The following netrc-style entries appear in order of precedence: @example machine Libera/cellphone login MyNick password sEcReT @@ -1258,13 +1319,16 @@ Integrations @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. +hence the @samp{:host} keyword parameter to @code{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 @code{erc-auth-source-services-function} +and friends, described just below. -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 +@subsubheading 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: @@ -1277,14 +1341,7 @@ Integrations 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} +@anchor{auth-source functions} @defopt erc-auth-source-server-function @end defopt @defopt erc-auth-source-services-function @@ -1293,22 +1350,31 @@ Integrations 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. +current context, if any. For example, when identifying to services, +@code{:user} contains your current nickname. Generalized parameter +names, like @code{:user} and @code{:host}, are always preferred over +backend 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. +parameters with those provided or discovered from the logical +connection or the underlying transport. + +For using auth-source along with SASL, @pxref{SASL auth-source +function}. @end defopt +@subsubheading Channel keys +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. + + @node Options @section Options @cindex options diff --git a/etc/ERC-NEWS b/etc/ERC-NEWS index 1925cc1114..76439f1d06 100644 --- a/etc/ERC-NEWS +++ b/etc/ERC-NEWS @@ -45,7 +45,7 @@ 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 section titled "Auth-source" in +nonstandard server passwords. See the section titled "auth-source" in the Integrations chapter of ERC's manual. ** Rudimentary SASL support has arrived. diff --git a/lisp/erc/erc-sasl.el b/lisp/erc/erc-sasl.el index 5b2c93988a..280910111d 100644 --- a/lisp/erc/erc-sasl.el +++ b/lisp/erc/erc-sasl.el @@ -102,7 +102,7 @@ erc-sasl-auth-source-function `erc-sasl-password', to their values from entry-point invocation. In return, ERC expects a string to send as the SASL password, or nil, in which case, ERC will prompt the for input. See info -node `(erc) Connecting' for details on ERC's auth-source +node `(erc) auth-source' for details on ERC's auth-source integration." :type '(choice (function-item erc-sasl-auth-source-password-as-host) (function-item erc-auth-source-search) -- 2.38.1