idnits 2.17.1 draft-ietf-trans-rfc6962-bis-14.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 6 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 11, 2016) is 2931 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '1' on line 582 -- Looks like a reference, but probably isn't: '7' on line 587 -- Looks like a reference, but probably isn't: '0' on line 577 -- Looks like a reference, but probably isn't: '2' on line 579 -- Possible downref: Non-RFC (?) normative reference: ref. 'DSS' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTML401' ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 3447 (Obsoleted by RFC 8017) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 6961 (Obsoleted by RFC 8446) ** Downref: Normative reference to an Informational RFC: RFC 6979 == Outdated reference: A later version (-05) exists of draft-ietf-trans-gossip-01 == Outdated reference: A later version (-16) exists of draft-ietf-trans-threat-analysis-03 -- Obsolete informational reference (is this intentional?): RFC 6962 (Obsoleted by RFC 9162) Summary: 7 errors (**), 0 flaws (~~), 4 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Public Notary Transparency Working Group B. Laurie 3 Internet-Draft A. Langley 4 Intended status: Standards Track E. Kasper 5 Expires: October 13, 2016 E. Messeri 6 Google 7 R. Stradling 8 Comodo 9 April 11, 2016 11 Certificate Transparency 12 draft-ietf-trans-rfc6962-bis-14 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 October 13, 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 . . . . . . . . . . . . . . . . . . . . . . . . 4 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. Redaction of Domain Name Labels . . . . . . . . . . . . . 11 77 4.2.1. Redacting Labels in Precertificates . . . . . . . . . 12 78 4.2.2. Redacted Labels Certificate Extension . . . . . . . . 12 79 4.3. Using a Name-Constrained Intermediate CA . . . . . . . . 12 80 5. Log Format and Operation . . . . . . . . . . . . . . . . . . 13 81 5.1. Accepting Submissions . . . . . . . . . . . . . . . . . . 14 82 5.2. Log Entries . . . . . . . . . . . . . . . . . . . . . . . 14 83 5.3. Log ID . . . . . . . . . . . . . . . . . . . . . . . . . 15 84 5.4. TransItem Structure . . . . . . . . . . . . . . . . . . . 16 85 5.5. Merkle Tree Leaves . . . . . . . . . . . . . . . . . . . 17 86 5.6. Signed Certificate Timestamp (SCT) . . . . . . . . . . . 18 87 5.7. Merkle Tree Head . . . . . . . . . . . . . . . . . . . . 19 88 5.8. Signed Tree Head (STH) . . . . . . . . . . . . . . . . . 19 89 5.9. Merkle Consistency Proofs . . . . . . . . . . . . . . . . 21 90 5.10. Merkle Inclusion Proofs . . . . . . . . . . . . . . . . . 21 91 5.11. Shutting down a log . . . . . . . . . . . . . . . . . . . 22 92 6. Log Client Messages . . . . . . . . . . . . . . . . . . . . . 22 93 6.1. Add Chain to Log . . . . . . . . . . . . . . . . . . . . 24 94 6.2. Add PreCertChain to Log . . . . . . . . . . . . . . . . . 25 95 6.3. Retrieve Latest Signed Tree Head . . . . . . . . . . . . 25 96 6.4. Retrieve Merkle Consistency Proof between Two Signed Tree 97 Heads . . . . . . . . . . . . . . . . . . . . . . . . . . 26 98 6.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash . . 27 99 6.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and 100 Consistency Proof by Leaf Hash . . . . . . . . . . . . . 28 101 6.7. Retrieve Entries and STH from Log . . . . . . . . . . . . 29 102 6.8. Retrieve Accepted Trust Anchors . . . . . . . . . . . . . 30 103 7. TLS Servers . . . . . . . . . . . . . . . . . . . . . . . . . 31 104 7.1. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . . 31 105 7.2. TransItemList Structure . . . . . . . . . . . . . . . . . 32 106 7.3. Presenting SCTs, inclusion proofs and STHs . . . . . . . 32 107 7.4. Presenting SCTs only . . . . . . . . . . . . . . . . . . 33 108 7.5. transparency_info TLS Extension . . . . . . . . . . . . . 33 109 8. Certification Authorities . . . . . . . . . . . . . . . . . . 33 110 8.1. Transparency Information X.509v3 Extension . . . . . . . 34 111 8.1.1. OCSP Response Extension . . . . . . . . . . . . . . . 34 112 8.1.2. Certificate Extension . . . . . . . . . . . . . . . . 34 113 8.2. TLS Feature Extension . . . . . . . . . . . . . . . . . . 34 114 9. Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 115 9.1. Metadata . . . . . . . . . . . . . . . . . . . . . . . . 35 116 9.2. TLS Client . . . . . . . . . . . . . . . . . . . . . . . 36 117 9.2.1. Receiving SCTs . . . . . . . . . . . . . . . . . . . 36 118 9.2.2. Reconstructing the TBSCertificate . . . . . . . . . . 36 119 9.2.3. Validating SCTs . . . . . . . . . . . . . . . . . . . 36 120 9.2.4. Validating inclusion proofs . . . . . . . . . . . . . 37 121 9.2.5. Evaluating compliance . . . . . . . . . . . . . . . . 37 122 9.2.6. TLS Feature Extension . . . . . . . . . . . . . . . . 37 123 9.2.7. Handling of Non-compliance . . . . . . . . . . . . . 37 124 9.3. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 38 125 9.4. Auditing . . . . . . . . . . . . . . . . . . . . . . . . 39 126 9.4.1. Verifying an inclusion proof . . . . . . . . . . . . 40 127 9.4.2. Verifying consistency between two STHs . . . . . . . 40 128 9.4.3. Verifying root hash given entries . . . . . . . . . . 41 129 10. Algorithm Agility . . . . . . . . . . . . . . . . . . . . . . 42 130 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43 131 11.1. TLS Extension Type . . . . . . . . . . . . . . . . . . . 43 132 11.2. Hash Algorithms . . . . . . . . . . . . . . . . . . . . 43 133 11.3. Signature Algorithms . . . . . . . . . . . . . . . . . . 43 134 11.4. SCT Extensions . . . . . . . . . . . . . . . . . . . . . 43 135 11.5. STH Extensions . . . . . . . . . . . . . . . . . . . . . 44 136 11.6. Object Identifiers . . . . . . . . . . . . . . . . . . . 44 137 11.6.1. Log ID Registry 1 . . . . . . . . . . . . . . . . . 44 138 11.6.2. Log ID Registry 2 . . . . . . . . . . . . . . . . . 44 139 12. Security Considerations . . . . . . . . . . . . . . . . . . . 45 140 12.1. Misissued Certificates . . . . . . . . . . . . . . . . . 45 141 12.2. Detection of Misissue . . . . . . . . . . . . . . . . . 45 142 12.3. Avoiding Overly Redacting Domain Name Labels . . . . . . 45 143 12.4. Misbehaving Logs . . . . . . . . . . . . . . . . . . . . 46 144 12.5. Deterministic Signatures . . . . . . . . . . . . . . . . 46 145 12.6. Multiple SCTs . . . . . . . . . . . . . . . . . . . . . 47 146 12.7. Threat Analysis . . . . . . . . . . . . . . . . . . . . 47 147 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 47 148 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 47 149 14.1. Normative References . . . . . . . . . . . . . . . . . . 47 150 14.2. Informative References . . . . . . . . . . . . . . . . . 49 151 Appendix A. Supporting v1 and v2 simultaneously . . . . . . . . 51 153 1. Introduction 155 Certificate transparency aims to mitigate the problem of misissued 156 certificates by providing append-only logs of issued certificates. 157 The logs do not need to be trusted because they are publicly 158 auditable. Anyone may verify the correctness of each log and monitor 159 when new certificates are added to it. The logs do not themselves 160 prevent misissue, but they ensure that interested parties 161 (particularly those named in certificates) can detect such 162 misissuance. Note that this is a general mechanism, but in this 163 document, we only describe its use for public TLS server certificates 164 issued by public certification authorities (CAs). 166 Each log consists of certificate chains, which can be submitted by 167 anyone. It is expected that public CAs will contribute all their 168 newly issued certificates to one or more logs, however certificate 169 holders can also contribute their own certificate chains, as can 170 third parties. In order to avoid logs being rendered useless by the 171 submission of large numbers of spurious certificates, it is required 172 that each chain ends with a trust anchor that is accepted by the log. 173 When a chain is accepted by a log, a signed timestamp is returned, 174 which can later be used to provide evidence to TLS clients that the 175 chain has been submitted. TLS clients can thus require that all 176 certificates they accept as valid are accompanied by signed 177 timestamps. 179 Those who are concerned about misissuance can monitor the logs, 180 asking them regularly for all new entries, and can thus check whether 181 domains they are responsible for have had certificates issued that 182 they did not expect. What they do with this information, 183 particularly when they find that a misissuance has happened, is 184 beyond the scope of this document, but broadly speaking, they can 185 invoke existing business mechanisms for dealing with misissued 186 certificates, such as working with the CA to get the certificate 187 revoked, or with maintainers of trust anchor lists to get the CA 188 removed. Of course, anyone who wants can monitor the logs and, if 189 they believe a certificate is incorrectly issued, take action as they 190 see fit. 192 Similarly, those who have seen signed timestamps from a particular 193 log can later demand a proof of inclusion from that log. If the log 194 is unable to provide this (or, indeed, if the corresponding 195 certificate is absent from monitors' copies of that log), that is 196 evidence of the incorrect operation of the log. The checking 197 operation is asynchronous to allow clients to proceed without delay, 198 despite possible issues such as network connectivity and the vagaries 199 of firewalls. 201 The append-only property of each log is technically achieved using 202 Merkle Trees, which can be used to show that any particular instance 203 of the log is a superset of any particular previous instance. 204 Likewise, Merkle Trees avoid the need to blindly trust logs: if a log 205 attempts to show different things to different people, this can be 206 efficiently detected by comparing tree roots and consistency proofs. 207 Similarly, other misbehaviors of any log (e.g., issuing signed 208 timestamps for certificates they then don't log) can be efficiently 209 detected and proved to the world at large. 211 1.1. Requirements Language 213 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 214 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 215 document are to be interpreted as described in RFC 2119 [RFC2119]. 217 1.2. Data Structures 219 Data structures are defined according to the conventions laid out in 220 Section 4 of [RFC5246]. 222 2. Cryptographic Components 224 2.1. Merkle Hash Trees 226 Logs use a binary Merkle Hash Tree for efficient auditing. The 227 hashing algorithm used by each log is expected to be specified as 228 part of the metadata relating to that log. We have established a 229 registry of acceptable algorithms, see Section 11.2. The hashing 230 algorithm in use is referred to as HASH throughout this document and 231 the size of its output in bytes as HASH_SIZE. The input to the 232 Merkle Tree Hash is a list of data entries; these entries will be 233 hashed to form the leaves of the Merkle Hash Tree. The output is a 234 single HASH_SIZE Merkle Tree Hash. Given an ordered list of n 235 inputs, D[n] = {d(0), d(1), ..., d(n-1)}, the Merkle Tree Hash (MTH) 236 is thus defined as follows: 238 The hash of an empty list is the hash of an empty string: 240 MTH({}) = HASH(). 242 The hash of a list with one entry (also known as a leaf hash) is: 244 MTH({d(0)}) = HASH(0x00 || d(0)). 246 For n > 1, let k be the largest power of two smaller than n (i.e., k 247 < n <= 2k). The Merkle Tree Hash of an n-element list D[n] is then 248 defined recursively as 250 MTH(D[n]) = HASH(0x01 || MTH(D[0:k]) || MTH(D[k:n])), 252 where || is concatenation and D[k1:k2] denotes the list {d(k1), 253 d(k1+1),..., d(k2-1)} of length (k2 - k1). (Note that the hash 254 calculations for leaves and nodes differ. This domain separation is 255 required to give second preimage resistance.) 257 Note that we do not require the length of the input list to be a 258 power of two. The resulting Merkle Tree may thus not be balanced; 259 however, its shape is uniquely determined by the number of leaves. 260 (Note: This Merkle Tree is essentially the same as the history tree 261 [CrosbyWallach] proposal, except our definition handles non-full 262 trees differently.) 264 2.1.1. Merkle Inclusion Proofs 266 A Merkle inclusion proof for a leaf in a Merkle Hash Tree is the 267 shortest list of additional nodes in the Merkle Tree required to 268 compute the Merkle Tree Hash for that tree. Each node in the tree is 269 either a leaf node or is computed from the two nodes immediately 270 below it (i.e., towards the leaves). At each step up the tree 271 (towards the root), a node from the inclusion proof is combined with 272 the node computed so far. In other words, the inclusion proof 273 consists of the list of missing nodes required to compute the nodes 274 leading from a leaf to the root of the tree. If the root computed 275 from the inclusion proof matches the true root, then the inclusion 276 proof proves that the leaf exists in the tree. 278 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 279 d(n-1)}, the Merkle inclusion proof PATH(m, D[n]) for the (m+1)th 280 input d(m), 0 <= m < n, is defined as follows: 282 The proof for the single leaf in a tree with a one-element input list 283 D[1] = {d(0)} is empty: 285 PATH(0, {d(0)}) = {} 286 For n > 1, let k be the largest power of two smaller than n. The 287 proof for the (m+1)th element d(m) in a list of n > m elements is 288 then defined recursively as 290 PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n]) for m < k; and 292 PATH(m, D[n]) = PATH(m - k, D[k:n]) : MTH(D[0:k]) for m >= k, 294 where : is concatenation of lists and D[k1:k2] denotes the length (k2 295 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 297 2.1.2. Merkle Consistency Proofs 299 Merkle consistency proofs prove the append-only property of the tree. 300 A Merkle consistency proof for a Merkle Tree Hash MTH(D[n]) and a 301 previously advertised hash MTH(D[0:m]) of the first m leaves, m <= n, 302 is the list of nodes in the Merkle Tree required to verify that the 303 first m inputs D[0:m] are equal in both trees. Thus, a consistency 304 proof must contain a set of intermediate nodes (i.e., commitments to 305 inputs) sufficient to verify MTH(D[n]), such that (a subset of) the 306 same nodes can be used to verify MTH(D[0:m]). We define an algorithm 307 that outputs the (unique) minimal consistency proof. 309 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 310 d(n-1)}, the Merkle consistency proof PROOF(m, D[n]) for a previous 311 Merkle Tree Hash MTH(D[0:m]), 0 < m < n, is defined as: 313 PROOF(m, D[n]) = SUBPROOF(m, D[n], true) 315 In SUBPROOF, the boolean value represents whether the subtree created 316 from D[0:m] is a complete subtree of the Merkle Tree created from 317 D[n], and, consequently, whether the subtree Merkle Tree Hash 318 MTH(D[0:m]) is known. The initial call to SUBPROOF sets this to be 319 true, and SUBPROOF is then defined as follows: 321 The subproof for m = n is empty if m is the value for which PROOF was 322 originally requested (meaning that the subtree created from D[0:m] is 323 a complete subtree of the Merkle Tree created from the original D[n] 324 for which PROOF was requested, and the subtree Merkle Tree Hash 325 MTH(D[0:m]) is known): 327 SUBPROOF(m, D[m], true) = {} 329 Otherwise, the subproof for m = n is the Merkle Tree Hash committing 330 inputs D[0:m]: 332 SUBPROOF(m, D[m], false) = {MTH(D[m])} 333 For m < n, let k be the largest power of two smaller than n. The 334 subproof is then defined recursively. 336 If m <= k, the right subtree entries D[k:n] only exist in the current 337 tree. We prove that the left subtree entries D[0:k] are consistent 338 and add a commitment to D[k:n]: 340 SUBPROOF(m, D[n], b) = SUBPROOF(m, D[0:k], b) : MTH(D[k:n]) 342 If m > k, the left subtree entries D[0:k] are identical in both 343 trees. We prove that the right subtree entries D[k:n] are consistent 344 and add a commitment to D[0:k]. 346 SUBPROOF(m, D[n], b) = SUBPROOF(m - k, D[k:n], false) : MTH(D[0:k]) 348 Here, : is a concatenation of lists, and D[k1:k2] denotes the length 349 (k2 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 351 The number of nodes in the resulting proof is bounded above by 352 ceil(log2(n)) + 1. 354 2.1.3. Example 356 The binary Merkle Tree with 7 leaves: 358 hash 359 / \ 360 / \ 361 / \ 362 / \ 363 / \ 364 k l 365 / \ / \ 366 / \ / \ 367 / \ / \ 368 g h i j 369 / \ / \ / \ | 370 a b c d e f d6 371 | | | | | | 372 d0 d1 d2 d3 d4 d5 374 The inclusion proof for d0 is [b, h, l]. 376 The inclusion proof for d3 is [c, g, l]. 378 The inclusion proof for d4 is [f, j, k]. 380 The inclusion proof for d6 is [i, k]. 382 The same tree, built incrementally in four steps: 384 hash0 hash1=k 385 / \ / \ 386 / \ / \ 387 / \ / \ 388 g c g h 389 / \ | / \ / \ 390 a b d2 a b c d 391 | | | | | | 392 d0 d1 d0 d1 d2 d3 394 hash2 hash 395 / \ / \ 396 / \ / \ 397 / \ / \ 398 / \ / \ 399 / \ / \ 400 k i k l 401 / \ / \ / \ / \ 402 / \ e f / \ / \ 403 / \ | | / \ / \ 404 g h d4 d5 g h i j 405 / \ / \ / \ / \ / \ | 406 a b c d a b c d e f d6 407 | | | | | | | | | | 408 d0 d1 d2 d3 d0 d1 d2 d3 d4 d5 410 The consistency proof between hash0 and hash is PROOF(3, D[7]) = [c, 411 d, g, l]. c, g are used to verify hash0, and d, l are additionally 412 used to show hash is consistent with hash0. 414 The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l]. 415 hash can be verified using hash1=k and l. 417 The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i, 418 j, k]. k, i are used to verify hash2, and j is additionally used to 419 show hash is consistent with hash2. 421 2.1.4. Signatures 423 Various data structures are signed. A log MUST use one of the 424 signature algorithms defined in the Section 11.3. 426 3. Submitters 428 Submitters submit certificates or preannouncements of certificates 429 prior to issuance (precertificates) to logs for public auditing, as 430 described below. In order to enable attribution of each logged 431 certificate or precertificate to its issuer, each submission MUST be 432 accompanied by all additional certificates required to verify the 433 chain up to an accepted trust anchor. The trust anchor (a root or 434 intermediate CA certificate) MAY be omitted from the submission. 436 If a log accepts a submission, it will return a Signed Certificate 437 Timestamp (SCT) (see Section 5.6). The submitter SHOULD validate the 438 returned SCT as described in Section 9.2 if they understand its 439 format and they intend to use it directly in a TLS handshake or to 440 construct a certificate. If the submitter does not need the SCT (for 441 example, the certificate is being submitted simply to make it 442 available in the log), it MAY validate the SCT. 444 3.1. Certificates 446 Any entity can submit a certificate (Section 6.1) to a log. Since 447 certificates may not be accepted by TLS clients unless logged, it is 448 expected that certificate owners or their CAs will usually submit 449 them. 451 3.2. Precertificates 453 Alternatively, (root as well as intermediate) CAs may preannounce a 454 certificate prior to issuance by submitting a precertificate 455 (Section 6.2) that the log can use to create an entry that will be 456 valid against the issued certificate. The CA MAY incorporate the 457 returned SCT in the issued certificate. Examples of situations where 458 the returned SCT is not incorporated into the issued certificate 459 would be when a CA sends the precertificate to multiple logs, but 460 only incorporates the SCTs that are returned first, or the CA is 461 using domain name redaction (Section 4.2) and intends to use another 462 mechanism to publish SCTs (such as an OCSP response (Section 8.1.1) 463 or the TLS extension (Section 7.5)). 465 A precertificate is a CMS [RFC5652] "signed-data" object that 466 conforms to the following requirements: 468 o It MUST be DER encoded. 470 o "SignedData.encapContentInfo.eContentType" MUST be the OID 471 1.3.101.78. 473 o "SignedData.encapContentInfo.eContent" MUST contain a 474 TBSCertificate [RFC5280], which MAY redact certain domain name 475 labels that will be present in the issued certificate (see 476 Section 4.2) and MUST NOT contain any SCTs, but which will be 477 otherwise identical to the TBSCertificate in the issued 478 certificate. 480 o "SignedData.signerInfos" MUST contain a signature from the same 481 (root or intermediate) CA that will ultimately issue the 482 certificate. This signature indicates the CA's intent to issue 483 the certificate. This intent is considered binding (i.e. 484 misissuance of the precertificate is considered equivalent to 485 misissuance of the certificate). (Note that, because of the 486 structure of CMS, the signature on the CMS object will not be a 487 valid X.509v3 signature and so cannot be used to construct a 488 certificate from the precertificate). 490 o "SignedData.certificates" SHOULD be omitted. 492 4. Private Domain Name Labels 494 Some regard some DNS domain name labels within their registered 495 domain space as private and security sensitive. Even though these 496 domains are often only accessible within the domain owner's private 497 network, it's common for them to be secured using publicly trusted 498 TLS server certificates. We define a mechanism to allow these 499 private labels to not appear in public logs. 501 4.1. Wildcard Certificates 503 A certificate containing a DNS-ID [RFC6125] of "*.example.com" could 504 be used to secure the domain "topsecret.example.com", without 505 revealing the string "topsecret" publicly. 507 Since TLS clients only match the wildcard character to the complete 508 leftmost label of the DNS domain name (see Section 6.4.3 of 509 [RFC6125]), a different approach is needed when more than one of the 510 leftmost labels in a DNS-ID are considered private (e.g. 511 "top.secret.example.com"). Also, wildcard certificates are 512 prohibited in some cases, such as Extended Validation Certificates 513 [EVSSLGuidelines]. 515 4.2. Redaction of Domain Name Labels 516 4.2.1. Redacting Labels in Precertificates 518 When creating a precertificate, the CA MAY substitute one or more 519 labels in each DNS-ID and CN-ID [RFC6125] with a corresponding number 520 of "?" labels. Every label to the left of a "?" label MUST also be 521 redacted. For example, if a certificate contains a DNS-ID of 522 "top.secret.example.com", then the corresponding DNS-ID in the 523 precertificate could contain "?.?.example.com" instead, but not 524 "top.?.example.com" instead. 526 Wildcard "*" labels MUST NOT be redacted. However, if the complete 527 leftmost label of a DNS-ID or CN-ID is "*", it is considered redacted 528 for the purposes of determining if the label to the right may be 529 redacted. For example, if a certificate contains a DNS-ID of 530 "*.top.secret.example.com", then the corresponding DNS-ID in the 531 precertificate could contain "*.?.?.example.com" instead, but not 532 "?.?.?.example.com" instead. 534 4.2.2. Redacted Labels Certificate Extension 536 When a precertificate contains one or more "?" labels, a non-critical 537 extension (OID 1.3.101.77, whose extnValue OCTET STRING contains an 538 ASN.1 SEQUENCE OF INTEGERs) MUST be added to the corresponding 539 certificate. The purpose of this extension is to enable TLS clients 540 to reconstruct the TBSCertificate component of the precertificate 541 from the certificate, as described in Section 9.2.2. 543 Each INTEGER MUST have a value of zero or more. The first INTEGER 544 indicates the total number of "?" labels in the precertificate's 545 first DNS-ID; the second INTEGER does the same for the 546 precertificate's second DNS-ID; etc. The last INTEGER does the same 547 for the precertificate's zero or more CN-IDs. There MUST NOT be more 548 INTEGERs than there are DNS-IDs (plus one, if any CN-IDs are 549 present); if there are fewer INTEGERs than this, the shortfall is 550 made up by implicitly repeating the last INTEGER. 552 4.3. Using a Name-Constrained Intermediate CA 554 An intermediate CA certificate or intermediate CA precertificate that 555 contains the critical or non-critical Name Constraints [RFC5280] 556 extension MAY be logged in place of end-entity certificates issued by 557 that intermediate CA, as long as all of the following conditions are 558 met: 560 o there MUST be a non-critical extension (OID 1.3.101.76, whose 561 extnValue OCTET STRING contains ASN.1 NULL data (0x05 0x00)). 562 This extension is an explicit indication that it is acceptable to 563 not log certificates issued by this intermediate CA. 565 o permittedSubtrees MUST specify one or more dNSNames. 567 o excludedSubtrees MUST specify the entire IPv4 and IPv6 address 568 ranges. 570 Below is an example Name Constraints extension that meets these 571 conditions: 573 SEQUENCE { 574 OBJECT IDENTIFIER '2 5 29 30' 575 OCTET STRING, encapsulates { 576 SEQUENCE { 577 [0] { 578 SEQUENCE { 579 [2] 'example.com' 580 } 581 } 582 [1] { 583 SEQUENCE { 584 [7] 00 00 00 00 00 00 00 00 585 } 586 SEQUENCE { 587 [7] 588 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 589 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 590 } 591 } 592 } 593 } 594 } 596 5. Log Format and Operation 598 A log is a single, append-only Merkle Tree of submitted certificate 599 and precertificate entries. 601 When it receives a valid submission, the log MUST return an SCT that 602 corresponds to the submitted certificate or precertificate. If the 603 log has previously seen this valid submission, it SHOULD return the 604 same SCT as it returned before (to reduce the ability to track 605 clients as described in Section 12.5). Note that if a certificate 606 was previously logged as a precertificate, then the precertificate's 607 SCT of type "precert_sct_v2" would not be appropriate; instead, a 608 fresh SCT of type "x509_sct_v2" should be generated. 610 An SCT is the log's promise to incorporate the submitted entry in its 611 Merkle Tree no later than a fixed amount of time, known as the 612 Maximum Merge Delay (MMD), after the issuance of the SCT. 614 Periodically, the log MUST append all its new entries to its Merkle 615 Tree and sign the root of the tree. 617 Log operators MUST NOT impose any conditions on retrieving or sharing 618 data from the log. 620 5.1. Accepting Submissions 622 Logs MUST verify that each submitted certificate or precertificate 623 has a valid signature chain to an accepted trust anchor, using the 624 chain of intermediate CA certificates provided by the submitter. 625 Logs MUST accept certificates and precertificates that are fully 626 valid according to RFC 5280 [RFC5280] verification rules and are 627 submitted with such a chain. Logs MAY accept certificates and 628 precertificates that have expired, are not yet valid, have been 629 revoked, or are otherwise not fully valid according to RFC 5280 630 verification rules in order to accommodate quirks of CA certificate- 631 issuing software. However, logs MUST reject submissions without a 632 valid signature chain to an accepted trust anchor. Logs MUST also 633 reject precertificates that do not conform to the requirements in 634 Section 3.2. 636 Logs SHOULD limit the length of chain they will accept. The maximum 637 chain length is specified in the log's metadata. 639 The log SHALL allow retrieval of its list of accepted trust anchors 640 (see Section 6.8), each of which is a root or intermediate CA 641 certificate. This list might usefully be the union of root 642 certificates trusted by major browser vendors. 644 5.2. Log Entries 646 If a submission is accepted and an SCT issued, the accepting log MUST 647 store the entire chain used for verification. This chain MUST 648 include the certificate or precertificate itself, the zero or more 649 intermediate CA certificates provided by the submitter, and the trust 650 anchor used to verify the chain (even if it was omitted from the 651 submission). The log MUST present this chain for auditing upon 652 request (see Section 6.7). This chain is required to prevent a CA 653 from avoiding blame by logging a partial or empty chain. 655 Each certificate entry in a log MUST include a "X509ChainEntry" 656 structure, and each precertificate entry MUST include a 657 "PrecertChainEntryV2" structure: 659 opaque ASN.1Cert<1..2^24-1>; 661 struct { 662 ASN.1Cert leaf_certificate; 663 ASN.1Cert certificate_chain<0..2^24-1>; 664 } X509ChainEntry; 666 opaque CMSPrecert<1..2^24-1>; 668 struct { 669 CMSPrecert pre_certificate; 670 ASN.1Cert precertificate_chain<1..2^24-1>; 671 } PrecertChainEntryV2; 673 "leaf_certificate" is a submitted certificate that has been accepted 674 by the log. 676 "certificate_chain" is a vector of 0 or more additional certificates 677 required to verify "leaf_certificate". The first certificate MUST 678 certify "leaf_certificate". Each following certificate MUST directly 679 certify the one preceding it. The final certificate MUST be a trust 680 anchor accepted by the log. If "leaf_certificate" is an accepted 681 trust anchor, then this vector is empty. 683 "pre_certificate" is a submitted precertificate that has been 684 accepted by the log. 686 "precertificate_chain" is a vector of 1 or more additional 687 certificates required to verify "pre_certificate". The first 688 certificate MUST certify "pre_certificate". Each following 689 certificate MUST directly certify the one preceding it. The final 690 certificate MUST be a trust anchor accepted by the log. 692 5.3. Log ID 694 Each log is uniquely identified by an OID. A log's operator MUST 695 either allocate the OID themselves or request an OID from one of the 696 two Log ID Registries (see Section 11.6.1 and Section 11.6.2). The 697 OID is specified in the log's metadata. Various data structures 698 include the DER encoding of this OID, excluding the ASN.1 tag and 699 length bytes, in an opaque vector: 701 opaque LogID<2..127>; 703 Note that the ASN.1 length and the opaque vector length are identical 704 in size (1 byte) and value, so the DER encoding of the OID can be 705 reproduced simply by prepending an OBJECT IDENTIFIER tag (0x06) to 706 the opaque vector length and contents. 708 5.4. TransItem Structure 710 Various data structures are encapsulated in the "TransItem" structure 711 to ensure that the type and version of each one is identified in a 712 common fashion: 714 enum { 715 reserved(0), 716 x509_entry_v2(1), precert_entry_v2(2), 717 x509_sct_v2(3), precert_sct_v2(4), 718 tree_head_v2(5), signed_tree_head_v2(6), 719 consistency_proof_v2(7), inclusion_proof_v2(8), 720 x509_sct_with_proof_v2(9), precert_sct_with_proof_v2(10), 721 (65535) 722 } VersionedTransType; 724 struct { 725 VersionedTransType versioned_type; 726 select (versioned_type) { 727 case x509_entry_v2: TimestampedCertificateEntryDataV2; 728 case precert_entry_v2: TimestampedCertificateEntryDataV2; 729 case x509_sct_v2: SignedCertificateTimestampDataV2; 730 case precert_sct_v2: SignedCertificateTimestampDataV2; 731 case tree_head_v2: TreeHeadDataV2; 732 case signed_tree_head_v2: SignedTreeHeadDataV2; 733 case consistency_proof_v2: ConsistencyProofDataV2; 734 case inclusion_proof_v2: InclusionProofDataV2; 735 case x509_sct_with_proof_v2: SCTWithProofDataV2; 736 case precert_sct_with_proof_v2: SCTWithProofDataV2; 737 } data; 738 } TransItem; 740 "versioned_type" is the type of the encapsulated data structure and 741 the earliest version of this protocol to which it conforms. This 742 document is v2. 744 "data" is the encapsulated data structure. The various structures 745 named with the "DataV2" suffix are defined in later sections of this 746 document. 748 Note that "VersionedTransType" combines the v1 [RFC6962] type 749 enumerations "Version", "LogEntryType", "SignatureType" and 750 "MerkleLeafType". Note also that v1 did not define "TransItem", but 751 this document provides guidelines (see Appendix A) on how v2 752 implementations can co-exist with v1 implementations. 754 Future versions of this protocol may reuse "VersionedTransType" 755 values defined in this document as long as the corresponding data 756 structures are not modified, and may add new "VersionedTransType" 757 values for new or modified data structures. 759 5.5. Merkle Tree Leaves 761 The leaves of a log's Merkle Tree correspond to the log's entries 762 (see Section 5.2). Each leaf is the leaf hash (Section 2.1) of a 763 "TransItem" structure of type "x509_entry_v2" or "precert_entry_v2", 764 which encapsulates a "TimestampedCertificateEntryDataV2" structure. 765 Note that leaf hashes are calculated as HASH(0x00 || TransItem), 766 where the hashing algorithm is specified in the log's metadata. 768 opaque TBSCertificate<1..2^24-1>; 770 struct { 771 uint64 timestamp; 772 opaque issuer_key_hash[HASH_SIZE]; 773 TBSCertificate tbs_certificate; 774 SctExtension sct_extensions<0..2^16-1>; 775 } TimestampedCertificateEntryDataV2; 777 "timestamp" is the NTP Time [RFC5905] at which the certificate or 778 precertificate was accepted by the log, measured in milliseconds 779 since the epoch (January 1, 1970, 00:00), ignoring leap seconds. 780 Note that the leaves of a log's Merkle Tree are not required to be in 781 strict chronological order. 783 "issuer_key_hash" is the HASH of the public key of the CA that issued 784 the certificate or precertificate, calculated over the DER encoding 785 of the key represented as SubjectPublicKeyInfo [RFC5280]. This is 786 needed to bind the CA to the certificate or precertificate, making it 787 impossible for the corresponding SCT to be valid for any other 788 certificate or precertificate whose TBSCertificate matches 789 "tbs_certificate". 791 "tbs_certificate" is the DER encoded TBSCertificate from either the 792 "leaf_certificate" (in the case of an "X509ChainEntry") or the 793 "pre_certificate" (in the case of a "PrecertChainEntryV2"). (Note 794 that a precertificate's TBSCertificate can be reconstructed from the 795 corresponding certificate as described in Section 9.2.2). 797 "sct_extensions" matches the SCT extensions of the corresponding SCT. 799 5.6. Signed Certificate Timestamp (SCT) 801 An SCT is a "TransItem" structure of type "x509_sct_v2" or 802 "precert_sct_v2", which encapsulates a 803 "SignedCertificateTimestampDataV2" structure: 805 enum { 806 reserved(65535) 807 } SctExtensionType; 809 struct { 810 SctExtensionType sct_extension_type; 811 opaque sct_extension_data<0..2^16-1>; 812 } SctExtension; 814 struct { 815 LogID log_id; 816 uint64 timestamp; 817 SctExtension sct_extensions<0..2^16-1>; 818 digitally-signed struct { 819 TransItem timestamped_entry; 820 } signature; 821 } SignedCertificateTimestampDataV2; 823 "log_id" is this log's unique ID, encoded in an opaque vector as 824 described in Section 5.3. 826 "timestamp" is equal to the timestamp from the 827 "TimestampedCertificateEntryDataV2" structure encapsulated in the 828 "timestamped_entry". 830 "sct_extension_type" identifies a single extension from the IANA 831 registry in Section 11.4. At the time of writing, no extensions are 832 specified. 834 The interpretation of the "sct_extension_data" field is determined 835 solely by the value of the "sct_extension_type" field. Each document 836 that registers a new "sct_extension_type" must describe how to 837 interpret the corresponding "sct_extension_data". 839 "sct_extensions" is a vector of 0 or more SCT extensions. This 840 vector MUST NOT include more than one extension with the same 841 "sct_extension_type". The extensions in the vector MUST be ordered 842 by the value of the "sct_extension_type" field, smallest value first. 843 If an implementation sees an extension that it does not understand, 844 it SHOULD ignore that extension. Furthermore, an implementation MAY 845 choose to ignore any extension(s) that it does understand. 847 The encoding of the digitally-signed element is defined in [RFC5246]. 849 "timestamped_entry" is a "TransItem" structure that MUST be of type 850 "x509_entry_v2" or "precert_entry_v2" (see Section 5.5). 852 5.7. Merkle Tree Head 854 The log stores information about its Merkle Tree in a "TransItem" 855 structure of type "tree_head_v2", which encapsulates a 856 "TreeHeadDataV2" structure: 858 opaque NodeHash[HASH_SIZE]; 860 struct { 861 uint64 timestamp; 862 uint64 tree_size; 863 NodeHash root_hash; 864 SthExtension sth_extensions<0..2^16-1>; 865 } TreeHeadDataV2; 867 "timestamp" is the current NTP Time [RFC5905], measured in 868 milliseconds since the epoch (January 1, 1970, 00:00), ignoring leap 869 seconds. 871 "tree_size" is the number of entries currently in the log's Merkle 872 Tree. 874 "root_hash" is the root of the Merkle Hash Tree. 876 "sth_extensions" matches the STH extensions of the corresponding STH. 878 5.8. Signed Tree Head (STH) 880 Periodically each log SHOULD sign its current tree head information 881 (see Section 5.7) to produce an STH. When a client requests a log's 882 latest STH (see Section 6.3), the log MUST return an STH that is no 883 older than the log's MMD. However, STHs could be used to mark 884 individual clients (by producing a new one for each query), so logs 885 MUST NOT produce them more frequently than is declared in their 886 metadata. In general, there is no need to produce a new STH unless 887 there are new entries in the log; however, in the unlikely event that 888 it receives no new submissions during an MMD period, the log SHALL 889 sign the same Merkle Tree Hash with a fresh timestamp. 891 An STH is a "TransItem" structure of type "signed_tree_head_v2", 892 which encapsulates a "SignedTreeHeadDataV2" structure: 894 enum { 895 reserved(65535) 896 } SthExtensionType; 898 struct { 899 SthExtensionType sth_extension_type; 900 opaque sth_extension_data<0..2^16-1>; 901 } SthExtension; 903 struct { 904 LogID log_id; 905 uint64 timestamp; 906 uint64 tree_size; 907 NodeHash root_hash; 908 SthExtension sth_extensions<0..2^16-1>; 909 digitally-signed struct { 910 TransItem merkle_tree_head; 911 } signature; 912 } SignedTreeHeadDataV2; 914 "log_id" is this log's unique ID, encoded in an opaque vector as 915 described in Section 5.3. 917 "timestamp" is equal to the timestamp from the "TreeHeadDataV2" 918 structure encapsulated in "merkle_tree_head". This timestamp MUST be 919 at least as recent as the most recent SCT timestamp in the tree. 920 Each subsequent timestamp MUST be more recent than the timestamp of 921 the previous update. 923 "tree_size" is equal to the tree size from the "TreeHeadDataV2" 924 structure encapsulated in "merkle_tree_head". 926 "root_hash" is equal to the root hash from the "TreeHeadDataV2" 927 structure encapsulated in "merkle_tree_head". 929 "sth_extension_type" identifies a single extension from the IANA 930 registry in Section 11.5. At the time of writing, no extensions are 931 specified. 933 The interpretation of the "sth_extension_data" field is determined 934 solely by the value of the "sth_extension_type" field. Each document 935 that registers a new "sth_extension_type" must describe how to 936 interpret the corresponding "sth_extension_data". 938 "sth_extensions" is a vector of 0 or more STH extensions. This 939 vector MUST NOT include more than one extension with the same 940 "sth_extension_type". The extensions in the vector MUST be ordered 941 by the value of the "sth_extension_type" field, smallest value first. 942 If an implementation sees an extension that it does not understand, 943 it SHOULD ignore that extension. Furthermore, an implementation MAY 944 choose to ignore any extension(s) that it does understand. 946 "merkle_tree_head" is a "TransItem" structure that MUST be of type 947 "tree_head_v2" (see Section 5.7). 949 5.9. Merkle Consistency Proofs 951 To prepare a Merkle Consistency Proof for distribution to clients, 952 the log produces a "TransItem" structure of type 953 "consistency_proof_v2", which encapsulates a "ConsistencyProofDataV2" 954 structure: 956 struct { 957 LogID log_id; 958 uint64 tree_size_1; 959 uint64 tree_size_2; 960 NodeHash consistency_path<1..2^8-1>; 961 } ConsistencyProofDataV2; 963 "log_id" is this log's unique ID, encoded in an opaque vector as 964 described in Section 5.3. 966 "tree_size_1" is the size of the older tree. 968 "tree_size_2" is the size of the newer tree. 970 "consistency_path" is a vector of Merkle Tree nodes proving the 971 consistency of two STHs. 973 5.10. Merkle Inclusion Proofs 975 To prepare a Merkle Inclusion Proof for distribution to clients, the 976 log produces a "TransItem" structure of type "inclusion_proof_v2", 977 which encapsulates an "InclusionProofDataV2" 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 5.11. Shutting down a log 1000 Log operators may decide to shut down a log for various reasons, such 1001 as deprecation of the signature algorithm. If there are entries in 1002 the log for certificates that have not yet expired, simply making TLS 1003 clients stop recognizing that log will have the effect of 1004 invalidating SCTs from that log. To avoid that, the following 1005 actions are suggested: 1007 o Make it known to clients and monitors that the log will be frozen. 1009 o Stop accepting new submissions (the error code "shutdown" should 1010 be returned for such requests). 1012 o Once MMD from the last accepted submission has passed and all 1013 pending submissions are incorporated, issue a final STH and 1014 publish it as a part of the log's metadata. Having an STH with a 1015 timestamp that is after the MMD has passed from the last SCT 1016 issuance allows clients to audit this log regularly without 1017 special handling for the final STH. At this point the log's 1018 private key is no longer needed and can be destroyed. 1020 o Keep the log running until the certificates in all of its entries 1021 have expired or exist in other logs (this can be determined by 1022 scanning other logs or connecting to domains mentioned in the 1023 certificates and inspecting the SCTs served). 1025 6. Log Client Messages 1027 Messages are sent as HTTPS GET or POST requests. Parameters for 1028 POSTs and all responses are encoded as JavaScript Object Notation 1029 (JSON) objects [RFC4627]. Parameters for GETs are encoded as order- 1030 independent key/value URL parameters, using the "application/x-www- 1031 form-urlencoded" format described in the "HTML 4.01 Specification" 1032 [HTML401]. Binary data is base64 encoded [RFC4648] as specified in 1033 the individual messages. 1035 Note that JSON objects and URL parameters may contain fields not 1036 specified here. These extra fields should be ignored. 1038 The prefix, which is part of the log's metadata, MAY 1039 include a path as well as a server name and a port. 1041 In practice, log servers may include multiple front-end machines. 1042 Since it is impractical to keep these machines in perfect sync, 1043 errors may occur that are caused by skew between the machines. Where 1044 such errors are possible, the front-end will return additional 1045 information (as specified below) making it possible for clients to 1046 make progress, if progress is possible. Front-ends MUST only serve 1047 data that is free of gaps (that is, for example, no front-end will 1048 respond with an STH unless it is also able to prove consistency from 1049 all log entries logged within that STH). 1051 For example, when a consistency proof between two STHs is requested, 1052 the front-end reached may not yet be aware of one or both STHs. In 1053 the case where it is unaware of both, it will return the latest STH 1054 it is aware of. Where it is aware of the first but not the second, 1055 it will return the latest STH it is aware of and a consistency proof 1056 from the first STH to the returned STH. The case where it knows the 1057 second but not the first should not arise (see the "no gaps" 1058 requirement above). 1060 If the log is unable to process a client's request, it MUST return an 1061 HTTP response code of 4xx/5xx (see [RFC2616]), and, in place of the 1062 responses outlined in the subsections below, the body SHOULD be a 1063 JSON structure containing at least the following field: 1065 error_message: A human-readable string describing the error which 1066 prevented the log from processing the request. 1068 In the case of a malformed request, the string SHOULD provide 1069 sufficient detail for the error to be rectified. 1071 error_code: An error code readable by the client. Some codes are 1072 generic and are detailed here. Others are detailed in the 1073 individual requests. Error codes are fixed text strings. 1075 not compliant The request is not compliant with this RFC. 1077 e.g. In response to a request of "/ct/v2/get- 1078 entries?start=100&end=99", the log would return a "400 Bad Request" 1079 response code with a body similar to the following: 1081 { 1082 "error_message": "'start' cannot be greater than 'end'", 1083 "error_code": "not compliant", 1084 } 1086 Clients SHOULD treat "500 Internal Server Error" and "503 Service 1087 Unavailable" responses as transient failures and MAY retry the same 1088 request without modification at a later date. Note that as per 1089 [RFC2616], in the case of a 503 response the log MAY include a 1090 "Retry-After:" header in order to request a minimum time for the 1091 client to wait before retrying the request. 1093 6.1. Add Chain to Log 1095 POST https:///ct/v2/add-chain 1097 Inputs: 1099 chain: An array of base64 encoded certificates. The first 1100 element is the certificate for which the submitter desires an 1101 SCT; the second certifies the first and so on to the last, 1102 which either is, or is certified by, an accepted trust anchor. 1104 Outputs: 1106 sct: A base64 encoded "TransItem" of type "x509_sct_v2", signed 1107 by this log, that corresponds to the submitted certificate. 1109 Error codes: 1111 unknown anchor The last certificate in the chain both is not, and 1112 is not certified by, an accepted trust anchor. 1114 bad chain The alleged chain is not actually a chain of 1115 certificates. 1117 bad certificate One or more certificates in the chain are not 1118 valid (e.g. not properly encoded). 1120 shutdown The log has ceased operation and is not accepting new 1121 submissions. 1123 If the version of "sct" is not v2, then a v2 client may be unable to 1124 verify the signature. It MUST NOT construe this as an error. This 1125 is to avoid forcing an upgrade of compliant v2 clients that do not 1126 use the returned SCTs. 1128 If a log detects bad encoding in a chain that otherwise verifies 1129 correctly then the log MAY still log the certificate but SHOULD NOT 1130 return an SCT. It should instead return the "bad certificate" error. 1131 Logging the certificate is useful, because monitors (Section 9.3) can 1132 then detect these encoding errors, which may be accepted by some TLS 1133 clients. 1135 Note that not all certificate handling software is capable of 1136 detecting all encoding errors (e.g. some software will accept BER 1137 instead of DER encodings in certificates, or incorrect character 1138 encodings, even though these are technically incorrect) . 1140 6.2. Add PreCertChain to Log 1142 POST https:///ct/v2/add-pre-chain 1144 Inputs: 1146 precertificate: The base64 encoded precertificate. 1148 chain: An array of base64 encoded CA certificates. The first 1149 element is the signer of the precertificate; the second 1150 certifies the first and so on to the last, which either is, or 1151 is certified by, an accepted trust anchor. 1153 Outputs: 1155 sct: A base64 encoded "TransItem" of type "precert_sct_v2", 1156 signed by this log, that corresponds to the submitted 1157 precertificate. 1159 Errors are the same as in Section 6.1. 1161 6.3. Retrieve Latest Signed Tree Head 1163 GET https:///ct/v2/get-sth 1165 No inputs. 1167 Outputs: 1169 sth: A base64 encoded "TransItem" of type "signed_tree_head_v2", 1170 signed by this log, that is no older than the log's MMD. 1172 6.4. Retrieve Merkle Consistency Proof between Two Signed Tree Heads 1174 GET https:///ct/v2/get-sth-consistency 1176 Inputs: 1178 first: The tree_size of the older tree, in decimal. 1180 second: The tree_size of the newer tree, in decimal (optional). 1182 Both tree sizes must be from existing v2 STHs. However, because 1183 of skew, the receiving front-end may not know one or both of the 1184 existing STHs. If both are known, then only the "consistency" 1185 output is returned. If the first is known but the second is not 1186 (or has been omitted), then the latest known STH is returned, 1187 along with a consistency proof between the first STH and the 1188 latest. If neither are known, then the latest known STH is 1189 returned without a consistency proof. 1191 Outputs: 1193 consistency: A base64 encoded "TransItem" of type 1194 "consistency_proof_v2", whose "tree_size_1" MUST match the 1195 "first" input. If the "sth" output is omitted, then 1196 "tree_size_2" MUST match the "second" input. 1198 sth: A base64 encoded "TransItem" of type "signed_tree_head_v2", 1199 signed by this log. 1201 Note that no signature is required for the "consistency" output as 1202 it is used to verify the consistency between two STHs, which are 1203 signed. 1205 Error codes: 1207 first unknown "first" is before the latest known STH but is not 1208 from an existing STH. 1210 second unknown "second" is before the latest known STH but is not 1211 from an existing STH. 1213 See Section 9.4.2 for an outline of how to use the "consistency" 1214 output. 1216 6.5. Retrieve Merkle Inclusion Proof from Log by Leaf Hash 1218 GET https:///ct/v2/get-proof-by-hash 1220 Inputs: 1222 hash: A base64 encoded v2 leaf hash. 1224 tree_size: The tree_size of the tree on which to base the proof, 1225 in decimal. 1227 The "hash" must be calculated as defined in Section 5.5. The 1228 "tree_size" must designate an existing v2 STH. Because of skew, 1229 the front-end may not know the requested STH. In that case, it 1230 will return the latest STH it knows, along with an inclusion proof 1231 to that STH. If the front-end knows the requested STH then only 1232 "inclusion" is returned. 1234 Outputs: 1236 inclusion: A base64 encoded "TransItem" of type 1237 "inclusion_proof_v2" whose "inclusion_path" array of Merkle 1238 Tree nodes proves the inclusion of the chosen certificate in 1239 the selected STH. 1241 sth: A base64 encoded "TransItem" of type "signed_tree_head_v2", 1242 signed by this log. 1244 Note that no signature is required for the "inclusion" output as 1245 it is used to verify inclusion in the selected STH, which is 1246 signed. 1248 Error codes: 1250 hash unknown "hash" is not the hash of a known leaf (may be 1251 caused by skew or by a known certificate not yet merged). 1253 tree_size unknown "hash" is before the latest known STH but is 1254 not from an existing STH. 1256 See Section 9.4.1 for an outline of how to use the "inclusion" 1257 output. 1259 6.6. Retrieve Merkle Inclusion Proof, Signed Tree Head and Consistency 1260 Proof by Leaf Hash 1262 GET https:///ct/v2/get-all-by-hash 1264 Inputs: 1266 hash: A base64 encoded v2 leaf hash. 1268 tree_size: The tree_size of the tree on which to base the proofs, 1269 in decimal. 1271 The "hash" must be calculated as defined in Section 5.5. The 1272 "tree_size" must designate an existing v2 STH. 1274 Because of skew, the front-end may not know the requested STH or 1275 the requested hash, which leads to a number of cases. 1277 latest STH < requested STH Return latest STH. 1279 latest STH > requested STH Return latest STH and a consistency 1280 proof between it and the requested STH (see Section 6.4). 1282 index of requested hash < latest STH Return "inclusion". 1284 Note that more than one case can be true, in which case the 1285 returned data is their concatenation. It is also possible for 1286 none to be true, in which case the front-end MUST return an empty 1287 response. 1289 Outputs: 1291 inclusion: A base64 encoded "TransItem" of type 1292 "inclusion_proof_v2" whose "inclusion_path" array of Merkle 1293 Tree nodes proves the inclusion of the chosen certificate in 1294 the selected STH. 1296 sth: A base64 encoded "TransItem" of type "signed_tree_head_v2", 1297 signed by this log. 1299 consistency: A base64 encoded "TransItem" of type 1300 "consistency_proof_v2" that proves the consistency of the 1301 requested STH and the returned STH. 1303 Note that no signature is required for the "inclusion" or 1304 "consistency" outputs as they are used to verify inclusion in and 1305 consistency of STHs, which are signed. 1307 Errors are the same as in Section 6.5. 1309 See Section 9.4.1 for an outline of how to use the "inclusion" 1310 output, and see Section 9.4.2 for an outline of how to use the 1311 "consistency" output. 1313 6.7. Retrieve Entries and STH from Log 1315 GET https:///ct/v2/get-entries 1317 Inputs: 1319 start: 0-based index of first entry to retrieve, in decimal. 1321 end: 0-based index of last entry to retrieve, in decimal. 1323 Outputs: 1325 entries: An array of objects, each consisting of 1327 leaf_input: The base64 encoded "TransItem" structure of type 1328 "x509_entry_v2" or "precert_entry_v2" (see Section 5.5). 1330 log_entry: The base64 encoded log entry (see Section 5.2). In 1331 the case of an "x509_entry_v2" entry, this is the whole 1332 "X509ChainEntry"; and in the case of a "precert_entry_v2", 1333 this is the whole "PrecertChainEntryV2". 1335 sct: A base64 encoded "TransItem" of type "x509_sct_v2" or 1336 "precert_sct_v2" corresponding to this log entry. Note that 1337 more than one SCT may have been returned for the same entry 1338 - only one of those is returned in this field. It may not 1339 be possible to retrieve others. 1341 sth: A base64 encoded "TransItem" of type "signed_tree_head_v2", 1342 signed by this log. 1344 Note that this message is not signed -- the "entries" data can be 1345 verified by constructing the Merkle Tree Hash corresponding to a 1346 retrieved STH. All leaves MUST be v2. However, a compliant v2 1347 client MUST NOT construe an unrecognized TransItem type as an error. 1348 This means it may be unable to parse some entries, but note that each 1349 client can inspect the entries it does recognize as well as verify 1350 the integrity of the data by treating unrecognized leaves as opaque 1351 input to the tree. 1353 The "start" and "end" parameters SHOULD be within the range 0 <= x < 1354 "tree_size" as returned by "get-sth" in Section 6.3. 1356 The "start" parameter MUST be less than or equal to the "end" 1357 parameter. 1359 Log servers MUST honor requests where 0 <= "start" < "tree_size" and 1360 "end" >= "tree_size" by returning a partial response covering only 1361 the valid entries in the specified range. "end" >= "tree_size" could 1362 be caused by skew. Note that the following restriction may also 1363 apply: 1365 Logs MAY restrict the number of entries that can be retrieved per 1366 "get-entries" request. If a client requests more than the permitted 1367 number of entries, the log SHALL return the maximum number of entries 1368 permissible. These entries SHALL be sequential beginning with the 1369 entry specified by "start". 1371 Because of skew, it is possible the log server will not have any 1372 entries between "start" and "end". In this case it MUST return an 1373 empty "entries" array. 1375 In any case, the log server MUST return the latest STH it knows 1376 about. 1378 See Section 9.4.3 for an outline of how to use a complete list of 1379 "leaf_input" entries to verify the "root_hash". 1381 6.8. Retrieve Accepted Trust Anchors 1383 GET https:///ct/v2/get-anchors 1385 No inputs. 1387 Outputs: 1389 certificates: An array of base64 encoded trust anchors that are 1390 acceptable to the log. 1392 max_chain: If the server has chosen to limit the length of chains 1393 it accepts, this is the maximum number of certificates in the 1394 chain, in decimal. If there is no limit, this is omitted. 1396 7. TLS Servers 1398 TLS servers MUST use at least one of the three mechanisms listed 1399 below to present one or more SCTs from one or more logs to each TLS 1400 client during full TLS handshakes, where each SCT corresponds to the 1401 server certificate or to a name-constrained intermediate the server 1402 certificate chains to. TLS servers SHOULD also present corresponding 1403 inclusion proofs and STHs (see Section 7.3). 1405 Three mechanisms are provided because they have different tradeoffs. 1407 o A TLS extension (Section 7.4.1.4 of [RFC5246]) with type 1408 "transparency_info" (see Section 7.5). This mechanism allows TLS 1409 servers to participate in CT without the cooperation of CAs, 1410 unlike the other two mechanisms. It also allows SCTs and 1411 inclusion proofs to be updated on the fly. 1413 o An Online Certificate Status Protocol (OCSP) [RFC6960] response 1414 extension (see Section 8.1.1), where the OCSP response is provided 1415 in the "CertificateStatus" message, provided that the TLS client 1416 included the "status_request" extension in the (extended) 1417 "ClientHello" (Section 8 of [RFC6066]). This mechanism, popularly 1418 known as OCSP stapling, is already widely (but not universally) 1419 implemented. It also allows SCTs and inclusion proofs to be 1420 updated on the fly. 1422 o An X509v3 certificate extension (see Section 8.1.2). This 1423 mechanism allows the use of unmodified TLS servers, but the SCTs 1424 and inclusion proofs cannot be updated on the fly. Since the logs 1425 from where the SCTs and inclusion proofs originated won't 1426 necessarily be accepted by TLS clients for the full lifetime of 1427 the certificate, there is a risk that TLS clients will 1428 subsequently consider the certificate to be non-compliant and in 1429 need of re-issuance. 1431 Additionally, a TLS server which supports presenting SCTs using an 1432 OCSP response MAY provide it when the TLS client included the 1433 "status_request_v2" extension ([RFC6961]) in the (extended) 1434 "ClientHello", but only in addition to at least one of the three 1435 mechanisms listed above. 1437 7.1. Multiple SCTs 1439 TLS servers SHOULD send SCTs from multiple logs in case one or more 1440 logs are not acceptable to the TLS client (for example, if a log has 1441 been struck off for misbehavior, has had a key compromise, or is not 1442 known to the TLS client). For example: 1444 o If a CA and a log collude, it is possible to temporarily hide 1445 misissuance from clients. Including SCTs from different logs 1446 makes it more difficult to mount this attack. 1448 o If a log misbehaves, a consequence may be that clients cease to 1449 trust it. Since the time an SCT may be in use can be considerable 1450 (several years is common in current practice when embedded in a 1451 certificate), servers may wish to reduce the probability of their 1452 certificates being rejected as a result by including SCTs from 1453 different logs. 1455 o TLS clients may have policies related to the above risks requiring 1456 servers to present multiple SCTs. For example, at the time of 1457 writing, Chromium [Chromium.Log.Policy] requires multiple SCTs to 1458 be presented with EV certificates in order for the EV indicator to 1459 be shown. 1461 To select the logs from which to obtain SCTs, a TLS server can, for 1462 example, examine the set of logs popular TLS clients accept and 1463 recognize. 1465 7.2. TransItemList Structure 1467 Multiple SCTs, inclusion proofs, and indeed "TransItem" structures of 1468 any type, are combined into a list as follows: 1470 opaque SerializedTransItem<1..2^16-1>; 1472 struct { 1473 SerializedTransItem trans_item_list<1..2^16-1>; 1474 } TransItemList; 1476 Here, "SerializedTransItem" is an opaque byte string that contains 1477 the serialized "TransItem" structure. This encoding ensures that TLS 1478 clients can decode each "TransItem" individually (so, for example, if 1479 there is a version upgrade, out-of-date clients can still parse old 1480 "TransItem" structures while skipping over new "TransItem" structures 1481 whose versions they don't understand). 1483 7.3. Presenting SCTs, inclusion proofs and STHs 1484 When constructing a "TransItemList" structure, a TLS server SHOULD 1485 construct and include "TransItem" structures of type 1486 "x509_sct_with_proof_v2" (for an SCT of type "x509_sct_v2") or 1487 "precert_sct_with_proof_v2" (for an SCT of type "precert_sct_v2"), 1488 both of which encapsulate a "SCTWithProofDataV2" structure: 1490 struct { 1491 SignedCertificateTimestampDataV2 sct; 1492 SignedTreeHeadDataV2 sth; 1493 InclusionProofDataV2 inclusion_proof; 1494 } SCTWithProofDataV2; 1496 "sct" is the encapsulated data structure from an SCT that corresponds 1497 to the server certificate or to a name-constrained intermediate the 1498 server certificate chains to. 1500 "sth" is the encapsulated data structure from an STH that was signed 1501 by the same log as "sct". 1503 "inclusion_proof" is the encapsulated data structure from an 1504 inclusion proof that corresponds to "sct" and can be used to compute 1505 the root in "sth". 1507 7.4. Presenting SCTs only 1509 Presenting inclusion proofs and STHs in the TLS handshake helps to 1510 protect the client's privacy (see Section 9.2.4) and reduces load on 1511 log servers. However, if a TLS server is unable to obtain an 1512 inclusion proof and STH that correspond to an SCT, then it MUST 1513 include "TransItem" structures of type "x509_sct_v2" or 1514 "precert_sct_v2" in the "TransItemList". 1516 7.5. transparency_info TLS Extension 1518 Provided that a TLS client includes the "transparency_info" extension 1519 type in the ClientHello, the TLS server SHOULD include the 1520 "transparency_info" extension in the ServerHello with 1521 "extension_data" set to a "TransItemList". The TLS server SHOULD 1522 ignore any "extension_data" sent by the TLS client. Additionally, 1523 the TLS server MUST NOT process or include this extension when a TLS 1524 session is resumed, since session resumption uses the original 1525 session information. 1527 8. Certification Authorities 1528 8.1. Transparency Information X.509v3 Extension 1530 The Transparency Information X.509v3 extension, which has OID 1531 1.3.101.75 and SHOULD be non-critical, contains one or more 1532 "TransItem" structures in a "TransItemList". This extension MAY be 1533 included in OCSP responses (see Section 8.1.1) and certificates (see 1534 Section 8.1.2). Since RFC5280 requires the "extnValue" field (an 1535 OCTET STRING) of each X.509v3 extension to include the DER encoding 1536 of an ASN.1 value, a "TransItemList" MUST NOT be included directly. 1537 Instead, it MUST be wrapped inside an additional OCTET STRING, which 1538 is then put into the "extnValue" field: 1540 TransparencyInformationSyntax ::= OCTET STRING 1542 "TransparencyInformationSyntax" contains a "TransItemList". 1544 8.1.1. OCSP Response Extension 1546 A certification authority MAY include a Transparency Information 1547 X.509v3 extension in the "singleExtensions" of a "SingleResponse" in 1548 an OCSP response. The included SCTs or inclusion proofs MUST be for 1549 the certificate identified by the "certID" of that "SingleResponse", 1550 or for a precertificate that corresponds to that certificate, or for 1551 a name-constrained intermediate to which that certificate chains. 1553 8.1.2. Certificate Extension 1555 A certification authority MAY include a Transparency Information 1556 X.509v3 extension in a certificate. Any included SCTs or inclusion 1557 proofs MUST be either for a precertificate that corresponds to this 1558 certificate, or for a name-constrained intermediate to which this 1559 certificate chains. 1561 8.2. TLS Feature Extension 1563 A certification authority MAY include the transparency_info 1564 (Section 7.5) TLS extension identifier in the TLS Feature [RFC7633] 1565 certificate extension in root, intermediate and end-entity 1566 certificates. When a certificate chain includes such a certificate, 1567 this indicates that CT compliance is required. 1569 9. Clients 1571 There are various different functions clients of logs might perform. 1572 We describe here some typical clients and how they should function. 1573 Any inconsistency may be used as evidence that a log has not behaved 1574 correctly, and the signatures on the data structures prevent the log 1575 from denying that misbehavior. 1577 All clients need various metadata in order to communicate with logs 1578 and verify their responses. This metadata is described below, but 1579 note that this document does not describe how the metadata is 1580 obtained, which is implementation dependent (see, for example, 1581 [Chromium.Policy]). 1583 Clients should somehow exchange STHs they see, or make them available 1584 for scrutiny, in order to ensure that they all have a consistent 1585 view. The exact mechanisms will be in separate documents, but it is 1586 expected there will be a variety. 1588 9.1. Metadata 1590 In order to communicate with and verify a log, clients need metadata 1591 about the log. 1593 Base URL: The URL to substitute for in Section 6. 1595 Hash Algorithm The hash algorithm used for the Merkle Tree (see 1596 Section 11.2). 1598 Signing Algorithm The signing algorithm used (see Section 2.1.4). 1600 Public Key The public key used to verify signatures generated by the 1601 log. A log MUST NOT use the same keypair as any other log. 1603 Log ID The OID that uniquely identifies the log. 1605 Maximum Merge Delay The MMD the log has committed to. 1607 Version The version of the protocol supported by the log (currently 1608 1 or 2). 1610 Maximum Chain Length The longest chain submission the log is willing 1611 to accept, if the log chose to limit it. 1613 STH Frequency Count The maximum number of STHs the log may produce 1614 in any period equal to the "Maximum Merge Delay" (see 1615 Section 5.8). 1617 Final STH If a log has been closed down (i.e. no longer accepts new 1618 entries), existing entries may still be valid. In this case, the 1619 client should know the final valid STH in the log to ensure no new 1620 entries can be added without detection. 1622 [JSON.Metadata] is an example of a metadata format which includes the 1623 above elements. 1625 9.2. TLS Client 1627 9.2.1. Receiving SCTs 1629 TLS clients receive SCTs alongside or in certificates. TLS clients 1630 MUST implement all of the three mechanisms by which TLS servers may 1631 present SCTs (see Section 7). TLS clients MAY also accept SCTs via 1632 the "status_request_v2" extension ([RFC6961]). TLS clients that 1633 support the "transparency_info" TLS extension SHOULD include it in 1634 ClientHello messages, with empty "extension_data". TLS clients may 1635 also receive inclusion proofs in addition to SCTs, which should be 1636 checked once the SCTs are validated. 1638 9.2.2. Reconstructing the TBSCertificate 1640 To reconstruct the TBSCertificate component of a precertificate from 1641 a certificate, TLS clients should: 1643 o Remove the Redacted Labels extension described in Section 4.2.2 1645 o Replace leftmost labels of each DNS-ID with "?", based on the 1646 INTEGER value corresponding to that DNS-ID in the extension. 1648 A certificate with redacted labels where one of the redacted labels 1649 is "*" MUST NOT be considered compliant. 1651 If the SCT checked is for a Precertificate (where the "type" of the 1652 "TransItem" is "precert_sct_v2"), then the client SHOULD also remove 1653 embedded v1 SCTs, identified by OID 1.3.6.1.4.1.11129.2.4.2 (See 1654 Section 3.3. of [RFC6962]), in the process of reconstructing the 1655 TBSCertificate. That is to allow embedded v1 and v2 SCTs to co-exist 1656 in a certificate (See Appendix A). 1658 9.2.3. Validating SCTs 1660 In addition to normal validation of the server certificate and its 1661 chain, TLS clients SHOULD validate each received SCT for which they 1662 have the corresponding log's metadata. To validate an SCT, a TLS 1663 client computes the signature input from the SCT data and the 1664 corresponding certificate, and then verifies the signature using the 1665 corresponding log's public key. TLS clients MUST NOT consider valid 1666 any SCT whose timestamp is in the future. 1668 Before considering any SCT to be invalid, the TLS client MUST attempt 1669 to validate it against the server certificate and against each of the 1670 zero or more suitable name-constrained intermediates (Section 4.3) in 1671 the chain. These certificates may be evaluated in the order they 1672 appear in the chain, or, indeed, in any order. 1674 9.2.4. Validating inclusion proofs 1676 After validating a received SCT, a TLS client MAY request a 1677 corresponding inclusion proof (if one is not already available) and 1678 then verify it. An inclusion proof can be requested directly from a 1679 log using "get-proof-by-hash" (Section 6.5) or "get-all-by-hash" 1680 (Section 6.6), but note that this will disclose to the log which TLS 1681 server the client has been communicating with. 1683 Alternatively, if the TLS client has received an inclusion proof (and 1684 an STH) alongside the SCT, it can proceed to verifying the inclusion 1685 proof to the provided STH. The client then has to verify consistency 1686 between the provided STH and an STH it knows about, which is less 1687 sensitive from a privacy perspective. 1689 TLS clients SHOULD also verify each received inclusion proof (see 1690 Section 9.4.1) for which they have the corresponding log's metadata, 1691 to audit the log and gain confidence that the certificate is logged. 1693 If the TLS client holds an STH that predates the SCT, it MAY, in the 1694 process of auditing, request a new STH from the log (Section 6.3), 1695 then verify it by requesting a consistency proof (Section 6.4). Note 1696 that if the TLS client uses "get-all-by-hash", then it will already 1697 have the new STH. 1699 9.2.5. Evaluating compliance 1701 To be considered compliant, a certificate MUST be accompanied by at 1702 least one valid SCT. A certificate not accompanied by any valid SCTs 1703 MUST NOT be considered compliant by TLS clients. 1705 9.2.6. TLS Feature Extension 1707 If any certificate in a chain includes the transparency_info 1708 (Section 7.5) TLS extension identifier in the TLS Feature [RFC7633] 1709 certificate extension, then CT compliance (using any of the 1710 mechanisms from Section 7) is required. 1712 TLS clients MUST treat certificates which fail this requirement as 1713 non-compliant. 1715 9.2.7. Handling of Non-compliance 1717 If a TLS server presents a certificate chain that is non-compliant, 1718 there are two possibilities. 1720 o In the case that use of TLS with a valid certificate is mandated 1721 by explicit security policy, application protocol specification, 1722 or other means, the TLS client MUST refuse the connection. 1724 o If the use of TLS with a valid certificate is optional, the TLS 1725 client MAY accept the connection but MUST NOT treat the 1726 certificate as valid. 1728 9.3. Monitor 1730 Monitors watch logs to check that they behave correctly, for 1731 certificates of interest, or both. For example, a monitor may be 1732 configured to report on all certificates that apply to a specific 1733 domain name when fetching new entries for consistency validation. 1735 A monitor needs to, at least, inspect every new entry in each log it 1736 watches. It may also want to keep copies of entire logs. In order 1737 to do this, it should follow these steps for each log: 1739 1. Fetch the current STH (Section 6.3). 1741 2. Verify the STH signature. 1743 3. Fetch all the entries in the tree corresponding to the STH 1744 (Section 6.7). 1746 4. Confirm that the tree made from the fetched entries produces the 1747 same hash as that in the STH. 1749 5. Fetch the current STH (Section 6.3). Repeat until the STH 1750 changes. 1752 6. Verify the STH signature. 1754 7. Fetch all the new entries in the tree corresponding to the STH 1755 (Section 6.7). If they remain unavailable for an extended 1756 period, then this should be viewed as misbehavior on the part of 1757 the log. 1759 8. Either: 1761 1. Verify that the updated list of all entries generates a tree 1762 with the same hash as the new STH. 1764 Or, if it is not keeping all log entries: 1766 1. Fetch a consistency proof for the new STH with the previous 1767 STH (Section 6.4). 1769 2. Verify the consistency proof. 1771 3. Verify that the new entries generate the corresponding 1772 elements in the consistency proof. 1774 9. Go to Step 5. 1776 9.4. Auditing 1778 Auditing ensures that the current published state of a log is 1779 reachable from previously published states that are known to be good, 1780 and that the promises made by the log in the form of SCTs have been 1781 kept. Audits are performed by monitors or TLS clients. 1783 In particular, there are four log behaviour properties that should be 1784 checked: 1786 o The Maximum Merge Delay (MMD). 1788 o The STH Frequency Count. 1790 o The append-only property. 1792 o The consistency of the log view presented to all query sources. 1794 A benign, conformant log publishes a series of STHs over time, each 1795 derived from the previous STH and the submitted entries incorporated 1796 into the log since publication of the previous STH. This can be 1797 proven through auditing of STHs. SCTs returned to TLS clients can be 1798 audited by verifying against the accompanying certificate, and using 1799 Merkle Inclusion Proofs, against the log's Merkle tree. 1801 The action taken by the auditor if an audit fails is not specified, 1802 but note that in general if audit fails, the auditor is in possession 1803 of signed proof of the log's misbehavior. 1805 A monitor (Section 9.3) can audit by verifying the consistency of 1806 STHs it receives, ensure that each entry can be fetched and that the 1807 STH is indeed the result of making a tree from all fetched entries. 1809 A TLS client (Section 9.2) can audit by verifying an SCT against any 1810 STH dated after the SCT timestamp + the Maximum Merge Delay by 1811 requesting a Merkle inclusion proof (Section 6.5). It can also 1812 verify that the SCT corresponds to the certificate it arrived with 1813 (i.e. the log entry is that certificate, is a precertificate for that 1814 certificate or is an appropriate name-constrained intermediate [see 1815 Section 4.3]). 1817 Checking of the consistency of the log view presented to all entities 1818 is more difficult to perform because it requires a way to share log 1819 responses among a set of CT-aware entities, and is discussed in 1820 Section 12.4. 1822 The following algorithm outlines may be useful for clients that wish 1823 to perform various audit operations. 1825 9.4.1. Verifying an inclusion proof 1827 When a client has received a "TransItem" of type "inclusion_proof_v2" 1828 and wishes to verify inclusion of an input "hash" for an STH with a 1829 given "tree_size" and "root_hash", the following algorithm may be 1830 used to prove the "hash" was included in the "root_hash": 1832 1. Compare "leaf_index" against "tree_size". If "leaf_index" is 1833 greater than or equal to "tree_size" fail the proof verification. 1835 2. Set "fn" to "leaf_index" and "sn" to "tree_size - 1". 1837 3. Set "r" to "hash". 1839 4. For each value "p" in the "inclusion_path" array: 1841 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1843 1. Set "r" to "HASH(0x01 || p || r)" 1845 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1846 equally until either "LSB(fn)" is set or "fn" is "0". 1848 Otherwise: 1850 Set "r" to "HASH(0x01 || r || p)" 1852 Finally, right-shift both "fn" and "sn" one time. 1854 5. Compare "sn" to 0. Compare "r" against the "root_hash". If "sn" 1855 is equal to 0, and "r" and the "root_hash" are equal, then the 1856 log has proven the inclusion of "hash". Otherwise, fail the 1857 proof verification. 1859 9.4.2. Verifying consistency between two STHs 1861 When a client has an STH "first_hash" for tree size "first", an STH 1862 "second_hash" for tree size "second" where "0 < first < second", and 1863 has received a "TransItem" of type "consistency_proof_v2" that they 1864 wish to use to verify both hashes, the following algorithm may be 1865 used: 1867 1. If "first" is an exact power of 2, then prepend "first_hash" to 1868 the "consistency_path" array. 1870 2. Set "fn" to "first - 1" and "sn" to "second - 1". 1872 3. If "LSB(fn)" is set, then right-shift both "fn" and "sn" equally 1873 until "LSB(fn)" is not set. 1875 4. Set both "fr" and "sr" to the first value in the 1876 "consistency_path" array. 1878 5. For each subsequent value "c" in the "consistency_path" array: 1880 If "sn" is 0, stop the iteration and fail the proof verification. 1882 If "LSB(fn)" is set, or if "fn" is equal to "sn", then: 1884 1. Set "fr" to "HASH(0x01 || c || fr)" 1885 Set "sr" to "HASH(0x01 || c || sr)" 1887 2. If "LSB(fn)" is not set, then right-shift both "fn" and "sn" 1888 equally until either "LSB(fn)" is set or "fn" is "0". 1890 Otherwise: 1892 Set "sr" to "HASH(0x01 || sr || c)" 1894 Finally, right-shift both "fn" and "sn" one time. 1896 6. After completing iterating through the "consistency_path" array 1897 as described above, verify that the "fr" calculated is equal to 1898 the "first_hash" supplied, that the "sr" calculated is equal to 1899 the "second_hash" supplied and that "sn" is 0. 1901 9.4.3. Verifying root hash given entries 1903 When a client has a complete list of leaf input "entries" from "0" up 1904 to "tree_size - 1" and wishes to verify this list against an STH 1905 "root_hash" returned by the log for the same "tree_size", the 1906 following algorithm may be used: 1908 1. Set "stack" to an empty stack. 1910 2. For each "i" from "0" up to "tree_size - 1": 1912 1. Push "HASH(0x00 || entries[i])" to "stack". 1914 2. Set "merge_count" to the lowest value ("0" included) such 1915 that "LSB(i >> merge_count)" is not set. In other words, set 1916 "merge_count" to the number of consecutive "1"s found 1917 starting at the least significant bit of "i". 1919 3. Repeat "merge_count" times: 1921 1. Pop "right" from "stack". 1923 2. Pop "left" from "stack". 1925 3. Push "HASH(0x01 || left || right)" to "stack". 1927 3. If there is more than one element in the "stack", repeat the same 1928 merge procedure (Step 2.3 above) until only a single element 1929 remains. 1931 4. The remaining element in "stack" is the Merkle Tree hash for the 1932 given "tree_size" and should be compared by equality against the 1933 supplied "root_hash". 1935 10. Algorithm Agility 1937 It is not possible for a log to change any of its algorithms part way 1938 through its lifetime: 1940 Signature algorithm: SCT signatures must remain valid so signature 1941 algorithms can only be added, not removed. 1943 Hash algorithm: A log would have to support the old and new hash 1944 algorithms to allow backwards-compatibility with clients that are 1945 not aware of a hash algorithm change. 1947 Allowing multiple signature or hash algorithms for a log would 1948 require that all data structures support it and would significantly 1949 complicate client implementation, which is why it is not supported by 1950 this document. 1952 If it should become necessary to deprecate an algorithm used by a 1953 live log, then the log should be frozen as specified in Section 9.1 1954 and a new log should be started. Certificates in the frozen log that 1955 have not yet expired and require new SCTs should be submitted to the 1956 new log and the SCTs from that log used instead. 1958 11. IANA Considerations 1960 11.1. TLS Extension Type 1962 IANA is asked to allocate an RFC 5246 ExtensionType value for the 1963 "transparency_info" TLS extension. IANA should update this extension 1964 type to point at this document. 1966 11.2. Hash Algorithms 1968 IANA is asked to establish a registry of hash values, initially 1969 consisting of: 1971 +-------+----------------------+ 1972 | Index | Hash | 1973 +-------+----------------------+ 1974 | 0 | SHA-256 [FIPS.180-4] | 1975 +-------+----------------------+ 1977 11.3. Signature Algorithms 1979 IANA is asked to establish a registry of signature algorithm values, 1980 initially consisting of: 1982 +-------+-----------------------------------------------------------+ 1983 | Index | Signature Algorithm | 1984 +-------+-----------------------------------------------------------+ 1985 | 0 | deterministic ECDSA [RFC6979] using the NIST P-256 curve | 1986 | | (Section D.1.2.3 of the Digital Signature Standard [DSS]) | 1987 | | and HMAC-SHA256 | 1988 | 1 | RSA signatures (RSASSA-PKCS1-v1_5 with SHA-256, Section | 1989 | | 8.2 of [RFC3447]) using a key of at least 2048 bits. | 1990 +-------+-----------------------------------------------------------+ 1992 11.4. SCT Extensions 1994 IANA is asked to establish a registry of SCT extensions, initially 1995 consisting of: 1997 +-------+-----------+ 1998 | Type | Extension | 1999 +-------+-----------+ 2000 | 65535 | reserved | 2001 +-------+-----------+ 2003 TBD: policy for adding to the registry 2005 11.5. STH Extensions 2007 IANA is asked to establish a registry of STH extensions, initially 2008 consisting of: 2010 +-------+-----------+ 2011 | Type | Extension | 2012 +-------+-----------+ 2013 | 65535 | reserved | 2014 +-------+-----------+ 2016 TBD: policy for adding to the registry 2018 11.6. Object Identifiers 2020 This document uses object identifiers (OIDs) to identify Log IDs (see 2021 Section 5.3), the precertificate CMS "eContentType" (see 2022 Section 3.2), and X.509v3 extensions in certificates (see 2023 Section 4.2.2, Section 4.3 and Section 8.1.2) and OCSP responses (see 2024 Section 8.1.1). The OIDs are defined in an arc that was selected due 2025 to its short encoding. 2027 11.6.1. Log ID Registry 1 2029 All OIDs in the range from 1.3.101.8192 to 1.3.101.16383 have been 2030 reserved. This is a limited resource of 8,192 OIDs, each of which 2031 has an encoded length of 4 octets. 2033 IANA is requested to establish a registry that will allocate Log IDs 2034 from this range. 2036 TBD: policy for adding to the registry. Perhaps "Expert Review"? 2038 11.6.2. Log ID Registry 2 2040 The 1.3.101.80 arc has been delegated. This is an unlimited 2041 resource, but only the 128 OIDs from 1.3.101.80.0 to 1.3.101.80.127 2042 have an encoded length of only 4 octets. 2044 IANA is requested to establish a registry that will allocate Log IDs 2045 from this arc. 2047 TBD: policy for adding to the registry. Perhaps "Expert Review"? 2049 12. Security Considerations 2051 With CAs, logs, and servers performing the actions described here, 2052 TLS clients can use logs and signed timestamps to reduce the 2053 likelihood that they will accept misissued certificates. If a server 2054 presents a valid signed timestamp for a certificate, then the client 2055 knows that a log has committed to publishing the certificate. From 2056 this, the client knows that monitors acting for the subject of the 2057 certificate have had some time to notice the misissue and take some 2058 action, such as asking a CA to revoke a misissued certificate, or 2059 that the log has misbehaved, which will be discovered when the SCT is 2060 audited. A signed timestamp is not a guarantee that the certificate 2061 is not misissued, since appropriate monitors might not have checked 2062 the logs or the CA might have refused to revoke the certificate. 2064 In addition, if TLS clients will not accept unlogged certificates, 2065 then site owners will have a greater incentive to submit certificates 2066 to logs, possibly with the assistance of their CA, increasing the 2067 overall transparency of the system. 2069 12.1. Misissued Certificates 2071 Misissued certificates that have not been publicly logged, and thus 2072 do not have a valid SCT, are not considered compliant (so TLS clients 2073 may decide, for example, to reject them). Misissued certificates 2074 that do have an SCT from a log will appear in that public log within 2075 the Maximum Merge Delay, assuming the log is operating correctly. 2076 Thus, the maximum period of time during which a misissued certificate 2077 can be used without being available for audit is the MMD. 2079 12.2. Detection of Misissue 2081 The logs do not themselves detect misissued certificates; they rely 2082 instead on interested parties, such as domain owners, to monitor them 2083 and take corrective action when a misissue is detected. 2085 12.3. Avoiding Overly Redacting Domain Name Labels 2087 Redaction of domain name labels carries the same risks as the use of 2088 wildcards (See Section 7.2 of [RFC6125], for example). If the 2089 entirety of the domain space below the unredacted part of a domain 2090 name is not controlled by a single entity (e.g. "?.com", "?.co.uk" 2091 and other public suffixes [Public.Suffix.List]), then the domain name 2092 may be considered by clients to be overly redacted. 2094 CAs should take care to avoid overly redacting domain names in 2095 precertificates. It is expected that monitors will treat 2096 precertificates that contain overly redacted domain names as 2097 potentially misissued. TLS clients MAY consider a certificate to be 2098 non-compliant if the reconstructed TBSCertificate (Section 9.2.2) 2099 contains any overly redacted domain names. 2101 12.4. Misbehaving Logs 2103 A log can misbehave in several ways. Examples include failing to 2104 incorporate a certificate with an SCT in the Merkle Tree within the 2105 MMD, presenting different, conflicting views of the Merkle Tree at 2106 different times and/or to different parties and issuing STHs too 2107 frequently. Such misbehavior is detectable and the 2108 [I-D.ietf-trans-threat-analysis] provides more details on how this 2109 can be done. 2111 Violation of the MMD contract is detected by log clients requesting a 2112 Merkle inclusion proof (Section 6.5) for each observed SCT. These 2113 checks can be asynchronous and need only be done once per each 2114 certificate. In order to protect the clients' privacy, these checks 2115 need not reveal the exact certificate to the log. Instead, clients 2116 can request the proof from a trusted auditor (since anyone can 2117 compute the proofs from the log) or communicate with the log via 2118 proxies. 2120 Violation of the append-only property or the STH issuance rate limit 2121 can be detected by clients comparing their instances of the Signed 2122 Tree Heads. There are various ways this could be done, for example 2123 via gossip (see [I-D.ietf-trans-gossip]) or peer-to-peer 2124 communications or by sending STHs to monitors (who could then 2125 directly check against their own copy of the relevant log). A proof 2126 of misbehavior in such cases would be a series of STHs that were 2127 issued too closely together, proving violation of the STH issuance 2128 rate limit, or an STH with a root hash that does not match the one 2129 calculated from a copy of the log, proving violation of the append- 2130 only property. 2132 12.5. Deterministic Signatures 2134 Logs are required to use deterministic signatures for the following 2135 reasons: 2137 o Using non-deterministic ECDSA with a predictable source of 2138 randomness means that each signature can potentially expose the 2139 secret material of the signing key. 2141 o Clients that gossip STHs or report back SCTs can be tracked or 2142 traced if a log was to produce multiple STHs or SCTs with the same 2143 timestamp and data but different signatures. 2145 12.6. Multiple SCTs 2147 By offering multiple SCTs, each from a different log, TLS servers 2148 reduce the effectiveness of an attack where a CA and a log collude 2149 (see Section 7.1). 2151 12.7. Threat Analysis 2153 [I-D.ietf-trans-threat-analysis] provides a more detailed threat 2154 analysis of the Certificate Transparency architecture. 2156 13. Acknowledgements 2158 The authors would like to thank Erwann Abelea, Robin Alden, Al 2159 Cutter, Francis Dupont, Adam Eijdenberg, Stephen Farrell, Daniel Kahn 2160 Gillmor, Paul Hadfield, Brad Hill, Jeff Hodges, Paul Hoffman, Jeffrey 2161 Hutzelman, Kat Joyce, Stephen Kent, SM, Alexey Melnikov, Linus 2162 Nordberg, Chris Palmer, Trevor Perrin, Pierre Phaneuf, Melinda Shore, 2163 Ryan Sleevi, Martin Smith, Carl Wallace and Paul Wouters for their 2164 valuable contributions. 2166 A big thank you to Symantec for kindly donating the OIDs from the 2167 1.3.101 arc that are used in this document. 2169 14. References 2171 14.1. Normative References 2173 [DSS] National Institute of Standards and Technology, "Digital 2174 Signature Standard (DSS)", FIPS 186-3, June 2009, 2175 . 2178 [FIPS.180-4] 2179 National Institute of Standards and Technology, "Secure 2180 Hash Standard", FIPS PUB 180-4, March 2012, 2181 . 2184 [HTML401] Raggett, D., Le Hors, A., and I. Jacobs, "HTML 4.01 2185 Specification", World Wide Web Consortium Recommendation 2186 REC-html401-19991224, December 1999, 2187 . 2189 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2190 Requirement Levels", BCP 14, RFC 2119, March 1997. 2192 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2193 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2194 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2196 [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography 2197 Standards (PKCS) #1: RSA Cryptography Specifications 2198 Version 2.1", RFC 3447, February 2003. 2200 [RFC4627] Crockford, D., "The application/json Media Type for 2201 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2203 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 2204 Encodings", RFC 4648, October 2006. 2206 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2207 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2209 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 2210 Housley, R., and W. Polk, "Internet X.509 Public Key 2211 Infrastructure Certificate and Certificate Revocation List 2212 (CRL) Profile", RFC 5280, May 2008. 2214 [RFC5652] Housley, R., "Cryptographic Message Syntax (CMS)", STD 70, 2215 RFC 5652, DOI 10.17487/RFC5652, September 2009, 2216 . 2218 [RFC5905] Mills, D., Martin, J., Burbank, J., and W. Kasch, "Network 2219 Time Protocol Version 4: Protocol and Algorithms 2220 Specification", RFC 5905, June 2010. 2222 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 2223 Extension Definitions", RFC 6066, January 2011. 2225 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2226 Verification of Domain-Based Application Service Identity 2227 within Internet Public Key Infrastructure Using X.509 2228 (PKIX) Certificates in the Context of Transport Layer 2229 Security (TLS)", RFC 6125, March 2011. 2231 [RFC6960] Santesson, S., Myers, M., Ankney, R., Malpani, A., 2232 Galperin, S., and C. Adams, "X.509 Internet Public Key 2233 Infrastructure Online Certificate Status Protocol - OCSP", 2234 RFC 6960, DOI 10.17487/RFC6960, June 2013, 2235 . 2237 [RFC6961] Pettersen, Y., "The Transport Layer Security (TLS) 2238 Multiple Certificate Status Request Extension", RFC 6961, 2239 DOI 10.17487/RFC6961, June 2013, 2240 . 2242 [RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature 2243 Algorithm (DSA) and Elliptic Curve Digital Signature 2244 Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August 2245 2013, . 2247 [RFC7633] Hallam-Baker, P., "X.509v3 Transport Layer Security (TLS) 2248 Feature Extension", RFC 7633, DOI 10.17487/RFC7633, 2249 October 2015, . 2251 14.2. Informative References 2253 [Chromium.Log.Policy] 2254 The Chromium Projects, "Chromium Certificate Transparency 2255 Log Policy", 2014, . 2258 [Chromium.Policy] 2259 The Chromium Projects, "Chromium Certificate 2260 Transparency", 2014, . 2263 [CrosbyWallach] 2264 Crosby, S. and D. Wallach, "Efficient Data Structures for 2265 Tamper-Evident Logging", Proceedings of the 18th USENIX 2266 Security Symposium, Montreal, August 2009, 2267 . 2270 [EVSSLGuidelines] 2271 CA/Browser Forum, "Guidelines For The Issuance And 2272 Management Of Extended Validation Certificates", 2007, 2273 . 2276 [I-D.ietf-trans-gossip] 2277 Nordberg, L., Gillmor, D., and T. Ritter, "Gossiping in 2278 CT", draft-ietf-trans-gossip-01 (work in progress), 2279 October 2015. 2281 [I-D.ietf-trans-threat-analysis] 2282 Kent, S., "Attack Model and Threat for Certificate 2283 Transparency", draft-ietf-trans-threat-analysis-03 (work 2284 in progress), October 2015. 2286 [JSON.Metadata] 2287 The Chromium Projects, "Chromium Log Metadata JSON 2288 Schema", 2014, . 2291 [Public.Suffix.List] 2292 Mozilla Foundation, "Public Suffix List", 2016, . 2295 [RFC6962] Laurie, B., Langley, A., and E. Kasper, "Certificate 2296 Transparency", RFC 6962, June 2013. 2298 Appendix A. Supporting v1 and v2 simultaneously 2300 Certificate Transparency logs have to be either v1 (conforming to 2301 [RFC6962]) or v2 (conforming to this document), as the data 2302 structures are incompatible and so a v2 log could not issue a valid 2303 v1 SCT. 2305 CT clients, however, can support v1 and v2 SCTs, for the same 2306 certificate, simultaneously, as v1 SCTs are delivered in different 2307 TLS, X.509 and OCSP extensions than v2 SCTs. 2309 v1 and v2 SCTs for X.509 certificates can be validated independently. 2310 For precertificates, v2 SCTs should be embedded in the TBSCertificate 2311 before submission of the TBSCertificate (inside a v1 precertificate, 2312 as described in Section 3.1. of [RFC6962]) to a v1 log so that TLS 2313 clients conforming to [RFC6962] but not this document are oblivious 2314 to the embedded v2 SCTs. An issuer can follow these steps to produce 2315 an X.509 certificate with embedded v1 and v2 SCTs: 2317 o Create a CMS precertificate as described in Section 3.2 and submit 2318 it to v2 logs. 2320 o Embed the obtained v2 SCTs in the TBSCertificate, as described in 2321 Section 8.1.2. 2323 o Use that TBSCertificate to create a v1 precertificate, as 2324 described in Section 3.1. of [RFC6962] and submit it to v1 logs. 2326 o Embed the v1 SCTs in the TBSCertificate, as described in 2327 Section 3.3. of [RFC6962]. 2329 o Sign that TBSCertificate (which now contains v1 and v2 SCTs) to 2330 issue the final X.509 certificate. 2332 Authors' Addresses 2334 Ben Laurie 2335 Google UK Ltd. 2337 EMail: benl@google.com 2339 Adam Langley 2340 Google Inc. 2342 EMail: agl@google.com 2343 Emilia Kasper 2344 Google Switzerland GmbH 2346 EMail: ekasper@google.com 2348 Eran Messeri 2349 Google UK Ltd. 2351 EMail: eranm@google.com 2353 Rob Stradling 2354 Comodo CA, Ltd. 2356 EMail: rob.stradling@comodo.com