Aller au contenu principal

7. Gestion des certificats

Dans cette section, nous décrivons les fonctionnalités de gestion des certificats activées par ACME :

  • Création de compte (Account Creation)
  • Commande d'un certificat (Ordering a Certificate)
  • Autorisation d'identifiant (Identifier Authorization)
  • Délivrance de certificat (Certificate Issuance)
  • Révocation de certificat (Certificate Revocation)

7.1. Ressources​

ACME est construit comme une application basée sur HTTP, avec les types de ressources suivants :

  • Ressources de compte (Account Resources), représentant les informations sur un compte (sections 7.1.2, 7.3)
  • Ressources de commande (Order Resources), représentant les demandes de délivrance de certificat d'un compte (section 7.1.3)
  • Ressources d'autorisation (Authorization Resources), représentant l'autorisation d'un compte à agir sur un identifiant (section 7.1.4)
  • Ressources de défi (Challenge Resources), représentant les défis pour prouver le contrôle d'un identifiant (sections 7.5, 8)
  • Ressources de certificat (Certificate Resources), représentant les certificats délivrés (section 7.4.2)
  • La ressource « directory » (section 7.1.1)
  • La ressource « newNonce » (section 7.2)
  • La ressource « newAccount » (section 7.3)
  • La ressource « newOrder » (section 7.4)
  • La ressource « revokeCert » (section 7.6)
  • La ressource « keyChange » (section 7.3.5)

Le serveur DOIT fournir les ressources « directory » et « newNonce ».

ACME utilise des URL différentes pour différentes fonctions de gestion. Chaque fonction est répertoriée dans le répertoire avec son URL correspondante, de sorte que les clients n'ont besoin de configurer que l'URL du répertoire. Ces URL sont reliées par plusieurs relations de lien différentes [RFC8288].

La relation de lien « up » est utilisée avec les ressources de défi pour indiquer la ressource d'autorisation à laquelle appartient le défi. Pour certains types de médias, elle est également utilisée depuis les ressources de certificat pour indiquer la ressource à partir de laquelle le client peut obtenir la chaîne de certificats CA pouvant être utilisée pour valider le certificat dans la ressource d'origine.

La relation de lien « index » apparaît sur toutes les ressources sauf le répertoire et indique l'URL du répertoire.

Le diagramme suivant illustre les relations entre les ressources sur un serveur ACME. Dans la plupart des cas, ces relations sont représentées par des URL fournies sous forme de chaînes dans la représentation JSON des ressources. Les lignes avec des étiquettes entre guillemets représentent des relations de lien HTTP.

                              directory
                                  |
                                  +--> newNonce
                                  |
      +----------+----------+-----+-----+------------+
      |          |          |           |            |
      |          |          |           |            |
      V          V          V           V            V
 newAccount   newAuthz   newOrder   revokeCert   keyChange
      |          |          |
      |          |          |
      V          |          V
   account       |        order --+--> finalize
                 |          |     |
                 |          |     +--> cert
                 |          V
                 +---> authorization
                           | ^
                           | | "up"
                           V |
                         challenge

                 ACME Resources and Relationships

Le tableau suivant illustre la séquence typique de requêtes nécessaires pour établir un nouveau compte auprès du serveur, prouver le contrôle d'un identifiant, délivrer un certificat et obtenir un certificat mis à jour quelque temps après la délivrance. « -> » est un mnémonique pour le champ d'en-tête Location pointant vers la ressource créée.

OpérationRequêteRéponse
Obtenir le répertoireGET directory200
Obtenir un nonceHEAD newNonce200
Créer un comptePOST newAccount201 -> account
Soumettre une commandePOST newOrder201 -> order
Récupérer les défisPOST-as-GET order's authorization urls200
Répondre aux défisPOST authorization challenge urls200
Interroger le statutPOST-as-GET order200
Finaliser la commandePOST order's finalize url200
Interroger le statutPOST-as-GET order200
Télécharger le certificatPOST-as-GET order's certificate url200

Le reste de cette section fournit des détails sur la façon dont ces ressources sont construites et comment le protocole ACME les utilise.

7.1.1. Répertoire (Directory)​

Pour aider les clients à configurer les URL correctes pour chaque opération ACME, le serveur ACME fournit un objet répertoire. Cela devrait être la seule URL nécessaire pour configurer un client. C'est un objet JSON dont les noms de champs proviennent du registre des ressources (section 9.7.5) et dont les valeurs sont les URL correspondantes.

ChampURL dans la valeur
newNonceNouveau nonce
newAccountNouveau compte
newOrderNouvelle commande
newAuthzNouvelle autorisation
revokeCertRévocation de certificat
keyChangeChangement de clé

L'URL du répertoire n'est soumise à aucune contrainte, sauf qu'elle devrait être différente des URL des autres ressources du serveur ACME et ne devrait pas entrer en conflit avec d'autres services. Par exemple :

  • Un hôte servant à la fois de serveur ACME et de serveur Web peut souhaiter réserver le chemin racine « / » pour la « page d'accueil » HTML et placer le répertoire ACME sous le chemin « /acme ».
  • Un hôte servant uniquement de serveur ACME peut placer le répertoire sous le chemin « / ».

Si le serveur ACME n'implémente pas la pré-autorisation (Pre-authorization) (section 7.4.1), il DOIT omettre le champ « newAuthz » du répertoire.

L'objet PEUT également contenir un champ « meta ». S'il est présent, il DOIT être un objet JSON ; chaque champ de l'objet est un élément de métadonnées lié au service fourni par le serveur ACME.

Les éléments de métadonnées suivants sont définis (section 9.7.6), tous OPTIONNELS :

termsOfService (optionnel, chaîne) : URL identifiant les conditions d'utilisation actuelles.

website (optionnel, chaîne) : URL HTTP ou HTTPS localisant un site Web fournissant plus d'informations sur le serveur ACME.

caaIdentities (optionnel, tableau de chaînes) : Noms d'hôtes que le serveur ACME reconnaît comme se référant à lui-même, à des fins de validation des enregistrements CAA tels que définis dans [RFC6844]. Chaque chaîne DOIT représenter la même séquence de points de code ASCII que le « nom de domaine de l'émetteur » (Issuer Domain Name) que le serveur s'attend à voir dans les étiquettes d'attribut CAA issue ou issuewild. Cela permet aux clients de déterminer le nom de domaine d'émetteur correct à utiliser lors de la configuration des enregistrements CAA.

externalAccountRequired (optionnel, booléen) : Si ce champ est présent et défini à « true », la CA exige que toutes les requêtes newAccount incluent un champ « externalAccountBinding » associant le nouveau compte à un compte externe.

Les clients accèdent au répertoire en envoyant une requête GET à l'URL du répertoire.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "newNonce": "https://example.com/acme/new-nonce",
  "newAccount": "https://example.com/acme/new-account",
  "newOrder": "https://example.com/acme/new-order",
  "newAuthz": "https://example.com/acme/new-authz",
  "revokeCert": "https://example.com/acme/revoke-cert",
  "keyChange": "https://example.com/acme/key-change",
  "meta": {
    "termsOfService": "https://example.com/acme/terms/2017-5-30",
    "website": "https://www.example.com/",
    "caaIdentities": ["example.com"],
    "externalAccountRequired": false
  }
}

7.1.2. Objets de compte (Account Objects)​

Une ressource de compte ACME représente un ensemble de métadonnées associées à un compte. La ressource de compte a la structure suivante :

status (requis, chaîne) : Le statut de ce compte. Les valeurs possibles sont « valid », « deactivated » et « revoked ». La valeur « deactivated » devrait être utilisée pour indiquer une désactivation initiée par le client, tandis que « revoked » devrait être utilisée pour indiquer une désactivation initiée par le serveur. Voir section 7.1.6.

contact (optionnel, tableau de chaînes) : Tableau d'URL que le serveur peut utiliser pour contacter le client concernant des problèmes liés à ce compte. Par exemple, le serveur peut souhaiter informer le client d'une révocation initiée par le serveur ou de l'expiration d'un certificat. Voir section 7.3 pour les informations sur les schémas d'URL pris en charge.

termsOfServiceAgreed (optionnel, booléen) : L'inclusion de ce champ avec la valeur true dans une requête newAccount indique que le client accepte les conditions d'utilisation. Ce champ ne peut pas être mis à jour par le client.

externalAccountBinding (optionnel, objet) : L'inclusion de ce champ dans une requête newAccount indique que le titulaire d'un compte non-ACME existant approuve la liaison de ce compte à ce compte ACME. Ce champ ne peut pas être mis à jour par le client (voir section 7.3.4).

orders (requis, chaîne) : URL à partir de laquelle une liste des commandes soumises par ce compte peut être récupérée via une requête POST-as-GET, comme décrit à la section 7.1.2.1.

{
  "status": "valid",
  "contact": [
    "mailto:[email protected]",
    "mailto:[email protected]"
  ],
  "termsOfServiceAgreed": true,
  "orders": "https://example.com/acme/orders/rzGoeA"
}

7.1.2.1. Liste des commandes (Orders List)​

Chaque objet de compte contient une URL « orders » à partir de laquelle une liste des commandes créées par le compte peut être récupérée via une requête POST-as-GET. Le résultat de la requête DOIT être un objet JSON dont le champ « orders » est un tableau d'URL, chacune identifiant une commande appartenant à ce compte. Le serveur DEVRAIT inclure les commandes en attente et NE DEVRAIT PAS inclure les commandes invalides dans le tableau d'URL. Le serveur PEUT retourner une liste incomplète, ainsi qu'un champ d'en-tête Link avec une relation de lien « next » indiquant où d'autres entrées peuvent être récupérées.

HTTP/1.1 200 OK
Content-Type: application/json
Link: `https://example.com/acme/directory`;rel="index"
Link: `https://example.com/acme/orders/rzGoeA?cursor=2`;rel="next"

{
  "orders": [
    "https://example.com/acme/order/TOlocE8rfgo",
    "https://example.com/acme/order/4E16bbL5iSw",
    /* more URLs not shown for brevity */
    "https://example.com/acme/order/neBHYLfw0mg"
  ]
}

7.1.3. Objets de commande (Order Objects)​

Un objet de commande ACME représente la demande d'un client pour un certificat et est utilisé pour suivre la progression de cette commande jusqu'à la délivrance. L'objet contient donc des informations sur le certificat demandé, les autorisations que le serveur exige que le client accomplisse, et tout certificat résultant de cette commande.

status (requis, chaîne) : Le statut de cette commande. Les valeurs possibles sont « pending », « ready », « processing », « valid » et « invalid ». Voir section 7.1.6.

expires (optionnel, chaîne) : Horodatage après lequel le serveur considérera cette commande comme invalide, encodé au format spécifié dans [RFC3339]. Ce champ est REQUIS pour les objets dont le champ status est « pending » ou « valid ».

identifiers (requis, tableau d'objets) : Tableau d'objets identifiants concernés par la commande.

  • type (requis, chaîne) : Le type de l'identifiant. Ce document définit le type d'identifiant « dns ». Voir le registre défini à la section 9.7.7 pour tout autre type.

  • value (requis, chaîne) : L'identifiant lui-même.

notBefore (optionnel, chaîne) : Valeur demandée pour le champ notBefore du certificat, au format de date défini dans [RFC3339].

notAfter (optionnel, chaîne) : Valeur demandée pour le champ notAfter du certificat, au format de date défini dans [RFC3339].

error (optionnel, objet) : L'erreur survenue lors du traitement de la commande, le cas échéant. Ce champ est structuré comme un document de problème [RFC7807].

authorizations (requis, tableau de chaînes) : Pour les commandes en attente, les autorisations que le client doit accomplir avant que le certificat demandé puisse être délivré (voir section 7.5), y compris les autorisations non expirées que le client a accomplies précédemment pour les identifiants spécifiés dans la commande. Les autorisations requises sont déterminées par la politique du serveur ; il peut ne pas y avoir de correspondance 1:1 entre les identifiants de la commande et les autorisations requises. Pour les commandes finales (en statut « valid » ou « invalid »), les autorisations accomplies. Chaque entrée est une URL à partir de laquelle une autorisation peut être récupérée avec une requête POST-as-GET.

finalize (requis, chaîne) : Une fois que toutes les autorisations de la commande sont satisfaites, la CSR DOIT être envoyée en POST à cette URL pour finaliser la commande. Le résultat d'une finalisation réussie sera l'URL du certificat renseignée dans la commande.

certificate (optionnel, chaîne) : URL du certificat délivré en réponse à cette commande.

{
  "status": "valid",
  "expires": "2016-01-20T14:09:07.99Z",

  "identifiers": [
    { "type": "dns", "value": "www.example.org" },
    { "type": "dns", "value": "example.org" }
  ],

  "notBefore": "2016-01-01T00:00:00Z",
  "notAfter": "2016-01-08T00:00:00Z",

  "authorizations": [
    "https://example.com/acme/authz/PAniVnsZcis",
    "https://example.com/acme/authz/r4HqLzrSrpI"
  ],

  "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",

  "certificate": "https://example.com/acme/cert/mAt3xBGaobw"
}

Tout identifiant de type « dns » dans une requête newOrder PEUT avoir un nom de domaine générique (wildcard) comme valeur. Un nom de domaine générique est composé d'un seul caractère astérisque suivi d'un seul caractère point (« *. ») suivi d'un nom de domaine tel que défini par [RFC5280] pour une utilisation dans l'extension Subject Alternative Name. Les autorisations retournées par le serveur pour un identifiant de nom de domaine générique NE DOIVENT PAS inclure le préfixe astérisque et point (« *. ») dans la valeur de l'identifiant d'autorisation. Les autorisations retournées DOIVENT contenir le champ optionnel « wildcard » avec la valeur true.

Les éléments des tableaux « authorizations » et « identifiers » sont immuables une fois définis. Le serveur NE DOIT PAS modifier le contenu de l'un ou l'autre tableau après la création. Si le client observe une modification du contenu de l'un ou l'autre tableau, il DEVRAIT considérer la commande comme invalide.

Le tableau « authorizations » d'une commande DEVRAIT refléter toutes les autorisations que la CA a prises en compte pour décider de délivrer, même si certaines autorisations ont été accomplies lors de transactions de commande ou de pré-autorisation antérieures. Par exemple, si la CA permet à plusieurs commandes d'être accomplies sur la base d'une seule transaction d'autorisation, elle DEVRAIT refléter cette autorisation dans toutes les commandes.

Notez que le simple fait qu'une URL d'autorisation soit répertoriée dans le tableau « authorizations » d'un objet de commande ne signifie pas que le client doit agir. Il peut y avoir plusieurs raisons pour lesquelles une autorisation référencée est déjà valide :

  • Le client a accompli l'autorisation dans le cadre d'une commande précédente
  • Le client a pré-autorisé l'identifiant précédemment (voir section 7.4.1)
  • Le serveur a accordé au client une autorisation basée sur un compte externe

Le client DEVRAIT vérifier le champ « status » de la commande pour déterminer si une action est nécessaire.

Note : En raison de la longueur du chapitre 7, ce fichier couvre les sections 7.1 à 7.1.3. Les sections 7.1.4 à 7.6 sont dans la Partie 2.

Dernière mise à jour le