idnits 2.17.1 draft-laurie-pki-sunlight-03.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 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([RFC5280], [RFC2560], [RFC5878], [RFC6066]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 352: '...e submission, the log MUST immediately...' RFC 2119 keyword, line 356: '... certificate, it MAY return the same S...' RFC 2119 keyword, line 357: '...before. Servers MUST present an SCT f...' RFC 2119 keyword, line 358: '...er with the certificate. Clients MUST...' RFC 2119 keyword, line 365: '...he log. The log MUST incorporate a ce...' (32 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 29, 2012) is 4165 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) -- Missing reference section? 'RFC5878' on line 954 looks like a reference -- Missing reference section? 'RFC6066' on line 962 looks like a reference -- Missing reference section? 'RFC2560' on line 950 looks like a reference -- Missing reference section? 'RFC5280' on line 957 looks like a reference -- Missing reference section? '1' on line 965 looks like a reference -- Missing reference section? '7' on line 333 looks like a reference -- Missing reference section? '32' on line 622 looks like a reference -- Missing reference section? 'RFC5246' on line 947 looks like a reference -- Missing reference section? 'TBD' on line 679 looks like a reference Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Laurie 3 Internet-Draft A. Langley 4 Expires: June 2, 2013 E. Kasper 5 November 29, 2012 7 Certificate Transparency 8 draft-laurie-pki-sunlight-03 10 Abstract 12 The aim of Certificate Transparency is to have every public end- 13 entity and intermediate TLS certificate issued by a known Certificate 14 Authority recorded in one or more certificate logs. In order to 15 detect mis-issuance of certificates, all logs are publicly auditable. 16 In particular, domain owners or their agents will be able to monitor 17 logs for certificates issued on their own domain. 19 To protect clients from unlogged mis-issued certificates, logs sign 20 all recorded certificates, and clients can choose not to trust 21 certificates that are not accompanied by an appropriate log 22 signature. For privacy and performance reasons log signatures are 23 embedded in the TLS handshake via the TLS authorization extension 24 [RFC5878], in a stapled [RFC6066] OCSP extension [RFC2560], or in the 25 certificate itself via an X.509v3 certificate extension [RFC5280]. 27 To ensure a globally consistent view of the log, logs also provide a 28 global signature over the entire log. Any inconsistency of logs can 29 be detected through cross-checks on the global signature. 30 Consistency between any pair of global signatures, corresponding to 31 snapshots of the log at different times, can be efficiently shown. 33 Logs are only expected to certify that they have seen a certificate, 34 and thus we do not specify any revocation mechanism for log 35 signatures in this document. Logs are append-only, and log 36 signatures will be valid indefinitely. 38 Status of this Memo 40 This Internet-Draft is submitted in full conformance with the 41 provisions of BCP 78 and BCP 79. 43 Internet-Drafts are working documents of the Internet Engineering 44 Task Force (IETF). Note that other groups may also distribute 45 working documents as Internet-Drafts. The list of current Internet- 46 Drafts is at http://datatracker.ietf.org/drafts/current/. 48 Internet-Drafts are draft documents valid for a maximum of six months 49 and may be updated, replaced, or obsoleted by other documents at any 50 time. It is inappropriate to use Internet-Drafts as reference 51 material or to cite them other than as "work in progress." 53 This Internet-Draft will expire on June 2, 2013. 55 Copyright Notice 57 Copyright (c) 2012 IETF Trust and the persons identified as the 58 document authors. All rights reserved. 60 This document is subject to BCP 78 and the IETF Trust's Legal 61 Provisions Relating to IETF Documents 62 (http://trustee.ietf.org/license-info) in effect on the date of 63 publication of this document. Please review these documents 64 carefully, as they describe your rights and restrictions with respect 65 to this document. Code Components extracted from this document must 66 include Simplified BSD License text as described in Section 4.e of 67 the Trust Legal Provisions and are provided without warranty as 68 described in the Simplified BSD License. 70 Table of Contents 72 1. Informal introduction . . . . . . . . . . . . . . . . . . . . 4 73 2. Cryptographic components . . . . . . . . . . . . . . . . . . . 5 74 2.1. Merkle Hash Trees . . . . . . . . . . . . . . . . . . . . 5 75 2.1.1. Merkle audit paths . . . . . . . . . . . . . . . . . . 5 76 2.1.2. Merkle consistency proofs . . . . . . . . . . . . . . 6 77 2.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 7 78 2.1.4. Signatures . . . . . . . . . . . . . . . . . . . . . . 8 79 3. Log Format . . . . . . . . . . . . . . . . . . . . . . . . . . 9 80 3.1. Log Entries . . . . . . . . . . . . . . . . . . . . . . . 9 81 3.2. Including the Signed Certificate Timestamp in the TLS 82 Handshake . . . . . . . . . . . . . . . . . . . . . . . . 12 83 3.3. Merkle Tree . . . . . . . . . . . . . . . . . . . . . . . 13 84 3.4. Tree Head Signature . . . . . . . . . . . . . . . . . . . 14 85 4. Client Messages . . . . . . . . . . . . . . . . . . . . . . . 16 86 4.1. Add Chain to Log . . . . . . . . . . . . . . . . . . . . . 16 87 4.2. Add PreCertChain to Log . . . . . . . . . . . . . . . . . 16 88 4.3. Retrieve Latest Signed Tree Head . . . . . . . . . . . . . 17 89 4.4. Retrieve Merkle Consistency Proof between two Signed 90 Tree Heads . . . . . . . . . . . . . . . . . . . . . . . . 17 91 4.5. Retrieve Merkle Audit Proof from Log by Leaf Hash . . . . 17 92 4.6. Retrieve Entries from Log . . . . . . . . . . . . . . . . 18 93 4.7. Retrieve Entry+Merkle Audit Proof from Log . . . . . . . . 19 94 5. Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 95 5.1. Monitor . . . . . . . . . . . . . . . . . . . . . . . . . 20 96 5.2. Auditor . . . . . . . . . . . . . . . . . . . . . . . . . 21 97 6. Security and Privacy Considerations . . . . . . . . . . . . . 22 98 6.1. Misissued Certificates . . . . . . . . . . . . . . . . . . 22 99 6.2. Detection of Misissue . . . . . . . . . . . . . . . . . . 22 100 6.3. Misbehaving logs . . . . . . . . . . . . . . . . . . . . . 22 101 7. Efficiency Considerations . . . . . . . . . . . . . . . . . . 23 102 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 105 1. Informal introduction 107 Certificate Transparency aims to solve the problem of mis-issued 108 certificates by providing a publicly auditable, append-only, 109 untrusted log of all issued certificates. The logs are publicly 110 auditable so that it is possible for anyone to verify the correct 111 operation of the log, and to monitor when new certificates added to 112 it. The logs do not themselves prevent mis-issue, but they ensure 113 that interested parties (particularly those named in certificates) 114 can detect such mis-issuance. Note that this is a general mechanism, 115 but in this document we only decsribe its use for public TLS 116 certificates issued by public CAs. 118 The log consists of certificate chains, which can be submitted by 119 anyone. It is expected that most public CAs will contribute all 120 their newly-issued certificates to the log; it is also expected that 121 certificate holders will also contribute their own certificate 122 chains. In order to avoid the log being spammed into uselessness, it 123 is required that the chain is rooted in a known CA certificate. When 124 a chain is submitted to the log, a signed timestamp is returned, 125 which can later be used to prove to clients that the chain has been 126 submitted. Clients can thus require that all certificates they see 127 have been logged. 129 Those who are concerned about mis-issue can monitor the log, asking 130 it regularly for all new entries, and can thus check whether domains 131 they are responsible for have had certificates issued that they did 132 not expect. What they do with this information, particularly when 133 they find that a mis-issuance has happened, is beyond the scope of 134 this document, but broadly speaking they can invoke existing business 135 mechanisms for dealing with mis-issued certificates. Of course, 136 anyone who wants can monitor the log, and if they believe a 137 certificate is incorrectly issued, take action as they see fit. 139 Similarly, those who have seen signed timestamps from the log can 140 later demand a proof of inclusion from the log. If the log is unable 141 to provide this (or, indeed, if the corresponding certificate is 142 absent from monitors' copies of the log), that is evidence of the 143 incorrect operation of the log. This operation is asynchronous to 144 allow TLS connections to proceed without delay, despite network 145 connectivity issues and the vagaries of firewalls. 147 The append-only property of a log is technically achieved using 148 Merkle Trees, which can be used to show that any particular version 149 of the log is a superset of any particular previous version. 150 Likewise, Merkle Trees avoid the need to trust the log: if the log 151 attempts to show different things to different people, this can be 152 efficiently detected by comparing tree roots and consistency proofs. 154 2. Cryptographic components 156 2.1. Merkle Hash Trees 158 Logs use a binary Merkle hash tree for efficient auditing. The 159 hashing algorithm is SHA-256. The input to the Merkle tree hash is a 160 list of data entries; these entries will be hashed to form the leaves 161 of the Merkle hash tree. The output is a single 32-byte root hash. 162 Given an ordered list of n inputs, D[n] = {d(0), d(1), ..., d(n-1)}, 163 the Merkle Tree Hash (MTH) is thus defined as follows: 165 The hash of an empty list is the hash of an empty string: 167 MTH({}) = SHA-256(). 169 The hash of a list with one entry is: 171 MTH({d(0)}) = SHA-256(0 || d(0)). 173 For n > 1, let k be the largest power of two smaller than n. The 174 Merkle Tree Hash of an n-element list D[n] is then defined 175 recursively as 177 MTH(D[n]) = SHA-256(1 || MTH(D[0:k]) || MTH(D[k:n])), 179 where || is concatenation and D[k1:k2] denotes the length (k2 - k1) 180 list {d(k1), d(k1+1),..., d(k2-1)}. 182 Note that we do not require the length of the input list to be a 183 power of two. The resulting Merkle tree may thus not be balanced, 184 however, its shape is uniquely determined by the number of leaves. 185 [This Merkle tree is essentially the same as the history tree [1] 186 proposal, except our definition omits dummy leaves.] 188 2.1.1. Merkle audit paths 190 A Merkle audit path for a leaf in a Merkle hash tree is the shortest 191 list of additional nodes in the Merkle tree required to compute the 192 Merkle Tree Hash for that tree. Each node in the tree is either a 193 leaf node, or is computed from the two nodes immediately below it 194 (i.e. towards the leaves). At each step up the tree (towards the 195 root), a node from the audit path is combined with the node computed 196 so far. In other words, the audit path consists of the list of 197 missing nodes required to compute the nodes leading from a leaf to 198 the root of the tree. If the root computed from the audit path 199 matches the true root, then the audit path is proof that the leaf 200 exists in the tree. 202 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 203 d(n-1)}, the Merkle audit path PATH(m, D[n]) for the (m+1)th input 204 d(m), 0 <= m < n, is defined as follows: 206 The path for the single leaf in a tree with a one-element input list 207 D[1] = {d(0)} is empty: 209 PATH(0, {d(0)}) = {} 211 For n > 1, let k be the largest power of two smaller than n. The 212 path for the (m+1)th element d(m) in a list of n > m elements is then 213 defined recursively as 215 PATH(m, D[n]) = PATH(m, D[0:k]) : MTH(D[k:n]) for m < k; and 217 PATH(m, D[n]) = PATH(m - k, D[k:n]) : MTH(D[0:k]) for m >= k, 219 where : is concatenation of lists and D[k1:k2] denotes the length (k2 220 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 222 2.1.2. Merkle consistency proofs 224 Merkle consistency proofs prove the append-only property of the tree. 225 A Merkle consistency proof for a Merkle Tree Hash MTH(D[n]) and a 226 previously advertised hash MTH(D[0:m]) of the first m leaves, m <= n, 227 is the list of nodes in the Merkle tree required to verify that the 228 first m inputs D[0:m] are equal in both trees. Thus, a consistency 229 proof must contain a set of intermediate nodes (i.e., commitments to 230 inputs) sufficient to verify MTH(D[n]), such that (a subset of) the 231 same nodes can be used to verify MTH(D[0:m]). We define an algorithm 232 that outputs the (unique) minimal consistency proof. 234 Given an ordered list of n inputs to the tree, D[n] = {d(0), ..., 235 d(n-1)}, the Merkle consistency proof PROOF(m, D[n]) for a previous 236 root hash MTH(D[0:m]), 0 < m < n, is defined as PROOF(m, D[n]) = 237 SUBPROOF(m, D[n], true): 239 The subproof for m = n is empty if m is the value for which PROOF was 240 originally requested (meaning that the subtree root hash MTH(D[0:m]) 241 is known): 243 SUBPROOF(m, D[m], true) = {} 245 The subproof for m = n is the root hash committing inputs D[0:m] 246 otherwise: 248 SUBPROOF(m, D[m], false) = {MTH(D[m])} 249 For m < n, let k be the largest power of two smaller than n. The 250 subproof is then defined recursively. 252 If m <= k, the right subtree entries D[k:n] only exist in the current 253 tree. We prove that the left subtree entries D[0:k] are consistent 254 and add a commitment to D[k:n]: 256 SUBPROOF(m, D[n], b) = SUBPROOF(m, D[0:k], b) : MTH(D[k:n]). 258 If m > k, the left subtree entries D[0:k] are identical in both 259 trees. We prove that the right subtree entries D[k:n] are consistent 260 and add a commitment to D[0:k]. 262 SUBPROOF(m, D[n], b) = SUBPROOF(m - k, D[k:n], false) : MTH(D[0:k]). 264 Here : is concatenation of lists and D[k1:k2] denotes the length (k2 265 - k1) list {d(k1), d(k1+1),..., d(k2-1)} as before. 267 The number of nodes in the resulting proof is bounded above by 268 ceil(log2(n)) + 1. 270 2.1.3. Example 272 The binary Merkle tree with 7 leaves: 274 hash 275 / \ 276 / \ 277 / \ 278 / \ 279 / \ 280 k l 281 / \ / \ 282 / \ / \ 283 / \ / \ 284 g h i j 285 / \ / \ / \ | 286 a b c d e f d6 287 | | | | | | 288 d0 d1 d2 d3 d4 d5 290 The audit path for d0 is [b, h, l]. 292 The audit path for d3 is [c, g, l]. 294 The audit path for d4 is [f, j, k]. 296 The audit path for d6 is [i, k]. 298 The same tree, built incrementally in four steps: 300 hash0 hash1=k 301 / \ / \ 302 / \ / \ 303 / \ / \ 304 g c g h 305 / \ | / \ / \ 306 a b d2 a b c d 307 | | | | | | 308 d0 d1 d0 d1 d2 d3 310 hash2 hash 311 / \ / \ 312 / \ / \ 313 / \ / \ 314 / \ / \ 315 / \ / \ 316 k i k l 317 / \ / \ / \ / \ 318 / \ e f / \ / \ 319 / \ | | / \ / \ 320 g h d4 d5 g h i j 321 / \ / \ / \ / \ / \ | 322 a b c d a b c d e f d6 323 | | | | | | | | | | 324 d0 d1 d2 d3 d0 d1 d2 d3 d4 d5 326 The consistency proof between hash0 and hash is PROOF(3, D[7]) = [c, 327 d, g, l]. c, g are used to verify hash0, and d, l are additionally 328 used to show hash is consistent with hash0. 330 The consistency proof between hash1 and hash is PROOF(4, D[7]) = [l]. 331 hash can be verified, using hash1=k and l. 333 The consistency proof between hash2 and hash is PROOF(6, D[7]) = [i, 334 j, k]. k, i are used to verify hash2, and j is additionally used to 335 show hash is consistent with hash2. 337 2.1.4. Signatures 339 Various data structures are signed. A log can use either elliptic 340 curve signatures using the NIST P-256 curve 341 (http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf 342 section D.1.2.3) or RSA signatures using a key of at least 2048 bits. 344 3. Log Format 346 Anyone can submit certificates to certificate logs for public 347 auditing, however, since certificates will not be accepted by clients 348 unless logged, it is expected that certificate owners or their CAs 349 will usually submit them. A log is a single, ever-growing, append- 350 only Merkle Tree of such certificates. 352 After accepting a certificate submission, the log MUST immediately 353 return a Signed Certificate Timestamp (SCT). The SCT is the log's 354 promise to incorporate the certificate in the Merkle Tree within a 355 fixed amount of time known as the Maximum Merge Delay (MMD). If the 356 log has previously seen the certificate, it MAY return the same SCT 357 as it returned before. Servers MUST present an SCT from one or more 358 logs to the client together with the certificate. Clients MUST 359 reject certificates that do not have a valid SCT for the end-entity 360 certificate. 362 Periodically, the log appends all new entries to the Merkle Tree, and 363 signs the root of the tree. Clients and auditors can thus verify 364 that each certificate for which an SCT has been issued indeed appears 365 in the log. The log MUST incorporate a certificate in its Merkle 366 Tree within the Maximum Merge Delay period after the issuance of the 367 SCT. 369 3.1. Log Entries 371 Anyone can submit a certificate to the log. In order to attribute 372 each logged certificate to its issuer, the log shall publish a list 373 of acceptable root certificates (this list should be the union of 374 root certificates trusted by major browser vendors). Each submitted 375 certificate MUST be accompanied by all additional certificates 376 required to verify the certificate chain up to an accepted root 377 certificate. The self-signed root certificate itself MAY be omitted 378 from this list. 380 Alternatively, (root as well as intermediate) Certificate Authorities 381 may submit a certificate to the log prior to issuance. To do so, a 382 Certificate Authority constructs a Precertificate by adding a special 383 critical poison extension (OID 1.3.6.1.4.1.11129.2.4.3, ASN.1 NULL 384 data) to the leaf TBSCertificate, and signing the resulting 385 TBSCertificate [RFC5280] with a special-purpose (Extended Key Usage: 386 Certificate Transparency, OID 1.3.6.1.4.1.11129.2.4.4, 387 basicConstraints=critical,CA:FALSE) Precertificate Signing 388 Certificate. The Precertificate Signing Certificate MUST be 389 certified by the CA certificate. As above, the Precertificate 390 submission MUST be accompanied by the Precertificate Signing 391 Certificate and all additional certificates required to verify the 392 chain up to an accepted root certificate. The signature on the 393 TBSCertificate indicates the Certificate Authority's intent to issue 394 a certificate. This intent is considered binding (i.e., misissuance 395 of the Precertificate is considered equal to misissuance of the final 396 certificate). The log verifies the Precertificate signature chain, 397 and issues a Signed Certificate Timestamp on the corresponding 398 TBSCertificate. 400 The log MUST verify that the submitted leaf certificate or 401 Precertificate has a valid signature chain leading back to a trusted 402 root CA certificate, using the chain of intermediate CA certificates 403 provided by the submitter. In case of Precertificates, the log MUST 404 also verify that the Precertificate Signing Certificate has the 405 correct Extended Key Usage extension. The log MAY accept 406 certificates that have expired, are not yet valid, have been revoked 407 or are otherwise not fully valid according to X.509 verification 408 rules. However, the log MUST refuse to publish certificates without 409 a valid chain to a known root CA. If a certificate is accepted and 410 an SCT issued, the log MUST store the chain used for verification 411 including the certificate or Precertificate itself, and MUST present 412 this chain for auditing upon request. 414 Each certificate entry in the log MUST include the following 415 components: 417 enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType; 419 struct { 420 LogEntryType entry_type; 421 select (entry_type) { 422 case x509_entry: X509ChainEntry; 423 case precert_entry: PrecertChainEntry; 424 } entry; 425 } LogEntry; 427 opaque ASN.1Cert<1..2^24-1>; 429 struct { 430 ASN.1Cert leaf_certificate; 431 ASN.1Cert certificate_chain<0..2^24-1>; 432 } X509ChainEntry; 434 struct { 435 ASN.1Cert tbs_certificate; 436 ASN.1Cert precertificate_chain<1..2^24-1>; 437 } PrecertChainEntry; 439 Logs MAY limit the length of chain they will accept. 441 "entry_type" is the type of this entry. Future revisions of this 442 protocol version may add new LogEntryType values. Section 4 explains 443 how clients should handle unknown entry types. 445 "leaf_certificate" is the end-entity certificate submitted for 446 auditing. 448 "certificate_chain" is a chain of additional certificates required to 449 verify the leaf certificate. The first certificate MUST certify the 450 leaf certificate. Each following certificate MUST directly certify 451 the one preceding it. The self-signed root certificate MAY be 452 omitted from the chain. 454 "tbs_certificate" is the TBSCertificate component of the 455 Precertificate (i.e., the original TBSCertificate, without the 456 Precertificate signature and the SCT extension). 458 "precertificate_chain" is a chain of certificates required to verify 459 the Precertificate submission. The first certificate MUST be the 460 original Precertificate, with its unsigned part matching the 461 "tbs_certificate". The second certificate MUST be a valid 462 Precertificate Signing Certificate, and MUST certify the first 463 certificate. Each following certificate MUST directly certify the 464 one preceding it. The self-signed root certificate MAY be omitted 465 from the chain. 467 Structure of the Signed Certificate Timestamp: 469 enum { certificate_timestamp(0), tree_hash(1), 255 } 470 SignatureType; 472 enum { v1(0), 255 } 473 Version; 475 struct { 476 opaque key_id[32]; 477 } LogID; 479 opaque CtExtensions<0..2^16-1>; 481 "key_id" is the SHA-256 hash of the log's public key [TODO: define 482 how to calculate this]. 484 struct { 485 Version sct_version; 486 LogID id; 487 uint64 timestamp; 488 CtExtensions extensions; 489 digitally-signed struct { 490 Version sct_version; 491 SignatureType signature_type = certificate_timestamp; 492 uint64 timestamp; 493 LogEntryType entry_type; 494 select(entry_type) { 495 case x509_entry: ASN.1Cert; 496 case precert_entry: ASN.1Cert; 497 } signed_entry; 498 CtExtensions extensions; 499 }; 500 } SignedCertificateTimestamp; 502 The encoding of the digitally-signed element is defined in [RFC5246]. 504 "sct_version" is the version of the protocol the SCT conforms to. 505 This version is v1. 507 "timestamp" is the current UTC time since epoch (January 1, 1970, 508 00:00), in milliseconds. 510 "entry_type" is assumed to be implicit from the context in which the 511 SCT is presented. 513 "signed_entry" is the "leaf_certificate" (in case of an 514 X509ChainEntry), or "tbs_certificate" (in case of a 515 PrecertChainEntry). 517 "extensions" are future extensions to this protocol version (v1). 518 Currently, no extensions are specified. 520 3.2. Including the Signed Certificate Timestamp in the TLS Handshake 522 The SCT data from at least one log must be included in the TLS 523 handshake, either by using an Authorization Extension [RFC5878] with 524 type 182, or by using OCSP Stapling (section 8 of [RFC6066]), where 525 the response includes an OCSP extension with OID 526 1.3.6.1.4.1.11129.2.4.5 (see [RFC2560]) and body: 528 SignedCertificateTimestampList ::= OCTET STRING 530 At least one SCT MUST be included. Server operators MAY include more 531 than one SCT. 533 Similarly, the Certificate Authority MAY submit the precertificate to 534 more than one log, and all obtained SCTs can be directly embedded in 535 the final certificate, by encoding the SignedCertificateTimestampList 536 structure as an ASN.1 OCTET STRING and inserting the resulting data 537 in the TBSCertificate as an X.509v3 certificate extension (OID 538 1.3.6.1.4.1.11129.2.4.2). Upon receiving the certificate, clients 539 can reconstruct the original TBSCertificate to verify the SCT 540 signature. 542 The contents of the ASN.1 OCTET STRING embedded in an OCSP extension 543 or X509v3 certificate extension are as follows: 545 opaque SerializedSCT<1..2^16-1>; 547 struct { 548 SerializedSCT sct_list <1..2^16-1>; 549 } SignedCertificateTimestampList; 551 Here "SerializedSCT" is an opaque bytestring that contains the 552 serialized TLS structure. This encoding ensures that clients can 553 decode each SCT individually (i.e., if there is a version upgrade, 554 out of date clients can still parse old SCTs while skipping over new 555 SCTs whose version they don't understand). 557 SCTs embedded in the TLS Authorization Extension are each encoded as 558 an individual AuthorizationDataEntry [RFC5878]. 560 3.3. Merkle Tree 562 A certificate log MUST periodically append all new log entries to the 563 log Merkle Tree. The log MUST sign these entries by constructing a 564 binary Merkle Tree with log entries as consecutive inputs to the 565 tree, signing the corresponding Merkle Tree Hash, and publishing each 566 update to the tree in a Signed Merkle Tree Update. The hashing 567 algorithm for the Merkle Tree Hash is SHA-256. 569 Structure of the Merkle Tree input: 571 enum { timestamped_entry(0), 255 } 572 MerkleLeafType; 574 struct { 575 uint64 timestamp; 576 LogEntryType entry_type; 577 select(entry_type) { 578 case x509_entry: ASN.1Cert; 579 case precert_entry: ASN.1Cert; 580 } signed_entry; 581 CtExtensions extensions; 582 } TimestampedEntry; 584 struct { 585 Version version; 586 MerkleLeafType leaf_type; 587 select (leaf_type) { 588 case timestamped_entry: TimestampedEntry; 589 } 590 } MerkleTreeLeaf; 592 Here "version" is the version of the protocol the MerkleTreeLeaf 593 corresponds to. This version is v1. 595 "leaf_type" is the type of the leaf input. Currently, only 596 "timestamped_entry" (corresponding to an SCT) is defined. Future 597 revisions of this protocol version may add new MerkleLeafType types. 598 Section 4 explains how clients should handle unknown leaf types. 600 "timestamp" is the timestamp of the corresponding SCT issued for this 601 certificate. 603 "signed_entry" is the "signed_entry" of the corresponding SCT. 605 "extensions" are "extensions" of the corresponding SCT. 607 The leaves of the Merkle Tree are the hashes of the corresponding 608 "MerkleTreeLeaf" structures. 610 3.4. Tree Head Signature 612 Every time the log appends new entries to the tree, the log MUST sign 613 the corresponding tree hash and tree information (see also the 614 corresponding Signed Tree Head client message in Section 4.3). The 615 signature input is structured as follows: 617 digitally-signed struct { 618 Version version; 619 SignatureType signature_type = tree_hash; 620 uint64 timestamp; 621 uint64 tree_size; 622 opaque sha256_root_hash[32]; 623 } TreeHeadSignature; 625 "version" is the version of the protocol the TreeHeadSignature 626 conforms to. This version is v1. 628 "timestamp" is the current time. The timestamp MUST be at least as 629 recent as the most recent SCT timestamp in the tree. Each subsequent 630 timestamp MUST be more recent than the timestamp of the previous 631 update. 633 "tree_size" equals the number of entries in the new tree. 635 "sha256_root_hash" is the root of the Merkle Hash Tree. 637 The log MUST produce a Tree Head Signature at least as often as the 638 Maximum Merge Delay. In the unlikely event that it receives no new 639 submissions during an MMD period, the log SHALL sign the same Merkle 640 Tree Hash with a fresh timestamp. 642 4. Client Messages 644 Messages are sent as HTTPS GET or POST requests. Parameters for 645 POSTs and all responses are encoded as JSON objects. Parameters for 646 GETs are encoded as URL parameters. Binary data is base64 encoded as 647 specified in the individual messages. 649 The prefix can include a path as well as a server name 650 and a port. It must map one-to-one to a known public key (how this 651 mapping is distributed is out of scope for this document). 653 In general, where needed, the "version" is v1 and the "id" is the log 654 id for the log server queried. 656 4.1. Add Chain to Log 658 POST https:///ct/v1/add-chain 660 Inputs 662 chain An array of base64 encoded certificates. The first element is 663 the leaf certificate, the second chains to the first and so on to 664 the last, which is either the root certificate or a certificate 665 that chains to a known root certificate. 667 Outputs 669 sct_version The version of the SignedCertificateTimestamp structure, 670 in decimal. A compliant v1 implementation MUST NOT expect this to 671 be 0 (i.e. v1). 673 id The log ID, base64 encoded. Since clients who request an SCT for 674 inclusion in the TLS handshake are not required to verify it, we 675 do not assume they know the ID of the log. 677 timestamp The SCT timestamp, in decimal. 679 extensions [TBD] 681 signature The SCT signature, base64 encoded. 683 If the "sct_version" is not v1, then a v1 client may be unable to 684 verify the signature. It MUST NOT construe this as an error. 686 4.2. Add PreCertChain to Log 688 POST https:///ct/v1/add-pre-chain 689 Inputs 691 chain An array of base64 encoded precertificates. The first element 692 is the leaf certificate, the second chains to the first and so on 693 to the last, which is either the root certificate or a certificate 694 that chains to a known root certificate. 696 Outputs are the same as Section 4.1. 698 4.3. Retrieve Latest Signed Tree Head 700 GET https:///ct/v1/get-sth 702 No inputs. 704 Outputs 706 tree_size The size of the tree, in entries, in decimal. 708 timestamp The timestamp, in decimal. 710 sha256_root_hash The root hash of the tree, in base64. 712 tree_head_signature A TreeHeadSignature for the above data. 714 4.4. Retrieve Merkle Consistency Proof between two Signed Tree Heads 716 GET https:///ct/v1/get-sth-consistency 718 Inputs 720 first The tree_size of the first tree, in decimal. 722 second The tree_size of the second tree, in decimal. 724 Both tree sizes must be from published v1 STHs. 726 Outputs 728 consistency An array of Merkle tree nodes, base64 encoded. 730 Note that no signature is required on this data, as it is used to 731 verify an STH, which is signed. 733 4.5. Retrieve Merkle Audit Proof from Log by Leaf Hash 735 GET https:///ct/v1/get-proof-by-hash 736 Inputs 738 hash A base64 encoded v1 leaf hash. 740 tree_size The tree_size of the tree to base the proof on, in 741 decimal. 743 The "hash" must be calculated as defined in Section 3.3. The 744 "tree_size" must designate a published v1 STH. 746 Outputs 748 timestamp The tree's timestamp, in decimal. 750 leaf_index The index of the leaf corresponding to the "hash" 751 parameter. 753 audit_path An array of base64 encoded Merkle tree nodes proving the 754 inclusion of the chosen certificate. 756 4.6. Retrieve Entries from Log 758 GET https:///ct/v1/get-entries 760 Inputs 762 start Index of first entry to retrieve, in decimal. 764 end Index of last entry to retrieve, in decimal. 766 Outputs 768 entries An array of objects, each consisting of 770 leaf_input The base64-encoded MerkleTreeLeaf structure. 772 extra_data The base64-encoded unsigned data pertaining to the log 773 entry. In the case of an X509ChainEntry, this is the 774 "certificate_chain". In the case of a PrecertChainEntry, this 775 is the "precertificate_chain". 777 Note that this message is not signed - the retrieved data can be 778 verified by constructing the root hash corresponding to a retrieved 779 STH. All leaves MUST be v1. However, a compliant v1 client MUST NOT 780 construe an unrecognized MerkleLeafType or LogEntryType value as an 781 error. This means it may be unable to parse some entries, but note 782 that each client can inspect the entries it does recognize, as well 783 as verify the integrity of the data by treating unrecognized leaves 784 as opaque input to the tree. 786 4.7. Retrieve Entry+Merkle Audit Proof from Log 788 GET https:///ct/v1/get-entry-and-proof 790 Inputs 792 leaf_index The index of the desired entry. 794 tree_size The tree_size of the tree for which the proof is desired. 796 The tree size must designate a published STH. 798 Outputs 800 entries An array of objects, each consisting of 802 leaf_input The base64-encoded MerkleTreeLeaf structure. 804 auxiliary_data The base64-encoded unsigned data, same as in 805 Section 4.6. 807 timestamp The tree's timestamp, in decimal. 809 audit_path An array of base64 encoded Merkle tree nodes proving the 810 inclusion of the chosen certificate. 812 This API is probably only useful for debugging. 814 5. Clients 816 There are various different functions clients of the log might 817 perform. We describe here some typical clients and how they could 818 function. Any inconsistency may be used as evidence that a log has 819 not behaved correctly, and the signatures on the data structures 820 prevent the log from denying that misbehaviour. 822 All clients should gossip with each other, exchanging STHs at least: 823 this is all that is required to ensure that they all have a 824 consistent view. The exact mechanism for gossip is TBD, but it is 825 expected there will be a variety. 827 5.1. Monitor 829 Monitors watch the log and check that it behaves correctly. They 830 also watch for certificates of interest. 832 A monitor needs to, at least, inspect every new entry in the log. It 833 may also want to keep a copy of the entire log. In order to do this, 834 it should follow these steps: 836 1. Fetch the current STH using Section 4.3. 838 2. Verify the STH signature. 840 3. Fetch all the entries in the tree corresponding to the STH using 841 Section 4.6. 843 4. Confirm that the tree made from the fetched entries produces the 844 same hash as that in the STH. 846 5. Fetch the current STH using Section 4.3. Repeat until STH 847 changes. 849 6. Verify the STH signature. 851 7. Fetch all the new entries in the tree corresponding to the STH 852 using Section 4.6. If they remain unavailable for an extended 853 period, then this should be viewed as misbehaviour on the part of 854 the log. 856 8. Either: 858 1. Verify that the updated list of all entries generates a tree 859 with the same hash as the new STH. 861 Or, if it is not keeping all log entries: 863 2. Fetch a consistency proof for the new STH with the previous 864 STH using Section 4.4. 866 3. Verify the consistency proof. 868 4. Verify that the new entries generate the corresponding 869 elements in the consistency proof. 871 9. Go to Step 5. 873 5.2. Auditor 875 Auditors take partial information about a log as input and verify 876 that this information is consistent with other partial information 877 they have. An auditor might be an integral component of a TLS 878 client, it might be a standalone service or it might be a secondary 879 function of a monitor. 881 Any pair of STHs from the same log can be verified by requesting a 882 consistency proof using Section 4.4. 884 A certificate accompanied by an SCT can be verified against any STH 885 dated after the SCT timestamp + the Maximum Merge Delay by requesting 886 a Merkle Audit Proof using Section 4.5. 888 Auditors can fetch STHs from time to time of their own accord, of 889 course, using Section 4.3. 891 6. Security and Privacy Considerations 893 6.1. Misissued Certificates 895 Misissued certificates that have not been publicly logged, and thus 896 do not have a valid SCT, will be rejected by clients. Misissued 897 certificates that do have an SCT from a log will appear in the public 898 log within the Maximum Merge Delay, assuming the log is operating 899 correctly. Thus, the maximum period of time during which a misissued 900 certificate can be used without being available for audit is the MMD. 902 6.2. Detection of Misissue 904 The log does not itself detect misissued certificate, it relies 905 instead on interested parties, such as domain owners, to monitor it 906 and take corrective action when a misissue is detected. 908 6.3. Misbehaving logs 910 A log can misbehave in two ways: (1), by failing to incorporate a 911 certificate with an SCT in the Merkle Tree within the MMD; and (2), 912 by violating its append-only property by presenting two different, 913 conflicting views of the Merkle Tree at different times and/or to 914 different parties. Both forms of violation will be promptly and 915 publicly detectable. 917 Violation of the MMD contract is detected by clients requesting a 918 Merkle audit proof for each observed SCT. These checks can be 919 asynchronous, and need only be done once per each certificate. In 920 order to protect the clients' privacy, these checks need not reveal 921 the exact certificate to the log. Clients can instead request the 922 proof from a trusted auditor (since anyone can compute the audit 923 proofs from the log), or request Merkle proofs for a batch of 924 certificates around the SCT timestamp. 926 Violation of the append-only property is detected by global 927 gossiping, i.e., everyone auditing the log comparing their versions 928 of the latest signed tree head. As soon as two conflicting signed 929 tree heads are detected, this is cryptographic proof of the log's 930 misbehaviour. 932 7. Efficiency Considerations 934 The Merkle tree design serves the purpose of keeping communication 935 overhead low. 937 Auditing the log for integrity does not require third parties to 938 maintain a copy of the entire log. The Signed Tree Head can be 939 updated as new entries become available, without recomputing the 940 entire tree. Third party auditors need only fetch the Merkle 941 consistency proof against an existing STH to efficiently verify the 942 append-only property of an update to the Merkle Tree, without 943 auditing the entire tree. 945 8. References 947 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 948 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 950 [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. 951 Adams, "X.509 Internet Public Key Infrastructure Online 952 Certificate Status Protocol - OCSP", RFC 2560, June 1999. 954 [RFC5878] Brown, M. and R. Housley, "The Transport Layer Security 955 (TLS) Authorization Extensions", RFC 5280, May 2010. 957 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 958 Housley, R., and W. Polk, "Internet X.509 Public Key 959 Infrastructure Certificate and Certificate Revocation List 960 (CRL) Profile", RFC 5280, May 2008. 962 [RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions: 963 Extension Definitions", RFC 6066, January 2011. 965 [1] 967 Authors' Addresses 969 Ben Laurie 971 Email: benl@google.com 973 Adam Langley 975 Email: agl@google.com 977 Emilia Kasper 979 Email: ekasper@google.com