idnits 2.17.1 draft-ietf-trans-rfc6962-bis-12.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 (January 28, 2016) is 3010 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 551 -- Looks like a reference, but probably isn't: '7' on line 556 -- Looks like a reference, but probably isn't: '0' on line 546 -- Looks like a reference, but probably isn't: '2' on line 548 -- Looks like a reference, but probably isn't: '32' on line 2060 -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTML401' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Downref: Normative reference to an Informational RFC: RFC 6979 -- Obsolete informational reference (is this intentional?): RFC 6962 (Obsoleted by RFC 9162) Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 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: July 31, 2016 E. Messeri 6 Google 7 R. Stradling 8 Comodo 9 January 28, 2016 11 Certificate Transparency 12 draft-ietf-trans-rfc6962-bis-12 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 July 31, 2016. 45 Copyright Notice 47 Copyright (c) 2016 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 Trust Anchors . . . . . . . . . . . . . 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. Signature Algorithms . . . . . . . . . . . . . . . . . . 40 120 11.5. SCT Extensions . . . . . . . . . . . . . . . . . . . . . 40 121 11.6. STH Extensions . . . . . . . . . . . . . . . . . . . . . 40 122 12. Security Considerations . . . . . . . . . . . . . . . . . . . 40 123 12.1. Misissued Certificates . . . . . . . . . . . . . . . . . 41 124 12.2. Detection of Misissue . . . . . . . . . . . . . . . . . 41 125 12.3. Redaction of Public Domain Name Labels . . . . . . . . . 41 126 12.4. Misbehaving Logs . . . . . . . . . . . . . . . . . . . . 41 127 12.5. Deterministic Signatures . . . . . . . . . . . . . . . . 42 128 12.6. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . 42 129 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 43 130 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 43 131 14.1. Normative References . . . . . . . . . . . . . . . . . . 43 132 14.2. Informative References . . . . . . . . . . . . . . . . . 44 133 Appendix A. TransItemV1 . . . . . . . . . . . . . . . . . . . . 46 135 1. Introduction 137 Certificate transparency aims to mitigate the problem of misissued 138 certificates by providing append-only logs of issued certificates. 139 The logs do not need to be trusted because they are publicly 140 auditable. Anyone may verify the correctness of each log and monitor 141 when new certificates are added to it. The logs do not themselves 142 prevent misissue, but they ensure that interested parties 143 (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 the 153 submission of large numbers of spurious certificates, it is required 154 that each chain ends with a trust anchor that is accepted by the log. 155 When a chain is accepted by 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 one of the 401 signature algorithms defined in the Section 11.4 section. 403 3. Submitters 405 Submitters submit certificates or precertificates to logs for public 406 auditing, as described below. In order to enable attribution of each 407 logged certificate or precertificate to its issuer, each submission 408 MUST be accompanied by all additional certificates required to verify 409 the chain up to an accepted trust anchor. The trust anchor (a root 410 or intermediate CA certificate) MAY be omitted from the submission. 412 If a log accepts a submission, it will return a Signed Certificate 413 Timestamp (SCT) (see Section 5.6). The submitter SHOULD validate the 414 returned SCT as described in Section 9.2 if they understand its 415 format and they intend to use it directly in a TLS handshake or to 416 construct a certificate. 418 3.1. Certificates 420 Anyone can submit a certificate (Section 6.1) to a log. Since 421 certificates may not be accepted by TLS clients unless logged, it is 422 expected that certificate owners or their CAs will usually submit 423 them. 425 3.2. Precertificates 427 Alternatively, (root as well as intermediate) CAs may preannounce a 428 certificate prior to issuance by submitting a precertificate 429 (Section 6.2) that the log can use to create an entry that will be 430 valid against the issued certificate. The CA MAY incorporate the 431 returned SCT in the issued certificate. 433 A precertificate is a CMS [RFC5652] "signed-data" object that 434 conforms to the following requirements: 436 o It MUST be DER encoded. 438 o "SignedData.encapContentInfo.eContentType" MUST be the OID . 440 o "SignedData.encapContentInfo.eContent" MUST contain a 441 TBSCertificate [RFC5280], which MAY redact certain domain name 442 labels that will be present in the issued certificate (see 443 Section 4.2) and MUST NOT contain any SCTs, but which will be 444 otherwise identical to the TBSCertificate in the issued 445 certificate. 447 o "SignedData.signerInfos" MUST contain a signature from the same 448 (root or intermediate) CA that will ultimately issue the 449 certificate. This signature indicates the CA's intent to issue 450 the certificate. This intent is considered binding (i.e. 452 misissuance of the precertificate is considered equivalent to 453 misissuance of the certificate). (Note that, because of the 454 structure of CMS, the signature on the CMS object will not be a 455 valid X.509v3 signature and so cannot be used to construct a 456 certificate from the precertificate). 458 o "SignedData.certificates" SHOULD be omitted. 460 4. Private Domain Name Labels 462 Some regard some DNS domain name labels within their registered 463 domain space as private and security sensitive. Even though these 464 domains are often only accessible within the domain owner's private 465 network, it's common for them to be secured using publicly trusted 466 TLS server certificates. We define a mechanism to allow these 467 private labels to not appear in public logs. 469 4.1. Wildcard Certificates 471 A certificate containing a DNS-ID [RFC6125] of "*.example.com" could 472 be used to secure the domain "topsecret.example.com", without 473 revealing the string "topsecret" publicly. 475 Since TLS clients only match the wildcard character to the complete 476 leftmost label of the DNS domain name (see Section 6.4.3 of 477 [RFC6125]), this approach would not work for a DNS-ID such as 478 "top.secret.example.com". Also, wildcard certificates are prohibited 479 in some cases, such as Extended Validation Certificates 480 [EVSSLGuidelines]. 482 4.2. Redacting Domain Name Labels in Precertificates 484 When creating a precertificate, the CA MAY substitute one or more 485 labels in each DNS-ID with a corresponding number of "?" labels. 486 Every label to the left of a "?" label MUST also be redacted. For 487 example, if a certificate contains a DNS-ID of 488 "top.secret.example.com", then the corresponding precertificate could 489 contain "?.?.example.com" instead, but not "top.?.example.com" 490 instead. 492 Wildcard "*" labels MUST NOT be redacted. However, if the complete 493 leftmost label of a DNS-ID is "*", it is considered redacted for the 494 purposes of determining if the label to the right may be redacted. 495 For example, if a certificate contains a DNS-ID of 496 "*.top.secret.example.com", then the corresponding precertificate 497 could contain "*.?.?.example.com" instead, but not 498 "?.?.?.example.com" instead. 500 When a precertificate contains one or more redacted labels, a non- 501 critical extension (OID 1.3.6.1.4.1.11129.2.4.6, whose extnValue 502 OCTET STRING contains an ASN.1 SEQUENCE OF INTEGERs) MUST be added to 503 the corresponding certificate: the first INTEGER indicates the total 504 number of redacted labels and wildcard "*" labels in the 505 precertificate's first DNS-ID; the second INTEGER does the same for 506 the precertificate's second DNS-ID; etc. There MUST NOT be more 507 INTEGERs than there are DNS-IDs. If there are fewer INTEGERs than 508 there are DNS-IDs, the shortfall is made up by implicitly repeating 509 the last INTEGER. Each INTEGER MUST have a value of zero or more. 510 The purpose of this extension is to enable TLS clients to accurately 511 reconstruct the TBSCertificate component of the precertificate from 512 the certificate without having to perform any guesswork. 514 When a precertificate contains that extension and contains a CN-ID 515 [RFC6125], the CN-ID MUST match the first DNS-ID and have the same 516 labels redacted. TLS clients will use the first entry in the 517 SEQUENCE OF INTEGERs to reconstruct both the first DNS-ID and the CN- 518 ID. 520 4.3. Using a Name-Constrained Intermediate CA 522 An intermediate CA certificate or intermediate CA precertificate that 523 contains the critical or non-critical Name Constraints [RFC5280] 524 extension MAY be logged in place of end-entity certificates issued by 525 that intermediate CA, as long as all of the following conditions are 526 met: 528 o there MUST be a non-critical extension (OID 529 1.3.6.1.4.1.11129.2.4.7, whose extnValue OCTET STRING contains 530 ASN.1 NULL data (0x05 0x00)). This extension is an explicit 531 indication that it is acceptable to not log certificates issued by 532 this intermediate CA. 534 o permittedSubtrees MUST specify one or more dNSNames. 536 o excludedSubtrees MUST specify the entire IPv4 and IPv6 address 537 ranges. 539 Below is an example Name Constraints extension that meets these 540 conditions: 542 SEQUENCE { 543 OBJECT IDENTIFIER '2 5 29 30' 544 OCTET STRING, encapsulates { 545 SEQUENCE { 546 [0] { 547 SEQUENCE { 548 [2] 'example.com' 549 } 550 } 551 [1] { 552 SEQUENCE { 553 [7] 00 00 00 00 00 00 00 00 554 } 555 SEQUENCE { 556 [7] 557 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 558 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 559 } 560 } 561 } 562 } 563 } 565 5. Log Format and Operation 567 A log is a single, append-only Merkle Tree of submitted certificate 568 and precertificate entries. 570 When it receives a valid submission, the log MUST return an SCT that 571 corresponds to the submitted certificate or precertificate. If the 572 log has previously seen this valid submission, it MAY return the same 573 SCT as it returned before. (Note that if a certificate was 574 previously logged as a precertificate, then the precertificate's SCT 575 of type "precert_sct" would not be appropriate; instead, a fresh SCT 576 of type "x509_sct" should be generated). 578 An SCT is the log's promise to incorporate the submitted entry in its 579 Merkle Tree no later than a fixed amount of time, known as the 580 Maximum Merge Delay (MMD), after the issuance of the SCT. 581 Periodically, the log MUST append all its new entries to its Merkle 582 Tree and sign the root of the tree. 584 Log operators MUST NOT impose any conditions on retrieving or sharing 585 data from the log. 587 5.1. Accepting Submissions 589 Logs MUST verify that each submitted certificate or precertificate 590 has a valid signature chain to an accepted trust anchor, using the 591 chain of intermediate CA certificates provided by the submitter. 592 Logs MUST accept certificates and precertificates that are fully 593 valid according to RFC 5280 [RFC5280] verification rules and are 594 submitted with such a chain. Logs MAY accept certificates and 595 precertificates that have expired, are not yet valid, have been 596 revoked, or are otherwise not fully valid according to RFC 5280 597 verification rules in order to accommodate quirks of CA certificate- 598 issuing software. However, logs MUST reject submissions without a 599 valid signature chain to an accepted trust anchor. Logs MUST also 600 reject precertificates that do not conform to the requirements in 601 Section 3.2. 603 Logs SHOULD limit the length of chain they will accept. The maximum 604 chain length is specified in the log's metadata. 606 The log SHALL allow retrieval of its list of accepted trust anchors 607 (see Section 6.8), each of which is a root or intermediate CA 608 certificate. This list might usefully be the union of root 609 certificates trusted by major browser vendors. 611 5.2. Log Entries 613 If a submission is accepted and an SCT issued, the accepting log MUST 614 store the entire chain used for verification. This chain MUST 615 include the certificate or precertificate itself, the zero or more 616 intermediate CA certificates provided by the submitter, and the trust 617 anchor used to verify the chain (even if it was omitted from the 618 submission). The log MUST present this chain for auditing upon 619 request (see Section 6.7). This chain is required to prevent a CA 620 from avoiding blame by logging a partial or empty chain. 622 Each certificate entry in a log MUST include a "X509ChainEntry" 623 structure, and each precertificate entry MUST include a 624 "PrecertChainEntryV2" structure: 626 opaque ASN.1Cert<1..2^24-1>; 628 struct { 629 ASN.1Cert leaf_certificate; 630 ASN.1Cert certificate_chain<0..2^24-1>; 631 } X509ChainEntry; 633 opaque CMSPrecert<1..2^24-1>; 635 struct { 636 CMSPrecert pre_certificate; 637 ASN.1Cert precertificate_chain<1..2^24-1>; 638 } PrecertChainEntryV2; 640 "leaf_certificate" is a submitted certificate that has been accepted 641 by the log. 643 "certificate_chain" is a vector of 0 or more additional certificates 644 required to verify "leaf_certificate". The first certificate MUST 645 certify "leaf_certificate". Each following certificate MUST directly 646 certify the one preceding it. The final certificate MUST be a trust 647 anchor accepted by the log. If "leaf_certificate" is an accepted 648 trust anchor, then this vector is empty. 650 "pre_certificate" is a submitted precertificate that has been 651 accepted by the log. 653 "precertificate_chain" is a vector of 1 or more additional 654 certificates required to verify "pre_certificate". The first 655 certificate MUST certify "pre_certificate". Each following 656 certificate MUST directly certify the one preceding it. The final 657 certificate MUST be a trust anchor accepted by the log. 659 5.3. Log ID 661 Each log's operator allocates an OID for the purpose of uniquely 662 identifying that log. This OID is specified in the log's metadata. 663 Various data structures include the DER encoding of this OID, 664 excluding the ASN.1 tag and length bytes, in an opaque vector: 666 opaque LogID<2..127>; 668 Note that the ASN.1 length and the opaque vector length are identical 669 in size (1 byte) and value, so the DER encoding of the OID can be 670 reproduced simply by prepending an OBJECT IDENTIFIER tag (0x06) to 671 the opaque vector length and contents. 673 5.4. The TransItem Structure 674 Various data structures produced by logs are encapsulated in the 675 "TransItem" structure to ensure that the type and version of each one 676 is identified in a common fashion: 678 enum { 679 v1(0), v2(1), (255) 680 } Version; 682 enum { 683 x509_entry(0), precert_entry(1), x509_sct(2), precert_sct(3), 684 tree_head(4), signed_tree_head(5), consistency_proof(6), 685 inclusion_proof(7), (65535) 686 } TransType; 688 enum { 689 reserved(65535) 690 } ItemExtensionType; 692 struct { 693 ItemExtensionType item_extension_type; 694 opaque item_extension_data<0..2^16-1>; 695 } ItemExtension; 697 struct { 698 TransType type; 699 select (type) { 700 case x509_entry: TimestampedCertificateEntryDataV2; 701 case precert_entry: TimestampedCertificateEntryDataV2; 702 case x509_sct: SignedCertificateTimestampDataV2; 703 case precert_sct: SignedCertificateTimestampDataV2; 704 case tree_head: TreeHeadDataV2; 705 case signed_tree_head: SignedTreeHeadDataV2; 706 case consistency_proof: ConsistencyProofDataV2; 707 case inclusion_proof: InclusionProofDataV2; 708 } data; 709 ItemExtension item_extensions<0..2^16-1>; 710 } TransItemV2; 712 struct { 713 Version version; 714 select (version) { 715 case v1: TransItemV1; 716 case v2: TransItemV2; 717 } 718 } TransItem; 720 "version" is the earliest version of this protocol to which the 721 encapsulated data structure conforms. This document is v2. Note 722 that v1 [RFC6962] did not define "TransItem", but this document 723 specifies a mechanism (see Appendix A) for v2 implementations to 724 encapsulate existing v1 objects in the "TransItem" structure. Note 725 also that, since each "TransItem" object is individually versioned, 726 future revisions to this protocol could conceivably update some 727 encapsulated data structures without having to update all of them. 729 "type" is the type of the encapsulated data structure. (Note that 730 "TransType" combines the v1 type enumerations "LogEntryType", 731 "SignatureType" and "MerkleLeafType"). Future revisions of this 732 protocol may add new "TransType" values. 734 "data" is the encapsulated data structure. The various structures 735 named with the "DataV2" suffix are defined in later sections of this 736 document. 738 "item_extension_type" identifies a single extension from the IANA 739 registry in Section 11.3. 741 The interpretation of the "item_extension_data" field is determined 742 solely by the value of the "item_extension_type" field. Each 743 document that registers a new "item_extension_type" must describe how 744 to interpret the corresponding "item_extension_data". 746 "item_extensions" is a vector of 0 or more item extensions. This 747 vector MUST NOT include more than one extension with the same 748 "item_extension_type". The extensions in the vector MUST be ordered 749 by the value of the "item_extension_type" field, smallest value 750 first. 752 5.5. Merkle Tree Leaves 754 The leaves of a log's Merkle Tree correspond to the log's entries 755 (see Section 5.2). Each leaf is the leaf hash (Section 2.1) of a 756 "TransItem" structure of type "x509_entry" or "precert_entry", which 757 in this version (v2) encapsulates a 758 "TimestampedCertificateEntryDataV2" structure. Note that leaf hashes 759 are calculated as HASH(0x00 || TransItem), where the hashing 760 algorithm is specified in the log's metadata. 762 opaque TBSCertificate<1..2^24-1>; 764 struct { 765 uint64 timestamp; 766 opaque issuer_key_hash[HASH_SIZE]; 767 TBSCertificate tbs_certificate; 768 SctExtension sct_extensions<0..2^16-1>; 769 } TimestampedCertificateEntryDataV2; 771 "timestamp" is the NTP Time [RFC5905] at which the certificate or 772 precertificate was accepted by the log, measured in milliseconds 773 since the epoch (January 1, 1970, 00:00), ignoring leap seconds. 775 "issuer_key_hash" is the HASH of the public key of the CA that issued 776 the certificate or precertificate, calculated over the DER encoding 777 of the key represented as SubjectPublicKeyInfo [RFC5280]. This is 778 needed to bind the CA to the certificate or precertificate, making it 779 impossible for the corresponding SCT to be valid for any other 780 certificate or precertificate whose TBSCertificate matches 781 "tbs_certificate". 783 "tbs_certificate" is the DER encoded TBSCertificate from either the 784 "leaf_certificate" (in the case of an "X509ChainEntry") or the 785 "pre_certificate" (in the case of a "PrecertChainEntryV2"). (Note 786 that a precertificate's TBSCertificate can be reconstructed from the 787 issued certificate's TBSCertificate by redacting the domain name 788 labels indicated by the redacted labels extension, and deleting the 789 SCT list extension and redacted labels extension). 791 "sct_extensions" matches the SCT extensions of the corresponding SCT. 793 5.6. Signed Certificate Timestamp (SCT) 795 An SCT is a "TransItem" structure of type "x509_sct" or 796 "precert_sct", which in this version (v2) encapsulates a 797 "SignedCertificateTimestampDataV2" structure: 799 enum { 800 reserved(65535) 801 } SctExtensionType; 803 struct { 804 SctExtensionType sct_extension_type; 805 opaque sct_extension_data<0..2^16-1>; 806 } SctExtension; 808 struct { 809 LogID log_id; 810 uint64 timestamp; 811 SctExtension sct_extensions<0..2^16-1>; 812 digitally-signed struct { 813 TransItem timestamped_entry; 814 } signature; 815 } SignedCertificateTimestampDataV2; 817 "log_id" is this log's unique ID, encoded in an opaque vector as 818 described in Section 5.3. 820 "timestamp" is equal to the timestamp from the 821 "TimestampedCertificateEntryDataV2" structure encapsulated in the 822 "timestamped_entry". 824 "sct_extension_type" identifies a single extension from the IANA 825 registry in Section 11.5. At the time of writing, no extensions are 826 specified. 828 The interpretation of the "sct_extension_data" field is determined 829 solely by the value of the "sct_extension_type" field. Each document 830 that registers a new "sct_extension_type" must describe how to 831 interpret the corresponding "sct_extension_data". 833 "sct_extensions" is a vector of 0 or more SCT extensions. This 834 vector MUST NOT include more than one extension with the same 835 "sct_extension_type". The extensions in the vector MUST be ordered 836 by the value of the "sct_extension_type" field, smallest value first. 837 If an implementation sees an extension that it does not understand, 838 it SHOULD ignore that extension. Furthermore, an implementation MAY 839 choose to ignore any extension(s) that it does understand. 841 The encoding of the digitally-signed element is defined in [RFC5246]. 843 "timestamped_entry" is a "TransItem" structure that MUST be of type 844 "x509_entry" or "precert_entry" (see Section 5.5) and MUST have an 845 empty "item_extensions" vector. 847 5.7. Merkle Tree Head 849 The log stores information about its Merkle Tree in a "TransItem" 850 structure of type "tree_head", which in this version (v2) 851 encapsulates a "TreeHeadDataV2" structure: 853 opaque NodeHash[HASH_SIZE]; 855 struct { 856 uint64 timestamp; 857 uint64 tree_size; 858 NodeHash root_hash; 859 SthExtension sth_extensions<0..2^16-1>; 860 } TreeHeadDataV2; 862 "timestamp" is the current NTP Time [RFC5905], measured in 863 milliseconds since the epoch (January 1, 1970, 00:00), ignoring leap 864 seconds. 866 "tree_size" is the number of entries currently in the log's Merkle 867 Tree. 869 "root_hash" is the root of the Merkle Hash Tree. 871 "sth_extensions" matches the STH extensions of the corresponding STH. 873 5.8. Signed Tree Head (STH) 875 Periodically each log SHOULD sign its current tree head information 876 (see Section 5.7) to produce an STH. When a client requests a log's 877 latest STH (see Section 6.3), the log MUST return an STH that is no 878 older than the log's MMD. However, STHs could be used to mark 879 individual clients (by producing a new one for each query), so logs 880 MUST NOT produce them more frequently than is declared in their 881 metadata. In general, there is no need to produce a new STH unless 882 there are new entries in the log; however, in the unlikely event that 883 it receives no new submissions during an MMD period, the log SHALL 884 sign the same Merkle Tree Hash with a fresh timestamp. 886 An STH is a "TransItem" structure of type "signed_tree_head", which 887 in this version (v2) encapsulates a "SignedTreeHeadDataV2" structure: 889 enum { 890 reserved(65535) 891 } SthExtensionType; 893 struct { 894 SthExtensionType sth_extension_type; 895 opaque sth_extension_data<0..2^16-1>; 896 } SthExtension; 898 struct { 899 LogID log_id; 900 uint64 timestamp; 901 uint64 tree_size; 902 NodeHash root_hash; 903 SthExtension sth_extensions<0..2^16-1>; 904 digitally-signed struct { 905 TransItem merkle_tree_head; 906 } signature; 907 } SignedTreeHeadDataV2; 909 "log_id" is this log's unique ID, encoded in an opaque vector as 910 described in Section 5.3. 912 "timestamp" is equal to the timestamp from the "TreeHeadDataV2" 913 structure encapsulated in "merkle_tree_head". This timestamp MUST be 914 at least as recent as the most recent SCT timestamp in the tree. 915 Each subsequent timestamp MUST be more recent than the timestamp of 916 the previous update. 918 "tree_size" is equal to the tree size from the "TreeHeadDataV2" 919 structure encapsulated in "merkle_tree_head". 921 "root_hash" is equal to the root hash from the "TreeHeadDataV2" 922 structure encapsulated in "merkle_tree_head". 924 "sth_extension_type" identifies a single extension from the IANA 925 registry in Section 11.6. At the time of writing, no extensions are 926 specified. 928 The interpretation of the "sth_extension_data" field is determined 929 solely by the value of the "sth_extension_type" field. Each document 930 that registers a new "sth_extension_type" must describe how to 931 interpret the corresponding "sth_extension_data". 933 "sth_extensions" is a vector of 0 or more STH extensions. This 934 vector MUST NOT include more than one extension with the same 935 "sth_extension_type". The extensions in the vector MUST be ordered 936 by the value of the "sth_extension_type" field, smallest value first. 937 If an implementation sees an extension that it does not understand, 938 it SHOULD ignore that extension. Furthermore, an implementation MAY 939 choose to ignore any extension(s) that it does understand. 941 "merkle_tree_head" is a "TransItem" structure that MUST be of type 942 "tree_head" (see Section 5.7) and MUST have an empty 943 "item_extensions" vector. 945 5.9. Merkle Consistency Proofs 947 To prepare a Merkle Consistency Proof for distribution to clients, 948 the log produces a "TransItem" structure of type "consistency_proof", 949 which in this version (v2) encapsulates a "ConsistencyProofDataV2" 950 structure: 952 struct { 953 LogID log_id; 954 uint64 tree_size_1; 955 uint64 tree_size_2; 956 NodeHash consistency_path<1..2^8-1>; 957 } ConsistencyProofDataV2; 959 "log_id" is this log's unique ID, encoded in an opaque vector as 960 described in Section 5.3. 962 "tree_size_1" is the size of the older tree. 964 "tree_size_2" is the size of the newer tree. 966 "consistency_path" is a vector of Merkle Tree nodes proving the 967 consistency of two STHs. 969 5.10. Merkle Inclusion Proofs 971 To prepare a Merkle Inclusion Proof for distribution to clients, the 972 log produces a "TransItem" structure of type "inclusion_proof", which 973 in this version (v2) encapsulates an "InclusionProofDataV2" 974 structure: 976 struct { 977 LogID log_id; 978 uint64 tree_size; 979 uint64 leaf_index; 980 NodeHash inclusion_path<1..2^8-1>; 981 } InclusionProofDataV2; 983 "log_id" is this log's unique ID, encoded in an opaque vector as 984 described in Section 5.3. 986 "tree_size" is the size of the tree on which this inclusion proof is 987 based. 989 "leaf_index" is the 0-based index of the log entry corresponding to 990 this inclusion proof. 992 "inclusion_path" is a vector of Merkle Tree nodes proving the 993 inclusion of the chosen certificate or precertificate. 995 6. Log Client Messages 997 Messages are sent as HTTPS GET or POST requests. Parameters for 998 POSTs and all responses are encoded as JavaScript Object Notation 999 (JSON) objects [RFC4627]. Parameters for GETs are encoded as order- 1000 independent key/value URL parameters, using the "application/x-www- 1001 form-urlencoded" format described in the "HTML 4.01 Specification" 1002 [HTML401]. Binary data is base64 encoded [RFC4648] as specified in 1003 the individual messages. 1005 Note that JSON objects and URL parameters may contain fields not 1006 specified here. These extra fields should be ignored. 1008 The prefix, which is part of the log's metadata, MAY 1009 include a path as well as a server name and a port. 1011 In practice, log servers may include multiple front-end machines. 1012 Since it is impractical to keep these machines in perfect sync, 1013 errors may occur that are caused by skew between the machines. Where 1014 such errors are possible, the front-end will return additional 1015 information (as specified below) making it possible for clients to 1016 make progress, if progress is possible. Front-ends MUST only serve 1017 data that is free of gaps (that is, for example, no front-end will 1018 respond with an STH unless it is also able to prove consistency from 1019 all log entries logged within that STH). 1021 For example, when a consistency proof between two STHs is requested, 1022 the front-end reached may not yet be aware of one or both STHs. In 1023 the case where it is unaware of both, it will return the latest STH 1024 it is aware of. Where it is aware of the first but not the second, 1025 it will return the latest STH it is aware of and a consistency proof 1026 from the first STH to the returned STH. The case where it knows the 1027 second but not the first should not arise (see the "no gaps" 1028 requirement above). 1030 If the log is unable to process a client's request, it MUST return an 1031 HTTP response code of 4xx/5xx (see [RFC2616]), and, in place of the 1032 responses outlined in the subsections below, the body SHOULD be a 1033 JSON structure containing at least the following field: 1035 error_message: A human-readable string describing the error which 1036 prevented the log from processing the request. 1038 In the case of a malformed request, the string SHOULD provide 1039 sufficient detail for the error to be rectified. 1041 error_code: An error code readable by the client. Some codes are 1042 generic and are detailed here. Others are detailed in the 1043 individual requests. Error codes are fixed text strings. 1045 not compliant The request is not compliant with this RFC. 1047 e.g. In response to a request of "/ct/v2/get- 1048 entries?start=100&end=99", the log would return a "400 Bad Request" 1049 response code with a body similar to the following: 1051 { 1052 "error_message": "'start' cannot be greater than 'end'", 1053 "error_code": "not compliant", 1054 } 1056 Clients SHOULD treat "500 Internal Server Error" and "503 Service 1057 Unavailable" responses as transient failures and MAY retry the same 1058 request without modification at a later date. Note that as per 1059 [RFC2616], in the case of a 503 response the log MAY include a 1060 "Retry-After:" header in order to request a minimum time for the 1061 client to wait before retrying the request. 1063 6.1. Add Chain to Log 1065 POST https:///ct/v2/add-chain 1067 Inputs: 1069 chain: An array of base64 encoded certificates. The first 1070 element is the certificate for which the submitter desires an 1071 SCT; the second certifies the first and so on to the last, 1072 which either is, or is certified by, an accepted trust anchor. 1074 Outputs: 1076 sct: A base64 encoded "TransItem" of type "x509_sct", signed by 1077 this log, that corresponds to the submitted certificate. 1079 Error codes: 1081 unknown anchor The last certificate in the chain both is not, and 1082 is not certified by, an accepted trust anchor. 1084 bad chain The alleged chain is not actually a chain of 1085 certificates. 1087 bad certificate One or more certificates in the chain are not 1088 valid (e.g. not properly encoded). 1090 If the version of "sct" is not v2, then a v2 client may be unable to 1091 verify the signature. It MUST NOT construe this as an error. This 1092 is to avoid forcing an upgrade of compliant v2 clients that do not 1093 use the returned SCTs. 1095 If a log detects bad encoding in a chain that otherwise verifies 1096 correctly then the log MAY still log the certificate but SHOULD NOT 1097 return an SCT. It should instead return the "bad certificate" error. 1098 Logging the certificate is useful, because monitors (Section 9.3) can 1099 then detect these encoding errors, which may be accepted by some TLS 1100 clients. 1102 Note that not all certificate handling software is capable of 1103 detecting all encoding errors (e.g. some software will accept BER 1104 instead of DER encodings in certificates, or incorrect character 1105 encodings, even though these are technically incorrect) . 1107 6.2. Add PreCertChain to Log 1109 POST https:///ct/v2/add-pre-chain 1111 Inputs: 1113 precertificate: The base64 encoded precertificate. 1115 chain: An array of base64 encoded CA certificates. The first 1116 element is the signer of the precertificate; the second 1117 certifies the first and so on to the last, which either is, or 1118 is certified by, an accepted trust anchor. 1120 Outputs: 1122 sct: A base64 encoded "TransItem" of type "precert_sct", signed 1123 by this log, that corresponds to the submitted precertificate. 1125 Errors are the same as in Section 6.1. 1127 6.3. Retrieve Latest Signed Tree Head 1129 GET https:///ct/v2/get-sth 1131 No inputs. 1133 Outputs: 1135 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1136 signed by this log, that is no older than the log's MMD. 1138 6.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads 1140 GET https:///ct/v2/get-sth-consistency 1142 Inputs: 1144 first: The tree_size of the older tree, in decimal. 1146 second: The tree_size of the newer tree, in decimal (optional). 1148 Both tree sizes must be from existing v2 STHs. However, because 1149 of skew, the receiving front-end may not know one or both of the 1150 existing STHs. If both are known, then only the "consistency" 1151 output is returned. If the first is known but the second is not 1152 (or has been omitted), then the latest known STH is returned, 1153 along with a consistency proof between the first STH and the 1154 latest. If neither are known, then the latest known STH is 1155 returned without a consistency proof. 1157 Outputs: 1159 consistency: A base64 encoded "TransItem" of type 1160 "consistency_proof", whose "tree_size_1" MUST match the "first" 1161 input. If the "sth" output is omitted, then "tree_size_2" MUST 1162 match the "second" input. 1164 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1165 signed by this log. 1167 Note that no signature is required for the "consistency" output as 1168 it is used to verify the consistency between two STHs, which are 1169 signed. 1171 Error codes: 1173 first unknown "first" is before the latest known STH but is not 1174 from an existing STH. 1176 second unknown "second" is before the latest known STH but is not 1177 from an existing STH. 1179 See Section 9.4.2 for an outline of how to use the "consistency" 1180 output. 1182 6.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash 1184 GET https:///ct/v2/get-proof-by-hash 1186 Inputs: 1188 hash: A base64 encoded v1 leaf hash. 1190 tree_size: The tree_size of the tree on which to base the proof, 1191 in decimal. 1193 The "hash" must be calculated as defined in Section 5.5. The 1194 "tree_size" must designate an existing v2 STH. Because of skew, 1195 the front-end may not know the requested STH. In that case, it 1196 will return the latest STH it knows, along with an inclusion proof 1197 to that STH. If the front-end knows the requested STH then only 1198 "inclusion" is returned. 1200 Outputs: 1202 inclusion: A base64 encoded "TransItem" of type "inclusion_proof" 1203 whose "inclusion_path" array of Merkle Tree nodes proves the 1204 inclusion of the chosen certificate in the selected STH. 1206 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1207 signed by this log. 1209 Note that no signature is required for the "inclusion" output as 1210 it is used to verify inclusion in the selected STH, which is 1211 signed. 1213 Error codes: 1215 hash unknown "hash" is not the hash of a known leaf (may be 1216 caused by skew or by a known certificate not yet merged). 1218 tree_size unknown "hash" is before the latest known STH but is 1219 not from an existing STH. 1221 See Section 9.4.1 for an outline of how to use the "inclusion" 1222 output. 1224 6.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and Consistency 1225 Proof by Leaf Hash 1227 GET https:///ct/v2/get-all-by-hash 1229 Inputs: 1231 hash: A base64 encoded v1 leaf hash. 1233 tree_size: The tree_size of the tree on which to base the proofs, 1234 in decimal. 1236 The "hash" must be calculated as defined in Section 5.5. The 1237 "tree_size" must designate an existing v2 STH. 1239 Because of skew, the front-end may not know the requested STH or 1240 the requested hash, which leads to a number of cases. 1242 latest STH < requested STH Return latest STH. 1244 latest STH > requested STH Return latest STH and a consistency 1245 proof between it and the requested STH (see Section 6.4). 1247 index of requested hash < latest STH Return "inclusion". 1249 Note that more than one case can be true, in which case the 1250 returned data is their concatenation. It is also possible for 1251 none to be true, in which case the front-end MUST return an empty 1252 response. 1254 Outputs: 1256 inclusion: A base64 encoded "TransItem" of type "inclusion_proof" 1257 whose "inclusion_path" array of Merkle Tree nodes proves the 1258 inclusion of the chosen certificate in the selected STH. 1260 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1261 signed by this log. 1263 consistency: A base64 encoded "TransItem" of type 1264 "consistency_proof" that proves the consistency of the 1265 requested STH and the returned STH. 1267 Note that no signature is required for the "inclusion" or 1268 "consistency" outputs as they are used to verify inclusion in and 1269 consistency of STHs, which are signed. 1271 Errors are the same as in Section 6.5. 1273 See Section 9.4.1 for an outline of how to use the "inclusion" 1274 output, and see Section 9.4.2 for an outline of how to use the 1275 "consistency" output. 1277 6.7. Retrieve Entries and STH from Log 1279 GET https:///ct/v2/get-entries 1281 Inputs: 1283 start: 0-based index of first entry to retrieve, in decimal. 1285 end: 0-based index of last entry to retrieve, in decimal. 1287 Outputs: 1289 entries: An array of objects, each consisting of 1291 leaf_input: The base64 encoded "TransItem" structure of type 1292 "x509_entry" or "precert_entry" (see Section 5.5). 1294 log_entry: The base64 encoded log entry (see Section 5.2). In 1295 the case of an "x509_entry" entry, this is the whole 1296 "X509ChainEntry"; and in the case of a "precert_entry", this 1297 is the whole "PrecertChainEntryV2". 1299 sct: A base64 encoded "TransItem" of type "x509_sct" or 1300 "precert_sct" corresponding to this log entry. Note that 1301 more than one SCT may have been returned for the same entry 1302 - only one of those is returned in this field. It may not 1303 be possible to retrieve others. 1305 sth: A base64 encoded "TransItem" of type "signed_tree_head", 1306 signed by this log. 1308 Note that this message is not signed -- the "entries" data can be 1309 verified by constructing the Merkle Tree Hash corresponding to a 1310 retrieved STH. All leaves MUST be v1 or v2. However, a compliant v1 1311 client MUST NOT construe an unrecognized LogEntryType value as an 1312 error. This means it may be unable to parse some entries, but note 1313 that each client can inspect the entries it does recognize as well as 1314 verify the integrity of the data by treating unrecognized leaves as 1315 opaque input to the tree. 1317 The "start" and "end" parameters SHOULD be within the range 0 <= x < 1318 "tree_size" as returned by "get-sth" in Section 6.3. 1320 The "start" parameter MUST be less than or equal to the "end" 1321 parameter. 1323 Log servers MUST honor requests where 0 <= "start" < "tree_size" and 1324 "end" >= "tree_size" by returning a partial response covering only 1325 the valid entries in the specified range. "end" >= "tree_size" could 1326 be caused by skew. Note that the following restriction may also 1327 apply: 1329 Logs MAY restrict the number of entries that can be retrieved per 1330 "get-entries" request. If a client requests more than the permitted 1331 number of entries, the log SHALL return the maximum number of entries 1332 permissible. These entries SHALL be sequential beginning with the 1333 entry specified by "start". 1335 Because of skew, it is possible the log server will not have any 1336 entries between "start" and "end". In this case it MUST return an 1337 empty "entries" array. 1339 In any case, the log server MUST return the latest STH it knows 1340 about. 1342 See Section 9.4.3 for an outline of how to use a complete list of 1343 "leaf_input" entries to verify the "root_hash". 1345 6.8. Retrieve Accepted Trust Anchors 1347 GET https:///ct/v2/get-anchors 1349 No inputs. 1351 Outputs: 1353 certificates: An array of base64 encoded trust anchors that are 1354 acceptable to the log. 1356 max_chain: If the server has chosen to limit the length of chains 1357 it accepts, this is the maximum number of certificates in the 1358 chain, in decimal. If there is no limit, this is omitted. 1360 7. TLS Servers 1362 TLS servers MUST use at least one of the three mechanisms listed 1363 below to present one or more SCTs or inclusion proofs from one or 1364 more logs to each TLS client during TLS handshakes, where each SCT or 1365 inclusion proof corresponds to the server certificate or to a name- 1366 constrained intermediate the server certificate chains to. Three 1367 mechanisms are provided because they have different tradeoffs. 1369 o A TLS extension (Section 7.4.1.4 of [RFC5246]) with type 1370 "transparency_info" (see Section 7.1). This mechanism allows TLS 1371 servers to participate in CT without the cooperation of CAs, 1372 unlike the other two mechanisms. It also allows SCTs and 1373 inclusion proofs to be updated on the fly. 1375 o An Online Certificate Status Protocol (OCSP) [RFC6960] response 1376 extension (see Section 8.1.1), where the OCSP response is provided 1377 in the "CertificateStatus" message, provided that the TLS client 1378 included the "status_request" extension in the (extended) 1379 "ClientHello" (Section 8 of [RFC6066]). This mechanism, popularly 1380 known as OCSP stapling, is already widely (but not universally) 1381 implemented. It also allows SCTs and inclusion proofs to be 1382 updated on the fly. 1384 o An X509v3 certificate extension (see Section 8.1.2). This 1385 mechanism allows the use of unmodified TLS servers, but the SCTs 1386 and inclusion proofs cannot be updated on the fly. Since the logs 1387 from where the SCTs and inclusion proofs originated won't 1388 necessarily be accepted by TLS clients for the full lifetime of 1389 the certificate, there is a risk that TLS clients will 1390 subsequently consider the certificate to be non-compliant and in 1391 need of re-issuance. 1393 TLS servers SHOULD send SCTs or inclusion proofs from multiple logs 1394 in case one or more logs are not acceptable to the TLS client (for 1395 example, if a log has been struck off for misbehavior, has had a key 1396 compromise, or is not known to the TLS client). 1398 Multiple SCTs, inclusion proofs, and indeed "TransItem" structures of 1399 any type, are combined into a list as follows: 1401 opaque SerializedTransItem<1..2^16-1>; 1403 struct { 1404 SerializedTransItem trans_item_list<1..2^16-1>; 1405 } TransItemList; 1407 Here, "SerializedTransItem" is an opaque byte string that contains 1408 the serialized "TransItem" structure. This encoding ensures that TLS 1409 clients can decode each "TransItem" individually (so, for example, if 1410 there is a version upgrade, out-of-date clients can still parse old 1411 "TransItem" structures while skipping over new "TransItem" structures 1412 whose versions they don't understand). 1414 TODO: We need to define at least one ItemExtensionType for 1415 associating SCT and inclusion proof TransItems with the relevant 1416 certificate. 1418 7.1. TLS Extension 1420 If a TLS client includes the "transparency_info" extension type in 1421 the ClientHello, the TLS server MAY include the "transparency_info" 1422 extension in the ServerHello with "extension_data" set to a 1423 "TransItemList". The TLS server is not expected to process or 1424 include this extension when a TLS session is resumed, since session 1425 resumption uses the original session information. 1427 8. Certification Authorities 1429 8.1. Transparency Information X.509v3 Extension 1431 One or more "TransItem" structures can be embedded in the 1432 Transparency Information X.509v3 extension, which has OID and 1433 SHOULD be non-critical. This extension can be included in OCSP 1434 responses and certificates. Since RFC5280 requires the "extnValue" 1435 field (an OCTET STRING) of each X.509v3 extension to include the DER 1436 encoding of an ASN.1 value, we cannot embed a "TransItemList" 1437 directly. Instead, we have to wrap it inside an additional OCTET 1438 STRING, which we then put into the "extnValue" field: 1440 TransparencyInformationSyntax ::= OCTET STRING 1442 "TransparencyInformationSyntax" contains a "TransItemList". 1444 8.1.1. OCSP Response Extension 1446 A certification authority may include a Transparency Information 1447 X.509v3 extension in the "singleExtensions" of a "SingleResponse" in 1448 an OCSP response. The included SCTs or inclusion proofs MUST be for 1449 the certificate identified by the "certID" of that "SingleResponse", 1450 or for a precertificate that corresponds to that certificate, or for 1451 a name-constrained intermediate to which that certificate chains. 1453 8.1.2. Certificate Extension 1455 A certification authority may include a Transparency Information 1456 X.509v3 extension in a certificate. Any included SCTs or inclusion 1457 proofs MUST be either for a precertificate that corresponds to this 1458 certificate, or for a name-constrained intermediate to which this 1459 certificate chains. 1461 9. Clients 1463 There are various different functions clients of logs might perform. 1464 We describe here some typical clients and how they should function. 1465 Any inconsistency may be used as evidence that a log has not behaved 1466 correctly, and the signatures on the data structures prevent the log 1467 from denying that misbehavior. 1469 All clients need various metadata in order to communicate with logs 1470 and verify their responses. This metadata is described below, but 1471 note that this document does not describe how the metadata is 1472 obtained, which is implementation dependent (see, for example, 1473 [Chromium.Policy]). 1475 Clients should somehow exchange STHs they see, or make them available 1476 for scrutiny, in order to ensure that they all have a consistent 1477 view. The exact mechanisms will be in separate documents, but it is 1478 expected there will be a variety. 1480 9.1. Metadata 1482 In order to communicate with and verify a log, clients need metadata 1483 about the log. 1485 Base URL: The URL to substitute for in Section 6. 1487 Hash Algorithm The hash algorithm used for the Merkle Tree (see 1488 Section 11.2). 1490 Signing Algorithm The signing algorithm used (see Section 2.1.4). 1492 Public Key The public key used to verify signatures generated by the 1493 log. A log MUST NOT use the same keypair as any other log. 1495 Log ID The OID that uniquely identifies the log. 1497 Maximum Merge Delay The MMD the log has committed to. 1499 Version The version of the protocol supported by the log (currently 1500 1 or 2). 1502 Maximum Chain Length The longest chain submission the log is willing 1503 to accept, if the log chose to limit it. 1505 STH Frequency Count The maximum number of STHs the log may produce 1506 in any period equal to the "Maximum Merge Delay" (see 1507 Section 5.8). 1509 Final STH If a log has been closed down (i.e. no longer accepts new 1510 entries), existing entries may still be valid. In this case, the 1511 client should know the final valid STH in the log to ensure no new 1512 entries can be added without detection. 1514 [JSON.Metadata] is an example of a metadata format which includes the 1515 above elements. 1517 9.2. TLS Client 1519 TLS clients receive SCTs alongside or in certificates, either for the 1520 server certificate itself or for a name-constrained intermediate the 1521 server certificate chains to. TLS clients MUST implement all of the 1522 three mechanisms by which TLS servers may present SCTs (see 1523 Section 7). TLS clients that support the "transparency_info" TLS 1524 extension SHOULD include it in ClientHello messages, with 1525 "extension_data" set to . 1527 TODO: What should the TLS client communicate in the extension_data? 1528 Version(s) of CT that it supports? Certain types of TransItem that 1529 it can handle? Whether or not it wants to gossip? 1531 In addition to normal validation of the certificate and its chain, 1532 TLS clients SHOULD validate each supplied SCT by computing the 1533 signature input from the SCT data as well as the certificate and 1534 verifying the signature, using the corresponding log's public key. 1535 TLS clients MUST reject SCTs whose timestamp is in the future. 1537 TLS clients SHOULD also validate each supplied inclusion proof (see 1538 Section 9.4.1), in order to audit the log. If no inclusion proof was 1539 supplied by the TLS server, the TLS client MAY request one directly 1540 from the corresponding log using "get-proof-by-hash" (Section 6.5) or 1541 "get-all-by-hash" (Section 6.6), and then validate it. 1543 To be considered compliant, a certificate MUST be accompanied by at 1544 least one valid SCT or at least one valid inclusion proof. A 1545 certificate not accompanied by any valid SCTs or any valid inclusion 1546 proofs MUST NOT be considered compliant by TLS clients. However, 1547 specifying the TLS clients' behavior once compliance or non- 1548 compliance has been determined (for example, whether a certificate 1549 should be rejected due to non-compliance) is outside the scope of 1550 this document. 1552 If the TLS client holds an STH that predates the SCT, it MAY, in the 1553 process of auditing, request a new STH from the log (Section 6.3), 1554 then verify it by requesting a consistency proof (Section 6.4). Note 1555 that if the TLS client uses "get-all-by-hash", then it will already 1556 have the new STH. 1558 9.3. Monitor 1560 Monitors watch logs and check that they behave correctly. Monitors 1561 may additionally watch for certificates of interest. For example, a 1562 monitor may be configured to report on all certificates that apply to 1563 a specific domain name when fetching new entries for consistency 1564 validation. 1566 A monitor needs to, at least, inspect every new entry in each log it 1567 watches. It may also want to keep copies of entire logs. In order 1568 to do this, it should follow these steps for each log: 1570 1. Fetch the current STH (Section 6.3). 1572 2. Verify the STH signature. 1574 3. Fetch all the entries in the tree corresponding to the STH 1575 (Section 6.7). 1577 4. Confirm that the tree made from the fetched entries produces the 1578 same hash as that in the STH. 1580 5. Fetch the current STH (Section 6.3). Repeat until the STH 1581 changes. 1583 6. Verify the STH signature. 1585 7. Fetch all the new entries in the tree corresponding to the STH 1586 (Section 6.7). If they remain unavailable for an extended 1587 period, then this should be viewed as misbehavior on the part of 1588 the log. 1590 8. Either: 1592 1. Verify that the updated list of all entries generates a tree 1593 with the same hash as the new STH. 1595 Or, if it is not keeping all log entries: 1597 1. Fetch a consistency proof for the new STH with the previous 1598 STH (Section 6.4). 1600 2. Verify the consistency proof. 1602 3. Verify that the new entries generate the corresponding 1603 elements in the consistency proof. 1605 9. Go to Step 5. 1607 9.4. Auditing 1609 Auditing is taking partial information about a log as input and 1610 verifying that this information is consistent with other partial 1611 information held. All clients described above may perform auditing 1612 as an additional function. The action taken by the client if audit 1613 fails is not specified, but note that in general if audit fails, the 1614 client is in possession of signed proof of the log's misbehavior. 1616 A monitor (Section 9.3) can audit by verifying the consistency of 1617 STHs it receives, ensure that each entry can be fetched and that the 1618 STH is indeed the result of making a tree from all fetched entries. 1620 A TLS client (Section 9.2) can audit by verifying an SCT against any 1621 STH dated after the SCT timestamp + the Maximum Merge Delay by 1622 requesting a Merkle inclusion proof (Section 6.5). It can also 1623 verify that the SCT corresponds to the certificate it arrived with 1624 (i.e. the log entry is that certificate, is a precertificate for that 1625 certificate or is an appropriate name-constrained intermediate [see 1626 Section 4.3]). 1628 The following algorithm outlines may be useful for clients that wish 1629 to perform various audit operations. 1631 9.4.1. Verifying an inclusion proof 1633 When a client has received a "TransItem" of type "inclusion_proof" 1634 and wishes to verify inclusion of an input "hash" for an STH with a 1635 given "tree_size" and "root_hash", the following algorithm may be 1636 used to prove the "hash" was included in the "root_hash": 1638 1. Set "fn" to "leaf_index" and "sn" to "tree_size - 1". 1640 2. Set "r" to "hash". 1642 3. For each value "p" in the "inclusion_path" array: 1644 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1646 1. Set "r" to "HASH(0x01 || p || r)" 1648 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1649 equally until either "LSB(fn)" is set or "fn" is "0". 1651 Otherwise: 1653 Set "r" to "HASH(0x01 || r || p)" 1655 Finally, right-shift both "fn" and "sn" one time. 1657 4. Compare "r" against the "root_hash". If they are equal, then the 1658 log has proven the inclusion of "hash". 1660 9.4.2. Verifying consistency between two STHs 1662 When a client has an STH "first_hash" for tree size "first", an STH 1663 "second_hash" for tree size "second" where "0 < first < second", and 1664 has received a "TransItem" of type "consistency_proof" that they wish 1665 to use to verify both hashes, the following algorithm may be used: 1667 1. If "first" is an exact power of 2, then prepend "first_hash" to 1668 the "consistency_path" array. 1670 2. Set "fn" to "first - 1" and "sn" to "second - 1". 1672 3. If "LSB(fn)" is set, then right-shift both "fn" and "sn" equally 1673 until "LSB(fn)" is not set. 1675 4. Set both "fr" and "sr" to the first value in the 1676 "consistency_path" array. 1678 5. For each subsequent value "c" in the "consistency_path" array: 1680 If "sn" is 0, stop the iteration and fail the proof verification. 1682 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1684 1. Set "fr" to "HASH(0x01 || c || fr)" 1685 Set "sr" to "HASH(0x01 || c || sr)" 1687 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1688 equally until either "LSB(fn)" is set or "fn" is "0". 1690 Otherwise: 1692 Set "sr" to "HASH(0x01 || sr || c)" 1694 Finally, right-shift both "fn" and "sn" one time. 1696 6. After completing iterating through the "consistency_path" array 1697 as described above, verify that the "fr" calculated is equal to 1698 the "first_hash" supplied, that the "sr" calculated is equal to 1699 the "second_hash" supplied and that "sn" is 0. 1701 9.4.3. Verifying root hash given entries 1703 When a client has a complete list of leaf input "entries" from "0" up 1704 to "tree_size - 1" and wishes to verify this list against an STH 1705 "root_hash" returned by the log for the same "tree_size", the 1706 following algorithm may be used: 1708 1. Set "stack" to an empty stack. 1710 2. For each "i" from "0" up to "tree_size - 1": 1712 1. Push "HASH(0x00 || entries[i])" to "stack". 1714 2. Set "merge_count" to the lowest value ("0" included) such 1715 that "LSB(i >> merge_count)" is not set. In other words, set 1716 "merge_count" to the number of consecutive "1"s found 1717 starting at the least significant bit of "i". 1719 3. Repeat "merge_count" times: 1721 1. Pop "right" from "stack". 1723 2. Pop "left" from "stack". 1725 3. Push "HASH(0x01 || left || right)" to "stack". 1727 3. If there is more than one element in the "stack", repeat the same 1728 merge procedure (Step 2.3 above) until only a single element 1729 remains. 1731 4. The remaining element in "stack" is the Merkle Tree hash for the 1732 given "tree_size" and should be compared by equality against the 1733 supplied "root_hash". 1735 10. Algorithm Agility 1737 It is not possible for a log to change any of its algorithms part way 1738 through its lifetime. If it should become necessary to deprecate an 1739 algorithm used by a live log, then the log should be frozen as 1740 specified in Section 9.1 and a new log should be started. If 1741 necessary, the new log can contain existing entries from the frozen 1742 log, which monitors can verify are an exact match. 1744 11. IANA Considerations 1746 11.1. TLS Extension Type 1748 IANA is asked to allocate an RFC 5246 ExtensionType value for the 1749 "transparency_info" TLS extension. IANA should update this extension 1750 type to point at this document. 1752 11.2. Hash Algorithms 1754 IANA is asked to establish a registry of hash values, initially 1755 consisting of: 1757 +-------+----------------------+ 1758 | Index | Hash | 1759 +-------+----------------------+ 1760 | 0 | SHA-256 [FIPS.180-4] | 1761 +-------+----------------------+ 1763 11.3. TransItem Extensions 1765 IANA is asked to establish a registry of TransItem extensions, 1766 initially consisting of: 1768 +-------+-----------+ 1769 | Type | Extension | 1770 +-------+-----------+ 1771 | 65535 | reserved | 1772 +-------+-----------+ 1774 TBD: policy for adding to the registry 1776 11.4. Signature Algorithms 1778 IANA is asked to establish a registry of signature algorithm values, 1779 initially consisting of: 1781 +-------+-----------------------------------------------------------+ 1782 | Index | Signature Algorithm | 1783 +-------+-----------------------------------------------------------+ 1784 | 0 | deterministic ECDSA [RFC6979] using the NIST P-256 curve | 1785 | | (Section D.1.2.3 of the Digital Signature Standard [DSS]) | 1786 | | and HMAC-SHA256 | 1787 | 1 | RSA signatures (RSASSA-PKCS1-v1_5 with SHA-256, Section | 1788 | | 8.2 of [RFC3447]) using a key of at least 2048 bits. | 1789 +-------+-----------------------------------------------------------+ 1791 11.5. SCT Extensions 1793 IANA is asked to establish a registry of SCT extensions, initially 1794 consisting of: 1796 +-------+-----------+ 1797 | Type | Extension | 1798 +-------+-----------+ 1799 | 65535 | reserved | 1800 +-------+-----------+ 1802 TBD: policy for adding to the registry 1804 11.6. STH Extensions 1806 IANA is asked to establish a registry of STH extensions, initially 1807 consisting of: 1809 +-------+-----------+ 1810 | Type | Extension | 1811 +-------+-----------+ 1812 | 65535 | reserved | 1813 +-------+-----------+ 1815 TBD: policy for adding to the registry 1817 12. Security Considerations 1819 With CAs, logs, and servers performing the actions described here, 1820 TLS clients can use logs and signed timestamps to reduce the 1821 likelihood that they will accept misissued certificates. If a server 1822 presents a valid signed timestamp for a certificate, then the client 1823 knows that a log has committed to publishing the certificate. From 1824 this, the client knows that monitors acting for the subject of the 1825 certificate have had some time to notice the misissue and take some 1826 action, such as asking a CA to revoke a misissued certificate, or 1827 that the log has misbehaved, which will be discovered when the SCT is 1828 audited. A signed timestamp is not a guarantee that the certificate 1829 is not misissued, since appropriate monitors might not have checked 1830 the logs or the CA might have refused to revoke the certificate. 1832 In addition, if TLS clients will not accept unlogged certificates, 1833 then site owners will have a greater incentive to submit certificates 1834 to logs, possibly with the assistance of their CA, increasing the 1835 overall transparency of the system. 1837 12.1. Misissued Certificates 1839 Misissued certificates that have not been publicly logged, and thus 1840 do not have a valid SCT, are not considered compliant (so TLS clients 1841 may decide, for example, to reject them). Misissued certificates 1842 that do have an SCT from a log will appear in that public log within 1843 the Maximum Merge Delay, assuming the log is operating correctly. 1844 Thus, the maximum period of time during which a misissued certificate 1845 can be used without being available for audit is the MMD. 1847 12.2. Detection of Misissue 1849 The logs do not themselves detect misissued certificates; they rely 1850 instead on interested parties, such as domain owners, to monitor them 1851 and take corrective action when a misissue is detected. 1853 12.3. Redaction of Public Domain Name Labels 1855 CAs SHOULD NOT redact domain name labels in precertificates such that 1856 the entirety of the domain space below the unredacted part of the 1857 domain name is not owned or controlled by a single entity (e.g. 1858 "?.com" and "?.co.uk" would both be problematic). Logs MUST NOT 1859 reject any precertificate that is overly redacted but which is 1860 otherwise considered compliant. It is expected that monitors will 1861 treat overly redacted precertificates as potentially misissued. TLS 1862 clients MAY reject a certificate whose corresponding precertificate 1863 would be overly redacted, perhaps using the same mechanism for 1864 determining whether a wildcard in a domain name of a certificate is 1865 too broad. 1867 12.4. Misbehaving Logs 1869 A log can misbehave in two ways: (1) by failing to incorporate a 1870 certificate with an SCT in the Merkle Tree within the MMD and (2) by 1871 violating its append-only property by presenting two different, 1872 conflicting views of the Merkle Tree at different times and/or to 1873 different parties. Both forms of violation will be promptly and 1874 publicly detectable. 1876 Violation of the MMD contract is detected by log clients requesting a 1877 Merkle audit proof for each observed SCT. These checks can be 1878 asynchronous and need only be done once per each certificate. In 1879 order to protect the clients' privacy, these checks need not reveal 1880 the exact certificate to the log. Clients can instead request the 1881 proof from a trusted auditor (since anyone can compute the audit 1882 proofs from the log) or request Merkle proofs for a batch of 1883 certificates around the SCT timestamp. 1885 Violation of the append-only property can be detected by clients 1886 comparing their instances of the Signed Tree Heads. As soon as two 1887 conflicting Signed Tree Heads for the same log are detected, this is 1888 cryptographic proof of that log's misbehavior. There are various 1889 ways this could be done, for example via gossip (see http:// 1890 trac.tools.ietf.org/id/draft-linus-trans-gossip-00.txt) or peer-to- 1891 peer communications or by sending STHs to monitors (who could then 1892 directly check against their own copy of the relevant log). 1894 12.5. Deterministic Signatures 1896 Logs are required to use deterministic signatures for the following 1897 reasons: 1899 o Using non-deterministic ECDSA with a predictable source of 1900 randomness means that each signature can potentially expose the 1901 secret material of the signing key. 1903 o Clients that gossip STHs or report back SCTs can be tracked or 1904 traced if a log was to produce multiple STHs or SCTs with the same 1905 timestamp and data but different signatures. 1907 12.6. Multiple SCTs 1909 TLS servers may wish to offer multiple SCTs, each from a different 1910 log. 1912 o If a CA and a log collude, it is possible to temporarily hide 1913 misissuance from clients. Including SCTs from different logs 1914 makes it more difficult to mount this attack. 1916 o If a log misbehaves, a consequence may be that clients cease to 1917 trust it. Since the time an SCT may be in use can be considerable 1918 (several years is common in current practice when the SCT is 1919 embedded in a certificate), servers may wish to reduce the 1920 probability of their certificates being rejected as a result by 1921 including SCTs from different logs. 1923 o TLS clients may have policies related to the above risks requiring 1924 servers to present multiple SCTs. For example Chromium 1925 [Chromium.Log.Policy] currently requires multiple SCTs to be 1926 presented with EV certificates in order for the EV indicator to be 1927 shown. 1929 13. Acknowledgements 1931 The authors would like to thank Erwann Abelea, Robin Alden, Al 1932 Cutter, Francis Dupont, Adam Eijdenberg, Stephen Farrell, Daniel Kahn 1933 Gillmor, Brad Hill, Jeff Hodges, Paul Hoffman, Jeffrey Hutzelman, 1934 Stephen Kent, SM, Alexey Melnikov, Linus Nordberg, Chris Palmer, 1935 Trevor Perrin, Pierre Phaneuf, Melinda Shore, Ryan Sleevi, Carl 1936 Wallace and Paul Wouters for their valuable contributions. 1938 14. References 1940 14.1. Normative References 1942 [DSS] National Institute of Standards and Technology, "Digital 1943 Signature Standard (DSS)", FIPS 186-3, June 2009, 1944 . 1947 [FIPS.180-4] 1948 National Institute of Standards and Technology, "Secure 1949 Hash Standard", FIPS PUB 180-4, March 2012, 1950 . 1953 [HTML401] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 1954 Specification", World Wide Web Consortium Recommendation 1955 REC-html401-19991224, December 1999, 1956 . 1958 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1959 Requirement Levels", BCP 14, RFC 2119, March 1997. 1961 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1962 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1963 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1965 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 1966 Standards (PKCS) #1: RSA Cryptography Specifications 1967 Version 2.1", RFC 3447, February 2003. 1969 [RFC4627] Crockford, D., "The application/json Media Type for 1970 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1972 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1973 Encodings", RFC 4648, October 2006. 1975 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1976 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1978 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 1979 Housley, R., and W. Polk, "Internet X.509 Public Key 1980 Infrastructure Certificate and Certificate Revocation List 1981 (CRL) Profile", RFC 5280, May 2008. 1983 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 1984 RFC 5652, DOI 10.17487/RFC5652, September 2009, 1985 . 1987 [RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 1988 Time Protocol Version 4: Protocol and Algorithms 1989 Specification", RFC 5905, June 2010. 1991 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 1992 Extension Definitions", RFC 6066, January 2011. 1994 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1995 Verification of Domain-Based Application Service Identity 1996 within Internet Public Key Infrastructure Using X.509 1997 (PKIX) Certificates in the Context of Transport Layer 1998 Security (TLS)", RFC 6125, March 2011. 2000 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2001 Galperin, S., and C. Adams, "X.509 Internet Public Key 2002 Infrastructure Online Certificate Status Protocol - OCSP", 2003 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2004 . 2006 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 2007 Algorithm (DSA) and Elliptic Curve Digital Signature 2008 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 2009 2013, . 2011 14.2. Informative References 2013 [Chromium.Log.Policy] 2014 The Chromium Projects, "Chromium Certificate Transparency 2015 Log Policy", 2014, . 2018 [Chromium.Policy] 2019 The Chromium Projects, "Chromium Certificate 2020 Transparency", 2014, . 2023 [CrosbyWallach] 2024 Crosby, S. and D. Wallach, "Efficient Data Structures for 2025 Tamper-Evident Logging", Proceedings of the 18th USENIX 2026 Security Symposium, Montreal, August 2009, 2027 . 2030 [EVSSLGuidelines] 2031 CA/Browser Forum, "Guidelines For The Issuance And 2032 Management Of Extended Validation Certificates", 2007, 2033 . 2036 [JSON.Metadata] 2037 The Chromium Projects, "Chromium Log Metadata JSON 2038 Schema", 2014, . 2041 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 2042 Transparency", RFC 6962, June 2013. 2044 Appendix A. TransItemV1 2046 TODO: Finish writing this section. Or should it be in a separate 2047 document? 2049 struct { 2050 TransType type; 2051 select (type) { 2052 case x509_sct: SignedCertificateTimestampV1; 2053 case precert_sct: SignedCertificateTimestampV1; 2054 case signed_tree_head: SignedTreeHeadDataV1; 2055 case consistency_proof: ConsistencyProofDataV1; 2056 case inclusion_proof: InclusionProofDataV1; 2057 } data; 2058 } TransItemV1; 2060 opaque SHA256Hash[32]; 2062 struct { 2063 Version version = v1; 2064 SHA256Hash log_id; 2065 uint64 timestamp; 2066 SctExtensions extensions; 2067 digitally-signed struct { 2068 Version version = v1; 2069 uint8 signature_type = 0; /* "certificate_timestamp" */ 2070 uint64 timestamp; 2071 TransType type; /* x509_entry(0) or precert_entry(1) */ 2072 select (type) { 2073 case x509_entry: ASN.1Cert; 2074 case precert_entry: PreCert; 2075 } signed_entry; 2076 SctExtensions extensions; 2077 } signature; 2078 } SignedCertificateTimestampV1; 2080 struct { 2081 SHA256Hash log_id; 2082 uint64 timestamp; 2083 uint64 tree_size; 2084 SHA256Hash sha256_root_hash; 2085 digitally-signed struct { 2086 Version version = v1; 2087 uint8 signature_type = 1; /* "tree_hash" */ 2088 uint64 timestamp; 2089 uint64 tree_size; 2090 SHA256Hash sha256_root_hash; 2091 } signature; 2093 } SignedTreeHeadDataV1; 2095 struct { 2096 SHA256Hash log_id; 2097 uint64 tree_size_1; 2098 uint64 tree_size_2; 2099 SHA256Hash consistency_path<1..2^8-1>; 2100 } ConsistencyProofDataV1; 2102 struct { 2103 SHA256Hash log_id; 2104 uint64 tree_size; 2105 uint64 leaf_index; 2106 SHA256Hash inclusion_path<1..2^8-1>; 2107 } InclusionProofDataV1; 2109 Authors' Addresses 2111 Ben Laurie 2112 Google UK Ltd. 2114 EMail: benl@google.com 2116 Adam Langley 2117 Google Inc. 2119 EMail: agl@google.com 2121 Emilia Kasper 2122 Google Switzerland GmbH 2124 EMail: ekasper@google.com 2126 Eran Messeri 2127 Google UK Ltd. 2129 EMail: eranm@google.com 2131 Rob Stradling 2132 Comodo CA, Ltd. 2134 EMail: rob.stradling@comodo.com