Émission immédiate d'un certificat DV

Lorsque vous commandez des certificats DV à l’aide de l’API, l’émission du certificat prend souvent beaucoup de temps. En suivant les étapes de ce guide consacré aux workflows, vous pourrez tirer parti de notre fonctionnalité d’émission instantanée de certificats DV. Elle vous permettra d’obtenir votre certificat DV immédiatement tout en réduisant vos appels d’API jusqu’à 70 %.

Pour demander des certificats DV Encryption Everywhere, suivez la procédure suivante et configurez une clé d'authentification pour votre compte. À défaut, vous recevrez une erreur auth_key_not_setup lors de l'introduction de la requête.

Aperçu

Pour que les certificats puissent être émis immédiatement, vous devez suivre la procédure avant de soumettre votre commande de certificat DV :

  1. Créez une clé d’authentification pour votre compte CertCentral.
  2. Générez une Demande de signature de certificat (Certificate Signing Request, CSR) pour la commande de certificat DV.
  3. Créez un horodatage pour déterminer la période de validité du jeton de demande.
  4. Construisez un jeton de demande en utilisant votre clé d'authentification et votre CSR.
  5. Ajoutez le jeton de demande généré au domaine à sécuriser par le certificat DV.
  6. Envoyez votre commande de certificat DV.

Une fois ces étapes terminées lorsque vous soumettez votre commande de certificat DV, nous vous émettons immédiatement votre certificat DV et le renvoyons au corps de la réponse. Si l’une ou l’autre de ces étapes préalables n’est pas remplie, l’émission instantanée ne peut avoir lieu.

Étape 1 : Créer une clé d'authentification

Vous devez d'abord créer une clé d'authentification pour votre compte CertCentral. Vous utiliserez cette clé pour générer un jeton de demande afin de prouver que vous contrôlez le domaine. Vous pouvez créer une clé d'authentification en envoyant une commande POST vers le point de terminaison Create AuthKey (Créer une clé d'authentification).

Si la commande POST envoyée à ce point de terminaison aboutit, elle renvoie une réponse HTTP 200 OK. Le corps de la réponse inclut deux éléments d'information clés :

  • auth_key_id – ID unique de la clé d’authentification créée
  • auth_key – Clé d’authentification générée pour votre compte CertCentral.

Vous ne pouvez créer qu'une seule clé d'authentification pour votre compte CertCentral. Si votre compte possède déjà une clé d'authentification, le point de terminaison Create AuthKey (Créer une clé d'authentification) renvoie une réponse HTTP 400 Bad Request avec l'erreur auth_key_exists_for_account. Si vous rencontrez cette erreur, vous pouvez utiliser le point de terminaison AuthKey details (Détails de la clé d'authentification) pour obtenir votre clé d'authentification existante.

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_id": "{{auth_key_id}}",
  "auth_key": "{{auth_key}}"
}
400 Bad Request
{
  "errors": [
    {
      "code": "auth_key_exists_for_account",
      "message": "An error occurred while processing your request."
    }
  ]
}

Étape 2 : Générez une demande de signature de certificat (CSR)

Après avoir obtenu la clé d'authentification pour votre compte, vous devez créer un CSR pour la commande de certificat. Vous aurez besoin du CSR pour générer un jeton de demande. Assurez-vous de générer votre CSR sur le serveur où le certificat sera installé.

Besoin d’aide pour créer une CSR ? Consultez la page Créer une demande de signature de certificat (Certificate Signing Request, CSR).

Étape 3 : Créez un horodatage

L'horodatage détermine le début de la période de validité de 30 jours du jeton de demande. Lorsque vous créez un horodatage, assurez-vous que la fenêtre de validité résultante coïncide avec la date à laquelle vous soumettrez votre commande de certificat DV. Si votre commande est soumise avant ou après la fenêtre de validité, l’émission instantanée ne peut avoir lieu.

Vous pouvez créer un horodatage pour une date ultérieure. Ne soumettez toutefois pas la commande de certificat DV avant cette date. Le jeton de demande n'étant pas encore "valide", il ne peut pas être utilisé pour valider le domaine.

Une fois que vous avez déterminé le moment où la fenêtre de validité du jeton de demande doit commencer, vous devez formater l'horodatage comme indiqué ci-dessous :

generic
yyyyMMddhhmmss

Par exemple, October 21, 2019 1:30:12 PM deviendrait 20191021133012.

Étape 4 : Générer un jeton de demande

Les jetons de demande ont une validité de 30 jours déterminée par les données figurant dans l'horodatage. Lorsque vous générez un jeton de demande, assurez-vous que votre fenêtre d'horodatage de 30 jours coïncide avec le moment où vous soumettrez votre commande de certificat.

Une fois que vous avez votre clé d'authentification, votre CSR et votre horodatage, vous êtes prêt à générer un jeton de demande utilisé pour prouver le contrôle du domaine. Ce jeton de demande vous permet de configurer l'enregistrement DNS TXT ou le fichier fileauth.txt de votre domaine avant de passer une commande de certificat.

Comment générer votre jeton de demande

  1. Construisez le secret à hacher en préfixant l'horodatage de votre CSR au format PEM.
  2. Hachez le secret en utilisant HMAC-SHA256 avec votre clé d'authentification comme clé.
  3. Convertissez le hachage hexadécimal résultant en une valeur de hachage décimale (base10).
  4. Convertissez la valeur de hachage décimale en une valeur de hachage de base36.
  5. Assurez-vous que la valeur de hachage de base36 comporte au moins 50 caractères. Si ce n'est pas le cas, ajoutez des zéros (0) jusqu'à avoir 50 caractères.
  6. Construisez le jeton de demande finale en préfixant l'horodatage à la valeur de hachage de base36.

L'exemple de pseudo-code suivant explique comment procéder pour générer un jeton de demande :

generic
# 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

Étape 5 : Placez le jeton de demande

Pour l’émission instantanée d'un certificat DV, vous devez placer le jeton de demande à l'un de ces endroits avant de commander le certificat :

  • Dans le DNS du domaine comme un enregistrement TXT.
  • Dans un fichier fileauth.txt à un endroit prédéterminé sur votre site web.

Une fois que le jeton de demande est placé, vous pouvez soumettre votre commande de certificat DV.

DNS TXT

Vous pouvez démontrer que vous contrôlez les domaines dans votre commande de certificat DV en créant un enregistrement DNS TXT contenant le jeton de demande. Une fois que l'enregistrement DNS TXT est créé, vous pouvez demander votre certificat DV.

Assurez-vous de définir la valeur dcv_method à dns-txt-token lorsque vous utilisez l’enregistrement DNS TXT pour votre jeton de demande.

  1. Accédez au site de votre fournisseur de DNS et créez un autre enregistrement TXT.

  2. Dans le champ Valeur TXT, collez le jeton de demande.

  3. Suivant la commande de votre certificat et le domaine à protéger, choisissez l’une des procédures suivantes pour le champ Host (Hôte) :

    • Domaine de base (par ex., exemple.com)
      Laissez ce champs vide ou ajoutez le symbole @ (en fonction des exigences de votre fournisseur de DNS)
    • Sous-domaines
      Saisissez le sous-domaine qui doit être sécurisé par le certificat.
    • Autorisation concernant le nom de domaine
      Saisissez _dnsauth.
  4. Dans le champ du type d’enregistrement (ou un champ équivalent), sélectionnez TXT.

  5. Sélectionnez une valeur « Time-to-Live » (TTL) ou utilisez la valeur par défaut de votre fournisseur de DNS.

  6. Enregistrez l’enregistrement.

  7. Envoyez votre commande de certificat DV, en vous assurant de définir le dcv_method à dns-txt-token.

File Auth

Vous pouvez démontrer que vous contrôlez les domaines dans votre commande de certificat DV en hébergeant un fichier fileauth.txt contenant le jeton de demande à un endroit prédéterminé sur votre site web. Assurez-vous d’éviter les erreurs les plus courantes lors de l'utilisation de File Auth.

Une fois que le dossier est disponible sur votre site web, vous pouvez demander votre certificat DV.

Assurez-vous de définir la valeur dcv_method à http-token lorsque vous utilisez File Auth pour votre jeton de demande.

  1. Ouvrez un éditeur de texte (par exemple le Bloc-note Windows) et collez-y votre jeton de demande.

  2. Enregistrez le fichier sous le nom de fileauth.txt.

  3. Ce fichier doit être accessible sur votre site web à l’endroit suivant (créez des répertoires si nécessaire) :

    http://[domain.name]/.well-known/pki-validation/fileauth.txt

Sur les serveurs sous Windows, ce répertoire .well-known doit être créé en ligne de commande : mkdir .well-known

  1. Envoyez votre commande de certificat DV, en vous assurant de définir le dcv_method à http-token.

Étape 6 : Envoi de la commande de certificat DV

Une fois que vous avez placé le jeton de demande, vous êtes prêt à soumettre votre demande de commande de certificat DV. Cette action s’effectue en envoyant une commande POST au point de terminaison Order DV SSL (Commander un certificat DV SSL).

Une commande POST envoyée à ce point de terminaison renvoie un code de réponse HHTP 201 Created. Si toutes les conditions d’émission instantanée sont remplies, toute la chaîne du certificat est renvoyée dans le corps de la réponse.

Lorsque vous passez votre commande de certificat DV, assurez-vous que la valeur dcv_method correspond à l'emplacement du jeton de demande.

Si l’une ou l’autre de ces conditions préalables n’est pas remplie, l’émission instantanée ne peut avoir lieu. Au lieu de recevoir la chaîne complète de certificats, vous recevrez le corps de réponse standard pour Commander un certificat SSL DV.

cURL (DNS 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
        }
    },
    "validity_years": 1,
    "dcv_method": "dns-txt-token"
}'
cURL (File Auth)
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
        }
    },
    "validity_years": 1,
    "dcv_method": "http-token"
}'
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>"
    }
  ]
}