1/*
2 * Copyright (c) 2002-2010,2012-2013 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 SecPolicy
26	The functions provided in SecPolicy.h provide an interface to various
27	X.509 certificate trust policies.
28*/
29
30#ifndef _SECURITY_SECPOLICY_H_
31#define _SECURITY_SECPOLICY_H_
32
33#include <CoreFoundation/CFBase.h>
34#include <CoreFoundation/CFDictionary.h>
35#include <Security/SecBase.h>
36
37__BEGIN_DECLS
38
39/*!
40	@enum Policy Constants
41	@discussion Predefined constants used to specify a policy.
42	@constant kSecPolicyAppleX509Basic
43	@constant kSecPolicyAppleSSL
44	@constant kSecPolicyAppleSMIME
45	@constant kSecPolicyAppleEAP
46	@constant kSecPolicyAppleIPsec
47	@constant kSecPolicyApplePKINITClient
48	@constant kSecPolicyApplePKINITServer
49	@constant kSecPolicyAppleCodeSigning
50	@constant kSecPolicyMacAppStoreReceipt
51	@constant kSecPolicyAppleIDValidation
52	@constant kSecPolicyAppleTimeStamping
53	@constant kSecPolicyAppleRevocation
54*/
55extern CFTypeRef kSecPolicyAppleX509Basic
56    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
57extern CFTypeRef kSecPolicyAppleSSL
58    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
59extern CFTypeRef kSecPolicyAppleSMIME
60    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
61extern CFTypeRef kSecPolicyAppleEAP
62    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
63extern CFTypeRef kSecPolicyAppleIPsec
64    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
65extern CFTypeRef kSecPolicyApplePKINITClient
66    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
67extern CFTypeRef kSecPolicyApplePKINITServer
68    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
69extern CFTypeRef kSecPolicyAppleCodeSigning
70    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
71extern CFTypeRef kSecPolicyMacAppStoreReceipt
72    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
73extern CFTypeRef kSecPolicyAppleIDValidation
74    __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
75extern CFTypeRef kSecPolicyAppleTimeStamping
76    __OSX_AVAILABLE_STARTING(__MAC_10_8, __IPHONE_7_0);
77extern CFTypeRef kSecPolicyAppleRevocation
78    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
79
80/*!
81    @enum Policy Value Constants
82    @abstract Predefined property key constants used to get or set values in
83        a dictionary for a policy instance.
84    @discussion
85        All policies will have the following read-only value:
86            kSecPolicyOid       (the policy object identifier)
87
88        Additional policy values which your code can optionally set:
89            kSecPolicyName      (name which must be matched)
90            kSecPolicyClient    (evaluate for client, rather than server)
91            kSecPolicyRevocationFlags (only valid for a revocation policy)
92
93    @constant kSecPolicyOid Specifies the policy OID (value is a CFStringRef)
94    @constant kSecPolicyName Specifies a CFStringRef (or CFArrayRef of same)
95        containing a name which must be matched in the certificate to satisfy
96        this policy. For SSL/TLS, EAP, and IPSec policies, this specifies the
97        server name which must match the common name of the certificate.
98        For S/MIME, this specifies the RFC822 email address.
99    @constant kSecPolicyClient Specifies a CFBooleanRef value that indicates
100        this evaluation should be for a client certificate. If not set (or
101        false), the policy evaluates the certificate as a server certificate.
102    @constant kSecPolicyRevocationFlags Specifies a CFNumberRef that holds a
103        kCFNumberCFIndexType bitmask value. See "Revocation Policy Constants"
104        for a description of individual bits in this value.
105 */
106extern CFTypeRef kSecPolicyOid
107	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
108extern CFTypeRef kSecPolicyName
109	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
110extern CFTypeRef kSecPolicyClient
111	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
112extern CFTypeRef kSecPolicyRevocationFlags
113	__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
114
115
116/*!
117    @function SecPolicyGetTypeID
118    @abstract Returns the type identifier of SecPolicy instances.
119    @result The CFTypeID of SecPolicy instances.
120*/
121CFTypeID SecPolicyGetTypeID(void)
122	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
123
124/*!
125    @function SecPolicyCopyProperties
126    @abstract Returns a dictionary of this policy's properties.
127    @param policyRef A policy reference.
128    @result A properties dictionary. See "Policy Value Constants" for a list
129    of currently defined property keys. It is the caller's responsibility to
130    CFRelease this reference when it is no longer needed.
131    @result A result code. See "Security Error Codes" (SecBase.h).
132    @discussion This function returns the properties for a policy, as set by the
133    policy's construction function or by a prior call to SecPolicySetProperties.
134*/
135CFDictionaryRef SecPolicyCopyProperties(SecPolicyRef policyRef)
136	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_7_0);
137
138/*!
139    @function SecPolicyCreateBasicX509
140    @abstract Returns a policy object for the default X.509 policy.
141    @result A policy object. The caller is responsible for calling CFRelease
142    on this when it is no longer needed.
143*/
144SecPolicyRef SecPolicyCreateBasicX509(void)
145	__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
146
147/*!
148    @function SecPolicyCreateSSL
149    @abstract Returns a policy object for evaluating SSL certificate chains.
150    @param server Passing true for this parameter creates a policy for SSL
151    server certificates.
152    @param hostname (Optional) If present, the policy will require the specified
153    hostname to match the hostname in the leaf certificate.
154    @result A policy object. The caller is responsible for calling CFRelease
155    on this when it is no longer needed.
156*/
157SecPolicyRef SecPolicyCreateSSL(Boolean server, CFStringRef hostname)
158	__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_2_0);
159
160/*!
161	@enum Revocation Policy Constants
162	@abstract Predefined constants which allow you to specify how revocation
163	checking will be performed for a trust evaluation.
164	@constant kSecRevocationOCSPMethod If this flag is set, perform revocation
165	checking using OCSP (Online Certificate Status Protocol).
166	@constant kSecRevocationCRLMethod If this flag is set, perform revocation
167	checking using the CRL (Certificate Revocation List) method.
168	@constant kSecRevocationPreferCRL If this flag is set, then CRL revocation
169	checking will be preferred over OCSP (by default, OCSP is preferred.)
170	Note that this flag only matters if both revocation methods are specified.
171	@constant kSecRevocationRequirePositiveResponse If this flag is set, then
172	the policy will fail unless a verified positive response is obtained. If
173	the flag is not set, revocation checking is done on a "best attempt" basis,
174	where failure to reach the server is not considered fatal.
175	@constant kSecRevocationNetworkAccessDisabled If this flag is set, then
176	no network access is performed; only locally cached replies are consulted.
177	@constant kSecRevocationUseAnyAvailableMethod Specifies that either
178	OCSP or CRL may be used, depending on the method(s) specified in the
179	certificate and the value of kSecRevocationPreferCRL.
180 */
181enum {
182	kSecRevocationOCSPMethod = (1 << 0),
183	kSecRevocationCRLMethod = (1 << 1),
184	kSecRevocationPreferCRL = (1 << 2),
185	kSecRevocationRequirePositiveResponse = (1 << 3),
186	kSecRevocationNetworkAccessDisabled = (1 << 4),
187	kSecRevocationUseAnyAvailableMethod = (kSecRevocationOCSPMethod |
188		kSecRevocationCRLMethod)
189};
190
191/*!
192	@function SecPolicyCreateRevocation
193	@abstract Returns a policy object for checking revocation of certificates.
194	@result A policy object. The caller is responsible for calling CFRelease
195	on this when it is no longer needed.
196	@param revocationFlags Flags to specify revocation checking options.
197	@discussion Use this function to create a revocation policy with behavior
198	specified by revocationFlags. See the "Revocation Policy Constants" section
199	for a description of these flags. Note: it is usually not necessary to
200	create a revocation policy yourself unless you wish to override default
201	system behavior (e.g. to force a particular method, or to disable
202	revocation checking entirely.)
203*/
204SecPolicyRef SecPolicyCreateRevocation(CFOptionFlags revocationFlags)
205	__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
206
207/*!
208	@function SecPolicyCreateWithProperties
209	@abstract Returns a policy object based on an object identifier for the
210	policy type. See the "Policy Constants" section for a list of defined
211	policy object identifiers.
212	@param policyIdentifier The identifier for the desired policy type.
213	@param properties (Optional) A properties dictionary. See "Policy Value
214	Constants" for a list of currently defined property keys.
215	@result The returned policy reference, or NULL if the policy could not be
216	created.
217*/
218SecPolicyRef SecPolicyCreateWithProperties(CFTypeRef policyIdentifier,
219	CFDictionaryRef properties)
220	__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
221
222
223/*
224 *  Legacy functions (OS X only)
225 */
226#if TARGET_OS_MAC && !TARGET_OS_IPHONE
227#include <Security/cssmtype.h>
228
229/*!
230    @enum Policy Value Constants (OS X)
231    @discussion Predefined property key constants used to get or set values in
232        a dictionary for a policy instance.
233
234        Some policy values may specify CFBooleanRef key usage constraints:
235            kSecPolicyKU_DigitalSignature
236            kSecPolicyKU_NonRepudiation
237            kSecPolicyKU_KeyEncipherment
238            kSecPolicyKU_DataEncipherment
239            kSecPolicyKU_KeyAgreement
240            kSecPolicyKU_KeyCertSign
241            kSecPolicyKU_CRLSign
242            kSecPolicyKU_EncipherOnly
243            kSecPolicyKU_DecipherOnly
244
245        kSecPolicyKU policy values define certificate-level key purposes,
246        in contrast to the key-level definitions in SecItem.h
247
248        For example, a key in a certificate might be acceptable to use for
249        signing a CRL, but not for signing another certificate. In either
250        case, this key would have the ability to sign (i.e. kSecAttrCanSign
251        is true), but may only sign for specific purposes allowed by these
252        policy constants. Similarly, a public key might have the capability
253        to perform encryption or decryption, but the certificate in which it
254        resides might have a decipher-only certificate policy.
255
256        These constants correspond to values defined in RFC 5280, section
257        4.2.1.3 (Key Usage) which define the purpose of a key contained in a
258        certificate, in contrast to section 4.1.2.7 which define the uses that
259        a key is capable of.
260
261        Note: these constants are not available on iOS. Your code should
262        avoid direct reliance on these values for making policy decisions
263        and use higher level policies where possible.
264
265    @constant kSecPolicyKU_DigitalSignature Specifies that the certificate must
266        have a key usage that allows it to be used for signing.
267    @constant kSecPolicyKU_NonRepudiation Specifies that the certificate must
268        have a key usage that allows it to be used for non-repudiation.
269    @constant kSecPolicyKU_KeyEncipherment Specifies that the certificate must
270        have a key usage that allows it to be used for key encipherment.
271    @constant kSecPolicyKU_DataEncipherment Specifies that the certificate must
272        have a key usage that allows it to be used for data encipherment.
273    @constant kSecPolicyKU_KeyAgreement Specifies that the certificate must
274        have a key usage that allows it to be used for key agreement.
275    @constant kSecPolicyKU_KeyCertSign Specifies that the certificate must
276        have a key usage that allows it to be used for signing certificates.
277    @constant kSecPolicyKU_CRLSign Specifies that the certificate must
278        have a key usage that allows it to be used for signing CRLs.
279    @constant kSecPolicyKU_EncipherOnly Specifies that the certificate must
280        have a key usage that permits it to be used for encryption only.
281    @constant kSecPolicyKU_DecipherOnly Specifies that the certificate must
282        have a key usage that permits it to be used for decryption only.
283 */
284extern CFTypeRef kSecPolicyKU_DigitalSignature
285	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
286extern CFTypeRef kSecPolicyKU_NonRepudiation
287	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
288extern CFTypeRef kSecPolicyKU_KeyEncipherment
289	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
290extern CFTypeRef kSecPolicyKU_DataEncipherment
291	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
292extern CFTypeRef kSecPolicyKU_KeyAgreement
293	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
294extern CFTypeRef kSecPolicyKU_KeyCertSign
295	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
296extern CFTypeRef kSecPolicyKU_CRLSign
297	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
298extern CFTypeRef kSecPolicyKU_EncipherOnly
299	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
300extern CFTypeRef kSecPolicyKU_DecipherOnly
301	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
302
303/*!
304	@function SecPolicyCreateWithOID
305	@abstract Returns a policy object based on an object identifier for the
306	policy type. See the "Policy Constants" section for a list of defined
307	policy object identifiers.
308	@param policyOID The OID of the desired policy.
309	@result The returned policy reference, or NULL if the policy could not be
310	created.
311	@discussion This function is deprecated in Mac OS X 10.9 and later;
312	use SecPolicyCreateWithProperties (or a more specific policy creation
313	function) instead.
314*/
315SecPolicyRef SecPolicyCreateWithOID(CFTypeRef policyOID)
316	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
317
318/*!
319	@function SecPolicyGetOID
320	@abstract Returns a policy's object identifier.
321	@param policyRef A policy reference.
322	@param oid On return, a pointer to the policy's object identifier.
323	@result A result code. See "Security Error Codes" (SecBase.h).
324	@discussion This function is deprecated in Mac OS X 10.7 and later;
325	use SecPolicyCopyProperties instead.
326*/
327OSStatus SecPolicyGetOID(SecPolicyRef policyRef, CSSM_OID *oid)
328	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
329
330/*!
331	@function SecPolicyGetValue
332	@abstract Returns a policy's value.
333	@param policyRef A policy reference.
334	@param value On return, a pointer to the policy's value.
335	@result A result code. See "Security Error Codes" (SecBase.h).
336	@discussion This function is deprecated in Mac OS X 10.7 and later;
337	use SecPolicyCopyProperties instead.
338*/
339OSStatus SecPolicyGetValue(SecPolicyRef policyRef, CSSM_DATA *value)
340	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
341
342/*!
343	@function SecPolicySetValue
344	@abstract Sets a policy's value.
345	@param policyRef A policy reference.
346	@param value The value to be set into the policy object, replacing any
347	previous value.
348	@result A result code. See "Security Error Codes" (SecBase.h).
349	@discussion This function is deprecated in Mac OS X 10.7 and later. Policy
350	instances should be considered read-only; in cases where your code would
351	consider changing properties of a policy, it should instead create a new
352	policy instance with the desired properties.
353*/
354OSStatus SecPolicySetValue(SecPolicyRef policyRef, const CSSM_DATA *value)
355	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
356
357/*!
358	@function SecPolicySetProperties
359	@abstract Sets a policy's properties.
360	@param policyRef A policy reference.
361	@param properties A properties dictionary. See "Policy Value Constants"
362	for a list of currently defined property keys. This dictionary replaces the
363	policy's existing properties, if any. Note that the policy OID (specified
364	by kSecPolicyOid) is a read-only property of the policy and cannot be set.
365	@result A result code. See "Security Error Codes" (SecBase.h).
366	@discussion This function is deprecated in Mac OS X 10.9 and later. Policy
367	instances should be considered read-only; in cases where your code would
368	consider changing properties of a policy, it should instead create a new
369	policy instance with the desired properties.
370*/
371OSStatus SecPolicySetProperties(SecPolicyRef policyRef,
372	CFDictionaryRef properties)
373	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
374
375/*!
376	@function SecPolicyGetTPHandle
377	@abstract Returns the CSSM trust policy handle for the given policy.
378	@param policyRef A policy reference.
379	@param tpHandle On return, a pointer to a value of type CSSM_TP_HANDLE.
380	@result A result code. See "Security Error Codes" (SecBase.h).
381	@discussion This function is deprecated in Mac OS X 10.7 and later.
382*/
383OSStatus SecPolicyGetTPHandle(SecPolicyRef policyRef, CSSM_TP_HANDLE *tpHandle)
384	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_2, __MAC_10_7, __IPHONE_NA, __IPHONE_NA);
385
386#endif /* TARGET_OS_MAC && !TARGET_OS_IPHONE */
387
388
389__END_DECLS
390
391#endif /* !_SECURITY_SECPOLICY_H_ */
392