Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(572)

Side by Side Diff: net/docs/certificate-transparency.md

Issue 2758763002: Correct some Markdown typos in CT documentation (Closed)
Patch Set: Absolutify links per Gitiles Markdown Syntax Created 3 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
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.
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698