OSX/libsecurity_keychain/lib/SecKeychainItemPriv.h

   1 /*
   2  * Copyright (c) 2003-2008,2011,2013 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_SECKEYCHAINITEMPRIV_H_
  25 #define _SECURITY_SECKEYCHAINITEMPRIV_H_
  26
  27 #include <CoreFoundation/CFData.h>
  28 #include <Security/SecBase.h>
  29 #include <Security/SecKeychainItem.h>
  30
  31 #if defined(__cplusplus)
  32 extern "C" {
  33 #endif
  34
  35 /* Private keychain item attributes */
  36 enum
  37 {
  38         kSecClassItemAttr            = 'clas',                       /* Item class (KCItemClass) */
  39         kSecProtectedDataItemAttr    = 'prot',                       /* Item's data is protected (encrypted) (Boolean) */
  40 };
  41
  42 /* Temporary: CRL attributes */
  43 enum
  44 {
  45         kSecCrlEncodingItemAttr                  = 'cren',
  46         kSecThisUpdateItemAttr                   = 'crtu',
  47         kSecNextUpdateItemAttr                   = 'crnu',
  48         kSecUriItemAttr                                  = 'curi',      // URI from which it came
  49         kSecCrlNumberItemAttr                    = 'crnm',
  50         kSecDeltaCrlNumberItemAttr               = 'dlcr'
  51 };
  52
  53 /* Unlock referral item attributes */
  54 enum {
  55         kSecReferralTypeAttr                     = 'rtyp',      // type of referral
  56         kSecReferralDbNameAttr                   = 'rnam',      // database name
  57         kSecReferralDbGuidAttr                   = 'rgui',      // module GUID
  58         kSecReferralDbSSIDAttr                   = 'rssi',      // module subservice ID
  59         kSecReferralDbSSTypeAttr                 = 'rsty',      // subservice type
  60         kSecReferralDbNetnameAttr                = 'rnnm',      // network name (blob)
  61         kSecReferralKeyLabelAttr                 = 'rlbl',      // key's Label
  62         kSecReferralKeyAppTagAttr                = 'rkat'       // key's ApplicationTag
  63 };
  64
  65
  66 /* Extended Attribute record attributes */
  67 enum {
  68         kExtendedAttrRecordTypeAttr             = 'eart',
  69         kExtendedAttrItemIDAttr                 = 'eaii',
  70         kExtendedAttrAttributeNameAttr  = 'eaan',
  71         kExtendedAttrAttributeValueAttr = 'eaav'
  72         /* also kSecModDateItemAttr from SecKeychainItem.h */
  73 };
  74
  75 OSStatus SecKeychainItemCreateNew(SecItemClass itemClass, OSType itemCreator, UInt32 length, const void* data, SecKeychainItemRef* itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  76
  77 OSStatus SecKeychainItemGetData(SecKeychainItemRef itemRef, UInt32 maxLength, void* data, UInt32* actualLength) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  78
  79 OSStatus SecKeychainItemGetAttribute(SecKeychainItemRef itemRef, SecKeychainAttribute* attribute, UInt32* actualLength) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  80
  81 OSStatus SecKeychainItemSetAttribute(SecKeychainItemRef itemRef, SecKeychainAttribute* attribute) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  82
  83 OSStatus SecKeychainItemAdd(SecKeychainItemRef itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  84
  85 OSStatus SecKeychainItemAddNoUI(SecKeychainRef keychainRef, SecKeychainItemRef itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  86
  87 OSStatus SecKeychainItemUpdate(SecKeychainItemRef itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  88
  89 OSStatus SecKeychainItemSetData(SecKeychainItemRef itemRef, UInt32 length, const void* data) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  90
  91 OSStatus SecKeychainItemFindFirst(SecKeychainRef keychainRef, const SecKeychainAttributeList *attrList, SecKeychainSearchRef *searchRef, SecKeychainItemRef *itemRef) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
  92
  93 /*!
  94         @function SecKeychainItemCopyRecordIdentifier
  95         @abstract Returns the record identifier for a keychain item
  96         @param itemRef The item for which the localID is to be returned
  97         @param recordIdentifier The returned recordIdentifier
  98     @result A result code. See "Security Error Codes" (SecBase.h).
  99 */
 100
 101 OSStatus SecKeychainItemCopyRecordIdentifier(SecKeychainItemRef itemRef, CFDataRef *recordIdentifier) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 102
 103 /*!
 104         @function SecKeychainItemCopyFromRecordIdentifier
 105         @abstract Returns a SecKeychainItemRef, given a keychain and a recordIdentifier
 106         @param keychain The keychain in which the item is located
 107         @param itemRef The item for which the localID is to be returned
 108         @param recordIdentifier The returned localID
 109     @result A result code. See "Security Error Codes" (SecBase.h).
 110 */
 111
 112 OSStatus SecKeychainItemCopyFromRecordIdentifier(SecKeychainRef keychain,
 113                                                                                                  SecKeychainItemRef *itemRef,
 114                                                                                                  CFDataRef recordIdentifier) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 115
 116 /*!
 117         @function SecKeychainItemCopyAttributesAndEncryptedData
 118         @abstract Copies the data and/or attributes stored in the given keychain item. You must call SecKeychainItemFreeAttributesAndData()
 119                           when you no longer need the attributes and data. If you want to modify the attributes returned here, use SecKeychainModifyAttributesAndData().
 120                           The data is not decrypted.
 121         @param itemRef A reference to the keychain item to copy.
 122         @param info List of tags of attributes to retrieve.
 123         @param itemClass The item's class. You should pass NULL if not required.
 124         @param attrList on output, an attribute list with the attributes specified by info. You must call SecKeychainItemFreeAttributesAndData() when you no longer need this list.
 125         @param length on output the actual length of the data.
 126         @param outData Pointer to a buffer containing the data in this item. Pass NULL if not required. You must call SecKeychainItemFreeAttributesAndData() when you no longer need the data.
 127     @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if not enough valid parameters are supplied.
 128 */
 129 OSStatus SecKeychainItemCopyAttributesAndEncryptedData(SecKeychainItemRef itemRef, SecKeychainAttributeInfo *info,
 130                                                                                                            SecItemClass *itemClass, SecKeychainAttributeList **attrList,
 131                                                                                                            UInt32 *length, void **outData) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 132
 133 /*!
 134         @function SecKeychainItemModifyEncryptedData
 135         @abstract Updates an existing keychain item after changing its data.
 136                           The data is not re-encrypted.
 137         @param itemRef A reference to the keychain item to modify.
 138         @param length The length of the buffer pointed to by data.
 139         @param data Pointer to a buffer containing the data to store.
 140     @result A result code.  See "Security Error Codes" (SecBase.h).
 141         @discussion The keychain item is written to the keychain's permanent data store. If the keychain item has not previously been added to a keychain, a call to the SecKeychainItemModifyContent function does nothing and returns errSecSuccess.
 142 */
 143 OSStatus SecKeychainItemModifyEncryptedData(SecKeychainItemRef itemRef, UInt32 length, const void *data) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 144
 145 /*!
 146         @function SecKeychainItemCreateFromEncryptedContent
 147         @abstract Creates a new keychain item from the supplied parameters. The data is not re-encrypted.
 148         @param itemClass A constant identifying the class of item to create.
 149         @param length The length of the buffer pointed to by data.
 150         @param data A pointer to a buffer containing the data to store.
 151     @param keychainRef A reference to the keychain in which to add the item.
 152         @param initialAccess A reference to the access for this keychain item.
 153         @param itemRef On return, a pointer to a reference to the newly created keychain item (optional). When the item reference is no longer required, call CFRelease to deallocate memory occupied by the item.
 154         @param itemLocalID On return, the item's local ID data (optional). When the local ID data reference is no longer required, call CFRelease to deallocate memory occupied by the reference.
 155     @result A result code.  See "Security Error Codes" (SecBase.h). In addition, errSecParam (-50) may be returned if not enough valid parameters are supplied, or errSecAllocate (-108) if there is not enough memory in the current heap zone to create the object.
 156 */
 157 OSStatus SecKeychainItemCreateFromEncryptedContent(SecItemClass itemClass, UInt32 length, const void *data,
 158                                                                                                    SecKeychainRef keychainRef, SecAccessRef initialAccess,
 159                                                                                                    SecKeychainItemRef *itemRef, CFDataRef *itemLocalID) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 160
 161  /*!
 162     @function SecKeychainItemSetAccessWithPassword
 163     @abstract Sets the access of a given keychain item.
 164     @param itemRef A reference to a keychain item.
 165     @param accessRef A reference to an access to replace the keychain item's current access.
 166     @param passwordLength An unsigned 32-bit integer representing the length of the password buffer.
 167     @param password A buffer containing the password for the keychain. if this password is incorrect, this call might fail---it will not prompt the user.
 168     @result A result code. See "Security Error Codes" (SecBase.h).
 169 */
 170  OSStatus SecKeychainItemSetAccessWithPassword(SecKeychainItemRef itemRef, SecAccessRef accessRef, UInt32 passwordLength, const void * password) API_UNAVAILABLE(ios, watchos, tvos, bridgeos, macCatalyst);
 171 #if defined(__cplusplus)
 172 }
 173 #endif
 174
 175 #endif /* !_SECURITY_SECKEYCHAINITEMPRIV_H_ */