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