Cycle de vie d'un certificat DV

Le cycle de vie des certificats DV se compose des étapes principales suivantes :

Préparation de la demande de certificat DV
Envoi de la commande de certificat DV
Annulation de la commande de certificat (facultatif)
Validation du contrôle de domaine (DCV)
Vérification du statut de la commande
Téléchargement du certificat émis

Une fois le certificat émis, vous pouvez exécuter les actions suivantes :

Réémettre le certificat
Révoquer le certificat

Préparation de la demande de certificat DV

Avant d’envoyer une requête de commande, vous devez recueillir certains éléments d’information clés pour créer le corps :

Nom(s) de domaine que le certificat doit protéger
Demande de signature de certificat (Certificate signing request, CSR) générée sur le serveur où le certificat sera installé.
Période de validité du certificat (durée de validité du certificat)
Méthode de validation du contrôle de domaine à utiliser pour prouver le contrôle du ou des domaine(s)

Nom(s) de domaine

Après avoir recueilli le(s) nom(s) de domaine que le certificat doit protéger, vous devez les spécifier dans l’un des deux paramètres du corps de la requête.

Paramètre	Type	Description
`common_name`	Chaîne	Domaine principal que le certificat doit protéger
`dns_names`	groupe	Domaines supplémentaires que le certificat doit protéger L’ajout de domaines à ce paramètre peut engager des coûts supplémentaires.

Toutes les commandes de ce certificat DV comprennent une fonction Plus permettant de protéger la racine et le sous-domaine « www. » de votre domaine sans coût supplémentaire. Lorsque vous créez le corps de votre requête, ajoutez le domaine de base ([votre-domaine].com) au paramètre common_name, puis l’autre version du domaine (www.[votre-domaine].com) au groupe dns_names.

Demande de signature de certificat (Certificate Signing Request, CSR)

La CSR devrait être générée sur le serveur où le certificat sera installé. Une fois la CSR générée, saisissez-la au format PEM dans le paramètre csr du corps de la requête. Pour plus de précisions, consultez la page Créer une demande de signature de certificat (Certificate Signing Request, CSR).

Période de validité

Lorsque vous commandez un certificat, vous devez spécifier sa période de validité. Pour déterminer la durée de validité d’un certificat, vous pouvez utiliser les paramètres suivants :

Paramètre	Type	Description
`validity_years`	int	Utilisez ce paramètre pour spécifier la durée de validité du certificat en années. Valeurs autorisées : `1`, `2`
`validity_days`	int	Utilisez ce paramètre pour spécifier la durée de validité du certificat en jours.
`custom_expiration_date`	Chaîne	Utilisez ce paramètre pour spécifier la date exacte à laquelle le certificat doit expirer. Format : `yyyy-MM-dd`

Si vous utilisez plus d’un paramètre de validité dans le corps de la requête, nous les présentons selon l’ordre de priorité suivant : custom_expiration_date > validity_days > validity_years.

Méthodes DCV

La validation du contrôle de domaine par courrier électronique est la méthode DCV utilisée pour les commandes de certificat DV. Si vous le souhaitez, vous pouvez changer la méthode par défaut en incluant le paramètre dcv_method dans le corps de la requête. Le paramètre dcv_method accepte les valeurs suivantes :

Valeur	Description
`email`	Envoie un courrier DCV à toutes les adresses électroniques (par ex., à l’administrateur ou aux contacts techniques) figurant dans l’enregistrement WHOIS du domaine, ainsi qu’à cinq adresses électroniques construites pour le domaine (admin, administrateur, webmaster, hostmaster et postmaster). @[domain_name]). Lorsque vous utilisez cette méthode, vous pouvez définir une étendue de diffusion spécifique en incluant l’objet `dcv_emails`.
`dns‑txt‑token`	Renvoie un jeton de valeur aléatoire dans le corps de réponse, que vous devez ajouter à l’enregistrement DNS TXT d’un domaine. L’utilisation de cette méthode requiert l’autorisation de modifier les enregistrements DNS de domaine.
`http‑token`	Renvoie un jeton de valeur aléatoire dans le corps de réponse, que vous devez placer dans un fichier .txt sur le site web que le certificat doit protéger. L’utilisation de cette méthode requiert l’autorisation d’importer des fichiers sur le serveur web.

Pour plus d’informations sur les différentes méthodes DCV et leur application, consultez la page Méthodes de validation du contrôle de domaine (Domain Control Validation, DCV).

Groupe dcv_emails (facultatif)

Lorsque vous utilisez la méthode DCV par courrier électronique, vous pouvez spécifier des adresses électroniques auxquelles envoyer les courriers DCV. Pour ce faire, il vous suffit d’inclure le groupe dcv_emails dans le corps de la requête et d’ajouter une entrée pour chaque domaine de la commande.

Lorsque vous utilisez ce paramètre, les adresses électroniques saisies doivent être spécifiées dans l’enregistrement WHOIS du domaine ou bien, l’une d’elles doit être l’adresse par défaut du domaine (définie par les normes de l’industrie : admin, administrateur, webmaster, hostmaster et/ou postmaster @[domain_name]). De plus, les courriers DCV ne sont envoyés qu’aux adresses spécifiées.

Par exemple, si vous spécifiez john.doe@,[domain_name], les courriers DCV ne seront envoyés à aucune autre adresse par défaut. De même, si vous spécifiez admin@[domaine.com,], le courrier DCV ne sera envoyé qu’à l’adresse john.doe@[domain_name].

Example dcv_emails array

"dcv_emails": [
  { 
    "dns_name": "example.com",
    "email_domain": "example.com",
    "email": "hostname@example.com"
  },
  { 
    "dns_name": "my.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  },
  { 
    "dns_name": "another.example.com",
    "email_domain": "example.com",
    "email": "admin@example.com"
  }
]

Envoi de la commande de certificat DV

Maintenant que vous avez recueillir les informations ci-dessus, vous êtes prêt à créer le corps de votre requête et à envoyer la requête de commande. 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. Le corps de la réponse inclut alors des éléments d’information clés pouvant permettre de vérifier le statut de la commande et de télécharger le certificat une fois émis.

id – ID de commande utilisé pour vérifier les détails de la commande et exécuter les actions DCV.
certificate_id – ID de certificat utilisé pour télécharger le certificat émis.
dcv_random_value – Jeton généré de manière aléatoire et utilisé avec les méthodes DCV par enregistrement DNS TXT avec jeton et HTTP avec jeton. Ce jeton expire au bout de 30 jours.

Pour plus d’informations sur chacun des paramètres utilisés dans le corps de la demande, consultez le tableau Commande de certificat DV SSL – Paramètres de demande.

cURL

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",
        "dns_names": [
            "sub.example.com",
            "app.example.com"
        ],
        "csr": "<csr>",
        "server_platform": {
            "id": 45
        },
        "signature_hash": "sha256",
        "organization_units": [
            "Accounting department"
        ]
    },
    "validity_years": 2,
    "comments": "Message for the approver",
    "disable_renewal_notifications": true,
    "dcv_method": "email",
    "locale": "en",
    "dcv_emails": [
      { 
        "dns_name": "example.com",
        "email_domain": "example.com",
        "email": "hostname@example.com"
      },
      { 
        "dns_name": "sub.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      },
      { 
        "dns_name": "app.example.com",
        "email_domain": "example.com",
        "email": "admin@example.com"
      }
    ],
    "payment_method": "balance",
    "custom_fields": [
        {
            "metadata_id": 11,
            "value": "Invoice #00001"
        }
    ]
}'

201 Created (email)

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

201 Created (dns-txt-token or http-token)

{
  "id": 112233,
  "certificate_id": 123456,
  "dcv_random_value": "icru1984rnekfj"
}

Après avoir envoyé la commande, vous pouvez appeler le point de terminaison Order info pour obtenir les détails de la commande et vérifier les informations envoyées.

Annulation de la commande de certificat (facultatif)

Après avoir passé une commande, il se pourrait que vous ayez besoin de l’annuler. Pour ce faire, vous devez remplacer le statut de la commande « en attente » par « annulée ». Cette action s’effectue en envoyant une commande PUT au point de terminaison Update order status (Mettre à jour le statut de la commande).

Si la commande PUT envoyée à ce point de terminaison aboutit, elle renvoie une réponse HTTP 204 No Content.

La paramètre status n’accepte que la valeur CANCELED (sensible à la casse).

cURL

curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/status' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
    "status": "CANCELED",
    "note": "Message about the cancellation."
}'

204 No Content

// empty

Validation du contrôle de domaine (DCV)

Une fois la commande DV envoyée, vous devez prouver que vous contrôlez les domaines associés à la commande.

Quelle que soit la méthode DCV choisie, vous devez procéder à la validation du contrôle de chaque domaine que le certificat doit protéger. Par exemple, si vous avez choisi la méthode dns-txt-token, vous devez créer un enregistrement DNS TXT pour chaque domaine de la commande.

Méthode DCV par courrier électronique

Si le corps de la réponse comporte le groupe dcv_emails, les courriers DCV sont alors envoyés aux adresses définies dans ce groupe. Les courriers DCV sont envoyés aux adresses électroniques suivantes :

Toutes les adresses électroniques figurant dans l’enregistrement WHOIS du domaine
Les cinq adresses électroniques construites suivantes :
- admin@[domain_name]
- administrateur@[domain_name]
- webmaster@[domain_name]
- hostmaster@[domain_name]
- postmaster@[domain_name]

Pour procéder à la validation du contrôle de domaine, dans votre boîte de réception, repérez le message ayant pour objet [Action Required] Approve Certificate Request for[yourdomain] {Commande n°} et suivez les instructions.

Si vous avez besoin de renvoyer les courriers DCV pour une commande envoyée, vous pouvez appeler le point de terminaison DV SSL: Resend emails (DV SSL : renvoyer les courriers). Vous devez remplacer le conteneur {{order_id}} par l’ID de commande renvoyé dans le corps de la réponse lorsque vous avez envoyé la commande.

Méthode DCV par enregistrement DNS TXT

Si vous ne disposez plus de la valeur aléatoire et que vous avez besoin d’en générer une autre, vous pouvez appeler le point de terminaison DV SSL: Generate DCV token (DV SSL : générer le jeton DCV) en remplaçant le conteneur {{order_id}} par l’ID de commande inclus dans le corps de la réponse lorsque vous avez envoyé la commande.

Pour procéder à la validation du contrôle de domaine par enregistrement DNS TXT et prouver que vous êtes le propriétaire de vos domaines, suivez la procédure ci-dessous :

Copiez la valeur dcv_random_value renvoyée dans le corps de la réponse lorsque la commande a été passée.
Accédez au site de votre fournisseur de DNS et créez un autre enregistrement TXT.
Dans le champ « TXT Value » (Valeur TXT), saisissez la valeur aléatoire copiée.
Champ « Host »
1. Domaine de base (par exemple,[yourdomain].com)
  Validez-vous le domaine de base ? Laissez le champ « Host » vide ou ajoutez le symbole @ (en fonction des exigences de votre fournisseur de DNS).
2. Sous-domaine (par exemple,[votre.domaine].com)
  Vous validez un sous-domaine ? Dans le champ « Host », ajoutez le sous-domaine que vous validez.
Dans le type de fichier d’enregistrement (ou l’équivalent), sélectionnez TXT.
Sélectionnez une valeur « Time-to-Live » (TTL) ou utilisez la valeur par défaut de votre fournisseur de DNS.
Enregistrez l’enregistrement.
Répétez les étapes ci-dessus pour chaque domaine de la commande.

Lorsque vous avez ajouté l’enregistrement DNS TXT pour tous les domaines associés à la commande, vous avez terminé et nous sommes prêts à vérifier ces enregistrements TXT (consultez la section Vérification DCV).

Méthode DCV par jeton HTTP

Pour procéder à la validation du contrôle de domaine par jeton HTTP et prouver que vous êtes le propriétaire de vos domaines, suivez la procédure ci-dessous :

Copiez la valeur dcv_random_value renvoyée dans le corps de la réponse lorsque la commande a été passée.
Dans votre éditeur de texte préféré, collez la valeur aléatoire que vous avez copiée.
Enregistrez le fichier avec le nom de fichier fileauth.txt.
Sur votre serveur, importez le fichier fileauth.txt dans l’emplacement suivant : [yourdomain]/.well-known/pki-validation/fileauth.txt.

Effectuer une vérification DCV

Une fois le jeton aléatoire ajouté à l’enregistrement DNS TXT (méthode DNS TXT) ou le fichier fileauth.txt importé dans l’emplacement spécifié (méthode DCV HTTP) pour chaque domaine de la commande, vous êtes prêt à effectuer une vérification DCV. Cette action s’effectue en envoyant une commande PUT au point de terminaison DV SSL : Check DCV (Effectuer une vérification DCV).

Une commande PUT envoyée à ce point de terminaison renvoie quatre réponses possibles :

200 OK – Vérification DCV effectuée avec succès
400 Bad Request – Cette réponse peut indiquer trois codes d’erreur possibles :
- invalid_dns_txt – L’enregistrement DNS TXT est introuvable ou contient une mauvaise valeur aléatoire pour un ou plusieurs domaines. Vérifiez que l’enregistrement DNS TXT approprié contient la bonne valeur aléatoire pour tous les domaines associés à la commande.
- file_random_value_not_found – Le fichier fileauth.txt est introuvable ou contient une mauvaise valeur aléatoire pour un ou plusieurs domaines. Pour tous les domaines associés à la commande, vérifiez que le fichier se trouve dans le bon répertoire, qu’il est accessible au public et qu’il contient la bonne valeur aléatoire.
- invalid_dns_method – La méthode DCV associée à la commande est définie sur « courrier électronique ». Accédez au message électronique envoyé et suivez les instructions DCV ou changez la méthode DCV.

cURL

curl -X PUT \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/check-dcv' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

200 OK

{
  "order_status": "pending",
  "certificate_id": 123456,
  "dcv_status": "valid"
}

400 (dns-txt-token)

{
  "errors": [
    {
      "code": "invalid_dns_txt",
      "message": "Could not find a valid TXT record for one or more domains."
    }
  ]
}

400 (http-token)

{
  "errors": [
    {
      "code": "file_random_value_not_found",
      "message": "Could not find the random value at the expected file location for one or more domains."
    }
  ]
}

400 (email)

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

Vérification du statut de la commande

Après avoir envoyé votre commande et procédé à la validation du contrôle de chaque domaine, vous souhaiterez être notifié du changement de statut de la commande et savoir quand le certificat est prêt à être téléchargé. La meilleure façon de procéder est d’envoyer une commande GET au point de terminaison Status change list (Répertorier les changements de statuts).

Une commande GET envoyée à ce point de terminaison renvoie trois réponses possibles :

200 OK (groupe orders) – Ce groupe renvoie la liste de toutes les commandes dont le statut a changé dans le délai spécifié. Lorsque le statut de votre commande passe de « en attente » à « émise », cela apparaît dans la liste. Dans le cas de plusieurs commandes, utilisez l’ID de la commande ou l’ID du certificat pour repérer la commande concernée.
200 OK (objet vide) – Une réponse indiquant un objet vide ({}) signifie qu’il n’y a pas eu de changement de statut pour aucune commande dans le délai spécifié. Prolongez le délai ou attendez l’envoi d’une prochaine requête.
400 Bad Request – Une réponse comportant le code d’erreur time_frame_too_long signifie que le délai spécifié dans la chaîne de requête de l’URL dépasse la valeur maximale. Réduisez le délai à une valeur inférieure à 10 080 minutes (7 jours).

cURL

curl -X GET \
  'https://www.digicert.com/services/v2/order/certificate/status-changes?minutes=10' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'

200 OK

{
  "orders": [
    {
      "order_id": 112233,
      "certificate_id": 123456,
      "status": "issued"
    }
  ]
}

200 OK (no orders found)

{}

400 Bad Request

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

Télécharger un certificat DV

Une fois que le statut de votre commande est passé de « en attente » à « émise », votre certificat est prêt à être téléchargé. En fonction de vos besoin, quatre points de terminaison sont disponibles pour télécharger votre certificat :

Utilisation de l’ID du certificat :
- Télécharger le certificat
- Télécharger le certificat par format
Utilisation de l’ID de la commande :
- Télécharger un certificat (order_id)
- Télécharger un certificat par format (order_id)

Réémettre un certificat DV

La réémission d’un certificat vous permet d’ajouter, de supprimer ou de changer des noms de domaine, de mettre à jour la CSR ou de changer le hachage de signature d’un certificat sans devoir envoyer une nouvelle commande. Un certificat réémis aura un nouvel ID de certificat, mais l’ID de commande demeure le même. Une fois la réémission approuvée, un nouveau certificat est émis et doit être installé.

Lorsque vous réémettez un certificat, vous devez fournir les informations suivantes :

Nom commun
Noms SAN (inclure les noms SAN actuels dans le paramètre dns_names ainsi que tous les autres noms SAN à protéger)
CSR (pour obtenir et réutiliser la CSR actuelle, appelez le point de terminaison Request info (Obtenir des informations)
ID de la plate-forme serveur (options répertoriées ici)

Même si certains des éléments d’information ci-dessus demeurent identiques, vous devez quand-même les inclure dans la requête de réémission.

Sachez que certaines modifications, telles que l’ajout de noms SAN supplémentaires (« dns_names ») peut engager des frais supplémentaires.

Il peut s’avérer nécessaire de procéder à la validation du contrôle de domaine pour tous les domaines.

Le point de terminaison Reissue certificate (Réémettre le certificat) accepte les paramètres facultatifs suivants :

comments – Ajoute un message à la demande à l’attention de l’approbateur.
skip_approval -‑ Permet d’envoyer immédiatement la demande pour validation, sans passer par l’approbation de la demande de réémission.

cURL

curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{order_id}}/reissue' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "certificate": {
    "common_name": "example.com",
    "dns_names": [
        "sub.example.com"
    ],
    "csr": "<csr>",
    "server_platform": {
      "id": 2
    },
    "signature_hash": "sha256"
    "skip_approval": true
  }
}'

201 Created

{
  "id": 112233,
  "requests": [
    {
      "id": 332211
    }
  ]
}

201 skip_approval

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

Une fois le processus de réémission terminé, vous pouvez télécharger le nouveau certificat (consultez la section Télécharger un certificat DV).

Vous pouvez consulter un historique complet des réémissions associées à une commande en appelant le point de terminaison List reissues (Répertorier les réémissions).

Révoquer un certificat DV

Une fois le certificat émis, vous pouvez envoyer une demande de révocation si nécessaire.

Toutes les demandes de révocation doivent être approuvées par un administrateur dans CertCentral avant que DigiCert puisse révoquer le certificat. Cette étape d’approbation est obligatoire est ne peut être ignorée.

Vous pouvez révoquer un certificat à l’aide de l’un des deux points de terminaison suivants :

Revoke certificate – Appelez ce point de terminaison pour révoquer un certificat spécifique à l’aide de l’ID de certificat.
Revoke order certificate – Appelez ce point de terminaison pour révoquer tous les certificats associés à un ID de commande.

Ces deux points de terminaison utilisent les mêmes paramètres dans le corps de la requête.

Après avoir envoyé la demande de révocation, celle-ci doit être approuvée par un administrateur ) à l’aide du point de terminaison Update request status (Mettre à jour le statut de la demande).

cURL

curl -X PUT \
  'https://www.digicert.com/services/v2/certificate/{{certificate_id}}/revoke' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}' \
  -d '{
  "comments": "I no longer need this cert."
}'

201 Created

{
  "id": 1,
  "date": "2016-02-10T17:06:15+00:00",
  "type": "revoke",
  "status": "pending",
  "requester": {
    "id": 14,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@digicert.com"
  },
  "comments": "I no longer need this cert."
}

Préparation de la demande de certificat DV

Nom(s) de domaine

Demande de signature de certificat (Certificate Signing Request, CSR)

Période de validité

Méthodes DCV

Groupe dcv_emails (facultatif)

Envoi de la commande de certificat DV

Annulation de la commande de certificat (facultatif)

Validation du contrôle de domaine (DCV)

Méthode DCV par courrier électronique

Méthode DCV par enregistrement DNS TXT

Méthode DCV par jeton HTTP

Effectuer une vérification DCV

Vérification du statut de la commande

Télécharger un certificat DV

Réémettre un certificat DV

Révoquer un certificat DV

À propos de