
Challenges
**********

Digital certificates can only be issued to people who are entitled to
them. For example, assuming you don't run google.com, you're not
entitled to a certificate for it. Nor is someone else entitled to
receive a certificate for your web site.

In order to receive a certificate from Let's Encrypt certificate
authority (CA), you have to prove your control over each of the domain
names that will be listed in the certificate. You can do so by making
certain publicly-visible changes, proving that the person who's
requested a particular certificate is the same person who controls the
site(s) that the certificate will refer to.

Let’s Encrypt specifies three different ways to prove your control
over a domain (each of which Certbot may be able to do for you). These
are called "challenges," because you are being challenged to perform
tasks that only someone who controls the domain should be able to
accomplish.

When you use Certbot, it will attempt to help you prove control over
your domains automatically in a way that's acceptable to the CA.
Especially if this doesn't work the way you expected, it can be
helpful to understand what Certbot is trying to do in each case.

The three ways to prove your control over a domain for the Let’s
Encrypt CA are:

* Posting a specified file on a web site

This method is called the HTTP-01 challenge.  In this challenge, the
certificate authority will expect a specified file to be posted in a
specified location on a web site.  The file will be downloaded using
an HTTP request on TCP port 80.  Since part of what this challenge
shows is the ability to create a file at an arbitrary location, you
cannot choose a different location or port number.

* Offering a specified certificate on a web site

This method is called the TLS-SNI-01 challenge.  In this challenge,
the certificate authority will expect a specified digital certificate
to be provided by the web server in response to an HTTPS request using
a particular made-up domain name.  The request will be made using
HTTPS on TCP port 443.  You cannot choose a different port number.

This certificate is a self-signed certificate created by Certbot.  You
use it only temporarily to prove your control over a domain name.
It’s not the same as the certificate for your site that will later be
issued by Let's Encrypt once you've proven that you control the site.

* Posting a specified DNS record in the domain name system

This method is called the DNS-01 challenge.  In this challenge, the
certificate authority will expect a specified DNS record to be present
in your DNS zone when queried for.  The record will be a TXT record
for a specific subdomain of the name you're proving your control over.

For each kind of challenge, the challenge can potentially be completed
*automatically* (Certbot directly makes the necessary changes itself,
or runs another program that does so), or *manually* (Certbot tells
you to make a certain change, and you edit a configuration file of
some kind in order to accomplish it).  Certbot's design emphasizes
performing challenges *automatically*, and this is the normal case for
most uses of Certbot.

Some Certbot *plugins* offer the functionality of an *authenticator*,
which simply means that they can satisfy challenges. Different plugins
can satisfy different kinds of challenges, as follows:

apache plugin: Can only use TLS-SNI-01.  Tries to edit your Apache
configuration files in order to temporarily serve a specified Certbot-
generated certificate for a specified name.  This can work when you're
running Certbot on a web server with an existing installation of
Apache that is able to listen on port 443. This makes certain
assumptions about your Apache configuration.

nginx plugin: Can only use TLS-SNI-01.  Tries to edit your nginx
configuration files in order to temporarily serve a specified Certbot-
generated certificate for a specified name.  This can work when you're
running Certbot on a web server with an existing installation of nginx
that is able to listen on port 443. This makes certain assumptions
about your nginx configuration.

webroot plugin: Can only use HTTP-01.  Tries to place a file into an
appropriate place in order for that file to be served over HTTP on
port 80 by an existing web server running on your system.  This can
work when you're running Certbot on a web server with any existing
server application that already listens to web requests on port 80,
and that serves files from disk in response.

standalone plugin: Can use either TLS-SNI-01 or HTTP-01.  (You can
choose with the "--preferred-challenges" option.)  Tries to run its
own temporary web server which will speak either HTTP on port 80 (for
HTTP-01) or HTTPS on port 443 (for TLS-SNI-01).  This can work if
either of these ports is free to receive incoming connections at the
moment that you run Certbot, because there's no existing program
listening to them or because you've temporarily shut down any server
application that was listening to them.

manual plugin: Can use either DNS-01 or HTTP-01.  May tell you what
changes you are expected to make to your configuration.  Or, using an
external script, can update your DNS records (for DNS-01) or your
webroot (for HTTP-01).  This can work if you have appropriate
technical knowledge of how to make these kinds of changes yourself
when asked to do so.  Note that this will prevent automated renewal of
your certificate using "certbot renew".  [Can manual also use TLS-
SNI-01??]

Common problems with passing different challenges

HTTP-01 challenge: * (With webroot plugin) You aren't running Certbot
on your web server

   Most people should install and run Certbot on their web server
   hosting their website, not on their laptops or some other computer.
   While you can use Certbot in manual mode on a laptop and then
   separately set up the appropriate files on your webserver, it's not
   likely to be the most convenient way to get a certificate for most
   users.

* A domain name you're requesting a certificate for isn't correctly
  pointed at that web server

  In most cases, every name you're requesting a certificate for should
  already exist and be pointed to the public IP address of the server
  where you're requesting that certificate.  (Some alternatives exist
  for complex network configurations, but they're the exception rather
  than the rule.)

* A firewall is blocking access to port 80

  The certificate authority needs to be able to connect to port 80 of
  your server in order to confirm that you satisfied the HTTP-01
  challenge.  So that needs to be publicly reachable from the
  Internet, and not blocked by a router or firewall.

* (With webroot plugin) You specified the webroot directory
  incorrectly

  If you used "--webroot", you need to tell Certbot where it can put
  files in order to have them served by your existing web server. If
  you said your webroot for example.com was /var/www/example.com, then
  a file placed in /var/www/example.com/.well-known/acme-
  challenge/testfile should appear on your web site at
  "http://example.com/.well-known/acme-challenge/testfile" (which you
  can test using a web browser). (A redirection to HTTPS is OK here
  and should not stop the challenge from working.)

  Note that you should *not* specify the .well-known/acme-challenge
  directory itself.  Instead, you should specify the top level
  directory that web content is served from.

* (With webroot plugin) You don't have a webroot directory at all

  In some web server configurations, all pages are dynamically
  generated by some kind of framework, usually using a database
  backend.  In this case, there might not be a particular directory
  that files can be directly served from by the existing web server
  application.  Using the webroot plugin in this case requires making
  a change to your web server configuration first.

* (With manual plugin) You updated the webroot directory incorrectly

  If you used "--manual", you need to know where you can put files in
  order to have them served by your existing web server. If you think
  your webroot for example.com is /var/www/example.com, then a file
  placed in /var/www/example.com/.well-known/acme-challenge/testfile
  should appear on your web site at "http://example.com/.well-known
  /acme-challenge/testfile".  (A redirection to HTTPS is OK here and
  should not stop the challenge from working.) You should also make
  sure that you don't make a typo in the name of the file when
  creating it.

* Your existing web server's configuration refuses to serve files
  from /.well-known/acme-challenge, or doesn't serve them at the
  /.well- known/acme-challenge location on your site, or serves them
  with a header or footer, or serves them with an unusual MIME type.

* (With standalone plugin) You tried to use "--standalone" when
  there was already some other program on your server listening to
  port 80

* (With webroot plugin) You tried to use "--webroot" when you don't
  have an existing web server listening on port 80

* Your DNS records aren't valid Try checking your DNS records with a
  tool like the DNSchecker at http://www.dnsstuff.com/ to make sure
  there are no serious errors. Sometimes a DNS error still allows your
  site to load in a web browser, but prevents the certificate
  authority from issuing a certificate.

TLS-SNI-01 challenge: * You aren't running Certbot on your web server

   Most people should install and run Certbot on their web server
   hosting their website, not on their laptops or some other computer.
   While you can use Certbot in manual mode on a laptop and then
   separately set up the appropriate files on your webserver, it's not
   likely to be the most convenient way to get a certificate for most
   users.

* A domain name you're requesting a certificate for isn't correctly
  pointed at that web server

  In most cases, every name you're requesting a certificate for should
  already exist and be pointed to the server where you're requesting
  that certificate.  (Some alternatives exist for complex network
  configurations, but they're the exception rather than the rule.)

* You're using a content delivery network (CDN)

  TLS-SNI-01 doesn't work with CDNs (like CloudFlare and Akamai).  You
  have to use a different challenge type.  (This is a special case of
  the previous problem: the domain name is pointed at the CDN, not
  directly at your server.)

* A firewall is blocking access to port 443

  The certificate authority needs to be able to connect to port 443 of
  your server in order to confirm that you satisfied the TLS-SNI-01
  challenge.  So that needs to be publicly reachable from the
  Internet, and not blocked by a router or firewall.

* (With apache plugin) Certbot thinks you're running Apache, but you
  aren't running it, or you're running a different server of some kind
  on port 443

* (With nginx plugin) Certbot thinks you're running nginx, but you
  aren't running it, or you're running a different server of some kind
  on port 443

* (With apache or nginx plugin) Certbot doesn't know how to modify
  your web server configuration correctly

* (With standalone plugin) You tried to use "--standalone" when
  there was already some other program on your server listening to
  port 443

* Your DNS records aren't valid Try checking your DNS records with a
  tool like the DNSchecker at http://www.dnsstuff.com/ to make sure
  there are no serious errors. Sometimes a DNS error still allows your
  site to load in a web browser, but prevents the certificate
  authority from issuing a certificate.

DNS-01 challenge:

* (With manual plugin) Your DNS records weren't correctly updated.
  You need to be able to make appropriate changes to your DNS zone in
  order to pass the challenge.

* Your DNS records aren't valid. Try checking your DNS records with
  a tool like the DNSchecker at http://www.dnsstuff.com/ to make sure
  there are no serious errors. Sometimes a DNS error still allows your
  site to load in a web browser, but prevents the certificate
  authority from issuing a certificate.
