Passa al contenuto principale

4. Log Client Messages (Messaggi del client verso il log)

4. Log Client Messages (Messaggi del client verso il log)​

I messaggi sono inviati come richieste HTTPS GET o POST. I parametri per le POST e tutte le risposte sono codificati come oggetti JavaScript Object Notation (JSON) [RFC4627]. I parametri per le GET sono codificati come parametri URL chiave/valore indipendenti dall'ordine, usando il formato "application/x-www-form-urlencoded" descritto nella "HTML 4.01 Specification" [HTML401]. I dati binari sono codificati in base64 [RFC4648] come specificato nei singoli messaggi.

Si noti che gli oggetti JSON e i parametri URL possono contenere campi non specificati qui. Questi campi extra dovrebbero essere ignorati.

Il prefisso <log server> può includere un percorso oltre al nome del server e alla porta.

In generale, ove necessario, "version" è v1 e "id" è il log id per il log server interrogato.

Qualsiasi errore sarà restituito come risposte HTTP 4xx o 5xx, con messaggi di errore leggibili dall'uomo.

4.1 Add Chain to Log (Aggiunta catena al log)​

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

Input:

  • chain: Un array di certificati codificati in base64. Il primo elemento è il certificato end-entity; il secondo concatena al primo e così via fino all'ultimo, che è il certificato radice oppure un certificato che concatena a una radice nota.

Output:

  • sct_version: La versione della struttura SignedCertificateTimestamp, in decimale. Un'implementazione v1 conforme NON DEVE attendersi che questo sia 0 (cioè, v1).

  • id: Il log ID, codificato in base64. Poiché i log client che richiedono un SCT per inclusione negli handshake TLS non sono tenuti a verificarlo, non assumiamo che conoscano l'ID del log.

  • timestamp: Il timestamp SCT, in decimale.

  • extensions: Un tipo opaco per espansioni future. È probabile che non tutti i partecipanti debbano comprendere i dati in questo campo. I log dovrebbero impostarlo alla stringa vuota. I client dovrebbero decodificare i dati in base64 e includerli nell'SCT.

  • signature: La firma SCT, codificata in base64.

Se "sct_version" non è v1, allora un client v1 può essere incapace di verificare la firma. NON DEVE interpretare ciò come errore. (Nota: non è richiesto che i log client siano in grado di verificare questa struttura; solo i client TLS. Se servissimo la struttura come blob binario, potremmo cambiarla completamente senza richiedere un aggiornamento ai client v1.)

4.2 Add PreCertChain to Log (Aggiunta PreCertChain al log)​

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

Input:

  • chain: Un array di Precertificate codificati in base64. Il primo elemento è il certificato end-entity; il secondo concatena al primo e così via fino all'ultimo, che è il certificato radice oppure un certificato che concatena a una radice nota.

Gli output sono gli stessi della Sezione 4.1.

4.3 Retrieve Latest Signed Tree Head (Recupero ultima STH)​

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

Nessun input.

Output:

  • tree_size: La dimensione dell'albero, in voci, in decimale.

  • timestamp: Il timestamp, in decimale.

  • sha256_root_hash: Il Merkle Tree Hash dell'albero, in base64.

  • tree_head_signature: Un TreeHeadSignature per i dati sopra.

4.4 Retrieve Merkle Consistency Proof between Two Signed Tree Heads (Recupero prova di coerenza tra due STH)​

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

Input:

  • first: Il tree_size del primo albero, in decimale.

  • second: Il tree_size del secondo albero, in decimale.

Entrambe le dimensioni dell'albero DEVONO provenire da STH (Signed Tree Heads) v1 esistenti.

Output:

  • consistency: Un array di nodi Merkle Tree, codificati in base64.

Si noti che non è richiesta una firma su questi dati, poiché sono usati per verificare una STH, che è firmata.

4.5 Retrieve Merkle Audit Proof from Log by Leaf Hash (Recupero prova di verifica per hash foglia)​

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

Input:

  • hash: Un leaf hash v1 codificato in base64.

  • tree_size: Il tree_size dell'albero su cui basare la prova, in decimale.

"hash" DEVE essere calcolato come definito nella Sezione 3.4. "tree_size" DEVE designare una STH v1 esistente.

Output:

  • leaf_index: L'indice in base zero dell'entità finale corrispondente al parametro "hash".

  • audit_path: Un array di nodi Merkle Tree codificati in base64 che provano l'inclusione del certificato scelto.

4.6 Retrieve Entries from Log (Recupero voci dal log)​

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

Input:

  • start: Indice in base zero della prima voce da recuperare, in decimale.

  • end: Indice in base zero dell'ultima voce da recuperare, in decimale.

Output:

  • entries: Un array di oggetti, ciascuno costituito da

    • leaf_input: La struttura MerkleTreeLeaf codificata in base64.

    • extra_data: I dati non firmati codificati in base64 pertinenti alla voce del log. Nel caso di un X509ChainEntry, questo è il "certificate_chain". Nel caso di un PrecertChainEntry, questo è l'intero "PrecertChainEntry".

Si noti che questo messaggio non è firmato; i dati recuperati possono essere verificati costruendo il Merkle Tree Hash corrispondente a una STH recuperata. Tutte le foglie DEVONO essere v1. Tuttavia, un client v1 conforme NON DEVE interpretare un valore MerkleLeafType o LogEntryType non riconosciuto come errore. Ciò significa che può essere incapace di analizzare alcune voci, ma si noti che ciascun client può ispezionare le voci che riconosce così come verificare l'integrità dei dati trattando le foglie non riconosciute come input opachi all'albero.

I parametri "start" e "end" DOVREBBERO essere nell'intervallo 0 <= x < "tree_size" come restituito da "get-sth" nella Sezione 4.3.

I log POSSONO soddisfare richieste dove 0 <= "start" < "tree_size" e "end" >= "tree_size" restituendo una risposta parziale che copre solo le voci valide nell'intervallo specificato. Si noti che può applicarsi anche la seguente restrizione:

I log POSSONO limitare il numero di voci recuperabili per richiesta "get-entries". Se un client richiede più del numero consentito di voci, il log DEVE restituire il numero massimo di voci consentito. Queste voci DEVONO essere sequenziali a partire dalla voce specificata da "start".

4.7 Retrieve Accepted Root Certificates (Recupero certificati radice accettati)​

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

Nessun input.

Output:

  • certificates: Un array di certificati radice codificati in base64 accettabili per il log.

4.8 Retrieve Entry+Merkle Audit Proof from Log (Recupero voce e prova Merkle)​

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

Input:

  • leaf_index: L'indice della voce desiderata.

  • tree_size: Il tree_size dell'albero per cui si desidera la prova.

La dimensione dell'albero DEVE designare una STH esistente.

Output:

  • leaf_input: La struttura MerkleTreeLeaf codificata in base64.

  • extra_data: I dati non firmati codificati in base64, come nella Sezione 4.6.

  • audit_path: Un array di nodi Merkle Tree codificati in base64 che provano l'inclusione del certificato scelto.

Questa API è probabilmente utile solo per il debug.

Ultimo aggiornamento il