Flesh out ECDSA documentation (#8464)

* Changelog tweaks.

* Add ECDSA documentation

* Fix typo

certbot/CHANGELOG.md

@@ -9,8 +9,7 @@ Certbot adheres to [Semantic Versioning](https://semver.org/).
 * Added timeout to DNS query function calls for dns-rfc2136 plugin.
 * Confirmation when deleting certificates
 * CLI flag `--key-type` has been added to specify 'rsa' or 'ecdsa' (default 'rsa').
-  Only accepts a single value at this time.
+* CLI flag `--elliptic-curve` has been added which takes an NIST/SECG elliptic curve. Any of
-* CLI flag `--elliptic-curve` has been added which takes an NIST/SECG elliptic curve. Either of
   `secp256r1`, `secp284r1` and `secp521r1` are accepted values.
 * The command `certbot certficates` lists the which type of the private key that was used
   for the private key.

certbot/docs/using.rst

@@ -410,18 +410,67 @@ replace that set entirely::
   certbot certonly --cert-name example.com -d example.org,www.example.org
 
 
-Migrating to certificates based on ECDSA keys
+Using ECDSA keys
----------------------------------------------
+----------------
 
 As of version 1.10, Certbot supports two types of private key algorithms:
-``rsa`` and ``ecdsa``.  You may freely upgrade an existing certificate with a
+``rsa`` and ``ecdsa``. The type of key used by Certbot can be controlled
-new private key. This requires issuing a new command, or changing the renewal
+through the ``--key-type`` option. You can also use the ``--elliptic-curve``
-file for the certificates so it will happen on the next renewal. The two
+option to control the curve used in ECDSA certificates.
-options that you need for the renewal command are ``--key-type`` and
-``--elliptic-curve <name>`` in case you either want to be explicit or want to
-use something else than the default curve ``secp256r1``::
 
-  certbot renew --key-type ecdsa --cert-name example.com -d example.org,www.example.org
+.. warning:: If you obtain certificates using ECDSA keys, you should be careful
+   not to downgrade your Certbot installation since ECDSA keys are not
+   supported by older versions of Certbot. Downgrades like this are possible if
+   you switch from something like the snaps or certbot-auto to packages
+   provided by your operating system which often lag behind.
+
+Changing existing certificates from RSA to ECDSA
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Unless you are aware that you need to support very old HTTPS clients that are
+not supported by most sites, you can safely just transition your site to use
+ECDSA keys instead of RSA keys. To accomplish this if you have existing
+certificates managed by Certbot, you may freely change the certificate to a new
+private key.
+
+If you want to use ECDSA keys for all certificates in the future, you can
+simply add the following line to Certbot's :ref:`configuration file <config-file>`
+
+.. code-block:: ini
+
+  key-type = ecdsa
+
+After this option is set, newly obtained certificates will use ECDSA keys. This
+includes certificates managed by Certbot that previously used RSA keys.
+
+If you want to change a single certificate to use ECDSA keys, you'll need to
+issue a new Certbot command setting ``--key-type ecdsa`` on the command line
+like
+
+.. code-block:: shell
+
+  certbot renew --key-type ecdsa --cert-name example.com --force-renewal
+
+Obtaining ECDSA certificates in addition to RSA certificates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When Certbot configures the certificates it obtains with Apache or Nginx, all
+HTTPS clients that we try to support can use certificates with ECDSA keys. If,
+however, you are aware of having a specific need to support very old TLS
+clients, you may want to obtain both ECDSA and RSA certificates for the same
+domains. Certbot can only configure Apache or Nginx to use a single
+certificate, however, you could manually configure your software to use the
+different certificates depending on your needs.
+
+When obtaining both ECDSA and RSA certificates for the same domains with
+Certbot, we recommend using the ``--cert-name`` option to give your
+certificates names so that you can easily identify them. For instance, you may
+want to append "ecdsa" to the name of your ECDSA certificate by using a command
+like
+
+.. code-block:: shell
+
+  certbot certonly --key-type ecdsa --cert-name example.com-ecdsa
 
 Revoking certificates
 ---------------------