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