Security/libsecurity_keychain/lib/SecIdentity.h

   1 /*
   2  * Copyright (c) 2002-2011 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)
  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_ */