OSX/include/security_keychain/SecTrustSettings.h

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