Thousands of people around the world make our work possible. Donate today.
Let's Encrypt

Challenge Types

Se på Dansk

Auf Deutsch ansehen

Ver en español

Katso suomeksi

Voir en français

לעבור לעברית

Megtekintés magyar nyelven

日本語で表示する

한국어로 보기

Просмотреть на русском

Переглянути українською

阅读简体中文页面

使用正體中文閲讀本網頁。

Last updated: | See all Documentation

When you get a certificate from Let’s Encrypt, our servers validate that you control the domain names in that certificate using “challenges,” as defined by the ACME standard. Most of the time, this validation is handled automatically by your ACME client, but if you need to make some more complex configuration decisions, it’s useful to know more about them. If you’re unsure, go with your client’s defaults or with HTTP-01.

HTTP-01 challenge

This is the most common challenge type today. Let’s Encrypt gives a token to your ACME client, and your ACME client puts a file on your web server at http://<YOUR_DOMAIN>/.well-known/acme-challenge/<TOKEN>. That file contains the token, plus a thumbprint of your account key. Once your ACME client tells Let’s Encrypt that the file is ready, Let’s Encrypt tries retrieving it (potentially multiple times from multiple vantage points). If our validation checks get the right responses from your web server, the validation is considered successful and you can go on to issue your certificate. If the validation checks fail, you’ll have to try again with a new certificate.

Our implementation of the HTTP-01 challenge follows redirects, up to 10 redirects deep. It only accepts redirects to “http:” or “https:”, and only to ports 80 or 443. It does not accept redirects to IP addresses. When redirected to an HTTPS URL, it does not validate certificates (since this challenge is intended to bootstrap valid certificates, it may encounter self-signed or expired certificates along the way).

The HTTP-01 challenge can only be done on port 80. Allowing clients to specify arbitrary ports would make the challenge less secure, and so it is not allowed by the ACME standard.

Pros:

Cons:

DNS-01 challenge

This challenge asks you to prove that you control the DNS for your domain name by putting a specific value in a TXT record under that domain name. It is harder to configure than HTTP-01, but can work in scenarios that HTTP-01 can’t. It also allows you to issue wildcard certificates. After Let’s Encrypt gives your ACME client a token, your client will create a TXT record derived from that token and your account key, and put that record at _acme-challenge.<YOUR_DOMAIN>. Then Let’s Encrypt will query the DNS system for that record. If it finds a match, you can proceed to issue a certificate!

Since automation of issuance and renewals is really important, it only makes sense to use DNS-01 challenges if your DNS provider has an API you can use to automate updates. Our community has started a list of such DNS providers here. Your DNS provider may be the same as your registrar (the company you bought your domain name from), or it might be different. If you want to change your DNS provider, you just need to make some small changes at your registrar. You don’t need to wait for your domain to be close to expiration to do so.

Note that putting your full DNS API credentials on your web server significantly increases the impact if that web server is hacked. Best practice is to use more narrowly scoped API credentials, or perform DNS validation from a separate server and automatically copy certificates to your web server.

Since Let’s Encrypt follows the DNS standards when looking up TXT records for DNS-01 validation, you can use CNAME records or NS records to delegate answering the challenge to other DNS zones. This can be used to delegate the _acme-challenge subdomain to a validation-specific server or zone. It can also be used if your DNS provider is slow to update, and you want to delegate to a quicker-updating server.

Most DNS providers have a “propagation time” that governs how long it takes from the time you update a DNS record until it’s available on all of their servers. It can be hard to measure this because they often also use anycast, which means multiple servers can have the same IP address, and depending on where you are in the world you might talk to a different server (and get a different answer) than Let’s Encrypt does. The best DNS APIs provide a way for you to automatically check whether an update is fully propagated. If your DNS provider doesn’t have this, you just have to configure your client to wait long enough (often as much as an hour) to ensure the update is propagated before triggering validation.

You can have multiple TXT records in place for the same name. For instance, this might happen if you are validating a challenge for a wildcard and a non-wildcard certificate at the same time. However, you should make sure to clean up old TXT records, because if the response size gets too big Let’s Encrypt will start rejecting it.

Pros:

Cons:

TLS-SNI-01

This challenge was defined in draft versions of ACME. It did a TLS handshake on port 443 and sent a specific SNI header, looking for certificate that contained the token. It was disabled in March 2019 because it was not secure enough.

TLS-ALPN-01

This challenge was developed after TLS-SNI-01 became deprecated, and is being developed as a separate standard. Like TLS-SNI-01, it is performed via TLS on port 443. However, it uses a custom ALPN protocol to ensure that only servers that are aware of this challenge type will respond to validation requests. This also allows validation requests for this challenge type to use an SNI field that matches the domain name being validated, making it more secure.

This challenge is not suitable for most people. It is best suited to authors of TLS-terminating reverse proxies that want to perform host-based validation like HTTP-01, but want to do it entirely at the TLS layer in order to separate concerns. Right now that mainly means large hosting providers, but mainstream web servers like Apache and Nginx could someday implement this (and Caddy already does).

Pros:

Cons: