Docs Order/cert validation

Order/cert validation

In the ACME protocol, clients place orders for certs. The server then performs validation checks to determine if the client is authorized to have the ordered cert. Finally, if those checks pass, the cert is issued to the client.

CertFu supports several types of validation checks to authorize each order.

HTTP-01

Perhaps the most common because of its simplicity, HTTP-01 validates that the client software has control of the target host. HTTP-01 checks make a request to http://[cert.fqdn.or.ip]/.well-known/acme_challenge/[token] and the target webserver is required to return the authorization token that was provided to the client software by CertFu.

A few things to keep in mind:

  1. If the cert order/request is for www.example.org, the request will also be to http://www.example.org.
  2. If the cert order contains an IP address, the request will use that IP, eg: http://203.0.113.1 or http://[2001:db8::1].
  3. If the order is for two or more domains or IP addresses, all of them will be checked and must pass.
  4. The request is always on port 80. Therefore this port must be publicly reachable by CertFu.
  5. If www.example.org resolves to two or more IPs, all of them may be checked.
  6. Tokens change upon each renewal. Old tokens should generally be removed/disabled once the cert is issued.

DNS-01

DNS-01 validates control of the domain directly through a DNS TXT record. This allows the validation of wildcard certs, like *.example.org, and provides a way to validate certs when port 80 is not publicly reachable. In fact, as long as the DNS entry is public, the host itself does not need to be.

Again, a few notes:

  1. If the cert order is for www.example.org, the required DNS record will be _acme-challenge.www.example.org TXT [token].
  2. If the order is for *.example.org, the DNS record must be _acme-challenge.example.org TXT [token]. Note that the *. portion is simply removed. If a single order is for both example.org and *.example.org, two TXT records, with two tokens, must be created.
  3. Because of the reliance on the DNS system, DNS-01 cannot be used to validate certs for IP addresses.
  4. CNAMEs may be used and will be followed.
  5. Tokens change upon each renewal. Old TXT records should be removed once the cert is issued.
Using CNAMEs with DNS-01

Since DNS must be dynamically updatable to add the _acme-challenge token, CNAMEs can be particularly useful for managing access control or permissions to the DNS infrastructure.

Again, for a cert order for www.example.org:

_acme-challenge.www.example.org  CNAME  www-example-org.acme.example.com

www-example-org.acme.example.com  TXT  [token]

In this instance, the CNAME for _acme-challenge.www.example.org can be statically configured and left in place. Then the ACME client can dynamically create/delete the www-example-org.acme.example.com TXT record as needed. As such, the client would only need permission to modify DNS for *.acme.example.com.

The example here jumps between domains, from .example.org to .example.com, but you can stay within the same base domain too, of course.

DNS CAA records

DNS CAA records allow a domain name to allow or block individual certificate authorities from issuing certs for that domain. CertFu checks CAA records for all orders with domain names (unless validations are bypassed–see below).

Some key ideas:

  1. By default, certs are allowed if no CAA record exists. This can be changed with the Directory setting On missing CAA.
  2. CAA records climb the FQDN tree. That is, if the cert order is for www.example.org, CAA records will be checked on www.example.org, and then potentially on example.org.
  3. CAA checks look for the CA issuer name certfu.com. This may be customized on higher plans–see the Directory setting CAA tag.

Generally CAA records are statically created in advance. While uncommon, it’s possible to have a static default-deny CAA record and then to create per-fqdn CAA records to allow issuance by CertFu. To facilitate this kind of advanced workflow, CertFu checks CAA records after challenge validation has been initiated by the client.

Private domains/IPs and bypassing validations

To support private or internal domains, IPs, and other restricted access scenarios, CertFu allows individual Account keys to be configured to automatically authorize orders. This bypasses all checks above (HTTP-01, DNS-01, and CAA). See the Order validations setting.