Le cycle de vie des certificats DV se compose des étapes principales suivantes :
Une fois le certificat émis, vous pouvez exécuter les actions suivantes :
Avant d’envoyer une requête de commande, vous devez recueillir certains éléments d’information clés pour créer le corps :
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
.
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).
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
.
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).
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].
"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"
}
]
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 -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"
}
]
}'
{
"id": 112233,
"certificate_id": 123456
}
{
"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.
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 -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."
}'
// empty
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.
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 :
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.
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 :
dcv_random_value
renvoyée dans le corps de la réponse lorsque la commande a été passée.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).
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 :
dcv_random_value
renvoyée dans le corps de la réponse lorsque la commande a été passée.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 :
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 -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}}'
{
"order_status": "pending",
"certificate_id": 123456,
"dcv_status": "valid"
}
{
"errors": [
{
"code": "invalid_dns_txt",
"message": "Could not find a valid TXT record for one or more domains."
}
]
}
{
"errors": [
{
"code": "file_random_value_not_found",
"message": "Could not find the random value at the expected file location for one or more domains."
}
]
}
{
"errors": [
{
"code": "invalid_dns_method",
"message": "An error occurred while processing your request."
}
]
}
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 :
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.{}
) 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.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 -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}}'
{
"orders": [
{
"order_id": 112233,
"certificate_id": 123456,
"status": "issued"
}
]
}
{}
{
"errors": [
{
"code": "time_frame_too_long",
"message": "An error occurred while processing your request."
}
]
}
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 :
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 :
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 :
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
}
}'
{
"id": 112233,
"requests": [
{
"id": 332211
}
]
}
{
"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).
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 :
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 -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."
}'
{
"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."
}