trust/SecTrustSettings.h

   1 /*
   2  * Copyright (c) 2006,2007,2011,2012,2014-2016 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     @header SecTrustSettings
  26     The functions and data types in SecTrustSettings implement a way to
  27     set and retrive trustability of certificates.
  28 */
  29
  30 #ifndef _SECURITY_SECTRUSTSETTINGS_H_
  31 #define _SECURITY_SECTRUSTSETTINGS_H_
  32
  33 #include <CoreFoundation/CoreFoundation.h>
  34 #include <CoreFoundation/CFArray.h>
  35 #include <Security/SecBase.h>
  36 #include <Security/SecCertificate.h>
  37
  38 #if SEC_OS_OSX
  39 #include <Security/SecKeychain.h>
  40 #include <Security/SecPolicy.h>
  41 #include <Security/cssmtype.h>
  42 #endif /* SEC_OS_OSX */
  43
  44 __BEGIN_DECLS
  45
  46 #if SEC_OS_OSX_INCLUDES
  47 CF_ASSUME_NONNULL_BEGIN
  48 #endif
  49
  50 /*
  51  * Any certificate (cert) which resides in a keychain can have associated with
  52  * it a set of Trust Settings. Trust Settings specify conditions in which a
  53  * given cert can be trusted or explicitly distrusted. A "trusted" cert is
  54  * either a root (self-signed) cert that, when a cert chain verifies back to that
  55  * root, the entire cert chain is trusted; or a non-root cert that does not need
  56  * to verify to a trusted root cert (which is normally the case when verifying a
  57  * cert chain). An "explicitly distrusted" cert is one which will, when encountered
  58  * during the evaluation of a cert chain, cause immediate and unconditional failure
  59  * of the verify operation.
  60  *
  61  * Trust Settings are configurable by the user; they can apply on three levels
  62  * (called domains):
  63  *
  64  * -- Per-user.
  65  * -- Locally administered, system-wide. Administrator privileges are required
  66  *    to make changes to this domain.
  67  * -- System. These Trust Settings are immutable and comprise the set of trusted
  68  *    root certificates supplied in Mac OS X.
  69  *
  70  * Per-user Trust Settings override locally administered Trust Settings, which
  71  * in turn override the System Trust Settings.
  72  *
  73  * Each cert's Trust Settings are expressed as a CFArray which includes any
  74  * number (including zero) of CFDictionaries, each of which comprises one set of
  75  * Usage Constraints. Each Usage Constraints dictionary contains zero or one of
  76  * each the following components:
  77  *
  78  * key = kSecTrustSettingsPolicy        On OSX, value = SecPolicyRef
  79                                         On iOS, value = policy OID as CFString
  80  *
  81  * key = kSecTrustSettingsApplication           value = SecTrustedApplicationRef
  82  * key = kSecTrustSettingsPolicyString          value = CFString, policy-specific
  83  * key = kSecTrustSettingsKeyUsage              value = CFNumber, an SInt32 key usage
  84  *
  85  * A given Usage Constraints dictionary applies to a given cert if *all* of the
  86  * usage constraint components specified in the dictionary match the usage of
  87  * the cert being evaluated; when this occurs, the value of the
  88  * kSecTrustSettingsResult entry in the dictionary, shown below, is the effective
  89  * trust setting for the cert.
  90  *
  91  * key = kSecTrustSettingsResult          value = CFNumber, an SInt32 SecTrustSettingsResult
  92  *
  93  * The overall Trust Settings of a given cert are the sum of all such Usage
  94  * Constraints CFDictionaries: Trust Settings for a given usage apply if *any*
  95  * of the CFDictionaries in the cert's Trust Settings array satisfies
  96  * the specified usage. Thus, when a cert has multiple Usage Constraints
  97  * dictionaries in its Trust Settings array, the overall Trust Settings
  98  * for the cert are
  99  *
 100  * (Usage Constraint 0 component 0 AND Usage Constraint 0 component 1 ...)
 101  *     -- OR --
 102  * (Usage Constraint 1 component 0 AND Usage Constraint 1 component 1 ...)
 103  *     -- OR --
 104  * ...
 105  *
 106  * Notes on the various Usage Constraints components:
 107  *
 108  * kSecTrustSettingsPolicy          Specifies a cert verification policy, e.g., SSL,
 109  *                                  SMIME, etc, using Policy Constants
 110  * kSecTrustSettingsApplication     Specifies the application performing the cert
 111  *                                  verification.
 112  * kSecTrustSettingsPolicyString    Policy-specific. For the SMIME policy, this is
 113  *                                  an email address.
 114  *                                  For the SSL policy, this is a host name.
 115  * kSecTrustSettingsKeyUsage        A bitfield indicating key operations (sign,
 116  *                                  encrypt, etc.) for which this Usage Constraint
 117  *                                  apply. Values are defined below as the
 118  *                                  SecTrustSettingsKeyUsage enum.
 119  * kSecTrustSettingsResult          The resulting trust value. If not present this has a
 120  *                                  default of kSecTrustSettingsResultTrustRoot, meaning
 121  *                                  "trust this root cert". Other legal values are:
 122  *                                  kSecTrustSettingsResultTrustAsRoot : trust non-root
 123  *                                      cert as if it were a trusted root.
 124  *                                  kSecTrustSettingsResultDeny : explicitly distrust this
 125  *                                      cert.
 126  *                                  kSecTrustSettingsResultUnspecified : neither trust nor
 127  *                                      distrust; can be used to specify an "Allowed error"
 128  *                                      (see below) without assigning trust to a specific
 129  *                                      cert.
 130  *
 131  * Another optional component in a Usage Constraints dictionary is a CSSM_RETURN
 132  * which, if encountered during certificate verification, is ignored for that
 133  * cert. These "allowed error" values are constrained by Usage Constraints as
 134  * described above; a Usage Constraint dictionary with no constraints but with
 135  * an Allowed Error value causes that error to always be allowed when the cert
 136  * is being evaluated.
 137  *
 138  * The "allowed error" entry in a Usage Constraints dictionary is formatted
 139  * as follows:
 140  *
 141  * key = kSecTrustSettingsAllowedError     value = CFNumber, an SInt32 CSSM_RETURN
 142  *
 143  * Note that if kSecTrustSettingsResult value of kSecTrustSettingsResultUnspecified
 144  * is *not* present for a Usage Constraints dictionary with no Usage
 145  * Constraints, the default of kSecTrustSettingsResultTrustRoot is assumed. To
 146  * specify a kSecTrustSettingsAllowedError without explicitly trusting (or
 147  * distrusting) the associated cert, specify kSecTrustSettingsResultUnspecified
 148  * for the kSecTrustSettingsResult component.
 149  *
 150  * Note that an empty Trust Settings array means "always trust this cert,
 151  * with a resulting kSecTrustSettingsResult of kSecTrustSettingsResultTrustRoot".
 152  * An empty Trust Settings array is definitely not the same as *no* Trust
 153  * Settings, which means "this cert must be verified to a known trusted cert".
 154  *
 155  * Note the distinction between kSecTrustSettingsResultTrustRoot and
 156  * kSecTrustSettingsResultTrustAsRoot; the former can only be applied to
 157  * root (self-signed) certs; the latter can only be applied to non-root
 158  * certs. This also means that an empty TrustSettings array for a non-root
 159  * cert is invalid, since the default value for kSecTrustSettingsResult is
 160  * kSecTrustSettingsResultTrustRoot, which is invalid for a non-root cert.
 161  *
 162  * Authentication
 163  * --------------
 164  *
 165  * When making changes to the per-user Trust Settings, the user will be
 166  * prompted with an alert panel asking for authentication via user name a
 167  * password (or other credentials normally used for login). This means
 168  * that it is not possible to modify per-user Trust Settings when not
 169  * running in a GUI environment (i.e. the user is not logged in via
 170  * Loginwindow).
 171  *
 172  * When making changes to the system-wide Trust Settings, the user will be
 173  * prompted with an alert panel asking for an administrator's name and
 174  * password, unless the calling process is running as root in which case
 175  * no futher authentication is needed.
 176  */
 177
 178 /*
 179  * The keys in one Usage Constraints dictionary.
 180  */
 181 #define kSecTrustSettingsPolicy         CFSTR("kSecTrustSettingsPolicy")
 182 #define kSecTrustSettingsApplication    CFSTR("kSecTrustSettingsApplication")
 183 #define kSecTrustSettingsPolicyString   CFSTR("kSecTrustSettingsPolicyString")
 184 #define kSecTrustSettingsKeyUsage       CFSTR("kSecTrustSettingsKeyUsage")
 185 #define kSecTrustSettingsAllowedError   CFSTR("kSecTrustSettingsAllowedError")
 186 #define kSecTrustSettingsResult         CFSTR("kSecTrustSettingsResult")
 187
 188 /*
 189  * Key usage bits, the value for Usage Constraints key kSecTrustSettingsKeyUsage.
 190  */
 191 typedef CF_OPTIONS(uint32_t, SecTrustSettingsKeyUsage) {
 192      /* sign/verify data */
 193      kSecTrustSettingsKeyUseSignature       = 0x00000001,
 194      /* bulk encryption */
 195      kSecTrustSettingsKeyUseEnDecryptData   = 0x00000002,
 196      /* key wrap/unwrap */
 197      kSecTrustSettingsKeyUseEnDecryptKey    = 0x00000004,
 198      /* sign/verify cert */
 199      kSecTrustSettingsKeyUseSignCert        = 0x00000008,
 200      /* sign/verify CRL and OCSP */
 201      kSecTrustSettingsKeyUseSignRevocation  = 0x00000010,
 202      /* key exchange, e.g., Diffie-Hellman */
 203      kSecTrustSettingsKeyUseKeyExchange     = 0x00000020,
 204      /* any usage (the default if this value is not specified) */
 205      kSecTrustSettingsKeyUseAny             = 0xffffffff
 206 };
 207
 208 /*!
 209     @enum SecTrustSettingsResult
 210     @abstract Result of a trust settings evaluation.
 211 */
 212 typedef CF_ENUM(uint32_t, SecTrustSettingsResult) {
 213      kSecTrustSettingsResultInvalid = 0,   /* Never valid in a Trust Settings array or
 214                                             * in an API call. */
 215      kSecTrustSettingsResultTrustRoot,     /* Root cert is explicitly trusted */
 216      kSecTrustSettingsResultTrustAsRoot,   /* Non-root cert is explicitly trusted */
 217      kSecTrustSettingsResultDeny,          /* Cert is explicitly distrusted */
 218      kSecTrustSettingsResultUnspecified    /* Neither trusted nor distrusted; evaluation
 219                                             * proceeds as usual */
 220 };
 221
 222 /*
 223  * Specify user, local administrator, or system domain Trust Settings.
 224  * Note that kSecTrustSettingsDomainSystem settings are read-only, even by
 225  * root.
 226  */
 227 typedef CF_ENUM(uint32_t, SecTrustSettingsDomain) {
 228      kSecTrustSettingsDomainUser = 0,
 229      kSecTrustSettingsDomainAdmin,
 230      kSecTrustSettingsDomainSystem
 231 };
 232
 233 /*
 234  * This constant is deprecated and ineffective as of macOS 10.12.
 235  * Please discontinue use.
 236  */
 237 #define kSecTrustSettingsDefaultRootCertSetting          ((SecCertificateRef)-1)
 238
 239 #if SEC_OS_OSX_INCLUDES
 240 /*
 241  * Obtain Trust Settings for specified cert.
 242  * Caller must CFRelease() the returned CFArray.
 243  * Returns errSecItemNotFound if no Trust settings exist for the cert.
 244  */
 245 OSStatus SecTrustSettingsCopyTrustSettings(
 246      SecCertificateRef          certRef,
 247      SecTrustSettingsDomain     domain,
 248      CFArrayRef * __nonnull CF_RETURNS_RETAINED trustSettings);     /* RETURNED */
 249
 250 /*
 251  * Specify Trust Settings for specified cert. If specified cert
 252  * already has Trust Settings in the specified domain, they will
 253  * be replaced.
 254  * The trustSettingsDictOrArray parameter is either a CFDictionary,
 255  * a CFArray of them, or NULL. NULL indicates "always trust this
 256  * root cert regardless of usage".
 257  */
 258 OSStatus SecTrustSettingsSetTrustSettings(
 259      SecCertificateRef          certRef,
 260      SecTrustSettingsDomain     domain,
 261      CFTypeRef __nullable     trustSettingsDictOrArray);
 262
 263 /*
 264  * Delete Trust Settings for specified cert.
 265  * Returns errSecItemNotFound if no Trust settings exist for the cert.
 266  */
 267 OSStatus SecTrustSettingsRemoveTrustSettings(
 268      SecCertificateRef          certRef,
 269      SecTrustSettingsDomain     domain);
 270
 271 /*
 272  * Obtain an array of all certs which have Trust Settings in the
 273  * specified domain. Elements in the returned certArray are
 274  * SecCertificateRefs.
 275  * Caller must CFRelease() the returned array.
 276  * Returns errSecNoTrustSettings if no trust settings exist
 277  * for the specified domain.
 278  */
 279 OSStatus SecTrustSettingsCopyCertificates(
 280      SecTrustSettingsDomain     domain,
 281      CFArrayRef * __nullable CF_RETURNS_RETAINED certArray);
 282
 283 /*
 284  * Obtain the time at which a specified cert's Trust Settings
 285  * were last modified. Caller must CFRelease the result.
 286  * Returns errSecItemNotFound if no Trust Settings exist for specified
 287  * cert and domain.
 288  */
 289 OSStatus SecTrustSettingsCopyModificationDate(
 290      SecCertificateRef          certRef,
 291      SecTrustSettingsDomain     domain,
 292      CFDateRef * __nonnull CF_RETURNS_RETAINED modificationDate);     /* RETURNED */
 293
 294 /*
 295  * Obtain an external, portable representation of the specified
 296  * domain's TrustSettings. Caller must CFRelease the returned data.
 297  * Returns errSecNoTrustSettings if no trust settings exist
 298  * for the specified domain.
 299  */
 300 OSStatus SecTrustSettingsCreateExternalRepresentation(
 301      SecTrustSettingsDomain     domain,
 302      CFDataRef * __nonnull CF_RETURNS_RETAINED trustSettings);
 303
 304 /*
 305  * Import trust settings, obtained via SecTrustSettingsCreateExternalRepresentation,
 306  * into the specified domain.
 307  */
 308 OSStatus SecTrustSettingsImportExternalRepresentation(
 309      SecTrustSettingsDomain     domain,
 310      CFDataRef                    trustSettings);
 311
 312 CF_ASSUME_NONNULL_END
 313
 314 #endif /* SEC_OS_OSX_INCLUDES */
 315
 316 __END_DECLS
 317
 318 #endif /* _SECURITY_SECTRUSTSETTINGS_H_ */