draft-ietf-trans-rfc6962-bis-07.txt   draft-ietf-trans-rfc6962-bis-08.txt 
Public Notary Transparency Working Group B. Laurie Public Notary Transparency Working Group B. Laurie
Internet-Draft A. Langley Internet-Draft A. Langley
Intended status: Standards Track E. Kasper Intended status: Standards Track E. Kasper
Expires: September 10, 2015 E. Messeri Expires: January 7, 2016 E. Messeri
Google Google
R. Stradling R. Stradling
Comodo Comodo
March 9, 2015 July 6, 2015
Certificate Transparency Certificate Transparency
draft-ietf-trans-rfc6962-bis-07 draft-ietf-trans-rfc6962-bis-08
Abstract Abstract
This document describes a protocol for publicly logging the existence This document describes a protocol for publicly logging the existence
of Transport Layer Security (TLS) certificates as they are issued or of Transport Layer Security (TLS) certificates as they are issued or
observed, in a manner that allows anyone to audit certification observed, in a manner that allows anyone to audit certification
authority (CA) activity and notice the issuance of suspect authority (CA) activity and notice the issuance of suspect
certificates as well as to audit the certificate logs themselves. certificates as well as to audit the certificate logs themselves.
The intent is that eventually clients would refuse to honor The intent is that eventually clients would refuse to honor
certificates that do not appear in a log, effectively forcing CAs to certificates that do not appear in a log, effectively forcing CAs to
skipping to change at page 1, line 44 skipping to change at page 1, line 44
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 10, 2015. This Internet-Draft will expire on January 7, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 25 skipping to change at page 2, line 25
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4
1.2. Data Structures . . . . . . . . . . . . . . . . . . . . . 4 1.2. Data Structures . . . . . . . . . . . . . . . . . . . . . 4
2. Cryptographic Components . . . . . . . . . . . . . . . . . . 4 2. Cryptographic Components . . . . . . . . . . . . . . . . . . 5
2.1. Merkle Hash Trees . . . . . . . . . . . . . . . . . . . . 5 2.1. Merkle Hash Trees . . . . . . . . . . . . . . . . . . . . 5
2.1.1. Merkle Inclusion Proofs . . . . . . . . . . . . . . . 5 2.1.1. Merkle Inclusion Proofs . . . . . . . . . . . . . . . 5
2.1.2. Merkle Consistency Proofs . . . . . . . . . . . . . . 6 2.1.2. Merkle Consistency Proofs . . . . . . . . . . . . . . 6
2.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 7 2.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 7
2.1.4. Signatures . . . . . . . . . . . . . . . . . . . . . 9 2.1.4. Signatures . . . . . . . . . . . . . . . . . . . . . 9
3. Log Format and Operation . . . . . . . . . . . . . . . . . . 9 3. Log Format and Operation . . . . . . . . . . . . . . . . . . 10
3.1. Log Entries . . . . . . . . . . . . . . . . . . . . . . . 9 3.1. Log Entries . . . . . . . . . . . . . . . . . . . . . . . 10
3.2. Private Domain Name Labels . . . . . . . . . . . . . . . 12 3.2. Private Domain Name Labels . . . . . . . . . . . . . . . 12
3.2.1. Wildcard Certificates . . . . . . . . . . . . . . . . 12 3.2.1. Wildcard Certificates . . . . . . . . . . . . . . . . 13
3.2.2. Redacting Domain Name Labels in Precertificates . . . 12 3.2.2. Redacting Domain Name Labels in Precertificates . . . 13
3.2.3. Using a Name-Constrained Intermediate CA . . . . . . 13 3.2.3. Using a Name-Constrained Intermediate CA . . . . . . 14
3.3. Structure of the Signed Certificate Timestamp . . . . . . 14 3.3. Structure of the Signed Certificate Timestamp . . . . . . 15
3.4. Including the Signed Certificate Timestamp in the TLS 3.4. Including the Signed Certificate Timestamp in the TLS
Handshake . . . . . . . . . . . . . . . . . . . . . . . . 15 Handshake . . . . . . . . . . . . . . . . . . . . . . . . 17
3.4.1. TLS Extension . . . . . . . . . . . . . . . . . . . . 16 3.4.1. TLS Extension . . . . . . . . . . . . . . . . . . . . 18
3.4.2. X.509v3 Extension . . . . . . . . . . . . . . . . . . 17 3.4.2. X.509v3 Extension . . . . . . . . . . . . . . . . . . 18
3.5. Merkle Tree . . . . . . . . . . . . . . . . . . . . . . . 17 3.5. Merkle Tree . . . . . . . . . . . . . . . . . . . . . . . 19
3.6. Signed Tree Head . . . . . . . . . . . . . . . . . . . . 18 3.6. Signed Tree Head . . . . . . . . . . . . . . . . . . . . 20
4. Log Client Messages . . . . . . . . . . . . . . . . . . . . . 19 4. Log Client Messages . . . . . . . . . . . . . . . . . . . . . 20
4.1. Add Chain to Log . . . . . . . . . . . . . . . . . . . . 21 4.1. Add Chain to Log . . . . . . . . . . . . . . . . . . . . 22
4.2. Add PreCertChain to Log . . . . . . . . . . . . . . . . . 22 4.2. Add PreCertChain to Log . . . . . . . . . . . . . . . . . 23
4.3. Retrieve Latest Signed Tree Head . . . . . . . . . . . . 22 4.3. Retrieve Latest Signed Tree Head . . . . . . . . . . . . 23
4.4. Retrieve Merkle Consistency Proof between Two Signed Tree 4.4. Retrieve Merkle Consistency Proof between Two Signed Tree
Heads . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Heads . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash . . 23 4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash . . 25
4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and 4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and
Consistency Proof by Leaf Hash . . . . . . . . . . . . . 24 Consistency Proof by Leaf Hash . . . . . . . . . . . . . 26
4.7. Retrieve Entries from Log . . . . . . . . . . . . . . . . 25 4.7. Retrieve Entries and STH from Log . . . . . . . . . . . . 27
4.8. Retrieve Accepted Root Certificates . . . . . . . . . . . 26 4.8. Retrieve Accepted Root Certificates . . . . . . . . . . . 28
5. Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5. Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.1. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 27 5.1. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 29
5.2. Submitters . . . . . . . . . . . . . . . . . . . . . . . 28 5.2. Submitters . . . . . . . . . . . . . . . . . . . . . . . 30
5.3. TLS Client . . . . . . . . . . . . . . . . . . . . . . . 28 5.3. TLS Client . . . . . . . . . . . . . . . . . . . . . . . 30
5.4. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 28 5.4. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.5. Auditing . . . . . . . . . . . . . . . . . . . . . . . . 29 5.5. Auditing . . . . . . . . . . . . . . . . . . . . . . . . 31
6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . . . 30 5.5.1. Verifying an inclusion proof . . . . . . . . . . . . 32
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 5.5.2. Verifying consistency between two STHs . . . . . . . 32
7.1. TLS Extension Type . . . . . . . . . . . . . . . . . . . 30 5.5.3. Verifying root hash given entries . . . . . . . . . . 33
7.2. Hash Algorithms . . . . . . . . . . . . . . . . . . . . . 30 6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . . . 34
8. Security Considerations . . . . . . . . . . . . . . . . . . . 30 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34
8.1. Misissued Certificates . . . . . . . . . . . . . . . . . 31 7.1. TLS Extension Type . . . . . . . . . . . . . . . . . . . 34
8.2. Detection of Misissue . . . . . . . . . . . . . . . . . . 31 7.2. Hash Algorithms . . . . . . . . . . . . . . . . . . . . . 34
8.3. Redaction of Public Domain Name Labels . . . . . . . . . 31 8. Security Considerations . . . . . . . . . . . . . . . . . . . 34
8.4. Misbehaving Logs . . . . . . . . . . . . . . . . . . . . 31 8.1. Misissued Certificates . . . . . . . . . . . . . . . . . 35
8.5. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . . 32 8.2. Detection of Misissue . . . . . . . . . . . . . . . . . . 35
9. Efficiency Considerations . . . . . . . . . . . . . . . . . . 32 8.3. Redaction of Public Domain Name Labels . . . . . . . . . 35
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 33 8.4. Misbehaving Logs . . . . . . . . . . . . . . . . . . . . 36
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 8.5. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . . 36
11.1. Normative References . . . . . . . . . . . . . . . . . . 33 9. Efficiency Considerations . . . . . . . . . . . . . . . . . . 37
11.2. Informative References . . . . . . . . . . . . . . . . . 34 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 37
11.1. Normative References . . . . . . . . . . . . . . . . . . 37
11.2. Informative References . . . . . . . . . . . . . . . . . 38
1. Introduction 1. Introduction
Certificate transparency aims to mitigate the problem of misissued Certificate transparency aims to mitigate the problem of misissued
certificates by providing publicly auditable, append-only, untrusted certificates by providing publicly auditable, append-only, untrusted
logs of all issued certificates. The logs are publicly auditable so logs of all issued certificates. The logs are publicly auditable so
that it is possible for anyone to verify the correctness of each log that it is possible for anyone to verify the correctness of each log
and to monitor when new certificates are added to it. The logs do and to monitor when new certificates are added to it. The logs do
not themselves prevent misissue, but they ensure that interested not themselves prevent misissue, but they ensure that interested
parties (particularly those named in certificates) can detect such parties (particularly those named in certificates) can detect such
skipping to change at page 5, line 4 skipping to change at page 5, line 6
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
1.2. Data Structures 1.2. Data Structures
Data structures are defined according to the conventions laid out in Data structures are defined according to the conventions laid out in
Section 4 of [RFC5246]. Section 4 of [RFC5246].
2. Cryptographic Components 2. Cryptographic Components
2.1. Merkle Hash Trees 2.1. Merkle Hash Trees
Logs use a binary Merkle Hash Tree for efficient auditing. The Logs use a binary Merkle Hash Tree for efficient auditing. The
hashing algorithm used by each log is expected to be specified as hashing algorithm used by each log is expected to be specified as
part of the metadata relating to that log. We have established a part of the metadata relating to that log. We have established a
registry of acceptable algorithms, see Section 7.2. The hashing registry of acceptable algorithms, see Section 7.2. The hashing
algorithm in use is referred to as HASH throughout this document. algorithm in use is referred to as HASH throughout this document and
The input to the Merkle Tree Hash is a list of data entries; these the size of its output in bytes as HASH_SIZE. The input to the
entries will be hashed to form the leaves of the Merkle Hash Tree. Merkle Tree Hash is a list of data entries; these entries will be
The output is a single 32-byte Merkle Tree Hash. Given an ordered hashed to form the leaves of the Merkle Hash Tree. The output is a
list of n inputs, D[n] = {d(0), d(1), ..., d(n-1)}, the Merkle Tree single HASH_SIZE Merkle Tree Hash. Given an ordered list of n
Hash (MTH) is thus defined as follows: inputs, D[n] = {d(0), d(1), ..., d(n-1)}, the Merkle Tree Hash (MTH)
is thus defined as follows:
The hash of an empty list is the hash of an empty string: The hash of an empty list is the hash of an empty string:
MTH({}) = HASH(). MTH({}) = HASH().
The hash of a list with one entry (also known as a leaf hash) is: The hash of a list with one entry (also known as a leaf hash) is:
MTH({d(0)}) = HASH(0x00 || d(0)). MTH({d(0)}) = HASH(0x00 || d(0)).
For n > 1, let k be the largest power of two smaller than n (i.e., k For n > 1, let k be the largest power of two smaller than n (i.e., k
skipping to change at page 9, line 7 skipping to change at page 9, line 44
The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l]. The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l].
hash can be verified using hash1=k and l. hash can be verified using hash1=k and l.
The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i, The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i,
j, k]. k, i are used to verify hash2, and j is additionally used to j, k]. k, i are used to verify hash2, and j is additionally used to
show hash is consistent with hash2. show hash is consistent with hash2.
2.1.4. Signatures 2.1.4. Signatures
Various data structures are signed. A log MUST use either elliptic Various data structures are signed. A log MUST use either
curve signatures using the NIST P-256 curve (Section D.1.2.3 of the deterministic ECDSA [RFC6979] using the NIST P-256 curve
Digital Signature Standard [DSS]) or RSA signatures (RSASSA- (Section D.1.2.3 of the Digital Signature Standard [DSS]) and HMAC-
PKCS1-v1_5 with SHA-256, Section 8.2 of [RFC3447]) using a key of at SHA256 or RSA signatures (RSASSA-PKCS1-v1_5 with SHA-256, Section 8.2
least 2048 bits. of [RFC3447]) using a key of at least 2048 bits.
3. Log Format and Operation 3. Log Format and Operation
Anyone can submit certificates to certificate logs for public Anyone can submit certificates to certificate logs for public
auditing; however, since certificates will not be accepted by TLS auditing; however, since certificates will not be accepted by TLS
clients unless logged, it is expected that certificate owners or clients unless logged, it is expected that certificate owners or
their CAs will usually submit them. A log is a single, ever-growing, their CAs will usually submit them. A log is a single, ever-growing,
append-only Merkle Tree of such certificates. append-only Merkle Tree of such certificates.
When a valid certificate is submitted to a log, the log MUST return a When a valid certificate is submitted to a log, the log MUST return a
skipping to change at page 10, line 30 skipping to change at page 11, line 22
MUST contain a signature from the same (root or intermediate) CA that MUST contain a signature from the same (root or intermediate) CA that
will ultimately issue the certificate. This signature indicates the will ultimately issue the certificate. This signature indicates the
certification authority's intent to issue the certificate. This certification authority's intent to issue the certificate. This
intent is considered binding (i.e., misissuance of the precertificate intent is considered binding (i.e., misissuance of the precertificate
is considered equivalent to misissuance of the certificate). As is considered equivalent to misissuance of the certificate). As
above, the precertificate submission MUST be accompanied by all the above, the precertificate submission MUST be accompanied by all the
additional certificates required to verify the chain up to an additional certificates required to verify the chain up to an
accepted root certificate. This does not involve using the accepted root certificate. This does not involve using the
"SignedData.certificates" field, so that field SHOULD be omitted. "SignedData.certificates" field, so that field SHOULD be omitted.
The CMS object MUST be DER encoded. Note that, because of the
structure of CMS, the signature on the CMS object will not be a valid
X.509v3 signature and so cannot be used to construct a certificate
from the precertificate.
Logs MUST verify that the submitted certificate or precertificate has Logs MUST verify that the submitted certificate or precertificate has
a valid signature chain to an accepted root certificate, using the a valid signature chain to an accepted root certificate, using the
chain of intermediate CA certificates provided by the submitter. chain of intermediate CA certificates provided by the submitter.
Logs MUST accept certificates that are fully valid according to X.509 Logs MUST accept certificates that are fully valid according to RFC
verification rules and are submitted with such a chain. Logs MAY 5280 [RFC5280] verification rules and are submitted with such a
accept certificates and precertificates that have expired, are not chain. Logs MAY accept certificates and precertificates that have
yet valid, have been revoked, or are otherwise not fully valid expired, are not yet valid, have been revoked, or are otherwise not
according to X.509 verification rules in order to accommodate quirks fully valid according to RFC 5280 verification rules in order to
of CA certificate-issuing software. However, logs MUST reject accommodate quirks of CA certificate-issuing software. However, logs
certificates without a valid signature chain to an accepted root MUST reject certificates without a valid signature chain to an
certificate. If a certificate is accepted and an SCT issued, the accepted root certificate. Logs MUST also reject precertificates
accepting log MUST store the entire chain used for verification, that are not valid DER encoded CMS "signed-data" objects. If a
including the certificate or precertificate itself and including the certificate is accepted and an SCT issued, the accepting log MUST
root certificate used to verify the chain (even if it was omitted store the entire chain used for verification, including the
from the submission), and MUST present this chain for auditing upon certificate or precertificate itself and including the root
request. This chain is required to prevent a CA from avoiding blame certificate used to verify the chain (even if it was omitted from the
by logging a partial or empty chain. (Note: This effectively submission), and MUST present this chain for auditing upon request.
excludes self-signed and DANE-based certificates until some mechanism This chain is required to prevent a CA from avoiding blame by logging
to limit the submission of spurious certificates is found. The a partial or empty chain. (Note: This effectively excludes self-
authors welcome suggestions.) signed and DANE-based certificates until some mechanism to limit the
submission of spurious certificates is found. The authors welcome
suggestions.)
Each certificate or precertificate entry in a log MUST include the Each certificate or precertificate entry in a log MUST include the
following components: following components:
enum { x509_entry(0), precert_entry_V2(3), (65535) } LogEntryType; enum { x509_entry(0), precert_entry_V2(2), (65535) } LogEntryType;
struct {
LogEntryType entry_type;
select (entry_type) {
case x509_entry: X509ChainEntry;
case precert_entry_V2: PrecertChainEntryV2;
} entry;
} LogEntry;
opaque ASN.1Cert<1..2^24-1>; opaque ASN.1Cert<1..2^24-1>;
struct { struct {
ASN.1Cert leaf_certificate; ASN.1Cert leaf_certificate;
ASN.1Cert certificate_chain<0..2^24-1>; ASN.1Cert certificate_chain<0..2^24-1>;
} X509ChainEntry; } X509ChainEntry;
opaque CMSPrecert<1..2^24-1>; opaque CMSPrecert<1..2^24-1>;
skipping to change at page 11, line 40 skipping to change at page 12, line 30
Logs SHOULD limit the length of chain they will accept. Logs SHOULD limit the length of chain they will accept.
"entry_type" is the type of this entry. Future revisions of this "entry_type" is the type of this entry. Future revisions of this
protocol may add new LogEntryType values. Section 4 explains how protocol may add new LogEntryType values. Section 4 explains how
clients should handle unknown entry types. clients should handle unknown entry types.
"leaf_certificate" is the end-entity certificate submitted for "leaf_certificate" is the end-entity certificate submitted for
auditing. auditing.
"certificate_chain" is a chain of additional certificates required to "certificate_chain" is an array of additional certificates required
verify the end-entity certificate. The first certificate MUST to verify the end-entity certificate. The first certificate MUST
certify the end-entity certificate. Each following certificate MUST certify the end-entity certificate. Each following certificate MUST
directly certify the one preceding it. The final certificate MUST directly certify the one preceding it. The final certificate MUST
either be, or be issued by, a root certificate accepted by the log. either be, or be issued by, a root certificate accepted by the log.
If the end-entity certificate is a root certificate, then this array
is empty.
"pre_certificate" is the precertificate submitted for auditing. "pre_certificate" is the precertificate submitted for auditing.
"precertificate_chain" is a chain of additional certificates required "precertificate_chain" is a chain of additional certificates required
to verify the precertificate submission. The first certificate MUST to verify the precertificate submission. The first certificate MUST
certify the precertificate. Each following certificate MUST directly certify the precertificate. Each following certificate MUST directly
certify the one preceding it. The final certificate MUST be a root certify the one preceding it. The final certificate MUST be a root
certificate accepted by the log. certificate accepted by the log.
3.2. Private Domain Name Labels 3.2. Private Domain Name Labels
skipping to change at page 14, line 33 skipping to change at page 15, line 33
} }
} }
} }
} }
3.3. Structure of the Signed Certificate Timestamp 3.3. Structure of the Signed Certificate Timestamp
enum { certificate_timestamp(0), tree_hash(1), (255) } enum { certificate_timestamp(0), tree_hash(1), (255) }
SignatureType; SignatureType;
enum { v1(0), v2(1), (255) } enum { v2(1), (255) }
Version; Version;
struct { struct {
opaque key_id[32]; opaque key_id[HASH_SIZE];
} LogID; } LogID;
opaque TBSCertificate<1..2^24-1>; opaque TBSCertificate<1..2^24-1>;
struct {
opaque issuer_key_hash[HASH_SIZE];
TBSCertificate tbs_certificate;
} CertInfo;
opaque CtExtensions<0..2^16-1>; opaque CtExtensions<0..2^16-1>;
"key_id" is the SHA-256 hash of the log's public key, calculated over "key_id" is the HASH of the log's public key, calculated over the DER
the DER encoding of the key represented as SubjectPublicKeyInfo. encoding of the key represented as SubjectPublicKeyInfo.
"issuer_key_hash" is the 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, making it impossible for the SCT to be valid for any
other certificate.
"tbs_certificate" is the DER-encoded TBSCertificate component of the "tbs_certificate" is the DER-encoded TBSCertificate component of the
precertificate. Note that it is also possible to reconstruct this precertificate. Note that it is also possible to reconstruct this
TBSCertificate from the issued certificate by extracting the TBSCertificate from the issued certificate by extracting the
TBSCertificate from it, redacting the domain name labels indicated by TBSCertificate from it, redacting the domain name labels indicated by
the redacted labels extension, and deleting the SCT list extension the redacted labels extension, and deleting the SCT list extension
and redacted labels extension. and redacted labels extension.
struct { struct {
Version sct_version; Version sct_version;
LogID id; LogID id;
uint64 timestamp; uint64 timestamp;
CtExtensions extensions; CtExtensions extensions;
digitally-signed struct { digitally-signed struct {
Version sct_version; Version sct_version;
SignatureType signature_type = certificate_timestamp; SignatureType signature_type = certificate_timestamp;
uint64 timestamp; uint64 timestamp;
LogEntryType entry_type; LogEntryType entry_type;
select(entry_type) { select(entry_type) {
case x509_entry: ASN.1Cert; case x509_entry: CertInfo;
case precert_entry_V2: TBSCertificate; case precert_entry_V2: CertInfo;
} signed_entry; } signed_entry;
CtExtensions extensions; CtExtensions extensions;
}; };
} SignedCertificateTimestamp; } SignedCertificateTimestamp;
The encoding of the digitally-signed element is defined in [RFC5246]. The encoding of the digitally-signed element is defined in [RFC5246].
"sct_version" is the version of the protocol to which the SCT "sct_version" is the version of the protocol to which the SCT
conforms. This version is v2. conforms. This version is v2. Note that SignedCertificateTimestamp
v1 [RFC6962] had a different definition of "signed_entry".
"timestamp" is the current NTP Time [RFC5905], measured since the "timestamp" is the current NTP Time [RFC5905], measured since the
epoch (January 1, 1970, 00:00), ignoring leap seconds, in epoch (January 1, 1970, 00:00), ignoring leap seconds, in
milliseconds. milliseconds.
"entry_type" may be implicit from the context in which the SCT is "entry_type" may be implicit from the context in which the SCT is
presented. presented.
"signed_entry" is the "leaf_certificate" (in the case of an "signed_entry" includes the TBSCertificate from either the
X509ChainEntry) or is the TBSCertificate (in the case of a "leaf_certificate" (in the case of an X509ChainEntry) or the
PrecertChainEntryV2), as described above. "pre_certificate" (in the case of a PrecertChainEntryV2).
"extensions" are future extensions to SignedCertificateTimestamp v2. "extensions" are future extensions to SignedCertificateTimestamp v2.
Currently, no extensions are specified. Currently, no extensions are specified.
3.4. Including the Signed Certificate Timestamp in the TLS Handshake 3.4. Including the Signed Certificate Timestamp in the TLS Handshake
The SCT data corresponding to at least one certificate in the chain The SCT data corresponding to at least one certificate in the chain
from at least one log must be included in the TLS handshake by using from at least one log must be included in the TLS handshake by using
one or more of the mechanisms listed below. Three mechanisms are one or more of the mechanisms listed below. Three mechanisms are
provided because they have different tradeoffs. TLS clients MUST provided because they have different tradeoffs. TLS clients MUST
skipping to change at page 18, line 14 skipping to change at page 19, line 27
Structure of the Merkle Tree input: Structure of the Merkle Tree input:
enum { v1(0), v2(1), (255) } enum { v1(0), v2(1), (255) }
LeafVersion; LeafVersion;
struct { struct {
uint64 timestamp; uint64 timestamp;
LogEntryType entry_type; LogEntryType entry_type;
select(entry_type) { select(entry_type) {
case x509_entry: ASN.1Cert; case x509_entry: CertInfo;
case precert_entry_V2: TBSCertificate; case precert_entry_V2: CertInfo;
} signed_entry; } signed_entry;
CtExtensions extensions; CtExtensions extensions;
} TimestampedEntry; } TimestampedEntry;
struct { struct {
LeafVersion version; LeafVersion version;
TimestampedEntry timestamped_entry; TimestampedEntry timestamped_entry;
} MerkleTreeLeaf; } MerkleTreeLeaf;
Here, "version" is the version of the MerkleTreeLeaf structure. This Here, "version" is the version of the MerkleTreeLeaf structure. This
skipping to change at page 18, line 42 skipping to change at page 20, line 6
"entry_type" is the type of entry stored in "signed_entry". New "entry_type" is the type of entry stored in "signed_entry". New
"LogEntryType" values may be added to "signed_entry" without "LogEntryType" values may be added to "signed_entry" without
increasing the "MerkleTreeLeaf" version. Section 4 explains how increasing the "MerkleTreeLeaf" version. Section 4 explains how
clients should handle unknown entry types. clients should handle unknown entry types.
"signed_entry" is the "signed_entry" of the corresponding SCT. "signed_entry" is the "signed_entry" of the corresponding SCT.
"extensions" are "extensions" of the corresponding SCT. "extensions" are "extensions" of the corresponding SCT.
The leaves of the Merkle Tree are the leaf hashes of the The leaves of the Merkle Tree are the leaf hashes of the
corresponding "MerkleTreeLeaf" structures. corresponding "MerkleTreeLeaf" structures. Note that leaf hashes
(Section 2.1) are calculated as HASH(0x00 || MerkleTreeLeaf).
3.6. Signed Tree Head 3.6. Signed Tree Head
Every time a log appends new entries to the tree, the log SHOULD sign Periodically the log SHOULD sign the corresponding tree hash and tree
the corresponding tree hash and tree information (see the information (see the corresponding Signed Tree Head client message in
corresponding Signed Tree Head client message in Section 4.3). The Section 4.3). The signature for that data is structured as follows:
signature for that data is structured as follows:
enum { v1(0), (255) } TreeHeadVersion; enum { v1(0), (255) } TreeHeadVersion;
digitally-signed struct { digitally-signed struct {
TreeHeadVersion version; TreeHeadVersion version;
SignatureType signature_type = tree_hash; SignatureType signature_type = tree_hash;
uint64 timestamp; uint64 timestamp;
uint64 tree_size; uint64 tree_size;
opaque sha256_root_hash[32]; opaque root_hash[HASH_SIZE];
} TreeHeadSignature; } TreeHeadSignature;
"version" is the version of the TreeHeadSignature structure. This "version" is the version of the TreeHeadSignature structure. This
version is v1. version is v1.
"timestamp" is the current time. The timestamp MUST be at least as "timestamp" is the current time. The timestamp MUST be at least as
recent as the most recent SCT timestamp in the tree. Each subsequent recent as the most recent SCT timestamp in the tree. Each subsequent
timestamp MUST be more recent than the timestamp of the previous timestamp MUST be more recent than the timestamp of the previous
update. update.
"tree_size" equals the number of entries in the new tree. "tree_size" equals the number of entries in the new tree.
"sha256_root_hash" is the root of the Merkle Hash Tree. "root_hash" is the root of the Merkle Hash Tree.
Each log MUST produce on demand a Signed Tree Head that is no older Each log MUST produce on demand a Signed Tree Head that is no older
than the Maximum Merge Delay. In the unlikely event that it receives than the Maximum Merge Delay. However, Signed Tree Heads could be
no new submissions during an MMD period, the log SHALL sign the same used to mark individual clients (by producing a new one for each
Merkle Tree Hash with a fresh timestamp. query), so logs MUST NOT produce them more frequently than is
declared in their metadata. In general, there is no need to produce
a new Signed Tree Head unless there are new entries in the log,
however, in the unlikely event that it receives no new submissions
during an MMD period, the log SHALL sign the same Merkle Tree Hash
with a fresh timestamp.
4. Log Client Messages 4. Log Client Messages
Messages are sent as HTTPS GET or POST requests. Parameters for Messages are sent as HTTPS GET or POST requests. Parameters for
POSTs and all responses are encoded as JavaScript Object Notation POSTs and all responses are encoded as JavaScript Object Notation
(JSON) objects [RFC4627]. Parameters for GETs are encoded as order- (JSON) objects [RFC4627]. Parameters for GETs are encoded as order-
independent key/value URL parameters, using the "application/x-www- independent key/value URL parameters, using the "application/x-www-
form-urlencoded" format described in the "HTML 4.01 Specification" form-urlencoded" format described in the "HTML 4.01 Specification"
[HTML401]. Binary data is base64 encoded [RFC4648] as specified in [HTML401]. Binary data is base64 encoded [RFC4648] as specified in
the individual messages. the individual messages.
skipping to change at page 20, line 38 skipping to change at page 22, line 5
In the case of a malformed request, the string SHOULD provide In the case of a malformed request, the string SHOULD provide
sufficient detail for the error to be rectified. sufficient detail for the error to be rectified.
error_code: An error code readable by the client. Some codes are error_code: An error code readable by the client. Some codes are
generic and are detailed here. Others are detailed in the generic and are detailed here. Others are detailed in the
individual requests. Error codes are fixed text strings. individual requests. Error codes are fixed text strings.
not compliant The request is not compliant with this RFC. not compliant The request is not compliant with this RFC.
e.g. In response to a request of "/ct/v1/get- e.g. In response to a request of "/ct/v2/get-
entries?start=100&end=99", the log would return a "400 Bad Request" entries?start=100&end=99", the log would return a "400 Bad Request"
response code with a body similar to the following: response code with a body similar to the following:
{ {
"error_message": "'start' cannot be greater than 'end'", "error_message": "'start' cannot be greater than 'end'",
"error_code": "not compliant", "error_code": "not compliant",
} }
Clients SHOULD treat "500 Internal Server Error" and "503 Service Clients SHOULD treat "500 Internal Server Error" and "503 Service
Unavailable" responses as transient failures and MAY retry the same Unavailable" responses as transient failures and MAY retry the same
request without modification at a later date. Note that as per request without modification at a later date. Note that as per
[RFC2616], in the case of a 503 response the log MAY include a [RFC2616], in the case of a 503 response the log MAY include a
"Retry-After:" header in order to request a minimum time for the "Retry-After:" header in order to request a minimum time for the
client to wait before retrying the request. client to wait before retrying the request.
4.1. Add Chain to Log 4.1. Add Chain to Log
POST https://<log server>/ct/v1/add-chain POST https://<log server>/ct/v2/add-chain
Inputs: Inputs:
chain: An array of base64-encoded certificates. The first chain: An array of base64 encoded certificates. The first
element is the end-entity certificate; the second chains to the element is the end-entity certificate; the second chains to the
first and so on to the last, which is either the root first and so on to the last, which is either the root
certificate or a certificate that chains to a known root certificate or a certificate that chains to a known root
certificate. certificate.
Outputs: Outputs:
sct_version: The version of the SignedCertificateTimestamp sct: The base64 encoded "SignedCertificateTimestamp" for the
structure, in decimal. A compliant v1 implementation MUST NOT submitted certificate.
expect this to be 0 (i.e., v1).
id: The log ID, base64 encoded.
timestamp: The SCT timestamp, in decimal.
extensions: An opaque type for future expansion. It is likely
that not all participants will need to understand data in this
field. Logs should set this to the empty string. Clients
should decode the base64-encoded data and include it in the
SCT.
signature: The SCT signature, base64 encoded.
Error codes: Error codes:
unknown root The root of the chain is not one accepted by the unknown root The root of the chain is not one accepted by the
log. log.
bad chain The alleged chain is not actually a chain of bad chain The alleged chain is not actually a chain of
certificates. certificates.
bad certificate One or more certificates in the chain are not bad certificate One or more certificates in the chain are not
valid (e.g. not properly encoded). valid (e.g. not properly encoded).
If the "sct_version" is not v1, then a v1 client may be unable to If the version of "sct" is not v2, then a v2 client may be unable to
verify the signature. It MUST NOT construe this as an error. This verify the signature. It MUST NOT construe this as an error. This
is to avoid forcing an upgrade of compliant v1 clients that do not is to avoid forcing an upgrade of compliant v2 clients that do not
use the returned SCTs. use the returned SCTs.
If a log detects bad encoding in a chain that otherwise verifies If a log detects bad encoding in a chain that otherwise verifies
correctly (e.g. some software will accept BER instead of DER correctly then the log MAY still log the certificate but SHOULD NOT
encodings in certificates, or incorrect character encodings, even return an SCT. It should instead return the "bad certificate" error.
though these are technically incorrect) then the log MAY still log Logging the certificate is useful, because monitors (Section 5.4) can
the certificate but SHOULD NOT return an SCT. It should instead then detect these encoding errors, which may be accepted by some TLS
return the "bad certificate" error. Logging the certificate is clients.
useful, because monitors can then detect these encoding errors, which
may be accepted by some TLS clients.
Note that not all certificate handling software is capable of Note that not all certificate handling software is capable of
detecting all encoding errors. detecting all encoding errors (e.g. some software will accept BER
instead of DER encodings in certificates, or incorrect character
encodings, even though these are technically incorrect) .
4.2. Add PreCertChain to Log 4.2. Add PreCertChain to Log
POST https://<log server>/ct/v1/add-pre-chain POST https://<log server>/ct/v2/add-pre-chain
Inputs: Inputs:
precertificate: The base64-encoded precertificate. precertificate: The base64 encoded precertificate.
chain: An array of base64-encoded CA certificates. The first chain: An array of base64 encoded CA certificates. The first
element is the signer of the precertificate; the second chains element is the signer of the precertificate; the second chains
to the first and so on to the last, which is either the root to the first and so on to the last, which is either the root
certificate or a certificate that chains to an accepted root certificate or a certificate that chains to an accepted root
certificate. certificate.
Outputs and errors are the same as in Section 4.1. Outputs and errors are the same as in Section 4.1.
4.3. Retrieve Latest Signed Tree Head 4.3. Retrieve Latest Signed Tree Head
GET https://<log server>/ct/v1/get-sth GET https://<log server>/ct/v1/get-sth
No inputs. No inputs.
Outputs: Outputs:
tree_size: The size of the tree, in entries, in decimal. tree_size: The size of the tree, in entries, in decimal.
timestamp: The timestamp, in decimal. timestamp: The timestamp, in decimal.
sha256_root_hash: The Merkle Tree Hash of the tree, in base64. root_hash: The base64 encoded Merkle Tree Hash of the tree.
tree_head_signature: A TreeHeadSignature for the above data. tree_head_signature: A base64 encoded TreeHeadSignature for
"tree_size", "timestamp" and "root_hash".
4.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads 4.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads
GET https://<log server>/ct/v2/get-sth-consistency GET https://<log server>/ct/v2/get-sth-consistency
Inputs: Inputs:
first: The tree_size of the older tree, in decimal. first: The tree_size of the older tree, in decimal.
second: The tree_size of the newer tree, in decimal (optional). second: The tree_size of the newer tree, in decimal (optional).
skipping to change at page 23, line 26 skipping to change at page 24, line 26
However, because of skew, the receiving front-end may not know one However, because of skew, the receiving front-end may not know one
or both of the existing STHs. If both are known, then only the or both of the existing STHs. If both are known, then only the
"consistency" output is returned. If the first is known but the "consistency" output is returned. If the first is known but the
second is not (or has been omitted), then the latest known STH is second is not (or has been omitted), then the latest known STH is
returned, along with a consistency proof between the first STH and returned, along with a consistency proof between the first STH and
the latest. If neither are known, then the latest known STH is the latest. If neither are known, then the latest known STH is
returned without a consistency proof. returned without a consistency proof.
Outputs: Outputs:
consistency: An array of Merkle Tree nodes, base64 encoded. consistency: An array of base64 encoded Merkle Tree nodes.
tree_size: The size of the tree, in entries, in decimal. tree_size: The size of the tree, in entries, in decimal.
timestamp: The timestamp, in decimal. timestamp: The timestamp, in decimal.
sha256_root_hash: The Merkle Tree Hash of the tree, in base64. root_hash: The base64 encoded Merkle Tree Hash of the tree.
tree_head_signature: A TreeHeadSignature for the above data. tree_head_signature: A base64 encoded TreeHeadSignature for
"tree_size", "timestamp" and "root_hash".
Note that no signature is required on this data, as it is used to Note that no signature is required for the "consistency" output as
verify an STH, which is signed. it is used to verify an STH, which is signed.
Error codes: Error codes:
first unknown "first" is before the latest known STH but is not first unknown "first" is before the latest known STH but is not
from an existing STH. from an existing STH.
second unknown "second" is before the latest known STH but is not second unknown "second" is before the latest known STH but is not
from an existing STH. from an existing STH.
See Section 5.5.2 for an outline of how to use the "consistency"
array.
4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash 4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash
GET https://<log server>/ct/v2/get-proof-by-hash GET https://<log server>/ct/v2/get-proof-by-hash
Inputs: Inputs:
hash: A base64-encoded v1 leaf hash. hash: A base64 encoded v1 leaf hash.
tree_size: The tree_size of the tree on which to base the proof, tree_size: The tree_size of the tree on which to base the proof,
in decimal. in decimal.
The "hash" must be calculated as defined in Section 3.5. The The "hash" must be calculated as defined in Section 3.5. The
"tree_size" must designate an existing v1 STH. Because of skew, "tree_size" must designate an existing v1 STH. Because of skew,
the front-end may not know the requested STH. In that case, it the front-end may not know the requested STH. In that case, it
will return the latest STH it knows, along with an inclusion proof will return the latest STH it knows, along with an inclusion proof
to that STH. If the front-end knows the requested STH then only to that STH. If the front-end knows the requested STH then only
"leaf_index" and "audit_path" are returned. "leaf_index" and "audit_path" are returned.
Outputs: Outputs:
leaf_index: The 0-based index of the entry corresponding to the leaf_index: The 0-based index of the entry corresponding to the
"hash" parameter. "hash" parameter.
audit_path: An array of base64-encoded Merkle Tree nodes proving audit_path: An array of base64 encoded Merkle Tree nodes proving
the inclusion of the chosen certificate. the inclusion of the chosen certificate.
tree_size: The size of the tree, in entries, in decimal. tree_size: The size of the tree, in entries, in decimal.
timestamp: The timestamp, in decimal. timestamp: The timestamp, in decimal.
sha256_root_hash: The Merkle Tree Hash of the tree, in base64. root_hash: The base64 encoded Merkle Tree Hash of the tree.
tree_head_signature: A TreeHeadSignature for the above data. tree_head_signature: A base64 encoded TreeHeadSignature for
"tree_size", "timestamp" and "root_hash".
Note that no signature is required for the "leaf_index" or
"audit_path" output as this is used to verify inclusion in an STH,
which is signed.
Error codes: Error codes:
hash unknown "hash" is not the hash of a known leaf (may be hash unknown "hash" is not the hash of a known leaf (may be
caused by skew or by a known certificate not yet merged). caused by skew or by a known certificate not yet merged).
tree_size unknown "hash" is before the latest known STH but is tree_size unknown "hash" is before the latest known STH but is
not from an existing STH. not from an existing STH.
See Section 5.5.1 for an outline of how to use the "audit_path"
array.
4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and Consistency 4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and Consistency
Proof by Leaf Hash Proof by Leaf Hash
GET https://<log server>/ct/v2/get-all-by-hash GET https://<log server>/ct/v2/get-all-by-hash
Inputs: Inputs:
hash: A base64-encoded v1 leaf hash. hash: A base64 encoded v1 leaf hash.
tree_size: The tree_size of the tree on which to base the proofs, tree_size: The tree_size of the tree on which to base the proofs,
in decimal. in decimal.
The "hash" must be calculated as defined in Section 3.5. The The "hash" must be calculated as defined in Section 3.5. The
"tree_size" must designate an existing v1 STH. "tree_size" must designate an existing v1 STH.
Because of skew, the front-end may not know the requested STH or Because of skew, the front-end may not know the requested STH or
the requested hash, which leads to a number of cases. the requested hash, which leads to a number of cases.
skipping to change at page 25, line 29 skipping to change at page 26, line 44
Note that more than one case can be true, in which case the Note that more than one case can be true, in which case the
returned data is their concatenation. It is also possible for returned data is their concatenation. It is also possible for
none to be true, in which case the front-end MUST return an empty none to be true, in which case the front-end MUST return an empty
response. response.
Outputs: Outputs:
leaf_index: The 0-based index of the entry corresponding to the leaf_index: The 0-based index of the entry corresponding to the
"hash" parameter. "hash" parameter.
audit_path: An array of base64-encoded Merkle Tree nodes proving audit_path: An array of base64 encoded Merkle Tree nodes proving
the inclusion of the chosen certificate. the inclusion of the chosen certificate.
tree_size: The size of the tree, in entries, in decimal. tree_size: The size of the tree, in entries, in decimal.
timestamp: The timestamp, in decimal. timestamp: The timestamp, in decimal.
sha256_root_hash: The Merkle Tree Hash of the tree, in base64. root_hash: The base64 encoded Merkle Tree Hash of the tree.
tree_head_signature: A TreeHeadSignature for the above data. tree_head_signature: A base64 encoded TreeHeadSignature for
"tree_size", "timestamp" and "root_hash".
consistency: An array of base64-encoded Merkle Tree nodes proving consistency: An array of base64 encoded Merkle Tree nodes proving
the consistency of the requested STH and the returned STH. the consistency of the requested STH and the returned STH.
Note that no signature is required for the "leaf_index",
"audit_path" or "consistency" output as this is used to verify
inclusion in and consistency of an STH, which is signed.
Errors are the same as in Section 4.5. Errors are the same as in Section 4.5.
4.7. Retrieve Entries from Log See Section 5.5.1 for an outline of how to use the "audit_path" array
and see Section 5.5.2 for an outline of how to use the "consistency"
array.
GET https://<log server>/ct/v1/get-entries 4.7. Retrieve Entries and STH from Log
GET https://<log server>/ct/v2/get-entries
Inputs: Inputs:
start: 0-based index of first entry to retrieve, in decimal. start: 0-based index of first entry to retrieve, in decimal.
end: 0-based index of last entry to retrieve, in decimal. end: 0-based index of last entry to retrieve, in decimal.
Outputs: Outputs:
entries: An array of objects, each consisting of entries: An array of objects, each consisting of
leaf_input: The base64-encoded MerkleTreeLeaf structure. leaf_input: The base64 encoded MerkleTreeLeaf structure.
extra_data: The base64-encoded unsigned data pertaining to the extra_data: The base64 encoded unsigned data pertaining to the
log entry. In the case of an X509ChainEntry, this is the log entry. In the case of an X509ChainEntry, this is the
"certificate_chain". In the case of a PrecertChainEntryV2, whole "X509ChainEntry". In the case of a
this is the whole "PrecertChainEntryV2". PrecertChainEntryV2, this is the whole
"PrecertChainEntryV2".
Note that this message is not signed -- the retrieved data can be sct: A base64 encoded "SignedCertificateTimestamp" for this
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.
tree_size: The size of the tree, in entries, in decimal.
timestamp: The timestamp, in decimal.
root_hash: The base64 encoded Merkle Tree Hash of the tree.
tree_head_signature: A base64 encoded TreeHeadSignature for
"tree_size", "timestamp" and "root_hash".
Note that this message is not signed -- the "entries" data can be
verified by constructing the Merkle Tree Hash corresponding to a verified by constructing the Merkle Tree Hash corresponding to a
retrieved STH. All leaves MUST be v1 or v2. However, a compliant v1 retrieved STH. All leaves MUST be v1 or v2. However, a compliant v1
client MUST NOT construe an unrecognized LogEntryType value as an client MUST NOT construe an unrecognized LogEntryType value as an
error. This means it may be unable to parse some entries, but note error. This means it may be unable to parse some entries, but note
that each client can inspect the entries it does recognize as well as that each client can inspect the entries it does recognize as well as
verify the integrity of the data by treating unrecognized leaves as verify the integrity of the data by treating unrecognized leaves as
opaque input to the tree. opaque input to the tree.
The "start" and "end" parameters SHOULD be within the range 0 <= x < The "start" and "end" parameters SHOULD be within the range 0 <= x <
"tree_size" as returned by "get-sth" in Section 4.3. "tree_size" as returned by "get-sth" in Section 4.3.
Logs MAY honor requests where 0 <= "start" < "tree_size" and "end" >= The "start" parameter MUST be less than or equal to the "end"
"tree_size" by returning a partial response covering only the valid parameter.
entries in the specified range. Note that the following restriction
may also apply: Log servers MUST honor requests where 0 <= "start" < "tree_size" and
"end" >= "tree_size" by returning a partial response covering only
the valid entries in the specified range. "end" >= "tree_size" could
be caused by skew. Note that the following restriction may also
apply:
Logs MAY restrict the number of entries that can be retrieved per Logs MAY restrict the number of entries that can be retrieved per
"get-entries" request. If a client requests more than the permitted "get-entries" request. If a client requests more than the permitted
number of entries, the log SHALL return the maximum number of entries number of entries, the log SHALL return the maximum number of entries
permissible. These entries SHALL be sequential beginning with the permissible. These entries SHALL be sequential beginning with the
entry specified by "start". entry specified by "start".
Because of skew, it is possible the log server will not have any Because of skew, it is possible the log server will not have any
entries between "start" and "end". In this case it MUST return an entries between "start" and "end". In this case it MUST return an
empty "entries" array. empty "entries" array.
In any case, the log server MUST return the latest STH it knows
about.
See Section 5.5.3 for an outline of how to use a complete list of
"leaf_input" entries to verify the "root_hash".
4.8. Retrieve Accepted Root Certificates 4.8. Retrieve Accepted Root Certificates
GET https://<log server>/ct/v1/get-roots GET https://<log server>/ct/v1/get-roots
No inputs. No inputs.
Outputs: Outputs:
certificates: An array of base64-encoded root certificates that certificates: An array of base64 encoded root certificates that
are acceptable to the log. are acceptable to the log.
max_chain: If the server has chosen to limit the length of chains max_chain: If the server has chosen to limit the length of chains
it accepts, this is the maximum number of certificates in the it accepts, this is the maximum number of certificates in the
chain, in decimal. If there is no limit, this is omitted. chain, in decimal. If there is no limit, this is omitted.
5. Clients 5. Clients
There are various different functions clients of logs might perform. There are various different functions clients of logs might perform.
We describe here some typical clients and how they could function. We describe here some typical clients and how they could function.
skipping to change at page 27, line 47 skipping to change at page 29, line 47
Hash Algorithm The hash algorithm used for the Merkle Tree (see Hash Algorithm The hash algorithm used for the Merkle Tree (see
Section 7.2). Section 7.2).
Signing Algorithm The signing algorithm used (see Section 2.1.4). Signing Algorithm The signing algorithm used (see Section 2.1.4).
Public Key The public key used for signing. Public Key The public key used for signing.
Maximum Merge Delay The MMD the log has committed to. Maximum Merge Delay The MMD the log has committed to.
Version The version of the protocol supported by the log (currently
1 or 2).
STH Frequency Count The maximum number of STHs the log may produce
in any period equal to the "Maximum Merge Delay" (see
Section 3.6).
Final STH If a log has been closed down (i.e. no longer accepts new Final STH If a log has been closed down (i.e. no longer accepts new
entries), existing entries may still be valid. In this case, the entries), existing entries may still be valid. In this case, the
client should know the final valid STH in the log to ensure no new client should know the final valid STH in the log to ensure no new
entries can be added without detection. entries can be added without detection.
[JSON.Metadata] is an example of a metadata format which includes the [JSON.Metadata] is an example of a metadata format which includes the
above elements. above elements.
5.2. Submitters 5.2. Submitters
skipping to change at page 30, line 7 skipping to change at page 32, line 10
STH is indeed the result of making a tree from all fetched entries. STH is indeed the result of making a tree from all fetched entries.
A TLS client (Section 5.3) can audit by verifying an SCT against any A TLS client (Section 5.3) can audit by verifying an SCT against any
STH dated after the SCT timestamp + the Maximum Merge Delay by STH dated after the SCT timestamp + the Maximum Merge Delay by
requesting a Merkle inclusion proof (Section 4.5). It can also requesting a Merkle inclusion proof (Section 4.5). It can also
verify that the SCT corresponds to the certificate it arrived with verify that the SCT corresponds to the certificate it arrived with
(i.e. the log entry is that certificate, is a precertificate for that (i.e. the log entry is that certificate, is a precertificate for that
certificate or is an appropriate name-constrained intermediate [see certificate or is an appropriate name-constrained intermediate [see
Section 3.2.3]). Section 3.2.3]).
The following algorithm outlines may be useful for clients that wish
to perform various audit operations.
5.5.1. Verifying an inclusion proof
When a client has received an "audit_path" and "leaf_index" and
wishes to verify inclusion of an input "hash" for an STH with a given
"tree_size" and "root_hash", the following algorithm may be used to
prove the "hash" was included in the "root_hash":
1. Set "fn" to "leaf_index" and "sn" to "tree_size - 1".
2. Set "r" to "hash".
3. For each value "p" in the "audit_path" array:
If "LSB(fn)" is set, or if "fn" is equal to "sn", then:
1. Set "r" to "HASH(0x01 || p || r)"
2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn"
equally until either "LSB(fn)" is set or "fn" is "0".
Otherwise:
Set "r" to "HASH(0x01 || r || p)"
Finally, right-shift both "fn" and "sn" one time.
4. Compare "r" against the "root_hash". If they are equal, then the
log has proven the inclusion of "hash".
5.5.2. Verifying consistency between two STHs
When a client has an STH "first_hash" for tree size "first", an STH
"second_hash" for tree size "second" where "0 < first < second", and
has received a "consistency" array that they wish to use to verify
both hashes, the following algorithm may be used:
1. If "first" is an exact power of 2, then prepend "first_hash" to
the "consistency" array.
2. Set "fn" to "first - 1" and "sn" to "second - 1".
3. If "LSB(fn)" is set, then right-shift both "fn" and "sn" equally
until "LSB(fn)" is not set.
4. Set both "fr" and "sr" to the first value in the "consistency"
array.
5. For each subsequent value "c" in the "consistency" array:
If "LSB(fn)" is set, or if "fn" is equal to "sn", then:
1. Set "fr" to "HASH(0x01 || c || fr)"
Set "sr" to "HASH(0x01 || c || sr)"
2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn"
equally until either "LSB(fn)" is set or "fn" is "0".
Otherwise:
Set "sr" to "HASH(0x01 || sr || c)"
Finally, right-shift both "fn" and "sn" one time.
6. After completing iterating through the "consistency" array as
described above, verify that the "fr" calculated is equal to the
"first_hash" supplied and that the "sr" calculated is equal to
the "second_hash" supplied.
5.5.3. Verifying root hash given entries
When a client has a complete list of leaf input "entries" from "0" up
to "tree_size - 1" and wishes to verify this list against an STH
"root_hash" returned by the log for the same "tree_size", the
following algorithm may be used:
1. Set "stack" to an empty stack.
2. For each "i" from "0" up to "tree_size - 1":
1. Push "HASH(0x00 || entries[i])" to "stack".
2. Set "merge_count" to the lowest value ("0" included) such
that "LSB(i >> merge_count)" is not set. In other words, set
"merge_count" to the number of consecutive "1"s found
starting at the least significant bit of "i".
3. Repeat "merge_count" times:
1. Pop "right" from "stack".
2. Pop "left" from "stack".
3. Push "HASH(0x01 || left || right)" to "stack".
3. If there is more than one element in the "stack", repeat the same
merge procedure (Step 2.3 above) until only a single element
remains.
4. The remaining element in "stack" is the Merkle Tree hash for the
given "tree_size" and should be compared by equality against the
supplied "root_hash".
6. Algorithm Agility 6. Algorithm Agility
It is not possible for a log to change any of its algorithms part way It is not possible for a log to change any of its algorithms part way
through its lifetime. If it should become necessary to deprecate an through its lifetime. If it should become necessary to deprecate an
algorithm used by a live log, then the log should be frozen as algorithm used by a live log, then the log should be frozen as
specified in Section 5.1 and a new log should be started. If specified in Section 5.1 and a new log should be started. If
necessary, the new log can contain existing entries from the frozen necessary, the new log can contain existing entries from the frozen
log, which monitors can verify are an exact match. log, which monitors can verify are an exact match.
7. IANA Considerations 7. IANA Considerations
skipping to change at page 34, line 31 skipping to change at page 38, line 44
Verification of Domain-Based Application Service Identity Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509 within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer (PKIX) Certificates in the Context of Transport Layer
Security (TLS)", RFC 6125, March 2011. Security (TLS)", RFC 6125, March 2011.
[RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A.,
Galperin, S., and C. Adams, "X.509 Internet Public Key Galperin, S., and C. Adams, "X.509 Internet Public Key
Infrastructure Online Certificate Status Protocol - OCSP", Infrastructure Online Certificate Status Protocol - OCSP",
RFC 6960, June 2013. RFC 6960, June 2013.
[RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature
Algorithm (DSA) and Elliptic Curve Digital Signature
Algorithm (ECDSA)", RFC 6979, August 2013.
11.2. Informative References 11.2. Informative References
[Chromium.Log.Policy] [Chromium.Log.Policy]
The Chromium Projects, "Chromium Certificate Transparency The Chromium Projects, "Chromium Certificate Transparency
Log Policy", 2014, <http://www.chromium.org/Home/ Log Policy", 2014, <http://www.chromium.org/Home/
chromium-security/certificate-transparency/log-policy>. chromium-security/certificate-transparency/log-policy>.
[Chromium.Policy] [Chromium.Policy]
The Chromium Projects, "Chromium Certificate The Chromium Projects, "Chromium Certificate
Transparency", 2014, <http://www.chromium.org/Home/ Transparency", 2014, <http://www.chromium.org/Home/
 End of changes. 76 change blocks. 
170 lines changed or deleted 344 lines changed or added

This html diff was produced by rfcdiff 1.42. The latest version is available from http://tools.ietf.org/tools/rfcdiff/