keychain/SecIdentity.h

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