[apple/security.git] / Security / libsecurity_keychain / lib / SecIdentityPriv.h

/*
 * Copyright (c) 2002-2011 Apple Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef _SECURITY_SECIDENTITYPRIV_H_
#define _SECURITY_SECIDENTITYPRIV_H_

#include <Security/SecBase.h>

#if defined(__cplusplus)
extern "C" {
#endif

/*!	@function SecIdentityCreate
	@abstract create a new identity object from the provided certificate and its associated private key.
    @param allocator CFAllocator to allocate the identity object. Pass NULL to use the default allocator.
    @param certificate A certificate reference.
	@param privateKey A private key reference.
    @result An identity reference.
*/
SecIdentityRef SecIdentityCreate(
	CFAllocatorRef allocator,
	SecCertificateRef certificate,
	SecKeyRef privateKey)
	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_NA);

/*!
	@function SecIdentityCompare
    @abstract Compares two SecIdentityRef instances for equality.
    @param identity1 An identity reference.
	@param identity2 An identity reference.
	@param compareOptions A value containing option flags. Currently there are no compare options, so 0 should be passed for this parameter.
    @result An enumerated value of type CFComparisonResult. See CFBase.h.
	@discussion Two identities are considered equal if they contain identical certificate and private key components.
    @deprecated in Mac OS X 10.5 and later; the CFEqual function should be used instead (CFBase.h).
*/
CFComparisonResult SecIdentityCompare(
    SecIdentityRef identity1,
    SecIdentityRef identity2,
    CFOptionFlags compareOptions)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;

/*!
	@function SecIdentityFindPreferenceItem
    @abstract Returns an identity preference item, given an identity string.
    @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.
    @param idString A string containing a URI, hostname, or email (RFC822) address.
	@param itemRef On return, a reference to the keychain item which was found. The caller is responsible for releasing this reference.
    @result A result code.  See "Security Error Codes" (SecBase.h).
	@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.
	@deprecated in Mac OS X 10.7 and later; use SecIdentityCopyPreferred() instead (SecIdentity.h)
	
	WARNING: This function is based on an implementation detail and will go away
	in a future release; its use should be avoided at all costs. It does not
	provide a way to find a preference item based on key usage, and it can only
	find preferences which are stored as keychain items, so it may fail to find
	the item you expect. Please use the public API functions to manipulate
	identity preferences.
*/
OSStatus SecIdentityFindPreferenceItem(
	CFTypeRef keychainOrArray,
	CFStringRef idString,
	SecKeychainItemRef *itemRef)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;

/*!
	@function SecIdentityAddPreferenceItem
    @abstract Adds a new identity preference item to the specified keychain.
	@param keychainRef A reference to the keychain in which to store the preference item. Pass NULL to specify the user's default keychain.
    @param identityRef An identity reference.
	@param idString A string containing a URI, hostname, or email (RFC822) address.
	@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.
    @result A result code.  See "Security Error Codes" (SecBase.h).
	@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.
    @deprecated in Mac OS X 10.5; use SecIdentitySetPreference() instead (SecIdentity.h).
*/
OSStatus SecIdentityAddPreferenceItem(
	SecKeychainRef keychainRef,
	SecIdentityRef identityRef,
	CFStringRef idString,
	SecKeychainItemRef *itemRef)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;

/*!
	@function SecIdentityUpdatePreferenceItem
    @abstract Given an existing identity preference keychain item, update it with the provided identity.
	@param itemRef An identity preference keychain item, as returned by SecIdentityFindPreferenceItem or SecIdentityAddPreferenceItem.
    @param identityRef An identity reference.
    @result A result code.  See "Security Error Codes" (SecBase.h).
	@discussion This function is used to update an existing preference item when a different identity is preferred.
    @deprecated in Mac OS X 10.5; use SecIdentitySetPreference() instead (SecIdentity.h).
*/
OSStatus SecIdentityUpdatePreferenceItem(
	SecKeychainItemRef itemRef,
	SecIdentityRef identityRef)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;

/*!
	@function SecIdentityCopyFromPreferenceItem
    @abstract Given an existing identity preference keychain item, obtain a SecIdentityRef for the identity it specifies.
	@param itemRef An identity preference keychain item, as returned by SecIdentityFindPreferenceItem or SecIdentityAddPreferenceItem.
    @param identityRef On return, an identity reference. The caller is responsible for releasing this reference.
    @result A result code.  See "Security Error Codes" (SecBase.h).
	@discussion This function is used to obtain a SecIdentityRef from an existing preference item.
    @deprecated in Mac OS X 10.5; use SecIdentityCopyPreference() instead (SecIdentity.h).
*/
OSStatus SecIdentityCopyFromPreferenceItem(
	SecKeychainItemRef itemRef,
	SecIdentityRef *identityRef)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;

/*!
	@function ConvertArrayToKeyUsage
    @abstract Given an array of key usages defined in SecItem.h return the equivalent CSSM_KEYUSE
	@param usage An CFArrayRef containing CFTypeRefs defined in SecItem.h
		kSecAttrCanEncrypt,
		kSecAttrCanDecrypt,
		kSecAttrCanDerive,
		kSecAttrCanSign,
		kSecAttrCanVerify,
		kSecAttrCanWrap,
		kSecAttrCanUnwrap
		If the CFArrayRef is NULL then the CSSM_KEYUSAGE will be CSSM_KEYUSE_ANY
    @result A CSSM_KEYUSE.  Derived from the passed in Array
*/		
CSSM_KEYUSE ConvertArrayToKeyUsage(CFArrayRef usage);


#if defined(__cplusplus)
}
#endif

#endif /* !_SECURITY_SECIDENTITYPRIV_H_ */
Commit	Line	Data
b1ab9ed8	1	/*
d8f41ccd	2	* Copyright (c) 2002-2011 Apple Inc. All Rights Reserved.
b1ab9ed8 A	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)
	30	extern "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	*/
	40	SecIdentityRef 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	*/
	56	CFComparisonResult 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	*/
79	OSStatus 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	*/
96	OSStatus 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	*/
112	OSStatus 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	*/
126	OSStatus 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	*/
145	CSSM_KEYUSE ConvertArrayToKeyUsage(CFArrayRef usage);
146
147
148	#if defined(__cplusplus)
149	}
150	#endif
151
152	#endif /* !_SECURITY_SECIDENTITYPRIV_H_ */