security/certverifier/CertVerifier.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef CertVerifier_h
   8 #define CertVerifier_h
   9
  10 #include "CTPolicyEnforcer.h"
  11 #include "CTVerifyResult.h"
  12 #include "EnterpriseRoots.h"
  13 #include "OCSPCache.h"
  14 #include "RootCertificateTelemetryUtils.h"
  15 #include "ScopedNSSTypes.h"
  16 #include "mozilla/EnumSet.h"
  17 #include "mozilla/Telemetry.h"
  18 #include "mozilla/TimeStamp.h"
  19 #include "mozilla/UniquePtr.h"
  20 #include "nsString.h"
  21 #include "mozpkix/pkixtypes.h"
  22 #include "sslt.h"
  23
  24 #if defined(_MSC_VER)
  25 #  pragma warning(push)
  26 // Silence "RootingAPI.h(718): warning C4324: 'js::DispatchWrapper<T>':
  27 // structure was padded due to alignment specifier with [ T=void * ]"
  28 #  pragma warning(disable : 4324)
  29 #endif /* defined(_MSC_VER) */
  30 #include "mozilla/BasePrincipal.h"
  31 #if defined(_MSC_VER)
  32 #  pragma warning(pop) /* popping the pragma in this file */
  33 #endif                 /* defined(_MSC_VER) */
  34
  35 namespace mozilla {
  36 namespace ct {
  37
  38 // Including the headers of the classes below would bring along all of their
  39 // dependent headers and force us to export them in moz.build.
  40 // Just forward-declare the classes here instead.
  41 class MultiLogCTVerifier;
  42 class CTDiversityPolicy;
  43
  44 }  // namespace ct
  45 }  // namespace mozilla
  46
  47 namespace mozilla {
  48 namespace psm {
  49
  50 typedef mozilla::pkix::Result Result;
  51
  52 enum class EVStatus : uint8_t {
  53   NotEV = 0,
  54   EV = 1,
  55 };
  56
  57 // These values correspond to the CERT_CHAIN_KEY_SIZE_STATUS telemetry.
  58 enum class KeySizeStatus {
  59   NeverChecked = 0,
  60   LargeMinimumSucceeded = 1,
  61   CompatibilityRisk = 2,
  62   AlreadyBad = 3,
  63 };
  64
  65 enum class CRLiteMode {
  66   Disabled = 0,
  67   TelemetryOnly = 1,
  68   Enforce = 2,
  69   ConfirmRevocations = 3,
  70 };
  71
  72 enum class NetscapeStepUpPolicy : uint32_t;
  73
  74 // Describes the source of the associated issuer.
  75 enum class IssuerSource {
  76   TLSHandshake,            // included by the peer in the TLS handshake
  77   PreloadedIntermediates,  // a preloaded intermediate (via remote settings)
  78   ThirdPartyCertificates,  // a third-party certificate gleaned from the OS
  79   NSSCertDB,  // a certificate found in the profile's NSS certificate DB
  80   BuiltInRootsModule,  // a root from the built-in roots module
  81 };
  82
  83 using IssuerSources = EnumSet<IssuerSource>;
  84
  85 class PinningTelemetryInfo {
  86  public:
  87   PinningTelemetryInfo()
  88       : certPinningResultBucket(0), rootBucket(ROOT_CERTIFICATE_UNKNOWN) {
  89     Reset();
  90   }
  91
  92   // Should we accumulate pinning telemetry for the result?
  93   bool accumulateResult;
  94   Maybe<Telemetry::HistogramID> certPinningResultHistogram;
  95   int32_t certPinningResultBucket;
  96   // Should we accumulate telemetry for the root?
  97   bool accumulateForRoot;
  98   int32_t rootBucket;
  99
 100   void Reset() {
 101     accumulateForRoot = false;
 102     accumulateResult = false;
 103   }
 104 };
 105
 106 class CertificateTransparencyInfo {
 107  public:
 108   CertificateTransparencyInfo()
 109       : enabled(false),
 110         policyCompliance(mozilla::ct::CTPolicyCompliance::Unknown) {
 111     Reset();
 112   }
 113
 114   // Was CT enabled?
 115   bool enabled;
 116   // Verification result of the processed SCTs.
 117   mozilla::ct::CTVerifyResult verifyResult;
 118   // Connection compliance to the CT Policy.
 119   mozilla::ct::CTPolicyCompliance policyCompliance;
 120
 121   void Reset();
 122 };
 123
 124 class DelegatedCredentialInfo {
 125  public:
 126   DelegatedCredentialInfo() : scheme(ssl_sig_none), authKeyBits(0) {}
 127   DelegatedCredentialInfo(SSLSignatureScheme scheme, uint32_t authKeyBits)
 128       : scheme(scheme), authKeyBits(authKeyBits) {}
 129
 130   // The signature scheme to be used in CertVerify. This tells us
 131   // whether to interpret |authKeyBits| in an RSA or ECDSA context.
 132   SSLSignatureScheme scheme;
 133
 134   // The size of the key, in bits.
 135   uint32_t authKeyBits;
 136 };
 137
 138 class NSSCertDBTrustDomain;
 139
 140 class CertVerifier {
 141  public:
 142   typedef unsigned int Flags;
 143   // XXX: FLAG_LOCAL_ONLY is ignored in the classic verification case
 144   static const Flags FLAG_LOCAL_ONLY;
 145   // Don't perform fallback DV validation on EV validation failure.
 146   static const Flags FLAG_MUST_BE_EV;
 147   // TLS feature request_status should be ignored
 148   static const Flags FLAG_TLS_IGNORE_STATUS_REQUEST;
 149
 150   // These values correspond to the SSL_OCSP_STAPLING telemetry.
 151   enum OCSPStaplingStatus {
 152     OCSP_STAPLING_NEVER_CHECKED = 0,
 153     OCSP_STAPLING_GOOD = 1,
 154     OCSP_STAPLING_NONE = 2,
 155     OCSP_STAPLING_EXPIRED = 3,
 156     OCSP_STAPLING_INVALID = 4,
 157   };
 158
 159   // *evOidPolicy == SEC_OID_UNKNOWN means the cert is NOT EV
 160   // Only one usage per verification is supported.
 161   mozilla::pkix::Result VerifyCert(
 162       const nsTArray<uint8_t>& certBytes, SECCertificateUsage usage,
 163       mozilla::pkix::Time time, void* pinArg, const char* hostname,
 164       /*out*/ nsTArray<nsTArray<uint8_t>>& builtChain, Flags flags = 0,
 165       /*optional in*/
 166       const Maybe<nsTArray<nsTArray<uint8_t>>>& extraCertificates = Nothing(),
 167       /*optional in*/ const Maybe<nsTArray<uint8_t>>& stapledOCSPResponseArg =
 168           Nothing(),
 169       /*optional in*/ const Maybe<nsTArray<uint8_t>>& sctsFromTLS = Nothing(),
 170       /*optional in*/ const OriginAttributes& originAttributes =
 171           OriginAttributes(),
 172       /*optional out*/ EVStatus* evStatus = nullptr,
 173       /*optional out*/ OCSPStaplingStatus* ocspStaplingStatus = nullptr,
 174       /*optional out*/ KeySizeStatus* keySizeStatus = nullptr,
 175       /*optional out*/ PinningTelemetryInfo* pinningTelemetryInfo = nullptr,
 176       /*optional out*/ CertificateTransparencyInfo* ctInfo = nullptr,
 177       /*optional out*/ bool* isBuiltChainRootBuiltInRoot = nullptr,
 178       /*optional out*/ bool* madeOCSPRequests = nullptr,
 179       /*optional out*/ IssuerSources* = nullptr);
 180
 181   mozilla::pkix::Result VerifySSLServerCert(
 182       const nsTArray<uint8_t>& peerCert, mozilla::pkix::Time time, void* pinarg,
 183       const nsACString& hostname,
 184       /*out*/ nsTArray<nsTArray<uint8_t>>& builtChain,
 185       /*optional*/ Flags flags = 0,
 186       /*optional*/ const Maybe<nsTArray<nsTArray<uint8_t>>>& extraCertificates =
 187           Nothing(),
 188       /*optional*/ const Maybe<nsTArray<uint8_t>>& stapledOCSPResponse =
 189           Nothing(),
 190       /*optional*/ const Maybe<nsTArray<uint8_t>>& sctsFromTLS = Nothing(),
 191       /*optional*/ const Maybe<DelegatedCredentialInfo>& dcInfo = Nothing(),
 192       /*optional*/ const OriginAttributes& originAttributes =
 193           OriginAttributes(),
 194       /*optional out*/ EVStatus* evStatus = nullptr,
 195       /*optional out*/ OCSPStaplingStatus* ocspStaplingStatus = nullptr,
 196       /*optional out*/ KeySizeStatus* keySizeStatus = nullptr,
 197       /*optional out*/ PinningTelemetryInfo* pinningTelemetryInfo = nullptr,
 198       /*optional out*/ CertificateTransparencyInfo* ctInfo = nullptr,
 199       /*optional out*/ bool* isBuiltChainRootBuiltInRoot = nullptr,
 200       /*optional out*/ bool* madeOCSPRequests = nullptr,
 201       /*optional out*/ IssuerSources* = nullptr);
 202
 203   enum OcspDownloadConfig { ocspOff = 0, ocspOn = 1, ocspEVOnly = 2 };
 204   enum OcspStrictConfig { ocspRelaxed = 0, ocspStrict };
 205
 206   enum class CertificateTransparencyMode {
 207     Disabled = 0,
 208     TelemetryOnly = 1,
 209   };
 210
 211   CertVerifier(OcspDownloadConfig odc, OcspStrictConfig osc,
 212                mozilla::TimeDuration ocspTimeoutSoft,
 213                mozilla::TimeDuration ocspTimeoutHard,
 214                uint32_t certShortLifetimeInDays,
 215                NetscapeStepUpPolicy netscapeStepUpPolicy,
 216                CertificateTransparencyMode ctMode, CRLiteMode crliteMode,
 217                const nsTArray<EnterpriseCert>& thirdPartyCerts);
 218   ~CertVerifier();
 219
 220   void ClearOCSPCache() { mOCSPCache.Clear(); }
 221
 222   const OcspDownloadConfig mOCSPDownloadConfig;
 223   const bool mOCSPStrict;
 224   const mozilla::TimeDuration mOCSPTimeoutSoft;
 225   const mozilla::TimeDuration mOCSPTimeoutHard;
 226   const uint32_t mCertShortLifetimeInDays;
 227   const NetscapeStepUpPolicy mNetscapeStepUpPolicy;
 228   const CertificateTransparencyMode mCTMode;
 229   const CRLiteMode mCRLiteMode;
 230
 231  private:
 232   OCSPCache mOCSPCache;
 233   // We keep a copy of the bytes of each third party root to own.
 234   nsTArray<EnterpriseCert> mThirdPartyCerts;
 235   // This is a reusable, precomputed list of Inputs corresponding to each root
 236   // in mThirdPartyCerts that wasn't too long to make an Input out of.
 237   nsTArray<mozilla::pkix::Input> mThirdPartyRootInputs;
 238   // Similarly, but with intermediates.
 239   nsTArray<mozilla::pkix::Input> mThirdPartyIntermediateInputs;
 240
 241   // We only have a forward declarations of these classes (see above)
 242   // so we must allocate dynamically.
 243   UniquePtr<mozilla::ct::MultiLogCTVerifier> mCTVerifier;
 244   UniquePtr<mozilla::ct::CTDiversityPolicy> mCTDiversityPolicy;
 245
 246   void LoadKnownCTLogs();
 247   mozilla::pkix::Result VerifyCertificateTransparencyPolicy(
 248       NSSCertDBTrustDomain& trustDomain,
 249       const nsTArray<nsTArray<uint8_t>>& builtChain,
 250       mozilla::pkix::Input sctsFromTLS, mozilla::pkix::Time time,
 251       /*optional out*/ CertificateTransparencyInfo* ctInfo);
 252 };
 253
 254 mozilla::pkix::Result IsCertBuiltInRoot(pkix::Input certInput, bool& result);
 255 mozilla::pkix::Result CertListContainsExpectedKeys(const CERTCertList* certList,
 256                                                    const char* hostname,
 257                                                    mozilla::pkix::Time time);
 258
 259 }  // namespace psm
 260 }  // namespace mozilla
 261
 262 #endif  // CertVerifier_h