From c93443364ce23ced97a80bfda8f8bb35ec19fcdb Mon Sep 17 00:00:00 2001
From: Guilhem Moulin <guilhem@fripost.org>
Date: Wed, 9 Dec 2020 19:02:44 +0100
Subject: documentation: suggest to generate private key material with
 genpkey(1ssl).

 * Also suggest a command to generate an ECDSA key not just RSA.
 * Hint at which key algorithms are supported.
---
 Changelog           |  3 +++
 lacme-accountd      |  2 +-
 lacme-accountd.1.md | 10 +++++++---
 lacme.8.md          | 26 ++++++++++++++++++++++----
 4 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/Changelog b/Changelog
index a565440..39df738 100644
--- a/Changelog
+++ b/Changelog
@@ -2,6 +2,9 @@ lacme (0.7.1) upstream;
 
  - lacme: delay webserver socket shutdown to after the process has
    terminated.
+ - documentation: suggest to generate private key material with
+   genpkey(1ssl); also suggest a command to generate an ECDSA key not
+   just RSA; hint at which key algorithms are supported.
 
  -- Guilhem Moulin <guilhem@fripost.org>  Wed, 09 Dec 2020 18:23:22 +0100
 
diff --git a/lacme-accountd b/lacme-accountd
index af64168..deccfa2 100755
--- a/lacme-accountd
+++ b/lacme-accountd
@@ -94,7 +94,7 @@ if ($OPTS{privkey} =~ /\A(file|gpg):(\p{Print}+)\z/) {
     my ($method, $filename) = ($1,$2);
     my ($fh, @command);
     if ($method eq 'file') {
-        # generate with `openssl genrsa 4096 | install --mode=0600 /dev/stdin /tmp/privkey`
+        # generate with `openssl genpkey -algorithm RSA`
         open $fh, '<', $filename or die "Error: Can't open $filename: $!\n";
     }
     elsif ($method eq 'gpg') {
diff --git a/lacme-accountd.1.md b/lacme-accountd.1.md
index a967b67..24e73eb 100644
--- a/lacme-accountd.1.md
+++ b/lacme-accountd.1.md
@@ -55,10 +55,13 @@ Options
     * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in
       PEM format).
 
-    The following command can be used to generate a new 4096-bits RSA
-    key in PEM format with mode 0600:
+    The [`genpkey`(1ssl)] command can be used to generate a new private
+    (account) key:
 
-        openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/account.key
+        $ install -vm0600 /dev/null /path/to/account.key
+        $ openssl genpkey -algorithm RSA -out /path/to/account.key
+
+    Currently `lacme-accountd` only supports RSA account keys.
 
 `--socket=`*path*
 
@@ -141,3 +144,4 @@ See also
 [`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html
 [OpenSSH]: https://www.openssh.com/
 [`ssh`(1)]: https://man.openbsd.org/ssh
+[`genpkey`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html
diff --git a/lacme.8.md b/lacme.8.md
index 4098662..c1bea54 100644
--- a/lacme.8.md
+++ b/lacme.8.md
@@ -332,11 +332,28 @@ Valid options are:
 
 *certificate-key*
 
-:   Path the service's private key.  This option is required.  The
-    following command can be used to generate a new 4096-bits RSA key in
-    PEM format with mode 0600:
+:   Path to the service's private key.  This option is required.  The
+    [`genpkey`(1ssl)] command can be used to generate a new service RSA
+    key:
 
-        openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/srv.key
+        $ install -vm0600 /dev/null /path/to/service.rsa.key
+        $ openssl genpkey -algorithm RSA -out /path/to/service.rsa.key
+
+    Alternatively, for an ECDSA key using the NIST P-256 curve:
+
+        $ install -vm0600 /dev/null /path/to/service.ecdsa.key
+        $ openssl genpkey -algorithm EC -out /path/to/service.ecdsa.key \
+			-pkeyopt ec_paramgen_curve:P-256 \
+			-pkeyopt ec_param_enc:named_curve
+
+    `lacme` supports any key algorithm than the underlying libssl
+    (OpenSSL) version is able to manipulate, but the [ACME] server might
+    reject CSRs associated with private keys of deprecated and/or
+    “exotic” algorithms.
+
+    For a dual cert setup (for instance RSA+ECDSA), duplicate the
+    certificate section and use a distinct *certificate-key* resp.
+    *certificate* (or *certificate-chain*) value for each key algorithm.
 
 *min-days*
 
@@ -407,3 +424,4 @@ See also
 [`iptables`(8)]: https://linux.die.net/man/8/iptables
 [`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
 [`x509v3_config`(5ssl)]: https://www.openssl.org/docs/manmaster/apps/x509v3_config.html
+[`genpkey`(1ssl)]: https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html
-- 
cgit v1.2.3