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     @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.
 111     @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.
 112 */
 113 __nullable
 114 SecIdentityRef SecIdentityCopyPreferred(CFStringRef name, CFArrayRef __nullable keyUsage, CFArrayRef __nullable validIssuers)
 115         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 116
 117 /*!
 118     @function SecIdentitySetPreference
 119     @abstract Sets the preferred identity for the specified name and key usage.
 120     @param identity A reference to the identity which will be preferred.
 121     @param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
 122     @param keyUsage A CSSM_KEYUSE key usage value, as defined in cssmtype.h. Pass 0 to specify any key usage.
 123     @result A result code. See "Security Error Codes" (SecBase.h).
 124         @discussion This API is deprecated in 10.7. Please use the SecIdentitySetPreferred API instead.
 125 */
 126 OSStatus SecIdentitySetPreference(SecIdentityRef identity, CFStringRef name, CSSM_KEYUSE keyUsage)
 127         DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 128
 129 /*!
 130     @function SecIdentitySetPreferred
 131     @abstract Sets the preferred identity for the specified name and key usage.
 132     @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.
 133     @param name A string containing a URI, RFC822 email address, DNS hostname, or other name which uniquely identifies a service requiring this identity.
 134     @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)
 135     @result A result code. See "Security Error Codes" (SecBase.h).
 136 */
 137 OSStatus SecIdentitySetPreferred(SecIdentityRef __nullable identity, CFStringRef name, CFArrayRef __nullable keyUsage)
 138         __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 139
 140 /*!
 141         @function       SecIdentityCopySystemIdentity
 142         @abstract       Obtain the system-wide SecIdentityRef associated with
 143                                 a specified domain.
 144         @param          domain  Identifies the SecIdentityRef to be obtained, typically
 145                                                 in the form "com.apple.subdomain...".
 146         @param          idRef   On return, the system SecIdentityRef assicated with
 147                                                 the specified domain. Caller must CFRelease this when
 148                                                 finished with it.
 149         @param          actualDomain (optional) The actual domain name of the
 150                                                 the returned identity is returned here. This
 151                                                 may be different from the requested domain.
 152     @result             A result code.  See "Security Error Codes" (SecBase.h).
 153         @discussion     If no system SecIdentityRef exists for the specified
 154                                 domain, a domain-specific alternate may be returned
 155                                 instead, typically (but not exclusively) the
 156                                 kSecIdentityDomainDefault SecIdentityRef.
 157  */
 158 OSStatus SecIdentityCopySystemIdentity(
 159    CFStringRef domain,
 160    SecIdentityRef * __nonnull CF_RETURNS_RETAINED idRef,
 161    CFStringRef * __nullable CF_RETURNS_RETAINED actualDomain) /* optional */
 162         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 163
 164 /*!
 165         @function       SecIdentitySetSystemIdentity
 166         @abstract       Assign the supplied SecIdentityRef to the specified
 167                                 domain.
 168         @param          domain Identifies the domain to which the specified
 169                                 SecIdentityRef will be assigned.
 170         @param          idRef (optional) The identity to be assigned to the specified
 171                                 domain. Pass NULL to delete a possible entry for the specified
 172                                 domain; in this case, it is not an error if no identity
 173                                 exists for the specified domain.
 174     @result             A result code.  See "Security Error Codes" (SecBase.h).
 175         @discussion     The caller must be running as root.
 176 */
 177 OSStatus SecIdentitySetSystemIdentity(
 178    CFStringRef domain,
 179    SecIdentityRef __nullable idRef)
 180         __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 181
 182 /*
 183  * Defined system identity domains.
 184  */
 185
 186 /*!
 187         @const kSecIdentityDomainDefault The system-wide default identity.
 188  */
 189 extern const CFStringRef kSecIdentityDomainDefault __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 190
 191 /*!
 192         @const kSecIdentityDomainKerberosKDC Kerberos KDC identity.
 193 */
 194 extern const CFStringRef kSecIdentityDomainKerberosKDC __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
 195
 196 CF_IMPLICIT_BRIDGING_DISABLED
 197 CF_ASSUME_NONNULL_END
 198
 199 #if defined(__cplusplus)
 200 }
 201 #endif
 202
 203 #endif /* !_SECURITY_SECIDENTITY_H_ */