From: Stefan Eissing <icing@apache.org>
Date: Mon, 17 May 2021 12:13:58 +0000 (+0000)
Subject: Merge r1889958 from trunk:
X-Git-Tag: 2.4.48~4
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2f4d7f82612957534c9b2f29b7d2dba118d5b9be;p=thirdparty%2Fapache%2Fhttpd.git

Merge r1889958 from trunk:

mod_md: update documentation regarding private keys and message events.



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1889959 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_md.xml b/docs/manual/mod/mod_md.xml
index 646cb66459b..6fcd9b75568 100644
--- a/docs/manual/mod/mod_md.xml
+++ b/docs/manual/mod/mod_md.xml
@@ -675,22 +675,31 @@ MDPortMap http:- https:8433
         <usage>
             <p>
                 Defines what kind of private keys are generated for a managed domain and with
-                what parameters. The only supported type right now is 'RSA' and the only parameter
-                it takes is the number of bits used for the key.
+                what parameters. You can have more than one private key type configured and
+                the module will obtain a certificate for each key.
             </p><p>
-                The current (2017) recommendation is at least 2048 bits and a smaller number is
-                not accepted here. Higher numbers offer longer security, but are computationally more 
-                expensive, e.g. increase the load on your server. That might or might not be an
-                issue for you.
+                For example, you may configure an RSA and an Elliptic Curve (EC) key, so
+                that 2 certicates are created for a domain. On a client connection, the first
+                one supported by the client will then be used.
             </p><p>
-                Other key types will be defined in the future.
+                Since EC keys and certificates are smaller, you might want to offer
+                them first for all compatible (modern) clients. This can enable
+                faster handshakes. Add an RSA key type to support older clients.
             </p>
             <example><title>Example</title>
                 <highlight language="config">
-MDPrivateKeys RSA 3072
+MDPrivateKeys secp256r1 rsa3072
                 </highlight>
             </example>
             <p>
+                The EC types supported depend on the CA you use. For Let's encrypt
+                the supported curves include 'secp256r1' and 'secp384r1'.
+            </p><p>
+                Each key and certificate type is stored in its own file in the
+                MD store. The key type is part of the file name with some backward
+                compatible naming for RSA certificates. So you may continue sharing
+                these files with other applications.
+            </p><p>
                 Please note that this setting only has an effect on new keys. Any existing
                 private key you have remains unaffected. Also, this only affects private keys
                 generated for certificates. ACME account keys are unaffected by this.
@@ -1039,6 +1048,21 @@ MDMessageCmd /etc/apache/md-message
                 with root permissions (on *nix systems) and has access to the certificate
                 files (and keys). Certificates needed for other applications or
                 in different formats can be processed on this event.
+            </p><p>
+                'renewing' event is triggered before starting renew process for the managed
+                 domain. Should the command return != 0 for this reason, renew will be
+                 aborted and repeated on next cycle. Some cluster setups use this to
+                 allow renewals to run only on a single node.
+            </p><p>
+                'challenge-setup:type:domain' event is triggered when the challenge data for a domain has
+                been created. This is invoked before the ACME server is told to check for it.
+                The type is one of the ACME challenge types. This is invoked for every
+                DNS name in a MDomain. Cluster setups may use this event to distribute
+                challenge files to all nodes in a cluster.
+            </p><p>
+                ocsp-errored happens when MDStapling is enabled for a domain, this indicates
+                that an error was encountered retrieving the OCSP response from the
+                Certificate Authority. mod_md will continue trying.
             </p>
         </usage>
     </directivesynopsis>