1 // Copyright 2015 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef BSSL_PKI_VERIFY_CERTIFICATE_CHAIN_H_ 6 #define BSSL_PKI_VERIFY_CERTIFICATE_CHAIN_H_ 7 8 #include <set> 9 10 #include <openssl/base.h> 11 #include <openssl/evp.h> 12 #include <openssl/pki/signature_verify_cache.h> 13 14 #include "cert_errors.h" 15 #include "input.h" 16 #include "parsed_certificate.h" 17 18 namespace bssl { 19 20 namespace der { 21 struct GeneralizedTime; 22 } 23 24 struct CertificateTrust; 25 26 // The key purpose (extended key usage) to check for during verification. 27 enum class KeyPurpose { 28 ANY_EKU, 29 SERVER_AUTH, 30 CLIENT_AUTH, 31 SERVER_AUTH_STRICT, // Skip ANY_EKU when checking, require EKU present in 32 // certificate. 33 CLIENT_AUTH_STRICT, // Skip ANY_EKU when checking, require EKU present in 34 // certificate. 35 }; 36 37 enum class InitialExplicitPolicy { 38 kFalse, 39 kTrue, 40 }; 41 42 enum class InitialPolicyMappingInhibit { 43 kFalse, 44 kTrue, 45 }; 46 47 enum class InitialAnyPolicyInhibit { 48 kFalse, 49 kTrue, 50 }; 51 52 // VerifyCertificateChainDelegate exposes delegate methods used when verifying a 53 // chain. 54 class OPENSSL_EXPORT VerifyCertificateChainDelegate { 55 public: 56 // Implementations should return true if |signature_algorithm| is allowed for 57 // certificate signing, false otherwise. When returning false implementations 58 // can optionally add high-severity errors to |errors| with details on why it 59 // was rejected. 60 virtual bool IsSignatureAlgorithmAcceptable( 61 SignatureAlgorithm signature_algorithm, CertErrors *errors) = 0; 62 63 // Implementations should return true if |public_key| is acceptable. This is 64 // called for each certificate in the chain, including the target certificate. 65 // When returning false implementations can optionally add high-severity 66 // errors to |errors| with details on why it was rejected. 67 // 68 // |public_key| can be assumed to be non-null. 69 virtual bool IsPublicKeyAcceptable(EVP_PKEY *public_key, 70 CertErrors *errors) = 0; 71 72 // This is called during verification to obtain a pointer to a signature 73 // verification cache if one exists. nullptr may be returned indicating there 74 // is no verification cache. 75 virtual SignatureVerifyCache *GetVerifyCache() = 0; 76 77 // This is called to determine if PreCertificates should be accepted, for the 78 // purpose of validating issued PreCertificates in a path. Most callers should 79 // return false here. This should never return true for TLS certificate 80 // validation. If this function returns true the CT precertificate poison 81 // extension will not prevent the certificate from being validated. 82 virtual bool AcceptPreCertificates() = 0; 83 84 virtual ~VerifyCertificateChainDelegate(); 85 }; 86 87 // VerifyCertificateChain() verifies an ordered certificate path in accordance 88 // with RFC 5280's "Certification Path Validation" algorithm (section 6). 89 // 90 // ----------------------------------------- 91 // Deviations from RFC 5280 92 // ----------------------------------------- 93 // 94 // * If Extended Key Usage appears on intermediates, it is treated as 95 // a restriction on subordinate certificates. 96 // * No revocation checking is performed. 97 // 98 // ----------------------------------------- 99 // Additional responsibilities of the caller 100 // ----------------------------------------- 101 // 102 // After successful path verification, the caller is responsible for 103 // subsequently checking: 104 // 105 // * The end-entity's KeyUsage before using its SPKI. 106 // * The end-entity's name/subjectAltName. Name constraints from intermediates 107 // will have already been applied, so it is sufficient to check the 108 // end-entity for a match. The caller MUST NOT check hostnames on the 109 // commonName field because this implementation does not apply dnsName 110 // constraints on commonName. 111 // 112 // --------- 113 // Inputs 114 // --------- 115 // 116 // certs: 117 // A non-empty chain of DER-encoded certificates, listed in the 118 // "forward" direction. The first certificate is the target 119 // certificate to verify, and the last certificate has trustedness 120 // given by |last_cert_trust| (generally a trust anchor). 121 // 122 // * certs[0] is the target certificate to verify. 123 // * certs[i+1] holds the certificate that issued cert_chain[i]. 124 // * certs[N-1] the root certificate 125 // 126 // Note that THIS IS NOT identical in meaning to the same named 127 // "certs" input defined in RFC 5280 section 6.1.1.a. The differences 128 // are: 129 // 130 // * The order of certificates is reversed 131 // * In RFC 5280 "certs" DOES NOT include the trust anchor 132 // 133 // last_cert_trust: 134 // Trustedness of |certs.back()|. The trustedness of |certs.back()| 135 // MUST BE decided by the caller -- this function takes it purely as 136 // an input. Moreover, the CertificateTrust can be used to specify 137 // trust anchor constraints. 138 // 139 // This combined with |certs.back()| (the root certificate) fills a 140 // similar role to "trust anchor information" defined in RFC 5280 141 // section 6.1.1.d. 142 // 143 // delegate: 144 // |delegate| must be non-null. It is used to answer policy questions such 145 // as whether a signature algorithm is acceptable, or a public key is strong 146 // enough. 147 // 148 // time: 149 // The UTC time to use for expiration checks. This is equivalent to 150 // the input from RFC 5280 section 6.1.1: 151 // 152 // (b) the current date/time. 153 // 154 // required_key_purpose: 155 // The key purpose that the target certificate needs to be valid for. 156 // 157 // user_initial_policy_set: 158 // This is equivalent to the same named input in RFC 5280 section 159 // 6.1.1: 160 // 161 // (c) user-initial-policy-set: A set of certificate policy 162 // identifiers naming the policies that are acceptable to the 163 // certificate user. The user-initial-policy-set contains the 164 // special value any-policy if the user is not concerned about 165 // certificate policy. 166 // 167 // initial_policy_mapping_inhibit: 168 // This is equivalent to the same named input in RFC 5280 section 169 // 6.1.1: 170 // 171 // (e) initial-policy-mapping-inhibit, which indicates if policy 172 // mapping is allowed in the certification path. 173 // 174 // initial_explicit_policy: 175 // This is equivalent to the same named input in RFC 5280 section 176 // 6.1.1: 177 // 178 // (f) initial-explicit-policy, which indicates if the path must be 179 // valid for at least one of the certificate policies in the 180 // user-initial-policy-set. 181 // 182 // initial_any_policy_inhibit: 183 // This is equivalent to the same named input in RFC 5280 section 184 // 6.1.1: 185 // 186 // (g) initial-any-policy-inhibit, which indicates whether the 187 // anyPolicy OID should be processed if it is included in a 188 // certificate. 189 // 190 // --------- 191 // Outputs 192 // --------- 193 // 194 // user_constrained_policy_set: 195 // Can be null. If non-null, |user_constrained_policy_set| will be filled 196 // with the matching policies (intersected with user_initial_policy_set). 197 // This is equivalent to the same named output in X.509 section 10.2. 198 // Note that it is OK for this to point to input user_initial_policy_set. 199 // 200 // errors: 201 // Must be non-null. The set of errors/warnings encountered while 202 // validating the path are appended to this structure. If verification 203 // failed, then there is guaranteed to be at least 1 high severity error 204 // written to |errors|. 205 // 206 // ------------------------- 207 // Trust Anchor constraints 208 // ------------------------- 209 // 210 // Conceptually, VerifyCertificateChain() sets RFC 5937's 211 // "enforceTrustAnchorConstraints" to true. 212 // 213 // One specifies trust anchor constraints using the |last_cert_trust| 214 // parameter in conjunction with extensions appearing in |certs.back()|. 215 // 216 // The trust anchor |certs.back()| is always passed as a certificate to 217 // this function, however the manner in which that certificate is 218 // interpreted depends on |last_cert_trust|: 219 // 220 // TRUSTED_ANCHOR: 221 // 222 // No properties from the root certificate, other than its Subject and 223 // SPKI, are checked during verification. This is the usual 224 // interpretation for a "trust anchor". 225 // 226 // enforce_anchor_expiry=true: 227 // 228 // The validity period of the root is checked, in addition to Subject and SPKI. 229 // 230 // enforce_anchor_constraints=true: 231 // 232 // Only a subset of extensions and properties from the certificate are checked. 233 // In general, constraints encoded by extensions are only enforced if the 234 // extension is present. 235 // 236 // * Signature: No 237 // * Validity (expiration): No 238 // * Key usage: Yes 239 // * Extended key usage: Yes (required if required_key_purpose is STRICT) 240 // * Basic constraints: Yes 241 // * Name constraints: Yes 242 // * Certificate policies: Yes 243 // * Policy Mappings: Yes 244 // * inhibitAnyPolicy: Yes 245 // * PolicyConstraints: Yes 246 // 247 // The presence of any other unrecognized extension marked as critical fails 248 // validation. 249 OPENSSL_EXPORT void VerifyCertificateChain( 250 const ParsedCertificateList &certs, const CertificateTrust &last_cert_trust, 251 VerifyCertificateChainDelegate *delegate, const der::GeneralizedTime &time, 252 KeyPurpose required_key_purpose, 253 InitialExplicitPolicy initial_explicit_policy, 254 const std::set<der::Input> &user_initial_policy_set, 255 InitialPolicyMappingInhibit initial_policy_mapping_inhibit, 256 InitialAnyPolicyInhibit initial_any_policy_inhibit, 257 std::set<der::Input> *user_constrained_policy_set, CertPathErrors *errors); 258 259 // Returns true if `cert` is self-signed. Returns false `cert` is not 260 // self-signed or there was an error. If `errors` is non-null, it will contain 261 // additional information about the problem. If `cache` is non-null, it will be 262 // used to cache the signature verification step. 263 OPENSSL_EXPORT bool VerifyCertificateIsSelfSigned(const ParsedCertificate &cert, 264 SignatureVerifyCache *cache, 265 CertErrors *errors); 266 267 } // namespace bssl 268 269 #endif // BSSL_PKI_VERIFY_CERTIFICATE_CHAIN_H_ 270