From: F. Jason Park <jp@neverwas.me>
Date: Sat, 15 Feb 2025 02:57:41 +0000 (-0800)
Subject: Use .pem extension for client certs in ERC docs
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=1c4f21ccff4fad565f19ae5150b19b42be190445;p=emacs.git

Use .pem extension for client certs in ERC docs

* doc/misc/erc.texi (Connecting): Change file-name extensions to .pem in
all examples, and explain that the key and the cert can be combined into
one file.
(SASL): Use .pem extension for certs.
* lisp/erc/erc.el (erc--warn-once-before-connect): Revise doc.
(erc-tls): Use .pem extension for certs.  (Bug#76278)

(cherry picked from commit 1f60f86af5edba45a7d59f45ca174f6c288dde3f)
---

diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi
index c1df5a62796..613df49883b 100644
--- a/doc/misc/erc.texi
+++ b/doc/misc/erc.texi
@@ -866,15 +866,15 @@ Examples of use:
 @example
 (erc-tls :server "irc.libera.chat" :port 6697
          :client-certificate
-         '("/home/bandali/my-cert.key"
-           "/home/bandali/my-cert.crt"))
+         (list (expand-file-name "~/key.pem")
+               (expand-file-name "~/cert.pem")))
 @end example
 
 @example
 (erc-tls :server "irc.libera.chat" :port 6697
          :client-certificate
-         `(,(expand-file-name "~/cert-libera.key")
-           ,(expand-file-name "~/cert-libera.crt")))
+         '("/home/bandali/libera.pem"
+           "/home/bandali/libera.pem")) ; same file
 @end example
 
 @example
@@ -882,16 +882,23 @@ Examples of use:
          :client-certificate t)
 @end example
 
+Make sure to use absolute file names for the key and the cert.  The
+files themselves must be in @acronym{PEM}-encoded text format and can be
+concatenated into a single file.
+
 In the case of @code{:client-certificate t}, you will need to add a
 line like the following to your authinfo file
 (for example, @file{~/.authinfo.gpg}):
 
 @example
-machine irc.libera.chat key /home/bandali/my-cert.key cert /home/bandali/my-cert.crt
+machine irc.libera.chat key /home/bandali/key.pem cert /home/bandali/cert.pem
 @end example
 
 @xref{Help for users,,,auth, Emacs auth-source Library}, for more on the
 @file{.authinfo}/@file{.netrc} backend of @code{auth-source}.
+If you invoke @code{erc-tls} interactively and need ERC to query
+auth-source for a client cert, see the user option
+@code{network-stream-use-client-certificates}.
 For other uses of auth-source throughout ERC, @pxref{auth-source,
 ERC's auth-source integration}.
 @end defun
@@ -1244,7 +1251,7 @@ External
 
 (erc-tls :server "irc.libera.chat" :port 6697 :nick "aph"
          :client-certificate
-         '("/home/aph/my.key" "/home/aph/my.crt"))
+         '("/home/aph/key.pem" "/home/aph/cert.pem"))
 @end lisp
 
 You decide to switch things up and try out the @samp{EXTERNAL}
@@ -1258,7 +1265,7 @@ Multiple networks
 @example
 # ~/.authinfo.gpg
 
-machine irc.libera.chat key /home/aph/my.key cert /home/aph/my.crt
+machine irc.libera.chat key /home/aph/key.pem cert /home/aph/cert.pem
 machine Example.Net login alyssa password sEcReT
 machine Example.Net login aph-bot password sesame
 @end example
diff --git a/lisp/erc/erc.el b/lisp/erc/erc.el
index e75c3ef176a..a661ae0a3a9 100644
--- a/lisp/erc/erc.el
+++ b/lisp/erc/erc.el
@@ -1661,13 +1661,12 @@ capabilities."
 (defun erc--warn-once-before-connect (mode-var &rest args)
   "Display an \"error notice\" once.
 Expect ARGS to be `erc-button--display-error-notice-with-keys'
-compatible parameters, except without any leading buffers or
-processes.  If we're in an ERC buffer with a network process when
-called, print the notice immediately.  Otherwise, if we're in a
-server buffer, arrange to do so after local modules have been set
-up and mode hooks have run.  Otherwise, if MODE-VAR is a global
-module, try again at most once the next time `erc-mode-hook'
-runs."
+compatible parameters, except without any leading buffers or processes.
+If the current buffer has an `erc-server-process', print the notice
+immediately.  Otherwise, if it's a server buffer without a process,
+arrange to do so on `erc-connect-pre-hook'.  In non-ERC buffers, so long
+as MODE-VAR belongs to a global module, try again at most once the next
+time `erc-mode-hook' runs for any connection."
   (declare (indent 1))
   (cl-assert (stringp (car args)))
   (if (derived-mode-p 'erc-mode)
@@ -2921,8 +2920,8 @@ Example client certificate (CertFP) usage:
 
     (erc-tls :server \"irc.libera.chat\" :port 6697
              :client-certificate
-             \\='(\"/home/bandali/my-cert.key\"
-               \"/home/bandali/my-cert.crt\"))
+             \\='(\"/home/bandali/my-key.pem\"
+               \"/home/bandali/my-cert.pem\"))
 
 See the alternative entry-point command `erc' as well as Info
 node `(erc) Connecting' for a fuller description of the various