Domain control validation (DCV) methods

Every request for enrollment, renewal, reissue, and revoke goes through the domain control validation (DCV) process.

  • Email authentication
  • File-based authentication
  • DNS-based authentication

All our APIs support authentication by the more commonly-used DCV email method. Partners who have a DNS level control over their customer's domain can automate the authentication process for domain-validated products. The automation feature is available only with the DNS and file-based authentication methods.

Starting release 2017-5, we also validate all the SANs in your order along with the common name.

DCV email

Sends an approval request to a registered domain contact.

Using DCV email method

  1. Submit your API request with EMAIL authentication specified as the authentication method.
  2. DigiCert sends an email to the registered email address of the domain as listed in a WHOIS query response.
  3. The domain contact follows a link in the email and approves the order.
  4. Authentication completes when DigiCert receives the domain contact's approval.

Starting with the 2017-2 release, the email approval link is valid for 30 days. The PIN length is now 26 characters. If customers attempt to use a link sent before 2017-2, they will see an invalid PIN error. To avoid this error, resend the approval email.

File-based authentication

Validates a file on your web server to authenticate the domain. This method is available only with enrollment APIs for domain-validated products. You cannot use file-based authentication for revoke and reissue APIs. To enable file-based authentication, contact the API support team or your sales engineer.

Server Name Indication (SNI) is supported during file-based authentication. File-based authentication uses a random number for completing the authentication and does not support the preshared key authentication method.

File-based authentication does not work with TLS 1.0. Your site must support TLS 1.1 or TLS 1.2 for this method to work.

Using file-based authentication

  1. Submit your API request with FILE authentication specified as the authentication method. The API response includes details of the authentication file.
  2. Create a .txt file from the authentication file details in the response.
    Note: Use the file content from the API response to make the fileauth.txt file. Do not generate your own file content. For multiple orders, separate each random string code with a line break, being careful not to break any of the 64-character random strings. Up to 31 separate orders (2048 characters) can be authenticated at once in the txt file.
  3. Place the .txt file at the root domain of the common name and all SANs, under .well-known/pki-validation (e.g., https://<CN>/.well-known/pki-validation/fileauth.txt or http://<CN>/.well-known/pki-validation/fileauth.txt). Complete this step immediately after submitting your API request for faster authentication.
  4. After placing the file, try to open the file in a browser using the URL to the file. Example: https://<CN or SAN>/.well-known/pki-validation/fileauth.txt or http://<CN or SAN>/.well-known/pki-validation/fileauth.txt. The file contents should be accessible through these URLs publicly on HTTP port 80 or HTTPS port 443.
  5. DigiCert polls port 80 and port 443 on the domain for the authentication file. DigiCert polls the HTTP location first, then the HTTPS location if necessary. Polling continues until the file is found, the order is moved to a different state, or more than 30 days have passed. Redirecting to other files, domains, or ports is not supported. If the polling is not successful within 30 days of placing the order, you must place a new order.
  6. Authentication completes when DigiCert finds the file and verifies its contents.

Starting release 2017-7, you must place the fileauth.txt file on both the domain in your order and the domain added for free with your order. For example, if you orderwww.domain.com and get domain.com for free, you must place the secret pin in two places. Namely: http://www.domain.com/well-known/pki-validation/fileauth.txt and http://domain.com/well-known/pki-validation/fileauth.txt

Fileauth.txt sample contents

File authentication for two orders on http(s)://<domain>/.well-known/pki-validation/fileauth.txt:

java
20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y
20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y

DNS-based authentication

Validates a DNS entry to authenticate the domain. DNS-based authentication is available for enroll, reissue, renewal, and revoke actions. For enroll, renew, reissue, and revoke DNS-based authentication is available for DV, OV, and EV products. Contact the API support team or your sales engineer to enable DNS-based authentication for your account. DNS-based authentication is not available for code-signing certificates.

DNS authentication methods:

  • Preshared key - Using a preshared key lets you generate a shared secret and include it in a new or an existing TXT record on the requested domain(s) (CN and SANs). Enroll, renew, and reissue requests use the CSR and a time in the order window (7 days before the order date to the time when the order was placed) to generate the shared secret. Revoke requests use the certificate instead of the CSR in the secret code generation process. This method is faster because you can generate the DNS entry before you submit your request. Your shared key for Partner API requests cannot be used with Encryption Everywhere API requests.
    Note: With preshared key DNS authentication, the API does not return the DNS entry.
  • Random string - If you do not have a preshared key, QuickOrder returns a random string. Create the TXT record on the requested domain immediately after placing the order and getting the DNS entry values from the response.

The DNS entry is a TXT record on the requested domain. You can update an existing TXT record or create a new one. The content of TXT record is generated using a shared secret or a random string. The format of this entry is <yyyyMMddHHmmss><secret code>.

In the case of multiple orders, you can add many 64-character <yyyyMMddHHmmss><secret code> entries to the TXT record. Separate each entry with a line break, being careful not to break the 64-character strings.

yyyyMMddHHmmss is a time within the order window (7 days before the order date to the time when the order was placed) and <secret code> is a HMACSHA2 hash of <yyyyMMddHHmmss><CSR> using the shared key.

Example TXT record (new record)

If the domain does not have a DNS TXT record, create one.

java
auth.scan-test.net.     3600    IN      TXT     
"20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y
20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y"

Example TXT record (update existing record)

If the domain already has a DNS TXT record, update it with the <yyyyMMddHHmmss><secret code> combination for each order you want to verify.

java
auth.scan-test.net.     3600    IN      TXT     
"purpose=something mx a:mail.scan-test.net  include:servers.scan-test.net ~all
20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y
20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y"

Troubleshooting DNS authentication issues

If you face an issue where CNAME and TXT records cannot be created on the same domain, contact DigiCert to turn on the authorized domain name prefix feature for your account. Once this feature is turned on, add the _dnsauth prefix to all of your TXT record entries for DNS authentication.

java
_dnsauth.auth.scan-test.net. 3600 IN TXT
"20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y
20170222202651ztkf61glu4h63r88opc9g1n5y5hveqf8r2t7cwuxugdiu72x1y"

Using DNS-based authentication

  1. Plan the order placement time and the DNS entry time in advance. Ensure that the date in the DNS entry is in the order window (7 days before the order date to the time when the order was placed).
  2. Get the DNS entry and create or update a TXT record on the domain and all SANs with the correct content format. (For string DNS authentication, do this step after you submit your request).
    Note: If your order contains a domain name in the format www.<domain_name>.com, we check for the TXT record on <domain_name>.com and not on www.<domain_name>.com. During authentication, our systems treat both these values as separate entities. After <domain_name>.com is successfully authenticated, we can issue you certificates for both <domain_name>.com and www.<domain_name>.com.
  3. Test the TXT record using the UNIX dig <sub-domain> txt command and verify that the entry is correct. The TXT record should contain <yyyyMMddHHmmss><secret code> for each order being verified.
  4. Submit your request with DNS authentication specified.
  5. DigiCert polls the domain for the DNS entry up to 30 days after the order was placed.
  6. Authentication completes when DigiCert finds the entry.

We use cookies to ensure that we give you the best experience on our website. By using this site, you agree to the Terms of Service.