]>
Commit | Line | Data |
---|---|---|
b1ab9ed8 A |
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 | |
37 | extern "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 | */ | |
179 | enum { | |
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 | }; | |
195 | typedef uint32_t SecTrustSettingsKeyUsage; | |
196 | ||
197 | /*! | |
198 | @enum SecTrustSettingsResult | |
199 | @abstract Result of a trust settings evaluation. | |
200 | */ | |
201 | enum { | |
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 | }; | |
210 | typedef 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 | */ | |
217 | enum { | |
218 | kSecTrustSettingsDomainUser = 0, | |
219 | kSecTrustSettingsDomainAdmin, | |
220 | kSecTrustSettingsDomainSystem | |
221 | }; | |
222 | typedef 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_ */ |