idnits 2.17.1 draft-ietf-trans-rfc6962-bis-07.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 (March 9, 2015) is 3336 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 611 -- Looks like a reference, but probably isn't: '7' on line 616 -- Looks like a reference, but probably isn't: '0' on line 606 -- Looks like a reference, but probably isn't: '2' on line 608 -- Looks like a reference, but probably isn't: '32' on line 848 -- 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) -- Obsolete informational reference (is this intentional?): RFC 6962 (Obsoleted by RFC 9162) Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 9 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: September 10, 2015 E. Messeri 6 Google 7 R. Stradling 8 Comodo 9 March 9, 2015 11 Certificate Transparency 12 draft-ietf-trans-rfc6962-bis-07 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 September 10, 2015. 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 . . . . . . . . . . . . . . . . . . 4 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 . . . . . . . . . . . . . . . . . . 9 72 3.1. Log Entries . . . . . . . . . . . . . . . . . . . . . . . 9 73 3.2. Private Domain Name Labels . . . . . . . . . . . . . . . 12 74 3.2.1. Wildcard Certificates . . . . . . . . . . . . . . . . 12 75 3.2.2. Redacting Domain Name Labels in Precertificates . . . 12 76 3.2.3. Using a Name-Constrained Intermediate CA . . . . . . 13 77 3.3. Structure of the Signed Certificate Timestamp . . . . . . 14 78 3.4. Including the Signed Certificate Timestamp in the TLS 79 Handshake . . . . . . . . . . . . . . . . . . . . . . . . 15 80 3.4.1. TLS Extension . . . . . . . . . . . . . . . . . . . . 16 81 3.4.2. X.509v3 Extension . . . . . . . . . . . . . . . . . . 17 82 3.5. Merkle Tree . . . . . . . . . . . . . . . . . . . . . . . 17 83 3.6. Signed Tree Head . . . . . . . . . . . . . . . . . . . . 18 84 4. Log Client Messages . . . . . . . . . . . . . . . . . . . . . 19 85 4.1. Add Chain to Log . . . . . . . . . . . . . . . . . . . . 21 86 4.2. Add PreCertChain to Log . . . . . . . . . . . . . . . . . 22 87 4.3. Retrieve Latest Signed Tree Head . . . . . . . . . . . . 22 88 4.4. Retrieve Merkle Consistency Proof between Two Signed Tree 89 Heads . . . . . . . . . . . . . . . . . . . . . . . . . . 23 90 4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash . . 23 91 4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and 92 Consistency Proof by Leaf Hash . . . . . . . . . . . . . 24 94 4.7. Retrieve Entries from Log . . . . . . . . . . . . . . . . 25 95 4.8. Retrieve Accepted Root Certificates . . . . . . . . . . . 26 96 5. Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 97 5.1. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 27 98 5.2. Submitters . . . . . . . . . . . . . . . . . . . . . . . 28 99 5.3. TLS Client . . . . . . . . . . . . . . . . . . . . . . . 28 100 5.4. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 28 101 5.5. Auditing . . . . . . . . . . . . . . . . . . . . . . . . 29 102 6. Algorithm Agility . . . . . . . . . . . . . . . . . . . . . . 30 103 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30 104 7.1. TLS Extension Type . . . . . . . . . . . . . . . . . . . 30 105 7.2. Hash Algorithms . . . . . . . . . . . . . . . . . . . . . 30 106 8. Security Considerations . . . . . . . . . . . . . . . . . . . 30 107 8.1. Misissued Certificates . . . . . . . . . . . . . . . . . 31 108 8.2. Detection of Misissue . . . . . . . . . . . . . . . . . . 31 109 8.3. Redaction of Public Domain Name Labels . . . . . . . . . 31 110 8.4. Misbehaving Logs . . . . . . . . . . . . . . . . . . . . 31 111 8.5. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . . 32 112 9. Efficiency Considerations . . . . . . . . . . . . . . . . . . 32 113 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 33 114 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 115 11.1. Normative References . . . . . . . . . . . . . . . . . . 33 116 11.2. Informative References . . . . . . . . . . . . . . . . . 34 118 1. Introduction 120 Certificate transparency aims to mitigate the problem of misissued 121 certificates by providing publicly auditable, append-only, untrusted 122 logs of all issued certificates. The logs are publicly auditable so 123 that it is possible for anyone to verify the correctness of each log 124 and to monitor when new certificates are added to it. The logs do 125 not themselves prevent misissue, but they ensure that interested 126 parties (particularly those named in certificates) can detect such 127 misissuance. Note that this is a general mechanism, but in this 128 document, we only describe its use for public TLS server certificates 129 issued by public certification authorities (CAs). 131 Each log consists of certificate chains, which can be submitted by 132 anyone. It is expected that public CAs will contribute all their 133 newly issued certificates to one or more logs, however certificate 134 holders can also contribute their own certificate chains, as can 135 third parties. In order to avoid logs being rendered useless by 136 submitting large numbers of spurious certificates, it is required 137 that each chain is rooted in a CA certificate accepted by the log. 138 When a chain is submitted to a log, a signed timestamp is returned, 139 which can later be used to provide evidence to TLS clients that the 140 chain has been submitted. TLS clients can thus require that all 141 certificates they accept as valid have been logged. 143 Those who are concerned about misissue can monitor the logs, asking 144 them regularly for all new entries, and can thus check whether 145 domains they are responsible for have had certificates issued that 146 they did not expect. What they do with this information, 147 particularly when they find that a misissuance has happened, is 148 beyond the scope of this document, but broadly speaking, they can 149 invoke existing business mechanisms for dealing with misissued 150 certificates, such as working with the CA to get the certificate 151 revoked, or with maintainers of trust anchor lists to get the CA 152 removed. Of course, anyone who wants can monitor the logs and, if 153 they believe a certificate is incorrectly issued, take action as they 154 see fit. 156 Similarly, those who have seen signed timestamps from a particular 157 log can later demand a proof of inclusion from that log. If the log 158 is unable to provide this (or, indeed, if the corresponding 159 certificate is absent from monitors' copies of that log), that is 160 evidence of the incorrect operation of the log. The checking 161 operation is asynchronous to allow TLS connections to proceed without 162 delay, despite network connectivity issues and the vagaries of 163 firewalls. 165 The append-only property of each log is technically achieved using 166 Merkle Trees, which can be used to show that any particular instance 167 of the log is a superset of any particular previous instance. 168 Likewise, Merkle Trees avoid the need to blindly trust logs: if a log 169 attempts to show different things to different people, this can be 170 efficiently detected by comparing tree roots and consistency proofs. 171 Similarly, other misbehaviors of any log (e.g., issuing signed 172 timestamps for certificates they then don't log) can be efficiently 173 detected and proved to the world at large. 175 1.1. Requirements Language 177 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 178 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 179 document are to be interpreted as described in RFC 2119 [RFC2119]. 181 1.2. Data Structures 183 Data structures are defined according to the conventions laid out in 184 Section 4 of [RFC5246]. 186 2. Cryptographic Components 187 2.1. Merkle Hash Trees 189 Logs use a binary Merkle Hash Tree for efficient auditing. The 190 hashing algorithm used by each log is expected to be specified as 191 part of the metadata relating to that log. We have established a 192 registry of acceptable algorithms, see Section 7.2. The hashing 193 algorithm in use is referred to as HASH throughout this document. 194 The input to the Merkle Tree Hash is a list of data entries; these 195 entries will be hashed to form the leaves of the Merkle Hash Tree. 196 The output is a single 32-byte Merkle Tree Hash. Given an ordered 197 list of n inputs, D[n] = {d(0), d(1), ..., d(n-1)}, the Merkle Tree 198 Hash (MTH) is thus defined as follows: 200 The hash of an empty list is the hash of an empty string: 202 MTH({}) = HASH(). 204 The hash of a list with one entry (also known as a leaf hash) is: 206 MTH({d(0)}) = HASH(0x00 || d(0)). 208 For n > 1, let k be the largest power of two smaller than n (i.e., k 209 < n <= 2k). The Merkle Tree Hash of an n-element list D[n] is then 210 defined recursively as 212 MTH(D[n]) = HASH(0x01 || MTH(D[0:k]) || MTH(D[k:n])), 214 where || is concatenation and D[k1:k2] denotes the list {d(k1), 215 d(k1+1),..., d(k2-1)} of length (k2 - k1). (Note that the hash 216 calculations for leaves and nodes differ. This domain separation is 217 required to give second preimage resistance.) 219 Note that we do not require the length of the input list to be a 220 power of two. The resulting Merkle Tree may thus not be balanced; 221 however, its shape is uniquely determined by the number of leaves. 222 (Note: This Merkle Tree is essentially the same as the history tree 223 [CrosbyWallach] proposal, except our definition handles non-full 224 trees differently.) 226 2.1.1. Merkle Inclusion Proofs 228 A Merkle inclusion proof for a leaf in a Merkle Hash Tree is the 229 shortest list of additional nodes in the Merkle Tree required to 230 compute the Merkle Tree Hash for that tree. Each node in the tree is 231 either a leaf node or is computed from the two nodes immediately 232 below it (i.e., towards the leaves). At each step up the tree 233 (towards the root), a node from the inclusion proof is combined with 234 the node computed so far. In other words, the inclusion proof 235 consists of the list of missing nodes required to compute the nodes 236 leading from a leaf to the root of the tree. If the root computed 237 from the inclusion proof matches the true root, then the inclusion 238 proof proves that the leaf exists in the tree. 240 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 241 d(n-1)}, the Merkle inclusion proof PATH(m, D[n]) for the (m+1)th 242 input d(m), 0 <= m < n, is defined as follows: 244 The proof for the single leaf in a tree with a one-element input list 245 D[1] = {d(0)} is empty: 247 PATH(0, {d(0)}) = {} 249 For n > 1, let k be the largest power of two smaller than n. The 250 proof for the (m+1)th element d(m) in a list of n > m elements is 251 then defined recursively as 253 PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n]) for m < k; and 255 PATH(m, D[n]) = PATH(m - k, D[k:n]) : MTH(D[0:k]) for m >= k, 257 where : is concatenation of lists and D[k1:k2] denotes the length (k2 258 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 260 2.1.2. Merkle Consistency Proofs 262 Merkle consistency proofs prove the append-only property of the tree. 263 A Merkle consistency proof for a Merkle Tree Hash MTH(D[n]) and a 264 previously advertised hash MTH(D[0:m]) of the first m leaves, m <= n, 265 is the list of nodes in the Merkle Tree required to verify that the 266 first m inputs D[0:m] are equal in both trees. Thus, a consistency 267 proof must contain a set of intermediate nodes (i.e., commitments to 268 inputs) sufficient to verify MTH(D[n]), such that (a subset of) the 269 same nodes can be used to verify MTH(D[0:m]). We define an algorithm 270 that outputs the (unique) minimal consistency proof. 272 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 273 d(n-1)}, the Merkle consistency proof PROOF(m, D[n]) for a previous 274 Merkle Tree Hash MTH(D[0:m]), 0 < m < n, is defined as: 276 PROOF(m, D[n]) = SUBPROOF(m, D[n], true) 278 The subproof for m = n is empty if m is the value for which PROOF was 279 originally requested (meaning that the subtree Merkle Tree Hash 280 MTH(D[0:m]) is known): 282 SUBPROOF(m, D[m], true) = {} 283 The subproof for m = n is the Merkle Tree Hash committing inputs 284 D[0:m]; otherwise: 286 SUBPROOF(m, D[m], false) = {MTH(D[m])} 288 For m < n, let k be the largest power of two smaller than n. The 289 subproof is then defined recursively. 291 If m <= k, the right subtree entries D[k:n] only exist in the current 292 tree. We prove that the left subtree entries D[0:k] are consistent 293 and add a commitment to D[k:n]: 295 SUBPROOF(m, D[n], b) = SUBPROOF(m, D[0:k], b) : MTH(D[k:n]) 297 If m > k, the left subtree entries D[0:k] are identical in both 298 trees. We prove that the right subtree entries D[k:n] are consistent 299 and add a commitment to D[0:k]. 301 SUBPROOF(m, D[n], b) = SUBPROOF(m - k, D[k:n], false) : MTH(D[0:k]) 303 Here, : is a concatenation of lists, and D[k1:k2] denotes the length 304 (k2 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 306 The number of nodes in the resulting proof is bounded above by 307 ceil(log2(n)) + 1. 309 2.1.3. Example 311 The binary Merkle Tree with 7 leaves: 313 hash 314 / \ 315 / \ 316 / \ 317 / \ 318 / \ 319 k l 320 / \ / \ 321 / \ / \ 322 / \ / \ 323 g h i j 324 / \ / \ / \ | 325 a b c d e f d6 326 | | | | | | 327 d0 d1 d2 d3 d4 d5 329 The inclusion proof for d0 is [b, h, l]. 331 The inclusion proof for d3 is [c, g, l]. 333 The inclusion proof for d4 is [f, j, k]. 335 The inclusion proof for d6 is [i, k]. 337 The same tree, built incrementally in four steps: 339 hash0 hash1=k 340 / \ / \ 341 / \ / \ 342 / \ / \ 343 g c g h 344 / \ | / \ / \ 345 a b d2 a b c d 346 | | | | | | 347 d0 d1 d0 d1 d2 d3 349 hash2 hash 350 / \ / \ 351 / \ / \ 352 / \ / \ 353 / \ / \ 354 / \ / \ 355 k i k l 356 / \ / \ / \ / \ 357 / \ e f / \ / \ 358 / \ | | / \ / \ 359 g h d4 d5 g h i j 360 / \ / \ / \ / \ / \ | 361 a b c d a b c d e f d6 362 | | | | | | | | | | 363 d0 d1 d2 d3 d0 d1 d2 d3 d4 d5 365 The consistency proof between hash0 and hash is PROOF(3, D[7]) = [c, 366 d, g, l]. c, g are used to verify hash0, and d, l are additionally 367 used to show hash is consistent with hash0. 369 The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l]. 370 hash can be verified using hash1=k and l. 372 The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i, 373 j, k]. k, i are used to verify hash2, and j is additionally used to 374 show hash is consistent with hash2. 376 2.1.4. Signatures 378 Various data structures are signed. A log MUST use either elliptic 379 curve signatures using the NIST P-256 curve (Section D.1.2.3 of the 380 Digital Signature Standard [DSS]) or RSA signatures (RSASSA- 381 PKCS1-v1_5 with SHA-256, Section 8.2 of [RFC3447]) using a key of at 382 least 2048 bits. 384 3. Log Format and Operation 386 Anyone can submit certificates to certificate logs for public 387 auditing; however, since certificates will not be accepted by TLS 388 clients unless logged, it is expected that certificate owners or 389 their CAs will usually submit them. A log is a single, ever-growing, 390 append-only Merkle Tree of such certificates. 392 When a valid certificate is submitted to a log, the log MUST return a 393 Signed Certificate Timestamp (SCT). The SCT is the log's promise to 394 incorporate the certificate in the Merkle Tree within a fixed amount 395 of time known as the Maximum Merge Delay (MMD). If the log has 396 previously seen the certificate, it MAY return the same SCT as it 397 returned before (note that if a certificate was previously logged as 398 a precertificate, then the precertificate's SCT would not be 399 appropriate, instead a fresh SCT of type x509_entry should be 400 generated). TLS servers MUST present an SCT from one or more logs to 401 the TLS client together with the certificate. A certificate not 402 accompanied by an SCT (either for the end-entity certificate or for a 403 name-constrained intermediate the end-entity certificate chains to) 404 MUST NOT be considered compliant by TLS clients. 406 Periodically, each log appends all its new entries to the Merkle Tree 407 and signs the root of the tree. The log MUST incorporate a 408 certificate in its Merkle Tree within the Maximum Merge Delay period 409 after the issuance of the SCT. When encountering an SCT, an Auditor 410 can verify that the certificate was added to the Merkle Tree within 411 that timeframe. 413 Log operators MUST NOT impose any conditions on retrieving or sharing 414 data from the log. 416 3.1. Log Entries 418 In order to enable attribution of each logged certificate to its 419 issuer, each submitted certificate MUST be accompanied by all 420 additional certificates required to verify the certificate chain up 421 to an accepted root certificate. The root certificate itself MAY be 422 omitted from the chain submitted to the log server. The log SHALL 423 allow retrieval of a list of accepted root certificates (this list 424 might usefully be the union of root certificates trusted by major 425 browser vendors). 427 Alternatively, (root as well as intermediate) certification 428 authorities may preannounce a certificate to logs prior to issuance 429 in order to incorporate the SCT in the issued certificate. To do 430 this, the CA submits a precertificate that the log can use to create 431 an entry that will be valid against the issued certificate. A 432 precertificate is a CMS [RFC5652] "signed-data" object that contains 433 a TBSCertificate [RFC5280] in its 434 "SignedData.encapContentInfo.eContent" field, identified by the OID 435 in the "SignedData.encapContentInfo.eContentType" field. This 436 TBSCertificate MAY redact certain domain name labels that will be 437 present in the issued certificate (see Section 3.2.2) and MUST NOT 438 contain any SCTs, but it will be otherwise identical to the 439 TBSCertificate in the issued certificate. "SignedData.signerInfos" 440 MUST contain a signature from the same (root or intermediate) CA that 441 will ultimately issue the certificate. This signature indicates the 442 certification authority's intent to issue the certificate. This 443 intent is considered binding (i.e., misissuance of the precertificate 444 is considered equivalent to misissuance of the certificate). As 445 above, the precertificate submission MUST be accompanied by all the 446 additional certificates required to verify the chain up to an 447 accepted root certificate. This does not involve using the 448 "SignedData.certificates" field, so that field SHOULD be omitted. 450 Logs MUST verify that the submitted certificate or precertificate has 451 a valid signature chain to an accepted root certificate, using the 452 chain of intermediate CA certificates provided by the submitter. 453 Logs MUST accept certificates that are fully valid according to X.509 454 verification rules and are submitted with such a chain. Logs MAY 455 accept certificates and precertificates that have expired, are not 456 yet valid, have been revoked, or are otherwise not fully valid 457 according to X.509 verification rules in order to accommodate quirks 458 of CA certificate-issuing software. However, logs MUST reject 459 certificates without a valid signature chain to an accepted root 460 certificate. If a certificate is accepted and an SCT issued, the 461 accepting log MUST store the entire chain used for verification, 462 including the certificate or precertificate itself and including the 463 root certificate used to verify the chain (even if it was omitted 464 from the submission), and MUST present this chain for auditing upon 465 request. This chain is required to prevent a CA from avoiding blame 466 by logging a partial or empty chain. (Note: This effectively 467 excludes self-signed and DANE-based certificates until some mechanism 468 to limit the submission of spurious certificates is found. The 469 authors welcome suggestions.) 470 Each certificate or precertificate entry in a log MUST include the 471 following components: 473 enum { x509_entry(0), precert_entry_V2(3), (65535) } LogEntryType; 475 struct { 476 LogEntryType entry_type; 477 select (entry_type) { 478 case x509_entry: X509ChainEntry; 479 case precert_entry_V2: PrecertChainEntryV2; 480 } entry; 481 } LogEntry; 483 opaque ASN.1Cert<1..2^24-1>; 485 struct { 486 ASN.1Cert leaf_certificate; 487 ASN.1Cert certificate_chain<0..2^24-1>; 488 } X509ChainEntry; 490 opaque CMSPrecert<1..2^24-1>; 492 struct { 493 CMSPrecert pre_certificate; 494 ASN.1Cert precertificate_chain<0..2^24-1>; 495 } PrecertChainEntryV2; 497 Logs SHOULD limit the length of chain they will accept. 499 "entry_type" is the type of this entry. Future revisions of this 500 protocol may add new LogEntryType values. Section 4 explains how 501 clients should handle unknown entry types. 503 "leaf_certificate" is the end-entity certificate submitted for 504 auditing. 506 "certificate_chain" is a chain of additional certificates required to 507 verify the end-entity certificate. The first certificate MUST 508 certify the end-entity certificate. Each following certificate MUST 509 directly certify the one preceding it. The final certificate MUST 510 either be, or be issued by, a root certificate accepted by the log. 512 "pre_certificate" is the precertificate submitted for auditing. 514 "precertificate_chain" is a chain of additional certificates required 515 to verify the precertificate submission. The first certificate MUST 516 certify the precertificate. Each following certificate MUST directly 517 certify the one preceding it. The final certificate MUST be a root 518 certificate accepted by the log. 520 3.2. Private Domain Name Labels 522 Some regard some DNS domain name labels within their registered 523 domain space as private and security sensitive. Even though these 524 domains are often only accessible within the domain owner's private 525 network, it's common for them to be secured using publicly trusted 526 TLS server certificates. We define a mechanism to allow these 527 private labels to not appear in public logs. 529 3.2.1. Wildcard Certificates 531 A certificate containing a DNS-ID [RFC6125] of "*.example.com" could 532 be used to secure the domain "topsecret.example.com", without 533 revealing the string "topsecret" publicly. 535 Since TLS clients only match the wildcard character to the complete 536 leftmost label of the DNS domain name (see Section 6.4.3 of 537 [RFC6125]), this approach would not work for a DNS-ID such as 538 "top.secret.example.com". Also, wildcard certificates are prohibited 539 in some cases, such as Extended Validation Certificates 540 [EVSSLGuidelines]. 542 3.2.2. Redacting Domain Name Labels in Precertificates 544 When creating a precertificate, the CA MAY substitute one or more 545 labels in each DNS-ID with a corresponding number of "?" labels. 546 Every label to the left of a "?" label MUST also be redacted. For 547 example, if a certificate contains a DNS-ID of 548 "top.secret.example.com", then the corresponding precertificate could 549 contain "?.?.example.com" instead, but not "top.?.example.com" 550 instead. 552 Wildcard "*" labels MUST NOT be redacted. However, if the complete 553 leftmost label of a DNS-ID is "*", it is considered redacted for the 554 purposes of determining if the label to the right may be redacted. 555 For example, if a certificate contains a DNS-ID of 556 "*.top.secret.example.com", then the corresponding precertificate 557 could contain "*.?.?.example.com" instead, but not 558 "?.?.?.example.com" instead. 560 When a precertificate contains one or more redacted labels, a non- 561 critical extension (OID 1.3.6.1.4.1.11129.2.4.6, whose extnValue 562 OCTET STRING contains an ASN.1 SEQUENCE OF INTEGERs) MUST be added to 563 the corresponding certificate: the first INTEGER indicates the total 564 number of redacted labels and wildcard "*" labels in the 565 precertificate's first DNS-ID; the second INTEGER does the same for 566 the precertificate's second DNS-ID; etc. There MUST NOT be more 567 INTEGERs than there are DNS-IDs. If there are fewer INTEGERs than 568 there are DNS-IDs, the shortfall is made up by implicitly repeating 569 the last INTEGER. Each INTEGER MUST have a value of zero or more. 570 The purpose of this extension is to enable TLS clients to accurately 571 reconstruct the TBSCertificate component of the precertificate from 572 the certificate without having to perform any guesswork. 574 When a precertificate contains that extension and contains a CN-ID 575 [RFC6125], the CN-ID MUST match the first DNS-ID and have the same 576 labels redacted. TLS clients will use the first entry in the 577 SEQUENCE OF INTEGERs to reconstruct both the first DNS-ID and the CN- 578 ID. 580 3.2.3. Using a Name-Constrained Intermediate CA 582 An intermediate CA certificate or intermediate CA precertificate that 583 contains the critical or non-critical Name Constraints [RFC5280] 584 extension MAY be logged in place of end-entity certificates issued by 585 that intermediate CA, as long as all of the following conditions are 586 met: 588 o there MUST be a non-critical extension (OID 589 1.3.6.1.4.1.11129.2.4.7, whose extnValue OCTET STRING contains 590 ASN.1 NULL data (0x05 0x00)). This extension is an explicit 591 indication that it is acceptable to not log certificates issued by 592 this intermediate CA. 594 o permittedSubtrees MUST specify one or more dNSNames. 596 o excludedSubtrees MUST specify the entire IPv4 and IPv6 address 597 ranges. 599 Below is an example Name Constraints extension that meets these 600 conditions: 602 SEQUENCE { 603 OBJECT IDENTIFIER '2 5 29 30' 604 OCTET STRING, encapsulates { 605 SEQUENCE { 606 [0] { 607 SEQUENCE { 608 [2] 'example.com' 609 } 610 } 611 [1] { 612 SEQUENCE { 613 [7] 00 00 00 00 00 00 00 00 614 } 615 SEQUENCE { 616 [7] 617 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 618 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 619 } 620 } 621 } 622 } 623 } 625 3.3. Structure of the Signed Certificate Timestamp 627 enum { certificate_timestamp(0), tree_hash(1), (255) } 628 SignatureType; 630 enum { v1(0), v2(1), (255) } 631 Version; 633 struct { 634 opaque key_id[32]; 635 } LogID; 637 opaque TBSCertificate<1..2^24-1>; 639 opaque CtExtensions<0..2^16-1>; 641 "key_id" is the SHA-256 hash of the log's public key, calculated over 642 the DER encoding of the key represented as SubjectPublicKeyInfo. 644 "tbs_certificate" is the DER-encoded TBSCertificate component of the 645 precertificate. Note that it is also possible to reconstruct this 646 TBSCertificate from the issued certificate by extracting the 647 TBSCertificate from it, redacting the domain name labels indicated by 648 the redacted labels extension, and deleting the SCT list extension 649 and redacted labels extension. 651 struct { 652 Version sct_version; 653 LogID id; 654 uint64 timestamp; 655 CtExtensions extensions; 656 digitally-signed struct { 657 Version sct_version; 658 SignatureType signature_type = certificate_timestamp; 659 uint64 timestamp; 660 LogEntryType entry_type; 661 select(entry_type) { 662 case x509_entry: ASN.1Cert; 663 case precert_entry_V2: TBSCertificate; 664 } signed_entry; 665 CtExtensions extensions; 666 }; 667 } SignedCertificateTimestamp; 669 The encoding of the digitally-signed element is defined in [RFC5246]. 671 "sct_version" is the version of the protocol to which the SCT 672 conforms. This version is v2. 674 "timestamp" is the current NTP Time [RFC5905], measured since the 675 epoch (January 1, 1970, 00:00), ignoring leap seconds, in 676 milliseconds. 678 "entry_type" may be implicit from the context in which the SCT is 679 presented. 681 "signed_entry" is the "leaf_certificate" (in the case of an 682 X509ChainEntry) or is the TBSCertificate (in the case of a 683 PrecertChainEntryV2), as described above. 685 "extensions" are future extensions to SignedCertificateTimestamp v2. 686 Currently, no extensions are specified. 688 3.4. Including the Signed Certificate Timestamp in the TLS Handshake 690 The SCT data corresponding to at least one certificate in the chain 691 from at least one log must be included in the TLS handshake by using 692 one or more of the mechanisms listed below. Three mechanisms are 693 provided because they have different tradeoffs. TLS clients MUST 694 implement all three mechanisms. TLS servers MUST present SCTs using 695 at least one of the three mechanisms. 697 o A TLS extension (Section 7.4.1.4 of [RFC5246]) with type 698 "signed_certificate_timestamp" (see Section 3.4.1). This 699 mechanism allows TLS servers to participate in CT without the 700 cooperation of CAs, unlike the other two mechanisms. It also 701 allows SCTs to be updated on the fly. 703 o An Online Certificate Status Protocol (OCSP) [RFC6960] response 704 extension (see Section 3.4.2.1), where the OCSP response is 705 provided in the "certificate_status" TLS extension (Section 8 of 706 [RFC6066]), also known as OCSP stapling. This mechanism is 707 already widely (but not universally) implemented. It also allows 708 SCTs to be updated on the fly. 710 o An X509v3 certificate extension (see Section 3.4.2.2). This 711 mechanism allows the use of unmodified TLS servers, but, because 712 the included SCTs cannot be changed without re-issuing the 713 certificate, increases the risk that the certificate will be 714 refused if any of the SCTs become invalid. 716 TLS servers SHOULD send SCTs from multiple logs in case one or more 717 logs are not acceptable to the TLS client (for example, if a log has 718 been struck off for misbehavior, has had a key compromise or is not 719 known to the TLS client). Multiple SCTs are combined into an SCT 720 list as follows: 722 opaque SerializedSCT<1..2^16-1>; 724 struct { 725 SerializedSCT sct_list <1..2^16-1>; 726 } SignedCertificateTimestampList; 728 Here, "SerializedSCT" is an opaque byte string that contains the 729 serialized SCT structure. This encoding ensures that TLS clients can 730 decode each SCT individually (i.e., if there is a version upgrade, 731 out-of-date clients can still parse old SCTs while skipping over new 732 SCTs whose versions they don't understand). 734 3.4.1. TLS Extension 736 One or more SCTs can be sent during the TLS handshake using a TLS 737 extension with type "signed_certificate_timestamp". 739 TLS clients that support the extension SHOULD send a ClientHello 740 extension with the appropriate type and empty "extension_data". 742 TLS servers MUST only send SCTs in this TLS extension to TLS clients 743 that have indicated support for the extension in the ClientHello, in 744 which case the SCTs are sent by setting the "extension_data" to a 745 "SignedCertificateTimestampList". 747 Session resumption uses the original session information: TLS clients 748 SHOULD include the extension type in the ClientHello, but if the 749 session is resumed, the TLS server is not expected to process it or 750 include the extension in the ServerHello. 752 3.4.2. X.509v3 Extension 754 One or more SCTs can be embedded in an X.509v3 extension that is 755 included in a certificate or an OCSP response. Since RFC5280 756 requires the "extnValue" field (an OCTET STRING) of each X.509v3 757 extension to include the DER encoding of an ASN.1 value, we cannot 758 embed a "SignedCertificateTimestampList" directly. Instead, we have 759 to wrap it inside an additional OCTET STRING (see below), which we 760 then put into the "extnValue" field. 762 3.4.2.1. OCSP Response Extension 764 A certification authority may embed one or more SCTs in OCSP 765 responses pertaining to the end-entity certificate, by including a 766 non-critical "singleExtensions" extension with OID 767 1.3.6.1.4.1.11129.2.4.5 whose "extnValue" contains: 769 CertificateSCTList ::= OCTET STRING 771 "CertificateSCTList" contains a "SignedCertificateTimestampList" 772 whose SCTs all have the "x509_entry" "LogEntryType". 774 3.4.2.2. Certificate Extension 776 A certification authority that has submitted a precertificate to one 777 or more logs may embed the obtained SCTs in the "TBSCertificate" that 778 will be signed to produce the certificate, by including a non- 779 critical X.509v3 extension with OID 1.3.6.1.4.1.11129.2.4.2 whose 780 "extnValue" contains: 782 PrecertificateSCTList ::= OCTET STRING 784 "PrecertificateSCTList" contains a "SignedCertificateTimestampList" 785 whose SCTs all have the "precert_entry_V2" "LogEntryType". 787 Upon receiving the certificate, clients can reconstruct the original 788 "TBSCertificate" to verify the SCT signatures. 790 3.5. Merkle Tree 792 The hashing algorithm for the Merkle Tree Hash is specified in the 793 log's metadata. 795 Structure of the Merkle Tree input: 797 enum { v1(0), v2(1), (255) } 798 LeafVersion; 800 struct { 801 uint64 timestamp; 802 LogEntryType entry_type; 803 select(entry_type) { 804 case x509_entry: ASN.1Cert; 805 case precert_entry_V2: TBSCertificate; 806 } signed_entry; 807 CtExtensions extensions; 808 } TimestampedEntry; 810 struct { 811 LeafVersion version; 812 TimestampedEntry timestamped_entry; 813 } MerkleTreeLeaf; 815 Here, "version" is the version of the MerkleTreeLeaf structure. This 816 version is v2. Note that MerkleTreeLeaf v1 [RFC6962] had another 817 layer of indirection which is removed in v2. 819 "timestamp" is the timestamp of the corresponding SCT issued for this 820 certificate. 822 "entry_type" is the type of entry stored in "signed_entry". New 823 "LogEntryType" values may be added to "signed_entry" without 824 increasing the "MerkleTreeLeaf" version. Section 4 explains how 825 clients should handle unknown entry types. 827 "signed_entry" is the "signed_entry" of the corresponding SCT. 829 "extensions" are "extensions" of the corresponding SCT. 831 The leaves of the Merkle Tree are the leaf hashes of the 832 corresponding "MerkleTreeLeaf" structures. 834 3.6. Signed Tree Head 836 Every time a log appends new entries to the tree, the log SHOULD sign 837 the corresponding tree hash and tree information (see the 838 corresponding Signed Tree Head client message in Section 4.3). The 839 signature for that data is structured as follows: 841 enum { v1(0), (255) } TreeHeadVersion; 843 digitally-signed struct { 844 TreeHeadVersion version; 845 SignatureType signature_type = tree_hash; 846 uint64 timestamp; 847 uint64 tree_size; 848 opaque sha256_root_hash[32]; 849 } TreeHeadSignature; 851 "version" is the version of the TreeHeadSignature structure. This 852 version is v1. 854 "timestamp" is the current time. The timestamp MUST be at least as 855 recent as the most recent SCT timestamp in the tree. Each subsequent 856 timestamp MUST be more recent than the timestamp of the previous 857 update. 859 "tree_size" equals the number of entries in the new tree. 861 "sha256_root_hash" is the root of the Merkle Hash Tree. 863 Each log MUST produce on demand a Signed Tree Head that is no older 864 than the Maximum Merge Delay. In the unlikely event that it receives 865 no new submissions during an MMD period, the log SHALL sign the same 866 Merkle Tree Hash with a fresh timestamp. 868 4. Log Client Messages 870 Messages are sent as HTTPS GET or POST requests. Parameters for 871 POSTs and all responses are encoded as JavaScript Object Notation 872 (JSON) objects [RFC4627]. Parameters for GETs are encoded as order- 873 independent key/value URL parameters, using the "application/x-www- 874 form-urlencoded" format described in the "HTML 4.01 Specification" 875 [HTML401]. Binary data is base64 encoded [RFC4648] as specified in 876 the individual messages. 878 Note that JSON objects and URL parameters may contain fields not 879 specified here. These extra fields should be ignored. 881 The prefix MAY include a path as well as a server name 882 and a port. 884 In general, where needed, the "version" is v1 and the "id" is the log 885 id for the log server queried. 887 In practice, log servers may include multiple front-end machines. 888 Since it is impractical to keep these machines in perfect sync, 889 errors may occur that are caused by skew between the machines. Where 890 such errors are possible, the front-end will return additional 891 information (as specified below) making it possible for clients to 892 make progress, if progress is possible. Front-ends MUST only serve 893 data that is free of gaps (that is, for example, no front-end will 894 respond with an STH unless it is also able to prove consistency from 895 all log entries logged within that STH). 897 For example, when a consistency proof between two STHs is requested, 898 the front-end reached may not yet be aware of one or both STHs. In 899 the case where it is unaware of both, it will return the latest STH 900 it is aware of. Where it is aware of the first but not the second, 901 it will return the latest STH it is aware of and a consistency proof 902 from the first STH to the returned STH. The case where it knows the 903 second but not the first should not arise (see the "no gaps" 904 requirement above). 906 If the log is unable to process a client's request, it MUST return an 907 HTTP response code of 4xx/5xx (see [RFC2616]), and, in place of the 908 responses outlined in the subsections below, the body SHOULD be a 909 JSON structure containing at least the following field: 911 error_message: A human-readable string describing the error which 912 prevented the log from processing the request. 914 In the case of a malformed request, the string SHOULD provide 915 sufficient detail for the error to be rectified. 917 error_code: An error code readable by the client. Some codes are 918 generic and are detailed here. Others are detailed in the 919 individual requests. Error codes are fixed text strings. 921 not compliant The request is not compliant with this RFC. 923 e.g. In response to a request of "/ct/v1/get- 924 entries?start=100&end=99", the log would return a "400 Bad Request" 925 response code with a body similar to the following: 927 { 928 "error_message": "'start' cannot be greater than 'end'", 929 "error_code": "not compliant", 930 } 932 Clients SHOULD treat "500 Internal Server Error" and "503 Service 933 Unavailable" responses as transient failures and MAY retry the same 934 request without modification at a later date. Note that as per 935 [RFC2616], in the case of a 503 response the log MAY include a 936 "Retry-After:" header in order to request a minimum time for the 937 client to wait before retrying the request. 939 4.1. Add Chain to Log 941 POST https:///ct/v1/add-chain 943 Inputs: 945 chain: An array of base64-encoded certificates. The first 946 element is the end-entity certificate; the second chains to the 947 first and so on to the last, which is either the root 948 certificate or a certificate that chains to a known root 949 certificate. 951 Outputs: 953 sct_version: The version of the SignedCertificateTimestamp 954 structure, in decimal. A compliant v1 implementation MUST NOT 955 expect this to be 0 (i.e., v1). 957 id: The log ID, base64 encoded. 959 timestamp: The SCT timestamp, in decimal. 961 extensions: An opaque type for future expansion. It is likely 962 that not all participants will need to understand data in this 963 field. Logs should set this to the empty string. Clients 964 should decode the base64-encoded data and include it in the 965 SCT. 967 signature: The SCT signature, base64 encoded. 969 Error codes: 971 unknown root The root of the chain is not one accepted by the 972 log. 974 bad chain The alleged chain is not actually a chain of 975 certificates. 977 bad certificate One or more certificates in the chain are not 978 valid (e.g. not properly encoded). 980 If the "sct_version" is not v1, then a v1 client may be unable to 981 verify the signature. It MUST NOT construe this as an error. This 982 is to avoid forcing an upgrade of compliant v1 clients that do not 983 use the returned SCTs. 985 If a log detects bad encoding in a chain that otherwise verifies 986 correctly (e.g. some software will accept BER instead of DER 987 encodings in certificates, or incorrect character encodings, even 988 though these are technically incorrect) then the log MAY still log 989 the certificate but SHOULD NOT return an SCT. It should instead 990 return the "bad certificate" error. Logging the certificate is 991 useful, because monitors can then detect these encoding errors, which 992 may be accepted by some TLS clients. 994 Note that not all certificate handling software is capable of 995 detecting all encoding errors. 997 4.2. Add PreCertChain to Log 999 POST https:///ct/v1/add-pre-chain 1001 Inputs: 1003 precertificate: The base64-encoded precertificate. 1005 chain: An array of base64-encoded CA certificates. The first 1006 element is the signer of the precertificate; the second chains 1007 to the first and so on to the last, which is either the root 1008 certificate or a certificate that chains to an accepted root 1009 certificate. 1011 Outputs and errors are the same as in Section 4.1. 1013 4.3. Retrieve Latest Signed Tree Head 1015 GET https:///ct/v1/get-sth 1017 No inputs. 1019 Outputs: 1021 tree_size: The size of the tree, in entries, in decimal. 1023 timestamp: The timestamp, in decimal. 1025 sha256_root_hash: The Merkle Tree Hash of the tree, in base64. 1027 tree_head_signature: A TreeHeadSignature for the above data. 1029 4.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads 1031 GET https:///ct/v2/get-sth-consistency 1033 Inputs: 1035 first: The tree_size of the older tree, in decimal. 1037 second: The tree_size of the newer tree, in decimal (optional). 1039 Both tree sizes must be from existing v1 STHs (Signed Tree Heads). 1040 However, because of skew, the receiving front-end may not know one 1041 or both of the existing STHs. If both are known, then only the 1042 "consistency" output is returned. If the first is known but the 1043 second is not (or has been omitted), then the latest known STH is 1044 returned, along with a consistency proof between the first STH and 1045 the latest. If neither are known, then the latest known STH is 1046 returned without a consistency proof. 1048 Outputs: 1050 consistency: An array of Merkle Tree nodes, base64 encoded. 1052 tree_size: The size of the tree, in entries, in decimal. 1054 timestamp: The timestamp, in decimal. 1056 sha256_root_hash: The Merkle Tree Hash of the tree, in base64. 1058 tree_head_signature: A TreeHeadSignature for the above data. 1060 Note that no signature is required on this data, as it is used to 1061 verify an STH, which is signed. 1063 Error codes: 1065 first unknown "first" is before the latest known STH but is not 1066 from an existing STH. 1068 second unknown "second" is before the latest known STH but is not 1069 from an existing STH. 1071 4.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash 1073 GET https:///ct/v2/get-proof-by-hash 1075 Inputs: 1077 hash: A base64-encoded v1 leaf hash. 1079 tree_size: The tree_size of the tree on which to base the proof, 1080 in decimal. 1082 The "hash" must be calculated as defined in Section 3.5. The 1083 "tree_size" must designate an existing v1 STH. Because of skew, 1084 the front-end may not know the requested STH. In that case, it 1085 will return the latest STH it knows, along with an inclusion proof 1086 to that STH. If the front-end knows the requested STH then only 1087 "leaf_index" and "audit_path" are returned. 1089 Outputs: 1091 leaf_index: The 0-based index of the entry corresponding to the 1092 "hash" parameter. 1094 audit_path: An array of base64-encoded Merkle Tree nodes proving 1095 the inclusion of the chosen certificate. 1097 tree_size: The size of the tree, in entries, in decimal. 1099 timestamp: The timestamp, in decimal. 1101 sha256_root_hash: The Merkle Tree Hash of the tree, in base64. 1103 tree_head_signature: A TreeHeadSignature for the above data. 1105 Error codes: 1107 hash unknown "hash" is not the hash of a known leaf (may be 1108 caused by skew or by a known certificate not yet merged). 1110 tree_size unknown "hash" is before the latest known STH but is 1111 not from an existing STH. 1113 4.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and Consistency 1114 Proof by Leaf Hash 1116 GET https:///ct/v2/get-all-by-hash 1118 Inputs: 1120 hash: A base64-encoded v1 leaf hash. 1122 tree_size: The tree_size of the tree on which to base the proofs, 1123 in decimal. 1125 The "hash" must be calculated as defined in Section 3.5. The 1126 "tree_size" must designate an existing v1 STH. 1128 Because of skew, the front-end may not know the requested STH or 1129 the requested hash, which leads to a number of cases. 1131 latest STH < requested STH Return latest STH. 1133 latest STH > requested STH Return latest STH and a consistency 1134 proof between it and the requested STH (see Section 4.4). 1136 index of requested hash < latest STH Return "leaf_index" and 1137 "audit_path". 1139 Note that more than one case can be true, in which case the 1140 returned data is their concatenation. It is also possible for 1141 none to be true, in which case the front-end MUST return an empty 1142 response. 1144 Outputs: 1146 leaf_index: The 0-based index of the entry corresponding to the 1147 "hash" parameter. 1149 audit_path: An array of base64-encoded Merkle Tree nodes proving 1150 the inclusion of the chosen certificate. 1152 tree_size: The size of the tree, in entries, in decimal. 1154 timestamp: The timestamp, in decimal. 1156 sha256_root_hash: The Merkle Tree Hash of the tree, in base64. 1158 tree_head_signature: A TreeHeadSignature for the above data. 1160 consistency: An array of base64-encoded Merkle Tree nodes proving 1161 the consistency of the requested STH and the returned STH. 1163 Errors are the same as in Section 4.5. 1165 4.7. Retrieve Entries from Log 1167 GET https:///ct/v1/get-entries 1169 Inputs: 1171 start: 0-based index of first entry to retrieve, in decimal. 1173 end: 0-based index of last entry to retrieve, in decimal. 1175 Outputs: 1177 entries: An array of objects, each consisting of 1179 leaf_input: The base64-encoded MerkleTreeLeaf structure. 1181 extra_data: The base64-encoded unsigned data pertaining to the 1182 log entry. In the case of an X509ChainEntry, this is the 1183 "certificate_chain". In the case of a PrecertChainEntryV2, 1184 this is the whole "PrecertChainEntryV2". 1186 Note that this message is not signed -- the retrieved data can be 1187 verified by constructing the Merkle Tree Hash corresponding to a 1188 retrieved STH. All leaves MUST be v1 or v2. However, a compliant v1 1189 client MUST NOT construe an unrecognized LogEntryType value as an 1190 error. This means it may be unable to parse some entries, but note 1191 that each client can inspect the entries it does recognize as well as 1192 verify the integrity of the data by treating unrecognized leaves as 1193 opaque input to the tree. 1195 The "start" and "end" parameters SHOULD be within the range 0 <= x < 1196 "tree_size" as returned by "get-sth" in Section 4.3. 1198 Logs MAY honor requests where 0 <= "start" < "tree_size" and "end" >= 1199 "tree_size" by returning a partial response covering only the valid 1200 entries in the specified range. Note that the following restriction 1201 may also apply: 1203 Logs MAY restrict the number of entries that can be retrieved per 1204 "get-entries" request. If a client requests more than the permitted 1205 number of entries, the log SHALL return the maximum number of entries 1206 permissible. These entries SHALL be sequential beginning with the 1207 entry specified by "start". 1209 Because of skew, it is possible the log server will not have any 1210 entries between "start" and "end". In this case it MUST return an 1211 empty "entries" array. 1213 4.8. Retrieve Accepted Root Certificates 1215 GET https:///ct/v1/get-roots 1217 No inputs. 1219 Outputs: 1221 certificates: An array of base64-encoded root certificates that 1222 are acceptable to the log. 1224 max_chain: If the server has chosen to limit the length of chains 1225 it accepts, this is the maximum number of certificates in the 1226 chain, in decimal. If there is no limit, this is omitted. 1228 5. Clients 1230 There are various different functions clients of logs might perform. 1231 We describe here some typical clients and how they could function. 1232 Any inconsistency may be used as evidence that a log has not behaved 1233 correctly, and the signatures on the data structures prevent the log 1234 from denying that misbehavior. 1236 All clients need various metadata in order to communicate with logs 1237 and verify their responses. This metadata is described below, but 1238 note that this document does not describe how the metadata is 1239 obtained, which is implementation dependent (see, for example, 1240 [Chromium.Policy]). 1242 Clients should somehow exchange STHs they see, or make them available 1243 for scrutiny, in order to ensure that they all have a consistent 1244 view. The exact mechanisms will be in separate documents, but it is 1245 expected there will be a variety. 1247 5.1. Metadata 1249 In order to communicate with and verify a log, clients need metadata 1250 about the log. 1252 Base URL: The URL to substitute for in Section 4. 1254 Hash Algorithm The hash algorithm used for the Merkle Tree (see 1255 Section 7.2). 1257 Signing Algorithm The signing algorithm used (see Section 2.1.4). 1259 Public Key The public key used for signing. 1261 Maximum Merge Delay The MMD the log has committed to. 1263 Final STH If a log has been closed down (i.e. no longer accepts new 1264 entries), existing entries may still be valid. In this case, the 1265 client should know the final valid STH in the log to ensure no new 1266 entries can be added without detection. 1268 [JSON.Metadata] is an example of a metadata format which includes the 1269 above elements. 1271 5.2. Submitters 1273 Submitters submit certificates or precertificates to the log as 1274 described above. When a Submitter intends to use the returned SCT 1275 directly in a TLS handshake or to construct a certificate, they 1276 SHOULD validate the SCT as described in Section 5.3 if they 1277 understand its format. 1279 5.3. TLS Client 1281 TLS clients receive SCTs alongside or in certificates, either for the 1282 server certificate itself or for intermediate CA precertificates. In 1283 addition to normal validation of the certificate and its chain, TLS 1284 clients SHOULD validate the SCT by computing the signature input from 1285 the SCT data as well as the certificate and verifying the signature, 1286 using the corresponding log's public key. 1288 A TLS client MAY audit the corresponding log by requesting, and 1289 verifying, a Merkle audit proof for said certificate. If the TLS 1290 client holds an STH that predates the SCT, it MAY, in the process of 1291 auditing, request a new STH from the log (Section 4.3), then verify 1292 it by requesting a consistency proof (Section 4.4). 1294 TLS clients MUST reject SCTs whose timestamp is in the future. 1296 5.4. Monitor 1298 Monitors watch logs and check that they behave correctly. Monitors 1299 may additionally watch for certificates of interest. For example, a 1300 monitor may be configured to report on all certificates that apply to 1301 a specific domain name when fetching new entries for consistency 1302 validation. 1304 A monitor needs to, at least, inspect every new entry in each log it 1305 watches. It may also want to keep copies of entire logs. In order 1306 to do this, it should follow these steps for each log: 1308 1. Fetch the current STH (Section 4.3). 1310 2. Verify the STH signature. 1312 3. Fetch all the entries in the tree corresponding to the STH 1313 (Section 4.7). 1315 4. Confirm that the tree made from the fetched entries produces the 1316 same hash as that in the STH. 1318 5. Fetch the current STH (Section 4.3). Repeat until the STH 1319 changes. 1321 6. Verify the STH signature. 1323 7. Fetch all the new entries in the tree corresponding to the STH 1324 (Section 4.7). If they remain unavailable for an extended 1325 period, then this should be viewed as misbehavior on the part of 1326 the log. 1328 8. Either: 1330 1. Verify that the updated list of all entries generates a tree 1331 with the same hash as the new STH. 1333 Or, if it is not keeping all log entries: 1335 1. Fetch a consistency proof for the new STH with the previous 1336 STH (Section 4.4). 1338 2. Verify the consistency proof. 1340 3. Verify that the new entries generate the corresponding 1341 elements in the consistency proof. 1343 9. Go to Step 5. 1345 5.5. Auditing 1347 Auditing is taking partial information about a log as input and 1348 verifying that this information is consistent with other partial 1349 information held. All clients described above may perform auditing 1350 as an additional function. The action taken by the client if audit 1351 fails is not specified, but note that in general if audit fails, the 1352 client is in possession of signed proof of the log's misbehavior. 1354 A monitor (Section 5.4) can audit by verifying the consistency of 1355 STHs it receives, ensure that each entry can be fetched and that the 1356 STH is indeed the result of making a tree from all fetched entries. 1358 A TLS client (Section 5.3) can audit by verifying an SCT against any 1359 STH dated after the SCT timestamp + the Maximum Merge Delay by 1360 requesting a Merkle inclusion proof (Section 4.5). It can also 1361 verify that the SCT corresponds to the certificate it arrived with 1362 (i.e. the log entry is that certificate, is a precertificate for that 1363 certificate or is an appropriate name-constrained intermediate [see 1364 Section 3.2.3]). 1366 6. Algorithm Agility 1368 It is not possible for a log to change any of its algorithms part way 1369 through its lifetime. If it should become necessary to deprecate an 1370 algorithm used by a live log, then the log should be frozen as 1371 specified in Section 5.1 and a new log should be started. If 1372 necessary, the new log can contain existing entries from the frozen 1373 log, which monitors can verify are an exact match. 1375 7. IANA Considerations 1377 7.1. TLS Extension Type 1379 IANA has allocated an RFC 5246 ExtensionType value (18) for the SCT 1380 TLS extension. The extension name is "signed_certificate_timestamp". 1381 IANA should update this extension type to point at this document. 1383 7.2. Hash Algorithms 1385 IANA is asked to establish a registry of hash values, initially 1386 consisting of: 1388 +-------+----------------------+ 1389 | Index | Hash | 1390 +-------+----------------------+ 1391 | 0 | SHA-256 [FIPS.180-4] | 1392 +-------+----------------------+ 1394 8. Security Considerations 1396 With CAs, logs, and servers performing the actions described here, 1397 TLS clients can use logs and signed timestamps to reduce the 1398 likelihood that they will accept misissued certificates. If a server 1399 presents a valid signed timestamp for a certificate, then the client 1400 knows that a log has committed to publishing the certificate. From 1401 this, the client knows that the subject of the certificate has had 1402 some time to notice the misissue and take some action, such as asking 1403 a CA to revoke a misissued certificate, or that the log has 1404 misbehaved, which will be discovered when the SCT is audited. A 1405 signed timestamp is not a guarantee that the certificate is not 1406 misissued, since the subject of the certificate might not have 1407 checked the logs or the CA might have refused to revoke the 1408 certificate. 1410 In addition, if TLS clients will not accept unlogged certificates, 1411 then site owners will have a greater incentive to submit certificates 1412 to logs, possibly with the assistance of their CA, increasing the 1413 overall transparency of the system. 1415 8.1. Misissued Certificates 1417 Misissued certificates that have not been publicly logged, and thus 1418 do not have a valid SCT, will be rejected by TLS clients. Misissued 1419 certificates that do have an SCT from a log will appear in that 1420 public log within the Maximum Merge Delay, assuming the log is 1421 operating correctly. Thus, the maximum period of time during which a 1422 misissued certificate can be used without being available for audit 1423 is the MMD. 1425 8.2. Detection of Misissue 1427 The logs do not themselves detect misissued certificates; they rely 1428 instead on interested parties, such as domain owners, to monitor them 1429 and take corrective action when a misissue is detected. 1431 8.3. Redaction of Public Domain Name Labels 1433 CAs SHOULD NOT redact domain name labels in precertificates such that 1434 the entirety of the domain space below the unredacted part of the 1435 domain name is not owned or controlled by a single entity (e.g. 1436 "?.com" and "?.co.uk" would both be problematic). Logs MUST NOT 1437 reject any precertificate that is overly redacted but which is 1438 otherwise considered compliant. It is expected that monitors will 1439 treat overly redacted precertificates as potentially misissued. TLS 1440 clients MAY reject a certificate whose corresponding precertificate 1441 would be overly redacted, perhaps using the same mechanism for 1442 determining whether a wildcard in a domain name of a certificate is 1443 too broad. 1445 8.4. Misbehaving Logs 1447 A log can misbehave in two ways: (1) by failing to incorporate a 1448 certificate with an SCT in the Merkle Tree within the MMD and (2) by 1449 violating its append-only property by presenting two different, 1450 conflicting views of the Merkle Tree at different times and/or to 1451 different parties. Both forms of violation will be promptly and 1452 publicly detectable. 1454 Violation of the MMD contract is detected by log clients requesting a 1455 Merkle audit proof for each observed SCT. These checks can be 1456 asynchronous and need only be done once per each certificate. In 1457 order to protect the clients' privacy, these checks need not reveal 1458 the exact certificate to the log. Clients can instead request the 1459 proof from a trusted auditor (since anyone can compute the audit 1460 proofs from the log) or request Merkle proofs for a batch of 1461 certificates around the SCT timestamp. 1463 Violation of the append-only property can be detected by clients 1464 comparing their instances of the Signed Tree Heads. As soon as two 1465 conflicting Signed Tree Heads for the same log are detected, this is 1466 cryptographic proof of that log's misbehavior. There are various 1467 ways this could be done, for example via gossip (see http:// 1468 trac.tools.ietf.org/id/draft-linus-trans-gossip-00.txt) or peer-to- 1469 peer communications or by sending STHs to monitors (who could then 1470 directly check against their own copy of the relevant log). 1472 8.5. Multiple SCTs 1474 TLS servers may wish to offer multiple SCTs, each from a different 1475 log. 1477 o If a CA and a log collude, it is possible to temporarily hide 1478 misissuance from clients. Including SCTs from different logs 1479 makes it more difficult to mount this attack. 1481 o If a log misbehaves, a consequence may be that clients cease to 1482 trust it. Since the time an SCT may be in use can be considerable 1483 (several years is common in current practice when the SCT is 1484 embedded in a certificate), servers may wish to reduce the 1485 probability of their certificates being rejected as a result by 1486 including SCTs from different logs. 1488 o TLS clients may have policies related to the above risks requiring 1489 servers to present multiple SCTs. For example Chromium 1490 [Chromium.Log.Policy] currently requires multiple SCTs to be 1491 presented with EV certificates in order for the EV indicator to be 1492 shown. 1494 9. Efficiency Considerations 1496 The Merkle Tree design serves the purpose of keeping communication 1497 overhead low. 1499 Auditing logs for integrity does not require third parties to 1500 maintain a copy of each entire log. The Signed Tree Heads can be 1501 updated as new entries become available, without recomputing entire 1502 trees. Third-party auditors need only fetch the Merkle consistency 1503 proofs against a log's existing STH to efficiently verify the append- 1504 only property of updates to their Merkle Trees, without auditing the 1505 entire tree. 1507 10. Acknowledgements 1509 The authors would like to thank Erwann Abelea, Robin Alden, Al 1510 Cutter, Francis Dupont, Stephen Farrell, Brad Hill, Jeff Hodges, Paul 1511 Hoffman, Jeffrey Hutzelman, SM, Alexey Melnikov, Chris Palmer, Trevor 1512 Perrin, Ryan Sleevi and Carl Wallace for their valuable 1513 contributions. 1515 11. References 1517 11.1. Normative References 1519 [DSS] National Institute of Standards and Technology, "Digital 1520 Signature Standard (DSS)", FIPS 186-3, June 2009, 1521 . 1524 [FIPS.180-4] 1525 National Institute of Standards and Technology, "Secure 1526 Hash Standard", FIPS PUB 180-4, March 2012, 1527 . 1530 [HTML401] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 1531 Specification", World Wide Web Consortium Recommendation 1532 REC-html401-19991224, December 1999, 1533 . 1535 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1536 Requirement Levels", BCP 14, RFC 2119, March 1997. 1538 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1539 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1540 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1542 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1543 Standards (PKCS) #1: RSA Cryptography Specifications 1544 Version 2.1", RFC 3447, February 2003. 1546 [RFC4627] Crockford, D., "The application/json Media Type for 1547 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1549 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1550 Encodings", RFC 4648, October 2006. 1552 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1553 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1555 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1556 Housley, R., and W. Polk, "Internet X.509 Public Key 1557 Infrastructure Certificate and Certificate Revocation List 1558 (CRL) Profile", RFC 5280, May 2008. 1560 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1561 RFC 5652, September 2009. 1563 [RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 1564 Time Protocol Version 4: Protocol and Algorithms 1565 Specification", RFC 5905, June 2010. 1567 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 1568 Extension Definitions", RFC 6066, January 2011. 1570 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1571 Verification of Domain-Based Application Service Identity 1572 within Internet Public Key Infrastructure Using X.509 1573 (PKIX) Certificates in the Context of Transport Layer 1574 Security (TLS)", RFC 6125, March 2011. 1576 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 1577 Galperin, S., and C. Adams, "X.509 Internet Public Key 1578 Infrastructure Online Certificate Status Protocol - OCSP", 1579 RFC 6960, June 2013. 1581 11.2. Informative References 1583 [Chromium.Log.Policy] 1584 The Chromium Projects, "Chromium Certificate Transparency 1585 Log Policy", 2014, . 1588 [Chromium.Policy] 1589 The Chromium Projects, "Chromium Certificate 1590 Transparency", 2014, . 1593 [CrosbyWallach] 1594 Crosby, S. and D. Wallach, "Efficient Data Structures for 1595 Tamper-Evident Logging", Proceedings of the 18th USENIX 1596 Security Symposium, Montreal, August 2009, 1597 . 1600 [EVSSLGuidelines] 1601 CA/Browser Forum, "Guidelines For The Issuance And 1602 Management Of Extended Validation Certificates", 2007, 1603 . 1606 [JSON.Metadata] 1607 The Chromium Projects, "Chromium Log Metadata JSON 1608 Schema", 2014, . 1611 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 1612 Transparency", RFC 6962, June 2013. 1614 Authors' Addresses 1616 Ben Laurie 1617 Google UK Ltd. 1619 EMail: benl@google.com 1621 Adam Langley 1622 Google Inc. 1624 EMail: agl@google.com 1626 Emilia Kasper 1627 Google Switzerland GmbH 1629 EMail: ekasper@google.com 1631 Eran Messeri 1632 Google UK Ltd. 1634 EMail: eranm@google.com 1636 Rob Stradling 1637 Comodo CA, Ltd. 1639 EMail: rob.stradling@comodo.com