upstream/certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-05-28 04:34:11 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Flesh out ECDSA documentation (#8464)

Browse source 
* Changelog tweaks.

* Add ECDSA documentation

* Fix typo
This commit is contained in:
Brad Warren 2020-11-19 00:10:56 -08:00 committed by GitHub
parent b742b60c4d
commit a8cede6ae1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 59 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
certbot/CHANGELOG.md
View file

@ -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.

67
certbot/docs/using.rst
View file

@ -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 <name>`` 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 <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
---------------------