diff --git a/draft-ietf-trans-rfc6962-bis.md b/draft-ietf-trans-rfc6962-bis.md index 3f68e07..b853a59 100644 --- a/draft-ietf-trans-rfc6962-bis.md +++ b/draft-ietf-trans-rfc6962-bis.md @@ -1,6 +1,6 @@ --- title: "Certificate Transparency Version 2.0" -docname: draft-ietf-trans-rfc6962-bis-35 +docname: draft-ietf-trans-rfc6962-bis-39 obsoletes: 6962 category: exp @@ -41,17 +41,22 @@ author: normative: RFC2119: + RFC3986: RFC4648: + RFC5246: RFC5280: RFC5652: RFC6066: + RFC6234: RFC6960: + RFC6979: RFC7231: RFC7633: RFC7807: RFC8032: RFC8174: RFC8259: + RFC8391: RFC8446: HTML401: target: http://www.w3.org/TR/1999/REC-html401-19991224 @@ -80,14 +85,18 @@ normative: title: The Open Group Base Specifications Issue 7 IEEE Std 1003.1-2008, 2016 Edition author: org: IEEE + X690: + title: "Information technology - ASN.1 encoding Rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER)" + date: November 2015 + author: + org: ITU-T + seriesinfo: + ISO/IEC: 8825-1:2002 informative: - RFC6234: RFC6962: - RFC6979: - RFC7320: RFC8126: - I-D.ietf-trans-gossip: + RFC8820: CrosbyWallach: target: http://static.usenix.org/event/sec09/tech/full_papers/crosby.pdf title: Efficient Data Structures for Tamper-Evident Logging @@ -119,7 +128,16 @@ informative: author: org: The Chromium Projects date: 2014 - I-D.ietf-trans-threat-analysis: + CABBR: + target: https://cabforum.org/wp-content/uploads/CA-Browser-Forum-BR-1.7.3.pdf + title: > + Baseline Requirements for the Issuance and Management of + Publicly-Trusted Certificates + author: + org: CA/Browser Forum + date: 2020 + format: + PDF: https://cabforum.org/wp-content/uploads/CA-Browser-Forum-BR-1.7.3.pdf --- abstract @@ -138,6 +156,10 @@ used to send various CT log artifacts. Logs are network services that implement the protocol operations for submissions and queries that are defined in this document. +\[RFC Editor: please update 'RFCXXXX' to refer to this document, +once its RFC number is known, through the document.\] + + --- middle # Introduction @@ -150,6 +172,7 @@ mechanism that could be used for transparently logging any form of binary data, subject to some kind of inclusion criteria. In this document, we only describe its use for public TLS server certificates (i.e., where the inclusion criteria is a valid certificate issued by a public certification authority (CA)). +A typical definition of "public" can be found in [CABBR]. Each log contains certificate chains, which can be submitted by anyone. It is expected that public CAs will contribute all their newly issued certificates to @@ -157,6 +180,8 @@ one or more logs; however certificate holders can also contribute their own certificate chains, as can third parties. In order to avoid logs being rendered useless by the submission of large numbers of spurious certificates, it is required that each chain ends with a trust anchor that is accepted by the log. +A log may also limit the length of the chain it is willing to accept; +such chains must also end with an acceptable trust anchor. When a chain is accepted by a log, a signed timestamp is returned, which can later be used to provide evidence to TLS clients that the chain has been submitted. TLS clients can thus require that all certificates they accept as @@ -189,8 +214,8 @@ is not subsequently logged). It is necessary to treat each log as a trusted third party, because the log auditing mechanisms described in this document can be circumvented by a misbehaving log that shows different, inconsistent views of itself to different -clients. Whilst it is anticipated that additional mechanisms could be developed -to address these shortcomings and thereby avoid the need to blindly trust logs, +clients. While mechanisms are being developed to address these +shortcomings and thereby avoid the need to blindly trust logs, such mechanisms are outside the scope of this document. ## Requirements Language @@ -205,6 +230,12 @@ when, and only when, they appear in all capitals, as shown here. Data structures are defined and encoded according to the conventions laid out in Section 3 of [RFC8446]. +This document uses object identifiers (OIDs) to identify Log IDs (see +{{log_id}}), the precertificate CMS `eContentType` (see {{precertificates}}), +and X.509v3 extensions in certificates (see {{cert_transinfo_extension}}) and +OCSP responses (see {{ocsp_transinfo_extension}}). The OIDs are defined in an +arc that was selected due to its short encoding. + ## Major Differences from CT 1.0 This document revises and obsoletes the CT 1.0 [RFC6962] protocol, drawing on @@ -266,6 +297,12 @@ major changes are: ## Merkle Hash Trees {#mht} +A full description of Merkle Hash Tree is beyond the scope of this +document. Briefly, it is a binary tree where each non-leaf node is a +hash of its children. For CT, the number of children is at most two. +Additional information can be found in the Introduction and Reference +section of {{!RFC8391}}. + ### Definition of the Merkle Tree {#mht_definition} The log uses a binary Merkle Hash Tree for efficient auditing. The hash @@ -319,7 +356,7 @@ definition handles non-full trees differently). ### Verifying a Tree Head Given Entries {#verify_hash} -When a client has a complete list of n input `entries` from `0` up to +When a client has a complete list of `entries` from `0` up to `tree_size - 1` and wishes to verify this list against a tree head `root_hash` returned by the log for the same `tree_size`, the following algorithm may be used: @@ -331,7 +368,8 @@ used: 1. Push `HASH(0x00 || entries[i])` to `stack`. 2. Set `merge_count` to the lowest value (`0` included) such that `LSB(i >> - merge_count)` is not set. In other words, set `merge_count` to the number + merge_count)` is not set, where `LSB` means the least significant bit. + In other words, set `merge_count` to the number of consecutive `1`s found starting at the least significant bit of `i`. 3. Repeat `merge_count` times: @@ -343,7 +381,8 @@ used: 3. Push `HASH(0x01 || left || right)` to `stack`. 3. If there is more than one element in the `stack`, repeat the same merge - procedure (Step 2.3 above) until only a single element remains. + procedure (the sub-items of Step 2.3 above) until only a single element + remains. 4. The remaining element in `stack` is the Merkle Tree hash for the given `tree_size` and should be compared by equality against the supplied @@ -392,7 +431,8 @@ When a client has received an inclusion proof (e.g., in a `TransItem` of type given `tree_size` and `root_hash`, the following algorithm may be used to prove the `hash` was included in the `root_hash`: -1. Compare `leaf_index` against `tree_size`. If `leaf_index` is greater than or +1. Compare `leaf_index` from the `inclusion_proof_v2` structure + against `tree_size`. If `leaf_index` is greater than or equal to `tree_size` then fail the proof verification. 2. Set `fn` to `leaf_index` and `sn` to `tree_size - 1`. @@ -453,18 +493,18 @@ of the Merkle Tree created from the original D\_n for which PROOF was requested, and the subtree Merkle Tree Hash MTH(D\[0:m]) is known): ~~~~~~~~~~~ -SUBPROOF(m, D[m], true) = {} +SUBPROOF(m, D_m, true) = {} ~~~~~~~~~~~ Otherwise, the subproof for m = n is the Merkle Tree Hash committing inputs D\[0:m]: ~~~~~~~~~~~ -SUBPROOF(m, D[m], false) = {MTH(D[m])} +SUBPROOF(m, D_m, false) = {MTH(D_m)} ~~~~~~~~~~~ For m \< n, let k be the largest power of two smaller than n. The subproof is -then defined recursively. +then defined recursively, using the appropriate step below: If m \<= k, the right subtree entries D\[k:n] only exist in the current tree. We prove that the left subtree entries D\[0:k] are consistent and add a @@ -495,17 +535,20 @@ received a consistency proof between the two (e.g., in a `TransItem` of type `consistency_proof_v2`), the following algorithm may be used to verify the consistency proof: -1. If `first` is an exact power of 2, then prepend `first_hash` to the +1. If `consistency_path` is an empty array, stop and fail the proof + verification. + +2. If `first` is an exact power of 2, then prepend `first_hash` to the `consistency_path` array. -2. Set `fn` to `first - 1` and `sn` to `second - 1`. +3. Set `fn` to `first - 1` and `sn` to `second - 1`. -3. If `LSB(fn)` is set, then right-shift both `fn` and `sn` equally until +4. If `LSB(fn)` is set, then right-shift both `fn` and `sn` equally until `LSB(fn)` is not set. -4. Set both `fr` and `sr` to the first value in the `consistency_path` array. +5. Set both `fr` and `sr` to the first value in the `consistency_path` array. -5. For each subsequent value `c` in the `consistency_path` array: +6. For each subsequent value `c` in the `consistency_path` array: If `sn` is 0, stop the iteration and fail the proof verification. @@ -523,7 +566,7 @@ consistency proof: Finally, right-shift both `fn` and `sn` one time. -6. After completing iterating through the `consistency_path` array as described +7. After completing iterating through the `consistency_path` array as described above, verify that the `fr` calculated is equal to the `first_hash` supplied, that the `sr` calculated is equal to the `second_hash` supplied and that `sn` is 0. @@ -601,8 +644,9 @@ consistent with hash2. ## Signatures {#signatures} -Various data structures {{data_structures}} are signed. A log MUST use one of -the signature algorithms defined in {{signature_algorithms}}. +When signing data structures, a log MUST use one of +the signature algorithms from the IANA CT Signature Algorithms registry, +described in {{signature_algorithms}}. # Submitters @@ -640,11 +684,11 @@ to multiple logs, but only incorporates the SCTs that are returned first. A precertificate is a CMS [RFC5652] `signed-data` object that conforms to the following profile: -* It MUST be DER encoded. +* It MUST be DER encoded as described in [X690]. * `SignedData.version` MUST be v3(3). -* `SignedData.digestAlgorithms` MUST only include the +* `SignedData.digestAlgorithms` MUST be the same as the `SignerInfo.digestAlgorithm` OID value (see below). * `SignedData.encapContentInfo`: @@ -661,6 +705,7 @@ following profile: * `version` MUST be v3(3). * `sid` MUST use the `subjectKeyIdentifier` option. * `digestAlgorithm` MUST be one of the hash algorithm OIDs listed in + the IANA CT Hash Algorithms Registry, described in {{hash_algorithms}}. * `signedAttrs` MUST be present and MUST contain two attributes: * A content-type attribute whose value is the same as @@ -710,8 +755,8 @@ precertificate entries. When it receives and accepts a valid submission, the log MUST return an SCT that corresponds to the submitted certificate or precertificate. If the log has previously seen this valid submission, it SHOULD return the same SCT as it -returned before (to reduce the ability to track clients as described in -{{prevent_tracking_clients}}). If different SCTs are produced for the same +returned before, as discussed in {{misbehaving_logs}}. +If different SCTs are produced for the same submission, multiple log entries will have to be created, one for each SCT (as the timestamp is a part of the leaf structure). Note that if a certificate was previously logged as a precertificate, then the precertificate's SCT of type @@ -743,7 +788,7 @@ Final Signed Tree Head (STH), each of these parameters MUST be established before the log operator begins to operate the log. Base URL: -: The prefix used to construct URLs for client messages (see +: The prefix used to construct URLs ([RFC3986]) for client messages (see {{client_messages}}). The base URL MUST be an "https" URL, MAY contain a port, MAY contain a path with any number of path segments, but MUST NOT contain a query string, fragment, or trailing "/". @@ -764,12 +809,14 @@ Log ID: Maximum Merge Delay: : The MMD the log has committed to. +This document deliberately does not specify any limits on the value, to allow +for experimentation. Version: : The version of the protocol supported by the log (currently 1 or 2). Maximum Chain Length: -: The longest chain submission the log is willing to accept, if the log imposes +: The longest certificate chain submission the log is willing to accept, if the log imposes any limit. STH Frequency Count: @@ -780,8 +827,9 @@ Final STH: : If a log has been closed down (i.e., no longer accepts new entries), existing entries may still be valid. In this case, the client should know the final valid STH in the log to ensure no new entries can be added without detection. - The final STH should be provided in the form of a TransItem of type + This value MUST be provided in the form of a TransItem of type `signed_tree_head_v2`. + If a log is still accepting entries, this value should not be provided. [JSON.Metadata] is an example of a metadata format which includes the above elements. @@ -846,8 +894,8 @@ If a submission is accepted and an SCT issued, the accepting log MUST store the entire chain used for verification. This chain MUST include the certificate or precertificate itself, the zero or more intermediate CA certificates provided by the submitter, and the trust anchor used to verify the chain (even if it was -omitted from the submission). The log MUST present this chain for auditing upon -request (see {{get-entries}}). This prevents the CA from avoiding blame by +omitted from the submission). The log MUST provide this chain for auditing upon +request (see {{get-entries}}) so that the CA cannot avoid blame by logging a partial or empty chain. Each log entry is a `TransItem` structure of type `x509_entry_v2` or `precert_entry_v2`. However, a log may store its entries in any format. If a @@ -861,7 +909,12 @@ chain that the log used to verify the submission. Each log is identified by an OID, which is one of the log's parameters (see {{log_parameters}}) and which MUST NOT be used to identify any other log. A log's operator MUST either allocate the OID themselves or request an OID from -the Log ID Registry (see {{log_id_registry}}). Various data structures include +the Log ID Registry (see {{log_id_registry}}). +The only advantage of the registry is that the DER encoding can be small. +(Recall that OID allocations do not require a central registration, although +logs will most likely want to make themselves known to potential clients +through out of band means.) +Various data structures include the DER encoding of this OID, excluding the ASN.1 tag and length bytes, in an opaque vector: @@ -870,12 +923,13 @@ opaque vector: ~~~~~~~~~~~ Note that the ASN.1 length and the opaque vector length are identical in size (1 -byte) and value, so the DER encoding of the OID can be reproduced simply by +byte) and value, so the full DER encoding (including the tag and length) +of the OID can be reproduced simply by prepending an OBJECT IDENTIFIER tag (0x06) to the opaque vector length and contents. -OIDs used to identify logs are limited such that the DER encoding of their value -is less than or equal to 127 octets. +The OID used to identify a log is limited such that the DER encoding of its +value, excluding the tag and length, MUST be no longer than 127 octets. ## TransItem Structure @@ -985,7 +1039,8 @@ HASH_SIZE. that a precertificate's TBSCertificate can be reconstructed from the corresponding certificate as described in {{reconstructing_tbscertificate}}). -`sct_extensions` matches the SCT extensions of the corresponding SCT. +`sct_extensions` is byte-for-byte identical to the SCT extensions of the +corresponding SCT. The type of the `TransItem` corresponds to the value of the `type` parameter supplied in the {{submit-entry}} call. @@ -1000,7 +1055,7 @@ which encapsulates a `SignedCertificateTimestampDataV2` structure: LogID log_id; uint64 timestamp; Extension sct_extensions<0..2^16-1>; - opaque signature<0..2^16-1>; + opaque signature<1..2^16-1>; } SignedCertificateTimestampDataV2; ~~~~~~~~~~~ @@ -1013,8 +1068,10 @@ which encapsulates a `SignedCertificateTimestampDataV2` structure: `sct_extensions` is a vector of 0 or more SCT extensions. This vector MUST NOT include more than one extension with the same `extension_type`. The extensions in the vector MUST be ordered by the value of the -`extension_type` field, smallest value first. If an implementation sees an -extension that it does not understand, it SHOULD ignore that extension. +`extension_type` field, smallest value first. +All SCT extensions are similar to non-critical X.509v3 extensions (i.e., +the `mustUnderstand` field is not set), and a recipient SHOULD ignore any +extension it does not understand. Furthermore, an implementation MAY choose to ignore any extension(s) that it does understand. @@ -1039,9 +1096,8 @@ The log stores information about its Merkle Tree in a `TreeHeadDataV2`: The length of NodeHash MUST match HASH_SIZE of the log. -`timestamp` is the current date and time, in the form of a 64-bit unsigned -number of milliseconds elapsed since the Unix Epoch (1 January 1970 -00:00:00 UTC - see [UNIXTIME]), ignoring leap seconds, in network byte order. +`timestamp` is the current date and time, using the format defined in +{tree_leaves}. `tree_size` is the number of entries currently in the log's Merkle Tree. @@ -1101,7 +1157,7 @@ encapsulates a `ConsistencyProofDataV2` structure: LogID log_id; uint64 tree_size_1; uint64 tree_size_2; - NodeHash consistency_path<1..2^16-1>; + NodeHash consistency_path<0..2^16-1>; } ConsistencyProofDataV2; ~~~~~~~~~~~ @@ -1113,7 +1169,7 @@ encapsulates a `ConsistencyProofDataV2` structure: `tree_size_2` is the size of the newer tree. `consistency_path` is a vector of Merkle Tree nodes proving the consistency of -two STHs. +two STHs as described in {consistency}. ## Merkle Inclusion Proofs @@ -1126,7 +1182,7 @@ encapsulates an `InclusionProofDataV2` structure: LogID log_id; uint64 tree_size; uint64 leaf_index; - NodeHash inclusion_path<1..2^16-1>; + NodeHash inclusion_path<0..2^16-1>; } InclusionProofDataV2; ~~~~~~~~~~~ @@ -1139,7 +1195,7 @@ encapsulates an `InclusionProofDataV2` structure: inclusion proof. `inclusion_path` is a vector of Merkle Tree nodes proving the inclusion of the -chosen certificate or precertificate. +chosen certificate or precertificate as described in {merkle_inclusion_proof}. ## Shutting down a log {#log_shutdown} @@ -1147,9 +1203,11 @@ Log operators may decide to shut down a log for various reasons, such as deprecation of the signature algorithm. If there are entries in the log for certificates that have not yet expired, simply making TLS clients stop recognizing that log will have the effect of invalidating SCTs from that log. -To avoid that, the following actions are suggested: +In order to avoid that, the following actions SHOULD be taken: * Make it known to clients and monitors that the log will be frozen. + This is not part of the API, so it will have to be done via a relevant + out-of-band mechanism. * Stop accepting new submissions (the error code "shutdown" should be returned for such requests). @@ -1172,18 +1230,20 @@ Messages are sent as HTTPS GET or POST requests. Parameters for POSTs and all responses are encoded as JavaScript Object Notation (JSON) objects [RFC8259]. Parameters for GETs are encoded as order-independent key/value URL parameters, using the "application/x-www-form-urlencoded" format described in the "HTML 4.01 -Specification" [HTML401]. Binary data is base64 encoded [RFC4648] as specified +Specification" [HTML401]. Binary data is base64 encoded according to +section 4 of [RFC4648] as specified in the individual messages. Clients are configured with a log's base URL, which is one of the log's parameters. Clients construct URLs for requests by appending suffixes to this base URL. This structure places some degree of restriction on how log operators -can deploy these services, as noted in [RFC7320]. However, operational +can deploy these services, as noted in [RFC8820]. However, operational experience with version 1 of this protocol has not indicated that these restrictions are a problem in practice. -Note that JSON objects and URL parameters may contain fields not specified here. -These extra fields SHOULD be ignored. +Note that JSON objects and URL parameters may contain fields not specified here, +to allow for experimentation. Any fields that are not understood SHOULD +be ignored. In practice, log servers may include multiple front-end machines. Since it is impractical to keep these machines in perfect sync, errors may occur that are @@ -1244,6 +1304,14 @@ responses as transient failures and MAY retry the same request without modification at a later date. Note that as per [RFC7231], in the case of a 503 response the log MAY include a `Retry-After:` header in order to request a minimum time for the client to wait before retrying the request. +In the absence of this header, this document does not specify a minimum. + +Clients SHOULD treat any 4xx error as a problem with the request and not +attempt to resubmit without some modification to the request. The full +status code MAY provide additional details. + +This document deliberately does not provide more specific guidance +on the use of HTTP status codes. ## Submit Entry to Log {#submit-entry} @@ -1259,7 +1327,8 @@ Inputs: `submission`: 1 for `x509_entry_v2`, or 2 for `precert_entry_v2`. chain: - : An array of zero or more base64 encoded CA certificates. The first element + : An array of zero or more JSON strings, + each of which is a base64 encoded CA certificate. The first element is the certifier of the `submission`; the second certifies the first; etc. The last element of `chain` (or, if `chain` is an empty array, the `submission`) is certified by an accepted trust anchor. @@ -1307,13 +1376,15 @@ which may be accepted by some TLS clients. If `submission` is an accepted trust anchor whose certifier is neither an accepted trust anchor nor the first element of `chain`, then the log MUST return -the "unknown anchor" error. A log cannot generate an SCT for a submission if it +the "unknown anchor" error. A log is not able to generate an SCT for a +submission if it does not have access to the issuer's public key. If the returned `sct` is intended to be provided to TLS clients, then `sth` and -`inclusion` (if returned) SHOULD also be provided to TLS clients (e.g., if -`type` was 2 (for `precert_sct_v2`) then all three `TransItem`s could be -embedded in the certificate). +`inclusion` (if returned) SHOULD also be provided to TLS clients. For +example, if +`type` was 2 (indicating `precert_sct_v2`) then all three `TransItem`s could be +embedded in the certificate. ## Retrieve Latest Signed Tree Head {#get-sth} @@ -1389,10 +1460,10 @@ Inputs: tree_size: : The tree_size of the tree on which to base the proof, in decimal. -> The `hash` must be calculated as defined in {{tree_leaves}}. The `tree_size` -> must designate an existing v2 STH. Because of skew, the front-end may not know -> the requested STH. In that case, it will return the latest STH it knows, along -> with an inclusion proof to that STH. If the front-end knows the requested STH +> The `hash` must be calculated as defined in {{tree_leaves}}. A v2 STH must +> exist for the `tree_size`. Because of skew, the front-end may not know +> the requested tree head. In that case, it will return the latest STH it knows, along +> with an inclusion proof to that STH. If the front-end knows the requested tree head > then only `inclusion` is returned. Outputs: @@ -1400,7 +1471,7 @@ Outputs: : inclusion: : A base64 encoded `TransItem` of type `inclusion_proof_v2` whose `inclusion_path` array of Merkle Tree nodes proves the inclusion of the - chosen certificate in the selected STH. + certificate (as specified by the `hash` parameter) in the selected STH. sth: : A base64 encoded `TransItem` of type `signed_tree_head_v2`, signed by this @@ -1432,17 +1503,17 @@ Inputs: tree_size: : The tree_size of the tree on which to base the proofs, in decimal. -> The `hash` must be calculated as defined in {{tree_leaves}}. The `tree_size` -> must designate an existing v2 STH. +> The `hash` must be calculated as defined in {{tree_leaves}}. A v2 STH must +> exist for the `tree_size`. -Because of skew, the front-end may not know the requested STH or the requested +Because of skew, the front-end may not know the requested tree head or the requested hash, which leads to a number of cases: |--------------------------------------+----------------------------------------------------------------------------------------------------------| | Case | Response | |--------------------------------------+----------------------------------------------------------------------------------------------------------| -| latest STH < requested STH | Return latest STH | -| latest STH > requested STH | Return latest STH and a consistency proof between it and the requested STH (see {{get-sth-consistency}}) | +| latest STH < requested tree head | Return latest STH | +| latest STH > requested tree head | Return latest STH and a consistency proof between it and the requested tree head (see {{get-sth-consistency}}) | | index of requested hash < latest STH | Return `inclusion` | |--------------------------------------+----------------------------------------------------------------------------------------------------------| @@ -1455,7 +1526,7 @@ Outputs: : inclusion: : A base64 encoded `TransItem` of type `inclusion_proof_v2` whose `inclusion_path` array of Merkle Tree nodes proves the inclusion of the - chosen certificate in the returned STH. + certificate (as specified by the `hash` parameter) in the selected STH. sth: : A base64 encoded `TransItem` of type `signed_tree_head_v2`, signed by this @@ -1463,7 +1534,7 @@ Outputs: consistency: : A base64 encoded `TransItem` of type `consistency_proof_v2` that proves the - consistency of the requested STH and the returned STH. + consistency of the requested tree head and the returned STH. > Note that no signature is required for the `inclusion` or `consistency` > outputs as they are used to verify inclusion in and consistency of STHs, which @@ -1497,7 +1568,7 @@ Outputs: `precert_entry_v2` (see {{log_entries}}). submitted_entry: - : JSON object representing the inputs that were submitted to + : JSON object equivalent to inputs that were submitted to `submit-entry`, with the addition of the trust anchor to the `chain` field if the submission did not include it. @@ -1537,6 +1608,9 @@ Logs MAY restrict the number of entries that can be retrieved per `get-entries` request. If a client requests more than the permitted number of entries, the log SHALL return the maximum number of entries permissible. These entries SHALL be sequential beginning with the entry specified by `start`. +Note that limit on the number of entries is not immutable and therefore +the restriction may be changed or lifted at any time and is not listed +with the other Log Parameters in {{log_parameters}}. Because of skew, it is possible the log server will not have any entries between `start` and `end`. In this case it MUST return an empty `entries` array. @@ -1564,48 +1638,74 @@ No inputs. Outputs: : certificates: - : An array of base64 encoded trust anchors that are acceptable to the log. - + : An array of JSON strings, each of which + is a base64 encoded CA certificate that is acceptable to the log. max_chain_length: : If the server has chosen to limit the length of chains it accepts, this is the maximum number of certificates in the chain, in decimal. If there is no limit, this is omitted. +> This data is not signed and the protocol depends on the security guarantees +> of TLS to ensure correctness. + # TLS Servers {#tls_servers} -CT-using TLS servers MUST use at least one of the three mechanisms listed below +CT-using TLS servers MUST use at least one of the mechanisms described below to present one or more SCTs from one or more logs to each TLS client during full -TLS handshakes, where each SCT corresponds to the server certificate. They +TLS handshakes, where each SCT corresponds to the server certificate. +(Of course, a server can only send a TLS extension if the client has +specified it first.) +Servers SHOULD also present corresponding inclusion proofs and STHs. -Three mechanisms are provided because they have different tradeoffs. - -* A TLS extension (Section 4.2 of [RFC8446]) with type `transparency_info` - (see {{tls_transinfo_extension}}). This mechanism allows TLS servers to - participate in CT without the cooperation of CAs, unlike the other two - mechanisms. It also allows SCTs and inclusion proofs to be updated on the fly. - -* An Online Certificate Status Protocol (OCSP) [RFC6960] response extension (see - {{ocsp_transinfo_extension}}), where the OCSP response is provided in the - `CertificateStatus` message, provided that the TLS client included the - `status_request` extension in the (extended) `ClientHello` (Section 8 of - [RFC6066]). This mechanism, popularly known as OCSP stapling, is already - widely (but not universally) implemented. It also allows SCTs and inclusion - proofs to be updated on the fly. - -* An X509v3 certificate extension (see {{cert_transinfo_extension}}). This - mechanism allows the use of unmodified TLS servers, but the SCTs and inclusion - proofs cannot be updated on the fly. Since the logs from which the SCTs and - inclusion proofs originated won't necessarily be accepted by TLS clients for - the full lifetime of the certificate, there is a risk that TLS clients will - subsequently consider the certificate to be non-compliant and in need of - re-issuance. +A server can provide SCTs using +a TLS 1.3 extension (Section 4.2 of [RFC8446]) with type `transparency_info` +(see {{tls_transinfo_extension}}). This mechanism allows TLS servers to +participate in CT without the cooperation of CAs, unlike the other two +mechanisms. It also allows SCTs and inclusion proofs to be updated on the fly. + +The server may also use an Online Certificate Status Protocol (OCSP) +[RFC6960] response extension (see {{ocsp_transinfo_extension}}), +providing the OCSP response as part of the TLS handshake. Providing +a response during a TLS handshake is popularly known as "OCSP stapling." +For TLS +1.3, the information is encoded as an extension in the `status_request` +extension data; see Section 4.4.2.1 of [RFC8446]. For TLS 1.2 ([RFC5246]), the information +is encoded as an extension in the `CertificateStatus` message; see Section 8 +of [RFC6066]. Using stapling also +allows SCTs and inclusion proofs to be updated on the fly. + +CT information can also be encoded as an extension in the X.509v3 certificate +(see {{cert_transinfo_extension}}). This +mechanism allows the use of unmodified TLS servers, but the SCTs and inclusion +proofs cannot be updated on the fly. Since the logs from which the SCTs and +inclusion proofs originated won't necessarily be accepted by TLS clients for +the full lifetime of the certificate, there is a risk that TLS clients may +subsequently consider the certificate to be non-compliant and in need of +re-issuance or the use of one of the other two methods for delivering CT +information. + +## TLS Client Authentication + +This specification includes no description of how a TLS server can +use CT for TLS client certificates. +While this may be useful, it is not documented here for the following +reasons: + +* The greater security exposure is for clients to end up interacting with an + illegitimate server. +* In general, TLS client certificates are not expected to be submitted to + CT logs, particularly those intended for general public use. + +A future version could include such information. ## Multiple SCTs {#multiple-scts} CT-using TLS servers SHOULD send SCTs from multiple logs, because: * One or more logs may not have become acceptable to all CT-using TLS clients. + Note that client discovery, trust, and distrust of logs is expected to + be handled out-of-band and is out of scope of this document. * If a CA and a log collude, it is possible to temporarily hide misissuance from clients. When a TLS client requires SCTs from multiple logs to be provided, it @@ -1646,7 +1746,7 @@ skipping over new `TransItem` structures whose versions they don't understand). ## Presenting SCTs, inclusions proofs and STHs {#presenting_transitems} -In each `TransItemList` that is sent to a client during a TLS handshake, the TLS +In each `TransItemList` that is sent during a TLS handshake, the TLS server MUST include a `TransItem` structure of type `x509_sct_v2` or `precert_sct_v2`. @@ -1668,7 +1768,9 @@ the ClientHello and the TLS server supports the `transparency_info` extension: already embedded in the server certificate or the stapled OCSP response (see {{x509v3_transinfo_extension}}). If the constructed `TransItemList` is not empty, then the TLS server MUST include the `transparency_info` extension with - the `extension_data` set to this `TransItemList`. + the `extension_data` set to this `TransItemList`. If the list is empty + then the server SHOULD omit the `extension_data` element, but MAY send + it with an empty array. TLS servers MUST only include this extension in the following messages: @@ -1855,6 +1957,8 @@ To inspect new entries, the monitor SHOULD follow these steps repeatedly for each log: 1. Fetch the current STH ({{get-sth}}). Repeat until the STH changes. +This document does not specify the polling frequency, to allow for +experimentation. 2. Verify the STH signature. @@ -1952,17 +2056,49 @@ instead. The assignment policy criteria mentioned in this section refer to the policies outlined in [RFC8126]. -## New Entry to the TLS ExtensionType Registry +## Additions to existing registries + +This sub-section defines additions to existing registries. + +### New Entry to the TLS ExtensionType Registry + +IANA is asked to add the following entry +to the "TLS ExtensionType Values" registry defined in [RFC8446], +with an assigned Value: + ++-----|-------------------|------------|-------------|-----------+ +Value | Extension Name | TLS 1.3 | Recommended | Reference | ++-----|-------------------|------------|-------------|-----------+ +TBD | transparency_info | CH, CR, CT | Y | RFCXXXX | ++-----|-------------------|------------|-------------|-----------+ + +### URN Sub-namespace for TRANS errors (urn:ietf:params:trans:error) + +IANA is requested to add a new entry in the +"IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" +registry, following the template in {{!RFC3553}}: + +Registry name: trans:error + +Specification: RFCXXXX + +Repository: https://www.iana.org/assignments/trans -IANA is asked to add an entry for `transparency_info(TBD)` to the "TLS -ExtensionType Values" registry defined in [RFC8446], setting the "Recommended" -value to "Y", setting the "TLS 1.3" value to "CH, CR, CT", and citing this -document as the "Reference". +Index value: No transformation needed. -## Hash Algorithms {#hash_algorithms} +## New CT-Related registries + +IANA is requested to add a new protocol registry, "Public Notary +Transparency", to the list that appears at +https://www.iana.org/assignments/ + +The rest of this section defines sub-registries to be +created within the new Public Notary Transparency registry. + +### Hash Algorithms {#hash_algorithms} IANA is asked to establish a registry of hash algorithm values, named -"CT Hash Algorithms", that initially consists of: +"Hash Algorithms", that initially consists of: |-------------+----------------+------------------------+-------------------------------| | Value | Hash Algorithm | OID | Reference / Assignment Policy | @@ -1973,17 +2109,29 @@ IANA is asked to establish a registry of hash algorithm values, named | 0xF0 - 0xFF | Reserved | | Private Use | |-------------+----------------+------------------------+-------------------------------| -### Specification Required guidance - -The appointed Expert should ensure that the proposed algorithm has a public +The Designated Expert(s) should ensure that the proposed algorithm has a public specification and is suitable for use as a cryptographic hash algorithm with no known preimage or collision attacks. These attacks can damage the integrity of the log. -## Signature Algorithms {#signature_algorithms} +### Signature Algorithms {#signature_algorithms} IANA is asked to establish a registry of signature algorithm values, named -"CT Signature Algorithms", that initially consists of: +"Signature Algorithms". + +The following notes should be added: + +- This is a subset of the TLS SignatureScheme Registry, limited to those +algorithms that are appropriate for CT. A major advantage of this is +leveraging the expertise of the TLS working group and its Designated +Expert(s). + +- The value `0x0403` appears twice. While this may be confusing, +it is okay because the verification +process is the same for both algorithms, and the choice of which to use +when generating a signature is purely internal to the log server. + +The registry should initially consist of: |--------------------------------+----------------------------------------------------+-------------------------------| | SignatureScheme Value | Signature Algorithm | Reference / Assignment Policy | @@ -1998,22 +2146,27 @@ IANA is asked to establish a registry of signature algorithm values, named | 0xFF00 - 0xFFFF | Reserved | Private Use | |--------------------------------+----------------------------------------------------+-------------------------------| -### Expert Review guidelines - -The appointed Expert should ensure that the proposed algorithm has a public +The Designated Expert(s) should ensure that the proposed algorithm has a public specification, has a value assigned to it in the TLS SignatureScheme Registry -(that IANA is asked to establish in [RFC8446]) and is suitable for use as a +(that IANA was asked to establish in [RFC8446]) and is suitable for use as a cryptographic signature algorithm. -## VersionedTransTypes {#versioned_trans_types} +### VersionedTransTypes {#versioned_trans_types} IANA is asked to establish a registry of `VersionedTransType` values, named -"CT VersionedTransTypes", that initially consists of: +"VersionedTransTypes". + +The following note should be added: + +- The 0x0000 value is reserved so that v1 SCTs are distinguishable from v2 +SCTs and other `TransItem` structures. + +The registry should initially consist of: |-----------------+---------------------------+-------------------------------| | Value | Type and Version | Reference / Assignment Policy | |-----------------+---------------------------+-------------------------------| -| 0x0000 | Reserved | [RFC6962] (*) | +| 0x0000 | Reserved | [RFC6962] | | 0x0001 | x509_entry_v2 | RFCXXXX | | 0x0002 | precert_entry_v2 | RFCXXXX | | 0x0003 | x509_sct_v2 | RFCXXXX | @@ -2026,19 +2179,12 @@ IANA is asked to establish a registry of `VersionedTransType` values, named | 0xF000 - 0xFFFF | Reserved | Private Use | |-----------------+---------------------------+-------------------------------| -(*) The 0x0000 value is reserved so that v1 SCTs are distinguishable from v2 -SCTs and other `TransItem` structures. - -\[RFC Editor: please update 'RFCXXXX' to refer to this document, once its RFC number is known.\] - -### Specification Required guidance - -The appointed Expert should review the public specification to ensure that it is +The Designated Expert(s) should review the public specification to ensure that it is detailed enough to ensure implementation interoperability. -## Log Artifact Extension Registry {#log_artifact_extension_registry} +### Log Artifact Extension Registry {#log_artifact_extension_registry} -IANA is asked to establish a registry of `ExtensionType` values, named "CT Log +IANA is asked to establish a registry of `ExtensionType` values, named "Log Artifact Extensions", that initially consists of: |-----------------+------------+-----+-------------------------------| @@ -2055,38 +2201,30 @@ The "Use" column should contain one or both of the following values: * "STH", for extensions specified for use in Signed Tree Heads. -### Specification Required guidance - -The appointed Expert should review the public specification to ensure that it is -detailed enough to ensure implementation interoperability. The Expert should +The Designated Expert(s) should review the public specification to ensure that it is +detailed enough to ensure implementation interoperability. They should also verify that the extension is appropriate to the contexts in which it is specified to be used (SCT, STH, or both). -## Object Identifiers - -This document uses object identifiers (OIDs) to identify Log IDs (see -{{log_id}}), the precertificate CMS `eContentType` (see {{precertificates}}), -and X.509v3 extensions in certificates (see {{cert_transinfo_extension}}) and -OCSP responses (see {{ocsp_transinfo_extension}}). The OIDs are defined in an -arc that was selected due to its short encoding. - ### Log ID Registry {#log_id_registry} -IANA is asked to establish a registry of Log IDs, named "CT Log ID Registry", +IANA is asked to establish a registry of Log IDs, named "Log ID Registry", that initially consists of: |------------------------------+--------------+--------------+-------------------------------| | Log ID | Log Base URL | Log Operator | Reference / Assignment Policy | |------------------------------+--------------+--------------+-------------------------------| | 1.3.101.8192 - 1.3.101.16383 | Unassigned | Unassigned | First Come First Served | -| 1.3.101.80.0 - 1.3.101.80.* | Unassigned | Unassigned | First Come First Served | +| 1.3.101.80.0 - 1.3.101.80.\* | Unassigned | Unassigned | First Come First Served | |------------------------------+--------------+--------------+-------------------------------| -All OIDs in the range from 1.3.101.8192 to 1.3.101.16383 have been reserved. +All OIDs in the range from 1.3.101.8192 to 1.3.101.16383 have been set aside +for Log IDs. This is a limited resource of 8,192 OIDs, each of which has an encoded length of 4 octets. -The 1.3.101.80 arc has been delegated. This is an unlimited resource, but only +The 1.3.101.80 arc has also been set assigned for LogIDs. +This is an unlimited resource, but only the 128 OIDs from 1.3.101.80.0 to 1.3.101.80.127 have an encoded length of only 4 octets. @@ -2105,6 +2243,58 @@ details in this registry. Since log operators can choose to not use this registry (see {{log_id}}), it is not expected to be a global directory of all logs. +### Error Types Registry + +IANA is requested to create a new registry for errors, +the "Error Types" registry. + +Requirements for this registry are Specification Required. + +This registry should have the following three fields: + +|------------+--------+-----------| +| Field Name | Type | Reference | +|------------+--------+-----------| +| identifier | string | RFCXXXX | +| meaning | string | RFCXXXX | +| reference | string | RFCXXXX | +|------------+--------+-----------| + +The initial values are as follows, taken from the text above: + +|------------+----------------------------------+-----------| +| Identifier | Meaning | Reference | +|------------+----------------------------------+-----------| +| malformed | The request could not be parsed. | RFCXXXX | +| badSubmission | `submission` is neither a valid certificate nor a valid precertificate | RFCXXXX | +| badType | `type` is neither 1 nor 2 | RFCXXXX | +| badChain | The first element of `chain` is not the certifier of the `submission`, or the second element does not certify the first, etc. | RFCXXXX | +| badCertificate | One or more certificates in the `chain` are not valid (e.g., not properly encoded) | RFCXXXX | +| unknownAnchor | The last element of `chain` (or, if `chain` is an empty array, the `submission`) both is not, and is not certified by, an accepted trust anchor | RFCXXXX | +| shutdown | The log is no longer accepting submissions | RFCXXXX | +| firstUnknown | `first` is before the latest known STH but is not from an existing STH. | RFCXXXX | +| secondUnknown | `second` is before the latest known STH but is not from an existing STH. | RFCXXXX | +| secondBeforeFirst | `second` is smaller than `first`. | RFCXXXX | +| hashUnknown | `hash` is not the hash of a known leaf (may be caused by skew or by a known certificate not yet merged). | RFCXXXX | +| treeSizeUnknown | `hash` is before the latest known STH but is not from an existing STH. | RFCXXXX | +| startUnknown | `start` is greater than the number of entries in the Merkle tree. | RFCXXXX | +| endBeforeStart | `start` cannot be greater than `end`. | RFCXXXX | +|------------+----------------------------------+-----------| + +## OID Assignment + +IANA is asked to assign one object identifier from the "SMI +Security for PKIX Module Identifier" registry to identify the +ASN.1 module in {{asn1_module}} of this document with an assigned +Decimal value. + +|---------+-------------------------+------------+ +| Decimal | Description | References | +|---------+-------------------------+------------+ +| TBD | id-mod-public-notary-v2 | RFCXXXX | +|---------+-------------------------+------------+ + + # Security Considerations With CAs, logs, and servers performing the actions described here, TLS clients @@ -2122,9 +2312,6 @@ owners will have a greater incentive to submit certificates to logs, possibly with the assistance of their CA, increasing the overall transparency of the system. -[I-D.ietf-trans-threat-analysis] provides a more detailed threat analysis of the -Certificate Transparency architecture. - ## Misissued Certificates Misissued certificates that have not been publicly logged, and thus do not have @@ -2147,8 +2334,7 @@ certificate with an SCT in the Merkle Tree within the MMD; presenting different, conflicting views of the Merkle Tree at different times and/or to different parties; issuing STHs too frequently; mutating the signature of a logged certificate; and failing to present a chain containing the certifier of a logged -certificate. Such misbehavior is detectable and [I-D.ietf-trans-threat-analysis] -provides more details on how this can be done. +certificate. Violation of the MMD contract is detected by log clients requesting a Merkle inclusion proof ({{get-proof-by-hash}}) for each observed SCT. These checks can @@ -2156,18 +2342,15 @@ be asynchronous and need only be done once per certificate. However, note that there may be privacy concerns (see {{fetching_inclusion_proofs}}). Violation of the append-only property or the STH issuance rate limit can be -detected by clients comparing their instances of the Signed Tree Heads. There -are various ways this could be done, for example via gossip (see -[I-D.ietf-trans-gossip]) or peer-to-peer communications or by sending STHs to -monitors (who could then directly check against their own copy of the relevant -log). Proof of misbehavior in such cases would be: a series of STHs that were +detected by multiple clients comparing their instances of the Signed Tree Heads. +This technique, known as "gossip," is an active area of research and not +defined here. +Proof of misbehavior in such cases would be: a series of STHs that were issued too closely together, proving violation of the STH issuance rate limit; or an STH with a root hash that does not match the one calculated from a copy of the log, proving violation of the append-only property. -## Preventing Tracking Clients {#prevent_tracking_clients} - -Clients that gossip STHs or report back SCTs can be tracked or traced if a log +Clients that report back SCTs can be tracked or traced if a log produces multiple STHs or SCTs with the same timestamp and data but different signatures. Logs SHOULD mitigate this risk by either: @@ -2197,16 +2380,16 @@ The authors would like to thank Erwann Abelea, Robin Alden, Andrew Ayer, Richard Barnes, Al Cutter, David Drysdale, Francis Dupont, Adam Eijdenberg, Stephen Farrell, Daniel Kahn Gillmor, Paul Hadfield, Brad Hill, Jeff Hodges, Paul Hoffman, Jeffrey Hutzelman, Kat Joyce, Stephen Kent, SM, Alexey Melnikov, Linus -Nordberg, Chris Palmer, Trevor Perrin, Pierre Phaneuf, Eric Rescorla, Melinda -Shore, Ryan Sleevi, Martin Smith, Carl Wallace and Paul Wouters for their -valuable contributions. +Nordberg, Chris Palmer, Trevor Perrin, Pierre Phaneuf, Eric Rescorla, Rich Salz, +Melinda Shore, Ryan Sleevi, Martin Smith, Carl Wallace and Paul Wouters for +their valuable contributions. A big thank you to Symantec for kindly donating the OIDs from the 1.3.101 arc that are used in this document. --- back -# Supporting v1 and v2 simultaneously {#v1_coexistence} +# Supporting v1 and v2 simultaneously (Informative) {#v1_coexistence} Certificate Transparency logs have to be either v1 (conforming to [RFC6962]) or v2 (conforming to this document), as the data structures are incompatible and so @@ -2238,3 +2421,87 @@ SCTs: * Sign that TBSCertificate (which now contains v1 and v2 SCTs) to issue the final X.509 certificate. + +# An ASN.1 Module (Informative) {#asn1_module} + +The following ASN.1 module may be useful to implementors. + +~~~~~~~~~~~ + +CertificateTransparencyV2Module-2021 + -- { OID Needed, but no point in using a short one } +DEFINITIONS IMPLICIT TAGS ::= BEGIN + +-- EXPORTS ALL -- + +IMPORTS + EXTENSION + FROM PKIX-CommonTypes-2009 -- RFC 5912 + { iso(1) identified-organization(3) dod(6) internet(1) + security(5) mechanisms(5) pkix(7) id-mod(0) + id-mod-pkixCommon-02(57) } + + CONTENT-TYPE + FROM CryptographicMessageSyntax-2010 -- RFC 6268 + { iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1) + pkcs-9(9) smime(16) modules(0) id-mod-cms-2009(58) } + + TBSCertificate + FROM PKIX1Explicit-2009 -- RFC 5912 + { iso(1) identified-organization(3) dod(6) internet(1) + security(5) mechanisms(5) pkix(7) id-mod(0) + id-mod-pkix1-explicit-02(51) } +; + +-- +-- Section 3.2. Precertificates +-- + +ct-tbsCertificate CONTENT-TYPE ::= { + TYPE TBSCertificate + IDENTIFIED BY id-ct-tbsCertificate } + +id-ct-tbsCertificate OBJECT IDENTIFIER ::= { 1 3 101 78 } + +-- +-- Section 7.1. Transparency Information X.509v3 Extension +-- + +ext-transparencyInfo EXTENSION ::= { + SYNTAX TransparencyInformationSyntax + IDENTIFIED BY id-ce-transparencyInfo + CRITICALITY { FALSE } } + +id-ce-transparencyInfo OBJECT IDENTIFIER ::= { 1 3 101 75 } + +TransparencyInformationSyntax ::= OCTET STRING + +-- +-- Section 7.1.1. OCSP Response Extension +-- + +ext-ocsp-transparencyInfo EXTENSION ::= { + SYNTAX TransparencyInformationSyntax + IDENTIFIED BY id-pkix-ocsp-transparencyInfo + CRITICALITY { FALSE } } + +id-pkix-ocsp-transparencyInfo OBJECT IDENTIFIER ::= + id-ce-transparencyInfo + +-- +-- Section 8.1.2. Reconstructing the TBSCertificate +-- + +ext-embeddedSCT-CTv1 EXTENSION ::= { + SYNTAX SignedCertificateTimestampList + IDENTIFIED BY id-ce-embeddedSCT-CTv1 + CRITICALITY { FALSE } } + +id-ce-embeddedSCT-CTv1 OBJECT IDENTIFIER ::= { + 1 3 6 1 4 1 11129 2 4 2 } + +SignedCertificateTimestampList ::= OCTET STRING + +END + +~~~~~~~~~~~