File-based domain control validation (http-token)

This article describes how the CertCentral Services API handles requests to validate domains submitted with a domain control validation (DCV) method of http-token.

Industry changes to file-based (http-token) DCV

Starting November 16, 2021, DigiCert only supports the use of the file-based DCV method to demonstrate control over fully qualified domain names (FQDNs) exactly as named in the certificate request.

Use one of the other supported DCV methods, such as email, DNS TXT, and CNAME, to:

  • Validate wildcard domains (*.example.com).
  • Include subdomains in the validation when validating a higher-level domain. For example, if you want to cover www.example.com when validating the higher-level domain example.com.
  • Prevalidate entire domains and subdomains.

If you have a pending certificate request with incomplete file-based DCV checks:

  • If the request includes wildcard domains that are pending validation, you must change the DCV method for the wildcard domains.
  • If the request includes non-wildcard domains that are pending validation, you must change the DCV method or complete the file-based DCV check for every FQDN exactly as named in the request.

Certificate order requests

When you use the Services API to request DV, OV, and EV TLS/SSL certificates, you can choose file-based DCV by setting the dcv_method request parameter to http-token. Because http-token is not a valid DCV method for wildcard domains, the API handles requests differently when the common_name or dns_names fields include a wildcard domain.

Non-wildcard domains only

Certificate order requests with common_name and dns_names fields that only contain non-wildcard domains are accepted. To complete domain validation, upload the random token in the API response to each individual FQDN on the order.

  • Orders for DV certificates return a single token value. Use the same token to complete the DCV check for every domain on the order.
  • Orders for OV/EV certificates return a different token for each domain you need to validate. Use each domain’s unique token to complete the DCV check for every domain on the order.

For example, to validate the domains in the JSON payload below, upload tokens to both example.com and sub.example.com.

Example request with non-wildcard domains
{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
      "sub.example.com"
    ]
    ...
  },
  "dcv_method": "http-token",
  ...
}

Wildcard domains only

For products that allow wildcard domain names, certificate order requests with common_name and dns_names fields that contain wildcard domains only (*.example.com) are rejected with the error code invalid_wildcard_dcv_method. To request a certificate that only includes wildcard domains, use a different DCV method (email, dns-txt-token, or dns-cname-token).

Example request with wildcard domain
{
  "certificate": {
    "common_name": "*.example.com",
    ...
  },
  "dcv_method": "http-token",
  ...
}

Both wildcard and non-wildcard domains

For products that allow wildcard domain names, certificate order requests with common_name and dns_names fields that contain a combination of wildcard and non-wildcard domains (for example, *.example.com, my.biz.example.com, and example.net) are handled differently depending on whether the order is for a DV or OV/EV certificate.

EV certificates only allow wildcard domains if the right-most domain label is "onion" (*.example.onion). To learn more about ordering a certificate for your .onion address, visit Ordering a .onion certificate from DigiCert.

Example request with wildcard and non-wildcard domains
{
  "certificate": {
    "common_name": "*.example.com",
    "dns_names": [
      "my.biz.example.com"
      "example.net"
    ]
    ...
  },
  "dcv_method": "http-token",
  ...
}

DV certificate orders

DV certificate order requests with common_name and dns_names fields that contain a combination of wildcard and non-wildcard domains are rejected with the error code invalid_wildcard_dcv_method. To request a DV certificate that includes wildcard and non-wildcard domains, use a different DCV method (email, dns-txt-token, or dns-cname-token).

OV/EV certificate orders

OV/EV certificate order requests with common_name and dns_names fields that contain a combination of wildcard and non-wildcard domains are accepted.

  • Non-wildcard domains (example.net) are submitted for validation with a DCV method of http-token.* To complete DCV checks, upload the token in the API response for each of these domains.
  • Wildcard domains (*.example.com) are submitted for validation with a DCV method of email. If the order includes non-wildcard subdomains of the wildcard domain (my.biz.example.com), these subdomains are validated when you complete the email DCV check for the wildcard domain. These subdomains are not individually submitted for file-based DCV.

*For accounts configured to submit base domains for validation

If you request an OV/EV certificate for both a wildcard domain (*.sub.example.com) and a higher-level domain of the wildcard domain (example.com), the shared base domain (example.com) is submitted for validation using email DCV. The DCV method for the base domain is automatically changed to email when you submit your request. This allows DigiCert to honor the account setting to submit the base domain for validation. To validate both domains, complete the email DCV check for the base domain.

Domain prevalidation

The Services API allows you to prevalidate domains for OV and EV certificate requests. Prevalidating domains reduces the number of tasks you must complete before your OV or EV certificate can be issued.

Use these endpoints to submit domains for prevalidation:

When you submit a domain for prevalidation, you choose which DCV method to use to prove control over the domain.

  • Using email, dns-txt-token, or dns-cname-token (recommended) validates the submitted domain and any wildcard domains or subdomains of the submitted domain.
  • Using http-token only validates the specific FQDN submitted for prevalidation.

Requests to add or submit a wildcard domain (*.example.com) for validation using the http-token DCV method are rejected with the error code invalid_wildcard_dcv_method.