| OLD | NEW |
| 1 # Certificate Transparency | 1 # Certificate Transparency |
| 2 | 2 |
| 3 ## Overview | 3 ## Overview |
| 4 | 4 |
| 5 [Certificate Transparency](http://www.certificate-transparency.org/) (CT) is a | 5 [Certificate Transparency](http://www.certificate-transparency.org/) (CT) is a |
| 6 protocol designed to fix several structural flaws in the SSL/TLS certificate | 6 protocol designed to fix several structural flaws in the SSL/TLS certificate |
| 7 ecosystem. Described by [RFC 6962](https://tools.ietf.org/html/rfc6962) and | 7 ecosystem. Described by [RFC 6962](https://tools.ietf.org/html/rfc6962) and |
| 8 the ongoing work in [RFC 6962-bis](https://datatracker.ietf.org/doc/draft-ietf-t
rans-rfc6962-bis/), | 8 the ongoing work in [RFC 6962-bis](https://datatracker.ietf.org/doc/draft-ietf-t
rans-rfc6962-bis/), |
| 9 it provides a means of providing a public, append-only data structure that | 9 it provides a means of providing a public, append-only data structure that |
| 10 can log certificates issued by [certificate authorities](https://en.wikipedia.or
g/wiki/Certificate_authority) (CAs). | 10 can log certificates issued by [certificate authorities](https://en.wikipedia.or
g/wiki/Certificate_authority) (CAs). |
| (...skipping 25 matching lines...) Expand all Loading... |
| 36 https://datatracker.ietf.org/doc/draft-ietf-trans-threat-analysis/ that | 36 https://datatracker.ietf.org/doc/draft-ietf-trans-threat-analysis/ that |
| 37 discusses the different risks in Certificate Transparency, and how the | 37 discusses the different risks in Certificate Transparency, and how the |
| 38 protocol addresses them. | 38 protocol addresses them. |
| 39 | 39 |
| 40 ## Certificate Transparency in `//net` | 40 ## Certificate Transparency in `//net` |
| 41 | 41 |
| 42 A goal of `//net` is to try to ensure that code is 'safe by default' when | 42 A goal of `//net` is to try to ensure that code is 'safe by default' when |
| 43 used. As part of serving that goal, in order to make a TLS or QUIC connection | 43 used. As part of serving that goal, in order to make a TLS or QUIC connection |
| 44 using code in `//net`, it's necessary for the `//net` embedder to make | 44 using code in `//net`, it's necessary for the `//net` embedder to make |
| 45 a decision about Certificate Transparency, much like it is necessary to | 45 a decision about Certificate Transparency, much like it is necessary to |
| 46 provide a [`CertVerifier`](../cert/cert_verifier.h) that describes how to | 46 provide a [`CertVerifier`](/net/cert/cert_verifier.h) that describes how to |
| 47 verify the server's certificate. | 47 verify the server's certificate. |
| 48 | 48 |
| 49 Because this is necessary to make a TLS or QUIC connection, this requirement | 49 Because this is necessary to make a TLS or QUIC connection, this requirement |
| 50 surfaces upwards through each layer in the stack - applying to things like | 50 surfaces upwards through each layer in the stack - applying to things like |
| 51 [`HttpNetworkSession`](../http/http_network_session.h) and upwards to | 51 [`HttpNetworkSession`](/net/http/http_network_session.h) and upwards to |
| 52 [`URLRequestContext`](../url_request/url_request_context.h). | 52 [`URLRequestContext`](/net/url_request/url_request_context.h). |
| 53 | 53 |
| 54 This requirement is expressed by requiring two separate, but related, objects | 54 This requirement is expressed by requiring two separate, but related, objects |
| 55 to be supplied: [`CTVerifier`](../cert/ct_verifier.h) and | 55 to be supplied: [`CTVerifier`](/net/cert/ct_verifier.h) and |
| 56 [`CTPolicyEnforcer`](../cert/ct_policy_enforcer.h), which together can be used | 56 [`CTPolicyEnforcer`](/net/cert/ct_policy_enforcer.h), which together can be used |
| 57 to express an application's policies with respect to Certificate Transparency. | 57 to express an application's policies with respect to Certificate Transparency. |
| 58 | 58 |
| 59 As part of the goal of ensuring 'safe by default', `//net` also has various | 59 As part of the goal of ensuring 'safe by default', `//net` also has various |
| 60 policies related to certificates issued by particular CAs whose past actions | 60 policies related to certificates issued by particular CAs whose past actions |
| 61 have created unnecessary security risk for TLS connections, and as a | 61 have created unnecessary security risk for TLS connections, and as a |
| 62 consequence, are required to have their certificates disclosed using | 62 consequence, are required to have their certificates disclosed using |
| 63 Certificate Transparency in order to ensure that the security provided by | 63 Certificate Transparency in order to ensure that the security provided by |
| 64 these CAs matches the level of security and assurance that other CAs provide. | 64 these CAs matches the level of security and assurance that other CAs provide. |
| 65 These policies are implemented in | 65 These policies are implemented in |
| 66 [`TransportSecurityState`](../http/transport_security_state.cc), via the | 66 [`TransportSecurityState`](/net/http/transport_security_state.cc), via the |
| 67 `ShouldRequireCT` method. | 67 `ShouldRequireCT` method. |
| 68 | 68 |
| 69 ### CTVerifier | 69 ### CTVerifier |
| 70 | 70 |
| 71 `CTVerifier` is the core interface for parsing and validating the structures | 71 `CTVerifier` is the core interface for parsing and validating the structures |
| 72 defined in RFC6962 (or future versions), and for providing basic information | 72 defined in RFC6962 (or future versions), and for providing basic information |
| 73 about the [`SignedCertificateTimestamps`](https://tools.ietf.org/html/rfc6962#se
ction-3.2) | 73 about the [`SignedCertificateTimestamps`](https://tools.ietf.org/html/rfc6962#se
ction-3.2) |
| 74 present within the connection. | 74 present within the connection. |
| 75 | 75 |
| 76 ### CTPolicyEnforcer | 76 ### CTPolicyEnforcer |
| 77 | 77 |
| 78 `CTPolicyEnforcer` is the core class for expressing an application's policies | 78 `CTPolicyEnforcer` is the core class for expressing an application's policies |
| 79 around how it expects Certificate Transparency to be used by the certificates | 79 around how it expects Certificate Transparency to be used by the certificates |
| 80 it trusts and the CAs that issue these certificates. | 80 it trusts and the CAs that issue these certificates. |
| 81 | 81 |
| 82 `CTPolicyEnforcer` currently expresses two policies: | 82 `CTPolicyEnforcer` currently expresses two policies: |
| 83 * How to treat [Extended Validation](https://cabforum.org/extended-validation-
2/) | 83 * How to treat [Extended Validation](https://cabforum.org/extended-validation-
2/) |
| 84 certificates (those for which a [`CertVerifier`](../cert/cert_verifier.h) | 84 certificates (those for which a [`CertVerifier`](/net/cert/cert_verifier.h) |
| 85 returned `CERT_STATUS_IS_EV`). | 85 returned `CERT_STATUS_IS_EV`). |
| 86 * How to treat all certificates, regardless of EV status. | 86 * How to treat all certificates, regardless of EV status. |
| 87 | 87 |
| 88 ### TransportSecurityState | 88 ### TransportSecurityState |
| 89 | 89 |
| 90 The `TransportSecurityState::ShouldRequireCT` method implements the core logic | 90 The `TransportSecurityState::ShouldRequireCT` method implements the core logic |
| 91 for determining whether or not a connection attempt should be rejected if it | 91 for determining whether or not a connection attempt should be rejected if it |
| 92 does not comply with an application's Certificate Transparency policy. | 92 does not comply with an application's Certificate Transparency policy. |
| 93 | 93 |
| 94 The implementation in `//net` provides a default implementation that tries to | 94 The implementation in `//net` provides a default implementation that tries to |
| 95 ensure maximum security, by failing connections that do not abide by an | 95 ensure maximum security, by failing connections that do not abide by an |
| 96 application's Certificate Transparency policy and are from CAs known to have | 96 application's Certificate Transparency policy and are from CAs known to have |
| 97 security issues in the past. | 97 security issues in the past. |
| 98 | 98 |
| 99 Embedders can customize or override this by providing a | 99 Embedders can customize or override this by providing a |
| 100 `TransportSecurityState::RequireCTDelegate` implementation, which allows | 100 `TransportSecurityState::RequireCTDelegate` implementation, which allows |
| 101 applications to inspect the connection information and determine whether | 101 applications to inspect the connection information and determine whether |
| 102 Certificate Transparency should be required, should not be required, or | 102 Certificate Transparency should be required, should not be required, or |
| 103 whether the default logic in `//net` should be used. | 103 whether the default logic in `//net` should be used. |
| 104 | 104 |
| 105 ## Certificate Transparency in Chromium | 105 ## Certificate Transparency in Chromium |
| 106 | 106 |
| 107 As part of the open-source implementation of Chrome, the policies related to | 107 As part of the open-source implementation of Chrome, the policies related to |
| 108 how Chromium code treats Certificate Transparency are documented at | 108 how Chromium code treats Certificate Transparency are documented at |
| 109 https://www.chromium.org/Home/chromium-security/certificate-transparency . This | 109 https://www.chromium.org/Home/chromium-security/certificate-transparency . This |
| 110 page includes the policies for how Chromium determines an acceptable set of | 110 page includes the policies for how Chromium determines an acceptable set of |
| 111 Certificate Transparency logs and what Certificate Transparency-related | 111 Certificate Transparency logs and what Certificate Transparency-related |
| 112 information is expected to accompany certificates, both for EV and non-EV. | 112 information is expected to accompany certificates, both for EV and non-EV. |
| 113 | 113 |
| 114 The implementation of these policies lives within [`//net/cert`](../cert), and | 114 The implementation of these policies lives within [`//net/cert`](/net/cert), and |
| 115 includes: | 115 includes: |
| 116 * [`ct_known_logs.h`](../cert/ct_known_logs.h): The set of Certificate | 116 * [`ct_known_logs.h`](/net/cert/ct_known_logs.h): The set of Certificate |
| 117 Transparency logs known and qualified according to Chromium's | 117 Transparency logs known and qualified according to Chromium's |
| 118 [Certificate Transparency Log Policy](https://www.chromium.org/Home/chromium
-security/certificate-transparency/log-policy). | 118 [Certificate Transparency Log Policy](https://www.chromium.org/Home/chromium
-security/certificate-transparency/log-policy). |
| 119 * ['multi_log_ct_verifier.h`](../cert/multi_log_ct_verifier.h): Capable of | 119 * [`multi_log_ct_verifier.h`](/net/cert/multi_log_ct_verifier.h): Capable of |
| 120 parsing `SignedCertificateTimestamps` s from a variety of logs and | 120 parsing `SignedCertificateTimestamps` from a variety of logs and |
| 121 validating their signatures, using the keys and information provided by | 121 validating their signatures, using the keys and information provided by |
| 122 `ct_known_logs.h`. | 122 `ct_known_logs.h`. |
| 123 * [`ct_policy_enforcer.h`](../cert/ct_policy_enforcer.h): A base class that | 123 * [`ct_policy_enforcer.h`](/net/cert/ct_policy_enforcer.h): A base class that |
| 124 implements the Certificate Transparency in Chrome Policy, for both EV and | 124 implements the Certificate Transparency in Chrome Policy, for both EV and |
| 125 non-EV certificates. | 125 non-EV certificates. |
| 126 | 126 |
| 127 ## Certificate Transparency for `//net` Consumers | 127 ## Certificate Transparency for `//net` Consumers |
| 128 | 128 |
| 129 This section is intended for code that is open-sourced as part of the | 129 This section is intended for code that is open-sourced as part of the |
| 130 Chromium projects, intended to be included within Google Chrome, and which | 130 Chromium projects, intended to be included within Google Chrome, and which |
| 131 uses the `//net` APIs for purposes other than loading and rendering web | 131 uses the `//net` APIs for purposes other than loading and rendering web |
| 132 content. Particularly, consumers of `//net` APIs that are communicating with | 132 content. Particularly, consumers of `//net` APIs that are communicating with |
| 133 a limited or defined set of endpoints and which don't use certificates issued | 133 a limited or defined set of endpoints and which don't use certificates issued |
| 134 by CAs. This may also include testing tools and utilities, as these are not | 134 by CAs. This may also include testing tools and utilities, as these are not |
| 135 generally shipped to users as part of Chrome. | 135 generally shipped to users as part of Chrome. |
| 136 | 136 |
| 137 Not every TLS connection may need the security assurances that | 137 Not every TLS connection may need the security assurances that |
| 138 Certificate Transparency aims to provide. For example, some consumers of | 138 Certificate Transparency aims to provide. For example, some consumers of |
| 139 `//net` APIs in Chromium use mutual authentication with self-signed | 139 `//net` APIs in Chromium use mutual authentication with self-signed |
| 140 certificates and which are authenticated out-of-band. For these connections, | 140 certificates and which are authenticated out-of-band. For these connections, |
| 141 Certificate Transparency is not relevant, and it's not necessary to parse | 141 Certificate Transparency is not relevant, and it's not necessary to parse |
| 142 or enforce Certificate Transparency related information. | 142 or enforce Certificate Transparency related information. |
| 143 | 143 |
| 144 For these cases, the approach is: | 144 For these cases, the approach is: |
| 145 * [`do_nothing_ct_verifier.h`](../cert/do_nothing_ct_verifier.h): A no-op | 145 * [`do_nothing_ct_verifier.h`](/net/cert/do_nothing_ct_verifier.h): A no-op |
| 146 CTVerifier that does not parse or verify Certificate Transparency-related | 146 CTVerifier that does not parse or verify Certificate Transparency-related |
| 147 information. | 147 information. |
| 148 * A derived `CTPolicyEnforcer` implementation that indicates all | 148 * A derived `CTPolicyEnforcer` implementation that indicates all |
| 149 certificates comply with its policies. | 149 certificates comply with its policies. |
| 150 **TODO(rsleevi):** Provide a DoNothingCTPolicyEnforcer | 150 |
| 151 **TODO(rsleevi):** Provide a `DoNothingCTPolicyEnforcer` |
| 151 | 152 |
| 152 As documented in these classes, care should be taken before using these, as | 153 As documented in these classes, care should be taken before using these, as |
| 153 they provide much weaker security guarantees. In general, emailing | 154 they provide much weaker security guarantees. In general, emailing |
| 154 net-dev@chromium.org or discussing it during a security review is the right | 155 [net-dev@chromium.org](mailto:net-dev@chromium.org) or discussing it during a |
| 155 answer, and documenting at the instantiation points why it is safe and | 156 security review is the right answer, and documenting at the instantiation |
| 156 acceptable to use these classes. | 157 points why it is safe and acceptable to use these classes. |
| 157 | 158 |
| 158 ## Certificate Transparency for `//net` Embedders | 159 ## Certificate Transparency for `//net` Embedders |
| 159 | 160 |
| 160 This section is intended for code that is used in other open-source Chromium | 161 This section is intended for code that is used in other open-source Chromium |
| 161 based projects, but are not included in Google Chrome or related. This | 162 based projects, but are not included in Google Chrome or related. This |
| 162 includes projects based on `//net`, such as `//components/cronet` or other | 163 includes projects based on `//net`, such as |
| 163 `//content` embedders. | 164 [`//components/cronet`](/components/cronet) or other |
| 165 [`//content`](/content) embedders. |
| 164 | 166 |
| 165 For projects and third party products that embed `//net`, the policies | 167 For projects and third party products that embed `//net`, the policies |
| 166 that are included as part of the open-source repository may not be | 168 that are included as part of the open-source repository may not be |
| 167 appropriate. This is because the implementations may rely implicitly | 169 appropriate. This is because the implementations may rely implicitly |
| 168 or explicitly on several key guarantees that come from Google-branded | 170 or explicitly on several key guarantees that come from Google-branded |
| 169 distributions and products, and may not be appropriate for other cases. | 171 distributions and products, and may not be appropriate for other cases. |
| 170 | 172 |
| 171 These key expectations are: | 173 These key expectations are: |
| 172 * A release cycle aligned with Chrome releases; that is, every six weeks, | 174 * A release cycle aligned with Chrome releases; that is, every six weeks, |
| 173 and on the same versions as Chrome releases. | 175 and on the same versions as Chrome releases. |
| 174 * Widespread support for automatic updates. | 176 * Widespread support for automatic updates. |
| 175 * That [`base::GetBuildTime()`](../../base/build_time.h) will reflect, to | 177 * That [`base::GetBuildTime()`](/base/build_time.h) will reflect, to |
| 176 some degree, when the tree was branched and/or released, and will not | 178 some degree, when the tree was branched and/or released, and will not |
| 177 be re-generated on recompilation. That is, this implies is_official_build | 179 be re-generated on recompilation. That is, this implies is_official_build |
| 178 for binaries released to end-users, but is not enforced in code so that | 180 for binaries released to end-users, but is not enforced in code so that |
| 179 developers can accurately test release behavior. | 181 developers can accurately test release behavior. |
| 180 * Support for dynamic [`base::FieldTrial`](../../base/metrics/field_trial.h) | 182 * Support for dynamic [`base::FieldTrial`](/base/metrics/field_trial.h) |
| 181 configurations. | 183 configurations. |
| 182 | 184 |
| 183 For projects that don't support automatic updates, or which measure 'stable' | 185 For projects that don't support automatic updates, or which measure 'stable' |
| 184 on the order of months to years, or which don't have tools suitable to | 186 on the order of months to years, or which don't have tools suitable to |
| 185 respond to changes in the Certificate Authority and Certificate Transparency | 187 respond to changes in the Certificate Authority and Certificate Transparency |
| 186 ecosystem, it may not be appropriate to enable Certificate Transparency | 188 ecosystem, it may not be appropriate to enable Certificate Transparency |
| 187 support yet. | 189 support yet. |
| 188 | 190 |
| 189 These issues are not unique or particular to Certificate Transparency - in | 191 These issues are not unique or particular to Certificate Transparency - in |
| 190 many ways, they're similar to issues already faced with determining which | 192 many ways, they're similar to issues already faced with determining which |
| 191 CAs are trusted and how to successfully validate a TLS server's certificate. | 193 CAs are trusted and how to successfully validate a TLS server's certificate. |
| 192 However, as the Certificate Transparency ecosystem is still growing, it may be | 194 However, as the Certificate Transparency ecosystem is still growing, it may be |
| 193 suitable to disable support until some of the solutions to these challenges | 195 suitable to disable support until some of the solutions to these challenges |
| 194 stablize. | 196 stablize. |
| 195 | 197 |
| 196 To opt-out of enforcing Certificate Transparency, using the `DoNothing` | 198 To opt-out of enforcing Certificate Transparency, using the `DoNothing` |
| 197 variants discussed above provides a suitable implementation that will opt to | 199 variants discussed above provides a suitable implementation that will opt to |
| 198 'fail open' instead. This may provide less security, but provides greater | 200 'fail open' instead. This may provide less security, but provides greater |
| 199 stability, and minimizes the risk that these `//net` embedding clients | 201 stability, and minimizes the risk that these `//net` embedding clients |
| 200 might cause to the Certificate Transparency ecosystem or receive from enabling | 202 might cause to the Certificate Transparency ecosystem or receive from enabling |
| 201 Certificate Transparency. | 203 Certificate Transparency. |
| OLD | NEW |