keychain/SecIdentityPriv.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 SecIdentityPriv
  26     The functions provided in SecIdentityPriv.h implement a convenient way to
  27     match private keys with certificates.
  28 */
  29
  30 #ifndef _SECURITY_SECIDENTITYPRIV_H_
  31 #define _SECURITY_SECIDENTITYPRIV_H_
  32
  33 #include <Security/SecBase.h>
  34 #include <Security/SecBasePriv.h>
  35 #include <CoreFoundation/CFBase.h>
  36
  37 __BEGIN_DECLS
  38
  39 /*! @function SecIdentityCreate
  40     @abstract create a new identity object from the provided certificate and its associated private key.
  41     @param allocator CFAllocator to allocate the identity object. Pass NULL to use the default allocator.
  42     @param certificate A certificate reference.
  43     @param privateKey A private key reference.
  44     @result An identity reference.
  45 */
  46 SecIdentityRef SecIdentityCreate(
  47      CFAllocatorRef allocator,
  48      SecCertificateRef certificate,
  49      SecKeyRef privateKey)
  50     __SEC_MAC_AND_IOS_UNKNOWN;
  51     //__OSX_AVAILABLE_STARTING(__MAC_10_3, __SEC_IPHONE_UNKNOWN);
  52
  53 #if SEC_OS_OSX
  54 /*!
  55     @function SecIdentityCompare
  56     @abstract Compares two SecIdentityRef instances for equality.
  57     @param identity1 An identity reference.
  58     @param identity2 An identity reference.
  59     @param compareOptions A value containing option flags. Currently there are no compare options, so 0 should be passed for this parameter.
  60     @result An enumerated value of type CFComparisonResult. See CFBase.h.
  61     @discussion Two identities are considered equal if they contain identical certificate and private key components.
  62     @deprecated in Mac OS X 10.5 and later; the CFEqual function should be used instead (CFBase.h).
  63  */
  64 CFComparisonResult SecIdentityCompare(
  65     SecIdentityRef identity1,
  66     SecIdentityRef identity2,
  67     CFOptionFlags compareOptions)
  68      DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
  69
  70 /*!
  71     @function SecIdentityFindPreferenceItem
  72     @abstract Returns an identity preference item, given an identity string.
  73     @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.
  74     @param idString A string containing a URI, hostname, or email (RFC822) address.
  75     @param itemRef On return, a reference to the keychain item which was found. The caller is responsible for releasing this reference.
  76     @result A result code.  See "Security Error Codes" (SecBase.h).
  77     @discussion An identity preference item maps a particular identity to a string, such as a URI or email address. It specifies that this identity should be preferred in transactions which match the provided string.
  78     @deprecated in Mac OS X 10.7 and later; use SecIdentityCopyPreferred() instead (SecIdentity.h)
  79
  80      WARNING: This function is based on an implementation detail and will go away
  81      in a future release; its use should be avoided at all costs. It does not
  82      provide a way to find a preference item based on key usage, and it can only
  83      find preferences which are stored as keychain items, so it may fail to find
  84      the item you expect. Please use the public API functions to manipulate
  85      identity preferences.
  86 */
  87 OSStatus SecIdentityFindPreferenceItem(
  88      CFTypeRef keychainOrArray,
  89      CFStringRef idString,
  90      SecKeychainItemRef *itemRef)
  91      DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
  92
  93 /*!
  94     @function SecIdentityAddPreferenceItem
  95     @abstract Adds a new identity preference item to the specified keychain.
  96     @param keychainRef A reference to the keychain in which to store the preference item. Pass NULL to specify the user's default keychain.
  97     @param identityRef An identity reference.
  98     @param idString A string containing a URI, hostname, or email (RFC822) address.
  99     @param itemRef On return, a reference to the new keychain item. The caller is responsible for releasing this reference. Pass NULL if the reference is not needed.
 100     @result A result code.  See "Security Error Codes" (SecBase.h).
 101     @discussion An identity preference item maps a particular identity to a string, such as a URI or email address. It specifies that this identity should be preferred in transactions which match the provided string.
 102     @deprecated in Mac OS X 10.5; use SecIdentitySetPreference() instead (SecIdentity.h).
 103 */
 104 OSStatus SecIdentityAddPreferenceItem(
 105      SecKeychainRef keychainRef,
 106      SecIdentityRef identityRef,
 107      CFStringRef idString,
 108      SecKeychainItemRef *itemRef)
 109      DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
 110
 111 /*!
 112     @function SecIdentityUpdatePreferenceItem
 113     @abstract Given an existing identity preference keychain item, update it with the provided identity.
 114     @param itemRef An identity preference keychain item, as returned by SecIdentityFindPreferenceItem or SecIdentityAddPreferenceItem.
 115     @param identityRef An identity reference.
 116     @result A result code.  See "Security Error Codes" (SecBase.h).
 117     @discussion This function is used to update an existing preference item when a different identity is preferred.
 118     @deprecated in Mac OS X 10.5; use SecIdentitySetPreference() instead (SecIdentity.h).
 119 */
 120 OSStatus SecIdentityUpdatePreferenceItem(
 121      SecKeychainItemRef itemRef,
 122      SecIdentityRef identityRef)
 123      DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
 124
 125 /*!
 126     @function SecIdentityCopyFromPreferenceItem
 127     @abstract Given an existing identity preference keychain item, obtain a SecIdentityRef for the identity it specifies.
 128     @param itemRef An identity preference keychain item, as returned by SecIdentityFindPreferenceItem or SecIdentityAddPreferenceItem.
 129     @param identityRef On return, an identity reference. The caller is responsible for releasing this reference.
 130     @result A result code.  See "Security Error Codes" (SecBase.h).
 131     @discussion This function is used to obtain a SecIdentityRef from an existing preference item.
 132     @deprecated in Mac OS X 10.5; use SecIdentityCopyPreference() instead (SecIdentity.h).
 133 */
 134 OSStatus SecIdentityCopyFromPreferenceItem(
 135      SecKeychainItemRef itemRef,
 136      SecIdentityRef *identityRef)
 137      DEPRECATED_IN_MAC_OS_X_VERSION_10_5_AND_LATER;
 138
 139 /*!
 140     @function ConvertArrayToKeyUsage
 141     @abstract Given an array of key usages defined in SecItem.h return the equivalent CSSM_KEYUSE
 142     @param usage An CFArrayRef containing CFTypeRefs defined in SecItem.h
 143           kSecAttrCanEncrypt,
 144           kSecAttrCanDecrypt,
 145           kSecAttrCanDerive,
 146           kSecAttrCanSign,
 147           kSecAttrCanVerify,
 148           kSecAttrCanWrap,
 149           kSecAttrCanUnwrap
 150           If the CFArrayRef is NULL then the CSSM_KEYUSAGE will be CSSM_KEYUSE_ANY
 151     @result A CSSM_KEYUSE.  Derived from the passed in Array
 152 */
 153 CSSM_KEYUSE ConvertArrayToKeyUsage(CFArrayRef usage)
 154   __SEC_MAC_ONLY_UNKNOWN;
 155 #endif // SEC_OS_OSX
 156
 157 __END_DECLS
 158
 159 #endif /* _SECURITY_SECIDENTITYPRIV_H_ */