OLD | NEW |
1 // Copyright 2015 The Chromium Authors. All rights reserved. | 1 // Copyright 2015 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 #ifndef NET_CERT_INTERNAL_VERIFY_CERTIFICATE_CHAIN_H_ | 5 #ifndef NET_CERT_INTERNAL_VERIFY_CERTIFICATE_CHAIN_H_ |
6 #define NET_CERT_INTERNAL_VERIFY_CERTIFICATE_CHAIN_H_ | 6 #define NET_CERT_INTERNAL_VERIFY_CERTIFICATE_CHAIN_H_ |
7 | 7 |
8 #include <vector> | 8 #include <set> |
9 | 9 |
10 #include "base/compiler_specific.h" | 10 #include "base/compiler_specific.h" |
11 #include "base/memory/ref_counted.h" | 11 #include "base/memory/ref_counted.h" |
12 #include "net/base/net_export.h" | 12 #include "net/base/net_export.h" |
13 #include "net/cert/internal/cert_errors.h" | 13 #include "net/cert/internal/cert_errors.h" |
14 #include "net/cert/internal/parsed_certificate.h" | 14 #include "net/cert/internal/parsed_certificate.h" |
15 #include "net/der/input.h" | 15 #include "net/der/input.h" |
16 | 16 |
17 namespace net { | 17 namespace net { |
18 | 18 |
19 namespace der { | 19 namespace der { |
20 struct GeneralizedTime; | 20 struct GeneralizedTime; |
21 } | 21 } |
22 | 22 |
23 class SignaturePolicy; | 23 class SignaturePolicy; |
24 struct CertificateTrust; | 24 struct CertificateTrust; |
25 | 25 |
26 // The key purpose (extended key usage) to check for during verification. | 26 // The key purpose (extended key usage) to check for during verification. |
27 enum class KeyPurpose { | 27 enum class KeyPurpose { |
28 ANY_EKU, | 28 ANY_EKU, |
29 SERVER_AUTH, | 29 SERVER_AUTH, |
30 CLIENT_AUTH, | 30 CLIENT_AUTH, |
31 }; | 31 }; |
32 | 32 |
| 33 enum class InitialExplicitPolicy { |
| 34 kFalse, |
| 35 kTrue, |
| 36 }; |
| 37 |
| 38 enum class InitialPolicyMappingInhibit { |
| 39 kFalse, |
| 40 kTrue, |
| 41 }; |
| 42 |
| 43 enum class InitialAnyPolicyInhibit { |
| 44 kFalse, |
| 45 kTrue, |
| 46 }; |
| 47 |
33 // VerifyCertificateChain() verifies an ordered certificate path in accordance | 48 // VerifyCertificateChain() verifies an ordered certificate path in accordance |
34 // with RFC 5280 (with some modifications [1]). | 49 // with RFC 5280's "Certification Path Validation" algorithm (section 6). |
35 // | 50 // |
36 // [1] Deviations from RFC 5280: | 51 // ----------------------------------------- |
| 52 // Deviations from RFC 5280 |
| 53 // ----------------------------------------- |
37 // | 54 // |
38 // * If Extended Key Usage appears on intermediates it is treated as a | 55 // * If Extended Key Usage appears on intermediates, it is treated as |
39 // restriction on subordinate certificates. | 56 // a restriction on subordinate certificates. |
40 // | 57 // |
41 // The caller is responsible for additionally checking: | 58 // ----------------------------------------- |
| 59 // Additional responsibilities of the caller |
| 60 // ----------------------------------------- |
| 61 // |
| 62 // After successful path verification, the caller is responsible for |
| 63 // subsequently checking: |
42 // | 64 // |
43 // * The end-entity's KeyUsage before using its SPKI. | 65 // * The end-entity's KeyUsage before using its SPKI. |
44 // * The end-entity's name/subjectAltName (note that name constraints from | 66 // * The end-entity's name/subjectAltName. Name constraints from intermediates |
45 // intermediates will have already been applied, so just need to check | 67 // will have already been applied, so it is sufficient to check the |
46 // the end-entity for a match). | 68 // end-entity for a match. |
47 // * Policies | |
48 // | |
49 // WARNING: This implementation is in progress, and is currently incomplete. | |
50 // Consult an OWNER before using it. | |
51 // | |
52 // TODO(eroman): Take a CertPath instead of ParsedCertificateList + | |
53 // TrustAnchor. | |
54 // | 69 // |
55 // --------- | 70 // --------- |
56 // Inputs | 71 // Inputs |
57 // --------- | 72 // --------- |
58 // | 73 // |
59 // cert_chain: | 74 // certs: |
60 // A non-empty chain of N DER-encoded certificates, listed in the | 75 // A non-empty chain of DER-encoded certificates, listed in the |
61 // "forward" direction. The first certificate is the target certificate to | 76 // "forward" direction. The first certificate is the target |
62 // verify, and the last certificate has trustedness given by | 77 // certificate to verify, and the last certificate has trustedness |
63 // |last_cert_trust|. | 78 // given by |last_cert_trust| (generally a trust anchor). |
64 // | 79 // |
65 // * cert_chain[0] is the target certificate to verify. | 80 // * certs[0] is the target certificate to verify. |
66 // * cert_chain[i+1] holds the certificate that issued cert_chain[i]. | 81 // * certs[i+1] holds the certificate that issued cert_chain[i]. |
67 // * cert_chain[N-1] the root certificate | 82 // * certs[N-1] the root certificate |
| 83 // |
| 84 // Note that THIS IS NOT identical in meaning to the same named |
| 85 // "certs" input defined in RFC 5280 section 6.1.1.a. The differences |
| 86 // are: |
| 87 // |
| 88 // * The order of certificates is reversed |
| 89 // * In RFC 5280 "certs" DOES NOT include the trust anchor |
68 // | 90 // |
69 // last_cert_trust: | 91 // last_cert_trust: |
70 // Trustedness of certs.back(). The trustedness of certs.back() MUST BE | 92 // Trustedness of |certs.back()|. The trustedness of |certs.back()| |
71 // decided by the caller -- this function takes it purely as an input. | 93 // MUST BE decided by the caller -- this function takes it purely as |
72 // Moreover, the CertificateTrust can be used to specify trust anchor | 94 // an input. Moreover, the CertificateTrust can be used to specify |
73 // constraints [1] | 95 // trust anchor constraints. |
| 96 // |
| 97 // This combined with |certs.back()| (the root certificate) fills a |
| 98 // similar role to "trust anchor information" defined in RFC 5280 |
| 99 // section 6.1.1.d. |
74 // | 100 // |
75 // signature_policy: | 101 // signature_policy: |
76 // The policy to use when verifying signatures (what hash algorithms are | 102 // The policy to use when verifying signatures (what hash algorithms are |
77 // allowed, what length keys, what named curves, etc). | 103 // allowed, what length keys, what named curves, etc). |
78 // | 104 // |
79 // time: | 105 // time: |
80 // The UTC time to use for expiration checks. | 106 // The UTC time to use for expiration checks. This is equivalent to |
| 107 // the input from RFC 5280 section 6.1.1: |
81 // | 108 // |
82 // key_purpose: | 109 // (b) the current date/time. |
| 110 // |
| 111 // required_key_purpose: |
83 // The key purpose that the target certificate needs to be valid for. | 112 // The key purpose that the target certificate needs to be valid for. |
84 // | 113 // |
| 114 // user_initial_policy_set: |
| 115 // This is equivalent to the same named input in RFC 5280 section |
| 116 // 6.1.1: |
| 117 // |
| 118 // (c) user-initial-policy-set: A set of certificate policy |
| 119 // identifiers naming the policies that are acceptable to the |
| 120 // certificate user. The user-initial-policy-set contains the |
| 121 // special value any-policy if the user is not concerned about |
| 122 // certificate policy. |
| 123 // |
| 124 // initial_policy_mapping_inhibit: |
| 125 // This is equivalent to the same named input in RFC 5280 section |
| 126 // 6.1.1: |
| 127 // |
| 128 // (e) initial-policy-mapping-inhibit, which indicates if policy |
| 129 // mapping is allowed in the certification path. |
| 130 // |
| 131 // initial_explicit_policy: |
| 132 // This is equivalent to the same named input in RFC 5280 section |
| 133 // 6.1.1: |
| 134 // |
| 135 // (f) initial-explicit-policy, which indicates if the path must be |
| 136 // valid for at least one of the certificate policies in the |
| 137 // user-initial-policy-set. |
| 138 // |
| 139 // initial_any_policy_inhibit: |
| 140 // This is equivalent to the same named input in RFC 5280 section |
| 141 // 6.1.1: |
| 142 // |
| 143 // (g) initial-any-policy-inhibit, which indicates whether the |
| 144 // anyPolicy OID should be processed if it is included in a |
| 145 // certificate. |
| 146 // |
85 // --------- | 147 // --------- |
86 // Outputs | 148 // Outputs |
87 // --------- | 149 // --------- |
| 150 // |
| 151 // user_constrained_policy_set: |
| 152 // Can be null. If non-null, |user_constrained_policy_set| will be filled |
| 153 // with the matching policies (intersected with user_initial_policy_set). |
| 154 // This is equivalent to the same named output in X.509 section 10.2. |
| 155 // Note that it is OK for this to point to input user_initial_policy_set. |
| 156 // |
88 // errors: | 157 // errors: |
89 // Must be non-null. The set of errors/warnings encountered while | 158 // Must be non-null. The set of errors/warnings encountered while |
90 // validating the path are appended to this structure. If verification | 159 // validating the path are appended to this structure. If verification |
91 // failed, then there is guaranteed to be at least 1 high severity error | 160 // failed, then there is guaranteed to be at least 1 high severity error |
92 // written to |errors|. | 161 // written to |errors|. |
93 // | 162 // |
94 // [1] Conceptually VerifyCertificateChain() sets RFC 5937's | 163 // ------------------------- |
95 // "enforceTrustAnchorConstraints" to true. And one specifies whether to | 164 // Trust Anchor constraints |
96 // interpret a root certificate as having trust anchor constraints through the | 165 // ------------------------- |
97 // |last_cert_trust| parameter. The constraints are just a subset of the | 166 // |
98 // extensions present in the certificate: | 167 // Conceptually, VerifyCertificateChain() sets RFC 5937's |
| 168 // "enforceTrustAnchorConstraints" to true. |
| 169 // |
| 170 // One specifies trust anchor constraints using the |last_cert_trust| |
| 171 // parameter in conjunction with extensions appearing in |certs.back()|. |
| 172 // |
| 173 // The trust anchor |certs.back()| is always passed as a certificate to |
| 174 // this function, however the manner in which that certificate is |
| 175 // interpreted depends on |last_cert_trust|: |
| 176 // |
| 177 // TRUSTED_ANCHOR: |
| 178 // |
| 179 // No properties from the root certificate, other than its Subject and |
| 180 // SPKI, are checked during verification. This is the usual |
| 181 // interpretation for a "trust anchor". |
| 182 // |
| 183 // TRUSTED_ANCHOR_WITH_CONSTRAINTS: |
| 184 // |
| 185 // Only a subset of extensions and properties from the certificate are checked, |
| 186 // as described by RFC 5937. |
99 // | 187 // |
100 // * Signature: No | 188 // * Signature: No |
101 // * Validity (expiration): No | 189 // * Validity (expiration): No |
102 // * Key usage: No | 190 // * Key usage: No |
103 // * Extended key usage: Yes (not part of RFC 5937) | 191 // * Extended key usage: Yes (not part of RFC 5937) |
104 // * Basic constraints: Yes, but only the pathlen (CA=false is accepted) | 192 // * Basic constraints: Yes, but only the pathlen (CA=false is accepted) |
105 // * Name constraints: Yes | 193 // * Name constraints: Yes |
106 // * Certificate policies: Not currently, TODO(crbug.com/634453) | 194 // * Certificate policies: Not currently, TODO(crbug.com/634453) |
| 195 // * Policy Mappings: No |
107 // * inhibitAnyPolicy: Not currently, TODO(crbug.com/634453) | 196 // * inhibitAnyPolicy: Not currently, TODO(crbug.com/634453) |
108 // * PolicyConstraints: Not currently, TODO(crbug.com/634452) | 197 // * PolicyConstraints: Not currently, TODO(crbug.com/634452) |
109 // | 198 // |
110 // The presence of any other unrecognized extension marked as critical fails | 199 // The presence of any other unrecognized extension marked as critical fails |
111 // validation. | 200 // validation. |
112 NET_EXPORT void VerifyCertificateChain(const ParsedCertificateList& certs, | 201 NET_EXPORT void VerifyCertificateChain( |
113 const CertificateTrust& last_cert_trust, | 202 const ParsedCertificateList& certs, |
114 const SignaturePolicy* signature_policy, | 203 const CertificateTrust& last_cert_trust, |
115 const der::GeneralizedTime& time, | 204 const SignaturePolicy* signature_policy, |
116 KeyPurpose required_key_purpose, | 205 const der::GeneralizedTime& time, |
117 CertPathErrors* errors); | 206 KeyPurpose required_key_purpose, |
| 207 InitialExplicitPolicy initial_explicit_policy, |
| 208 const std::set<der::Input>& user_initial_policy_set, |
| 209 InitialPolicyMappingInhibit initial_policy_mapping_inhibit, |
| 210 InitialAnyPolicyInhibit initial_any_policy_inhibit, |
| 211 std::set<der::Input>* user_constrained_policy_set, |
| 212 CertPathErrors* errors); |
118 | 213 |
119 // TODO(crbug.com/634443): Move exported errors to a central location? | 214 // TODO(crbug.com/634443): Move exported errors to a central location? |
120 extern CertErrorId kValidityFailedNotAfter; | 215 extern CertErrorId kValidityFailedNotAfter; |
121 extern CertErrorId kValidityFailedNotBefore; | 216 extern CertErrorId kValidityFailedNotBefore; |
122 NET_EXPORT extern CertErrorId kCertIsDistrusted; | 217 NET_EXPORT extern CertErrorId kCertIsDistrusted; |
123 | 218 |
124 } // namespace net | 219 } // namespace net |
125 | 220 |
126 #endif // NET_CERT_INTERNAL_VERIFY_CERTIFICATE_CHAIN_H_ | 221 #endif // NET_CERT_INTERNAL_VERIFY_CERTIFICATE_CHAIN_H_ |
OLD | NEW |