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 and  http-token-dynamic.

Certificate order requests

When using 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 or http-token-dynamic. Because http-token and http-token-dynamic are not valid DCV methods 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 value in the API response to each individual FQDN on the order.

• http-token To complete domain validation, upload the random value in the API response to each individual FQDN on the order. For example, to validate the domains in the JSON payload below, upload the random value to 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",
      ...
  }
  

• http-token-dynamic To complete domain validation, add a file with a random file name that contains a random value in the API response to each individual FQDN on the order. For example, to validate the domains in the JSON payload below, add a file with a random file name that contains a random value to 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-dynamic",
      ...
  }
  

Wildcard domains only

For products that allow wildcard domain names, certificate order requests with common_name and dns_name fields containing 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 http-token-dynamic request with wildcard domain

{
    "certificate": {
        "common_name": "*.example.com",
        ...
    },
    "dcv_method": "http-token-dynamic",
    ...
}

Both wildcard and non-wildcard domains

For products that allow wildcard domain names, certificate order requests with common_name and dns_name 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.

Example http-token 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_name fields containing 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_name 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 or http-token-dynamic.¹ 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.

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:

• New domains: Add domain
• Existing domains: Submit for validation

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 or http-token-dynamic only validates the specific FQDN submitted for prevalidation.