SecIdentity.h
1 /* 2 * Copyright (c) 2002-2011,2012-2013,2016-2021 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. Note: in versions of macOS prior to 11.3, identity preferences are shared between processes running as the same user. Starting in 11.3, URI names are considered per-application preferences. An identity preference for a URI name may not be found if the calling application is different from the one which set the preference with SecIdentitySetPreferred. 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 @discussion Note: in versions of macOS prior to 11.3, identity preferences are shared between processes running as the same user. Starting in 11.3, URI names are considered per-application preferences. An identity preference for a URI name will be scoped to the application which created it, such that a subsequent call to SecIdentityCopyPreferred will only return it for that same application. 148 */ 149 OSStatus SecIdentitySetPreferred(SecIdentityRef __nullable identity, CFStringRef name, CFArrayRef __nullable keyUsage) 150 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA); 151 152 /*! 153 @function SecIdentityCopySystemIdentity 154 @abstract Obtain the system-wide SecIdentityRef associated with 155 a specified domain. 156 @param domain Identifies the SecIdentityRef to be obtained, typically 157 in the form "com.apple.subdomain...". 158 @param idRef On return, the system SecIdentityRef assicated with 159 the specified domain. Caller must CFRelease this when 160 finished with it. 161 @param actualDomain (optional) The actual domain name of the 162 the returned identity is returned here. This 163 may be different from the requested domain. 164 @result A result code. See "Security Error Codes" (SecBase.h). 165 @discussion If no system SecIdentityRef exists for the specified 166 domain, a domain-specific alternate may be returned 167 instead, typically (but not exclusively) the 168 kSecIdentityDomainDefault SecIdentityRef. 169 */ 170 OSStatus SecIdentityCopySystemIdentity( 171 CFStringRef domain, 172 SecIdentityRef * __nonnull CF_RETURNS_RETAINED idRef, 173 CFStringRef * __nullable CF_RETURNS_RETAINED actualDomain) /* optional */ 174 __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 175 176 /*! 177 @function SecIdentitySetSystemIdentity 178 @abstract Assign the supplied SecIdentityRef to the specified 179 domain. 180 @param domain Identifies the domain to which the specified 181 SecIdentityRef will be assigned. 182 @param idRef (optional) The identity to be assigned to the specified 183 domain. Pass NULL to delete a possible entry for the specified 184 domain; in this case, it is not an error if no identity 185 exists for the specified domain. 186 @result A result code. See "Security Error Codes" (SecBase.h). 187 @discussion The caller must be running as root. 188 */ 189 OSStatus SecIdentitySetSystemIdentity( 190 CFStringRef domain, 191 SecIdentityRef __nullable idRef) 192 __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 193 194 /* 195 * Defined system identity domains. 196 */ 197 198 /*! 199 @const kSecIdentityDomainDefault The system-wide default identity. 200 */ 201 extern const CFStringRef kSecIdentityDomainDefault __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 202 203 /*! 204 @const kSecIdentityDomainKerberosKDC Kerberos KDC identity. 205 */ 206 extern const CFStringRef kSecIdentityDomainKerberosKDC __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 207 208 #endif // SEC_OS_OSX 209 210 CF_IMPLICIT_BRIDGING_DISABLED 211 CF_ASSUME_NONNULL_END 212 213 __END_DECLS 214 215 #endif /* !_SECURITY_SECIDENTITY_H_ */