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 |