OSX/include/security_keychain/TrustSettings.h

   1 /*
   2  * Copyright (c) 2005,2011,2014 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*
  25  * TrustSettings.h - class to manage trusted certs.
  26  */
  27
  28 #ifndef _TRUST_SETTINGS_H_
  29 #define _TRUST_SETTINGS_H_
  30
  31 #include "SecTrust.h"
  32 #include <security_keychain/StorageManager.h>
  33 #include <security_keychain/SecTrustSettings.h>
  34
  35 /*
  36  * Clarification of the bool arguments to our main constructor.
  37  */
  38 #define CREATE_YES      true
  39 #define CREATE_NO       false
  40 #define TRIM_YES        true
  41 #define TRIM_NO         false
  42
  43 namespace Security
  44 {
  45
  46 namespace KeychainCore
  47 {
  48
  49 /*
  50  * Additional values for the SecTrustSettingsDomain enum.
  51  */
  52 enum {
  53         /*
  54          * This indicates a TrustSettings that exists only in memory; it
  55          * can't be written to disk.
  56          */
  57         kSecTrustSettingsDomainMemory = 100
  58 };
  59
  60 class TrustSettings
  61 {
  62 private:
  63         TrustSettings(SecTrustSettingsDomain domain);
  64
  65 public:
  66
  67         /*
  68          * Normal constructor, from disk.
  69          * If create is true, the absence of an on-disk TrustSettings file
  70          * results in the creation of a new empty TrustSettings. If create is
  71          * false and no on-disk TrustSettings exists, errSecItemNotFound is
  72          * thrown.
  73          * If trim is true, the components of the on-disk TrustSettings not
  74          * needed for cert evaluation are discarded. This is for TrustSettings
  75          * that will be cached in memory long-term.
  76          */
  77         static OSStatus CreateTrustSettings(
  78                 SecTrustSettingsDomain                          domain,
  79                 bool                                                            create,
  80                 bool                                                            trim,
  81                 TrustSettings*&                                         ts);
  82
  83         /*
  84          * Create from external data, obtained by createExternal().
  85          * If externalData is NULL, we'll create an empty mTrustDict.
  86          */
  87         static OSStatus CreateTrustSettings(
  88                 SecTrustSettingsDomain                          domain,
  89                 CFDataRef                                                       externalData,
  90                 TrustSettings*&                                         ts);
  91
  92         ~TrustSettings();
  93
  94         /*
  95          * Evaluate specified cert. Returns true if we found a matching
  96          * record for the cert.
  97          */
  98         bool evaluateCert(
  99                 CFStringRef                             certHashStr,
 100                 const CSSM_OID                  *policyOID,                     /* optional */
 101                 const char                              *policyString,          /* optional */
 102                 SecTrustSettingsKeyUsage keyUsage,                      /* optional */
 103                 bool                                    isRootCert,                     /* for checking default setting */
 104                 CSSM_RETURN                             **allowedErrors,        /* mallocd and RETURNED */
 105                 uint32                                  *numAllowedErrors,      /* RETURNED */
 106                 SecTrustSettingsResult  *resultType,            /* RETURNED */
 107                 bool                                    *foundAnyEntry);        /* RETURNED - there is SOME entry for
 108                                                                                                          *   this cert */
 109
 110         /*
 111          * Only certs with a SecTrustSettingsResult of kSecTrustSettingsResultTrustRoot
 112          * or kSecTrustSettingsResultTrustAsRoot will be returned.
 113          */
 114         void findQualifiedCerts(
 115                 StorageManager::KeychainList    &keychains,
 116                 /*
 117                  * If findAll is true, all certs are returned and the subsequent
 118                  * qualifiers are ignored
 119                  */
 120                 bool                                                    findAll,
 121                 /* if true, only return root (self-signed) certs */
 122                 bool                                                    onlyRoots,
 123                 const CSSM_OID                                  *policyOID,             /* optional */
 124                 const char                                              *policyString,  /* optional */
 125                 SecTrustSettingsKeyUsage                keyUsage,               /* optional */
 126                 CFMutableArrayRef                               certArray);             /* certs appended here */
 127
 128         /*
 129          * Find all certs in specified keychain list which have entries in this trust record.
 130          * Certs already in the array are not added.
 131          */
 132         void findCerts(
 133                 StorageManager::KeychainList    &keychains,
 134                 CFMutableArrayRef                               certArray);
 135
 136         /*
 137          * Obtain trust settings for the specified cert. Returned settings array
 138          * is in the public API form; caller must release. Returns NULL
 139          * (does not throw) if the cert is not present in this TrustRecord.
 140          * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting.
 141          */
 142         CFArrayRef copyTrustSettings(
 143                 SecCertificateRef       certRef);
 144
 145         /*
 146          * Obtain the mod date for the specified cert's trust settings.
 147      * Returns NULL (does not throw) if the cert is not present in this
 148          * TrustRecord.
 149          * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting.
 150          */
 151         CFDateRef copyModDate(
 152                 SecCertificateRef       certRef);
 153
 154         /*
 155          * Modify cert's trust settings, or add a new cert to the record.
 156          * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting.
 157          */
 158         void setTrustSettings(
 159                 SecCertificateRef       certRef,
 160                 CFTypeRef                       trustSettingsDictOrArray);
 161
 162         /*
 163          * Delete a certificate's trust settings.
 164          * Throws errSecItemNotFound if there currently are no settings.
 165          * The certRef argument can be kSecTrustSettingsDefaultRootCertSetting.
 166          */
 167         void deleteTrustSettings(
 168                 SecCertificateRef       certRef);
 169
 170         /*
 171          * Flush property list data out to disk if dirty.
 172          */
 173         void flushToDisk();
 174
 175         /*
 176          * Obtain external representation of TrustSettings data.
 177          */
 178         CFDataRef createExternal();
 179
 180 private:
 181         /* common code to init mPropList from raw data */
 182         void initFromData(
 183                 CFDataRef                       trustSettingsData);
 184
 185         /*
 186          * Find a given cert's entry in mTrustDict.
 187          * Returned dictionary is not refcounted.
 188          */
 189         CFDictionaryRef findDictionaryForCert(
 190                 SecCertificateRef       certRef);
 191
 192         /*
 193          * Find entry in mTrustDict given cert hash string.
 194          */
 195         CFDictionaryRef findDictionaryForCertHash(
 196                 CFStringRef             certHashStr);
 197
 198         /*
 199          * Validate incoming API-style trust settings, which may be NULL, a
 200          * dictionary, or an array of dictionaries. We return a deep-copied,
 201          * refcounted CFArray, in internal format, in any case as long as the
 202          * incoming parameter is good.
 203          */
 204         CFArrayRef validateApiTrustSettings(
 205                 CFTypeRef trustSettingsDictOrArray,
 206                 Boolean isSelfSigned);
 207
 208         /*
 209          * Validate an usage constraint array from disk as part of our mPropDict
 210          * array. Returns true if OK, else returns false.
 211          */
 212         bool validateTrustSettingsArray(
 213                 CFArrayRef trustSettings);
 214
 215         /*
 216          * Obtain issuer and serial number for specified cert, both
 217          * returned as CFDataRefs owned by caller.
 218          */
 219         void copyIssuerAndSerial(
 220                 SecCertificateRef       cert,
 221                 CFDataRef                       *issuer,                /* optional, RETURNED */
 222                 CFDataRef                       *serial);               /* RETURNED */
 223
 224         /*
 225          * Validate mPropDict after it's read from disk. Allows subsequent use of
 226          * mPropDict and mTrustDict to proceed with relative impunity.
 227          * If trim is true, we remove fields in the per-cert dictionaries which
 228          * are not needed for cert evaluation. We also release the top-level
 229          * mPropList, which serves as a "this is trimmed" indicator if NULL.
 230          */
 231         void validatePropList(bool trim);
 232
 233         /* fatal error abort */
 234         void abort(
 235                 const char                      *why,
 236                 OSStatus                        err);
 237
 238         /* the overall parsed TrustSettings - may be NULL if this is trimmed */
 239         CFMutableDictionaryRef                  mPropList;
 240
 241         /* and the main thing we work with, the dictionary of per-cert trust settings */
 242         CFMutableDictionaryRef                  mTrustDict;
 243
 244         /* version number of mPropDict */
 245         SInt32                                                  mDictVersion;
 246
 247         SecTrustSettingsDomain                  mDomain;
 248         bool                                                    mDirty;         /* we've changed mPropDict since creation */
 249 };
 250
 251 } /* end namespace KeychainCore */
 252
 253 } /* end namespace Security */
 254
 255 #endif  /* _TRUST_SETTINGS_H_ */
 256