This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
A log is a single, append-only Merkle Tree of submitted certificate and precertificate entries.
</t>
<t>
When it receives a valid submission, the log MUST return an SCT that corresponds to the submitted certificate or precertificate. If the log has previously seen this valid submission, it SHOULD return the same SCT as it returned before (to reduce the ability to track clients as described in <xreftarget="deterministic_signatures"/>). Note that if a certificate was previously logged as a precertificate, then the precertificate's SCT of type <spanxstyle="verb">precert_sct</spanx> would not be appropriate; instead, a fresh SCT of type <spanxstyle="verb">x509_sct</spanx> should be generated.
When it receives a valid submission, the log MUST return an SCT that corresponds to the submitted certificate or precertificate. If the log has previously seen this valid submission, it SHOULD return the same SCT as it returned before (to reduce the ability to track clients as described in <xreftarget="deterministic_signatures"/>). Note that if a certificate was previously logged as a precertificate, then the precertificate's SCT of type <spanxstyle="verb">precert_sct_v2</spanx> would not be appropriate; instead, a fresh SCT of type <spanxstyle="verb">x509_sct_v2</spanx> should be generated.
</t>
<t>
An SCT is the log's promise to incorporate the submitted entry in its Merkle Tree no later than a fixed amount of time, known as the Maximum Merge Delay (MMD), after the issuance of the SCT. Periodically, the log MUST append all its new entries to its Merkle Tree and sign the root of the tree.
case x509_entry: TimestampedCertificateEntryDataV2;
case precert_entry: TimestampedCertificateEntryDataV2;
case x509_sct: SignedCertificateTimestampDataV2;
case precert_sct: SignedCertificateTimestampDataV2;
case tree_head: TreeHeadDataV2;
case signed_tree_head: SignedTreeHeadDataV2;
case consistency_proof: ConsistencyProofDataV2;
case inclusion_proof: InclusionProofDataV2;
VersionedTransType versioned_type;
select (versioned_type) {
case x509_entry_v2: TimestampedCertificateEntryDataV2;
case precert_entry_v2: TimestampedCertificateEntryDataV2;
case x509_sct_v2: SignedCertificateTimestampDataV2;
case precert_sct_v2: SignedCertificateTimestampDataV2;
case tree_head_v2: TreeHeadDataV2;
case signed_tree_head_v2: SignedTreeHeadDataV2;
case consistency_proof_v2: ConsistencyProofDataV2;
case inclusion_proof_v2: InclusionProofDataV2;
} data;
} TransItem;
</artwork>
</figure>
<t>
<spanxstyle="verb">version</spanx> is the earliest version of this protocol to which the encapsulated data structure conforms. This document is v2. Note that <xreftarget="RFC6962">v1</xref> did not define <spanxstyle="verb">TransItem</spanx>, but this document provides guidelines (see <xreftarget="v1_coexistence"/>) on how v2 implementations can co-exist with v1 implementations. Note also that, since each <spanxstyle="verb">TransItem</spanx> object is individually versioned, the version should be increased only if changes to it are made that are not backwards-compatible. The addition of encapsulated data structures can be done by adding <spanxstyle="verb">TransType</spanx> values without increasing the version.
<spanxstyle="verb">versioned_type</spanx> is the type of the encapsulated data structure and the earliest version of this protocol to which it conforms. This document is v2.
</t>
<t>
<spanxstyle="verb">data</spanx> is the encapsulated data structure. The various structures named with the <spanxstyle="verb">DataV2</spanx> suffix are defined in later sections of this document.
</t>
<t>
<spanxstyle="verb">type</spanx> is the type of the encapsulated data structure. (Note that <spanxstyle="verb">TransType</spanx> combines the v1 type enumerations <spanxstyle="verb">LogEntryType</spanx>, <spanxstyle="verb">SignatureType</spanx> and <spanxstyle="verb">MerkleLeafType</spanx>). Future revisions of this protocol may add new <spanxstyle="verb">TransType</spanx> values.
Note that <spanxstyle="verb">VersionedTransType</spanx> combines the <xreftarget="RFC6962">v1</xref> type enumerations <spanxstyle="verb">Version</spanx>, <spanxstyle="verb">LogEntryType</spanx>, <spanxstyle="verb">SignatureType</spanx> and <spanxstyle="verb">MerkleLeafType</spanx>. Note also that v1 did not define <spanxstyle="verb">TransItem</spanx>, but this document provides guidelines (see <xreftarget="v1_coexistence"/>) on how v2 implementations can co-exist with v1 implementations.
</t>
<t>
<spanxstyle="verb">data</spanx> is the encapsulated data structure. The various structures named with the <spanxstyle="verb">DataV2</spanx> suffix are defined in later sections of this document.
Future versions of this protocol may reuse <spanxstyle="verb">VersionedTransType</spanx> values defined in this document as long as the corresponding data structures are not modified, and may add new <spanxstyle="verb">VersionedTransType</spanx> values for new or modified data structures.
</t>
</section>
<sectiontitle="Merkle Tree Leaves"anchor="tree_leaves">
<figure>
<preamble>
The leaves of a log's Merkle Tree correspond to the log's entries (see <xreftarget="log_entries"/>). Each leaf is the <xreftarget="mht">leaf hash</xref> of a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">x509_entry</spanx> or <spanxstyle="verb">precert_entry</spanx>, which in this version (v2) encapsulates a <spanxstyle="verb">TimestampedCertificateEntryDataV2</spanx> structure. Note that leaf hashes are calculated as HASH(0x00 || TransItem), where the hashing algorithm is specified in the log's metadata.
The leaves of a log's Merkle Tree correspond to the log's entries (see <xreftarget="log_entries"/>). Each leaf is the <xreftarget="mht">leaf hash</xref> of a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">x509_entry_v2</spanx> or <spanxstyle="verb">precert_entry_v2</spanx>, which encapsulates a <spanxstyle="verb">TimestampedCertificateEntryDataV2</spanx> structure. Note that leaf hashes are calculated as HASH(0x00 || TransItem), where the hashing algorithm is specified in the log's metadata.
An SCT is a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">x509_sct</spanx> or <spanxstyle="verb">precert_sct</spanx>, which in this version (v2) encapsulates a <spanxstyle="verb">SignedCertificateTimestampDataV2</spanx> structure:
An SCT is a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">x509_sct_v2</spanx> or <spanxstyle="verb">precert_sct_v2</spanx>, which encapsulates a <spanxstyle="verb">SignedCertificateTimestampDataV2</spanx> structure:
The encoding of the digitally-signed element is defined in <xreftarget='RFC5246'/>.
</t>
<t>
<spanxstyle="verb">timestamped_entry</spanx> is a <spanxstyle="verb">TransItem</spanx> structure that MUST be of type <spanxstyle="verb">x509_entry</spanx> or <spanxstyle="verb">precert_entry</spanx> (see <xreftarget="tree_leaves"/>) and MUST have an empty <spanxstyle="verb">item_extensions</spanx> vector.
<spanxstyle="verb">timestamped_entry</spanx> is a <spanxstyle="verb">TransItem</spanx> structure that MUST be of type <spanxstyle="verb">x509_entry_v2</spanx> or <spanxstyle="verb">precert_entry_v2</spanx> (see <xreftarget="tree_leaves"/>) and MUST have an empty <spanxstyle="verb">item_extensions</spanx> vector.
</t>
</section>
<sectiontitle="Merkle Tree Head"anchor="tree_head">
<figure>
<preamble>
The log stores information about its Merkle Tree in a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">tree_head</spanx>, which in this version (v2) encapsulates a <spanxstyle="verb">TreeHeadDataV2</spanx> structure:
The log stores information about its Merkle Tree in a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">tree_head_v2</spanx>, which encapsulates a <spanxstyle="verb">TreeHeadDataV2</spanx> structure:
An STH is a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">signed_tree_head</spanx>, which in this version (v2) encapsulates a <spanxstyle="verb">SignedTreeHeadDataV2</spanx> structure:
An STH is a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">signed_tree_head_v2</spanx>, which encapsulates a <spanxstyle="verb">SignedTreeHeadDataV2</spanx> structure:
<spanxstyle="verb">sth_extensions</spanx> is a vector of 0 or more STH extensions. This vector MUST NOT include more than one extension with the same <spanxstyle="verb">sth_extension_type</spanx>. The extensions in the vector MUST be ordered by the value of the <spanxstyle="verb">sth_extension_type</spanx> field, smallest value first. If an implementation sees an extension that it does not understand, it SHOULD ignore that extension. Furthermore, an implementation MAY choose to ignore any extension(s) that it does understand.
</t>
<t>
<spanxstyle="verb">merkle_tree_head</spanx> is a <spanxstyle="verb">TransItem</spanx> structure that MUST be of type <spanxstyle="verb">tree_head</spanx> (see <xreftarget="tree_head"/>) and MUST have an empty <spanxstyle="verb">item_extensions</spanx> vector.
<spanxstyle="verb">merkle_tree_head</spanx> is a <spanxstyle="verb">TransItem</spanx> structure that MUST be of type <spanxstyle="verb">tree_head_v2</spanx> (see <xreftarget="tree_head"/>) and MUST have an empty <spanxstyle="verb">item_extensions</spanx> vector.
</t>
</section>
<sectiontitle="Merkle Consistency Proofs">
<figure>
<preamble>
To prepare a Merkle Consistency Proof for distribution to clients, the log produces a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">consistency_proof</spanx>, which in this version (v2) encapsulates a <spanxstyle="verb">ConsistencyProofDataV2</spanx> structure:
To prepare a Merkle Consistency Proof for distribution to clients, the log produces a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">consistency_proof_v2</spanx>, which encapsulates a <spanxstyle="verb">ConsistencyProofDataV2</spanx> structure:
To prepare a Merkle Inclusion Proof for distribution to clients, the log produces a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">inclusion_proof</spanx>, which in this version (v2) encapsulates an <spanxstyle="verb">InclusionProofDataV2</spanx> structure:
To prepare a Merkle Inclusion Proof for distribution to clients, the log produces a <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">inclusion_proof_v2</spanx>, which encapsulates an <spanxstyle="verb">InclusionProofDataV2</spanx> structure:
</preamble>
<artwork>
struct {
@@ -812,7 +810,7 @@ messages.
<thangText="Outputs:">
<liststyle="hanging">
<thangText="sct:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">x509_sct</spanx>, signed by this log, that corresponds to the submitted certificate.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">x509_sct_v2</spanx>, signed by this log, that corresponds to the submitted certificate.
</t>
</list>
</t>
@@ -864,7 +862,7 @@ messages.
<thangText="Outputs:">
<liststyle="hanging">
<thangText="sct:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">precert_sct</spanx>, signed by this log, that corresponds to the submitted precertificate.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">precert_sct_v2</spanx>, signed by this log, that corresponds to the submitted precertificate.
</t>
</list>
</t>
@@ -887,7 +885,7 @@ messages.
<thangText="Outputs:">
<liststyle="hanging">
<thangText="sth:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head</spanx>, signed by this log, that is no older than the log's MMD.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head_v2</spanx>, signed by this log, that is no older than the log's MMD.
</t>
</list>
</t>
@@ -917,10 +915,10 @@ messages.
<thangText="Outputs:">
<liststyle="hanging">
<thangText="consistency:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">consistency_proof</spanx>, whose <spanxstyle="verb">tree_size_1</spanx> MUST match the <spanxstyle="verb">first</spanx> input. If the <spanxstyle="verb">sth</spanx> output is omitted, then <spanxstyle="verb">tree_size_2</spanx> MUST match the <spanxstyle="verb">second</spanx> input.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">consistency_proof_v2</spanx>, whose <spanxstyle="verb">tree_size_1</spanx> MUST match the <spanxstyle="verb">first</spanx> input. If the <spanxstyle="verb">sth</spanx> output is omitted, then <spanxstyle="verb">tree_size_2</spanx> MUST match the <spanxstyle="verb">second</spanx> input.
</t>
<thangText="sth:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head</spanx>, signed by this log.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head_v2</spanx>, signed by this log.
</t>
</list>
</t>
@@ -966,10 +964,10 @@ messages.
<thangText="Outputs:">
<liststyle="hanging">
<thangText="inclusion:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">inclusion_proof</spanx> whose <spanxstyle="verb">inclusion_path</spanx> array of Merkle Tree nodes proves the inclusion of the chosen certificate in the selected STH.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">inclusion_proof_v2</spanx> whose <spanxstyle="verb">inclusion_path</spanx> array of Merkle Tree nodes proves the inclusion of the chosen certificate in the selected STH.
</t>
<thangText="sth:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head</spanx>, signed by this log.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head_v2</spanx>, signed by this log.
</t>
</list>
</t>
@@ -1032,13 +1030,13 @@ messages.
<thangText="Outputs:">
<liststyle="hanging">
<thangText="inclusion:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">inclusion_proof</spanx> whose <spanxstyle="verb">inclusion_path</spanx> array of Merkle Tree nodes proves the inclusion of the chosen certificate in the selected STH.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">inclusion_proof_v2</spanx> whose <spanxstyle="verb">inclusion_path</spanx> array of Merkle Tree nodes proves the inclusion of the chosen certificate in the selected STH.
</t>
<thangText="sth:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head</spanx>, signed by this log.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head_v2</spanx>, signed by this log.
</t>
<thangText="consistency:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">consistency_proof</spanx> that proves the consistency of the requested STH and the returned STH.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">consistency_proof_v2</spanx> that proves the consistency of the requested STH and the returned STH.
</t>
</list>
</t>
@@ -1077,18 +1075,18 @@ messages.
An array of objects, each consisting of
<liststyle="hanging">
<thangText="leaf_input:">
The base64 encoded <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">x509_entry</spanx> or <spanxstyle="verb">precert_entry</spanx> (see <xreftarget="tree_leaves"/>).
The base64 encoded <spanxstyle="verb">TransItem</spanx> structure of type <spanxstyle="verb">x509_entry_v2</spanx> or <spanxstyle="verb">precert_entry_v2</spanx> (see <xreftarget="tree_leaves"/>).
</t>
<thangText="log_entry:">
The base64 encoded log entry (see <xreftarget="log_entries"/>). In the case of an <spanxstyle="verb">x509_entry</spanx> entry, this is the whole <spanxstyle="verb">X509ChainEntry</spanx>; and in the case of a <spanxstyle="verb">precert_entry</spanx>, this is the whole <spanxstyle="verb">PrecertChainEntryV2</spanx>.
The base64 encoded log entry (see <xreftarget="log_entries"/>). In the case of an <spanxstyle="verb">x509_entry_v2</spanx> entry, this is the whole <spanxstyle="verb">X509ChainEntry</spanx>; and in the case of a <spanxstyle="verb">precert_entry_v2</spanx>, this is the whole <spanxstyle="verb">PrecertChainEntryV2</spanx>.
</t>
<thangText="sct:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">x509_sct</spanx> or <spanxstyle="verb">precert_sct</spanx> corresponding to this log entry. Note that more than one SCT may have been returned for the same entry - only one of those is returned in this field. It may not be possible to retrieve others.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">x509_sct_v2</spanx> or <spanxstyle="verb">precert_sct_v2</spanx> corresponding to this log entry. Note that more than one SCT may have been returned for the same entry - only one of those is returned in this field. It may not be possible to retrieve others.
</t>
</list>
</t>
<thangText="sth:">
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head</spanx>, signed by this log.
A base64 encoded <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">signed_tree_head_v2</spanx>, signed by this log.
</t>
</list>
</t>
@@ -1306,7 +1304,7 @@ but it is expected there will be a variety.
A certificate with redacted labels where one of the redacted labels is <spanxstyle="verb">*</spanx> MUST NOT be considered compliant.
</t>
<t>
If the SCT checked is for a Precertificate (where the <spanxstyle="verb">type</spanx> of the <spanxstyle="verb">TransItem</spanx> is <spanxstyle="verb">precert_sct</spanx>), then the client SHOULD also remove embedded v1 SCTs, identified by OID 1.3.6.1.4.1.11129.2.4.2 (See Section 3.3. of <xreftarget="RFC6962"/>), in the process of reconstructing the TBSCertificate. That is to allow embedded v1 and v2 SCTs to co-exist in a certificate (See <xreftarget="v1_coexistence"/>).
If the SCT checked is for a Precertificate (where the <spanxstyle="verb">type</spanx> of the <spanxstyle="verb">TransItem</spanx> is <spanxstyle="verb">precert_sct_v2</spanx>), then the client SHOULD also remove embedded v1 SCTs, identified by OID 1.3.6.1.4.1.11129.2.4.2 (See Section 3.3. of <xreftarget="RFC6962"/>), in the process of reconstructing the TBSCertificate. That is to allow embedded v1 and v2 SCTs to co-exist in a certificate (See <xreftarget="v1_coexistence"/>).
</t>
</section>
<sectiontitle="Validating SCTs">
@@ -1436,7 +1434,7 @@ but it is expected there will be a variety.
</t>
<sectiontitle="Verifying an inclusion proof"anchor="verify_inclusion">
<t>
When a client has received a <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">inclusion_proof</spanx> and wishes to verify inclusion of an input <spanxstyle="verb">hash</spanx> for an STH with a given <spanxstyle="verb">tree_size</spanx> and <spanxstyle="verb">root_hash</spanx>, the following algorithm may be used to prove the <spanxstyle="verb">hash</spanx> was included in the <spanxstyle="verb">root_hash</spanx>:
When a client has received a <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">inclusion_proof_v2</spanx> and wishes to verify inclusion of an input <spanxstyle="verb">hash</spanx> for an STH with a given <spanxstyle="verb">tree_size</spanx> and <spanxstyle="verb">root_hash</spanx>, the following algorithm may be used to prove the <spanxstyle="verb">hash</spanx> was included in the <spanxstyle="verb">root_hash</spanx>:
<liststyle="numbers">
<t>Compare <spanxstyle="verb">leaf_index</spanx> against <spanxstyle="verb">tree_size</spanx>. If <spanxstyle="verb">leaf_index</spanx> is greater than or equal to <spanxstyle="verb">tree_size</spanx> fail the proof verification.</t>
<t>Set <spanxstyle="verb">fn</spanx> to <spanxstyle="verb">leaf_index</spanx> and <spanxstyle="verb">sn</spanx> to <spanxstyle="verb">tree_size - 1</spanx>.</t>
@@ -1464,7 +1462,7 @@ but it is expected there will be a variety.
</section>
<sectiontitle="Verifying consistency between two STHs"anchor="verify_consistency">
<t>
When a client has an STH <spanxstyle="verb">first_hash</spanx> for tree size <spanxstyle="verb">first</spanx>, an STH <spanxstyle="verb">second_hash</spanx> for tree size <spanxstyle="verb">second</spanx> where <spanxstyle="verb">0 < first < second</spanx>, and has received a <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">consistency_proof</spanx> that they wish to use to verify both hashes, the following algorithm may be used:
When a client has an STH <spanxstyle="verb">first_hash</spanx> for tree size <spanxstyle="verb">first</spanx>, an STH <spanxstyle="verb">second_hash</spanx> for tree size <spanxstyle="verb">second</spanx> where <spanxstyle="verb">0 < first < second</spanx>, and has received a <spanxstyle="verb">TransItem</spanx> of type <spanxstyle="verb">consistency_proof_v2</spanx> that they wish to use to verify both hashes, the following algorithm may be used:
<liststyle="numbers">
<t>If <spanxstyle="verb">first</spanx> is an exact power of 2, then prepend <spanxstyle="verb">first_hash</spanx> to the <spanxstyle="verb">consistency_path</spanx> array.</t>
<t>Set <spanxstyle="verb">fn</spanx> to <spanxstyle="verb">first - 1</spanx> and <spanxstyle="verb">sn</spanx> to <spanxstyle="verb">second - 1</spanx>.</t>