1 // Copyright (c) 2012 The Chromium Authors. All rights reserved. 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 NET_CERT_CERT_VERIFIER_H_ 6 #define NET_CERT_CERT_VERIFIER_H_ 7 8 #include <string> 9 10 #include "base/basictypes.h" 11 #include "net/base/completion_callback.h" 12 #include "net/base/net_export.h" 13 14 namespace net { 15 16 class BoundNetLog; 17 class CertVerifyResult; 18 class CRLSet; 19 class X509Certificate; 20 21 // CertVerifier represents a service for verifying certificates. 22 // 23 // CertVerifiers can handle multiple requests at a time. A simpler alternative 24 // for consumers that only have 1 outstanding request at a time is to create a 25 // SingleRequestCertVerifier wrapper around CertVerifier (which will 26 // automatically cancel the single request when it goes out of scope). 27 class NET_EXPORT CertVerifier { 28 public: 29 // Opaque pointer type used to cancel outstanding requests. 30 typedef void* RequestHandle; 31 32 enum VerifyFlags { 33 // If set, enables online revocation checking via CRLs and OCSP for the 34 // certificate chain. 35 VERIFY_REV_CHECKING_ENABLED = 1 << 0, 36 37 // If set, and the certificate being verified may be an EV certificate, 38 // attempt to verify the certificate according to the EV processing 39 // guidelines. In order to successfully verify a certificate as EV, 40 // either an online or offline revocation check must be successfully 41 // completed. To ensure it's possible to complete a revocation check, 42 // callers should also specify either VERIFY_REV_CHECKING_ENABLED or 43 // VERIFY_REV_CHECKING_ENABLED_EV_ONLY (to enable online checks), and 44 // VERIFY_CERT_IO_ENABLED (to enable network fetches for online checks). 45 VERIFY_EV_CERT = 1 << 1, 46 47 // If set, permits NSS to use the network when verifying certificates, 48 // such as to fetch missing intermediates or to check OCSP or CRLs. 49 // TODO(rsleevi): http://crbug.com/143300 - Define this flag for all 50 // verification engines with well-defined semantics, rather than being 51 // NSS only. 52 VERIFY_CERT_IO_ENABLED = 1 << 2, 53 54 // If set, enables online revocation checking via CRLs or OCSP when the 55 // chain is not covered by a fresh CRLSet, but only for certificates which 56 // may be EV, and only when VERIFY_EV_CERT is also set. 57 VERIFY_REV_CHECKING_ENABLED_EV_ONLY = 1 << 3, 58 59 // If set, this is equivalent to VERIFY_REV_CHECKING_ENABLED, in that it 60 // enables online revocation checking via CRLs or OCSP, but only 61 // for certificates issued by non-public trust anchors. Failure to check 62 // revocation is treated as a hard failure. 63 // Note: If VERIFY_CERT_IO_ENABLE is not also supplied, certificates 64 // that chain to local trust anchors will likely fail - for example, due to 65 // lacking fresh cached revocation issue (Windows) or because OCSP stapling 66 // can only provide information for the leaf, and not for any 67 // intermediates. 68 VERIFY_REV_CHECKING_REQUIRED_LOCAL_ANCHORS = 1 << 4, 69 }; 70 71 // When the verifier is destroyed, all certificate verification requests are 72 // canceled, and their completion callbacks will not be called. 73 virtual ~CertVerifier() {} 74 75 // Verifies the given certificate against the given hostname as an SSL server. 76 // Returns OK if successful or an error code upon failure. 77 // 78 // The |*verify_result| structure, including the |verify_result->cert_status| 79 // bitmask, is always filled out regardless of the return value. If the 80 // certificate has multiple errors, the corresponding status flags are set in 81 // |verify_result->cert_status|, and the error code for the most serious 82 // error is returned. 83 // 84 // |flags| is bitwise OR'd of VerifyFlags. 85 // If VERIFY_REV_CHECKING_ENABLED is set in |flags|, certificate revocation 86 // checking is performed. 87 // 88 // If VERIFY_EV_CERT is set in |flags| too, EV certificate verification is 89 // performed. If |flags| is VERIFY_EV_CERT (that is, 90 // VERIFY_REV_CHECKING_ENABLED is not set), EV certificate verification will 91 // not be performed. 92 // 93 // |crl_set| points to an optional CRLSet structure which can be used to 94 // avoid revocation checks over the network. 95 // 96 // |callback| must not be null. ERR_IO_PENDING is returned if the operation 97 // could not be completed synchronously, in which case the result code will 98 // be passed to the callback when available. 99 // 100 // |*out_req| will be filled with a handle to the async request. 101 // This handle is not valid after the request has completed. 102 // 103 // TODO(rsleevi): Move CRLSet* out of the CertVerifier signature. 104 virtual int Verify(X509Certificate* cert, 105 const std::string& hostname, 106 int flags, 107 CRLSet* crl_set, 108 CertVerifyResult* verify_result, 109 const CompletionCallback& callback, 110 RequestHandle* out_req, 111 const BoundNetLog& net_log) = 0; 112 113 // Cancels the specified request. |req| is the handle returned by Verify(). 114 // After a request is canceled, its completion callback will not be called. 115 virtual void CancelRequest(RequestHandle req) = 0; 116 117 // Creates a CertVerifier implementation that verifies certificates using 118 // the preferred underlying cryptographic libraries. 119 static CertVerifier* CreateDefault(); 120 }; 121 122 } // namespace net 123 124 #endif // NET_CERT_CERT_VERIFIER_H_ 125
