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