DV certificate immediate issuance

When using the API to order your DV certificates, too often time is spent just waiting for the certificate to be issued. By following the steps in this workflow guide, you’ll be able to take advantage of our DV certificate immediate issuance feature, allowing you to get your DV certificate issued immediately and reduce your API calls.

Overview

In order to take advantage of immediate issuance, you must complete these steps before submitting your DV certificate order:

1. Create an AuthKey for your CertCentral account.
2. Generate a certificate signing request (CSR) for the DV certificate order.
3. Create a timestamp to define the request token validity period.
4. Construct a request token using your AuthKey and CSR.
5. Place the generated request token at the required location for the domain to be secured by the DV certificate.
6. Submit the DV certificate order.

If all these steps are complete when you submit your DV certificate order, we immediately issue your DV certificate and return it in the response body. If any of these steps are skipped, DigiCert cannot immediately issue the certificate.

Step 1: Create an AuthKey

First, you need to create an AuthKey for your CertCentral account. You will use this key to generate a request token for proving control over the domain. Additionally, you can create multiple AuthKeys with a defined validity period, often referred to as Time-to-Live (TTL) AuthKeys. It is possible to create multiple such AuthKeys, with a minimum validity of 1 day and no upper limit on the maximum duration. You can create an AuthKey or multiple AuthKeys by using the Create AuthKey endpoint.

A successful POST to this endpoint returns a 200 OK HTTP response. The response body includes two key pieces of information:

• auth_key_id: Unique ID of the created AuthKey.
• auth_key: Generated AuthKey for your CertCentral account.

Create an AuthKey (cURL)

curl -X POST \
  https://www.digicert.com/services/v2/account/auth-key \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

• 200 OK (Auth key details)
• 400 Bad Request

{
  "auth_key_id": "{{auth_key_id}}",
  "auth_key": "{{auth_key}}"
}

{
  "errors": [
    {
      "code": "auth_key_exists_for_account",
      "message": "An error occurred while processing your request."
    }
  ]
}

Step 2: Generate a certificate signing request (CSR)

Once you have the AuthKey for your account, the next step is to create a CSR for the certificate order. You’ll need the CSR to generate a request token. Make sure to generate your CSR on the server where the certificate will be installed.

Step 3: Create a timestamp

The timestamp determines the starting date and time (UTC) of the 30-day validity period for the request token. When creating a timestamp, make sure the resulting validity window coincides with when you will submit your DV certificate order. If your order is submitted before or after the validity window, immediate issuance cannot happen.

After determining when the request token’s validity window should start, you need to format the timestamp as shown below:

yyyyMMddhhmmss

For example, October 21, 2019 1:30:12 PM would become 20191021133012.

Step 4: Generate a request token

Now that you have your AuthKey, CSR, and timestamp, you’re ready to generate a request token used to prove control over the domain. This request token allows you to set up your domain’s DNS TXT record or fileauth.txt file before placing a certificate order.

How to generate your request token

1. Construct the secret to be hashed by prepending the timestamp to your PEM-formatted CSR.
2. Hash the secret using HMAC-SHA256 with your AuthKey as the key.
3. Convert the resulting hexadecimal hash to a decimal (base10) hash value.
4. Convert the decimal hash value to a base36 hash value.
5. Make sure the base36 hash value is at least 50 characters long. If not, prepend with zeros (0) until it is 50 characters long.
6. Construct the final request token by prepending the timestamp to the base36 hash value.

This example pseudo-code shows how to use the above steps to generate a request token:

# Declare AuthKey, CSR, and timestamp
auth_key = 'certcentral_account_auth_key'
csr = 'pem_formatted_csr'
timestamp = 'yyyyMMddhhmmss'

# Construct secret to be hashed
secret = timestamp + csr

# Hash secret using HMAC-SHA256 and auth_key
hash = hmac.sha256(secret, auth_key)

# Convert hexadecimal hash to decimal
decimal_hash = convertToBase10(hash)

# Convert decimal_hash to base36
base36_hash = convertToBase36(decimal_hash)

# If base36_hash length is < 50, prepend with zeros
valid_hash = base36_hash.padStart(50, '0')

# Construct final request token
request_token = timestamp + valid_hash

Step 5: Place request token

For DV certificate immediate issuance, based on the DCV method you use, place the request token in one of these places before you order the certificate:

• In the domain’s DNS as a TXT record.
• In a fileauth.txt file at a predetermined location on your website.

Once the request token is placed, you can submit your DV certificate order. -

For information about supported DCV methods, see DCV Methods. Key DCV related tasks you can perform with CertCentral APIs:

• For viewing the available DCV methods for a domain, see List DCV methods.
• For checking DCV status, see Validation details.
• For generating domain DCV random value, see DV SSL: Generate DCV token.
• For completing http-token DCV, see File-based domain control validation (http-token).

DNS TXT

You can demonstrate control over a domain on your DV certificate order by creating a DNS TXT record containing the request token. Once the DNS TXT record is created, you can request your DV certificate.

1. Go to your DNS provider’s site and create a new TXT record.
2. In the TXT Value field, paste the request token.
3. Depending on your certificate order and domain to be secured, do one of these for the Host field:
   • Base domain (e.g., example.com) Leave blank or enter @ symbol (depending on your DNS requirements).
   • Subdomain Enter the subdomain to be secured by the certificate.
   • Authorization Domain Name Enter _dnsauth.
4. In the record type field (or equivalent), select TXT.
5. Select a Time-to-Live (TTL) value or use your DNS provider’s default value.
6. Save the record.
7. Submit your certificate order, making sure to set the dcv_method to dns-txt-token.

File Auth

You can demonstrate control over a domain on your DV certificate order by hosting a fileauth.txt file containing the request token at a predetermined location on your website. Make sure to avoid the common mistakes while using File Auth. For more information, see Common mistakes: HTTP practical demonstration DCV method.

Once the file is available on your website, you can request your DV certificate.

1. Open a text editor (such as Notepad) and paste in the request token.
2. Save the file as fileauth.txt.
3. Make the file available on your website at this location (create directories as needed): http://``[domain.name]``/.well-known/pki-validation/fileauth.txt
   On Windows-based servers, the .well-known folder must be created via command line: mkdir .well-known
4. Submit your certificate order, making sure to set the dcv_method to http-token.

Step 6: Submit DV certificate order

Once you’ve placed the request token, you’re ready to submit your DV certificate order request. This is done with a POST to the Order DV SSL endpoint.

In the JSON request body:

• Include "use_auth_key": true in the request body.
  For Encryption Everywhere DV certificates, the use_auth_key parameter is ignored. When requesting an Encryption Everywhere certificate, if an AuthKey exists for the account, DigiCert always checks the DNS records for an AuthKey request token. If no AuthKey exists for the account, or if DigiCert doesn’t find a valid AuthKey request token for one or more domains on the order, the API returns an error.
• Set the dcv_method parameter to the method you used to place the AuthKey request token.

A successful POST to this endpoint returns a 201 Created HTTP response code. If all immediate issuance requirements are met, the full certificate chain is returned in the response body.

• cURL (DNS TXT)
• cURL (File Auth)
• cURL (Token based)
• cURL (Persistent Txt)

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "order_validity": {
        "years": 1
    },
    "dcv_method": "dns-txt-token",
    "use_auth_key": true,
    "auth_key_id": "{auth_key_id}",    
    "skip_approval": true
}'

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "order_validity": {
        "years": 1
    },
    "dcv_method": "http-token",
    "use_auth_key": true,
    "auth_key_id": "{auth_key_id}",    
    "skip_approval": true
}'

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "order_validity": {
        "years": 1
    },
    "dcv_method": "token-based",
    "use_auth_key": true,
    "auth_key_id": "{auth_key_id}",    
    "skip_approval": true
}'

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{dv_ssl_certificate_id}}' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "certificate": {
        "common_name": "example.com",
        "csr": "<csr>",
        "server_platform": {
            "id": 2
        }
    },
    "order_validity": {
        "years": 1
    },
    "dcv_method": "persistent-txt",
    "skip_approval": true
}'

201 Created

{
  "id": 112339,
  "certificate_id": 132345,
  "certificate_chain": [
    {
      "subject_common_name": "example.com",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert SHA2 Secure Server CA",
      "pem": "<pem_certificate>"
    },
    {
      "subject_common_name": "DigiCert Global Root CA",
      "pem": "<pem_certificate>"
    }
  ]
}

What if DigiCert can’t immediately issue the certificate?

If DigiCert cannot complete domain control validation (DCV) for one or more domains on the order, the API returns an error. Verify that the AuthKey request token is valid and placed at the correct location for each domain, and then submit the order again.

If it takes longer than expected to process the certificate request, the API returns the standard response for DV orders created in a pending state, omitting the certificate_chain:

{ 
  "id": 112233,
  "certificate_id": 113
}

To prevent failures caused by issuance delays, design your integration to account for the possibility of a pending order response.

When the API returns the response for a pending order, use one of these these methods to find out when the certificate is ready to download:

• Subscribe to CertCentral webhooks (recommended).
• Poll the Status change list API endpoint.

Then, when the order status becomes issued, download the certificate:

• Using certificate ID Download certificate or Download certificate by format
• Using order ID Download certificate (order_id) or Download certificate by format (order_id)