1/* 2 * Copyright (c) 2002-2010 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 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) 39extern "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*/ 47CFTypeID 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*/ 58OSStatus 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*/ 71OSStatus 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*/ 83OSStatus 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*/ 98OSStatus 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*/ 111SecIdentityRef 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*/ 123OSStatus 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*/ 134OSStatus 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 */ 155OSStatus 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*/ 174OSStatus 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 */ 187extern const CFStringRef kSecIdentityDomainDefault __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 188 189/*! 190 @const kSecIdentityDomainKerberosKDC Kerberos KDC identity. 191*/ 192extern 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_ */ 199