Re: ERC doc fixes for Emacs 29
"J.P." <[email protected]>
| Newsgroups | gmane.emacs.erc.general |
|---|---|
| Message-ID | <[email protected]> |
If anyone's interested in looking this over, please do. It'd be nice if links to other Emacs manuals in the HTML and PDF versions became non-clickable or (better yet) full URL hyperlinks when built for ELPA. (Not sure how exactly to achieve that, though. Perhaps conditionals, like @iflatex, could help?) BTW, this seems to build okay on Texinfo 4.13 (bug#59815).
0000-v1-v2.diff
(text/x-patch, 19.7 KB)
From 55ba649353adab81201b1b09e44073d17cf6040c Mon Sep 17 00:00:00 2001 From: "F. Jason Park" <[email protected]> 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
0001-Add-dedicated-auth-source-section-in-ERC-manual.patch
(text/x-patch, 23.6 KB)
From 55ba649353adab81201b1b09e44073d17cf6040c Mon Sep 17 00:00:00 2001 From: "F. Jason Park" <[email protected]> Date: Wed, 30 Nov 2022 23:10:58 -0800 Subject: [PATCH 1/1] Add dedicated auth-source section in ERC manual * doc/misc/erc.texi: Move auth-source description from the Password subheading of the Advanced chapter's Connecting section to the new Integrations section as a new node, Auth-Source, and give it a bit more structure. Fix various misuses of xref vs. pxref. Convert URL subheading to subsection and add anchor. Prefer "backend" as a single word, based on usage in other manuals. Also replace loud "warning" in SASL troubleshooting section. * etc/ERC-NEWS: Re-link auth-source mention. * lisp/erc/erc-sasl.el (erc-sasl-auth-source-function): Update info node in doc string. * 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 | 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(-) diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 5ad739a77e..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,6 +697,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, @pxref{auth-source, +ERC's auth-source integration}. @end defun @subheading Server @@ -778,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 @@ -803,8 +815,26 @@ 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 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}. + +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 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} @@ -814,109 +844,9 @@ 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 +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 @@ -946,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 @@ -1002,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 @@ -1038,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: @@ -1163,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 @@ -1260,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 @@ -1282,6 +1221,160 @@ Integrations @noindent Users on Emacs 28 and below may need to use @code{browse-url} instead. +@node auth-source +@subsection auth-source +@cindex auth-source + +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 + +@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 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. +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 +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 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. + +@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: + +@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 + +@anchor{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, 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. + +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 d0d84d0a98..76439f1d06 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-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) 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