trust/headers/SecTrustSettingsPriv.h

   1 /*
   2  * Copyright (c) 2002-2020 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 #ifndef _SECURITY_SECTRUSTSETTINGSPRIV_H_
  25 #define _SECURITY_SECTRUSTSETTINGSPRIV_H_
  26
  27 #include <Security/SecBase.h>
  28
  29 #include <CoreFoundation/CoreFoundation.h>
  30 #include <Security/SecPolicy.h>
  31 #include <Security/SecCertificate.h>
  32 #include <Security/SecTrustSettings.h>
  33 #if SEC_OS_OSX
  34 #include <Security/cssmtype.h>
  35 #endif
  36
  37 __BEGIN_DECLS
  38
  39 /*
  40  * Private Keys in the Usage Contraints dictionary.
  41  * kSecTrustSettingsPolicyName      Specifies a cert verification policy, e.g.,
  42  *                                  sslServer, eapClient, etc, using policy names.
  43  *                                  This entry can be used to restrict the policy where
  44  *                                  the same Policy Constant is used for multiple policyNames.
  45  * kSectrustSettingsPolicyOptions   Specifies a dictionary of policy options (from
  46  *                                  SecPolicyInternal.h). This entry can be used to require
  47  *                                  a particular SecPolicyCheck whenever this certificate is
  48  *                                  encountered during trust evaluation.
  49  */
  50 #define kSecTrustSettingsPolicyName               CFSTR("kSecTrustSettingsPolicyName")
  51 #define kSecTrustSettingsPolicyOptions            CFSTR("kSecTrustSettingsPolicyOptions")
  52
  53 extern const CFStringRef kSecCTExceptionsCAsKey;
  54 extern const CFStringRef kSecCTExceptionsDomainsKey;
  55 extern const CFStringRef kSecCTExceptionsHashAlgorithmKey;
  56 extern const CFStringRef kSecCTExceptionsSPKIHashKey;
  57
  58 /*
  59  @function SecTrustStoreSetCTExceptions
  60  @abstract Set the certificate transparency enforcement exceptions
  61  @param applicationIdentifier Identifier for the caller. If null, the application-identifier will be read from the caller's entitlements.
  62  @param exceptions Dictionary of exceptions to set for this application. These exceptions replace existing exceptions for the keys in the dictionary. Exceptions for omitted keys are not affected. Null removes all exceptions for this application. See the discussion sections below for a complete overview of options.
  63  @param error On failure, describes the cause of the failure; otherwise, null.
  64  @result boolean indicating success of the operation. If false, error will be filled in with a description of the error.
  65  @discussions An exceptions dictionary has two optional keys:
  66  kSecCTExceptionsDomainsKey takes an array of strings. These strings are the domains that are excluded from enforcing CT. A leading "." is supported to signify subdomains. Wildcard domains are not supported.
  67  kSecCTExceptionsCAsKey takes an array of dictionaries. Each dictionary has two required keys:
  68     kSecCTExceptionsHashAlgorithmKey takes a string indicating the hash algorithm. Currently only "sha256" is supported.
  69     kSecCTExceptionsSPKIHashKey takes a data containing hash of a certificate's SubjectPublicKeyInfo.
  70  */
  71 bool SecTrustStoreSetCTExceptions(CFStringRef applicationIdentifier, CFDictionaryRef exceptions, CFErrorRef *error);
  72
  73 /*
  74  @function SecTrustStoreCopyCTExceptions
  75  @abstract Return the certificate transparency enforcement exceptions
  76  @param applicationIdentifier Identifier for the caller's exceptions to fetch. If null, all set exceptions will be returned (regardless of which caller set them).
  77  @param error On failure, describes the cause of the failure; otherwise, null.
  78  @result The dictionary of currently set exceptions. Null if none exist or upon failure.
  79  @discussion The returned exceptions dictionary has the same options as input exceptions. See the discussion of SecTrustStoreSetCTExceptions.
  80  */
  81 CF_RETURNS_RETAINED CFDictionaryRef SecTrustStoreCopyCTExceptions(CFStringRef applicationIdentifier, CFErrorRef *error);
  82
  83
  84 extern const CFStringRef kSecCARevocationAdditionsKey;
  85 extern const CFStringRef kSecCARevocationHashAlgorithmKey;
  86 extern const CFStringRef kSecCARevocationSPKIHashKey;
  87
  88 /*
  89  @function SecTrustStoreSetCARevocationAdditions
  90  @abstract Set a list of certificate authorities (specified by subject public key info hash) for which revocation should be explicitly checked.
  91  @param applicationIdentifier Identifier for the caller. If null, the application-identifier will be read from the caller's entitlements.
  92  @param additions Dictionary of SPKI hashes for which revocation should be explicitly checked. Existing entries for the keys in the dictionary will be replaced. Null removes all CA revocation additions for this application. See the discussion sections below for a complete overview of options.
  93  @param error On failure, describes the cause of the failure; otherwise, null.
  94  @result boolean indicating success of the operation. If false, error will be filled in with a description of the error.
  95  @discussions An additions dictionary currently has one defined key:
  96  kSecCARevocationAdditionsKey takes an array of dictionaries. Each dictionary has two required keys:
  97     kSecCARevocationHashAlgorithmKey takes a string indicating the hash algorithm. Currently only "sha256" is supported.
  98     kSecCARevocationSPKIHashKey takes a data containing hash of a certificate's SubjectPublicKeyInfo.
  99  */
 100 bool SecTrustStoreSetCARevocationAdditions(CFStringRef applicationIdentifier, CFDictionaryRef additions, CFErrorRef *error);
 101
 102 /*
 103  @function SecTrustStoreCopyCARevocationAdditions
 104  @abstract Return the certificate authority SPKI hashes for which revocation should be explicitly checked.
 105  @param applicationIdentifier Identifier for the caller's additions to fetch. If null, all set exceptions will be returned (regardless of which caller set them).
 106  @param error On failure, describes cause of the failure; otherwise, null.
 107  @result The dictionary of currently set CA revocation additions. Null if none exist or upon failure.
 108  @discussion The returned additions dictionary has the same options as input additions. See the discussion of SecTrustStoreSetCARevocationAdditions.
 109  */
 110 CF_RETURNS_RETAINED CFDictionaryRef SecTrustStoreCopyCARevocationAdditions(CFStringRef applicationIdentifier, CFErrorRef *error);
 111
 112 #if SEC_OS_OSX
 113
 114 /*
 115  * Fundamental routine used by TP to ascertain status of one cert.
 116  *
 117  * Returns true in *foundMatchingEntry if a trust setting matching
 118  * specific constraints was found for the cert. Returns true in
 119  * *foundAnyEntry if any entry was found for the cert, even if it
 120  * did not match the specified constraints. The TP uses this to
 121  * optimize for the case where a cert is being evaluated for
 122  * one type of usage, and then later for another type. If
 123  * foundAnyEntry is false, the second evaluation need not occur.
 124  *
 125  * Returns the domain in which a setting was found in *foundDomain.
 126  *
 127  * Allowed errors applying to the specified cert evaluation
 128  * are returned in a mallocd array in *allowedErrors and must
 129  * be freed by caller.
 130  */
 131 OSStatus SecTrustSettingsEvaluateCert(
 132      CFStringRef                         certHashStr,
 133      /* parameters describing the current cert evalaution */
 134      const CSSM_OID                      *policyOID,
 135      const char                          *policyString,        /* optional */
 136      uint32                              policyStringLen,
 137      SecTrustSettingsKeyUsage            keyUsage,             /* optional */
 138      bool                                isRootCert,           /* for checking default setting */
 139      /* RETURNED values */
 140      SecTrustSettingsDomain              *foundDomain,
 141      CSSM_RETURN                         **allowedErrors,      /* mallocd and RETURNED */
 142      uint32                              *numAllowedErrors,    /* RETURNED */
 143      SecTrustSettingsResult              *resultType,          /* RETURNED */
 144      bool                                *foundMatchingEntry,  /* RETURNED */
 145      bool                                *foundAnyEntry)       /* RETURNED */
 146 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 147
 148 /*
 149  * Obtain trusted certs which match specified usage.
 150  * Only certs with a SecTrustSettingsResult of
 151  * kSecTrustSettingsResultTrustRoot or
 152  * or kSecTrustSettingsResultTrustAsRoot will be returned.
 153  *
 154  * To be used by SecureTransport for its (hopefully soon-to-be-
 155  * deprecated) SSLSetTrustedRoots() call; I hope nothing else has
 156  * to use this...
 157  *
 158  * Caller must CFRelease the returned CFArrayRef.
 159  */
 160 OSStatus SecTrustSettingsCopyQualifiedCerts(
 161      const CSSM_OID                      *policyOID,
 162      const char                          *policyString,        /* optional */
 163      uint32                              policyStringLen,
 164      SecTrustSettingsKeyUsage            keyUsage,             /* optional */
 165      CFArrayRef                          *certArray)           /* RETURNED */
 166 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 167
 168 /*
 169  * Obtain unrestricted root certificates from the specified domain(s).
 170  * Only returns root certificates with no usage constraints.
 171  * Caller must CFRelease the returned CFArrayRef.
 172  */
 173 OSStatus SecTrustSettingsCopyUnrestrictedRoots(
 174      Boolean                         userDomain,
 175      Boolean                         adminDomain,
 176      Boolean                         systemDomain,
 177      CFArrayRef                      *certArray);          /* RETURNED */
 178
 179 /*
 180  * Obtain a string representing a cert's SHA1 digest. This string is
 181  * the key used to look up per-cert trust settings in a TrustSettings record.
 182  */
 183 CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromCert(
 184      SecCertificateRef certRef);
 185
 186 CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromData(
 187      const void *cert,
 188      size_t certLen);
 189
 190 /*
 191  * Add a cert's TrustSettings to a non-persistent TrustSettings record.
 192  * Primarily intended for use in creating a system TrustSettings record
 193  * (which is itself immutable via this module).
 194  *
 195  * The settingsIn argument is an external representation of a TrustSettings
 196  * record, obtained from this function or from
 197  * SecTrustSettingsCreateExternalRepresentation().
 198  * If settingsIn is NULL, a new (empty) TrustSettings will be created.
 199  *
 200  * The certRef and trustSettingsDictOrArray arguments are as in
 201  * SecTrustSettingsSetTrustSettings(). May be NULL, when e.g. creating
 202  * a new and empty TrustSettings record.
 203  *
 204  * The external representation is written to the settingOut argument,
 205  * which must eventually be CFReleased by the caller.
 206  */
 207 OSStatus SecTrustSettingsSetTrustSettingsExternal(
 208      CFDataRef               settingsIn,                   /* optional */
 209      SecCertificateRef       certRef,                      /* optional */
 210      CFTypeRef               trustSettingsDictOrArray,     /* optional */
 211      CFDataRef               *settingsOut);                /* RETURNED */
 212
 213 /*
 214  * Add user trust settings for a SSL certificate and a given hostname.
 215  * This is a wrapper around the SecTrustSettingsSetTrustSettings API
 216  * and should be functionally equivalent to "Always trust" in the UI.
 217  *
 218  * When this function is called, the user will be prompted to authorize
 219  * the trust settings change. After they successfully authenticate, or
 220  * cancel the dialog, the result block will be called to indicate the
 221  * current trust status. If an error occurred (such as errUserCanceled),
 222  * the error reference provided to the block will be non-NULL.
 223  */
 224 void SecTrustSettingsSetTrustedCertificateForSSLHost(
 225     SecCertificateRef certificate,
 226     CFStringRef hostname,
 227     void (^result)(SecTrustSettingsResult trustResult, CFErrorRef error))
 228     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_NA);
 229 #endif // SEC_OS_OSX
 230
 231 #if SEC_OS_OSX_INCLUDES
 232 /*
 233  * Purge the cache of User and Admin Certs
 234  */
 235 void SecTrustSettingsPurgeUserAdminCertsCache(void);
 236
 237 /*
 238  * A wrapper around SecTrustSettingsCopyCertificates that combines user and admin
 239  * domain outputs.
 240  */
 241 OSStatus SecTrustSettingsCopyCertificatesForUserAdminDomains(
 242     CFArrayRef CF_RETURNS_RETAINED *certArray);
 243
 244 /* Just like the API version (SecTrustSettingsCopyTrustSettings) but
 245  * uses the cached version of trust settings to avoid disk reads. */
 246 OSStatus SecTrustSettingsCopyTrustSettings_Cached(
 247     SecCertificateRef certRef,
 248     SecTrustSettingsDomain domain,
 249     CFArrayRef CF_RETURNS_RETAINED *trustSettings);
 250
 251 /* Purge the trust settings cache (used by the above) */
 252 void SecTrustSettingsPurgeCache(void);
 253
 254 /* Determines if the given cert has any trust settings in the admin or user domains */
 255 bool SecTrustSettingsUserAdminDomainsContain(SecCertificateRef certRef);
 256 #endif /* SEC_OS_OSX_INCLUDES */
 257
 258 __END_DECLS
 259
 260 #endif // _SECURITY_SECTRUSTSETTINGSPRIV_H_