diff --git a/certbot/CHANGELOG.md b/certbot/CHANGELOG.md index e32bd1072..b7d57a62d 100644 --- a/certbot/CHANGELOG.md +++ b/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. Either of +* CLI flag `--elliptic-curve` has been added which takes an NIST/SECG elliptic curve. Any 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. diff --git a/certbot/docs/using.rst b/certbot/docs/using.rst index 353029822..1912dafa4 100644 --- a/certbot/docs/using.rst +++ b/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 -new private key. This requires issuing a new command, or changing the renewal -file for the certificates so it will happen on the next renewal. The two -options that you need for the renewal command are ``--key-type`` and -``--elliptic-curve `` in case you either want to be explicit or want to -use something else than the default curve ``secp256r1``:: +``rsa`` and ``ecdsa``. The type of key used by Certbot can be controlled +through the ``--key-type`` option. You can also use the ``--elliptic-curve`` +option to control the curve used in ECDSA certificates. - 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 ` + +.. 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 ---------------------