trust/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
 118 /*
 119  * Obtain trusted certs which match specified usage.
 120  * Only certs with a SecTrustSettingsResult of
 121  * kSecTrustSettingsResultTrustRoot or
 122  * or kSecTrustSettingsResultTrustAsRoot will be returned.
 123  *
 124  * To be used by SecureTransport for its (hopefully soon-to-be-
 125  * deprecated) SSLSetTrustedRoots() call; I hope nothing else has
 126  * to use this...
 127  *
 128  * Caller must CFRelease the returned CFArrayRef.
 129  */
 130 OSStatus SecTrustSettingsCopyQualifiedCerts(
 131      const CSSM_OID                      *policyOID,
 132      const char                          *policyString,        /* optional */
 133      uint32                              policyStringLen,
 134      SecTrustSettingsKeyUsage            keyUsage,             /* optional */
 135      CFArrayRef                          *certArray);          /* RETURNED */
 136
 137 /*
 138  * Obtain unrestricted root certificates from the specified domain(s).
 139  * Only returns root certificates with no usage constraints.
 140  * Caller must CFRelease the returned CFArrayRef.
 141  */
 142 OSStatus SecTrustSettingsCopyUnrestrictedRoots(
 143      Boolean                         userDomain,
 144      Boolean                         adminDomain,
 145      Boolean                         systemDomain,
 146      CFArrayRef                      *certArray);          /* RETURNED */
 147
 148 /*
 149  * Obtain a string representing a cert's SHA1 digest. This string is
 150  * the key used to look up per-cert trust settings in a TrustSettings record.
 151  */
 152 CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromCert(
 153      SecCertificateRef certRef);
 154
 155 CFStringRef CF_RETURNS_RETAINED SecTrustSettingsCertHashStrFromData(
 156      const void *cert,
 157      size_t certLen);
 158
 159 /*
 160  * Add a cert's TrustSettings to a non-persistent TrustSettings record.
 161  * Primarily intended for use in creating a system TrustSettings record
 162  * (which is itself immutable via this module).
 163  *
 164  * The settingsIn argument is an external representation of a TrustSettings
 165  * record, obtained from this function or from
 166  * SecTrustSettingsCreateExternalRepresentation().
 167  * If settingsIn is NULL, a new (empty) TrustSettings will be created.
 168  *
 169  * The certRef and trustSettingsDictOrArray arguments are as in
 170  * SecTrustSettingsSetTrustSettings(). May be NULL, when e.g. creating
 171  * a new and empty TrustSettings record.
 172  *
 173  * The external representation is written to the settingOut argument,
 174  * which must eventually be CFReleased by the caller.
 175  */
 176 OSStatus SecTrustSettingsSetTrustSettingsExternal(
 177      CFDataRef               settingsIn,                   /* optional */
 178      SecCertificateRef       certRef,                      /* optional */
 179      CFTypeRef               trustSettingsDictOrArray,     /* optional */
 180      CFDataRef               *settingsOut);                /* RETURNED */
 181
 182 /*
 183  * Add user trust settings for a SSL certificate and a given hostname.
 184  * This is a wrapper around the SecTrustSettingsSetTrustSettings API
 185  * and should be functionally equivalent to "Always trust" in the UI.
 186  *
 187  * When this function is called, the user will be prompted to authorize
 188  * the trust settings change. After they successfully authenticate, or
 189  * cancel the dialog, the result block will be called to indicate the
 190  * current trust status. If an error occurred (such as errUserCanceled),
 191  * the error reference provided to the block will be non-NULL.
 192  */
 193 void SecTrustSettingsSetTrustedCertificateForSSLHost(
 194     SecCertificateRef certificate,
 195     CFStringRef hostname,
 196     void (^result)(SecTrustSettingsResult trustResult, CFErrorRef error))
 197     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_NA);
 198
 199 /*
 200  * Purge the cache of User and Admin Certs
 201  */
 202 void SecTrustSettingsPurgeUserAdminCertsCache(void);
 203 #endif // SEC_OS_OSX
 204
 205 #if SEC_OS_OSX_INCLUDES
 206 /*
 207  * A wrapper around SecTrustSettingsCopyCertificates that combines user and admin
 208  * domain outputs.
 209  */
 210 OSStatus SecTrustSettingsCopyCertificatesForUserAdminDomains(
 211     CFArrayRef CF_RETURNS_RETAINED *certArray);
 212 #endif /* SEC_OS_OSX_INCLUDES */
 213
 214 __END_DECLS
 215
 216 #endif // _SECURITY_SECTRUSTSETTINGSPRIV_H_