trust/headers/SecTrustSettingsPriv.h

   1 /*
   2  * Copyright (c) 2002-2017 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 callers 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 Upon failure describes cause of the failure.
  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. Currenlty only "sha256" is supported.
  69     kSecCTExceptionsSPKIHashKey takes a data containing hash of a certificates 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 Upon failure describes cause of the failure.
  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 #if SEC_OS_OSX
  84
  85 /*
  86  * Fundamental routine used by TP to ascertain status of one cert.
  87  *
  88  * Returns true in *foundMatchingEntry if a trust setting matching
  89  * specific constraints was found for the cert. Returns true in
  90  * *foundAnyEntry if any entry was found for the cert, even if it
  91  * did not match the specified constraints. The TP uses this to
  92  * optimize for the case where a cert is being evaluated for
  93  * one type of usage, and then later for another type. If
  94  * foundAnyEntry is false, the second evaluation need not occur.
  95  *
  96  * Returns the domain in which a setting was found in *foundDomain.
  97  *
  98  * Allowed errors applying to the specified cert evaluation
  99  * are returned in a mallocd array in *allowedErrors and must
 100  * be freed by caller.
 101  */
 102 OSStatus SecTrustSettingsEvaluateCert(
 103      CFStringRef                         certHashStr,
 104      /* parameters describing the current cert evalaution */
 105      const CSSM_OID                      *policyOID,
 106      const char                          *policyString,        /* optional */
 107      uint32                              policyStringLen,
 108      SecTrustSettingsKeyUsage            keyUsage,             /* optional */
 109      bool                                isRootCert,           /* for checking default setting */
 110      /* RETURNED values */
 111      SecTrustSettingsDomain              *foundDomain,
 112      CSSM_RETURN                         **allowedErrors,      /* mallocd and RETURNED */
 113      uint32                              *numAllowedErrors,    /* RETURNED */
 114      SecTrustSettingsResult              *resultType,          /* RETURNED */
 115      bool                                *foundMatchingEntry,  /* RETURNED */
 116      bool                                *foundAnyEntry)       /* RETURNED */
 117 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 118
 119 /*
 120  * Obtain trusted certs which match specified usage.
 121  * Only certs with a SecTrustSettingsResult of
 122  * kSecTrustSettingsResultTrustRoot or
 123  * or kSecTrustSettingsResultTrustAsRoot will be returned.
 124  *
 125  * To be used by SecureTransport for its (hopefully soon-to-be-
 126  * deprecated) SSLSetTrustedRoots() call; I hope nothing else has
 127  * to use this...
 128  *
 129  * Caller must CFRelease the returned CFArrayRef.
 130  */
 131 OSStatus SecTrustSettingsCopyQualifiedCerts(
 132      const CSSM_OID                      *policyOID,
 133      const char                          *policyString,        /* optional */
 134      uint32                              policyStringLen,
 135      SecTrustSettingsKeyUsage            keyUsage,             /* optional */
 136      CFArrayRef                          *certArray)           /* RETURNED */
 137 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 138
 139 /*
 140  * Obtain unrestricted root certificates from the specified domain(s).
 141  * Only returns root certificates with no usage constraints.
 142  * Caller must CFRelease the returned CFArrayRef.
 143  */
 144 OSStatus SecTrustSettingsCopyUnrestrictedRoots(
 145      Boolean                         userDomain,
 146      Boolean                         adminDomain,
 147      Boolean                         systemDomain,
 148      CFArrayRef                      *certArray);          /* RETURNED */
 149
 150 /*
 151  * Obtain a string representing a cert's SHA1 digest. This string is
 152  * the key used to look up per-cert trust settings in a TrustSettings record.
 153  */
 154 CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromCert(
 155      SecCertificateRef certRef);
 156
 157 CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromData(
 158      const void *cert,
 159      size_t certLen);
 160
 161 /*
 162  * Add a cert's TrustSettings to a non-persistent TrustSettings record.
 163  * Primarily intended for use in creating a system TrustSettings record
 164  * (which is itself immutable via this module).
 165  *
 166  * The settingsIn argument is an external representation of a TrustSettings
 167  * record, obtained from this function or from
 168  * SecTrustSettingsCreateExternalRepresentation().
 169  * If settingsIn is NULL, a new (empty) TrustSettings will be created.
 170  *
 171  * The certRef and trustSettingsDictOrArray arguments are as in
 172  * SecTrustSettingsSetTrustSettings(). May be NULL, when e.g. creating
 173  * a new and empty TrustSettings record.
 174  *
 175  * The external representation is written to the settingOut argument,
 176  * which must eventually be CFReleased by the caller.
 177  */
 178 OSStatus SecTrustSettingsSetTrustSettingsExternal(
 179      CFDataRef               settingsIn,                   /* optional */
 180      SecCertificateRef       certRef,                      /* optional */
 181      CFTypeRef               trustSettingsDictOrArray,     /* optional */
 182      CFDataRef               *settingsOut);                /* RETURNED */
 183
 184 /*
 185  * Add user trust settings for a SSL certificate and a given hostname.
 186  * This is a wrapper around the SecTrustSettingsSetTrustSettings API
 187  * and should be functionally equivalent to "Always trust" in the UI.
 188  *
 189  * When this function is called, the user will be prompted to authorize
 190  * the trust settings change. After they successfully authenticate, or
 191  * cancel the dialog, the result block will be called to indicate the
 192  * current trust status. If an error occurred (such as errUserCanceled),
 193  * the error reference provided to the block will be non-NULL.
 194  */
 195 void SecTrustSettingsSetTrustedCertificateForSSLHost(
 196     SecCertificateRef certificate,
 197     CFStringRef hostname,
 198     void (^result)(SecTrustSettingsResult trustResult, CFErrorRef error))
 199     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_NA);
 200 #endif // SEC_OS_OSX
 201
 202 #if SEC_OS_OSX_INCLUDES
 203 /*
 204  * Purge the cache of User and Admin Certs
 205  */
 206 void SecTrustSettingsPurgeUserAdminCertsCache(void);
 207
 208 /*
 209  * A wrapper around SecTrustSettingsCopyCertificates that combines user and admin
 210  * domain outputs.
 211  */
 212 OSStatus SecTrustSettingsCopyCertificatesForUserAdminDomains(
 213     CFArrayRef CF_RETURNS_RETAINED *certArray);
 214 #endif /* SEC_OS_OSX_INCLUDES */
 215
 216 __END_DECLS
 217
 218 #endif // _SECURITY_SECTRUSTSETTINGSPRIV_H_