From c80f7f6a8905c3c5c5404bcbb414a50eb7cc222a Mon Sep 17 00:00:00 2001 From: "F. Jason Park" Date: Wed, 23 Nov 2022 21:31:19 -0800 Subject: [PATCH 2/3] * doc/misc/erc.texi: Revise SASL and modules chapters. --- doc/misc/erc.texi | 82 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 4 deletions(-) diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index f86465fed7..5317a3e5aa 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -392,10 +392,14 @@ Modules There is a spiffy customize interface, which may be reached by typing @kbd{M-x customize-option @key{RET} erc-modules @key{RET}}. When removing a module outside of the Custom ecosystem, you may wish -to ensure it's disabled by invoking its associated minor-mode toggle, -such as @kbd{M-x erc-spelling-mode @key{RET}}. Note that, these days, -calling @code{erc-update-modules} in an init file is typically -unnecessary. +to ensure it's disabled by invoking its associated minor-mode toggle +with a nonpositive prefix argument, for example, @kbd{C-u - M-x +erc-spelling-mode @key{RET}}. Additionally, if you plan on loading +third-party modules that perform atypical setup on activation, you may +need to arrange for calling @code{erc-update-modules} in your init +file. Examples of such setup might include registering an +@code{erc-before-connect} hook, advising @code{erc-open}, and +modifying @code{erc-modules} itself. The following is a list of available modules. @@ -1082,6 +1086,76 @@ SASL leave this set to @code{nil}. @end defopt +@subheading Examples + +@itemize @bullet +@item +Defaults + +@lisp +(erc-tls :server "irc.libera.chat" :port 6697 + :nick "aph" + :user "APHacker" + :password "changeme") +@end lisp + +Here, after adding @code{sasl} to @code{erc-modules} via the Customize +interface, you authenticate to Libera using the @samp{PLAIN} mechanism +and your NickServ credentials, @samp{APHacker} and @samp{changeme}. + +@item +External + +@lisp +(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")) +@end lisp + +You decide to switch things up and try out the @samp{EXTERNAL} +mechanism. You follow your network's instructions for telling +NickServ about your client-certificate's fingerprint, and you +authenticate successfully. + +@item +Multiple networks + +@example +# ~/.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 +@end example + +@lisp +;; init.el + +(defun my-erc-up (network) + (interactive "Snetwork: ") + + (pcase network + ('libera + (let ((erc-sasl-mechanism 'external)) + (erc-tls :server "irc.libera.chat" :port 6697 + :client-certificate t))) + ('example + (let ((erc-sasl-auth-source-function #'erc-auth-source-search) + (erc-sasl-password 'Example.Net)) + (erc-tls :server "irc.example.net" :port 6697 + :user "alyssa"))))) +@end lisp + +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 @samp{EXTERNAL}. You use +@code{let}-binding to get around this and successfully authenticate to +both networks. + +@end itemize + @subheading Troubleshooting @strong{Warning:} ERC's SASL offering is currently limited by a lack -- 2.38.1