upstream/certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-06-04 06:15:36 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Merge pull request #6574 from certbot/no-more-tls-sni-01

Browse source 
Remove references to TLS-SNI-01
This commit is contained in:
schoen 2018-12-10 22:55:28 -08:00 committed by GitHub
commit a8a1942ee2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 36 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
docs/challenges.rst
View file

@ -3,10 +3,9 @@ Challenges
To receive a certificate from Let's Encrypt certificate authority (CA), you must pass a *challenge* to
prove you control each of the domain names that will be listed in the certificate. A challenge is one of
three tasks that only someone who controls the domain should be able to accomplish:
a list of specified tasks that only someone who controls the domain should be able to accomplish, such as:
* Posting a specified file in a specified location on a web site (the HTTP-01 challenge)
* Offering a specified temporary certificate on a web site (the TLS-SNI-01 challenge)
* Posting a specified DNS record in the domain name system (the DNS-01 challenge)
It’s possible to complete each type of challenge *automatically* (Certbot directly makes the necessary
@ -16,21 +15,21 @@ design favors performing challenges automatically, and this is the normal case f
Some plugins offer an *authenticator*, meaning that they can satisfy challenges:
* Apache plugin: (TLS-SNI-01) Tries to edit your Apache configuration files to temporarily serve
a Certbot-generated certificate for a specified name. Use the Apache plugin when you're running
Certbot on a web server with Apache listening on port 443.
* NGINX plugin: (TLS-SNI-01) Tries to edit your NGINX configuration files to temporarily serve a
Certbot-generated certificate for a specified name. Use the NGINX plugin when you're running
Certbot on a web server with NGINX listening on port 443.
* Apache plugin: (HTTP-01) Tries to edit your Apache configuration files to temporarily serve files to
satisfy challenges from the certificate authority. Use the Apache plugin when you're running Certbot on a
web server with Apache listening on port 80.
* Nginx plugin: (HTTP-01) Tries to edit your nginx configuration files to temporarily serve files to
satisfy challenges from the certificate authority. Use the nginx plugin when you're running Certbot on a
web server with nginx listening on port 80.
* Webroot plugin: (HTTP-01) Tries to place a file where it can be served over HTTP on port 80 by a
web server running on your system. Use the Webroot plugin when you're running Certbot on
a web server with any server application listening on port 80 serving files from a folder on disk in response.
* Standalone plugin: (TLS-SNI-01 or HTTP-01) Tries to run a temporary web server listening on either HTTP on
port 80 (for HTTP-01) or HTTPS on port 443 (for TLS-SNI-01). Use the Standalone plugin if no existing program
is listening to these ports. Choose TLS-SNI-01 or HTTP-01 using the `--preferred-challenges` option.
* Standalone plugin: (HTTP-01) Tries to run a temporary web server listening on HTTP on port 80. Use the
Standalone plugin if no existing program is listening to this port.
* Manual plugin: (DNS-01 or HTTP-01) Either tells you what changes to make to your configuration or updates
your DNS records using an external script (for DNS-01) or your webroot (for HTTP-01). Use the Manual
plugin if you have the technical knowledge to make configuration changes yourself when asked to do so.
plugin if you have the technical knowledge to make configuration changes yourself when asked to do so,
and are prepared to repeat these steps every time the certificate needs to be renewed.
Tips for Challenges
-------------------
@ -63,20 +62,6 @@ HTTP-01 Challenge
* When using the Standalone plugin, make sure another program is not already listening to port 80 on the server.
* When using the Webroot plugin, make sure there is a web server listening on port 80.
TLS-SNI-01 Challenge
~~~~~~~~~~~~~~~~~~~~
* The TLS-SNI-01 challenge doesn’t work with content delivery networks (CDNs)
like CloudFlare and Akamai because the domain name is pointed at the CDN, not directly at your server.
* Make sure port 443 is open, publicly reachable from the Internet, and not blocked by a router or firewall.
* When using the Apache plugin, make sure you are running Apache and no other web server on port 443.
* When using the NGINX plugin, make sure you are running NGINX and no other web server on port 443.
* With either the Apache or NGINX plugin, certbot modifies your web server configuration. If you get
an error after successfully completing the challenge, then you have received a certificate but the
plugin was unable to modify your web server configuration, meaning that you'll have to install the certificate manually.
In that case, please file a bug to help us improve certbot!
* When using the Standalone plugin, make sure another program is not already listening to port 443 on the server.
DNS-01 Challenge
~~~~~~~~~~~~~~~~

6
docs/contributing.rst
View file

@ -186,8 +186,8 @@ Authenticators
--------------
Authenticators are plugins that prove control of a domain name by solving a
challenge provided by the ACME server. ACME currently defines three types of
challenges: HTTP, TLS-SNI, and DNS, represented by classes in `acme.challenges`.
challenge provided by the ACME server. ACME currently defines several types of
challenges: HTTP, TLS-SNI (deprecated), TLS-ALPR, and DNS, represented by classes in `acme.challenges`.
An authenticator plugin should implement support for at least one challenge type.
An Authenticator indicates which challenges it supports by implementing
@ -215,7 +215,7 @@ support for IIS, Icecast and Plesk.
Installers and Authenticators will oftentimes be the same class/object
(because for instance both tasks can be performed by a webserver like nginx)
though this is not always the case (the standalone plugin is an authenticator
that listens on port 443, but it cannot install certs; a postfix plugin would
that listens on port 80, but it cannot install certs; a postfix plugin would
be an installer but not an authenticator).
Installers and Authenticators are kept separate because

2
docs/install.rst
View file

@ -29,7 +29,7 @@ System Requirements
Certbot currently requires Python 2.7 or 3.4+ running on a UNIX-like operating
system. By default, it requires root access in order to write to
``/etc/letsencrypt``, ``/var/log/letsencrypt``, ``/var/lib/letsencrypt``; to
bind to ports 80 and 443 (if you use the ``standalone`` plugin) and to read and
bind to port 80 (if you use the ``standalone`` plugin) and to read and
modify webserver configurations (if you use the ``apache`` or ``nginx``
plugins). If none of these apply to you, it is theoretically possible to run
without root privileges, but for most users who want to avoid running an ACME

53
docs/using.rst
View file

@ -44,14 +44,13 @@ a combination_ of distinct authenticator and installer plugins.
=========== ==== ==== =============================================================== =============================
Plugin Auth Inst Notes Challenge types (and port)
=========== ==== ==== =============================================================== =============================
apache_ Y Y | Automates obtaining and installing a certificate with Apache tls-sni-01_ (443)
apache_ Y Y | Automates obtaining and installing a certificate with Apache http-01_ (80)
| 2.4 on OSes with ``libaugeas0`` 1.0+.
nginx_ Y Y | Automates obtaining and installing a certificate with Nginx. http-01_ (80)
webroot_ Y N | Obtains a certificate by writing to the webroot directory of http-01_ (80)
| an already running webserver.
nginx_ Y Y | Automates obtaining and installing a certificate with Nginx. tls-sni-01_ (443)
| Shipped with Certbot 0.9.0.
standalone_ Y N | Uses a "standalone" webserver to obtain a certificate. http-01_ (80) or
| Requires port 80 or 443 to be available. This is useful on tls-sni-01_ (443)
standalone_ Y N | Uses a "standalone" webserver to obtain a certificate. http-01_ (80)
| Requires port 80 to be available. This is useful on
| systems with no webserver, or when direct integration with
| the local webserver is not supported or not desired.
|dns_plugs| Y N | This category of plugins automates obtaining a certificate by dns-01_ (53)
@ -59,17 +58,17 @@ standalone_ Y N | Uses a "standalone" webserver to obtain a certificate.
| domain. Doing domain validation in this way is
| the only way to obtain wildcard certificates from Let's
| Encrypt.
manual_ Y N | Helps you obtain a certificate by giving you instructions to http-01_ (80),
| perform domain validation yourself. Additionally allows you dns-01_ (53) or
| to specify scripts to automate the validation task in a tls-sni-01_ (443)
manual_ Y N | Helps you obtain a certificate by giving you instructions to http-01_ (80) or
| perform domain validation yourself. Additionally allows you dns-01_ (53)
| to specify scripts to automate the validation task in a
| customized way.
=========== ==== ==== =============================================================== =============================
.. |dns_plugs| replace:: :ref:`DNS plugins <dns_plugins>`
Under the hood, plugins use one of several ACME protocol challenges_ to
prove you control a domain. The options are http-01_ (which uses port 80),
tls-sni-01_ (port 443) and dns-01_ (requiring configuration of a DNS server on
prove you control a domain. The options are http-01_ (which uses port 80)
and dns-01_ (requiring configuration of a DNS server on
port 53, though that's often not the same machine as your webserver). A few
plugins support more than one challenge type, in which case you can choose one
with ``--preferred-challenges``.
@ -78,7 +77,6 @@ There are also many third-party-plugins_ available. Below we describe in more de
the circumstances in which each plugin can be used, and how to use it.
.. _challenges: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7
.. _tls-sni-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.3
.. _http-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.2
.. _dns-01: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.4
@ -159,13 +157,9 @@ software running on the machine where you obtain the certificate.
To obtain a certificate using a "standalone" webserver, you can use the
standalone plugin by including ``certonly`` and ``--standalone``
on the command line. This plugin needs to bind to port 80 or 443 in
on the command line. This plugin needs to bind to port 80 in
order to perform domain validation, so you may need to stop your
existing webserver. To control which port the plugin uses, include
one of the options shown below on the command line.
* ``--preferred-challenges http`` to use port 80
* ``--preferred-challenges tls-sni`` to use port 443
existing webserver.
It must still be possible for your machine to accept inbound connections from
the Internet on the specified port using each requested domain name.
@ -222,8 +216,7 @@ the UI, you can use the plugin to obtain a certificate by specifying
to copy and paste commands into another terminal session, which may
be on a different computer.
The manual plugin can use either the ``http``, ``dns`` or the
``tls-sni`` challenge. You can use the ``--preferred-challenges`` option
The manual plugin can use either the ``http`` or the ``dns`` challenge. You can use the ``--preferred-challenges`` option
to choose the challenge of your preference.
The ``http`` challenge will ask you to place a file with a specific name and
@ -241,11 +234,6 @@ For example, for the domain ``example.com``, a zone file entry would look like:
_acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM"
When using the ``tls-sni`` challenge, ``certbot`` will prepare a self-signed
SSL certificate for you with the challenge validation appropriately
encoded into a subjectAlternatNames entry. You will need to configure
your SSL server to present this challenge SSL certificate to the ACME
server using SNI.
Additionally you can specify scripts to prepare for validation and
perform the authentication procedure and/or clean up after it by using
@ -262,16 +250,20 @@ installer plugins. To do so, specify the authenticator plugin with
``--authenticator`` or ``-a`` and the installer plugin with ``--installer`` or
``-i``.
For instance, you may want to create a certificate using the webroot_ plugin
for authentication and the apache_ plugin for installation, perhaps because you
use a proxy or CDN for SSL and only want to secure the connection between them
and your origin server, which cannot use the tls-sni-01_ challenge due to the
intermediate proxy.
For instance, you could create a certificate using the webroot_ plugin
for authentication and the apache_ plugin for installation.
::
certbot run -a webroot -i apache -w /var/www/html -d example.com
Or you could create a certificate using the manual_ plugin for authentication
and the nginx_ plugin for installation. (Note that this certificate cannot
be renewed automatically.)
::
certbot run -a manual -i nginx -d example.com
.. _third-party-plugins:
Third-party plugins
@ -781,9 +773,6 @@ variables to these scripts:
- ``CERTBOT_DOMAIN``: The domain being authenticated
- ``CERTBOT_VALIDATION``: The validation string (HTTP-01 and DNS-01 only)
- ``CERTBOT_TOKEN``: Resource name part of the HTTP-01 challenge (HTTP-01 only)
- ``CERTBOT_CERT_PATH``: The challenge SSL certificate (TLS-SNI-01 only)
- ``CERTBOT_KEY_PATH``: The private key associated with the aforementioned SSL certificate (TLS-SNI-01 only)
- ``CERTBOT_SNI_DOMAIN``: The SNI name for which the ACME server expects to be presented the self-signed certificate located at ``$CERTBOT_CERT_PATH`` (TLS-SNI-01 only)
Additionally for cleanup: