1/*
2 * Copyright (c) 2002-2011 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#ifndef _SECURITY_SECIDENTITYPRIV_H_
25#define _SECURITY_SECIDENTITYPRIV_H_
26
27#include <Security/SecBase.h>
28
29#if defined(__cplusplus)
30extern "C" {
31#endif
32
33/*!	@function SecIdentityCreate
34	@abstract create a new identity object from the provided certificate and its associated private key.
35    @param allocator CFAllocator to allocate the identity object. Pass NULL to use the default allocator.
36    @param certificate A certificate reference.
37	@param privateKey A private key reference.
38    @result An identity reference.
39*/
40SecIdentityRef SecIdentityCreate(
41	CFAllocatorRef allocator,
42	SecCertificateRef certificate,
43	SecKeyRef privateKey)
44	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);
45
46/*!
47	@function SecIdentityCompare
48    @abstract Compares two SecIdentityRef instances for equality.
49    @param identity1 An identity reference.
50	@param identity2 An identity reference.
51	@param compareOptions A value containing option flags. Currently there are no compare options, so 0 should be passed for this parameter.
52    @result An enumerated value of type CFComparisonResult. See CFBase.h.
53	@discussion Two identities are considered equal if they contain identical certificate and private key components.
54    @deprecated in Mac OS X 10.5 and later; the CFEqual function should be used instead (CFBase.h).
55*/
56CFComparisonResult SecIdentityCompare(
57    SecIdentityRef identity1,
58    SecIdentityRef identity2,
59    CFOptionFlags compareOptions)
60	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
61
62/*!
63	@function SecIdentityFindPreferenceItem
64    @abstract Returns an identity preference item, given an identity string.
65    @param keychainOrArray A reference to an array of keychains to search, a single keychain, or NULL to search the user's default keychain search list.
66    @param idString A string containing a URI, hostname, or email (RFC822) address.
67	@param itemRef On return, a reference to the keychain item which was found. The caller is responsible for releasing this reference.
68    @result A result code.  See "Security Error Codes" (SecBase.h).
69	@discussion An identity preference item maps a particular identity to a string, such as a URI or email address. It specifies that this identity should be preferred in transactions which match the provided string.
70	@deprecated in Mac OS X 10.7 and later; use SecIdentityCopyPreferred() instead (SecIdentity.h)
71
72	WARNING: This function is based on an implementation detail and will go away
73	in a future release; its use should be avoided at all costs. It does not
74	provide a way to find a preference item based on key usage, and it can only
75	find preferences which are stored as keychain items, so it may fail to find
76	the item you expect. Please use the public API functions to manipulate
77	identity preferences.
78*/
79OSStatus SecIdentityFindPreferenceItem(
80	CFTypeRef keychainOrArray,
81	CFStringRef idString,
82	SecKeychainItemRef *itemRef)
83	DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
84
85/*!
86	@function SecIdentityAddPreferenceItem
87    @abstract Adds a new identity preference item to the specified keychain.
88	@param keychainRef A reference to the keychain in which to store the preference item. Pass NULL to specify the user's default keychain.
89    @param identityRef An identity reference.
90	@param idString A string containing a URI, hostname, or email (RFC822) address.
91	@param itemRef On return, a reference to the new keychain item. The caller is responsible for releasing this reference. Pass NULL if the reference is not needed.
92    @result A result code.  See "Security Error Codes" (SecBase.h).
93	@discussion An identity preference item maps a particular identity to a string, such as a URI or email address. It specifies that this identity should be preferred in transactions which match the provided string.
94    @deprecated in Mac OS X 10.5; use SecIdentitySetPreference() instead (SecIdentity.h).
95*/
96OSStatus SecIdentityAddPreferenceItem(
97	SecKeychainRef keychainRef,
98	SecIdentityRef identityRef,
99	CFStringRef idString,
100	SecKeychainItemRef *itemRef)
101	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
102
103/*!
104	@function SecIdentityUpdatePreferenceItem
105    @abstract Given an existing identity preference keychain item, update it with the provided identity.
106	@param itemRef An identity preference keychain item, as returned by SecIdentityFindPreferenceItem or SecIdentityAddPreferenceItem.
107    @param identityRef An identity reference.
108    @result A result code.  See "Security Error Codes" (SecBase.h).
109	@discussion This function is used to update an existing preference item when a different identity is preferred.
110    @deprecated in Mac OS X 10.5; use SecIdentitySetPreference() instead (SecIdentity.h).
111*/
112OSStatus SecIdentityUpdatePreferenceItem(
113	SecKeychainItemRef itemRef,
114	SecIdentityRef identityRef)
115	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
116
117/*!
118	@function SecIdentityCopyFromPreferenceItem
119    @abstract Given an existing identity preference keychain item, obtain a SecIdentityRef for the identity it specifies.
120	@param itemRef An identity preference keychain item, as returned by SecIdentityFindPreferenceItem or SecIdentityAddPreferenceItem.
121    @param identityRef On return, an identity reference. The caller is responsible for releasing this reference.
122    @result A result code.  See "Security Error Codes" (SecBase.h).
123	@discussion This function is used to obtain a SecIdentityRef from an existing preference item.
124    @deprecated in Mac OS X 10.5; use SecIdentityCopyPreference() instead (SecIdentity.h).
125*/
126OSStatus SecIdentityCopyFromPreferenceItem(
127	SecKeychainItemRef itemRef,
128	SecIdentityRef *identityRef)
129	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
130
131/*!
132	@function ConvertArrayToKeyUsage
133    @abstract Given an array of key usages defined in SecItem.h return the equivalent CSSM_KEYUSE
134	@param usage An CFArrayRef containing CFTypeRefs defined in SecItem.h
135		kSecAttrCanEncrypt,
136		kSecAttrCanDecrypt,
137		kSecAttrCanDerive,
138		kSecAttrCanSign,
139		kSecAttrCanVerify,
140		kSecAttrCanWrap,
141		kSecAttrCanUnwrap
142		If the CFArrayRef is NULL then the CSSM_KEYUSAGE will be CSSM_KEYUSE_ANY
143    @result A CSSM_KEYUSE.  Derived from the passed in Array
144*/
145CSSM_KEYUSE ConvertArrayToKeyUsage(CFArrayRef usage);
146
147
148#if defined(__cplusplus)
149}
150#endif
151
152#endif /* !_SECURITY_SECIDENTITYPRIV_H_ */
153