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