1/* 2 * Copyright (c) 2007 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/CFArray.h> 34#include <Security/SecCertificate.h> 35 36#ifdef __cplusplus 37extern "C" { 38#endif 39 40/* 41 * Any certificate (cert) which resides in a keychain can have associated with 42 * it a set of Trust Settings. Trust Settings specify conditions in which a 43 * given cert can be trusted or explicitly distrusted. A "trusted" cert is 44 * either a root (self-signed) cert that, when a cert chain verifies back to that 45 * root, the entire cert chain is trusted; or a non-root cert that does not need 46 * to verify to a trusted root cert (which is normally the case when verifying a 47 * cert chain). An "explicitly distrusted" cert is one which will, when encountered 48 * during the evaluation of a cert chain, cause immediate and unconditional failure 49 * of the verify operation. 50 * 51 * Trust Settings are configurable by the user; they can apply on three levels 52 * (called domains): 53 * 54 * -- Per-user. 55 * -- Locally administered, system-wide. Administrator privileges are required 56 * to make changes to this domain. 57 * -- System. These Trust Settings are immutable and comprise the set of trusted 58 * root certificates supplied in Mac OS X. 59 * 60 * Per-user Trust Settings override locally administered Trust Settings, which 61 * in turn override the System Trust Settings. 62 * 63 * Each cert's Trust Settings are expressed as a CFArray which includes any 64 * number (including zero) of CFDictionaries, each of which comprises one set of 65 * Usage Constraints. Each Usage Constraints dictionary contains zero or one of 66 * each the following components: 67 * 68 * key = kSecTrustSettingsPolicy value = SecPolicyRef 69 * key = kSecTrustSettingsApplication value = SecTrustedApplicationRef 70 * key = kSecTrustSettingsPolicyString value = CFString, policy-specific 71 * key = kSecTrustSettingsKeyUsage value = CFNumber, an SInt32 key usage 72 * 73 * A given Usage Constraints dictionary applies to a given cert if *all* of the 74 * usage constraint components specified in the dictionary match the usage of 75 * the cert being evaluated; when this occurs, the value of the 76 * kSecTrustSettingsResult entry in the dictionary, shown below, is the effective 77 * trust setting for the cert. 78 * 79 * key = kSecTrustSettingsResult value = CFNumber, an SInt32 SecTrustSettingsResult 80 * 81 * The overall Trust Settings of a given cert are the sum of all such Usage 82 * Constraints CFDictionaries: Trust Settings for a given usage apply if *any* 83 * of the CFDictionaries in the cert's Trust Settings array satisfies 84 * the specified usage. Thus, when a cert has multiple Usage Constraints 85 * dictionaries in its Trust Settings array, the overall Trust Settings 86 * for the cert are 87 * 88 * (Usage Constraint 0 component 0 AND Usage Constraint 0 component 1 ...) 89 * -- OR -- 90 * (Usage Constraint 1 component 0 AND Usage Constraint 1 component 1 ...) 91 * -- OR -- 92 * ... 93 * 94 * Notes on the various Usage Constraints components: 95 * 96 * kSecTrustSettingsPolicy Specifies a cert verification policy, e.g., SSL, 97 * SMIME, etc. 98 * kSecTrustSettingsApplication Specifies the application performing the cert 99 * verification. 100 * kSecTrustSettingsPolicyString Policy-specific. For the SMIME policy, this is 101 * an email address. 102 * For the SSL policy, this is a host name. 103 * kSecTrustSettingsKeyUsage A bitfield indicating key operations (sign, 104 * encrypt, etc.) for which this Usage Constraint 105 * apply. Values are defined below as the 106 * SecTrustSettingsKeyUsage enum. 107 * kSecTrustSettingsResult The resulting trust value. If not present this has a 108 * default of kSecTrustSettingsResultTrustRoot, meaning 109 * "trust this root cert". Other legal values are: 110 * kSecTrustSettingsResultTrustAsRoot : trust non-root 111 * cert as if it were a trusted root. 112 * kSecTrustSettingsResultDeny : explicitly distrust this 113 * cert. 114 * kSecTrustSettingsResultUnspecified : neither trust nor 115 * distrust; can be used to specify an "Allowed error" 116 * (see below) without assigning trust to a specific 117 * cert. 118 * 119 * Another optional component in a Usage Constraints dictionary is a CSSM_RETURN 120 * which, if encountered during certificate verification, is ignored for that 121 * cert. These "allowed error" values are constrained by Usage Constraints as 122 * described above; a Usage Constraint dictionary with no constraints but with 123 * an Allowed Error value causes that error to always be allowed when the cert 124 * is being evaluated. 125 * 126 * The "allowed error" entry in a Usage Constraints dictionary is formatted 127 * as follows: 128 * 129 * key = kSecTrustSettingsAllowedError value = CFNumber, an SInt32 CSSM_RETURN 130 * 131 * Note that if kSecTrustSettingsResult value of kSecTrustSettingsResultUnspecified 132 * is *not* present for a Usage Constraints dictionary with no Usage 133 * Constraints, the default of kSecTrustSettingsResultTrustRoot is assumed. To 134 * specify a kSecTrustSettingsAllowedError without explicitly trusting (or 135 * distrusting) the associated cert, specify kSecTrustSettingsResultUnspecified 136 * for the kSecTrustSettingsResult component. 137 * 138 * Note that an empty Trust Settings array means "always trust this cert, 139 * with a resulting kSecTrustSettingsResult of kSecTrustSettingsResultTrustRoot". 140 * An empty Trust Settings array is definitely not the same as *no* Trust 141 * Settings, which means "this cert must be verified to a known trusted cert". 142 * 143 * Note the distinction between kSecTrustSettingsResultTrustRoot and 144 * kSecTrustSettingsResultTrustAsRoot; the former can only be applied to 145 * root (self-signed) certs; the latter can only be applied to non-root 146 * certs. This also means that an empty TrustSettings array for a non-root 147 * cert is invalid, since the default value for kSecTrustSettingsResult is 148 * kSecTrustSettingsResultTrustRoot, which is invalid for a non-root cert. 149 * 150 * Authentication 151 * -------------- 152 * 153 * When making changes to the per-user Trust Settings, the user will be 154 * prompted with an alert panel asking for authentication via user name a 155 * password (or other credentials normally used for login). This means 156 * that it is not possible to modify per-user Trust Settings when not 157 * running in a GUI environment (i.e. the user is not logged in via 158 * Loginwindow). 159 * 160 * When making changes to the system-wide Trust Settings, the user will be 161 * prompted with an alert panel asking for an administrator's name and 162 * password, unless the calling process is running as root in which case 163 * no futher authentication is needed. 164 */ 165 166/* 167 * The keys in one Usage Constraints dictionary. 168 */ 169#define kSecTrustSettingsPolicy CFSTR("kSecTrustSettingsPolicy") 170#define kSecTrustSettingsApplication CFSTR("kSecTrustSettingsApplication") 171#define kSecTrustSettingsPolicyString CFSTR("kSecTrustSettingsPolicyString") 172#define kSecTrustSettingsKeyUsage CFSTR("kSecTrustSettingsKeyUsage") 173#define kSecTrustSettingsAllowedError CFSTR("kSecTrustSettingsAllowedError") 174#define kSecTrustSettingsResult CFSTR("kSecTrustSettingsResult") 175 176/* 177 * Key usage bits, the value for Usage Constraints key kSecTrustSettingsKeyUsage. 178 */ 179enum { 180 /* sign/verify data */ 181 kSecTrustSettingsKeyUseSignature = 0x00000001, 182 /* bulk encryption */ 183 kSecTrustSettingsKeyUseEnDecryptData = 0x00000002, 184 /* key wrap/unwrap */ 185 kSecTrustSettingsKeyUseEnDecryptKey = 0x00000004, 186 /* sign/verify cert */ 187 kSecTrustSettingsKeyUseSignCert = 0x00000008, 188 /* sign/verify CRL and OCSP */ 189 kSecTrustSettingsKeyUseSignRevocation = 0x00000010, 190 /* key exchange, e.g., Diffie-Hellman */ 191 kSecTrustSettingsKeyUseKeyExchange = 0x00000020, 192 /* any usage (the default if this value is not specified) */ 193 kSecTrustSettingsKeyUseAny = 0xffffffff 194}; 195typedef uint32_t SecTrustSettingsKeyUsage; 196 197/*! 198 @enum SecTrustSettingsResult 199 @abstract Result of a trust settings evaluation. 200*/ 201enum { 202 kSecTrustSettingsResultInvalid = 0, /* Never valid in a Trust Settings array or 203 * in an API call. */ 204 kSecTrustSettingsResultTrustRoot, /* Root cert is explicitly trusted */ 205 kSecTrustSettingsResultTrustAsRoot, /* Non-root cert is explicitly trusted */ 206 kSecTrustSettingsResultDeny, /* Cert is explicitly distrusted */ 207 kSecTrustSettingsResultUnspecified /* Neither trusted nor distrusted; evaluation 208 * proceeds as usual */ 209}; 210typedef uint32_t SecTrustSettingsResult; 211 212/* 213 * Specify user, local administrator, or system domain Trust Properties. 214 * Note that kSecTrustSettingsDomainSystem settings are read-only, even by 215 * root. 216 */ 217enum { 218 kSecTrustSettingsDomainUser = 0, 219 kSecTrustSettingsDomainAdmin, 220 kSecTrustSettingsDomainSystem 221}; 222typedef uint32_t SecTrustSettingsDomain; 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#ifdef __cplusplus 244} 245#endif 246 247#endif /* _SECURITY_SECTRUSTSETTINGS_H_ */ 248