idnits 2.17.1 draft-ietf-trans-rfc6962-bis-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 6, 2015) is 3216 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 618 -- Looks like a reference, but probably isn't: '7' on line 623 -- Looks like a reference, but probably isn't: '0' on line 613 -- Looks like a reference, but probably isn't: '2' on line 615 -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTML401' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6979 -- Obsolete informational reference (is this intentional?): RFC 6962 (Obsoleted by RFC 9162) Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Public Notary Transparency Working Group B. Laurie 3 Internet-Draft A. Langley 4 Intended status: Standards Track E. Kasper 5 Expires: January 7, 2016 E. Messeri 6 Google 7 R. Stradling 8 Comodo 9 July 6, 2015 11 Certificate Transparency 12 draft-ietf-trans-rfc6962-bis-08 14 Abstract 16 This document describes a protocol for publicly logging the existence 17 of Transport Layer Security (TLS) certificates as they are issued or 18 observed, in a manner that allows anyone to audit certification 19 authority (CA) activity and notice the issuance of suspect 20 certificates as well as to audit the certificate logs themselves. 21 The intent is that eventually clients would refuse to honor 22 certificates that do not appear in a log, effectively forcing CAs to 23 add all issued certificates to the logs. 25 Logs are network services that implement the protocol operations for 26 submissions and queries that are defined in this document. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on January 7, 2016. 45 Copyright Notice 47 Copyright (c) 2015 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 4 64 1.2. Data Structures . . . . . . . . . . . . . . . . . . . . . 4 65 2. Cryptographic Components . . . . . . . . . . . . . . . . . . 5 66 2.1. Merkle Hash Trees . . . . . . . . . . . . . . . . . . . . 5 67 2.1.1. Merkle Inclusion Proofs . . . . . . . . . . . . . . . 5 68 2.1.2. Merkle Consistency Proofs . . . . . . . . . . . . . . 6 69 2.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 7 70 2.1.4. Signatures . . . . . . . . . . . . . . . . . . . . . 9 71 3. Log Format and Operation . . . . . . . . . . . . . . . . . . 10 72 3.1. Log Entries . . . . . . . . . . . . . . . . . . . . . . . 10 73 3.2. Private Domain Name Labels . . . . . . . . . . . . . . . 12 74 3.2.1. Wildcard Certificates . . . . . . . . . . . . . . . . 13 75 3.2.2. Redacting Domain Name Labels in Precertificates . . . 13 76 3.2.3. Using a Name-Constrained Intermediate CA . . . . . . 14 77 3.3. Structure of the Signed Certificate Timestamp . . . . . . 15 78 3.4. Including the Signed Certificate Timestamp in the TLS 79 Handshake . . . . . . . . . . . . . . . . . . . . . . . . 17 80 3.4.1. TLS Extension . . . . . . . . . . . . . . . . . . . . 18 81 3.4.2. X.509v3 Extension . . . . . . . . . . . . . . . . . . 18 82 3.5. Merkle Tree . . . . . . . . . . . . . . . . . . . . . . . 19 83 3.6. Signed Tree Head . . . . . . . . . . . . . . . . . . . . 20 84 4. Log Client Messages . . . . . . . . . . . . . . . . . . . . . 20 85 4.1. Add Chain to Log . . . . . . . . . . . . . . . . . . . . 22 86 4.2. Add PreCertChain to Log . . . . . . . . . . . . . . . . . 23 87 4.3. Retrieve Latest Signed Tree Head . . . . . . . . . . . . 23 88 4.4. Retrieve Merkle Consistency Proof between Two Signed Tree 89 Heads . . . . . . . . . . . . . . . . . . . . . . . . . . 24 90 4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash . . 25 91 4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and 92 Consistency Proof by Leaf Hash . . . . . . . . . . . . . 26 94 4.7. Retrieve Entries and STH from Log . . . . . . . . . . . . 27 95 4.8. Retrieve Accepted Root Certificates . . . . . . . . . . . 28 96 5. Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 97 5.1. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 29 98 5.2. Submitters . . . . . . . . . . . . . . . . . . . . . . . 30 99 5.3. TLS Client . . . . . . . . . . . . . . . . . . . . . . . 30 100 5.4. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 30 101 5.5. Auditing . . . . . . . . . . . . . . . . . . . . . . . . 31 102 5.5.1. Verifying an inclusion proof . . . . . . . . . . . . 32 103 5.5.2. Verifying consistency between two STHs . . . . . . . 32 104 5.5.3. Verifying root hash given entries . . . . . . . . . . 33 105 6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . . . 34 106 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 34 107 7.1. TLS Extension Type . . . . . . . . . . . . . . . . . . . 34 108 7.2. Hash Algorithms . . . . . . . . . . . . . . . . . . . . . 34 109 8. Security Considerations . . . . . . . . . . . . . . . . . . . 34 110 8.1. Misissued Certificates . . . . . . . . . . . . . . . . . 35 111 8.2. Detection of Misissue . . . . . . . . . . . . . . . . . . 35 112 8.3. Redaction of Public Domain Name Labels . . . . . . . . . 35 113 8.4. Misbehaving Logs . . . . . . . . . . . . . . . . . . . . 36 114 8.5. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . . 36 115 9. Efficiency Considerations . . . . . . . . . . . . . . . . . . 37 116 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 37 117 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 118 11.1. Normative References . . . . . . . . . . . . . . . . . . 37 119 11.2. Informative References . . . . . . . . . . . . . . . . . 38 121 1. Introduction 123 Certificate transparency aims to mitigate the problem of misissued 124 certificates by providing publicly auditable, append-only, untrusted 125 logs of all issued certificates. The logs are publicly auditable so 126 that it is possible for anyone to verify the correctness of each log 127 and to monitor when new certificates are added to it. The logs do 128 not themselves prevent misissue, but they ensure that interested 129 parties (particularly those named in certificates) can detect such 130 misissuance. Note that this is a general mechanism, but in this 131 document, we only describe its use for public TLS server certificates 132 issued by public certification authorities (CAs). 134 Each log consists of certificate chains, which can be submitted by 135 anyone. It is expected that public CAs will contribute all their 136 newly issued certificates to one or more logs, however certificate 137 holders can also contribute their own certificate chains, as can 138 third parties. In order to avoid logs being rendered useless by 139 submitting large numbers of spurious certificates, it is required 140 that each chain is rooted in a CA certificate accepted by the log. 141 When a chain is submitted to a log, a signed timestamp is returned, 142 which can later be used to provide evidence to TLS clients that the 143 chain has been submitted. TLS clients can thus require that all 144 certificates they accept as valid have been logged. 146 Those who are concerned about misissue can monitor the logs, asking 147 them regularly for all new entries, and can thus check whether 148 domains they are responsible for have had certificates issued that 149 they did not expect. What they do with this information, 150 particularly when they find that a misissuance has happened, is 151 beyond the scope of this document, but broadly speaking, they can 152 invoke existing business mechanisms for dealing with misissued 153 certificates, such as working with the CA to get the certificate 154 revoked, or with maintainers of trust anchor lists to get the CA 155 removed. Of course, anyone who wants can monitor the logs and, if 156 they believe a certificate is incorrectly issued, take action as they 157 see fit. 159 Similarly, those who have seen signed timestamps from a particular 160 log can later demand a proof of inclusion from that log. If the log 161 is unable to provide this (or, indeed, if the corresponding 162 certificate is absent from monitors' copies of that log), that is 163 evidence of the incorrect operation of the log. The checking 164 operation is asynchronous to allow TLS connections to proceed without 165 delay, despite network connectivity issues and the vagaries of 166 firewalls. 168 The append-only property of each log is technically achieved using 169 Merkle Trees, which can be used to show that any particular instance 170 of the log is a superset of any particular previous instance. 171 Likewise, Merkle Trees avoid the need to blindly trust logs: if a log 172 attempts to show different things to different people, this can be 173 efficiently detected by comparing tree roots and consistency proofs. 174 Similarly, other misbehaviors of any log (e.g., issuing signed 175 timestamps for certificates they then don't log) can be efficiently 176 detected and proved to the world at large. 178 1.1. Requirements Language 180 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 181 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 182 document are to be interpreted as described in RFC 2119 [RFC2119]. 184 1.2. Data Structures 186 Data structures are defined according to the conventions laid out in 187 Section 4 of [RFC5246]. 189 2. Cryptographic Components 191 2.1. Merkle Hash Trees 193 Logs use a binary Merkle Hash Tree for efficient auditing. The 194 hashing algorithm used by each log is expected to be specified as 195 part of the metadata relating to that log. We have established a 196 registry of acceptable algorithms, see Section 7.2. The hashing 197 algorithm in use is referred to as HASH throughout this document and 198 the size of its output in bytes as HASH_SIZE. The input to the 199 Merkle Tree Hash is a list of data entries; these entries will be 200 hashed to form the leaves of the Merkle Hash Tree. The output is a 201 single HASH_SIZE Merkle Tree Hash. Given an ordered list of n 202 inputs, D[n] = {d(0), d(1), ..., d(n-1)}, the Merkle Tree Hash (MTH) 203 is thus defined as follows: 205 The hash of an empty list is the hash of an empty string: 207 MTH({}) = HASH(). 209 The hash of a list with one entry (also known as a leaf hash) is: 211 MTH({d(0)}) = HASH(0x00 || d(0)). 213 For n > 1, let k be the largest power of two smaller than n (i.e., k 214 < n <= 2k). The Merkle Tree Hash of an n-element list D[n] is then 215 defined recursively as 217 MTH(D[n]) = HASH(0x01 || MTH(D[0:k]) || MTH(D[k:n])), 219 where || is concatenation and D[k1:k2] denotes the list {d(k1), 220 d(k1+1),..., d(k2-1)} of length (k2 - k1). (Note that the hash 221 calculations for leaves and nodes differ. This domain separation is 222 required to give second preimage resistance.) 224 Note that we do not require the length of the input list to be a 225 power of two. The resulting Merkle Tree may thus not be balanced; 226 however, its shape is uniquely determined by the number of leaves. 227 (Note: This Merkle Tree is essentially the same as the history tree 228 [CrosbyWallach] proposal, except our definition handles non-full 229 trees differently.) 231 2.1.1. Merkle Inclusion Proofs 233 A Merkle inclusion proof for a leaf in a Merkle Hash Tree is the 234 shortest list of additional nodes in the Merkle Tree required to 235 compute the Merkle Tree Hash for that tree. Each node in the tree is 236 either a leaf node or is computed from the two nodes immediately 237 below it (i.e., towards the leaves). At each step up the tree 238 (towards the root), a node from the inclusion proof is combined with 239 the node computed so far. In other words, the inclusion proof 240 consists of the list of missing nodes required to compute the nodes 241 leading from a leaf to the root of the tree. If the root computed 242 from the inclusion proof matches the true root, then the inclusion 243 proof proves that the leaf exists in the tree. 245 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 246 d(n-1)}, the Merkle inclusion proof PATH(m, D[n]) for the (m+1)th 247 input d(m), 0 <= m < n, is defined as follows: 249 The proof for the single leaf in a tree with a one-element input list 250 D[1] = {d(0)} is empty: 252 PATH(0, {d(0)}) = {} 254 For n > 1, let k be the largest power of two smaller than n. The 255 proof for the (m+1)th element d(m) in a list of n > m elements is 256 then defined recursively as 258 PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n]) for m < k; and 260 PATH(m, D[n]) = PATH(m - k, D[k:n]) : MTH(D[0:k]) for m >= k, 262 where : is concatenation of lists and D[k1:k2] denotes the length (k2 263 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 265 2.1.2. Merkle Consistency Proofs 267 Merkle consistency proofs prove the append-only property of the tree. 268 A Merkle consistency proof for a Merkle Tree Hash MTH(D[n]) and a 269 previously advertised hash MTH(D[0:m]) of the first m leaves, m <= n, 270 is the list of nodes in the Merkle Tree required to verify that the 271 first m inputs D[0:m] are equal in both trees. Thus, a consistency 272 proof must contain a set of intermediate nodes (i.e., commitments to 273 inputs) sufficient to verify MTH(D[n]), such that (a subset of) the 274 same nodes can be used to verify MTH(D[0:m]). We define an algorithm 275 that outputs the (unique) minimal consistency proof. 277 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 278 d(n-1)}, the Merkle consistency proof PROOF(m, D[n]) for a previous 279 Merkle Tree Hash MTH(D[0:m]), 0 < m < n, is defined as: 281 PROOF(m, D[n]) = SUBPROOF(m, D[n], true) 282 The subproof for m = n is empty if m is the value for which PROOF was 283 originally requested (meaning that the subtree Merkle Tree Hash 284 MTH(D[0:m]) is known): 286 SUBPROOF(m, D[m], true) = {} 288 The subproof for m = n is the Merkle Tree Hash committing inputs 289 D[0:m]; otherwise: 291 SUBPROOF(m, D[m], false) = {MTH(D[m])} 293 For m < n, let k be the largest power of two smaller than n. The 294 subproof is then defined recursively. 296 If m <= k, the right subtree entries D[k:n] only exist in the current 297 tree. We prove that the left subtree entries D[0:k] are consistent 298 and add a commitment to D[k:n]: 300 SUBPROOF(m, D[n], b) = SUBPROOF(m, D[0:k], b) : MTH(D[k:n]) 302 If m > k, the left subtree entries D[0:k] are identical in both 303 trees. We prove that the right subtree entries D[k:n] are consistent 304 and add a commitment to D[0:k]. 306 SUBPROOF(m, D[n], b) = SUBPROOF(m - k, D[k:n], false) : MTH(D[0:k]) 308 Here, : is a concatenation of lists, and D[k1:k2] denotes the length 309 (k2 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 311 The number of nodes in the resulting proof is bounded above by 312 ceil(log2(n)) + 1. 314 2.1.3. Example 316 The binary Merkle Tree with 7 leaves: 318 hash 319 / \ 320 / \ 321 / \ 322 / \ 323 / \ 324 k l 325 / \ / \ 326 / \ / \ 327 / \ / \ 328 g h i j 329 / \ / \ / \ | 330 a b c d e f d6 331 | | | | | | 332 d0 d1 d2 d3 d4 d5 334 The inclusion proof for d0 is [b, h, l]. 336 The inclusion proof for d3 is [c, g, l]. 338 The inclusion proof for d4 is [f, j, k]. 340 The inclusion proof for d6 is [i, k]. 342 The same tree, built incrementally in four steps: 344 hash0 hash1=k 345 / \ / \ 346 / \ / \ 347 / \ / \ 348 g c g h 349 / \ | / \ / \ 350 a b d2 a b c d 351 | | | | | | 352 d0 d1 d0 d1 d2 d3 354 hash2 hash 355 / \ / \ 356 / \ / \ 357 / \ / \ 358 / \ / \ 359 / \ / \ 360 k i k l 361 / \ / \ / \ / \ 362 / \ e f / \ / \ 363 / \ | | / \ / \ 364 g h d4 d5 g h i j 365 / \ / \ / \ / \ / \ | 366 a b c d a b c d e f d6 367 | | | | | | | | | | 368 d0 d1 d2 d3 d0 d1 d2 d3 d4 d5 370 The consistency proof between hash0 and hash is PROOF(3, D[7]) = [c, 371 d, g, l]. c, g are used to verify hash0, and d, l are additionally 372 used to show hash is consistent with hash0. 374 The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l]. 375 hash can be verified using hash1=k and l. 377 The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i, 378 j, k]. k, i are used to verify hash2, and j is additionally used to 379 show hash is consistent with hash2. 381 2.1.4. Signatures 383 Various data structures are signed. A log MUST use either 384 deterministic ECDSA [RFC6979] using the NIST P-256 curve 385 (Section D.1.2.3 of the Digital Signature Standard [DSS]) and HMAC- 386 SHA256 or RSA signatures (RSASSA-PKCS1-v1_5 with SHA-256, Section 8.2 387 of [RFC3447]) using a key of at least 2048 bits. 389 3. Log Format and Operation 391 Anyone can submit certificates to certificate logs for public 392 auditing; however, since certificates will not be accepted by TLS 393 clients unless logged, it is expected that certificate owners or 394 their CAs will usually submit them. A log is a single, ever-growing, 395 append-only Merkle Tree of such certificates. 397 When a valid certificate is submitted to a log, the log MUST return a 398 Signed Certificate Timestamp (SCT). The SCT is the log's promise to 399 incorporate the certificate in the Merkle Tree within a fixed amount 400 of time known as the Maximum Merge Delay (MMD). If the log has 401 previously seen the certificate, it MAY return the same SCT as it 402 returned before (note that if a certificate was previously logged as 403 a precertificate, then the precertificate's SCT would not be 404 appropriate, instead a fresh SCT of type x509_entry should be 405 generated). TLS servers MUST present an SCT from one or more logs to 406 the TLS client together with the certificate. A certificate not 407 accompanied by an SCT (either for the end-entity certificate or for a 408 name-constrained intermediate the end-entity certificate chains to) 409 MUST NOT be considered compliant by TLS clients. 411 Periodically, each log appends all its new entries to the Merkle Tree 412 and signs the root of the tree. The log MUST incorporate a 413 certificate in its Merkle Tree within the Maximum Merge Delay period 414 after the issuance of the SCT. When encountering an SCT, an Auditor 415 can verify that the certificate was added to the Merkle Tree within 416 that timeframe. 418 Log operators MUST NOT impose any conditions on retrieving or sharing 419 data from the log. 421 3.1. Log Entries 423 In order to enable attribution of each logged certificate to its 424 issuer, each submitted certificate MUST be accompanied by all 425 additional certificates required to verify the certificate chain up 426 to an accepted root certificate. The root certificate itself MAY be 427 omitted from the chain submitted to the log server. The log SHALL 428 allow retrieval of a list of accepted root certificates (this list 429 might usefully be the union of root certificates trusted by major 430 browser vendors). 432 Alternatively, (root as well as intermediate) certification 433 authorities may preannounce a certificate to logs prior to issuance 434 in order to incorporate the SCT in the issued certificate. To do 435 this, the CA submits a precertificate that the log can use to create 436 an entry that will be valid against the issued certificate. A 437 precertificate is a CMS [RFC5652] "signed-data" object that contains 438 a TBSCertificate [RFC5280] in its 439 "SignedData.encapContentInfo.eContent" field, identified by the OID 440 in the "SignedData.encapContentInfo.eContentType" field. This 441 TBSCertificate MAY redact certain domain name labels that will be 442 present in the issued certificate (see Section 3.2.2) and MUST NOT 443 contain any SCTs, but it will be otherwise identical to the 444 TBSCertificate in the issued certificate. "SignedData.signerInfos" 445 MUST contain a signature from the same (root or intermediate) CA that 446 will ultimately issue the certificate. This signature indicates the 447 certification authority's intent to issue the certificate. This 448 intent is considered binding (i.e., misissuance of the precertificate 449 is considered equivalent to misissuance of the certificate). As 450 above, the precertificate submission MUST be accompanied by all the 451 additional certificates required to verify the chain up to an 452 accepted root certificate. This does not involve using the 453 "SignedData.certificates" field, so that field SHOULD be omitted. 455 The CMS object MUST be DER encoded. Note that, because of the 456 structure of CMS, the signature on the CMS object will not be a valid 457 X.509v3 signature and so cannot be used to construct a certificate 458 from the precertificate. 460 Logs MUST verify that the submitted certificate or precertificate has 461 a valid signature chain to an accepted root certificate, using the 462 chain of intermediate CA certificates provided by the submitter. 463 Logs MUST accept certificates that are fully valid according to RFC 464 5280 [RFC5280] verification rules and are submitted with such a 465 chain. Logs MAY accept certificates and precertificates that have 466 expired, are not yet valid, have been revoked, or are otherwise not 467 fully valid according to RFC 5280 verification rules in order to 468 accommodate quirks of CA certificate-issuing software. However, logs 469 MUST reject certificates without a valid signature chain to an 470 accepted root certificate. Logs MUST also reject precertificates 471 that are not valid DER encoded CMS "signed-data" objects. If a 472 certificate is accepted and an SCT issued, the accepting log MUST 473 store the entire chain used for verification, including the 474 certificate or precertificate itself and including the root 475 certificate used to verify the chain (even if it was omitted from the 476 submission), and MUST present this chain for auditing upon request. 477 This chain is required to prevent a CA from avoiding blame by logging 478 a partial or empty chain. (Note: This effectively excludes self- 479 signed and DANE-based certificates until some mechanism to limit the 480 submission of spurious certificates is found. The authors welcome 481 suggestions.) 483 Each certificate or precertificate entry in a log MUST include the 484 following components: 486 enum { x509_entry(0), precert_entry_V2(2), (65535) } LogEntryType; 488 opaque ASN.1Cert<1..2^24-1>; 490 struct { 491 ASN.1Cert leaf_certificate; 492 ASN.1Cert certificate_chain<0..2^24-1>; 493 } X509ChainEntry; 495 opaque CMSPrecert<1..2^24-1>; 497 struct { 498 CMSPrecert pre_certificate; 499 ASN.1Cert precertificate_chain<0..2^24-1>; 500 } PrecertChainEntryV2; 502 Logs SHOULD limit the length of chain they will accept. 504 "entry_type" is the type of this entry. Future revisions of this 505 protocol may add new LogEntryType values. Section 4 explains how 506 clients should handle unknown entry types. 508 "leaf_certificate" is the end-entity certificate submitted for 509 auditing. 511 "certificate_chain" is an array of additional certificates required 512 to verify the end-entity certificate. The first certificate MUST 513 certify the end-entity certificate. Each following certificate MUST 514 directly certify the one preceding it. The final certificate MUST 515 either be, or be issued by, a root certificate accepted by the log. 516 If the end-entity certificate is a root certificate, then this array 517 is empty. 519 "pre_certificate" is the precertificate submitted for auditing. 521 "precertificate_chain" is a chain of additional certificates required 522 to verify the precertificate submission. The first certificate MUST 523 certify the precertificate. Each following certificate MUST directly 524 certify the one preceding it. The final certificate MUST be a root 525 certificate accepted by the log. 527 3.2. Private Domain Name Labels 529 Some regard some DNS domain name labels within their registered 530 domain space as private and security sensitive. Even though these 531 domains are often only accessible within the domain owner's private 532 network, it's common for them to be secured using publicly trusted 533 TLS server certificates. We define a mechanism to allow these 534 private labels to not appear in public logs. 536 3.2.1. Wildcard Certificates 538 A certificate containing a DNS-ID [RFC6125] of "*.example.com" could 539 be used to secure the domain "topsecret.example.com", without 540 revealing the string "topsecret" publicly. 542 Since TLS clients only match the wildcard character to the complete 543 leftmost label of the DNS domain name (see Section 6.4.3 of 544 [RFC6125]), this approach would not work for a DNS-ID such as 545 "top.secret.example.com". Also, wildcard certificates are prohibited 546 in some cases, such as Extended Validation Certificates 547 [EVSSLGuidelines]. 549 3.2.2. Redacting Domain Name Labels in Precertificates 551 When creating a precertificate, the CA MAY substitute one or more 552 labels in each DNS-ID with a corresponding number of "?" labels. 553 Every label to the left of a "?" label MUST also be redacted. For 554 example, if a certificate contains a DNS-ID of 555 "top.secret.example.com", then the corresponding precertificate could 556 contain "?.?.example.com" instead, but not "top.?.example.com" 557 instead. 559 Wildcard "*" labels MUST NOT be redacted. However, if the complete 560 leftmost label of a DNS-ID is "*", it is considered redacted for the 561 purposes of determining if the label to the right may be redacted. 562 For example, if a certificate contains a DNS-ID of 563 "*.top.secret.example.com", then the corresponding precertificate 564 could contain "*.?.?.example.com" instead, but not 565 "?.?.?.example.com" instead. 567 When a precertificate contains one or more redacted labels, a non- 568 critical extension (OID 1.3.6.1.4.1.11129.2.4.6, whose extnValue 569 OCTET STRING contains an ASN.1 SEQUENCE OF INTEGERs) MUST be added to 570 the corresponding certificate: the first INTEGER indicates the total 571 number of redacted labels and wildcard "*" labels in the 572 precertificate's first DNS-ID; the second INTEGER does the same for 573 the precertificate's second DNS-ID; etc. There MUST NOT be more 574 INTEGERs than there are DNS-IDs. If there are fewer INTEGERs than 575 there are DNS-IDs, the shortfall is made up by implicitly repeating 576 the last INTEGER. Each INTEGER MUST have a value of zero or more. 577 The purpose of this extension is to enable TLS clients to accurately 578 reconstruct the TBSCertificate component of the precertificate from 579 the certificate without having to perform any guesswork. 581 When a precertificate contains that extension and contains a CN-ID 582 [RFC6125], the CN-ID MUST match the first DNS-ID and have the same 583 labels redacted. TLS clients will use the first entry in the 584 SEQUENCE OF INTEGERs to reconstruct both the first DNS-ID and the CN- 585 ID. 587 3.2.3. Using a Name-Constrained Intermediate CA 589 An intermediate CA certificate or intermediate CA precertificate that 590 contains the critical or non-critical Name Constraints [RFC5280] 591 extension MAY be logged in place of end-entity certificates issued by 592 that intermediate CA, as long as all of the following conditions are 593 met: 595 o there MUST be a non-critical extension (OID 596 1.3.6.1.4.1.11129.2.4.7, whose extnValue OCTET STRING contains 597 ASN.1 NULL data (0x05 0x00)). This extension is an explicit 598 indication that it is acceptable to not log certificates issued by 599 this intermediate CA. 601 o permittedSubtrees MUST specify one or more dNSNames. 603 o excludedSubtrees MUST specify the entire IPv4 and IPv6 address 604 ranges. 606 Below is an example Name Constraints extension that meets these 607 conditions: 609 SEQUENCE { 610 OBJECT IDENTIFIER '2 5 29 30' 611 OCTET STRING, encapsulates { 612 SEQUENCE { 613 [0] { 614 SEQUENCE { 615 [2] 'example.com' 616 } 617 } 618 [1] { 619 SEQUENCE { 620 [7] 00 00 00 00 00 00 00 00 621 } 622 SEQUENCE { 623 [7] 624 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 625 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 626 } 627 } 628 } 629 } 630 } 632 3.3. Structure of the Signed Certificate Timestamp 634 enum { certificate_timestamp(0), tree_hash(1), (255) } 635 SignatureType; 637 enum { v2(1), (255) } 638 Version; 640 struct { 641 opaque key_id[HASH_SIZE]; 642 } LogID; 644 opaque TBSCertificate<1..2^24-1>; 646 struct { 647 opaque issuer_key_hash[HASH_SIZE]; 648 TBSCertificate tbs_certificate; 649 } CertInfo; 651 opaque CtExtensions<0..2^16-1>; 653 "key_id" is the HASH of the log's public key, calculated over the DER 654 encoding of the key represented as SubjectPublicKeyInfo. 656 "issuer_key_hash" is the HASH of the certificate issuer's public key, 657 calculated over the DER encoding of the key represented as 658 SubjectPublicKeyInfo. This is needed to bind the issuer to the final 659 certificate, making it impossible for the SCT to be valid for any 660 other certificate. 662 "tbs_certificate" is the DER-encoded TBSCertificate component of the 663 precertificate. Note that it is also possible to reconstruct this 664 TBSCertificate from the issued certificate by extracting the 665 TBSCertificate from it, redacting the domain name labels indicated by 666 the redacted labels extension, and deleting the SCT list extension 667 and redacted labels extension. 669 struct { 670 Version sct_version; 671 LogID id; 672 uint64 timestamp; 673 CtExtensions extensions; 674 digitally-signed struct { 675 Version sct_version; 676 SignatureType signature_type = certificate_timestamp; 677 uint64 timestamp; 678 LogEntryType entry_type; 679 select(entry_type) { 680 case x509_entry: CertInfo; 681 case precert_entry_V2: CertInfo; 682 } signed_entry; 683 CtExtensions extensions; 684 }; 685 } SignedCertificateTimestamp; 687 The encoding of the digitally-signed element is defined in [RFC5246]. 689 "sct_version" is the version of the protocol to which the SCT 690 conforms. This version is v2. Note that SignedCertificateTimestamp 691 v1 [RFC6962] had a different definition of "signed_entry". 693 "timestamp" is the current NTP Time [RFC5905], measured since the 694 epoch (January 1, 1970, 00:00), ignoring leap seconds, in 695 milliseconds. 697 "entry_type" may be implicit from the context in which the SCT is 698 presented. 700 "signed_entry" includes the TBSCertificate from either the 701 "leaf_certificate" (in the case of an X509ChainEntry) or the 702 "pre_certificate" (in the case of a PrecertChainEntryV2). 704 "extensions" are future extensions to SignedCertificateTimestamp v2. 705 Currently, no extensions are specified. 707 3.4. Including the Signed Certificate Timestamp in the TLS Handshake 709 The SCT data corresponding to at least one certificate in the chain 710 from at least one log must be included in the TLS handshake by using 711 one or more of the mechanisms listed below. Three mechanisms are 712 provided because they have different tradeoffs. TLS clients MUST 713 implement all three mechanisms. TLS servers MUST present SCTs using 714 at least one of the three mechanisms. 716 o A TLS extension (Section 7.4.1.4 of [RFC5246]) with type 717 "signed_certificate_timestamp" (see Section 3.4.1). This 718 mechanism allows TLS servers to participate in CT without the 719 cooperation of CAs, unlike the other two mechanisms. It also 720 allows SCTs to be updated on the fly. 722 o An Online Certificate Status Protocol (OCSP) [RFC6960] response 723 extension (see Section 3.4.2.1), where the OCSP response is 724 provided in the "certificate_status" TLS extension (Section 8 of 725 [RFC6066]), also known as OCSP stapling. This mechanism is 726 already widely (but not universally) implemented. It also allows 727 SCTs to be updated on the fly. 729 o An X509v3 certificate extension (see Section 3.4.2.2). This 730 mechanism allows the use of unmodified TLS servers, but, because 731 the included SCTs cannot be changed without re-issuing the 732 certificate, increases the risk that the certificate will be 733 refused if any of the SCTs become invalid. 735 TLS servers SHOULD send SCTs from multiple logs in case one or more 736 logs are not acceptable to the TLS client (for example, if a log has 737 been struck off for misbehavior, has had a key compromise or is not 738 known to the TLS client). Multiple SCTs are combined into an SCT 739 list as follows: 741 opaque SerializedSCT<1..2^16-1>; 743 struct { 744 SerializedSCT sct_list <1..2^16-1>; 745 } SignedCertificateTimestampList; 747 Here, "SerializedSCT" is an opaque byte string that contains the 748 serialized SCT structure. This encoding ensures that TLS clients can 749 decode each SCT individually (i.e., if there is a version upgrade, 750 out-of-date clients can still parse old SCTs while skipping over new 751 SCTs whose versions they don't understand). 753 3.4.1. TLS Extension 755 One or more SCTs can be sent during the TLS handshake using a TLS 756 extension with type "signed_certificate_timestamp". 758 TLS clients that support the extension SHOULD send a ClientHello 759 extension with the appropriate type and empty "extension_data". 761 TLS servers MUST only send SCTs in this TLS extension to TLS clients 762 that have indicated support for the extension in the ClientHello, in 763 which case the SCTs are sent by setting the "extension_data" to a 764 "SignedCertificateTimestampList". 766 Session resumption uses the original session information: TLS clients 767 SHOULD include the extension type in the ClientHello, but if the 768 session is resumed, the TLS server is not expected to process it or 769 include the extension in the ServerHello. 771 3.4.2. X.509v3 Extension 773 One or more SCTs can be embedded in an X.509v3 extension that is 774 included in a certificate or an OCSP response. Since RFC5280 775 requires the "extnValue" field (an OCTET STRING) of each X.509v3 776 extension to include the DER encoding of an ASN.1 value, we cannot 777 embed a "SignedCertificateTimestampList" directly. Instead, we have 778 to wrap it inside an additional OCTET STRING (see below), which we 779 then put into the "extnValue" field. 781 3.4.2.1. OCSP Response Extension 783 A certification authority may embed one or more SCTs in OCSP 784 responses pertaining to the end-entity certificate, by including a 785 non-critical "singleExtensions" extension with OID 786 1.3.6.1.4.1.11129.2.4.5 whose "extnValue" contains: 788 CertificateSCTList ::= OCTET STRING 790 "CertificateSCTList" contains a "SignedCertificateTimestampList" 791 whose SCTs all have the "x509_entry" "LogEntryType". 793 3.4.2.2. Certificate Extension 795 A certification authority that has submitted a precertificate to one 796 or more logs may embed the obtained SCTs in the "TBSCertificate" that 797 will be signed to produce the certificate, by including a non- 798 critical X.509v3 extension with OID 1.3.6.1.4.1.11129.2.4.2 whose 799 "extnValue" contains: 801 PrecertificateSCTList ::= OCTET STRING 803 "PrecertificateSCTList" contains a "SignedCertificateTimestampList" 804 whose SCTs all have the "precert_entry_V2" "LogEntryType". 806 Upon receiving the certificate, clients can reconstruct the original 807 "TBSCertificate" to verify the SCT signatures. 809 3.5. Merkle Tree 811 The hashing algorithm for the Merkle Tree Hash is specified in the 812 log's metadata. 814 Structure of the Merkle Tree input: 816 enum { v1(0), v2(1), (255) } 817 LeafVersion; 819 struct { 820 uint64 timestamp; 821 LogEntryType entry_type; 822 select(entry_type) { 823 case x509_entry: CertInfo; 824 case precert_entry_V2: CertInfo; 825 } signed_entry; 826 CtExtensions extensions; 827 } TimestampedEntry; 829 struct { 830 LeafVersion version; 831 TimestampedEntry timestamped_entry; 832 } MerkleTreeLeaf; 834 Here, "version" is the version of the MerkleTreeLeaf structure. This 835 version is v2. Note that MerkleTreeLeaf v1 [RFC6962] had another 836 layer of indirection which is removed in v2. 838 "timestamp" is the timestamp of the corresponding SCT issued for this 839 certificate. 841 "entry_type" is the type of entry stored in "signed_entry". New 842 "LogEntryType" values may be added to "signed_entry" without 843 increasing the "MerkleTreeLeaf" version. Section 4 explains how 844 clients should handle unknown entry types. 846 "signed_entry" is the "signed_entry" of the corresponding SCT. 848 "extensions" are "extensions" of the corresponding SCT. 850 The leaves of the Merkle Tree are the leaf hashes of the 851 corresponding "MerkleTreeLeaf" structures. Note that leaf hashes 852 (Section 2.1) are calculated as HASH(0x00 || MerkleTreeLeaf). 854 3.6. Signed Tree Head 856 Periodically the log SHOULD sign the corresponding tree hash and tree 857 information (see the corresponding Signed Tree Head client message in 858 Section 4.3). The signature for that data is structured as follows: 860 enum { v1(0), (255) } TreeHeadVersion; 862 digitally-signed struct { 863 TreeHeadVersion version; 864 SignatureType signature_type = tree_hash; 865 uint64 timestamp; 866 uint64 tree_size; 867 opaque root_hash[HASH_SIZE]; 868 } TreeHeadSignature; 870 "version" is the version of the TreeHeadSignature structure. This 871 version is v1. 873 "timestamp" is the current time. The timestamp MUST be at least as 874 recent as the most recent SCT timestamp in the tree. Each subsequent 875 timestamp MUST be more recent than the timestamp of the previous 876 update. 878 "tree_size" equals the number of entries in the new tree. 880 "root_hash" is the root of the Merkle Hash Tree. 882 Each log MUST produce on demand a Signed Tree Head that is no older 883 than the Maximum Merge Delay. However, Signed Tree Heads could be 884 used to mark individual clients (by producing a new one for each 885 query), so logs MUST NOT produce them more frequently than is 886 declared in their metadata. In general, there is no need to produce 887 a new Signed Tree Head unless there are new entries in the log, 888 however, in the unlikely event that it receives no new submissions 889 during an MMD period, the log SHALL sign the same Merkle Tree Hash 890 with a fresh timestamp. 892 4. Log Client Messages 894 Messages are sent as HTTPS GET or POST requests. Parameters for 895 POSTs and all responses are encoded as JavaScript Object Notation 896 (JSON) objects [RFC4627]. Parameters for GETs are encoded as order- 897 independent key/value URL parameters, using the "application/x-www- 898 form-urlencoded" format described in the "HTML 4.01 Specification" 899 [HTML401]. Binary data is base64 encoded [RFC4648] as specified in 900 the individual messages. 902 Note that JSON objects and URL parameters may contain fields not 903 specified here. These extra fields should be ignored. 905 The prefix MAY include a path as well as a server name 906 and a port. 908 In general, where needed, the "version" is v1 and the "id" is the log 909 id for the log server queried. 911 In practice, log servers may include multiple front-end machines. 912 Since it is impractical to keep these machines in perfect sync, 913 errors may occur that are caused by skew between the machines. Where 914 such errors are possible, the front-end will return additional 915 information (as specified below) making it possible for clients to 916 make progress, if progress is possible. Front-ends MUST only serve 917 data that is free of gaps (that is, for example, no front-end will 918 respond with an STH unless it is also able to prove consistency from 919 all log entries logged within that STH). 921 For example, when a consistency proof between two STHs is requested, 922 the front-end reached may not yet be aware of one or both STHs. In 923 the case where it is unaware of both, it will return the latest STH 924 it is aware of. Where it is aware of the first but not the second, 925 it will return the latest STH it is aware of and a consistency proof 926 from the first STH to the returned STH. The case where it knows the 927 second but not the first should not arise (see the "no gaps" 928 requirement above). 930 If the log is unable to process a client's request, it MUST return an 931 HTTP response code of 4xx/5xx (see [RFC2616]), and, in place of the 932 responses outlined in the subsections below, the body SHOULD be a 933 JSON structure containing at least the following field: 935 error_message: A human-readable string describing the error which 936 prevented the log from processing the request. 938 In the case of a malformed request, the string SHOULD provide 939 sufficient detail for the error to be rectified. 941 error_code: An error code readable by the client. Some codes are 942 generic and are detailed here. Others are detailed in the 943 individual requests. Error codes are fixed text strings. 945 not compliant The request is not compliant with this RFC. 947 e.g. In response to a request of "/ct/v2/get- 948 entries?start=100&end=99", the log would return a "400 Bad Request" 949 response code with a body similar to the following: 951 { 952 "error_message": "'start' cannot be greater than 'end'", 953 "error_code": "not compliant", 954 } 956 Clients SHOULD treat "500 Internal Server Error" and "503 Service 957 Unavailable" responses as transient failures and MAY retry the same 958 request without modification at a later date. Note that as per 959 [RFC2616], in the case of a 503 response the log MAY include a 960 "Retry-After:" header in order to request a minimum time for the 961 client to wait before retrying the request. 963 4.1. Add Chain to Log 965 POST https:///ct/v2/add-chain 967 Inputs: 969 chain: An array of base64 encoded certificates. The first 970 element is the end-entity certificate; the second chains to the 971 first and so on to the last, which is either the root 972 certificate or a certificate that chains to a known root 973 certificate. 975 Outputs: 977 sct: The base64 encoded "SignedCertificateTimestamp" for the 978 submitted certificate. 980 Error codes: 982 unknown root The root of the chain is not one accepted by the 983 log. 985 bad chain The alleged chain is not actually a chain of 986 certificates. 988 bad certificate One or more certificates in the chain are not 989 valid (e.g. not properly encoded). 991 If the version of "sct" is not v2, then a v2 client may be unable to 992 verify the signature. It MUST NOT construe this as an error. This 993 is to avoid forcing an upgrade of compliant v2 clients that do not 994 use the returned SCTs. 996 If a log detects bad encoding in a chain that otherwise verifies 997 correctly then the log MAY still log the certificate but SHOULD NOT 998 return an SCT. It should instead return the "bad certificate" error. 999 Logging the certificate is useful, because monitors (Section 5.4) can 1000 then detect these encoding errors, which may be accepted by some TLS 1001 clients. 1003 Note that not all certificate handling software is capable of 1004 detecting all encoding errors (e.g. some software will accept BER 1005 instead of DER encodings in certificates, or incorrect character 1006 encodings, even though these are technically incorrect) . 1008 4.2. Add PreCertChain to Log 1010 POST https:///ct/v2/add-pre-chain 1012 Inputs: 1014 precertificate: The base64 encoded precertificate. 1016 chain: An array of base64 encoded CA certificates. The first 1017 element is the signer of the precertificate; the second chains 1018 to the first and so on to the last, which is either the root 1019 certificate or a certificate that chains to an accepted root 1020 certificate. 1022 Outputs and errors are the same as in Section 4.1. 1024 4.3. Retrieve Latest Signed Tree Head 1026 GET https:///ct/v1/get-sth 1028 No inputs. 1030 Outputs: 1032 tree_size: The size of the tree, in entries, in decimal. 1034 timestamp: The timestamp, in decimal. 1036 root_hash: The base64 encoded Merkle Tree Hash of the tree. 1038 tree_head_signature: A base64 encoded TreeHeadSignature for 1039 "tree_size", "timestamp" and "root_hash". 1041 4.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads 1043 GET https:///ct/v2/get-sth-consistency 1045 Inputs: 1047 first: The tree_size of the older tree, in decimal. 1049 second: The tree_size of the newer tree, in decimal (optional). 1051 Both tree sizes must be from existing v1 STHs (Signed Tree Heads). 1052 However, because of skew, the receiving front-end may not know one 1053 or both of the existing STHs. If both are known, then only the 1054 "consistency" output is returned. If the first is known but the 1055 second is not (or has been omitted), then the latest known STH is 1056 returned, along with a consistency proof between the first STH and 1057 the latest. If neither are known, then the latest known STH is 1058 returned without a consistency proof. 1060 Outputs: 1062 consistency: An array of base64 encoded Merkle Tree nodes. 1064 tree_size: The size of the tree, in entries, in decimal. 1066 timestamp: The timestamp, in decimal. 1068 root_hash: The base64 encoded Merkle Tree Hash of the tree. 1070 tree_head_signature: A base64 encoded TreeHeadSignature for 1071 "tree_size", "timestamp" and "root_hash". 1073 Note that no signature is required for the "consistency" output as 1074 it is used to verify an STH, which is signed. 1076 Error codes: 1078 first unknown "first" is before the latest known STH but is not 1079 from an existing STH. 1081 second unknown "second" is before the latest known STH but is not 1082 from an existing STH. 1084 See Section 5.5.2 for an outline of how to use the "consistency" 1085 array. 1087 4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash 1089 GET https:///ct/v2/get-proof-by-hash 1091 Inputs: 1093 hash: A base64 encoded v1 leaf hash. 1095 tree_size: The tree_size of the tree on which to base the proof, 1096 in decimal. 1098 The "hash" must be calculated as defined in Section 3.5. The 1099 "tree_size" must designate an existing v1 STH. Because of skew, 1100 the front-end may not know the requested STH. In that case, it 1101 will return the latest STH it knows, along with an inclusion proof 1102 to that STH. If the front-end knows the requested STH then only 1103 "leaf_index" and "audit_path" are returned. 1105 Outputs: 1107 leaf_index: The 0-based index of the entry corresponding to the 1108 "hash" parameter. 1110 audit_path: An array of base64 encoded Merkle Tree nodes proving 1111 the inclusion of the chosen certificate. 1113 tree_size: The size of the tree, in entries, in decimal. 1115 timestamp: The timestamp, in decimal. 1117 root_hash: The base64 encoded Merkle Tree Hash of the tree. 1119 tree_head_signature: A base64 encoded TreeHeadSignature for 1120 "tree_size", "timestamp" and "root_hash". 1122 Note that no signature is required for the "leaf_index" or 1123 "audit_path" output as this is used to verify inclusion in an STH, 1124 which is signed. 1126 Error codes: 1128 hash unknown "hash" is not the hash of a known leaf (may be 1129 caused by skew or by a known certificate not yet merged). 1131 tree_size unknown "hash" is before the latest known STH but is 1132 not from an existing STH. 1134 See Section 5.5.1 for an outline of how to use the "audit_path" 1135 array. 1137 4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and Consistency 1138 Proof by Leaf Hash 1140 GET https:///ct/v2/get-all-by-hash 1142 Inputs: 1144 hash: A base64 encoded v1 leaf hash. 1146 tree_size: The tree_size of the tree on which to base the proofs, 1147 in decimal. 1149 The "hash" must be calculated as defined in Section 3.5. The 1150 "tree_size" must designate an existing v1 STH. 1152 Because of skew, the front-end may not know the requested STH or 1153 the requested hash, which leads to a number of cases. 1155 latest STH < requested STH Return latest STH. 1157 latest STH > requested STH Return latest STH and a consistency 1158 proof between it and the requested STH (see Section 4.4). 1160 index of requested hash < latest STH Return "leaf_index" and 1161 "audit_path". 1163 Note that more than one case can be true, in which case the 1164 returned data is their concatenation. It is also possible for 1165 none to be true, in which case the front-end MUST return an empty 1166 response. 1168 Outputs: 1170 leaf_index: The 0-based index of the entry corresponding to the 1171 "hash" parameter. 1173 audit_path: An array of base64 encoded Merkle Tree nodes proving 1174 the inclusion of the chosen certificate. 1176 tree_size: The size of the tree, in entries, in decimal. 1178 timestamp: The timestamp, in decimal. 1180 root_hash: The base64 encoded Merkle Tree Hash of the tree. 1182 tree_head_signature: A base64 encoded TreeHeadSignature for 1183 "tree_size", "timestamp" and "root_hash". 1185 consistency: An array of base64 encoded Merkle Tree nodes proving 1186 the consistency of the requested STH and the returned STH. 1188 Note that no signature is required for the "leaf_index", 1189 "audit_path" or "consistency" output as this is used to verify 1190 inclusion in and consistency of an STH, which is signed. 1192 Errors are the same as in Section 4.5. 1194 See Section 5.5.1 for an outline of how to use the "audit_path" array 1195 and see Section 5.5.2 for an outline of how to use the "consistency" 1196 array. 1198 4.7. Retrieve Entries and STH from Log 1200 GET https:///ct/v2/get-entries 1202 Inputs: 1204 start: 0-based index of first entry to retrieve, in decimal. 1206 end: 0-based index of last entry to retrieve, in decimal. 1208 Outputs: 1210 entries: An array of objects, each consisting of 1212 leaf_input: The base64 encoded MerkleTreeLeaf structure. 1214 extra_data: The base64 encoded unsigned data pertaining to the 1215 log entry. In the case of an X509ChainEntry, this is the 1216 whole "X509ChainEntry". In the case of a 1217 PrecertChainEntryV2, this is the whole 1218 "PrecertChainEntryV2". 1220 sct: A base64 encoded "SignedCertificateTimestamp" for this 1221 entry. Note that more than one SCT may have been returned 1222 for the same entry - only one of those is returned in this 1223 field. It may not be possible to retrieve others. 1225 tree_size: The size of the tree, in entries, in decimal. 1227 timestamp: The timestamp, in decimal. 1229 root_hash: The base64 encoded Merkle Tree Hash of the tree. 1231 tree_head_signature: A base64 encoded TreeHeadSignature for 1232 "tree_size", "timestamp" and "root_hash". 1234 Note that this message is not signed -- the "entries" data can be 1235 verified by constructing the Merkle Tree Hash corresponding to a 1236 retrieved STH. All leaves MUST be v1 or v2. However, a compliant v1 1237 client MUST NOT construe an unrecognized LogEntryType value as an 1238 error. This means it may be unable to parse some entries, but note 1239 that each client can inspect the entries it does recognize as well as 1240 verify the integrity of the data by treating unrecognized leaves as 1241 opaque input to the tree. 1243 The "start" and "end" parameters SHOULD be within the range 0 <= x < 1244 "tree_size" as returned by "get-sth" in Section 4.3. 1246 The "start" parameter MUST be less than or equal to the "end" 1247 parameter. 1249 Log servers MUST honor requests where 0 <= "start" < "tree_size" and 1250 "end" >= "tree_size" by returning a partial response covering only 1251 the valid entries in the specified range. "end" >= "tree_size" could 1252 be caused by skew. Note that the following restriction may also 1253 apply: 1255 Logs MAY restrict the number of entries that can be retrieved per 1256 "get-entries" request. If a client requests more than the permitted 1257 number of entries, the log SHALL return the maximum number of entries 1258 permissible. These entries SHALL be sequential beginning with the 1259 entry specified by "start". 1261 Because of skew, it is possible the log server will not have any 1262 entries between "start" and "end". In this case it MUST return an 1263 empty "entries" array. 1265 In any case, the log server MUST return the latest STH it knows 1266 about. 1268 See Section 5.5.3 for an outline of how to use a complete list of 1269 "leaf_input" entries to verify the "root_hash". 1271 4.8. Retrieve Accepted Root Certificates 1273 GET https:///ct/v1/get-roots 1275 No inputs. 1277 Outputs: 1279 certificates: An array of base64 encoded root certificates that 1280 are acceptable to the log. 1282 max_chain: If the server has chosen to limit the length of chains 1283 it accepts, this is the maximum number of certificates in the 1284 chain, in decimal. If there is no limit, this is omitted. 1286 5. Clients 1288 There are various different functions clients of logs might perform. 1289 We describe here some typical clients and how they could function. 1290 Any inconsistency may be used as evidence that a log has not behaved 1291 correctly, and the signatures on the data structures prevent the log 1292 from denying that misbehavior. 1294 All clients need various metadata in order to communicate with logs 1295 and verify their responses. This metadata is described below, but 1296 note that this document does not describe how the metadata is 1297 obtained, which is implementation dependent (see, for example, 1298 [Chromium.Policy]). 1300 Clients should somehow exchange STHs they see, or make them available 1301 for scrutiny, in order to ensure that they all have a consistent 1302 view. The exact mechanisms will be in separate documents, but it is 1303 expected there will be a variety. 1305 5.1. Metadata 1307 In order to communicate with and verify a log, clients need metadata 1308 about the log. 1310 Base URL: The URL to substitute for in Section 4. 1312 Hash Algorithm The hash algorithm used for the Merkle Tree (see 1313 Section 7.2). 1315 Signing Algorithm The signing algorithm used (see Section 2.1.4). 1317 Public Key The public key used for signing. 1319 Maximum Merge Delay The MMD the log has committed to. 1321 Version The version of the protocol supported by the log (currently 1322 1 or 2). 1324 STH Frequency Count The maximum number of STHs the log may produce 1325 in any period equal to the "Maximum Merge Delay" (see 1326 Section 3.6). 1328 Final STH If a log has been closed down (i.e. no longer accepts new 1329 entries), existing entries may still be valid. In this case, the 1330 client should know the final valid STH in the log to ensure no new 1331 entries can be added without detection. 1333 [JSON.Metadata] is an example of a metadata format which includes the 1334 above elements. 1336 5.2. Submitters 1338 Submitters submit certificates or precertificates to the log as 1339 described above. When a Submitter intends to use the returned SCT 1340 directly in a TLS handshake or to construct a certificate, they 1341 SHOULD validate the SCT as described in Section 5.3 if they 1342 understand its format. 1344 5.3. TLS Client 1346 TLS clients receive SCTs alongside or in certificates, either for the 1347 server certificate itself or for intermediate CA precertificates. In 1348 addition to normal validation of the certificate and its chain, TLS 1349 clients SHOULD validate the SCT by computing the signature input from 1350 the SCT data as well as the certificate and verifying the signature, 1351 using the corresponding log's public key. 1353 A TLS client MAY audit the corresponding log by requesting, and 1354 verifying, a Merkle audit proof for said certificate. If the TLS 1355 client holds an STH that predates the SCT, it MAY, in the process of 1356 auditing, request a new STH from the log (Section 4.3), then verify 1357 it by requesting a consistency proof (Section 4.4). 1359 TLS clients MUST reject SCTs whose timestamp is in the future. 1361 5.4. Monitor 1363 Monitors watch logs and check that they behave correctly. Monitors 1364 may additionally watch for certificates of interest. For example, a 1365 monitor may be configured to report on all certificates that apply to 1366 a specific domain name when fetching new entries for consistency 1367 validation. 1369 A monitor needs to, at least, inspect every new entry in each log it 1370 watches. It may also want to keep copies of entire logs. In order 1371 to do this, it should follow these steps for each log: 1373 1. Fetch the current STH (Section 4.3). 1375 2. Verify the STH signature. 1377 3. Fetch all the entries in the tree corresponding to the STH 1378 (Section 4.7). 1380 4. Confirm that the tree made from the fetched entries produces the 1381 same hash as that in the STH. 1383 5. Fetch the current STH (Section 4.3). Repeat until the STH 1384 changes. 1386 6. Verify the STH signature. 1388 7. Fetch all the new entries in the tree corresponding to the STH 1389 (Section 4.7). If they remain unavailable for an extended 1390 period, then this should be viewed as misbehavior on the part of 1391 the log. 1393 8. Either: 1395 1. Verify that the updated list of all entries generates a tree 1396 with the same hash as the new STH. 1398 Or, if it is not keeping all log entries: 1400 1. Fetch a consistency proof for the new STH with the previous 1401 STH (Section 4.4). 1403 2. Verify the consistency proof. 1405 3. Verify that the new entries generate the corresponding 1406 elements in the consistency proof. 1408 9. Go to Step 5. 1410 5.5. Auditing 1412 Auditing is taking partial information about a log as input and 1413 verifying that this information is consistent with other partial 1414 information held. All clients described above may perform auditing 1415 as an additional function. The action taken by the client if audit 1416 fails is not specified, but note that in general if audit fails, the 1417 client is in possession of signed proof of the log's misbehavior. 1419 A monitor (Section 5.4) can audit by verifying the consistency of 1420 STHs it receives, ensure that each entry can be fetched and that the 1421 STH is indeed the result of making a tree from all fetched entries. 1423 A TLS client (Section 5.3) can audit by verifying an SCT against any 1424 STH dated after the SCT timestamp + the Maximum Merge Delay by 1425 requesting a Merkle inclusion proof (Section 4.5). It can also 1426 verify that the SCT corresponds to the certificate it arrived with 1427 (i.e. the log entry is that certificate, is a precertificate for that 1428 certificate or is an appropriate name-constrained intermediate [see 1429 Section 3.2.3]). 1431 The following algorithm outlines may be useful for clients that wish 1432 to perform various audit operations. 1434 5.5.1. Verifying an inclusion proof 1436 When a client has received an "audit_path" and "leaf_index" and 1437 wishes to verify inclusion of an input "hash" for an STH with a given 1438 "tree_size" and "root_hash", the following algorithm may be used to 1439 prove the "hash" was included in the "root_hash": 1441 1. Set "fn" to "leaf_index" and "sn" to "tree_size - 1". 1443 2. Set "r" to "hash". 1445 3. For each value "p" in the "audit_path" array: 1447 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1449 1. Set "r" to "HASH(0x01 || p || r)" 1451 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1452 equally until either "LSB(fn)" is set or "fn" is "0". 1454 Otherwise: 1456 Set "r" to "HASH(0x01 || r || p)" 1458 Finally, right-shift both "fn" and "sn" one time. 1460 4. Compare "r" against the "root_hash". If they are equal, then the 1461 log has proven the inclusion of "hash". 1463 5.5.2. Verifying consistency between two STHs 1465 When a client has an STH "first_hash" for tree size "first", an STH 1466 "second_hash" for tree size "second" where "0 < first < second", and 1467 has received a "consistency" array that they wish to use to verify 1468 both hashes, the following algorithm may be used: 1470 1. If "first" is an exact power of 2, then prepend "first_hash" to 1471 the "consistency" array. 1473 2. Set "fn" to "first - 1" and "sn" to "second - 1". 1475 3. If "LSB(fn)" is set, then right-shift both "fn" and "sn" equally 1476 until "LSB(fn)" is not set. 1478 4. Set both "fr" and "sr" to the first value in the "consistency" 1479 array. 1481 5. For each subsequent value "c" in the "consistency" array: 1483 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1485 1. Set "fr" to "HASH(0x01 || c || fr)" 1486 Set "sr" to "HASH(0x01 || c || sr)" 1488 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1489 equally until either "LSB(fn)" is set or "fn" is "0". 1491 Otherwise: 1493 Set "sr" to "HASH(0x01 || sr || c)" 1495 Finally, right-shift both "fn" and "sn" one time. 1497 6. After completing iterating through the "consistency" array as 1498 described above, verify that the "fr" calculated is equal to the 1499 "first_hash" supplied and that the "sr" calculated is equal to 1500 the "second_hash" supplied. 1502 5.5.3. Verifying root hash given entries 1504 When a client has a complete list of leaf input "entries" from "0" up 1505 to "tree_size - 1" and wishes to verify this list against an STH 1506 "root_hash" returned by the log for the same "tree_size", the 1507 following algorithm may be used: 1509 1. Set "stack" to an empty stack. 1511 2. For each "i" from "0" up to "tree_size - 1": 1513 1. Push "HASH(0x00 || entries[i])" to "stack". 1515 2. Set "merge_count" to the lowest value ("0" included) such 1516 that "LSB(i >> merge_count)" is not set. In other words, set 1517 "merge_count" to the number of consecutive "1"s found 1518 starting at the least significant bit of "i". 1520 3. Repeat "merge_count" times: 1522 1. Pop "right" from "stack". 1524 2. Pop "left" from "stack". 1526 3. Push "HASH(0x01 || left || right)" to "stack". 1528 3. If there is more than one element in the "stack", repeat the same 1529 merge procedure (Step 2.3 above) until only a single element 1530 remains. 1532 4. The remaining element in "stack" is the Merkle Tree hash for the 1533 given "tree_size" and should be compared by equality against the 1534 supplied "root_hash". 1536 6. Algorithm Agility 1538 It is not possible for a log to change any of its algorithms part way 1539 through its lifetime. If it should become necessary to deprecate an 1540 algorithm used by a live log, then the log should be frozen as 1541 specified in Section 5.1 and a new log should be started. If 1542 necessary, the new log can contain existing entries from the frozen 1543 log, which monitors can verify are an exact match. 1545 7. IANA Considerations 1547 7.1. TLS Extension Type 1549 IANA has allocated an RFC 5246 ExtensionType value (18) for the SCT 1550 TLS extension. The extension name is "signed_certificate_timestamp". 1551 IANA should update this extension type to point at this document. 1553 7.2. Hash Algorithms 1555 IANA is asked to establish a registry of hash values, initially 1556 consisting of: 1558 +-------+----------------------+ 1559 | Index | Hash | 1560 +-------+----------------------+ 1561 | 0 | SHA-256 [FIPS.180-4] | 1562 +-------+----------------------+ 1564 8. Security Considerations 1566 With CAs, logs, and servers performing the actions described here, 1567 TLS clients can use logs and signed timestamps to reduce the 1568 likelihood that they will accept misissued certificates. If a server 1569 presents a valid signed timestamp for a certificate, then the client 1570 knows that a log has committed to publishing the certificate. From 1571 this, the client knows that the subject of the certificate has had 1572 some time to notice the misissue and take some action, such as asking 1573 a CA to revoke a misissued certificate, or that the log has 1574 misbehaved, which will be discovered when the SCT is audited. A 1575 signed timestamp is not a guarantee that the certificate is not 1576 misissued, since the subject of the certificate might not have 1577 checked the logs or the CA might have refused to revoke the 1578 certificate. 1580 In addition, if TLS clients will not accept unlogged certificates, 1581 then site owners will have a greater incentive to submit certificates 1582 to logs, possibly with the assistance of their CA, increasing the 1583 overall transparency of the system. 1585 8.1. Misissued Certificates 1587 Misissued certificates that have not been publicly logged, and thus 1588 do not have a valid SCT, will be rejected by TLS clients. Misissued 1589 certificates that do have an SCT from a log will appear in that 1590 public log within the Maximum Merge Delay, assuming the log is 1591 operating correctly. Thus, the maximum period of time during which a 1592 misissued certificate can be used without being available for audit 1593 is the MMD. 1595 8.2. Detection of Misissue 1597 The logs do not themselves detect misissued certificates; they rely 1598 instead on interested parties, such as domain owners, to monitor them 1599 and take corrective action when a misissue is detected. 1601 8.3. Redaction of Public Domain Name Labels 1603 CAs SHOULD NOT redact domain name labels in precertificates such that 1604 the entirety of the domain space below the unredacted part of the 1605 domain name is not owned or controlled by a single entity (e.g. 1606 "?.com" and "?.co.uk" would both be problematic). Logs MUST NOT 1607 reject any precertificate that is overly redacted but which is 1608 otherwise considered compliant. It is expected that monitors will 1609 treat overly redacted precertificates as potentially misissued. TLS 1610 clients MAY reject a certificate whose corresponding precertificate 1611 would be overly redacted, perhaps using the same mechanism for 1612 determining whether a wildcard in a domain name of a certificate is 1613 too broad. 1615 8.4. Misbehaving Logs 1617 A log can misbehave in two ways: (1) by failing to incorporate a 1618 certificate with an SCT in the Merkle Tree within the MMD and (2) by 1619 violating its append-only property by presenting two different, 1620 conflicting views of the Merkle Tree at different times and/or to 1621 different parties. Both forms of violation will be promptly and 1622 publicly detectable. 1624 Violation of the MMD contract is detected by log clients requesting a 1625 Merkle audit proof for each observed SCT. These checks can be 1626 asynchronous and need only be done once per each certificate. In 1627 order to protect the clients' privacy, these checks need not reveal 1628 the exact certificate to the log. Clients can instead request the 1629 proof from a trusted auditor (since anyone can compute the audit 1630 proofs from the log) or request Merkle proofs for a batch of 1631 certificates around the SCT timestamp. 1633 Violation of the append-only property can be detected by clients 1634 comparing their instances of the Signed Tree Heads. As soon as two 1635 conflicting Signed Tree Heads for the same log are detected, this is 1636 cryptographic proof of that log's misbehavior. There are various 1637 ways this could be done, for example via gossip (see http:// 1638 trac.tools.ietf.org/id/draft-linus-trans-gossip-00.txt) or peer-to- 1639 peer communications or by sending STHs to monitors (who could then 1640 directly check against their own copy of the relevant log). 1642 8.5. Multiple SCTs 1644 TLS servers may wish to offer multiple SCTs, each from a different 1645 log. 1647 o If a CA and a log collude, it is possible to temporarily hide 1648 misissuance from clients. Including SCTs from different logs 1649 makes it more difficult to mount this attack. 1651 o If a log misbehaves, a consequence may be that clients cease to 1652 trust it. Since the time an SCT may be in use can be considerable 1653 (several years is common in current practice when the SCT is 1654 embedded in a certificate), servers may wish to reduce the 1655 probability of their certificates being rejected as a result by 1656 including SCTs from different logs. 1658 o TLS clients may have policies related to the above risks requiring 1659 servers to present multiple SCTs. For example Chromium 1660 [Chromium.Log.Policy] currently requires multiple SCTs to be 1661 presented with EV certificates in order for the EV indicator to be 1662 shown. 1664 9. Efficiency Considerations 1666 The Merkle Tree design serves the purpose of keeping communication 1667 overhead low. 1669 Auditing logs for integrity does not require third parties to 1670 maintain a copy of each entire log. The Signed Tree Heads can be 1671 updated as new entries become available, without recomputing entire 1672 trees. Third-party auditors need only fetch the Merkle consistency 1673 proofs against a log's existing STH to efficiently verify the append- 1674 only property of updates to their Merkle Trees, without auditing the 1675 entire tree. 1677 10. Acknowledgements 1679 The authors would like to thank Erwann Abelea, Robin Alden, Al 1680 Cutter, Francis Dupont, Stephen Farrell, Brad Hill, Jeff Hodges, Paul 1681 Hoffman, Jeffrey Hutzelman, SM, Alexey Melnikov, Chris Palmer, Trevor 1682 Perrin, Ryan Sleevi and Carl Wallace for their valuable 1683 contributions. 1685 11. References 1687 11.1. Normative References 1689 [DSS] National Institute of Standards and Technology, "Digital 1690 Signature Standard (DSS)", FIPS 186-3, June 2009, 1691 . 1694 [FIPS.180-4] 1695 National Institute of Standards and Technology, "Secure 1696 Hash Standard", FIPS PUB 180-4, March 2012, 1697 . 1700 [HTML401] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 1701 Specification", World Wide Web Consortium Recommendation 1702 REC-html401-19991224, December 1999, 1703 . 1705 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1706 Requirement Levels", BCP 14, RFC 2119, March 1997. 1708 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1709 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1710 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1712 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1713 Standards (PKCS) #1: RSA Cryptography Specifications 1714 Version 2.1", RFC 3447, February 2003. 1716 [RFC4627] Crockford, D., "The application/json Media Type for 1717 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1719 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1720 Encodings", RFC 4648, October 2006. 1722 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1723 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1725 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1726 Housley, R., and W. Polk, "Internet X.509 Public Key 1727 Infrastructure Certificate and Certificate Revocation List 1728 (CRL) Profile", RFC 5280, May 2008. 1730 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1731 RFC 5652, September 2009. 1733 [RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 1734 Time Protocol Version 4: Protocol and Algorithms 1735 Specification", RFC 5905, June 2010. 1737 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 1738 Extension Definitions", RFC 6066, January 2011. 1740 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1741 Verification of Domain-Based Application Service Identity 1742 within Internet Public Key Infrastructure Using X.509 1743 (PKIX) Certificates in the Context of Transport Layer 1744 Security (TLS)", RFC 6125, March 2011. 1746 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 1747 Galperin, S., and C. Adams, "X.509 Internet Public Key 1748 Infrastructure Online Certificate Status Protocol - OCSP", 1749 RFC 6960, June 2013. 1751 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 1752 Algorithm (DSA) and Elliptic Curve Digital Signature 1753 Algorithm (ECDSA)", RFC 6979, August 2013. 1755 11.2. Informative References 1757 [Chromium.Log.Policy] 1758 The Chromium Projects, "Chromium Certificate Transparency 1759 Log Policy", 2014, . 1762 [Chromium.Policy] 1763 The Chromium Projects, "Chromium Certificate 1764 Transparency", 2014, . 1767 [CrosbyWallach] 1768 Crosby, S. and D. Wallach, "Efficient Data Structures for 1769 Tamper-Evident Logging", Proceedings of the 18th USENIX 1770 Security Symposium, Montreal, August 2009, 1771 . 1774 [EVSSLGuidelines] 1775 CA/Browser Forum, "Guidelines For The Issuance And 1776 Management Of Extended Validation Certificates", 2007, 1777 . 1780 [JSON.Metadata] 1781 The Chromium Projects, "Chromium Log Metadata JSON 1782 Schema", 2014, . 1785 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 1786 Transparency", RFC 6962, June 2013. 1788 Authors' Addresses 1790 Ben Laurie 1791 Google UK Ltd. 1793 EMail: benl@google.com 1795 Adam Langley 1796 Google Inc. 1798 EMail: agl@google.com 1799 Emilia Kasper 1800 Google Switzerland GmbH 1802 EMail: ekasper@google.com 1804 Eran Messeri 1805 Google UK Ltd. 1807 EMail: eranm@google.com 1809 Rob Stradling 1810 Comodo CA, Ltd. 1812 EMail: rob.stradling@comodo.com