RFC 6962
Certificate Transparency
Certificate Transparency 🦋
Bestie, this is RFC 6962 💖 It's an Experimental doc from the IETF (ISSN 2070-1721), written by B. Laurie, A. Langley, and E. Kasper at Google in June 2013. It doesn't list anything it obsoletes or updates in its header. ✨
Abstract
This doc describes an experimental protocol for publicly logging the existence of Transport Layer Security (TLS) certificates as they are issued or observed 🔥. The whole point is that anyone can audit certificate authority (CA) activity, spot suspect certificates being issued, and audit the certificate logs themselves 👀. The long-term plan is that clients would refuse to honor certificates that don't show up in a log, which basically forces CAs to log every certificate they issue 💅.
Logs are network services that implement the protocol operations for submissions and queries defined in this document 🧚.
Status of This Memo
Okay, the boring-but-important bit 🙈. This document is not an Internet Standards Track specification. It's published for examination, experimental implementation, and evaluation 🧪.
It defines an Experimental Protocol for the Internet community. It's a product of the IETF and represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). Not every IESG-approved doc is a candidate for any level of Internet Standard, so check Section 2 of RFC 5741 if you're curious about that 🤓.
Info on the current status of this document, any errata, and how to give feedback lives at http://www.rfc-editor.org/info/rfc6962 🌸.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved 🎀.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the date of publication. Please read these carefully, because they spell out your rights and restrictions for this document ⭐. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 📜.
Table of Contents
1. Informal Introduction ...........................................3
1.1. Requirements Language ......................................4
1.2. Data Structures ............................................4
2. Cryptographic Components ........................................4
2.1. Merkle Hash Trees ..........................................4
2.1.1. Merkle Audit Paths ..................................5
2.1.2. Merkle Consistency Proofs ...........................6
2.1.3. Example .............................................7
2.1.4. Signatures ..........................................8
3. Log Format and Operation ........................................9
3.1. Log Entries ................................................9
3.2. Structure of the Signed Certificate Timestamp .............12
3.3. Including the Signed Certificate Timestamp in the
TLS Handshake .............................................13
3.3.1. TLS Extension ......................................15
3.4. Merkle Tree ...............................................15
3.5. Signed Tree Head ..........................................16
4. Log Client Messages ............................................17
4.1. Add Chain to Log ..........................................17
4.2. Add PreCertChain to Log ...................................18
4.3. Retrieve Latest Signed Tree Head ..........................18
4.4. Retrieve Merkle Consistency Proof between Two
Signed Tree Heads .........................................19
4.5. Retrieve Merkle Audit Proof from Log by Leaf Hash .........19
4.6. Retrieve Entries from Log .................................20
4.7. Retrieve Accepted Root Certificates .......................21
4.8. Retrieve Entry+Merkle Audit Proof from Log ................21
5. Clients ........................................................21
5.1. Submitters ................................................22
5.2. TLS Client ................................................22
5.3. Monitor ...................................................22
5.4. Auditor ...................................................23
6. IANA Considerations ............................................23
7. Security Considerations ........................................23
7.1. Misissued Certificates ....................................24
7.2. Detection of Misissue .....................................24
7.3. Misbehaving Logs ..........................................24
8. Efficiency Considerations ......................................25
9. Future Changes .................................................25
10. Acknowledgements ..............................................25
11. References ....................................................25
11.1. Normative Reference ......................................25
11.2. Informative References ...................................261. Informal Introduction ✨
Okay, big picture 🌈. Certificate transparency is all about fixing the problem of misissued certificates. It does this by giving everyone publicly auditable, append-only, untrusted logs of every certificate that's been issued 📚.
The logs are publicly auditable, which means anyone can verify that each log is correct and watch for new certificates being added 👀. The logs don't stop misissue from happening by themselves. What they do is make sure interested parties (especially the people named in the certificates) can catch misissuance when it happens 🫶. This is a general mechanism, but this doc only covers its use for public TLS server certificates issued by public certificate authorities (CAs) 💜.
Each log is made up of certificate chains, and anyone can submit one 💅. Public CAs are expected to send all their newly issued certificates to one or more logs, and certificate holders are also expected to submit their own certificate chains 🍓. To keep logs from getting spammed into uselessness, each chain is required to be rooted in a known CA certificate 🛡️. When a chain gets submitted to a log, the log hands back a signed timestamp. That timestamp can be used later as evidence to clients that the chain was submitted, so TLS clients can require that every certificate they see has been logged 🔐.
People who worry about misissue can monitor the logs, asking them regularly for all new entries, and check whether domains they look after have had certificates issued that they didn't expect 🕵️♀️. What they do with that info, especially when they find an actual misissuance, is outside the scope of this doc. Broadly speaking, they can use existing business mechanisms for dealing with misissued certificates 💼. Of course, anyone who wants to can monitor the logs and, if they think a certificate was issued incorrectly, take whatever action they see fit ✨.
Similarly, anyone who has seen signed timestamps from a particular log can later demand a proof of inclusion from that log 🧾. If the log can't provide one (or if the matching certificate is missing from monitors' copies of that log), that's evidence the log isn't operating correctly 🚩. The checking happens asynchronously, so TLS connections can keep going without delay, even with network connectivity issues and the vagaries of firewalls 🏃♀️💨.
Each log's append-only property is technically achieved with Merkle Trees 🌳. They can show that any particular version of the log is a superset of any particular previous version 💖. Merkle Trees also mean nobody has to blindly trust logs: if a log tries to show different things to different people, comparing tree roots and consistency proofs can efficiently catch it 👑. Other misbehavior from a log, like issuing signed timestamps for certificates it then doesn't actually log, can be efficiently detected and proved to the world at large 📣.
1.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119] 🎀.
1.2. Data Structures
Data structures are defined according to the conventions laid out in Section 4 of [RFC5246] 🧩.
2. Cryptographic Components 🔐
2.1. Merkle Hash Trees 🌳
Logs use a binary Merkle Hash Tree for efficient auditing 🦋. The hashing algorithm is SHA-256 [FIPS.180-4]. Note that this is fixed for this experiment, but it's anticipated that each log would be able to specify a hash algorithm 🧪. The input to the Merkle Tree Hash is a list of data entries, and these entries get hashed to form the leaves of the Merkle Hash Tree 🍃. The output is a single 32-byte Merkle Tree Hash 💜.
Given an ordered list of n inputs, D[n] = {d(0), d(1), ..., d(n-1)}, the Merkle Tree Hash (MTH) is defined as follows 🧠:
The hash of an empty list is the hash of an empty string:
MTH({}) = SHA-256().The hash of a list with one entry (also known as a leaf hash) is:
MTH({d(0)}) = SHA-256(0x00 || d(0)).For n > 1, let k be the largest power of two smaller than n (i.e., k < n <= 2k). The Merkle Tree Hash of an n-element list D[n] is then defined recursively as
MTH(D[n]) = SHA-256(0x01 || MTH(D[0:k]) || MTH(D[k:n])),where || is concatenation and D[k1:k2] denotes the list {d(k1), d(k1+1),..., d(k2-1)} of length (k2 - k1). (Note that the hash calculations for leaves and nodes differ. This domain separation is required to give second preimage resistance 🛡️✨.)
Note that we do not require the length of the input list to be a power of two 🙌. The resulting Merkle Tree may therefore not be balanced 🌲. However, its shape is uniquely determined by the number of leaves 💅. (Note: This Merkle Tree is essentially the same as the history tree [CrosbyWallach] proposal, except our definition handles non-full trees differently 🤓.)
2.1.1. Merkle Audit Paths ✨
okay so a Merkle audit path for a leaf is the shortest list of extra nodes you need from the tree to compute the Merkle Tree Hash 💅 every node is either a leaf or gets computed from the two nodes right below it (aka closer to the leaves) 🌸 as you climb toward the root, you combine an audit path node with whatever you've computed so far. so the audit path is literally the list of missing pieces that get you from a leaf all the way up to the root 🦋 and if the root you compute from the path matches the true root? that's your proof the leaf is actually in the tree, no cap 🫶
Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., d(n-1)}, the Merkle audit path PATH(m, D[n]) for the (m+1)th input d(m), 0 <= m < n, is defined like this 👑
The path for a single leaf in a tree with a one-element input list D[1] = {d(0)} is empty 🧚
PATH(0, {d(0)}) = {}For n > 1, let k be the largest power of two smaller than n. The path for the (m+1)th element d(m) in a list of n > m elements is then defined recursively as
PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n]) for m < k; and
PATH(m, D[n]) = PATH(m - k, D[k:n]) : MTH(D[0:k]) for m >= k,where : is concatenation of lists, and D[k1:k2] is the length (k2 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before 💖
2.1.2. Merkle Consistency Proofs 🎀
okay this one is giving append-only energy 🍓 Merkle consistency proofs are how you prove the tree only ever grows and nothing got rewritten behind your back 😭 for a Merkle Tree Hash MTH(D[n]) and a previously advertised hash MTH(D[0:m]) of the first m leaves, m <= n, the proof is the list of nodes you need in order to check that those first m inputs D[0:m] are the same in both trees 🌈 so a consistency proof has to include a set of intermediate nodes (aka commitments to inputs) that's enough to verify MTH(D[n]), and a subset of those same nodes can then verify MTH(D[0:m]) ✨ the spec also gives an algorithm that outputs the (unique) minimal consistency proof, so there's only one smallest version 💅
Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., d(n-1)}, the Merkle consistency proof PROOF(m, D[n]) for a previous Merkle Tree Hash MTH(D[0:m]), 0 < m < n, is defined as:
PROOF(m, D[n]) = SUBPROOF(m, D[n], true)The subproof for m = n is empty if m is the value that PROOF was originally asked for (meaning the subtree Merkle Tree Hash MTH(D[0:m]) is already known) 🙈
SUBPROOF(m, D[m], true) = {}The subproof for m = n is the Merkle Tree Hash committing to inputs D[0:m]; otherwise 🫧
SUBPROOF(m, D[m], false) = {MTH(D[m])}For m < n, let k be the largest power of two smaller than n. The subproof is then defined recursively 💜
If m <= k, the right subtree entries D[k:n] only exist in the current tree. So we prove the left subtree entries D[0:k] are consistent, and add a commitment to D[k:n] 🦋
SUBPROOF(m, D[n], b) = SUBPROOF(m, D[0:k], b) : MTH(D[k:n])If m > k, the left subtree entries D[0:k] are identical in both trees. So we prove the right subtree entries D[k:n] are consistent, and add a commitment to D[0:k] 🌸
SUBPROOF(m, D[n], b) = SUBPROOF(m - k, D[k:n], false) : MTH(D[0:k])Here, : is a concatenation of lists, and D[k1:k2] denotes the length (k2 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before ✨
The number of nodes in the resulting proof is bounded above by ceil(log2(n)) + 1 🧚
2.1.3. Example 🍓
Here's the binary Merkle Tree with 7 leaves 🌳
hash
/ \
/ \
/ \
/ \
/ \
k l
/ \ / \
/ \ / \
/ \ / \
g h i j
/ \ / \ / \ |
a b c d e f d6
| | | | | |
d0 d1 d2 d3 d4 d5The audit path for d0 is [b, h, l] 💅
The audit path for d3 is [c, g, l] 💖
The audit path for d4 is [f, j, k] 🫶
The audit path for d6 is [i, k] 🦋
And here's that same tree built up incrementally in four steps 🔥
hash0 hash1=k
/ \ / \
/ \ / \
/ \ / \
g c g h
/ \ | / \ / \
a b d2 a b c d
| | | | | |
d0 d1 d0 d1 d2 d3
hash2 hash
/ \ / \
/ \ / \
/ \ / \
/ \ / \
/ \ / \
k i k l
/ \ / \ / \ / \
/ \ e f / \ / \
/ \ | | / \ / \
g h d4 d5 g h i j
/ \ / \ / \ / \ / \ |
a b c d a b c d e f d6
| | | | | | | | | |
d0 d1 d2 d3 d0 d1 d2 d3 d4 d5The consistency proof between hash0 and hash is PROOF(3, D[7]) = [c, d, g, l]. c and g are used to verify hash0, and d and l are also used to show hash is consistent with hash0 🎀
The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l]. hash can be verified using hash1=k and l 🌈
The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i, j, k]. k and i are used to verify hash2, and j is also used to show hash is consistent with hash2 ✨
2.1.4. Signatures 💜
Lots of data structures get signed here 🖊️ A log MUST use either elliptic curve signatures on the NIST P-256 curve (Section D.1.2.3 of the Digital Signature Standard [DSS]) or RSA signatures (RSASSA-PKCS1-V1_5 with SHA-256, Section 8.2 of [RFC3447]) using a key of at least 2048 bits 🔐
3. Log Format and Operation ✨
Anyone can submit certificates to certificate logs for public auditing 📜 but since TLS clients won't accept a certificate unless it's logged, the certificate owners or their CAs are usually the ones who submit them 🫶 a log is one single, ever-growing, append-only Merkle Tree of those certificates 🌳
When a valid certificate is submitted to a log, the log MUST immediately return a Signed Certificate Timestamp (SCT) 🎀 the SCT is the log's promise to fold the certificate into the Merkle Tree within a fixed amount of time called the Maximum Merge Delay (MMD) ⏰ if the log has already seen that certificate, it MAY hand back the same SCT it gave before 💅 and TLS servers MUST present an SCT from one or more logs to the TLS client together with the certificate. TLS clients MUST reject certificates that don't have a valid SCT for the end-entity certificate 🙅♀️
Periodically, each log appends all its new entries to the Merkle Tree and signs the root of the tree 🌸 that's how auditors can verify that each certificate with an issued SCT actually shows up in the log 🕵️♀️ The log MUST incorporate a certificate in its Merkle Tree within the Maximum Merge Delay period after the SCT was issued 😭
Log operators MUST NOT impose any conditions on retrieving or sharing data from the log 🔥
3.1. Log Entries ✨
okay so anyone can submit a certificate to any log 🫶 but to make sure every logged cert can be traced back to whoever issued it, the log SHALL publish a list of acceptable root certificates 📜 (honestly this list could just be the union of the root certificates that major browser vendors trust, it's giving consistency 💅). Each submitted certificate MUST be accompanied by all the additional certificates needed to verify the chain up to an accepted root certificate. The root certificate itself MAY be left out of the chain sent to the log server 🌸
Now for the plot twist. Certificate authorities, root or intermediate, can submit a certificate to logs before they issue it 🔮 This is called a Precertificate. You build it from the certificate that's about to be issued by adding a special critical poison extension (OID 1.3.6.1.4.1.11129.2.4.3, whose extnValue OCTET STRING contains ASN.1 NULL data 0x05 0x00) to the end-entity TBSCertificate. The poison is there so a standard X.509v3 client can't validate the Precertificate 🙅♀️ Then you sign the resulting TBSCertificate [RFC5280] with either:
- a special-purpose Precertificate Signing Certificate (CA:true, Extended Key Usage: Certificate Transparency, OID
1.3.6.1.4.1.11129.2.4.4). This MUST be directly certified by the (root or intermediate) CA certificate that will ultimately sign the end-entity TBSCertificate to produce the end-entity certificate. The log might relax standard validation rules to allow this, as long as the issued certificate will be valid, so that's a vibe check 💜 - or the CA certificate that will sign the final certificate.
As above, the Precertificate submission MUST be accompanied by the Precertificate Signing Certificate, if one is used, and by all the additional certificates needed to verify the chain up to an accepted root certificate. The signature on the TBSCertificate shows the certificate authority's intent to issue a certificate, and that intent is binding 😤 (so misissuing the Precertificate counts as misissuing the final certificate, no excuses). Each log verifies the Precertificate signature chain and then issues a Signed Certificate Timestamp on the matching TBSCertificate ✨
Logs MUST verify that the submitted end-entity certificate or Precertificate has a valid signature chain that leads back to a trusted root CA certificate, using the chain of intermediate CA certificates the submitter provided. Logs MAY accept certificates that have expired, are not yet valid, have been revoked, or are otherwise not fully valid under X.509 verification rules, just to handle quirks in CA certificate-issuing software 🙈 However, logs MUST refuse to publish certificates without a valid chain to a known root CA 🚫 If a certificate is accepted and an SCT is issued, the accepting log MUST store the entire chain used for verification, including the certificate or Precertificate itself and the root certificate used to verify the chain (even if it was left out of the submission). It MUST also present this chain for auditing when asked. This chain is required to stop a CA from dodging blame by logging a partial or empty chain 🕵️♀️ (Note: This effectively excludes self-signed and DANE-based certificates until some mechanism to control spam for those certificates is found. The authors welcome suggestions.)
Each certificate entry in a log MUST include the following components:
enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType;
struct {
LogEntryType entry_type;
select (entry_type) {
case x509_entry: X509ChainEntry;
case precert_entry: PrecertChainEntry;
} entry;
} LogEntry;
opaque ASN.1Cert<1..2^24-1>;
struct {
ASN.1Cert leaf_certificate;
ASN.1Cert certificate_chain<0..2^24-1>;
} X509ChainEntry;
struct {
ASN.1Cert pre_certificate;
ASN.1Cert precertificate_chain<0..2^24-1>;
} PrecertChainEntry;Logs MAY limit the length of chain they will accept 📏
"entry_type" is the type of this entry 🎀 Future revisions of this protocol version may add new LogEntryType values. Section 4 explains how clients should handle unknown entry types.
"leaf_certificate" is the end-entity certificate submitted for auditing 🍓
"certificate_chain" is a chain of additional certificates needed to verify the end-entity certificate. The first certificate MUST certify the end-entity certificate. Each following certificate MUST directly certify the one before it. The final certificate MUST be a root certificate accepted by the log 🌈
"pre_certificate" is the Precertificate submitted for auditing 🧚
"precertificate_chain" is a chain of additional certificates needed to verify the Precertificate submission. The first certificate MAY be a valid Precertificate Signing Certificate, and it MUST certify the first certificate. Each following certificate MUST directly certify the one before it. The final certificate MUST be a root certificate accepted by the log 💅
3.2. Structure of the Signed Certificate Timestamp 🦋
enum { certificate_timestamp(0), tree_hash(1), (255) }
SignatureType;
enum { v1(0), (255) }
Version;
struct {
opaque key_id[32];
} LogID;
opaque TBSCertificate<1..2^24-1>;
struct {
opaque issuer_key_hash[32];
TBSCertificate tbs_certificate;
} PreCert;
opaque CtExtensions<0..2^16-1>;"key_id" is the SHA-256 hash of the log's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo 🔐
"issuer_key_hash" is the SHA-256 hash of the certificate issuer's public key, calculated over the DER encoding of the key represented as SubjectPublicKeyInfo. This is needed to bind the issuer to the final certificate 🔗
"tbs_certificate" is the DER-encoded TBSCertificate (see [RFC5280]) component of the Precertificate. That means it's without the signature and without the poison extension 🫧 If the Precertificate is not signed with the CA certificate that will issue the final certificate, then the TBSCertificate also has its issuer changed to match that of the CA that will issue the final certificate. You can also rebuild this TBSCertificate from the final certificate by pulling out the TBSCertificate and deleting the SCT extension. Also, since the TBSCertificate contains an AlgorithmIdentifier that has to match both the Precertificate signature algorithm and the final certificate signature algorithm, they have to be signed with the same algorithm and parameters 🤓 If the Precertificate is issued using a Precertificate Signing Certificate and an Authority Key Identifier extension is present in the TBSCertificate, the matching extension also has to be present in the Precertificate Signing Certificate. In that case, the TBSCertificate also has its Authority Key Identifier changed to match the final issuer 🎯
struct {
Version sct_version;
LogID id;
uint64 timestamp;
CtExtensions extensions;
digitally-signed struct {
Version sct_version;
SignatureType signature_type = certificate_timestamp;
uint64 timestamp;
LogEntryType entry_type;
select(entry_type) {
case x509_entry: ASN.1Cert;
case precert_entry: PreCert;
} signed_entry;
CtExtensions extensions;
};
} SignedCertificateTimestamp;The encoding of the digitally-signed element is defined in [RFC5246] 📖
"sct_version" is the version of the protocol that the SCT conforms to. This version is v1 💜
"timestamp" is the current NTP Time [RFC5905], measured since the epoch (January 1, 1970, 00:00), ignoring leap seconds, in milliseconds ⏰
"entry_type" may be implicit from the context in which the SCT is presented 🌸
"signed_entry" is the "leaf_certificate" (in the case of an X509ChainEntry) or the PreCert (in the case of a PrecertChainEntry), as described above 🍓
"extensions" are future extensions to this protocol version (v1). Currently, no extensions are specified 🧚
3.3. Including the Signed Certificate Timestamp in the TLS Handshake 🤝
The SCT data for the end-entity certificate from at least one log must be included in the TLS handshake 🫶 You can do that with an X509v3 certificate extension (more on that below), with a TLS extension (Section 7.4.1.4 of [RFC5246]) of type "signed_certificate_timestamp", or with Online Certificate Status Protocol (OCSP) Stapling (also called the "Certificate Status Request" TLS extension; see [RFC6066]). For OCSP stapling, the response has an OCSP extension with OID 1.3.6.1.4.1.11129.2.4.5 (see [RFC2560]) and a body of:
SignedCertificateTimestampList ::= OCTET STRINGAt least one SCT MUST be included. Server operators MAY include more than one SCT 🎀
Similarly, a certificate authority MAY submit a Precertificate to more than one log. All the SCTs it gets can be embedded straight into the final certificate. You encode the SignedCertificateTimestampList structure as an ASN.1 OCTET STRING and insert the result into the TBSCertificate as an X.509v3 certificate extension (OID 1.3.6.1.4.1.11129.2.4.2) 🧁 When clients receive the certificate, they can rebuild the original TBSCertificate to verify the SCT signature 🔍
The contents of the ASN.1 OCTET STRING embedded in an OCSP extension or X509v3 certificate extension look like this:
opaque SerializedSCT<1..2^16-1>;
struct {
SerializedSCT sct_list <1..2^16-1>;
} SignedCertificateTimestampList;Here, "SerializedSCT" is an opaque byte string that holds the serialized TLS structure. This encoding means TLS clients can decode each SCT on its own. If there's a version upgrade, out-of-date clients can still parse the old SCTs and skip over new ones whose versions they don't understand 🦋
SCTs can also be embedded in a TLS extension. See below for details 💖
TLS clients MUST implement all three mechanisms. Servers MUST implement at least one of the three mechanisms. Good news: existing TLS servers can usually use the certificate extension mechanism without any changes 🙌
TLS servers should send SCTs from multiple logs in case one or more logs aren't acceptable to the client. For example, a log might have been struck off for misbehavior or might have had a key compromise 😭
3.3.1. TLS Extension 🌟
The SCT can be sent during the TLS handshake using a TLS extension with type "signed_certificate_timestamp" 🫧
Clients that support the extension SHOULD send a ClientHello extension with the appropriate type and an empty "extension_data" 💅
Servers MUST only send SCTs to clients who have indicated support for the extension in the ClientHello. When they do, the SCTs are sent by setting "extension_data" to a "SignedCertificateTimestampList" 🎁
Session resumption uses the original session information. Clients SHOULD include the extension type in the ClientHello, but if the session is resumed, the server isn't expected to process it or include the extension in the ServerHello. Main character energy for the original session, honestly 👑
3.4. Merkle Tree 🌳✨
okay so the hashing algorithm for the Merkle Tree Hash is SHA-256 💅 Here's how the Merkle Tree input is structured:
enum { timestamped_entry(0), (255) }
MerkleLeafType;
struct {
uint64 timestamp;
LogEntryType entry_type;
select(entry_type) {
case x509_entry: ASN.1Cert;
case precert_entry: PreCert;
} signed_entry;
CtExtensions extensions;
} TimestampedEntry;
struct {
Version version;
MerkleLeafType leaf_type;
select (leaf_type) {
case timestamped_entry: TimestampedEntry;
}
} MerkleTreeLeaf;Here's the breakdown, bestie 🫶
versionis the protocol version that theMerkleTreeLeafmatches. For this one, it's v1 🎀leaf_typeis the type of the leaf input. Right now the only one defined istimestamped_entry, which corresponds to an SCT 🦋 Future revisions of this protocol version may add newMerkleLeafTypetypes, and [Section 4](#4-log-client-messages-✨) explains how clients should handle unknown leaf types.timestampis the timestamp of the matching SCT that was issued for this certificate ⏰signed_entryis thesigned_entryof that same SCT 💖extensionsare theextensionsof that same SCT ✨
The leaves of the Merkle Tree are the leaf hashes of the matching MerkleTreeLeaf structures. Iconic, honestly 👑
3.5. Signed Tree Head 🌸
every time a log adds new entries to the tree, it SHOULD sign the matching tree hash and tree information (check out the Signed Tree Head client message in Section 4.3 for the bigger picture 🧚). The signature data is structured like this:
digitally-signed struct {
Version version;
SignatureType signature_type = tree_hash;
uint64 timestamp;
uint64 tree_size;
opaque sha256_root_hash[32];
} TreeHeadSignature;versionis the protocol version theTreeHeadSignatureconforms to. Again, that's v1 🍓timestampis the current time. It MUST be at least as recent as the most recent SCT timestamp in the tree, and every later timestamp MUST be more recent than the timestamp of the previous update ⏰💅tree_sizeequals the number of entries in the new tree 🌳sha256_root_hashis the root of the Merkle Hash Tree 🔥
Each log MUST produce, on demand, a Signed Tree Head that is no older than the Maximum Merge Delay. Now, in the unlikely event that it gets zero new submissions during an MMD period, the log SHALL sign the same Merkle Tree Hash with a fresh timestamp. Not me being the one who refreshes it 🙈
4. Log Client Messages ✨
the messages get sent as HTTPS GET or POST requests 💌 POST parameters and all responses are encoded as JavaScript Object Notation (JSON) objects [RFC4627]. GET parameters are encoded as order-independent key/value URL parameters, using the "application/x-www-form-urlencoded" format from the "HTML 4.01 Specification" [HTML401]. Binary data gets base64 encoded [RFC4648], as specified in each individual message 🧁
Note that JSON objects and URL parameters might contain fields that aren't specified here. These extra fields should be ignored 🙅♀️
The <log server> prefix can include a path as well as a server name and a port 🌈
In general, where it's needed, the "version" is v1 and the "id" is the log id for the log server you queried 🎀
Any errors come back as HTTP 4xx or 5xx responses, with human-readable error messages 😭
4.1. Add Chain to Log 🔗
the request is POST https://<log server>/ct/v1/add-chain
Inputs:
chain: an array of base64-encoded certificates. The first element is the end-entity certificate, the second chains to the first, and so on down to the last one, which is either the root certificate or a certificate that chains to a known root certificate 🌳
Outputs:
sct_version: the version of the SignedCertificateTimestamp structure, in decimal. A compliant v1 implementation MUST NOT expect this to be 0 (i.e., v1) 🙅♀️id: the log ID, base64 encoded. Log clients who request an SCT for TLS handshakes aren't required to verify it, so we don't assume they know the log's ID 🦋timestamp: the SCT timestamp, in decimal ⏰extensions: an opaque type for future expansion. It's likely that not all participants will need to understand the data in this field. Logs should set this to the empty string, and clients should decode the base64-encoded data and include it in the SCT 💜signature: the SCT signature, base64 encoded ✨
If the sct_version isn't v1, a v1 client might be unable to verify the signature. It MUST NOT construe this as an error. (Side note, bestie: log clients don't need to be able to verify this structure, only TLS clients do. If we served the structure as a binary blob, we could completely change it without requiring an upgrade to v1 clients. Big brain move 🧠)
4.2. Add PreCertChain to Log 🪄
the request is POST https://<log server>/ct/v1/add-pre-chain
Inputs:
chain: an array of base64-encoded Precertificates. The first element is the end-entity certificate, the second chains to the first, and so on down to the last one, which is either the root certificate or a certificate that chains to a known root certificate 🌸
Outputs are the same as in Section 4.1 💅
4.3. Retrieve Latest Signed Tree Head 👀
the request is GET https://<log server>/ct/v1/get-sth
No inputs, easy 🥰
Outputs:
tree_size: the size of the tree, in entries, in decimal 🌳timestamp: the timestamp, in decimal ⏰sha256_root_hash: the Merkle Tree Hash of the tree, in base64 🔥tree_head_signature: a TreeHeadSignature for the data above 🦋
4.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads 🧩
the request is GET https://<log server>/ct/v1/get-sth-consistency
Inputs:
first: the tree_size of the first tree, in decimal 🍓second: the tree_size of the second tree, in decimal 🍓
Both tree sizes must be from existing v1 STHs (Signed Tree Heads) 🎀
Outputs:
consistency: an array of Merkle Tree nodes, base64 encoded 💖
No signature is needed on this data, because it's used to verify an STH, and the STH itself is signed. Very clever, very neat 💅
4.5. Retrieve Merkle Audit Proof from Log by Leaf Hash 🔍
the request is GET https://<log server>/ct/v1/get-proof-by-hash
Inputs:
hash: a base64-encoded v1 leaf hash 🧷tree_size: the tree_size of the tree the proof should be based on, in decimal 🌳
The "hash" must be calculated as defined in Section 3.4, and the "tree_size" must designate an existing v1 STH 🫶
Outputs:
leaf_index: the 0-based index of the end entity that matches the "hash" parameter 🎯audit_path: an array of base64-encoded Merkle Tree nodes proving the inclusion of the chosen certificate 🧚
4.6. Retrieve Entries from Log 📚
the request is GET https://<log server>/ct/v1/get-entries
Inputs:
start: the 0-based index of the first entry to retrieve, in decimal 🌷end: the 0-based index of the last entry to retrieve, in decimal 🌷
Outputs:
entries: an array of objects, each consisting of:leaf_input: the base64-encoded MerkleTreeLeaf structure 🍃extra_data: the base64-encoded unsigned data for the log entry. For an X509ChainEntry, this is the "certificate_chain". For a PrecertChainEntry, this is the whole "PrecertChainEntry" 💜
This message isn't signed, which is fine, because you can verify the retrieved data by building the Merkle Tree Hash that matches a retrieved STH. All leaves MUST be v1. Still, a compliant v1 client MUST NOT construe an unrecognized MerkleLeafType or LogEntryType value as an error. That means it might not be able to parse some entries, but each client can inspect the entries it does recognize and verify the integrity of the data by treating unrecognized leaves as opaque input to the tree 🧠✨
The "start" and "end" parameters SHOULD be within the range 0 <= x < "tree_size", as returned by "get-sth" in Section 4.3 🎀
Logs MAY honor requests where 0 <= "start" < "tree_size" and "end" >= "tree_size", by returning a partial response that covers only the valid entries in the specified range. Note that the following restriction may also apply:
Logs MAY restrict the number of entries that can be retrieved per "get-entries" request. If a client asks for more than the permitted number of entries, the log SHALL return the maximum number of entries permissible. Those entries SHALL be sequential, beginning with the entry specified by "start" 🌊
4.7. Retrieve Accepted Root Certificates 🏛️
the request is GET https://<log server>/ct/v1/get-roots
No inputs 🫶
Outputs:
certificates: an array of base64-encoded root certificates that are acceptable to the log 👑
4.8. Retrieve Entry+Merkle Audit Proof from Log 🧾
the request is GET https://<log server>/ct/v1/get-entry-and-proof
Inputs:
leaf_index: the index of the desired entry 🎯tree_size: the tree_size of the tree the proof is wanted for 🌳
The tree size must designate an existing STH 🫶
Outputs:
leaf_input: the base64-encoded MerkleTreeLeaf structure 🍃extra_data: the base64-encoded unsigned data, same as in Section 4.6 💖audit_path: an array of base64-encoded Merkle Tree nodes proving the inclusion of the chosen certificate 🧚
This API is probably only useful for debugging 🛠️💀
5. Clients 💫
there are a bunch of different functions that log clients might perform. We'll go over some typical clients and how they could work. Any inconsistency can be used as evidence that a log hasn't behaved correctly, and the signatures on the data structures stop the log from denying that misbehavior. Caught in 4K 📸
All clients should gossip with each other, exchanging STHs at least. That's all it takes to make sure they all have a consistent view 🫶 The exact gossip mechanism will be described in a separate document, but there's expected to be a variety of them 🌈
5.1. Submitters 📮
Submitters send certificates or Precertificates to the log, as described above. They can then use the returned SCT to build a certificate or use it directly in a TLS handshake 💌
5.2. TLS Client 🔐
TLS clients aren't directly clients of the log, but they receive SCTs alongside or inside server certificates. On top of the normal validation of the certificate and its chain, they should validate the SCT. To do that, they compute the signature input from the SCT data and the certificate, then verify the signature using the corresponding log's public key. This document doesn't describe how clients get the logs' public keys, so that's a separate convo 🗝️
TLS clients MUST reject SCTs whose timestamp is in the future. No time travel allowed, periodt ⏳🙅♀️
5.3. Monitor 🦋
Okay so monitors are the ones who watch logs and make sure they're behaving 👀. They also keep an eye out for certificates of interest 💅
A monitor needs to, at least, inspect every new entry in each log it watches, bestie 😭. It may also want to keep copies of entire logs. To do this, it should follow these steps for each log:
- Fetch the current STH (Section 4.3).
- Verify the STH signature.
- Fetch all the entries in the tree corresponding to the STH (Section 4.6).
- Confirm that the tree made from the fetched entries produces the same hash as that in the STH.
- Fetch the current STH (Section 4.3). Repeat until the STH changes.
- Verify the STH signature.
- Fetch all the new entries in the tree corresponding to the STH (Section 4.6). If they remain unavailable for an extended period, then this should be viewed as misbehavior on the part of the log. 🚩
- Either:
- Verify that the updated list of all entries generates a tree with the same hash as the new STH.
Or, if it is not keeping all log entries:
- Fetch a consistency proof for the new STH with the previous STH (Section 4.4).
- Verify the consistency proof.
- Verify that the new entries generate the corresponding elements in the consistency proof.
- Go to Step 5. 🔁
5.4. Auditor 🔍
Auditors take partial info about a log as input and check that it's consistent with other partial info they already have. An auditor might be an integral part of a TLS client 🎀, a standalone service 🧚, or a secondary job of a monitor.
Any pair of STHs from the same log can be verified by requesting a consistency proof (Section 4.4).
A certificate accompanied by an SCT can be verified against any STH dated after the SCT timestamp + the Maximum Merge Delay by requesting a Merkle audit proof (Section 4.5). ✨
Auditors can fetch STHs from time to time of their own accord, of course (Section 4.3). 🌸
6. IANA Considerations 🌷
IANA has allocated an RFC 5246 ExtensionType value (18) for the SCT TLS extension. The extension name is signed_certificate_timestamp. 🍓
7. Security Considerations 🔐
With CAs, logs, and servers performing the actions described here, TLS clients can use logs and signed timestamps to reduce the likelihood that they will accept misissued certificates. If a server presents a valid signed timestamp for a certificate, then the client knows that the certificate has been published in a log. From this, the client knows that the subject of the certificate has had some time to notice the misissue and take some action, such as asking a CA to revoke a misissued certificate. A signed timestamp is not a guarantee that the certificate is not misissued, since the subject of the certificate might not have checked the logs or the CA might have refused to revoke the certificate. 😬
In addition, if TLS clients will not accept unlogged certificates, then site owners will have a greater incentive to submit certificates to logs, possibly with the assistance of their CA, increasing the overall transparency of the system. 💜
7.1. Misissued Certificates 🚫
Misissued certificates that have not been publicly logged, and thus do not have a valid SCT, will be rejected by TLS clients. Misissued certificates that do have an SCT from a log will appear in that public log within the Maximum Merge Delay, assuming the log is operating correctly. Thus, the maximum period of time during which a misissued certificate can be used without being available for audit is the MMD. ⏳
7.2. Detection of Misissue 👀
The logs do not themselves detect misissued certificates; they rely instead on interested parties, such as domain owners, to monitor them and take corrective action when a misissue is detected. Not the logs doing the detective work, bestie 💀.
7.3. Misbehaving Logs 🚨
A log can misbehave in two ways: (1) by failing to incorporate a certificate with an SCT in the Merkle Tree within the MMD and (2) by violating its append-only property by presenting two different, conflicting views of the Merkle Tree at different times and/or to different parties. Both forms of violation will be promptly and publicly detectable. 🔥
Misbehaving logs are seriously iconic in the wrong way, so keep an eye out 👁️
Violation of the MMD contract is detected by log clients requesting a Merkle audit proof for each observed SCT. These checks can be asynchronous and need only be done once per each certificate. In order to protect the clients' privacy, these checks need not reveal the exact certificate to the log. Clients can instead request the proof from a trusted auditor (since anyone can compute the audit proofs from the log) or request Merkle proofs for a batch of certificates around the SCT timestamp. 🛡️
Violation of the append-only property is detected by global gossiping, i.e., everyone auditing logs comparing their versions of the latest Signed Tree Heads. As soon as two conflicting Signed Tree Heads for the same log are detected, this is cryptographic proof of that log's misbehavior. 🧾
8. Efficiency Considerations ⚡
The Merkle Tree design serves the purpose of keeping communication overhead low. 🎀
Auditing logs for integrity does not require third parties to maintain a copy of each entire log. The Signed Tree Heads can be updated as new entries become available, without recomputing entire trees. Third-party auditors need only fetch the Merkle consistency proofs against a log's existing STH to efficiently verify the append-only property of updates to their Merkle Trees, without auditing the entire tree. Lowkey so smart 🧠✨
9. Future Changes 🔮
This section lists things we might address in a Standards Track version of this document.
- Rather than forcing a log operator to create a new log in order to change the log signing key, we may allow some key roll mechanism. 🔑
- We may add hash and signing algorithm agility.
- We may describe some gossip protocols.
10. Acknowledgements 🫶
The authors would like to thank Erwann Abelea, Robin Alden, Al Cutter, Francis Dupont, Stephen Farrell, Brad Hill, Jeff Hodges, Paul Hoffman, Jeffrey Hutzelman, SM, Alexey Melnikov, Chris Palmer, Trevor Perrin, Ryan Sleevi, Rob Stradling, and Carl Wallace for their valuable contributions. The whole squad 💖
11. References 📚
11.1. Normative Reference
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.11.2. Informative References
[CrosbyWallach] Crosby, S. and D. Wallach, "Efficient Data
Structures for Tamper-Evident Logging", Proceedings
of the 18th USENIX Security Symposium, Montreal,
August 2009, <http://static.usenix.org/event/sec09/
tech/full_papers/crosby.pdf>.
[DSS] National Institute of Standards and Technology,
"Digital Signature Standard (DSS)", FIPS 186-3,
June 2009, <http://csrc.nist.gov/publications/fips/
fips186-3/fips_186-3.pdf>.
[FIPS.180-4] National Institute of Standards and Technology,
"Secure Hash Standard", FIPS PUB 180-4, March 2012,
<http://csrc.nist.gov/publications/fips/fips180-4/
fips-180-4.pdf>.
[HTML401] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01
Specification", World Wide Web Consortium
Recommendation REC-html401-19991224, December 1999,
<http://www.w3.org/TR/1999/REC-html401-19991224>.
[RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S.,
and C. Adams, "X.509 Internet Public Key
Infrastructure Online Certificate Status Protocol -
OCSP", RFC 2560, June 1999.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627,
July 2006.
[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data
Encodings", RFC 4648, October 2006.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer
Security (TLS) Protocol Version 1.2", RFC 5246,
August 2008.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S.,
Housley, R., and W. Polk, "Internet X.509 Public Key
Infrastructure Certificate and Certificate
Revocation List (CRL) Profile", RFC 5280, May 2008.
[RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch,
"Network Time Protocol Version 4: Protocol and
Algorithms Specification", RFC 5905, June 2010.
[RFC6066] Eastlake, D., "Transport Layer Security (TLS)
Extensions: Extension Definitions", RFC 6066,
January 2011.Authors' Addresses 🎀
Ben Laurie
Google UK Ltd.
EMail: benl@google.com
Adam Langley
Google Inc.
EMail: agl@google.com
Emilia Kasper
Google Switzerland GmbH
EMail: ekasper@google.comAnd that's the whole spec, bestie! 🌈💅 Thanks for hanging with me through all five parts 🧚💖
📦 where this page comes from
- ietf: rfc6962 2013-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms