net/cert/x509_util_mac.h

   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_X509_UTIL_MAC_H_
   6 #define NET_CERT_X509_UTIL_MAC_H_
   7
   8 #include <CoreFoundation/CFArray.h>
   9 #include <Security/Security.h>
  10
  11 #include <string>
  12
  13 #include "base/basictypes.h"
  14 #include "net/base/net_export.h"
  15
  16 namespace net {
  17
  18 namespace x509_util {
  19
  20 // Creates a security policy for certificates used as client certificates
  21 // in SSL.
  22 // If a policy is successfully created, it will be stored in
  23 // |*policy| and ownership transferred to the caller.
  24 OSStatus NET_EXPORT CreateSSLClientPolicy(SecPolicyRef* policy);
  25
  26 // Create an SSL server policy. While certificate name validation will be
  27 // performed by SecTrustEvaluate(), it has the following limitations:
  28 // - Doesn't support IP addresses in dotted-quad literals (127.0.0.1)
  29 // - Doesn't support IPv6 addresses
  30 // - Doesn't support the iPAddress subjectAltName
  31 // Providing the hostname is necessary in order to locate certain user or
  32 // system trust preferences, such as those created by Safari. Preferences
  33 // created by Keychain Access do not share this requirement.
  34 // On success, stores the resultant policy in |*policy| and returns noErr.
  35 OSStatus NET_EXPORT CreateSSLServerPolicy(const std::string& hostname,
  36                                           SecPolicyRef* policy);
  37
  38 // Creates a security policy for basic X.509 validation. If the policy is
  39 // successfully created, it will be stored in |*policy| and ownership
  40 // transferred to the caller.
  41 OSStatus NET_EXPORT CreateBasicX509Policy(SecPolicyRef* policy);
  42
  43 // Creates security policies to control revocation checking (OCSP and CRL).
  44 // If |enable_revocation_checking| is true, revocation checking will be
  45 // explicitly enabled.
  46 // If |enable_revocation_checking| is false, but |enable_ev_checking| is
  47 // true, then the system policies for EV checking (which include checking
  48 // for an online OCSP response) will be permitted. However, if the OS
  49 // does not believe the certificate is EV, no revocation checking will be
  50 // performed.
  51 // If both are false, then the policies returned will be explicitly
  52 // prohibited from accessing the network or the local cache, regardless of
  53 // system settings.
  54 // If the policies are successfully created, they will be appended to
  55 // |policies|.
  56 OSStatus NET_EXPORT CreateRevocationPolicies(bool enable_revocation_checking,
  57                                              bool enable_ev_checking,
  58                                              CFMutableArrayRef policies);
  59
  60 // Wrapper for a CSSM_DATA_PTR that was obtained via one of the CSSM field
  61 // accessors (such as CSSM_CL_CertGet[First/Next]Value or
  62 // CSSM_CL_CertGet[First/Next]CachedValue).
  63 class CSSMFieldValue {
  64  public:
  65   CSSMFieldValue();
  66   CSSMFieldValue(CSSM_CL_HANDLE cl_handle,
  67                  const CSSM_OID* oid,
  68                  CSSM_DATA_PTR field);
  69   ~CSSMFieldValue();
  70
  71   CSSM_OID_PTR oid() const { return oid_; }
  72   CSSM_DATA_PTR field() const { return field_; }
  73
  74   // Returns the field as if it was an arbitrary type - most commonly, by
  75   // interpreting the field as a specific CSSM/CDSA parsed type, such as
  76   // CSSM_X509_SUBJECT_PUBLIC_KEY_INFO or CSSM_X509_ALGORITHM_IDENTIFIER.
  77   // An added check is applied to ensure that the current field is large
  78   // enough to actually contain the requested type.
  79   template <typename T> const T* GetAs() const {
  80     if (!field_ || field_->Length < sizeof(T))
  81       return NULL;
  82     return reinterpret_cast<const T*>(field_->Data);
  83   }
  84
  85   void Reset(CSSM_CL_HANDLE cl_handle,
  86              CSSM_OID_PTR oid,
  87              CSSM_DATA_PTR field);
  88
  89  private:
  90   CSSM_CL_HANDLE cl_handle_;
  91   CSSM_OID_PTR oid_;
  92   CSSM_DATA_PTR field_;
  93
  94   DISALLOW_COPY_AND_ASSIGN(CSSMFieldValue);
  95 };
  96
  97 // CSSMCachedCertificate is a container class that is used to wrap the
  98 // CSSM_CL_CertCache APIs and provide safe and efficient access to
  99 // certificate fields in their CSSM form.
 100 //
 101 // To provide efficient access to certificate/CRL fields, CSSM provides an
 102 // API/SPI to "cache" a certificate/CRL. The exact meaning of a cached
 103 // certificate is not defined by CSSM, but is documented to generally be some
 104 // intermediate or parsed form of the certificate. In the case of Apple's
 105 // CSSM CL implementation, the intermediate form is the parsed certificate
 106 // stored in an internal format (which happens to be NSS). By caching the
 107 // certificate, callers that wish to access multiple fields (such as subject,
 108 // issuer, and validity dates) do not need to repeatedly parse the entire
 109 // certificate, nor are they forced to convert all fields from their NSS types
 110 // to their CSSM equivalents. This latter point is especially helpful when
 111 // running on OS X 10.5, as it will fail to convert some fields that reference
 112 // unsupported algorithms, such as ECC.
 113 class CSSMCachedCertificate {
 114  public:
 115   CSSMCachedCertificate();
 116   ~CSSMCachedCertificate();
 117
 118   // Initializes the CSSMCachedCertificate by caching the specified
 119   // |os_cert_handle|. On success, returns noErr.
 120   // Note: Once initialized, the cached certificate should only be accessed
 121   // from a single thread.
 122   OSStatus Init(SecCertificateRef os_cert_handle);
 123
 124   // Fetches the first value for the field associated with |field_oid|.
 125   // If |field_oid| is a valid OID and is present in the current certificate,
 126   // returns CSSM_OK and stores the first value in |field|. If additional
 127   // values are associated with |field_oid|, they are ignored.
 128   OSStatus GetField(const CSSM_OID* field_oid, CSSMFieldValue* field) const;
 129
 130  private:
 131   CSSM_CL_HANDLE cl_handle_;
 132   CSSM_HANDLE cached_cert_handle_;
 133 };
 134
 135 }  // namespace x509_util
 136
 137 }  // namespace net
 138
 139 #endif  // NET_CERT_X509_UTIL_MAC_H_