15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 5c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#ifndef NET_CERT_CERT_VERIFIER_H_ 6c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#define NET_CERT_CERT_VERIFIER_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <string> 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/basictypes.h" 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/completion_callback.h" 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "net/base/net_export.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace net { 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class BoundNetLog; 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class CertVerifyResult; 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class CRLSet; 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class X509Certificate; 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// CertVerifier represents a service for verifying certificates. 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// CertVerifiers can handle multiple requests at a time. A simpler alternative 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// for consumers that only have 1 outstanding request at a time is to create a 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// SingleRequestCertVerifier wrapper around CertVerifier (which will 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// automatically cancel the single request when it goes out of scope). 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class NET_EXPORT CertVerifier { 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Opaque pointer type used to cancel outstanding requests. 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) typedef void* RequestHandle; 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum VerifyFlags { 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If set, enables online revocation checking via CRLs and OCSP for the 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // certificate chain. 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) VERIFY_REV_CHECKING_ENABLED = 1 << 0, 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If set, and the certificate being verified may be an EV certificate, 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // attempt to verify the certificate according to the EV processing 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // guidelines. In order to successfully verify a certificate as EV, 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // either an online or offline revocation check must be successfully 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // completed. To ensure it's possible to complete a revocation check, 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callers should also specify either VERIFY_REV_CHECKING_ENABLED or 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // VERIFY_REV_CHECKING_ENABLED_EV_ONLY (to enable online checks), and 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // VERIFY_CERT_IO_ENABLED (to enable network fetches for online checks). 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) VERIFY_EV_CERT = 1 << 1, 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If set, permits NSS to use the network when verifying certificates, 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // such as to fetch missing intermediates or to check OCSP or CRLs. 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TODO(rsleevi): http://crbug.com/143300 - Define this flag for all 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // verification engines with well-defined semantics, rather than being 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NSS only. 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) VERIFY_CERT_IO_ENABLED = 1 << 2, 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 54a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles) // If set, enables online revocation checking via CRLs or OCSP when the 55a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles) // chain is not covered by a fresh CRLSet, but only for certificates which 56a36e5920737c6adbddd3e43b760e5de8431db6e0Torne (Richard Coles) // may be EV, and only when VERIFY_EV_CERT is also set. 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) VERIFY_REV_CHECKING_ENABLED_EV_ONLY = 1 << 3, 58558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch 59558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // If set, this is equivalent to VERIFY_REV_CHECKING_ENABLED, in that it 60558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // enables online revocation checking via CRLs or OCSP, but only 61558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // for certificates issued by non-public trust anchors. Failure to check 62558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // revocation is treated as a hard failure. 63558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // Note: If VERIFY_CERT_IO_ENABLE is not also supplied, certificates 64558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // that chain to local trust anchors will likely fail - for example, due to 65558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // lacking fresh cached revocation issue (Windows) or because OCSP stapling 66558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // can only provide information for the leaf, and not for any 67558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // intermediates. 68558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch VERIFY_REV_CHECKING_REQUIRED_LOCAL_ANCHORS = 1 << 4, 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // When the verifier is destroyed, all certificate verification requests are 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // canceled, and their completion callbacks will not be called. 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~CertVerifier() {} 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Verifies the given certificate against the given hostname as an SSL server. 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns OK if successful or an error code upon failure. 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The |*verify_result| structure, including the |verify_result->cert_status| 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // bitmask, is always filled out regardless of the return value. If the 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // certificate has multiple errors, the corresponding status flags are set in 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |verify_result->cert_status|, and the error code for the most serious 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // error is returned. 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |flags| is bitwise OR'd of VerifyFlags. 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If VERIFY_REV_CHECKING_ENABLED is set in |flags|, certificate revocation 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // checking is performed. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // If VERIFY_EV_CERT is set in |flags| too, EV certificate verification is 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // performed. If |flags| is VERIFY_EV_CERT (that is, 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // VERIFY_REV_CHECKING_ENABLED is not set), EV certificate verification will 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not be performed. 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |crl_set| points to an optional CRLSet structure which can be used to 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // avoid revocation checks over the network. 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |callback| must not be null. ERR_IO_PENDING is returned if the operation 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // could not be completed synchronously, in which case the result code will 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // be passed to the callback when available. 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1002a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // |*out_req| will be filled with a handle to the async request. 1012a99a7e74a7f215066514fe81d2bfa6639d9edddTorne (Richard Coles) // This handle is not valid after the request has completed. 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TODO(rsleevi): Move CRLSet* out of the CertVerifier signature. 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual int Verify(X509Certificate* cert, 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& hostname, 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int flags, 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) CRLSet* crl_set, 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) CertVerifyResult* verify_result, 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const CompletionCallback& callback, 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) RequestHandle* out_req, 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const BoundNetLog& net_log) = 0; 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Cancels the specified request. |req| is the handle returned by Verify(). 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // After a request is canceled, its completion callback will not be called. 1155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual void CancelRequest(RequestHandle req) = 0; 1165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Creates a CertVerifier implementation that verifies certificates using 1185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the preferred underlying cryptographic libraries. 1195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static CertVerifier* CreateDefault(); 1205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace net 1235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 124c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#endif // NET_CERT_CERT_VERIFIER_H_ 125