libsecurity_keychain/lib/SecIdentityPriv.h

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