Aller au contenu principal

4. Messages client vers le journal

4. Messages client vers le journal​

Les messages sont envoyés comme requêtes HTTPS GET ou POST. Les paramètres des POST et toutes les réponses sont encodés comme des objets JavaScript Object Notation (JSON) [RFC4627]. Les paramètres des GET sont encodés comme des paramètres d’URL clé/valeur indépendants de l’ordre, en utilisant le format « application/x-www-form-urlencoded » décrit dans la « HTML 4.01 Specification » [HTML401]. Les données binaires sont encodées en base64 [RFC4648] comme spécifié dans les messages individuels.

Noter que les objets JSON et les paramètres d’URL peuvent contenir des champs non spécifiés ici. Ces champs supplémentaires devraient être ignorés.

Le préfixe <log server> peut inclure un chemin ainsi qu’un nom de serveur et un port.

En général, lorsque nécessaire, la « version » est v1 et le « id » est l’identifiant du journal pour le serveur de journal interrogé.

Toute erreur sera renvoyée comme réponse HTTP 4xx ou 5xx, avec des messages d’erreur lisibles par un humain.

4.1. Ajout d’une chaîne au journal​

POST https://<log server>/ct/v1/add-chain

Entrées :

  • chain : Un tableau de certificats encodés en base64. Le premier élément est le certificat de l’entité finale ; le second chaîne sur le premier et ainsi de suite jusqu’au dernier, qui est soit le certificat racine, soit un certificat qui chaîne vers un certificat racine connu.

Sorties :

  • sct_version : La version de la structure SignedCertificateTimestamp, en décimal. Une mise en œuvre v1 conforme NE DOIT PAS s’attendre à ce que ce soit 0 (c’est-à-dire, v1).

  • id : L’identifiant du journal, encodé en base64. Comme les clients de journal qui demandent un SCT pour inclusion dans les poignées de main TLS ne sont pas tenus de le vérifier, nous ne supposons pas qu’ils connaissent l’ID du journal.

  • timestamp : L’horodatage du SCT, en décimal.

  • extensions : Un type opaque pour extension future. Il est probable que tous les participants n’aient pas besoin de comprendre les données dans ce champ. Les journaux devraient le définir à la chaîne vide. Les clients devraient décoder les données encodées en base64 et les inclure dans le SCT.

  • signature : La signature du SCT, encodée en base64.

Si le « sct_version » n’est pas v1, alors un client v1 peut être incapable de vérifier la signature. Il NE DOIT PAS interpréter ceci comme une erreur. (Note : les clients de journal n’ont pas besoin de pouvoir vérifier cette structure ; seuls les clients TLS le doivent. Si nous servions la structure comme un blob binaire, nous pourrions la modifier entièrement sans exiger une mise à jour des clients v1.)

4.2. Ajout d’une chaîne PreCert au journal​

POST https://<log server>/ct/v1/add-pre-chain

Entrées :

  • chain : Un tableau de Precertificates encodés en base64. Le premier élément est le certificat de l’entité finale ; le second chaîne sur le premier et ainsi de suite jusqu’au dernier, qui est soit le certificat racine, soit un certificat qui chaîne vers un certificat racine connu.

Les sorties sont les mêmes qu’à la section 4.1.

4.3. Récupération de la Signed Tree Head la plus récente​

GET https://<log server>/ct/v1/get-sth

Aucune entrée.

Sorties :

  • tree_size : La taille de l’arbre, en entrées, en décimal.

  • timestamp : L’horodatage, en décimal.

  • sha256_root_hash : Le hachage d’arbre de Merkle de l’arbre, en base64.

  • tree_head_signature : Un TreeHeadSignature pour les données ci-dessus.

4.4. Récupération d’une preuve de cohérence Merkle entre deux Signed Tree Heads​

GET https://<log server>/ct/v1/get-sth-consistency

Entrées :

  • first : Le tree_size du premier arbre, en décimal.

  • second : Le tree_size du second arbre, en décimal.

Les deux tailles d’arbre doivent provenir de STH v1 (Signed Tree Heads) existantes.

Sorties :

  • consistency : Un tableau de nœuds d’arbre de Merkle, encodés en base64.

Noter qu’aucune signature n’est requise sur ces données, car elles servent à vérifier une STH, qui est signée.

4.5. Récupération d’une preuve d’audit Merkle par hachage de feuille​

GET https://<log server>/ct/v1/get-proof-by-hash

Entrées :

  • hash : Un hachage de feuille v1 encodé en base64.

  • tree_size : Le tree_size de l’arbre sur lequel baser la preuve, en décimal.

Le « hash » doit être calculé comme défini à la section 3.4. Le « tree_size » doit désigner une STH v1 existante.

Sorties :

  • leaf_index : L’index basé sur 0 de l’entité finale correspondant au paramètre « hash ».

  • audit_path : Un tableau de nœuds d’arbre de Merkle encodés en base64 prouvant l’inclusion du certificat choisi.

4.6. Récupération d’entrées depuis le journal​

GET https://<log server>/ct/v1/get-entries

Entrées :

  • start : Index basé sur 0 de la première entrée à récupérer, en décimal.

  • end : Index basé sur 0 de la dernière entrée à récupérer, en décimal.

Sorties :

  • entries : Un tableau d’objets, chacun constitué de

    • leaf_input : La structure MerkleTreeLeaf encodée en base64.

    • extra_data : Les données non signées encodées en base64 relatives à l’entrée du journal. Dans le cas d’un X509ChainEntry, il s’agit du « certificate_chain ». Dans le cas d’un PrecertChainEntry, il s’agit de l’intégralité du « PrecertChainEntry ».

Noter que ce message n’est pas signé — les données récupérées peuvent être vérifiées en construisant le hachage d’arbre de Merkle correspondant à une STH récupérée. Toutes les feuilles DOIVENT être v1. Toutefois, un client v1 conforme NE DOIT PAS interpréter une valeur MerkleLeafType ou LogEntryType non reconnue comme une erreur. Cela signifie qu’il peut être incapable d’analyser certaines entrées, mais noter que chaque client peut inspecter les entrées qu’il reconnaît ainsi que vérifier l’intégrité des données en traitant les feuilles non reconnues comme entrée opaque dans l’arbre.

Les paramètres « start » et « end » DEVRAIENT être dans la plage 0 <= x < « tree_size » tel que renvoyé par « get-sth » à la section 4.3.

Les journaux PEUVENT honorer les requêtes où 0 <= « start » < « tree_size » et « end » >= « tree_size » en renvoyant une réponse partielle couvrant uniquement les entrées valides dans la plage spécifiée. Noter que la restriction suivante peut également s’appliquer :

Les journaux PEUVENT restreindre le nombre d’entrées pouvant être récupérées par requête « get-entries ». Si un client demande plus que le nombre d’entrées autorisé, le journal DOIT renvoyer le nombre maximal d’entrées permises. Ces entrées DOIVENT être séquentielles en commençant par l’entrée spécifiée par « start ».

4.7. Récupération des certificats racines acceptés​

GET https://<log server>/ct/v1/get-roots

Aucune entrée.

Sorties :

  • certificates : Un tableau de certificats racines encodés en base64 acceptables pour le journal.

4.8. Récupération d’une entrée et d’une preuve d’audit Merkle​

GET https://<log server>/ct/v1/get-entry-and-proof

Entrées :

  • leaf_index : L’index de l’entrée désirée.

  • tree_size : Le tree_size de l’arbre pour lequel la preuve est désirée.

La taille d’arbre doit désigner une STH existante.

Sorties :

  • leaf_input : La structure MerkleTreeLeaf encodée en base64.

  • extra_data : Les données non signées encodées en base64, comme à la section 4.6.

  • audit_path : Un tableau de nœuds d’arbre de Merkle encodés en base64 prouvant l’inclusion du certificat choisi.

Cette API n’est probablement utile que pour le débogage.

Dernière mise à jour le