[apple/security.git] / Security / libsecurity_keychain / lib / SecIdentity.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@
 */

/*!
	@header SecIdentity
	The functions provided in SecIdentity implement a convenient way to match private keys with certificates.
*/

#ifndef _SECURITY_SECIDENTITY_H_
#define _SECURITY_SECIDENTITY_H_

#include <CoreFoundation/CFBase.h>
#include <CoreFoundation/CFArray.h>
#include <Security/SecBase.h>
#include <Security/cssmtype.h>
#include <AvailabilityMacros.h>

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

/*!
	@function SecIdentityGetTypeID
	@abstract Returns the type identifier of SecIdentity instances.
	@result The CFTypeID of SecIdentity instances.
*/
CFTypeID SecIdentityGetTypeID(void)
	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);

/*!
	@function SecIdentityCreateWithCertificate
    @abstract Creates a new identity reference for the given certificate, assuming the associated private key is in one of the specified keychains.
    @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 certificateRef A certificate reference.
    @param identityRef On return, an identity reference. You are responsible for releasing this reference by calling the CFRelease function.
    @result A result code. See "Security Error Codes" (SecBase.h).
*/
OSStatus SecIdentityCreateWithCertificate(
			CFTypeRef keychainOrArray,
			SecCertificateRef certificateRef,
            SecIdentityRef *identityRef)
	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*!
	@function SecIdentityCopyCertificate
    @abstract Returns a reference to a certificate for the given identity reference.
    @param identityRef An identity reference.
	@param certificateRef On return, a reference to the found certificate. You are responsible for releasing this reference by calling the CFRelease function.
    @result A result code. See "Security Error Codes" (SecBase.h).
*/
OSStatus SecIdentityCopyCertificate(
            SecIdentityRef identityRef, 
            SecCertificateRef *certificateRef)
	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);

/*!
	@function SecIdentityCopyPrivateKey
    @abstract Returns the private key associated with an identity.
    @param identityRef An identity reference.
	@param privateKeyRef On return, a reference to the private key for the given identity. You are responsible for releasing this reference by calling the CFRelease function.
    @result A result code. See "Security Error Codes" (SecBase.h).
*/
OSStatus SecIdentityCopyPrivateKey(
            SecIdentityRef identityRef, 
            SecKeyRef *privateKeyRef)
	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);

/*!
    @function SecIdentityCopyPreference
    @abstract Returns the preferred identity for the specified name and key usage, optionally limiting the result to an identity issued by a certificate whose subject is one of the distinguished names in validIssuers. If a preferred identity does not exist, NULL is returned.
    @param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies the service requiring an identity.
    @param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to ignore this parameter.
    @param validIssuers (optional) An array of CFDataRef instances whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames (SecureTransport.h). Pass NULL if any issuer is allowed.
    @param identity On return, a reference to the preferred identity, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.
    @result A result code. See "Security Error Codes" (SecBase.h).
    @discussion This API is deprecated in 10.7. Please use the SecIdentityCopyPreferred API instead.
*/
OSStatus SecIdentityCopyPreference(CFStringRef name, CSSM_KEYUSE keyUsage, CFArrayRef validIssuers, SecIdentityRef *identity)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;

/*!
    @function SecIdentityCopyPreferred
    @abstract Returns the preferred identity for the specified name and key usage, optionally limiting the result to an identity issued by a certificate whose subject is one of the distinguished names in validIssuers. If a preferred identity does not exist, NULL is returned.
    @param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies the service requiring an identity.
    @param keyUsage A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
    @param validIssuers (optional) An array of CFDataRef instances whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames (SecureTransport.h). Pass NULL if any issuer is allowed.
    @param identity On return, a reference to the preferred identity, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.
    @result An identity or NULL. if the preferred identity has not been set. Your code should then typically perform a search for possible identities using the SecItem APIs.
    @discussion If a preferred identity has not been set for the supplied name, the returned identity reference will be NULL. Your code should then perform a search for possible identities, using the SecItemCopyMatching API.
*/
SecIdentityRef SecIdentityCopyPreferred(CFStringRef name, CFArrayRef keyUsage, CFArrayRef validIssuers)	
	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
	
/*!
    @function SecIdentitySetPreference
    @abstract Sets the preferred identity for the specified name and key usage.
    @param identity A reference to the identity which will be preferred.
    @param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
    @param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to specify any key usage.
    @result A result code. See "Security Error Codes" (SecBase.h).
	@discussion This API is deprecated in 10.7. Please use the SecIdentitySetPreferred API instead.
*/
OSStatus SecIdentitySetPreference(SecIdentityRef identity, CFStringRef name, CSSM_KEYUSE keyUsage)
	DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
		
/*!
    @function SecIdentitySetPreferred
    @abstract Sets the preferred identity for the specified name and key usage.
    @param identity A reference to the identity which will be preferred. If NULL is passed, any existing preference for the specified name is cleared instead.
    @param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
    @param keyUsage A CFArrayRef value, containing items defined in SecItem.h  Pass NULL to specify any key usage. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
    @result A result code. See "Security Error Codes" (SecBase.h).
*/	
OSStatus SecIdentitySetPreferred(SecIdentityRef identity, CFStringRef name, CFArrayRef keyUsage)
	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);

/*!
	@function	SecIdentityCopySystemIdentity
	@abstract	Obtain the system-wide SecIdentityRef associated with 
				a specified domain.
	@param		domain  Identifies the SecIdentityRef to be obtained, typically
						in the form "com.apple.subdomain...". 
	@param		idRef	On return, the system SecIdentityRef assicated with 
						the specified domain. Caller must CFRelease this when 
						finished with it.	
	@param		actualDomain (optional) The actual domain name of the 
						the returned identity is returned here. This
						may be different from the requested domain. 
    @result		A result code.  See "Security Error Codes" (SecBase.h).
	@discussion	If no system SecIdentityRef exists for the specified
				domain, a domain-specific alternate may be returned
				instead, typically (but not exclusively) the 
				kSecIdentityDomainDefault SecIdentityRef. 
 */
OSStatus SecIdentityCopySystemIdentity(
   CFStringRef domain,          
   SecIdentityRef *idRef,
   CFStringRef *actualDomain) /* optional */
	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*!
	@function	SecIdentitySetSystemIdentity
	@abstract	Assign the supplied SecIdentityRef to the specified
				domain.
	@param		domain Identifies the domain to which the specified 
				SecIdentityRef will be assigned.
	@param		idRef (optional) The identity to be assigned to the specified 
				domain. Pass NULL to delete a possible entry for the specified
				domain; in this case, it is not an error if no identity
				exists for the specified domain. 
    @result		A result code.  See "Security Error Codes" (SecBase.h).
	@discussion	The caller must be running as root.
*/
OSStatus SecIdentitySetSystemIdentity(
   CFStringRef domain,     
   SecIdentityRef idRef)
	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);


/*
 * Defined system identity domains.
 */

/*!
	@const kSecIdentityDomainDefault The system-wide default identity.
 */
extern const CFStringRef kSecIdentityDomainDefault __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

/*!
	@const kSecIdentityDomainKerberosKDC Kerberos KDC identity.
*/
extern const CFStringRef kSecIdentityDomainKerberosKDC __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);

#if defined(__cplusplus)
}
#endif

#endif /* !_SECURITY_SECIDENTITY_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	/*!
	25	@header SecIdentity
	26	The functions provided in SecIdentity implement a convenient way to match private keys with certificates.
	27	*/
	28
	29	#ifndef _SECURITY_SECIDENTITY_H_
	30	#define _SECURITY_SECIDENTITY_H_
	31
	32	#include <CoreFoundation/CFBase.h>
	33	#include <CoreFoundation/CFArray.h>
	34	#include <Security/SecBase.h>
	35	#include <Security/cssmtype.h>
	36	#include <AvailabilityMacros.h>
	37
	38	#if defined(__cplusplus)
	39	extern "C" {
	40	#endif
	41
	42	/*!
	43	@function SecIdentityGetTypeID
	44	@abstract Returns the type identifier of SecIdentity instances.
	45	@result The CFTypeID of SecIdentity instances.
	46	*/
	47	CFTypeID SecIdentityGetTypeID(void)
	48	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
	49
	50	/*!
	51	@function SecIdentityCreateWithCertificate
	52	@abstract Creates a new identity reference for the given certificate, assuming the associated private key is in one of the specified keychains.
	53	@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.
	54	@param certificateRef A certificate reference.
	55	@param identityRef On return, an identity reference. You are responsible for releasing this reference by calling the CFRelease function.
	56	@result A result code. See "Security Error Codes" (SecBase.h).
	57	*/
	58	OSStatus SecIdentityCreateWithCertificate(
	59	CFTypeRef keychainOrArray,
	60	SecCertificateRef certificateRef,
	61	SecIdentityRef *identityRef)
	62	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
	63
	64	/*!
	65	@function SecIdentityCopyCertificate
	66	@abstract Returns a reference to a certificate for the given identity reference.
67	@param identityRef An identity reference.
68	@param certificateRef On return, a reference to the found certificate. You are responsible for releasing this reference by calling the CFRelease function.
69	@result A result code. See "Security Error Codes" (SecBase.h).
70	*/
71	OSStatus SecIdentityCopyCertificate(
72	SecIdentityRef identityRef,
73	SecCertificateRef *certificateRef)
74	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
75
76	/*!
77	@function SecIdentityCopyPrivateKey
78	@abstract Returns the private key associated with an identity.
79	@param identityRef An identity reference.
80	@param privateKeyRef On return, a reference to the private key for the given identity. You are responsible for releasing this reference by calling the CFRelease function.
81	@result A result code. See "Security Error Codes" (SecBase.h).
82	*/
83	OSStatus SecIdentityCopyPrivateKey(
84	SecIdentityRef identityRef,
85	SecKeyRef *privateKeyRef)
86	__OSX_AVAILABLE_STARTING(__MAC_10_3, __IPHONE_2_0);
87
88	/*!
89	@function SecIdentityCopyPreference
90	@abstract Returns the preferred identity for the specified name and key usage, optionally limiting the result to an identity issued by a certificate whose subject is one of the distinguished names in validIssuers. If a preferred identity does not exist, NULL is returned.
91	@param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies the service requiring an identity.
92	@param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to ignore this parameter.
93	@param validIssuers (optional) An array of CFDataRef instances whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames (SecureTransport.h). Pass NULL if any issuer is allowed.
94	@param identity On return, a reference to the preferred identity, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.
95	@result A result code. See "Security Error Codes" (SecBase.h).
96	@discussion This API is deprecated in 10.7. Please use the SecIdentityCopyPreferred API instead.
97	*/
98	OSStatus SecIdentityCopyPreference(CFStringRef name, CSSM_KEYUSE keyUsage, CFArrayRef validIssuers, SecIdentityRef *identity)
99	DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
100
101	/*!
102	@function SecIdentityCopyPreferred
103	@abstract Returns the preferred identity for the specified name and key usage, optionally limiting the result to an identity issued by a certificate whose subject is one of the distinguished names in validIssuers. If a preferred identity does not exist, NULL is returned.
104	@param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies the service requiring an identity.
105	@param keyUsage A CFArrayRef value, containing items defined in SecItem.h Pass NULL to ignore this parameter. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
106	@param validIssuers (optional) An array of CFDataRef instances whose contents are the subject names of allowable issuers, as returned by a call to SSLCopyDistinguishedNames (SecureTransport.h). Pass NULL if any issuer is allowed.
107	@param identity On return, a reference to the preferred identity, or NULL if none was found. You are responsible for releasing this reference by calling the CFRelease function.
108	@result An identity or NULL. if the preferred identity has not been set. Your code should then typically perform a search for possible identities using the SecItem APIs.
109	@discussion If a preferred identity has not been set for the supplied name, the returned identity reference will be NULL. Your code should then perform a search for possible identities, using the SecItemCopyMatching API.
110	*/
111	SecIdentityRef SecIdentityCopyPreferred(CFStringRef name, CFArrayRef keyUsage, CFArrayRef validIssuers)
112	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
113
114	/*!
115	@function SecIdentitySetPreference
116	@abstract Sets the preferred identity for the specified name and key usage.
117	@param identity A reference to the identity which will be preferred.
118	@param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
119	@param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to specify any key usage.
120	@result A result code. See "Security Error Codes" (SecBase.h).
121	@discussion This API is deprecated in 10.7. Please use the SecIdentitySetPreferred API instead.
122	*/
123	OSStatus SecIdentitySetPreference(SecIdentityRef identity, CFStringRef name, CSSM_KEYUSE keyUsage)
124	DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
125
126	/*!
127	@function SecIdentitySetPreferred
128	@abstract Sets the preferred identity for the specified name and key usage.
129	@param identity A reference to the identity which will be preferred. If NULL is passed, any existing preference for the specified name is cleared instead.
130	@param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
131	@param keyUsage A CFArrayRef value, containing items defined in SecItem.h Pass NULL to specify any key usage. (kSecAttrCanEncrypt, kSecAttrCanDecrypt, kSecAttrCanDerive, kSecAttrCanSign, kSecAttrCanVerify, kSecAttrCanWrap, kSecAttrCanUnwrap)
132	@result A result code. See "Security Error Codes" (SecBase.h).
133	*/
134	OSStatus SecIdentitySetPreferred(SecIdentityRef identity, CFStringRef name, CFArrayRef keyUsage)
135	__OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
136
137	/*!
138	@function SecIdentityCopySystemIdentity
139	@abstract Obtain the system-wide SecIdentityRef associated with
140	a specified domain.
141	@param domain Identifies the SecIdentityRef to be obtained, typically
142	in the form "com.apple.subdomain...".
143	@param idRef On return, the system SecIdentityRef assicated with
144	the specified domain. Caller must CFRelease this when
145	finished with it.
146	@param actualDomain (optional) The actual domain name of the
147	the returned identity is returned here. This
148	may be different from the requested domain.
149	@result A result code. See "Security Error Codes" (SecBase.h).
150	@discussion If no system SecIdentityRef exists for the specified
151	domain, a domain-specific alternate may be returned
152	instead, typically (but not exclusively) the
153	kSecIdentityDomainDefault SecIdentityRef.
154	*/
155	OSStatus SecIdentityCopySystemIdentity(
156	CFStringRef domain,
157	SecIdentityRef *idRef,
158	CFStringRef actualDomain) / optional */
159	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
160
161	/*!
162	@function SecIdentitySetSystemIdentity
163	@abstract Assign the supplied SecIdentityRef to the specified
164	domain.
165	@param domain Identifies the domain to which the specified
166	SecIdentityRef will be assigned.
167	@param idRef (optional) The identity to be assigned to the specified
168	domain. Pass NULL to delete a possible entry for the specified
169	domain; in this case, it is not an error if no identity
170	exists for the specified domain.
171	@result A result code. See "Security Error Codes" (SecBase.h).
172	@discussion The caller must be running as root.
173	*/
174	OSStatus SecIdentitySetSystemIdentity(
175	CFStringRef domain,
176	SecIdentityRef idRef)
177	__OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
178
179
180	/*
181	* Defined system identity domains.
182	*/
183
184	/*!
185	@const kSecIdentityDomainDefault The system-wide default identity.
186	*/
187	extern const CFStringRef kSecIdentityDomainDefault __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
188
189	/*!
190	@const kSecIdentityDomainKerberosKDC Kerberos KDC identity.
191	*/
192	extern const CFStringRef kSecIdentityDomainKerberosKDC __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
193
194	#if defined(__cplusplus)
195	}
196	#endif
197
198	#endif /* !_SECURITY_SECIDENTITY_H_ */