Cycle de vie d'un certificat OV/EV

Le cycle de vie des certificats OV/EV se compose des étapes principales suivantes :

  • Préparer la demande de certificat
  • Envoi de la commande de certificat
  • Annulation de la commande de certificat (facultatif)
  • Validation du contrôle de domaine (DCV)
  • Validation de l’organisation
  • 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éparer la demande de certificat

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 légal et informations de l’organisation à valider.

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.

Pour toutes les commandes OV/EV, vous pouvez ajouter gratuitement un nom SAN supplémentaire aux certificats de domaine unique. 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 OV/EV. 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-cname-token Renvoie un jeton de valeur aléatoire dans le corps de réponse, que vous devez ajouter à l’enregistrement DNS CNAME d’un domaine. L’utilisation de cette méthode requiert l’autorisation de modifier les enregistrements DNS de domaine.
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 Prouver le contrôle des domaines d’une commande de certificat en attente.

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

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 OV/EV SSL (Commander un certificat OV/EV SSL). Sachez que les produits de la gamme Secure Site se commandent via un point de terminaison distinct.

Les informations sur l’organisation et le contact sont présentés ici dans l'objet organization. Si l'organisation a déjà un identifiant attribué, vous pouvez simplement le passer avec la chaîne id au lieu de fournir les informations complètes de l'organisation.

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 requête, consultez le tableau Commande de certificat OV/EV SSL – Paramètres de requête.

cURL
curl -X POST \
  'https://www.digicert.com/services/v2/order/certificate/{{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,
    "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",
    "organization": {
        "name": "Epigyne Unwieldiness llc",
        "assumed_name": "Epigyne Unwieldiness",
        "country": "us",
        "address": "932 Prospect Street",
        "address2": "Floor 08",
        "city": "Minneapolis",
        "state": "mn",
        "zip": "40849",
        "telephone": "666-186-6450",
        "container": {
            "id": 93288
        },
        "organization_contact": {
            "first_name": "Gia",
            "last_name": "Booth",
            "job_title": "Clinical Laboratory Technician",
            "email": "gia.booth@inbox.com",
            "telephone": "666-186-6450",
            "telephone_extension": "736"
        }
    },
    "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 OV/EV 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 Resend emails (Renvoyer les courriers) en remplaçant 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 CNAME

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

  1. Copiez la valeur dcv_random_value générée lors de la passation de la commande. Pour les commandes OV/EV, vous pouvez récupérer cette valeur en utilisant le point de terminaison Informations sur le domaine et en incluant la chaîne de requête d'URL include_dcv=true.
  2. Accédez au site de votre fournisseur de DNS et créez un enregistrement CNAME.
  3. Dans le champ du nom d’hôte (ou un champ équivalent), saisissez la valeur aléatoire copiée.
  4. Dans le champ du type d’enregistrement (ou un champ équivalent), sélectionnez CNAME.
  5. Dans le champ de l’hôte cible (ou un champ équivalent), saisissez dcv.digicert.com (ceci pointe l’enregistrement CNAME vers dcv.digicert.com).
  6. Sélectionnez une valeur « Time-to-Live » (TTL) ou utilisez la valeur par défaut de votre fournisseur de DNS.
  7. Enregistrez l’enregistrement.
  8. Répétez les étapes ci-dessus pour chaque domaine de la commande.

Lorsque vous avez ajouté l’enregistrement DNS CNAME pour tous les domaines associés à la commande, vous avez terminé et nous sommes prêts à vérifier ces enregistrements CNAME.

Méthode DCV par enregistrement DNS TXT

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 :

  1. Copiez la valeur dcv_random_value générée lors de la passation de la commande. Pour les commandes OV/EV, vous pouvez récupérer cette valeur en utilisant le point de terminaison Informations sur le domaine et en incluant la chaîne de requête d'URL include_dcv=true.
  2. Accédez au site de votre fournisseur de DNS et créez un autre enregistrement TXT.
  3. Dans le champ « TXT Value » (Valeur TXT), saisissez la valeur aléatoire copiée.
  4. 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.
  5. Dans le type de fichier d’enregistrement (ou l’équivalent), sélectionnez TXT.
  6. Sélectionnez une valeur « Time-to-Live » (TTL) ou utilisez la valeur par défaut de votre fournisseur de DNS.
  7. Enregistrez l’enregistrement.
  8. 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.

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 :

  1. Dans CertCentral, copiez les informations du jeton HTTP à partir de la page « Order Detail » (Détails de la commande).
  2. Dans votre éditeur de texte préféré, collez la valeur aléatoire que vous avez copiée.
  3. Enregistrez le fichier avec le nom de fichier fileauth.txt.
  4. 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 via la page Order Detail (Détails de la commande) dans CertCentral.

Dans la section Order status (Statut de la commande) de la page, cliquez sur chaque domaine affichant « en attente de validation DCV », puis cliquez sur "Check" (Vérifier) pour vérifier la méthode DCV et la confirmer.

Validation de l’organisation

En plus de la validation du domaine, toutes les commandes OV/EV nécessitent également une validation de l'organisation. Lorsqu’une commande est envoyée, l’équipe de validation de DigiCert entame le processus de validation OV/EV de l'organisation.

La validation de l'organisation et du domaine doit être terminée avant de pouvoir émettre le certificat.

Vérification du statut de validation

Vous pouvez vérifier l’état de validation actuel d'une organisation ayant une commande GET envoyée au point de terminaison Détails de validation d'une organisation (Organization Validation details).

Si la commande GET envoyée à ce point de terminaison aboutit, elle renvoie une réponse HTTP 200 OK.

cURL
curl -X GET \
  'https://www.digicert.com/services/v2/organization/{{organization_id}}/validation' \
  -H 'Content-Type: application/json' \
  -H 'X-DC-DEVKEY: {{api_key}}'
200 OK
{
  "validations": [
    {
      "type": "ov",
      "name": "OV",
      "description": "Normal Organization Validation",
      "status": "pending"
    },
    {
      "type": "ev",
      "name": "EV",
      "description": "Extended Organization Validation (EV)",
      "status": "pending",
      "verified_users": [
        {
          "id": 12,
          "first_name": "John",
          "last_name": "Smith"
        }
      ]
    }
  ]
}

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 le certificat

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 :

Réémettre le certificat

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).

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 le certificat

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."
}