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