idnits 2.17.1 draft-ietf-trans-rfc6962-bis-11.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 20, 2015) is 3080 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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 554 -- Looks like a reference, but probably isn't: '7' on line 559 -- Looks like a reference, but probably isn't: '0' on line 549 -- Looks like a reference, but probably isn't: '2' on line 551 -- Looks like a reference, but probably isn't: '32' on line 2063 -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTML401' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6979 -- Obsolete informational reference (is this intentional?): RFC 6962 (Obsoleted by RFC 9162) Summary: 6 errors (**), 0 flaws (~~), 1 warning (==), 10 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: May 23, 2016 E. Messeri 6 Google 7 R. Stradling 8 Comodo 9 November 20, 2015 11 Certificate Transparency 12 draft-ietf-trans-rfc6962-bis-11 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 May 23, 2016. 45 Copyright Notice 47 Copyright (c) 2015 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 64 1.2. Data Structures . . . . . . . . . . . . . . . . . . . . . 5 65 2. Cryptographic Components . . . . . . . . . . . . . . . . . . 5 66 2.1. Merkle Hash Trees . . . . . . . . . . . . . . . . . . . . 5 67 2.1.1. Merkle Inclusion Proofs . . . . . . . . . . . . . . . 6 68 2.1.2. Merkle Consistency Proofs . . . . . . . . . . . . . . 7 69 2.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 8 70 2.1.4. Signatures . . . . . . . . . . . . . . . . . . . . . 9 71 3. Submitters . . . . . . . . . . . . . . . . . . . . . . . . . 10 72 3.1. Certificates . . . . . . . . . . . . . . . . . . . . . . 10 73 3.2. Precertificates . . . . . . . . . . . . . . . . . . . . . 10 74 4. Private Domain Name Labels . . . . . . . . . . . . . . . . . 11 75 4.1. Wildcard Certificates . . . . . . . . . . . . . . . . . . 11 76 4.2. Redacting Domain Name Labels in Precertificates . . . . . 11 77 4.3. Using a Name-Constrained Intermediate CA . . . . . . . . 12 78 5. Log Format and Operation . . . . . . . . . . . . . . . . . . 13 79 5.1. Accepting Submissions . . . . . . . . . . . . . . . . . . 14 80 5.2. Log Entries . . . . . . . . . . . . . . . . . . . . . . . 14 81 5.3. Log ID . . . . . . . . . . . . . . . . . . . . . . . . . 15 82 5.4. The TransItem Structure . . . . . . . . . . . . . . . . . 16 83 5.5. Merkle Tree Leaves . . . . . . . . . . . . . . . . . . . 18 84 5.6. Signed Certificate Timestamp (SCT) . . . . . . . . . . . 19 85 5.7. Merkle Tree Head . . . . . . . . . . . . . . . . . . . . 20 86 5.8. Signed Tree Head (STH) . . . . . . . . . . . . . . . . . 21 87 5.9. Merkle Consistency Proofs . . . . . . . . . . . . . . . . 22 88 5.10. Merkle Inclusion Proofs . . . . . . . . . . . . . . . . . 23 89 6. Log Client Messages . . . . . . . . . . . . . . . . . . . . . 23 90 6.1. Add Chain to Log . . . . . . . . . . . . . . . . . . . . 25 91 6.2. Add PreCertChain to Log . . . . . . . . . . . . . . . . . 26 92 6.3. Retrieve Latest Signed Tree Head . . . . . . . . . . . . 26 93 6.4. Retrieve Merkle Consistency Proof between Two Signed Tree 94 Heads . . . . . . . . . . . . . . . . . . . . . . . . . . 26 95 6.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash . . 27 96 6.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and 97 Consistency Proof by Leaf Hash . . . . . . . . . . . . . 28 98 6.7. Retrieve Entries and STH from Log . . . . . . . . . . . . 29 99 6.8. Retrieve Accepted Root Certificates . . . . . . . . . . . 31 100 7. TLS Servers . . . . . . . . . . . . . . . . . . . . . . . . . 31 101 7.1. TLS Extension . . . . . . . . . . . . . . . . . . . . . . 32 102 8. Certification Authorities . . . . . . . . . . . . . . . . . . 32 103 8.1. Transparency Information X.509v3 Extension . . . . . . . 32 104 8.1.1. OCSP Response Extension . . . . . . . . . . . . . . . 33 105 8.1.2. Certificate Extension . . . . . . . . . . . . . . . . 33 106 9. Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 107 9.1. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 33 108 9.2. TLS Client . . . . . . . . . . . . . . . . . . . . . . . 34 109 9.3. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 35 110 9.4. Auditing . . . . . . . . . . . . . . . . . . . . . . . . 36 111 9.4.1. Verifying an inclusion proof . . . . . . . . . . . . 37 112 9.4.2. Verifying consistency between two STHs . . . . . . . 37 113 9.4.3. Verifying root hash given entries . . . . . . . . . . 38 114 10. Algorithm Agility . . . . . . . . . . . . . . . . . . . . . . 39 115 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 116 11.1. TLS Extension Type . . . . . . . . . . . . . . . . . . . 39 117 11.2. Hash Algorithms . . . . . . . . . . . . . . . . . . . . 39 118 11.3. TransItem Extensions . . . . . . . . . . . . . . . . . . 39 119 11.4. SCT Extensions . . . . . . . . . . . . . . . . . . . . . 40 120 11.5. STH Extensions . . . . . . . . . . . . . . . . . . . . . 40 121 12. Security Considerations . . . . . . . . . . . . . . . . . . . 40 122 12.1. Misissued Certificates . . . . . . . . . . . . . . . . . 41 123 12.2. Detection of Misissue . . . . . . . . . . . . . . . . . 41 124 12.3. Redaction of Public Domain Name Labels . . . . . . . . . 41 125 12.4. Misbehaving Logs . . . . . . . . . . . . . . . . . . . . 41 126 12.5. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . 42 127 13. Efficiency Considerations . . . . . . . . . . . . . . . . . . 42 128 14. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 43 129 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 130 15.1. Normative References . . . . . . . . . . . . . . . . . . 43 131 15.2. Informative References . . . . . . . . . . . . . . . . . 45 132 Appendix A. TransItemV1 . . . . . . . . . . . . . . . . . . . . 46 133 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 135 1. Introduction 137 Certificate transparency aims to mitigate the problem of misissued 138 certificates by providing publicly auditable, append-only, untrusted 139 logs of all issued certificates. The logs are publicly auditable so 140 that it is possible for anyone to verify the correctness of each log 141 and to monitor when new certificates are added to it. The logs do 142 not themselves prevent misissue, but they ensure that interested 143 parties (particularly those named in certificates) can detect such 144 misissuance. Note that this is a general mechanism, but in this 145 document, we only describe its use for public TLS server certificates 146 issued by public certification authorities (CAs). 148 Each log consists of certificate chains, which can be submitted by 149 anyone. It is expected that public CAs will contribute all their 150 newly issued certificates to one or more logs, however certificate 151 holders can also contribute their own certificate chains, as can 152 third parties. In order to avoid logs being rendered useless by 153 submitting large numbers of spurious certificates, it is required 154 that each chain is rooted in a CA certificate accepted by the log. 155 When a chain is submitted to a log, a signed timestamp is returned, 156 which can later be used to provide evidence to TLS clients that the 157 chain has been submitted. TLS clients can thus require that all 158 certificates they accept as valid are accompanied by signed 159 timestamps. 161 Those who are concerned about misissue can monitor the logs, asking 162 them regularly for all new entries, and can thus check whether 163 domains they are responsible for have had certificates issued that 164 they did not expect. What they do with this information, 165 particularly when they find that a misissuance has happened, is 166 beyond the scope of this document, but broadly speaking, they can 167 invoke existing business mechanisms for dealing with misissued 168 certificates, such as working with the CA to get the certificate 169 revoked, or with maintainers of trust anchor lists to get the CA 170 removed. Of course, anyone who wants can monitor the logs and, if 171 they believe a certificate is incorrectly issued, take action as they 172 see fit. 174 Similarly, those who have seen signed timestamps from a particular 175 log can later demand a proof of inclusion from that log. If the log 176 is unable to provide this (or, indeed, if the corresponding 177 certificate is absent from monitors' copies of that log), that is 178 evidence of the incorrect operation of the log. The checking 179 operation is asynchronous to allow TLS connections to proceed without 180 delay, despite network connectivity issues and the vagaries of 181 firewalls. 183 The append-only property of each log is technically achieved using 184 Merkle Trees, which can be used to show that any particular instance 185 of the log is a superset of any particular previous instance. 186 Likewise, Merkle Trees avoid the need to blindly trust logs: if a log 187 attempts to show different things to different people, this can be 188 efficiently detected by comparing tree roots and consistency proofs. 190 Similarly, other misbehaviors of any log (e.g., issuing signed 191 timestamps for certificates they then don't log) can be efficiently 192 detected and proved to the world at large. 194 1.1. Requirements Language 196 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 197 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 198 document are to be interpreted as described in RFC 2119 [RFC2119]. 200 1.2. Data Structures 202 Data structures are defined according to the conventions laid out in 203 Section 4 of [RFC5246]. 205 2. Cryptographic Components 207 2.1. Merkle Hash Trees 209 Logs use a binary Merkle Hash Tree for efficient auditing. The 210 hashing algorithm used by each log is expected to be specified as 211 part of the metadata relating to that log. We have established a 212 registry of acceptable algorithms, see Section 11.2. The hashing 213 algorithm in use is referred to as HASH throughout this document and 214 the size of its output in bytes as HASH_SIZE. The input to the 215 Merkle Tree Hash is a list of data entries; these entries will be 216 hashed to form the leaves of the Merkle Hash Tree. The output is a 217 single HASH_SIZE Merkle Tree Hash. Given an ordered list of n 218 inputs, D[n] = {d(0), d(1), ..., d(n-1)}, the Merkle Tree Hash (MTH) 219 is thus defined as follows: 221 The hash of an empty list is the hash of an empty string: 223 MTH({}) = HASH(). 225 The hash of a list with one entry (also known as a leaf hash) is: 227 MTH({d(0)}) = HASH(0x00 || d(0)). 229 For n > 1, let k be the largest power of two smaller than n (i.e., k 230 < n <= 2k). The Merkle Tree Hash of an n-element list D[n] is then 231 defined recursively as 233 MTH(D[n]) = HASH(0x01 || MTH(D[0:k]) || MTH(D[k:n])), 235 where || is concatenation and D[k1:k2] denotes the list {d(k1), 236 d(k1+1),..., d(k2-1)} of length (k2 - k1). (Note that the hash 237 calculations for leaves and nodes differ. This domain separation is 238 required to give second preimage resistance.) 240 Note that we do not require the length of the input list to be a 241 power of two. The resulting Merkle Tree may thus not be balanced; 242 however, its shape is uniquely determined by the number of leaves. 243 (Note: This Merkle Tree is essentially the same as the history tree 244 [CrosbyWallach] proposal, except our definition handles non-full 245 trees differently.) 247 2.1.1. Merkle Inclusion Proofs 249 A Merkle inclusion proof for a leaf in a Merkle Hash Tree is the 250 shortest list of additional nodes in the Merkle Tree required to 251 compute the Merkle Tree Hash for that tree. Each node in the tree is 252 either a leaf node or is computed from the two nodes immediately 253 below it (i.e., towards the leaves). At each step up the tree 254 (towards the root), a node from the inclusion proof is combined with 255 the node computed so far. In other words, the inclusion proof 256 consists of the list of missing nodes required to compute the nodes 257 leading from a leaf to the root of the tree. If the root computed 258 from the inclusion proof matches the true root, then the inclusion 259 proof proves that the leaf exists in the tree. 261 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 262 d(n-1)}, the Merkle inclusion proof PATH(m, D[n]) for the (m+1)th 263 input d(m), 0 <= m < n, is defined as follows: 265 The proof for the single leaf in a tree with a one-element input list 266 D[1] = {d(0)} is empty: 268 PATH(0, {d(0)}) = {} 270 For n > 1, let k be the largest power of two smaller than n. The 271 proof for the (m+1)th element d(m) in a list of n > m elements is 272 then defined recursively as 274 PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n]) for m < k; and 276 PATH(m, D[n]) = PATH(m - k, D[k:n]) : MTH(D[0:k]) for m >= k, 278 where : is concatenation of lists and D[k1:k2] denotes the length (k2 279 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 281 2.1.2. Merkle Consistency Proofs 283 Merkle consistency proofs prove the append-only property of the tree. 284 A Merkle consistency proof for a Merkle Tree Hash MTH(D[n]) and a 285 previously advertised hash MTH(D[0:m]) of the first m leaves, m <= n, 286 is the list of nodes in the Merkle Tree required to verify that the 287 first m inputs D[0:m] are equal in both trees. Thus, a consistency 288 proof must contain a set of intermediate nodes (i.e., commitments to 289 inputs) sufficient to verify MTH(D[n]), such that (a subset of) the 290 same nodes can be used to verify MTH(D[0:m]). We define an algorithm 291 that outputs the (unique) minimal consistency proof. 293 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 294 d(n-1)}, the Merkle consistency proof PROOF(m, D[n]) for a previous 295 Merkle Tree Hash MTH(D[0:m]), 0 < m < n, is defined as: 297 PROOF(m, D[n]) = SUBPROOF(m, D[n], true) 299 The subproof for m = n is empty if m is the value for which PROOF was 300 originally requested (meaning that the subtree Merkle Tree Hash 301 MTH(D[0:m]) is known): 303 SUBPROOF(m, D[m], true) = {} 305 The subproof for m = n is the Merkle Tree Hash committing inputs 306 D[0:m]; otherwise: 308 SUBPROOF(m, D[m], false) = {MTH(D[m])} 310 For m < n, let k be the largest power of two smaller than n. The 311 subproof is then defined recursively. 313 If m <= k, the right subtree entries D[k:n] only exist in the current 314 tree. We prove that the left subtree entries D[0:k] are consistent 315 and add a commitment to D[k:n]: 317 SUBPROOF(m, D[n], b) = SUBPROOF(m, D[0:k], b) : MTH(D[k:n]) 319 If m > k, the left subtree entries D[0:k] are identical in both 320 trees. We prove that the right subtree entries D[k:n] are consistent 321 and add a commitment to D[0:k]. 323 SUBPROOF(m, D[n], b) = SUBPROOF(m - k, D[k:n], false) : MTH(D[0:k]) 325 Here, : is a concatenation of lists, and D[k1:k2] denotes the length 326 (k2 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 328 The number of nodes in the resulting proof is bounded above by 329 ceil(log2(n)) + 1. 331 2.1.3. Example 333 The binary Merkle Tree with 7 leaves: 335 hash 336 / \ 337 / \ 338 / \ 339 / \ 340 / \ 341 k l 342 / \ / \ 343 / \ / \ 344 / \ / \ 345 g h i j 346 / \ / \ / \ | 347 a b c d e f d6 348 | | | | | | 349 d0 d1 d2 d3 d4 d5 351 The inclusion proof for d0 is [b, h, l]. 353 The inclusion proof for d3 is [c, g, l]. 355 The inclusion proof for d4 is [f, j, k]. 357 The inclusion proof for d6 is [i, k]. 359 The same tree, built incrementally in four steps: 361 hash0 hash1=k 362 / \ / \ 363 / \ / \ 364 / \ / \ 365 g c g h 366 / \ | / \ / \ 367 a b d2 a b c d 368 | | | | | | 369 d0 d1 d0 d1 d2 d3 371 hash2 hash 372 / \ / \ 373 / \ / \ 374 / \ / \ 375 / \ / \ 376 / \ / \ 377 k i k l 378 / \ / \ / \ / \ 379 / \ e f / \ / \ 380 / \ | | / \ / \ 381 g h d4 d5 g h i j 382 / \ / \ / \ / \ / \ | 383 a b c d a b c d e f d6 384 | | | | | | | | | | 385 d0 d1 d2 d3 d0 d1 d2 d3 d4 d5 387 The consistency proof between hash0 and hash is PROOF(3, D[7]) = [c, 388 d, g, l]. c, g are used to verify hash0, and d, l are additionally 389 used to show hash is consistent with hash0. 391 The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l]. 392 hash can be verified using hash1=k and l. 394 The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i, 395 j, k]. k, i are used to verify hash2, and j is additionally used to 396 show hash is consistent with hash2. 398 2.1.4. Signatures 400 Various data structures are signed. A log MUST use either 401 deterministic ECDSA [RFC6979] using the NIST P-256 curve 402 (Section D.1.2.3 of the Digital Signature Standard [DSS]) and HMAC- 403 SHA256 or RSA signatures (RSASSA-PKCS1-v1_5 with SHA-256, Section 8.2 404 of [RFC3447]) using a key of at least 2048 bits. 406 3. Submitters 408 Submitters submit certificates or precertificates to logs for public 409 auditing, as described below. In order to enable attribution of each 410 logged certificate or precertificate to its issuer, each submission 411 MUST be accompanied by all additional certificates required to verify 412 the chain up to an accepted root certificate. The root certificate 413 itself MAY be omitted from the submission. 415 If a log accepts a submission, it will return a Signed Certificate 416 Timestamp (SCT) (see Section 5.6). The submitter SHOULD validate the 417 returned SCT as described in Section 9.2 if they understand its 418 format and they intend to use it directly in a TLS handshake or to 419 construct a certificate. 421 3.1. Certificates 423 Anyone can submit a certificate (Section 6.1) to a log. Since 424 certificates may not be accepted by TLS clients unless logged, it is 425 expected that certificate owners or their CAs will usually submit 426 them. 428 3.2. Precertificates 430 Alternatively, (root as well as intermediate) CAs may preannounce a 431 certificate prior to issuance by submitting a precertificate 432 (Section 6.2) that the log can use to create an entry that will be 433 valid against the issued certificate. The CA MAY incorporate the 434 returned SCT in the issued certificate. 436 A precertificate is a CMS [RFC5652] "signed-data" object that 437 conforms to the following requirements: 439 o It MUST be DER encoded. 441 o "SignedData.encapContentInfo.eContentType" MUST be the OID . 443 o "SignedData.encapContentInfo.eContent" MUST contain a 444 TBSCertificate [RFC5280], which MAY redact certain domain name 445 labels that will be present in the issued certificate (see 446 Section 4.2) and MUST NOT contain any SCTs, but which will be 447 otherwise identical to the TBSCertificate in the issued 448 certificate. 450 o "SignedData.signerInfos" MUST contain a signature from the same 451 (root or intermediate) CA that will ultimately issue the 452 certificate. This signature indicates the CA's intent to issue 453 the certificate. This intent is considered binding (i.e. 455 misissuance of the precertificate is considered equivalent to 456 misissuance of the certificate). (Note that, because of the 457 structure of CMS, the signature on the CMS object will not be a 458 valid X.509v3 signature and so cannot be used to construct a 459 certificate from the precertificate). 461 o "SignedData.certificates" SHOULD be omitted. 463 4. Private Domain Name Labels 465 Some regard some DNS domain name labels within their registered 466 domain space as private and security sensitive. Even though these 467 domains are often only accessible within the domain owner's private 468 network, it's common for them to be secured using publicly trusted 469 TLS server certificates. We define a mechanism to allow these 470 private labels to not appear in public logs. 472 4.1. Wildcard Certificates 474 A certificate containing a DNS-ID [RFC6125] of "*.example.com" could 475 be used to secure the domain "topsecret.example.com", without 476 revealing the string "topsecret" publicly. 478 Since TLS clients only match the wildcard character to the complete 479 leftmost label of the DNS domain name (see Section 6.4.3 of 480 [RFC6125]), this approach would not work for a DNS-ID such as 481 "top.secret.example.com". Also, wildcard certificates are prohibited 482 in some cases, such as Extended Validation Certificates 483 [EVSSLGuidelines]. 485 4.2. Redacting Domain Name Labels in Precertificates 487 When creating a precertificate, the CA MAY substitute one or more 488 labels in each DNS-ID with a corresponding number of "?" labels. 489 Every label to the left of a "?" label MUST also be redacted. For 490 example, if a certificate contains a DNS-ID of 491 "top.secret.example.com", then the corresponding precertificate could 492 contain "?.?.example.com" instead, but not "top.?.example.com" 493 instead. 495 Wildcard "*" labels MUST NOT be redacted. However, if the complete 496 leftmost label of a DNS-ID is "*", it is considered redacted for the 497 purposes of determining if the label to the right may be redacted. 498 For example, if a certificate contains a DNS-ID of 499 "*.top.secret.example.com", then the corresponding precertificate 500 could contain "*.?.?.example.com" instead, but not 501 "?.?.?.example.com" instead. 503 When a precertificate contains one or more redacted labels, a non- 504 critical extension (OID 1.3.6.1.4.1.11129.2.4.6, whose extnValue 505 OCTET STRING contains an ASN.1 SEQUENCE OF INTEGERs) MUST be added to 506 the corresponding certificate: the first INTEGER indicates the total 507 number of redacted labels and wildcard "*" labels in the 508 precertificate's first DNS-ID; the second INTEGER does the same for 509 the precertificate's second DNS-ID; etc. There MUST NOT be more 510 INTEGERs than there are DNS-IDs. If there are fewer INTEGERs than 511 there are DNS-IDs, the shortfall is made up by implicitly repeating 512 the last INTEGER. Each INTEGER MUST have a value of zero or more. 513 The purpose of this extension is to enable TLS clients to accurately 514 reconstruct the TBSCertificate component of the precertificate from 515 the certificate without having to perform any guesswork. 517 When a precertificate contains that extension and contains a CN-ID 518 [RFC6125], the CN-ID MUST match the first DNS-ID and have the same 519 labels redacted. TLS clients will use the first entry in the 520 SEQUENCE OF INTEGERs to reconstruct both the first DNS-ID and the CN- 521 ID. 523 4.3. Using a Name-Constrained Intermediate CA 525 An intermediate CA certificate or intermediate CA precertificate that 526 contains the critical or non-critical Name Constraints [RFC5280] 527 extension MAY be logged in place of end-entity certificates issued by 528 that intermediate CA, as long as all of the following conditions are 529 met: 531 o there MUST be a non-critical extension (OID 532 1.3.6.1.4.1.11129.2.4.7, whose extnValue OCTET STRING contains 533 ASN.1 NULL data (0x05 0x00)). This extension is an explicit 534 indication that it is acceptable to not log certificates issued by 535 this intermediate CA. 537 o permittedSubtrees MUST specify one or more dNSNames. 539 o excludedSubtrees MUST specify the entire IPv4 and IPv6 address 540 ranges. 542 Below is an example Name Constraints extension that meets these 543 conditions: 545 SEQUENCE { 546 OBJECT IDENTIFIER '2 5 29 30' 547 OCTET STRING, encapsulates { 548 SEQUENCE { 549 [0] { 550 SEQUENCE { 551 [2] 'example.com' 552 } 553 } 554 [1] { 555 SEQUENCE { 556 [7] 00 00 00 00 00 00 00 00 557 } 558 SEQUENCE { 559 [7] 560 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 561 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 562 } 563 } 564 } 565 } 566 } 568 5. Log Format and Operation 570 A log is a single, append-only Merkle Tree of submitted certificate 571 and precertificate entries. 573 When it receives a valid submission, the log MUST return an SCT that 574 corresponds to the submitted certificate or precertificate. If the 575 log has previously seen this valid submission, it MAY return the same 576 SCT as it returned before. (Note that if a certificate was 577 previously logged as a precertificate, then the precertificate's SCT 578 of type "precert_sct" would not be appropriate; instead, a fresh SCT 579 of type "x509_sct" should be generated). 581 An SCT is the log's promise to incorporate the submitted entry in its 582 Merkle Tree no later than a fixed amount of time, known as the 583 Maximum Merge Delay (MMD), after the issuance of the SCT. 584 Periodically, the log MUST append all its new entries to its Merkle 585 Tree and sign the root of the tree. This provides auditable evidence 586 that the log kept all its promises. 588 Log operators MUST NOT impose any conditions on retrieving or sharing 589 data from the log. 591 5.1. Accepting Submissions 593 Logs MUST verify that each submitted certificate or precertificate 594 has a valid signature chain to an accepted root certificate, using 595 the chain of intermediate CA certificates provided by the submitter. 596 Logs MUST accept certificates and precertificates that are fully 597 valid according to RFC 5280 [RFC5280] verification rules and are 598 submitted with such a chain. Logs MAY accept certificates and 599 precertificates that have expired, are not yet valid, have been 600 revoked, or are otherwise not fully valid according to RFC 5280 601 verification rules in order to accommodate quirks of CA certificate- 602 issuing software. However, logs MUST reject submissions without a 603 valid signature chain to an accepted root certificate. Logs MUST 604 also reject precertificates that do not conform to the requirements 605 in Section 3.2. 607 Logs SHOULD limit the length of chain they will accept. The maximum 608 chain length is specified in the log's metadata. 610 The log SHALL allow retrieval of its list of accepted root 611 certificates (see Section 6.8). This list might usefully be the 612 union of root certificates trusted by major browser vendors. 614 5.2. Log Entries 616 If a submission is accepted and an SCT issued, the accepting log MUST 617 store the entire chain used for verification. This chain MUST 618 include the certificate or precertificate itself, the zero or more 619 intermediate CA certificates provided by the submitter, and the root 620 certificate used to verify the chain (even if it was omitted from the 621 submission). The log MUST present this chain for auditing upon 622 request (see Section 6.7). This chain is required to prevent a CA 623 from avoiding blame by logging a partial or empty chain. 625 Each certificate entry in a log MUST include a "X509ChainEntry" 626 structure, and each precertificate entry MUST include a 627 "PrecertChainEntryV2" structure: 629 opaque ASN.1Cert<1..2^24-1>; 631 struct { 632 ASN.1Cert leaf_certificate; 633 ASN.1Cert certificate_chain<0..2^24-1>; 634 } X509ChainEntry; 636 opaque CMSPrecert<1..2^24-1>; 638 struct { 639 CMSPrecert pre_certificate; 640 ASN.1Cert precertificate_chain<1..2^24-1>; 641 } PrecertChainEntryV2; 643 "leaf_certificate" is a submitted certificate that has been accepted 644 by the log. 646 "certificate_chain" is a vector of 0 or more additional certificates 647 required to verify "leaf_certificate". The first certificate MUST 648 certify "leaf_certificate". Each following certificate MUST directly 649 certify the one preceding it. The final certificate MUST be a root 650 certificate accepted by the log. If "leaf_certificate" is a root 651 certificate, then this vector is empty. 653 "pre_certificate" is a submitted precertificate that has been 654 accepted by the log. 656 "precertificate_chain" is a vector of 1 or more additional 657 certificates required to verify "pre_certificate". The first 658 certificate MUST certify "pre_certificate". Each following 659 certificate MUST directly certify the one preceding it. The final 660 certificate MUST be a root certificate accepted by the log. 662 5.3. Log ID 664 Each log's operator allocates an OID for the purpose of uniquely 665 identifying that log. This OID is specified in the log's metadata. 666 Various data structures include the DER encoding of this OID, 667 excluding the ASN.1 tag and length bytes, in an opaque vector: 669 opaque LogID<2..127>; 671 Note that the ASN.1 length and the opaque vector length are identical 672 in size (1 byte) and value, so the DER encoding of the OID can be 673 reproduced simply by prepending an OBJECT IDENTIFIER tag (0x06) to 674 the opaque vector length and contents. 676 5.4. The TransItem Structure 677 Various data structures produced by logs are encapsulated in the 678 "TransItem" structure to ensure that the type and version of each one 679 is identified in a common fashion: 681 enum { 682 v1(0), v2(1), (255) 683 } Version; 685 enum { 686 x509_entry(0), precert_entry(1), x509_sct(2), precert_sct(3), 687 tree_head(4), signed_tree_head(5), consistency_proof(6), 688 inclusion_proof(7), (65535) 689 } TransType; 691 enum { 692 reserved(65535) 693 } ItemExtensionType; 695 struct { 696 ItemExtensionType item_extension_type; 697 opaque item_extension_data<0..2^16-1>; 698 } ItemExtension; 700 struct { 701 TransType type; 702 select (type) { 703 case x509_entry: TimestampedCertificateEntryDataV2; 704 case precert_entry: TimestampedCertificateEntryDataV2; 705 case x509_sct: SignedCertificateTimestampDataV2; 706 case precert_sct: SignedCertificateTimestampDataV2; 707 case tree_head: TreeHeadDataV2; 708 case signed_tree_head: SignedTreeHeadDataV2; 709 case consistency_proof: ConsistencyProofDataV2; 710 case inclusion_proof: InclusionProofDataV2; 711 } data; 712 ItemExtension item_extensions<0..2^16-1>; 713 } TransItemV2; 715 struct { 716 Version version; 717 select (version) { 718 case v1: TransItemV1; 719 case v2: TransItemV2; 720 } 721 } TransItem; 723 "version" is the earliest version of this protocol to which the 724 encapsulated data structure conforms. This document is v2. Note 725 that v1 [RFC6962] did not define "TransItem", but this document 726 specifies a mechanism (see Appendix A) for v2 implementations to 727 encapsulate existing v1 objects in the "TransItem" structure. Note 728 also that, since each "TransItem" object is individually versioned, 729 future revisions to this protocol could conceivably update some 730 encapsulated data structures without having to update all of them. 732 "type" is the type of the encapsulated data structure. (Note that 733 "TransType" combines the v1 type enumerations "LogEntryType", 734 "SignatureType" and "MerkleLeafType"). Future revisions of this 735 protocol may add new "TransType" values. 737 "data" is the encapsulated data structure. The various structures 738 named with the "DataV2" suffix are defined in later sections of this 739 document. 741 "item_extension_type" identifies a single extension from the IANA 742 registry in Section 11.3. 744 The interpretation of the "item_extension_data" field is determined 745 solely by the value of the "item_extension_type" field. Each 746 document that registers a new "item_extension_type" must describe how 747 to interpret the corresponding "item_extension_data". 749 "item_extensions" is a vector of 0 or more item extensions. This 750 vector MUST NOT include more than one extension with the same 751 "item_extension_type". The extensions in the vector MUST be ordered 752 by the value of the "item_extension_type" field, smallest value 753 first. 755 5.5. Merkle Tree Leaves 757 The leaves of a log's Merkle Tree correspond to the log's entries 758 (see Section 5.2). Each leaf is the leaf hash (Section 2.1) of a 759 "TransItem" structure of type "x509_entry" or "precert_entry", which 760 in this version (v2) encapsulates a 761 "TimestampedCertificateEntryDataV2" structure. Note that leaf hashes 762 are calculated as HASH(0x00 || TransItem), where the hashing 763 algorithm is specified in the log's metadata. 765 opaque TBSCertificate<1..2^24-1>; 767 struct { 768 uint64 timestamp; 769 opaque issuer_key_hash[HASH_SIZE]; 770 TBSCertificate tbs_certificate; 771 SctExtension sct_extensions<0..2^16-1>; 772 } TimestampedCertificateEntryDataV2; 774 "timestamp" is the NTP Time [RFC5905] at which the certificate or 775 precertificate was accepted by the log, measured in milliseconds 776 since the epoch (January 1, 1970, 00:00), ignoring leap seconds. 778 "issuer_key_hash" is the HASH of the public key of the CA that issued 779 the certificate or precertificate, calculated over the DER encoding 780 of the key represented as SubjectPublicKeyInfo [RFC5280]. This is 781 needed to bind the CA to the certificate or precertificate, making it 782 impossible for the corresponding SCT to be valid for any other 783 certificate or precertificate whose TBSCertificate matches 784 "tbs_certificate". 786 "tbs_certificate" is the DER encoded TBSCertificate from either the 787 "leaf_certificate" (in the case of an "X509ChainEntry") or the 788 "pre_certificate" (in the case of a "PrecertChainEntryV2"). (Note 789 that a precertificate's TBSCertificate can be reconstructed from the 790 issued certificate's TBSCertificate by redacting the domain name 791 labels indicated by the redacted labels extension, and deleting the 792 SCT list extension and redacted labels extension). 794 "sct_extensions" matches the SCT extensions of the corresponding SCT. 796 5.6. Signed Certificate Timestamp (SCT) 798 An SCT is a "TransItem" structure of type "x509_sct" or 799 "precert_sct", which in this version (v2) encapsulates a 800 "SignedCertificateTimestampDataV2" structure: 802 enum { 803 reserved(65535) 804 } SctExtensionType; 806 struct { 807 SctExtensionType sct_extension_type; 808 opaque sct_extension_data<0..2^16-1>; 809 } SctExtension; 811 struct { 812 LogID log_id; 813 uint64 timestamp; 814 SctExtension sct_extensions<0..2^16-1>; 815 digitally-signed struct { 816 TransItem timestamped_entry; 817 } signature; 818 } SignedCertificateTimestampDataV2; 820 "log_id" is this log's unique ID, encoded in an opaque vector as 821 described in Section 5.3. 823 "timestamp" is equal to the timestamp from the 824 "TimestampedCertificateEntryDataV2" structure encapsulated in the 825 "timestamped_entry". 827 "sct_extension_type" identifies a single extension from the IANA 828 registry in Section 11.4. At the time of writing, no extensions are 829 specified. 831 The interpretation of the "sct_extension_data" field is determined 832 solely by the value of the "sct_extension_type" field. Each document 833 that registers a new "sct_extension_type" must describe how to 834 interpret the corresponding "sct_extension_data". 836 "sct_extensions" is a vector of 0 or more SCT extensions. This 837 vector MUST NOT include more than one extension with the same 838 "sct_extension_type". The extensions in the vector MUST be ordered 839 by the value of the "sct_extension_type" field, smallest value first. 840 If an implementation sees an extension that it does not understand, 841 it SHOULD ignore that extension. Furthermore, an implementation MAY 842 choose to ignore any extension(s) that it does understand. 844 The encoding of the digitally-signed element is defined in [RFC5246]. 846 "timestamped_entry" is a "TransItem" structure that MUST be of type 847 "x509_entry" or "precert_entry" (see Section 5.5) and MUST have an 848 empty "item_extensions" vector. 850 5.7. Merkle Tree Head 852 The log stores information about its Merkle Tree in a "TransItem" 853 structure of type "tree_head", which in this version (v2) 854 encapsulates a "TreeHeadDataV2" structure: 856 opaque NodeHash[HASH_SIZE]; 858 struct { 859 uint64 timestamp; 860 uint64 tree_size; 861 NodeHash root_hash; 862 SthExtension sth_extensions<0..2^16-1>; 863 } TreeHeadDataV2; 865 "timestamp" is the current NTP Time [RFC5905], measured in 866 milliseconds since the epoch (January 1, 1970, 00:00), ignoring leap 867 seconds. 869 "tree_size" is the number of entries currently in the log's Merkle 870 Tree. 872 "root_hash" is the root of the Merkle Hash Tree. 874 "sth_extensions" matches the STH extensions of the corresponding STH. 876 5.8. Signed Tree Head (STH) 878 Periodically each log SHOULD sign its current tree head information 879 (see Section 5.7) to produce an STH. When a client requests a log's 880 latest STH (see Section 6.3), the log MUST return an STH that is no 881 older than the log's MMD. However, STHs could be used to mark 882 individual clients (by producing a new one for each query), so logs 883 MUST NOT produce them more frequently than is declared in their 884 metadata. In general, there is no need to produce a new STH unless 885 there are new entries in the log; however, in the unlikely event that 886 it receives no new submissions during an MMD period, the log SHALL 887 sign the same Merkle Tree Hash with a fresh timestamp. 889 An STH is a "TransItem" structure of type "signed_tree_head", which 890 in this version (v2) encapsulates a "SignedTreeHeadDataV2" structure: 892 enum { 893 reserved(65535) 894 } SthExtensionType; 896 struct { 897 SthExtensionType sth_extension_type; 898 opaque sth_extension_data<0..2^16-1>; 899 } SthExtension; 901 struct { 902 LogID log_id; 903 uint64 timestamp; 904 uint64 tree_size; 905 NodeHash root_hash; 906 SthExtension sth_extensions<0..2^16-1>; 907 digitally-signed struct { 908 TransItem merkle_tree_head; 909 } signature; 910 } SignedTreeHeadDataV2; 912 "log_id" is this log's unique ID, encoded in an opaque vector as 913 described in Section 5.3. 915 "timestamp" is equal to the timestamp from the "TreeHeadDataV2" 916 structure encapsulated in "merkle_tree_head". This timestamp MUST be 917 at least as recent as the most recent SCT timestamp in the tree. 918 Each subsequent timestamp MUST be more recent than the timestamp of 919 the previous update. 921 "tree_size" is equal to the tree size from the "TreeHeadDataV2" 922 structure encapsulated in "merkle_tree_head". 924 "root_hash" is equal to the root hash from the "TreeHeadDataV2" 925 structure encapsulated in "merkle_tree_head". 927 "sth_extension_type" identifies a single extension from the IANA 928 registry in Section 11.5. At the time of writing, no extensions are 929 specified. 931 The interpretation of the "sth_extension_data" field is determined 932 solely by the value of the "sth_extension_type" field. Each document 933 that registers a new "sth_extension_type" must describe how to 934 interpret the corresponding "sth_extension_data". 936 "sth_extensions" is a vector of 0 or more STH extensions. This 937 vector MUST NOT include more than one extension with the same 938 "sth_extension_type". The extensions in the vector MUST be ordered 939 by the value of the "sth_extension_type" field, smallest value first. 940 If an implementation sees an extension that it does not understand, 941 it SHOULD ignore that extension. Furthermore, an implementation MAY 942 choose to ignore any extension(s) that it does understand. 944 "merkle_tree_head" is a "TransItem" structure that MUST be of type 945 "tree_head" (see Section 5.7) and MUST have an empty 946 "item_extensions" vector. 948 5.9. Merkle Consistency Proofs 950 To prepare a Merkle Consistency Proof for distribution to clients, 951 the log produces a "TransItem" structure of type "consistency_proof", 952 which in this version (v2) encapsulates a "ConsistencyProofDataV2" 953 structure: 955 struct { 956 LogID log_id; 957 uint64 tree_size_1; 958 uint64 tree_size_2; 959 NodeHash consistency_path<1..2^8-1>; 960 } ConsistencyProofDataV2; 962 "log_id" is this log's unique ID, encoded in an opaque vector as 963 described in Section 5.3. 965 "tree_size_1" is the size of the older tree. 967 "tree_size_2" is the size of the newer tree. 969 "consistency_path" is a vector of Merkle Tree nodes proving the 970 consistency of two STHs. 972 5.10. Merkle Inclusion Proofs 974 To prepare a Merkle Inclusion Proof for distribution to clients, the 975 log produces a "TransItem" structure of type "inclusion_proof", which 976 in this version (v2) encapsulates an "InclusionProofDataV2" 977 structure: 979 struct { 980 LogID log_id; 981 uint64 tree_size; 982 uint64 leaf_index; 983 NodeHash inclusion_path<1..2^8-1>; 984 } InclusionProofDataV2; 986 "log_id" is this log's unique ID, encoded in an opaque vector as 987 described in Section 5.3. 989 "tree_size" is the size of the tree on which this inclusion proof is 990 based. 992 "leaf_index" is the 0-based index of the log entry corresponding to 993 this inclusion proof. 995 "inclusion_path" is a vector of Merkle Tree nodes proving the 996 inclusion of the chosen certificate or precertificate. 998 6. Log Client Messages 1000 Messages are sent as HTTPS GET or POST requests. Parameters for 1001 POSTs and all responses are encoded as JavaScript Object Notation 1002 (JSON) objects [RFC4627]. Parameters for GETs are encoded as order- 1003 independent key/value URL parameters, using the "application/x-www- 1004 form-urlencoded" format described in the "HTML 4.01 Specification" 1005 [HTML401]. Binary data is base64 encoded [RFC4648] as specified in 1006 the individual messages. 1008 Note that JSON objects and URL parameters may contain fields not 1009 specified here. These extra fields should be ignored. 1011 The prefix, which is part of the log's metadata, MAY 1012 include a path as well as a server name and a port. 1014 In practice, log servers may include multiple front-end machines. 1015 Since it is impractical to keep these machines in perfect sync, 1016 errors may occur that are caused by skew between the machines. Where 1017 such errors are possible, the front-end will return additional 1018 information (as specified below) making it possible for clients to 1019 make progress, if progress is possible. Front-ends MUST only serve 1020 data that is free of gaps (that is, for example, no front-end will 1021 respond with an STH unless it is also able to prove consistency from 1022 all log entries logged within that STH). 1024 For example, when a consistency proof between two STHs is requested, 1025 the front-end reached may not yet be aware of one or both STHs. In 1026 the case where it is unaware of both, it will return the latest STH 1027 it is aware of. Where it is aware of the first but not the second, 1028 it will return the latest STH it is aware of and a consistency proof 1029 from the first STH to the returned STH. The case where it knows the 1030 second but not the first should not arise (see the "no gaps" 1031 requirement above). 1033 If the log is unable to process a client's request, it MUST return an 1034 HTTP response code of 4xx/5xx (see [RFC2616]), and, in place of the 1035 responses outlined in the subsections below, the body SHOULD be a 1036 JSON structure containing at least the following field: 1038 error_message: A human-readable string describing the error which 1039 prevented the log from processing the request. 1041 In the case of a malformed request, the string SHOULD provide 1042 sufficient detail for the error to be rectified. 1044 error_code: An error code readable by the client. Some codes are 1045 generic and are detailed here. Others are detailed in the 1046 individual requests. Error codes are fixed text strings. 1048 not compliant The request is not compliant with this RFC. 1050 e.g. In response to a request of "/ct/v2/get- 1051 entries?start=100&end=99", the log would return a "400 Bad Request" 1052 response code with a body similar to the following: 1054 { 1055 "error_message": "'start' cannot be greater than 'end'", 1056 "error_code": "not compliant", 1057 } 1059 Clients SHOULD treat "500 Internal Server Error" and "503 Service 1060 Unavailable" responses as transient failures and MAY retry the same 1061 request without modification at a later date. Note that as per 1062 [RFC2616], in the case of a 503 response the log MAY include a 1063 "Retry-After:" header in order to request a minimum time for the 1064 client to wait before retrying the request. 1066 6.1. Add Chain to Log 1068 POST https:///ct/v2/add-chain 1070 Inputs: 1072 chain: An array of base64 encoded certificates. The first 1073 element is the certificate for which the submitter desires an 1074 SCT; the second chains to the first and so on to the last, 1075 which is either an accepted root certificate or a certificate 1076 that chains to an accepted root certificate. 1078 Outputs: 1080 sct: A base64 encoded "TransItem" of type "x509_sct", signed by 1081 this log, that corresponds to the submitted certificate. 1083 Error codes: 1085 unknown root The root of the chain is not one accepted by the 1086 log. 1088 bad chain The alleged chain is not actually a chain of 1089 certificates. 1091 bad certificate One or more certificates in the chain are not 1092 valid (e.g. not properly encoded). 1094 If the version of "sct" is not v2, then a v2 client may be unable to 1095 verify the signature. It MUST NOT construe this as an error. This 1096 is to avoid forcing an upgrade of compliant v2 clients that do not 1097 use the returned SCTs. 1099 If a log detects bad encoding in a chain that otherwise verifies 1100 correctly then the log MAY still log the certificate but SHOULD NOT 1101 return an SCT. It should instead return the "bad certificate" error. 1102 Logging the certificate is useful, because monitors (Section 9.3) can 1103 then detect these encoding errors, which may be accepted by some TLS 1104 clients. 1106 Note that not all certificate handling software is capable of 1107 detecting all encoding errors (e.g. some software will accept BER 1108 instead of DER encodings in certificates, or incorrect character 1109 encodings, even though these are technically incorrect) . 1111 6.2. Add PreCertChain to Log 1113 POST https:///ct/v2/add-pre-chain 1115 Inputs: 1117 precertificate: The base64 encoded precertificate. 1119 chain: An array of base64 encoded CA certificates. The first 1120 element is the signer of the precertificate; the second chains 1121 to the first and so on to the last, which is either an accepted 1122 root certificate or a certificate that chains to an accepted 1123 root certificate. 1125 Outputs: 1127 sct: A base64 encoded "TransItem" of type "precert_sct", signed 1128 by this log, that corresponds to the submitted precertificate. 1130 Errors are the same as in Section 6.1. 1132 6.3. Retrieve Latest Signed Tree Head 1134 GET https:///ct/v2/get-sth 1136 No inputs. 1138 Outputs: 1140 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1141 signed by this log, that is no older than the log's MMD. 1143 6.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads 1145 GET https:///ct/v2/get-sth-consistency 1147 Inputs: 1149 first: The tree_size of the older tree, in decimal. 1151 second: The tree_size of the newer tree, in decimal (optional). 1153 Both tree sizes must be from existing v2 STHs. However, because 1154 of skew, the receiving front-end may not know one or both of the 1155 existing STHs. If both are known, then only the "consistency" 1156 output is returned. If the first is known but the second is not 1157 (or has been omitted), then the latest known STH is returned, 1158 along with a consistency proof between the first STH and the 1159 latest. If neither are known, then the latest known STH is 1160 returned without a consistency proof. 1162 Outputs: 1164 consistency: A base64 encoded "TransItem" of type 1165 "consistency_proof", whose "tree_size_1" MUST match the "first" 1166 input. If the "sth" output is omitted, then "tree_size_2" MUST 1167 match the "second" input. 1169 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1170 signed by this log. 1172 Note that no signature is required for the "consistency" output as 1173 it is used to verify the consistency between two STHs, which are 1174 signed. 1176 Error codes: 1178 first unknown "first" is before the latest known STH but is not 1179 from an existing STH. 1181 second unknown "second" is before the latest known STH but is not 1182 from an existing STH. 1184 See Section 9.4.2 for an outline of how to use the "consistency" 1185 output. 1187 6.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash 1189 GET https:///ct/v2/get-proof-by-hash 1191 Inputs: 1193 hash: A base64 encoded v1 leaf hash. 1195 tree_size: The tree_size of the tree on which to base the proof, 1196 in decimal. 1198 The "hash" must be calculated as defined in Section 5.5. The 1199 "tree_size" must designate an existing v2 STH. Because of skew, 1200 the front-end may not know the requested STH. In that case, it 1201 will return the latest STH it knows, along with an inclusion proof 1202 to that STH. If the front-end knows the requested STH then only 1203 "inclusion" is returned. 1205 Outputs: 1207 inclusion: A base64 encoded "TransItem" of type "inclusion_proof" 1208 whose "inclusion_path" array of Merkle Tree nodes proves the 1209 inclusion of the chosen certificate in the selected STH. 1211 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1212 signed by this log. 1214 Note that no signature is required for the "inclusion" output as 1215 it is used to verify inclusion in the selected STH, which is 1216 signed. 1218 Error codes: 1220 hash unknown "hash" is not the hash of a known leaf (may be 1221 caused by skew or by a known certificate not yet merged). 1223 tree_size unknown "hash" is before the latest known STH but is 1224 not from an existing STH. 1226 See Section 9.4.1 for an outline of how to use the "inclusion" 1227 output. 1229 6.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and Consistency 1230 Proof by Leaf Hash 1232 GET https:///ct/v2/get-all-by-hash 1234 Inputs: 1236 hash: A base64 encoded v1 leaf hash. 1238 tree_size: The tree_size of the tree on which to base the proofs, 1239 in decimal. 1241 The "hash" must be calculated as defined in Section 5.5. The 1242 "tree_size" must designate an existing v2 STH. 1244 Because of skew, the front-end may not know the requested STH or 1245 the requested hash, which leads to a number of cases. 1247 latest STH < requested STH Return latest STH. 1249 latest STH > requested STH Return latest STH and a consistency 1250 proof between it and the requested STH (see Section 6.4). 1252 index of requested hash < latest STH Return "inclusion". 1254 Note that more than one case can be true, in which case the 1255 returned data is their concatenation. It is also possible for 1256 none to be true, in which case the front-end MUST return an empty 1257 response. 1259 Outputs: 1261 inclusion: A base64 encoded "TransItem" of type "inclusion_proof" 1262 whose "inclusion_path" array of Merkle Tree nodes proves the 1263 inclusion of the chosen certificate in the selected STH. 1265 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1266 signed by this log. 1268 consistency: A base64 encoded "TransItem" of type 1269 "consistency_proof" that proves the consistency of the 1270 requested STH and the returned STH. 1272 Note that no signature is required for the "inclusion" or 1273 "consistency" outputs as they are used to verify inclusion in and 1274 consistency of STHs, which are signed. 1276 Errors are the same as in Section 6.5. 1278 See Section 9.4.1 for an outline of how to use the "inclusion" 1279 output, and see Section 9.4.2 for an outline of how to use the 1280 "consistency" output. 1282 6.7. Retrieve Entries and STH from Log 1284 GET https:///ct/v2/get-entries 1286 Inputs: 1288 start: 0-based index of first entry to retrieve, in decimal. 1290 end: 0-based index of last entry to retrieve, in decimal. 1292 Outputs: 1294 entries: An array of objects, each consisting of 1296 leaf_input: The base64 encoded "TransItem" structure of type 1297 "x509_entry" or "precert_entry" (see Section 5.5). 1299 log_entry: The base64 encoded log entry (see Section 5.2). In 1300 the case of an "x509_entry" entry, this is the whole 1301 "X509ChainEntry"; and in the case of a "precert_entry", this 1302 is the whole "PrecertChainEntryV2". 1304 sct: A base64 encoded "TransItem" of type "x509_sct" or 1305 "precert_sct" corresponding to this log entry. Note that 1306 more than one SCT may have been returned for the same entry 1307 - only one of those is returned in this field. It may not 1308 be possible to retrieve others. 1310 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1311 signed by this log. 1313 Note that this message is not signed -- the "entries" data can be 1314 verified by constructing the Merkle Tree Hash corresponding to a 1315 retrieved STH. All leaves MUST be v1 or v2. However, a compliant v1 1316 client MUST NOT construe an unrecognized LogEntryType value as an 1317 error. This means it may be unable to parse some entries, but note 1318 that each client can inspect the entries it does recognize as well as 1319 verify the integrity of the data by treating unrecognized leaves as 1320 opaque input to the tree. 1322 The "start" and "end" parameters SHOULD be within the range 0 <= x < 1323 "tree_size" as returned by "get-sth" in Section 6.3. 1325 The "start" parameter MUST be less than or equal to the "end" 1326 parameter. 1328 Log servers MUST honor requests where 0 <= "start" < "tree_size" and 1329 "end" >= "tree_size" by returning a partial response covering only 1330 the valid entries in the specified range. "end" >= "tree_size" could 1331 be caused by skew. Note that the following restriction may also 1332 apply: 1334 Logs MAY restrict the number of entries that can be retrieved per 1335 "get-entries" request. If a client requests more than the permitted 1336 number of entries, the log SHALL return the maximum number of entries 1337 permissible. These entries SHALL be sequential beginning with the 1338 entry specified by "start". 1340 Because of skew, it is possible the log server will not have any 1341 entries between "start" and "end". In this case it MUST return an 1342 empty "entries" array. 1344 In any case, the log server MUST return the latest STH it knows 1345 about. 1347 See Section 9.4.3 for an outline of how to use a complete list of 1348 "leaf_input" entries to verify the "root_hash". 1350 6.8. Retrieve Accepted Root Certificates 1352 GET https:///ct/v2/get-roots 1354 No inputs. 1356 Outputs: 1358 certificates: An array of base64 encoded root certificates that 1359 are acceptable to the log. 1361 max_chain: If the server has chosen to limit the length of chains 1362 it accepts, this is the maximum number of certificates in the 1363 chain, in decimal. If there is no limit, this is omitted. 1365 7. TLS Servers 1367 TLS servers MUST use at least one of the three mechanisms listed 1368 below to present one or more SCTs or inclusion proofs from one or 1369 more logs to each TLS client during TLS handshakes, where each SCT or 1370 inclusion proof corresponds to the server certificate or to a name- 1371 constrained intermediate the server certificate chains to. Three 1372 mechanisms are provided because they have different tradeoffs. 1374 o A TLS extension (Section 7.4.1.4 of [RFC5246]) with type 1375 "transparency_info" (see Section 7.1). This mechanism allows TLS 1376 servers to participate in CT without the cooperation of CAs, 1377 unlike the other two mechanisms. It also allows SCTs and 1378 inclusion proofs to be updated on the fly. 1380 o An Online Certificate Status Protocol (OCSP) [RFC6960] response 1381 extension (see Section 8.1.1), where the OCSP response is provided 1382 in the "certificate_status" TLS extension (Section 8 of 1383 [RFC6066]), also known as OCSP stapling. This mechanism is 1384 already widely (but not universally) implemented. It also allows 1385 SCTs and inclusion proofs to be updated on the fly. 1387 o An X509v3 certificate extension (see Section 8.1.2). This 1388 mechanism allows the use of unmodified TLS servers, but the SCTs 1389 and inclusion proofs cannot be updated on the fly. Since the logs 1390 from where the SCTs and inclusion proofs originated won't 1391 necessarily be accepted by TLS clients for the full lifetime of 1392 the certificate, there is a risk that TLS clients will 1393 subsequently consider the certificate to be non-compliant and in 1394 need of re-issuance. 1396 TLS servers SHOULD send SCTs or inclusion proofs from multiple logs 1397 in case one or more logs are not acceptable to the TLS client (for 1398 example, if a log has been struck off for misbehavior, has had a key 1399 compromise, or is not known to the TLS client). 1401 Multiple SCTs, inclusion proofs, and indeed "TransItem" structures of 1402 any type, are combined into a list as follows: 1404 opaque SerializedTransItem<1..2^16-1>; 1406 struct { 1407 SerializedTransItem trans_item_list<1..2^16-1>; 1408 } TransItemList; 1410 Here, "SerializedTransItem" is an opaque byte string that contains 1411 the serialized "TransItem" structure. This encoding ensures that TLS 1412 clients can decode each "TransItem" individually (so, for example, if 1413 there is a version upgrade, out-of-date clients can still parse old 1414 "TransItem" structures while skipping over new "TransItem" structures 1415 whose versions they don't understand). 1417 TODO: We need to define at least one ItemExtensionType for 1418 associating SCT and inclusion proof TransItems with the relevant 1419 certificate. 1421 7.1. TLS Extension 1423 If a TLS client includes the "transparency_info" extension type in 1424 the ClientHello, the TLS server MAY include the "transparency_info" 1425 extension in the ServerHello with "extension_data" set to a 1426 "TransItemList". The TLS server is not expected to process or 1427 include this extension when a TLS session is resumed, since session 1428 resumption uses the original session information. 1430 8. Certification Authorities 1432 8.1. Transparency Information X.509v3 Extension 1434 One or more "TransItem" structures can be embedded in the 1435 Transparency Information X.509v3 extension, which has OID and 1436 SHOULD be non-critical. This extension can be included in OCSP 1437 responses and certificates. Since RFC5280 requires the "extnValue" 1438 field (an OCTET STRING) of each X.509v3 extension to include the DER 1439 encoding of an ASN.1 value, we cannot embed a "TransItemList" 1440 directly. Instead, we have to wrap it inside an additional OCTET 1441 STRING, which we then put into the "extnValue" field: 1443 TransparencyInformationSyntax ::= OCTET STRING 1445 "TransparencyInformationSyntax" contains a "TransItemList". 1447 8.1.1. OCSP Response Extension 1449 A certification authority may include a Transparency Information 1450 X.509v3 extension in the "singleExtensions" of a "SingleResponse" in 1451 an OCSP response. The included SCTs or inclusion proofs MUST be for 1452 the certificate identified by the "certID" of that "SingleResponse", 1453 or for a precertificate that corresponds to that certificate, or for 1454 a name-constrained intermediate to which that certificate chains. 1456 8.1.2. Certificate Extension 1458 A certification authority may include a Transparency Information 1459 X.509v3 extension in a certificate. Any included SCTs or inclusion 1460 proofs MUST be either for a precertificate that corresponds to this 1461 certificate, or for a name-constrained intermediate to which this 1462 certificate chains. 1464 9. Clients 1466 There are various different functions clients of logs might perform. 1467 We describe here some typical clients and how they should function. 1468 Any inconsistency may be used as evidence that a log has not behaved 1469 correctly, and the signatures on the data structures prevent the log 1470 from denying that misbehavior. 1472 All clients need various metadata in order to communicate with logs 1473 and verify their responses. This metadata is described below, but 1474 note that this document does not describe how the metadata is 1475 obtained, which is implementation dependent (see, for example, 1476 [Chromium.Policy]). 1478 Clients should somehow exchange STHs they see, or make them available 1479 for scrutiny, in order to ensure that they all have a consistent 1480 view. The exact mechanisms will be in separate documents, but it is 1481 expected there will be a variety. 1483 9.1. Metadata 1485 In order to communicate with and verify a log, clients need metadata 1486 about the log. 1488 Base URL: The URL to substitute for in Section 6. 1490 Hash Algorithm The hash algorithm used for the Merkle Tree (see 1491 Section 11.2). 1493 Signing Algorithm The signing algorithm used (see Section 2.1.4). 1495 Public Key The public key used to verify signatures generated by the 1496 log. A log MUST NOT use the same keypair as any other log. 1498 Log ID The OID that uniquely identifies the log. 1500 Maximum Merge Delay The MMD the log has committed to. 1502 Version The version of the protocol supported by the log (currently 1503 1 or 2). 1505 Maximum Chain Length The longest chain submission the log is willing 1506 to accept, if the log chose to limit it. 1508 STH Frequency Count The maximum number of STHs the log may produce 1509 in any period equal to the "Maximum Merge Delay" (see 1510 Section 5.8). 1512 Final STH If a log has been closed down (i.e. no longer accepts new 1513 entries), existing entries may still be valid. In this case, the 1514 client should know the final valid STH in the log to ensure no new 1515 entries can be added without detection. 1517 [JSON.Metadata] is an example of a metadata format which includes the 1518 above elements. 1520 9.2. TLS Client 1522 TLS clients receive SCTs alongside or in certificates, either for the 1523 server certificate itself or for a name-constrained intermediate the 1524 server certificate chains to. TLS clients MUST implement all of the 1525 three mechanisms by which TLS servers may present SCTs (see 1526 Section 7). TLS clients that support the "transparency_info" TLS 1527 extension SHOULD include it in ClientHello messages, with 1528 "extension_data" set to . 1530 TODO: What should the TLS client communicate in the extension_data? 1531 Version(s) of CT that it supports? Certain types of TransItem that 1532 it can handle? Whether or not it wants to gossip? 1534 In addition to normal validation of the certificate and its chain, 1535 TLS clients SHOULD validate each supplied SCT by computing the 1536 signature input from the SCT data as well as the certificate and 1537 verifying the signature, using the corresponding log's public key. 1538 TLS clients MUST reject SCTs whose timestamp is in the future. 1540 TLS clients SHOULD also validate each supplied inclusion proof (see 1541 Section 9.4.1), in order to audit the log. If no inclusion proof was 1542 supplied by the TLS server, the TLS client MAY request one directly 1543 from the corresponding log using "get-proof-by-hash" (Section 6.5) or 1544 "get-all-by-hash" (Section 6.6), and then validate it. 1546 To be considered compliant, a certificate MUST be accompanied by at 1547 least one valid SCT or at least one valid inclusion proof. A 1548 certificate not accompanied by any valid SCTs or any valid inclusion 1549 proofs MUST NOT be considered compliant by TLS clients. However, 1550 specifying the TLS clients' behavior once compliance or non- 1551 compliance has been determined (for example, whether a certificate 1552 should be rejected due to non-compliance) is outside the scope of 1553 this document. 1555 If the TLS client holds an STH that predates the SCT, it MAY, in the 1556 process of auditing, request a new STH from the log (Section 6.3), 1557 then verify it by requesting a consistency proof (Section 6.4). Note 1558 that if the TLS client uses "get-all-by-hash", then it will already 1559 have the new STH. 1561 9.3. Monitor 1563 Monitors watch logs and check that they behave correctly. Monitors 1564 may additionally watch for certificates of interest. For example, a 1565 monitor may be configured to report on all certificates that apply to 1566 a specific domain name when fetching new entries for consistency 1567 validation. 1569 A monitor needs to, at least, inspect every new entry in each log it 1570 watches. It may also want to keep copies of entire logs. In order 1571 to do this, it should follow these steps for each log: 1573 1. Fetch the current STH (Section 6.3). 1575 2. Verify the STH signature. 1577 3. Fetch all the entries in the tree corresponding to the STH 1578 (Section 6.7). 1580 4. Confirm that the tree made from the fetched entries produces the 1581 same hash as that in the STH. 1583 5. Fetch the current STH (Section 6.3). Repeat until the STH 1584 changes. 1586 6. Verify the STH signature. 1588 7. Fetch all the new entries in the tree corresponding to the STH 1589 (Section 6.7). If they remain unavailable for an extended 1590 period, then this should be viewed as misbehavior on the part of 1591 the log. 1593 8. Either: 1595 1. Verify that the updated list of all entries generates a tree 1596 with the same hash as the new STH. 1598 Or, if it is not keeping all log entries: 1600 1. Fetch a consistency proof for the new STH with the previous 1601 STH (Section 6.4). 1603 2. Verify the consistency proof. 1605 3. Verify that the new entries generate the corresponding 1606 elements in the consistency proof. 1608 9. Go to Step 5. 1610 9.4. Auditing 1612 Auditing is taking partial information about a log as input and 1613 verifying that this information is consistent with other partial 1614 information held. All clients described above may perform auditing 1615 as an additional function. The action taken by the client if audit 1616 fails is not specified, but note that in general if audit fails, the 1617 client is in possession of signed proof of the log's misbehavior. 1619 A monitor (Section 9.3) can audit by verifying the consistency of 1620 STHs it receives, ensure that each entry can be fetched and that the 1621 STH is indeed the result of making a tree from all fetched entries. 1623 A TLS client (Section 9.2) can audit by verifying an SCT against any 1624 STH dated after the SCT timestamp + the Maximum Merge Delay by 1625 requesting a Merkle inclusion proof (Section 6.5). It can also 1626 verify that the SCT corresponds to the certificate it arrived with 1627 (i.e. the log entry is that certificate, is a precertificate for that 1628 certificate or is an appropriate name-constrained intermediate [see 1629 Section 4.3]). 1631 The following algorithm outlines may be useful for clients that wish 1632 to perform various audit operations. 1634 9.4.1. Verifying an inclusion proof 1636 When a client has received a "TransItem" of type "inclusion_proof" 1637 and wishes to verify inclusion of an input "hash" for an STH with a 1638 given "tree_size" and "root_hash", the following algorithm may be 1639 used to prove the "hash" was included in the "root_hash": 1641 1. Set "fn" to "leaf_index" and "sn" to "tree_size - 1". 1643 2. Set "r" to "hash". 1645 3. For each value "p" in the "inclusion_path" array: 1647 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1649 1. Set "r" to "HASH(0x01 || p || r)" 1651 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1652 equally until either "LSB(fn)" is set or "fn" is "0". 1654 Otherwise: 1656 Set "r" to "HASH(0x01 || r || p)" 1658 Finally, right-shift both "fn" and "sn" one time. 1660 4. Compare "r" against the "root_hash". If they are equal, then the 1661 log has proven the inclusion of "hash". 1663 9.4.2. Verifying consistency between two STHs 1665 When a client has an STH "first_hash" for tree size "first", an STH 1666 "second_hash" for tree size "second" where "0 < first < second", and 1667 has received a "TransItem" of type "consistency_proof" that they wish 1668 to use to verify both hashes, the following algorithm may be used: 1670 1. If "first" is an exact power of 2, then prepend "first_hash" to 1671 the "consistency_path" array. 1673 2. Set "fn" to "first - 1" and "sn" to "second - 1". 1675 3. If "LSB(fn)" is set, then right-shift both "fn" and "sn" equally 1676 until "LSB(fn)" is not set. 1678 4. Set both "fr" and "sr" to the first value in the 1679 "consistency_path" array. 1681 5. For each subsequent value "c" in the "consistency_path" array: 1683 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1685 1. Set "fr" to "HASH(0x01 || c || fr)" 1686 Set "sr" to "HASH(0x01 || c || sr)" 1688 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1689 equally until either "LSB(fn)" is set or "fn" is "0". 1691 Otherwise: 1693 Set "sr" to "HASH(0x01 || sr || c)" 1695 Finally, right-shift both "fn" and "sn" one time. 1697 6. After completing iterating through the "consistency_path" array 1698 as described above, verify that the "fr" calculated is equal to 1699 the "first_hash" supplied and that the "sr" calculated is equal 1700 to the "second_hash" supplied. 1702 9.4.3. Verifying root hash given entries 1704 When a client has a complete list of leaf input "entries" from "0" up 1705 to "tree_size - 1" and wishes to verify this list against an STH 1706 "root_hash" returned by the log for the same "tree_size", the 1707 following algorithm may be used: 1709 1. Set "stack" to an empty stack. 1711 2. For each "i" from "0" up to "tree_size - 1": 1713 1. Push "HASH(0x00 || entries[i])" to "stack". 1715 2. Set "merge_count" to the lowest value ("0" included) such 1716 that "LSB(i >> merge_count)" is not set. In other words, set 1717 "merge_count" to the number of consecutive "1"s found 1718 starting at the least significant bit of "i". 1720 3. Repeat "merge_count" times: 1722 1. Pop "right" from "stack". 1724 2. Pop "left" from "stack". 1726 3. Push "HASH(0x01 || left || right)" to "stack". 1728 3. If there is more than one element in the "stack", repeat the same 1729 merge procedure (Step 2.3 above) until only a single element 1730 remains. 1732 4. The remaining element in "stack" is the Merkle Tree hash for the 1733 given "tree_size" and should be compared by equality against the 1734 supplied "root_hash". 1736 10. Algorithm Agility 1738 It is not possible for a log to change any of its algorithms part way 1739 through its lifetime. If it should become necessary to deprecate an 1740 algorithm used by a live log, then the log should be frozen as 1741 specified in Section 9.1 and a new log should be started. If 1742 necessary, the new log can contain existing entries from the frozen 1743 log, which monitors can verify are an exact match. 1745 11. IANA Considerations 1747 11.1. TLS Extension Type 1749 IANA is asked to allocate an RFC 5246 ExtensionType value for the 1750 "transparency_info" TLS extension. IANA should update this extension 1751 type to point at this document. 1753 11.2. Hash Algorithms 1755 IANA is asked to establish a registry of hash values, initially 1756 consisting of: 1758 +-------+----------------------+ 1759 | Index | Hash | 1760 +-------+----------------------+ 1761 | 0 | SHA-256 [FIPS.180-4] | 1762 +-------+----------------------+ 1764 11.3. TransItem Extensions 1766 IANA is asked to establish a registry of TransItem extensions, 1767 initially consisting of: 1769 +-------+-----------+ 1770 | Type | Extension | 1771 +-------+-----------+ 1772 | 65535 | reserved | 1773 +-------+-----------+ 1775 TBD: policy for adding to the registry 1777 11.4. SCT Extensions 1779 IANA is asked to establish a registry of SCT extensions, initially 1780 consisting of: 1782 +-------+-----------+ 1783 | Type | Extension | 1784 +-------+-----------+ 1785 | 65535 | reserved | 1786 +-------+-----------+ 1788 TBD: policy for adding to the registry 1790 11.5. STH Extensions 1792 IANA is asked to establish a registry of STH extensions, initially 1793 consisting of: 1795 +-------+-----------+ 1796 | Type | Extension | 1797 +-------+-----------+ 1798 | 65535 | reserved | 1799 +-------+-----------+ 1801 TBD: policy for adding to the registry 1803 12. Security Considerations 1805 With CAs, logs, and servers performing the actions described here, 1806 TLS clients can use logs and signed timestamps to reduce the 1807 likelihood that they will accept misissued certificates. If a server 1808 presents a valid signed timestamp for a certificate, then the client 1809 knows that a log has committed to publishing the certificate. From 1810 this, the client knows that the subject of the certificate has had 1811 some time to notice the misissue and take some action, such as asking 1812 a CA to revoke a misissued certificate, or that the log has 1813 misbehaved, which will be discovered when the SCT is audited. A 1814 signed timestamp is not a guarantee that the certificate is not 1815 misissued, since the subject of the certificate might not have 1816 checked the logs or the CA might have refused to revoke the 1817 certificate. 1819 In addition, if TLS clients will not accept unlogged certificates, 1820 then site owners will have a greater incentive to submit certificates 1821 to logs, possibly with the assistance of their CA, increasing the 1822 overall transparency of the system. 1824 12.1. Misissued Certificates 1826 Misissued certificates that have not been publicly logged, and thus 1827 do not have a valid SCT, are not considered compliant (so TLS clients 1828 may decide, for example, to reject them). Misissued certificates 1829 that do have an SCT from a log will appear in that public log within 1830 the Maximum Merge Delay, assuming the log is operating correctly. 1831 Thus, the maximum period of time during which a misissued certificate 1832 can be used without being available for audit is the MMD. 1834 12.2. Detection of Misissue 1836 The logs do not themselves detect misissued certificates; they rely 1837 instead on interested parties, such as domain owners, to monitor them 1838 and take corrective action when a misissue is detected. 1840 12.3. Redaction of Public Domain Name Labels 1842 CAs SHOULD NOT redact domain name labels in precertificates such that 1843 the entirety of the domain space below the unredacted part of the 1844 domain name is not owned or controlled by a single entity (e.g. 1845 "?.com" and "?.co.uk" would both be problematic). Logs MUST NOT 1846 reject any precertificate that is overly redacted but which is 1847 otherwise considered compliant. It is expected that monitors will 1848 treat overly redacted precertificates as potentially misissued. TLS 1849 clients MAY reject a certificate whose corresponding precertificate 1850 would be overly redacted, perhaps using the same mechanism for 1851 determining whether a wildcard in a domain name of a certificate is 1852 too broad. 1854 12.4. Misbehaving Logs 1856 A log can misbehave in two ways: (1) by failing to incorporate a 1857 certificate with an SCT in the Merkle Tree within the MMD and (2) by 1858 violating its append-only property by presenting two different, 1859 conflicting views of the Merkle Tree at different times and/or to 1860 different parties. Both forms of violation will be promptly and 1861 publicly detectable. 1863 Violation of the MMD contract is detected by log clients requesting a 1864 Merkle audit proof for each observed SCT. These checks can be 1865 asynchronous and need only be done once per each certificate. In 1866 order to protect the clients' privacy, these checks need not reveal 1867 the exact certificate to the log. Clients can instead request the 1868 proof from a trusted auditor (since anyone can compute the audit 1869 proofs from the log) or request Merkle proofs for a batch of 1870 certificates around the SCT timestamp. 1872 Violation of the append-only property can be detected by clients 1873 comparing their instances of the Signed Tree Heads. As soon as two 1874 conflicting Signed Tree Heads for the same log are detected, this is 1875 cryptographic proof of that log's misbehavior. There are various 1876 ways this could be done, for example via gossip (see 1877 http://trac.tools.ietf.org/id/draft-linus-trans-gossip-00.txt) or 1878 peer-to-peer communications or by sending STHs to monitors (who could 1879 then directly check against their own copy of the relevant log). 1881 12.5. Multiple SCTs 1883 TLS servers may wish to offer multiple SCTs, each from a different 1884 log. 1886 o If a CA and a log collude, it is possible to temporarily hide 1887 misissuance from clients. Including SCTs from different logs 1888 makes it more difficult to mount this attack. 1890 o If a log misbehaves, a consequence may be that clients cease to 1891 trust it. Since the time an SCT may be in use can be considerable 1892 (several years is common in current practice when the SCT is 1893 embedded in a certificate), servers may wish to reduce the 1894 probability of their certificates being rejected as a result by 1895 including SCTs from different logs. 1897 o TLS clients may have policies related to the above risks requiring 1898 servers to present multiple SCTs. For example Chromium 1899 [Chromium.Log.Policy] currently requires multiple SCTs to be 1900 presented with EV certificates in order for the EV indicator to be 1901 shown. 1903 13. Efficiency Considerations 1905 The Merkle Tree design serves the purpose of keeping communication 1906 overhead low. 1908 Auditing logs for integrity does not require third parties to 1909 maintain a copy of each entire log. The Signed Tree Heads can be 1910 updated as new entries become available, without recomputing entire 1911 trees. Third-party auditors need only fetch the Merkle consistency 1912 proofs against a log's existing STH to efficiently verify the append- 1913 only property of updates to their Merkle Trees, without auditing the 1914 entire tree. 1916 14. Acknowledgements 1918 The authors would like to thank Erwann Abelea, Robin Alden, Al 1919 Cutter, Francis Dupont, Adam Eijdenberg, Stephen Farrell, Daniel Kahn 1920 Gillmor, Brad Hill, Jeff Hodges, Paul Hoffman, Jeffrey Hutzelman, 1921 Stephen Kent, SM, Alexey Melnikov, Linus Nordberg, Chris Palmer, 1922 Trevor Perrin, Pierre Phaneuf, Melinda Shore, Ryan Sleevi, Carl 1923 Wallace and Paul Wouters for their valuable contributions. 1925 15. References 1927 15.1. Normative References 1929 [DSS] National Institute of Standards and Technology, "Digital 1930 Signature Standard (DSS)", FIPS 186-3, June 2009, 1931 . 1934 [FIPS.180-4] 1935 National Institute of Standards and Technology, "Secure 1936 Hash Standard", FIPS PUB 180-4, March 2012, 1937 . 1940 [HTML401] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 1941 Specification", World Wide Web Consortium Recommendation 1942 REC-html401-19991224, December 1999, 1943 . 1945 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1946 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1947 RFC2119, March 1997, 1948 . 1950 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1951 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1952 Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/ 1953 RFC2616, June 1999, 1954 . 1956 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1957 Standards (PKCS) #1: RSA Cryptography Specifications 1958 Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 1959 2003, . 1961 [RFC4627] Crockford, D., "The application/json Media Type for 1962 JavaScript Object Notation (JSON)", RFC 4627, DOI 1963 10.17487/RFC4627, July 2006, 1964 . 1966 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1967 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1968 . 1970 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1971 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 1972 RFC5246, August 2008, 1973 . 1975 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1976 Housley, R., and W. Polk, "Internet X.509 Public Key 1977 Infrastructure Certificate and Certificate Revocation List 1978 (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, 1979 . 1981 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1982 RFC 5652, DOI 10.17487/RFC5652, September 2009, 1983 . 1985 [RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, 1986 "Network Time Protocol Version 4: Protocol and Algorithms 1987 Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010, 1988 . 1990 [RFC6066] Eastlake 3rd, D., "Transport Layer Security (TLS) 1991 Extensions: Extension Definitions", RFC 6066, DOI 1992 10.17487/RFC6066, January 2011, 1993 . 1995 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1996 Verification of Domain-Based Application Service Identity 1997 within Internet Public Key Infrastructure Using X.509 1998 (PKIX) Certificates in the Context of Transport Layer 1999 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, March 2000 2011, . 2002 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2003 Galperin, S., and C. Adams, "X.509 Internet Public Key 2004 Infrastructure Online Certificate Status Protocol - OCSP", 2005 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2006 . 2008 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 2009 Algorithm (DSA) and Elliptic Curve Digital Signature 2010 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 2011 2013, . 2013 15.2. Informative References 2015 [Chromium.Log.Policy] 2016 The Chromium Projects, "Chromium Certificate Transparency 2017 Log Policy", 2014, . 2020 [Chromium.Policy] 2021 The Chromium Projects, "Chromium Certificate 2022 Transparency", 2014, . 2025 [CrosbyWallach] 2026 Crosby, S. and D. Wallach, "Efficient Data Structures for 2027 Tamper-Evident Logging", Proceedings of the 18th USENIX 2028 Security Symposium, Montreal, August 2009, 2029 . 2032 [EVSSLGuidelines] 2033 CA/Browser Forum, "Guidelines For The Issuance And 2034 Management Of Extended Validation Certificates", 2007, 2035 . 2038 [JSON.Metadata] 2039 The Chromium Projects, "Chromium Log Metadata JSON 2040 Schema", 2014, . 2043 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 2044 Transparency", RFC 6962, DOI 10.17487/RFC6962, June 2013, 2045 . 2047 Appendix A. TransItemV1 2049 TODO: Finish writing this section. Or should it be in a separate 2050 document? 2052 struct { 2053 TransType type; 2054 select (type) { 2055 case x509_sct: SignedCertificateTimestampV1; 2056 case precert_sct: SignedCertificateTimestampV1; 2057 case signed_tree_head: SignedTreeHeadDataV1; 2058 case consistency_proof: ConsistencyProofDataV1; 2059 case inclusion_proof: InclusionProofDataV1; 2060 } data; 2061 } TransItemV1; 2063 opaque SHA256Hash[32]; 2065 struct { 2066 Version version = v1; 2067 SHA256Hash log_id; 2068 uint64 timestamp; 2069 SctExtensions extensions; 2070 digitally-signed struct { 2071 Version version = v1; 2072 uint8 signature_type = 0; /* "certificate_timestamp" */ 2073 uint64 timestamp; 2074 TransType type; /* x509_entry(0) or precert_entry(1) */ 2075 select (type) { 2076 case x509_entry: ASN.1Cert; 2077 case precert_entry: PreCert; 2078 } signed_entry; 2079 SctExtensions extensions; 2080 } signature; 2081 } SignedCertificateTimestampV1; 2083 struct { 2084 SHA256Hash log_id; 2085 uint64 timestamp; 2086 uint64 tree_size; 2087 SHA256Hash sha256_root_hash; 2088 digitally-signed struct { 2089 Version version = v1; 2090 uint8 signature_type = 1; /* "tree_hash" */ 2091 uint64 timestamp; 2092 uint64 tree_size; 2093 SHA256Hash sha256_root_hash; 2094 } signature; 2096 } SignedTreeHeadDataV1; 2098 struct { 2099 SHA256Hash log_id; 2100 uint64 tree_size_1; 2101 uint64 tree_size_2; 2102 SHA256Hash consistency_path<1..2^8-1>; 2103 } ConsistencyProofDataV1; 2105 struct { 2106 SHA256Hash log_id; 2107 uint64 tree_size; 2108 uint64 leaf_index; 2109 SHA256Hash inclusion_path<1..2^8-1>; 2110 } InclusionProofDataV1; 2112 Authors' Addresses 2114 Ben Laurie 2115 Google UK Ltd. 2117 EMail: benl@google.com 2119 Adam Langley 2120 Google Inc. 2122 EMail: agl@google.com 2124 Emilia Kasper 2125 Google Switzerland GmbH 2127 EMail: ekasper@google.com 2129 Eran Messeri 2130 Google UK Ltd. 2132 EMail: eranm@google.com 2134 Rob Stradling 2135 Comodo CA, Ltd. 2137 EMail: rob.stradling@comodo.com