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