Keychain/SecKeychainItem.h

   1 /*
   2  * Copyright (c) 2000-2002 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18 /*!
  19         @header SecKeychainItem
  20         SecKeychainItem implements an item which may be stored in a SecKeychain, with publicly
  21         visible attributes and encrypted data.  The access to the data of an item is protected
  22         using strong cryptographic algorithms.
  23 */
  24
  25 #ifndef _SECURITY_SECKEYCHAINITEM_H_
  26 #define _SECURITY_SECKEYCHAINITEM_H_
  27
  28 #include <Security/SecBase.h>
  29 #include <Security/cssmapple.h>
  30
  31 #if defined(__cplusplus)
  32 extern "C" {
  33 #endif
  34
  35 /*!
  36         @typedef SecItemClass
  37         @abstract Represents a keychain item's class.
  38 */
  39 typedef FourCharCode    SecItemClass;
  40
  41 /*!
  42         @enum ItemClassConstants
  43         @abstract Specifies a keychain item's class code.
  44         @constant kSecInternetPasswordItemClass Indicates that the item is an internet password.
  45         @constant kSecGenericPasswordItemClass Indicates that the item is a generic password.
  46         @constant kSecAppleSharePasswordItemClass Indicates that the item is an AppleShare password.
  47         @constant kSecCertificateItemClass Indicates that the item is a digital certificate.
  48         @discussion The SecItemClass enumeration defines constants your application can use to specify the type of the keychain item you wish to create, dispose, add, delete, update, copy, or locate. You can also use these constants with the tag constant SecItemAttr.
  49 */
  50 enum
  51 {
  52     kSecInternetPasswordItemClass       = 'inet',
  53     kSecGenericPasswordItemClass        = 'genp',
  54     kSecAppleSharePasswordItemClass     = 'ashp',
  55     kSecCertificateItemClass            = CSSM_DL_DB_RECORD_X509_CERTIFICATE,
  56 };
  57
  58 /*!
  59         @typedef SecItemAttr
  60         @abstract Represents a keychain item's attributes.
  61
  62 */
  63 typedef FourCharCode SecItemAttr;
  64
  65 /*!
  66         @enum ItemAttributeConstants
  67         @abstract Specifies keychain item attributes.
  68         @constant kSecCreationDateItemAttr Identifies the creation date attribute. You use this tag to set or get a value of type UInt32 that indicates the date the item was created.
  69         @constant kSecModDateItemAttr Identifies the modification date attribute. You use this tag to set or get a value of type UInt32 that indicates the last time the item was updated.
  70         @constant kSecDescriptionItemAttr Identifies the description attribute. You use this tag to set or get a value of type string that represents a user-visible string describing this particular kind of item (e.g. "disk image password").
  71         @constant kSecCommentItemAttr Identifies the comment attribute. You use this tag to set or get a value of type string that represents a user-editable string containing comments for this item.
  72         @constant kSecCreatorItemAttr Identifies the creator attribute. You use this tag to set or get a value that represents the itemÕs creator.
  73         @constant kSecTypeItemAttr Identifies the type attribute. You use this tag to set or get a value that represents the itemÕs type.
  74         @constant kSecScriptCodeItemAttr Identifies the script code attribute. You use this tag to set or get a value of type ScriptCode that represents the script code for all strings. (Note: use of this attribute is deprecated; string attributes should be stored in UTF-8 encoding.)
  75         @constant kSecLabelItemAttr Identifies the label attribute. You use this tag to set or get a value of type string that represents a user-editable string containing the label for this item.
  76         @constant kSecInvisibleItemAttr Identifies the invisible attribute. You use this tag to set or get a value of type Boolean that indicates whether the item is invisible.
  77         @constant kSecNegativeItemAttr Identifies the negative attribute. You use this tag to set or get a value of type Boolean that indicates whether there is a valid password associated with this keychain item. This is useful if your application doesn't want a password for some particular service to be stored in the keychain, but prefers that it always be entered by the user. The item (typically invisible and with zero-length data) acts as a placeholder to say Òdon't use me.Ó
  78         @constant kSecCustomIconItemAttr Identifies the custom icon attribute. You use this tag to set or get a value of type Boolean that indicates whether the item has an application-specific icon. To do this, you must also set the attribute value identified by the tag kSecTypeItemAttr to a file type for which there is a corresponding icon in the desktop database, and set the attribute value identified by the tag kSecCreatorItemAttr to an appropriate application creator type. If a custom icon corresponding to the item's type and creator can be found in the desktop database, it will be displayed by Keychain Access. Otherwise, default icons are used.
  79         @constant kSecAccountItemAttr Identifies the account attribute. You use this tag to set or get a string that represents the user account. It also applies to generic and AppleShare passwords.
  80         @constant kSecServiceItemAttr Identifies the service attribute. You use this tag to set or get a string that represents the service associated with this item (e.g. "iTools"). This is unique to generic password attributes.
  81         @constant kSecGenericItemAttr Identifies the generic attribute. You use this tag to set or get a value of untyped bytes that represents a user-defined attribute.  This is unique to generic password attributes.
  82         @constant kSecSecurityDomainItemAttr Identifies the security domain attribute. You use this tag to set or get a value that represents the Internet security domain. This is unique to Internet password attributes.
  83         @constant kSecServerItemAttr Identifies the server attribute. You use this tag to set or get a value of type string that represents the Internet serverÕs domain name or IP address. This is unique to Internet password attributes.
  84         @constant kSecAuthenticationTypeItemAttr Identifies the authentication type attribute. You use this tag to set or get a value of type SecAuthenticationType that represents the Internet authentication scheme. This is unique to Internet password attributes.
  85         @constant kSecPortItemAttr Identifies the port attribute. You use this tag to set or get a value of type UInt32 that represents the Internet port number. This is unique to Internet password attributes.
  86         @constant kSecPathItemAttr Identifies the path attribute. You use this tag to set or get a value  that represents the path. This is unique to Internet password attributes.
  87         @constant kSecVolumeItemAttr Identifies the volume attribute. You use this tag to set or get a value that represents the AppleShare volume. This is unique to AppleShare password attributes.
  88         @constant kSecAddressItemAttr Identifies the address attribute. You use this tag to set or get a value of type string that represents the AppleTalk zone name, or the IP or domain name that represents the server address. This is unique to AppleShare password attributes.
  89         @constant kSecSignatureItemAttr Identifies the server signature attribute. You use this tag to set or get a value of type SecAFPServerSignature that represents the server signature block. This is unique to AppleShare password attributes.
  90         @constant kSecProtocolItemAttr Identifies the protocol attribute. You use this tag to set or get a value of type SecProtocolType that represents the Internet protocol. This is unique to AppleShare and Internet password attributes.
  91         @constant kSecCertificateType Indicates a CSSM_CERT_TYPE type.
  92         @constant kSecCertificateEncoding Indicates a CSSM_CERT_ENCODING type.
  93         @constant kSecCrlType Indicates a CSSM_CRL_TYPE type.
  94         @constant kSecCrlEncoding Indicates a CSSM_CRL_ENCODING type.
  95         @constant kSecAlias Indicates an alias.
  96         @discussion To obtain information about a certificate, use the CDSA Certificate Library (CL) API. To obtain information about a key, use the SecKeyGetCSSMKey function and the CDSA Cryptographic Service Provider (CSP) API.
  97 */
  98 enum
  99 {
 100     kSecCreationDateItemAttr            = 'cdat',
 101     kSecModDateItemAttr                         = 'mdat',
 102     kSecDescriptionItemAttr                     = 'desc',
 103     kSecCommentItemAttr                         = 'icmt',
 104     kSecCreatorItemAttr                         = 'crtr',
 105     kSecTypeItemAttr                            = 'type',
 106     kSecScriptCodeItemAttr                      = 'scrp',
 107     kSecLabelItemAttr                           = 'labl',
 108     kSecInvisibleItemAttr                       = 'invi',
 109     kSecNegativeItemAttr                        = 'nega',
 110     kSecCustomIconItemAttr                      = 'cusi',
 111     kSecAccountItemAttr                         = 'acct',
 112     kSecServiceItemAttr                         = 'svce',
 113     kSecGenericItemAttr                         = 'gena',
 114     kSecSecurityDomainItemAttr          = 'sdmn',
 115     kSecServerItemAttr                          = 'srvr',
 116     kSecAuthenticationTypeItemAttr      = 'atyp',
 117     kSecPortItemAttr                            = 'port',
 118     kSecPathItemAttr                            = 'path',
 119     kSecVolumeItemAttr                          = 'vlme',
 120     kSecAddressItemAttr                         = 'addr',
 121     kSecSignatureItemAttr                       = 'ssig',
 122     kSecProtocolItemAttr                        = 'ptcl',
 123         kSecCertificateType                             = 'ctyp',
 124         kSecCertificateEncoding                 = 'cenc',
 125         kSecCrlType                                             = 'crtp',
 126         kSecCrlEncoding                                 = 'crnc',
 127         kSecAlias                                               = 'alis'
 128 };
 129
 130 /*!
 131         @typedef SecAFPServerSignature
 132         @abstract Represents a 16-byte Apple File Protocol server signature block.
 133 */
 134 typedef UInt8   SecAFPServerSignature[16];
 135
 136 /*!
 137         @typedef SecPublicKeyHash
 138         @abstract Represents a 20-byte public key hash.
 139 */
 140 typedef UInt8   SecPublicKeyHash[20];
 141
 142 #pragma mark ÑÑÑÑ Keychain Item Management ÑÑÑÑ
 143 /*!
 144         @function SecKeychainItemGetTypeID
 145         @abstract Returns the type identifier of SecKeychainItem instances.
 146         @result The CFTypeID of SecKeychainItem instances.
 147 */
 148 CFTypeID SecKeychainItemGetTypeID(void);
 149
 150 /*!
 151         @function SecKeychainItemModifyAttributesAndData
 152         @abstract Updates an existing keychain item after changing its attributes or data.
 153         @param itemRef A reference to the keychain item to modify.
 154         @param attrList The list of attributes to set.
 155         @param length The length of the buffer pointed to by data.
 156         @param data Pointer to a buffer containing the data to store.
 157     @result A result code.  See "Security Error Codes" (SecBase.h).
 158         @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 noErr.
 159 */
 160 OSStatus SecKeychainItemModifyAttributesAndData(SecKeychainItemRef itemRef, const SecKeychainAttributeList *attrList, UInt32 length, const void *data);
 161
 162 /*!
 163         @function SecKeychainItemCreateFromContent
 164         @abstract Creates a new keychain item from the supplied parameters.
 165         @param itemClass A constant identifying the class of item to create.
 166         @param attrList The list of attributes of the item to create.
 167         @param length The length of the buffer pointed to by data.
 168         @param data A pointer to a buffer containing the data to store.
 169         @param initialAccess A reference to the access for this keychain item.
 170     @param keychainRef A reference to the keychain in which to add the item.
 171         @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.
 172     @result A result code.  See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if not enough valid parameters are supplied, or memFullErr (-108) if there is not enough memory in the current heap zone to create the object.
 173 */
 174 OSStatus SecKeychainItemCreateFromContent(SecItemClass itemClass, SecKeychainAttributeList *attrList,
 175                 UInt32 length, const void *data, SecKeychainRef keychainRef,
 176                 SecAccessRef initialAccess, SecKeychainItemRef *itemRef);
 177
 178 /*!
 179         @function SecKeychainItemModifyContent
 180         @abstract Updates an existing keychain item after changing its attributes or data. This call should only be used in conjunction with SecKeychainItemCopyContent().
 181         @param itemRef A reference to the keychain item to modify.
 182         @param attrList The list of attributes to set.
 183         @param length The length of the buffer pointed to by data.
 184         @param data A pointer to a buffer containing the data to store.
 185     @result A result code.  See "Security Error Codes" (SecBase.h).
 186 */
 187 OSStatus SecKeychainItemModifyContent(SecKeychainItemRef itemRef, const SecKeychainAttributeList *attrList, UInt32 length, const void *data);
 188
 189 /*!
 190         @function SecKeychainItemCopyContent
 191         @abstract Copies the data and/or attributes stored in the given keychain item. It is recommended that you use SecKeychainItemCopyAttributesAndData(). You must call SecKeychainItemFreeContent when you no longer need the attributes and data. If you want to modify the attributes returned here, use SecKeychainModifyContent().
 192         @param itemRef A reference to the keychain item to modify.
 193         @param itemClass The item's class. You should pass NULL if it is not required.
 194         @param attrList The list of attributes to get in this item on input, on output the attributes are filled in. You must call SecKeychainItemFreeContent when you no longer need the attributes.
 195         @param length On return, the length of the buffer pointed to by outData.
 196         @param outData On return, a pointer to a buffer containing the data in this item. You must call SecKeychainItemFreeContent when you no longer need the data.
 197     @result A result code.  See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if not enough valid parameters are supplied.
 198 */
 199 OSStatus SecKeychainItemCopyContent(SecKeychainItemRef itemRef, SecItemClass *itemClass, SecKeychainAttributeList *attrList, UInt32 *length, void **outData);
 200
 201 /*!
 202         @function SecKeychainItemFreeContent
 203         @abstract Releases the memory used by the keychain attribute list and the keychain data retrieved in a call to SecKeychainItemCopyContent.
 204         @param attrList A pointer to the attribute list to release.
 205     @param data A pointer to the data buffer to release.
 206 */
 207 OSStatus SecKeychainItemFreeContent(SecKeychainAttributeList *attrList, void *data);
 208
 209 /*!
 210         @function SecKeychainItemCopyAttributesAndData
 211         @abstract Copies the data and/or attributes stored in the given keychain item. You must call SecKeychainItemFreeAttributesAndData() when you no longer need the attributes and data. If you want to modify the attributes returned here, use SecKeychainModifyAttributesAndData().
 212         @param itemRef A reference to the keychain item to copy.
 213         @param info List of tags of attributes to retrieve.
 214         @param itemClass The item's class. You should pass NULL if not required.
 215         @param attrList on output, an attribute list with the attributes specified by info. You must call SecKeychainItemFreeAttributesAndData() when you no longer need this list.
 216         @param length on output the actual length of the data.
 217         @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.
 218     @result A result code.  See "Security Error Codes" (SecBase.h). In addition, paramErr (-50) may be returned if not enough valid parameters are supplied.
 219 */
 220 OSStatus SecKeychainItemCopyAttributesAndData(SecKeychainItemRef itemRef, SecKeychainAttributeInfo *info, SecItemClass *itemClass, SecKeychainAttributeList **attrList, UInt32 *length, void **outData);
 221
 222 /*!
 223         @function SecKeychainItemFreeAttributesAndData
 224         @abstract Releases the memory used by the keychain attribute list and the keychain data retrieved in a call to SecKeychainItemCopyAttributesAndData.
 225         @param attrList A pointer to the attribute list to release.
 226     @param data A pointer to the data buffer to release.
 227     @result A result code.  See "Security Error Codes" (SecBase.h).
 228 */
 229 OSStatus SecKeychainItemFreeAttributesAndData(SecKeychainAttributeList *attrList, void *data);
 230
 231 /*!
 232         @function SecKeychainItemDelete
 233         @abstract Deletes a keychain item from the default keychain's permanent data store.
 234         @param itemRef A keychain item reference of the item to delete.
 235     @result A result code.  See "Security Error Codes" (SecBase.h).
 236         @discussion  If itemRef has not previously been added to the keychain,  SecKeychainItemDelete does nothing and returns noErr. IMPORTANT: SecKeychainItemDelete does not dispose the memory occupied by the item reference itself; use the CFRelease function when you are completely finished with an item.
 237 */
 238 OSStatus SecKeychainItemDelete(SecKeychainItemRef itemRef);
 239
 240 /*!
 241         @function SecKeychainItemCopyKeychain
 242         @abstract Copies an existing keychain reference from a keychain item.
 243         @param itemRef A keychain item reference of the item to update.
 244         @param keychainRef On return, a pointer to a keychain reference.  Release this by calling CFRelease function.
 245     @result A result code.  See "Security Error Codes" (SecBase.h).
 246 */
 247 OSStatus SecKeychainItemCopyKeychain(SecKeychainItemRef itemRef, SecKeychainRef *keychainRef);
 248
 249 /*!
 250         @function SecKeychainItemCreateCopy
 251         @abstract Copies a keychain item.
 252         @param itemRef A reference to the keychain item to copy.
 253         @param destKeychainRef A reference to the keychain in which to insert the copied keychain item.
 254         @param initialAccess The initial access for the copied keychain item.
 255         @param itemCopy On return, a pointer to a copy of the keychain item referenced by itemRef.
 256     @result A result code.  See "Security Error Codes" (SecBase.h).
 257 */
 258 OSStatus SecKeychainItemCreateCopy(SecKeychainItemRef itemRef, SecKeychainRef destKeychainRef,
 259         SecAccessRef initialAccess, SecKeychainItemRef *itemCopy);
 260
 261
 262 #pragma mark ÑÑÑÑ CSSM Bridge Functions ÑÑÑÑ
 263 /*!
 264     @function SecKeychainItemGetDLDBHandle
 265     @abstract Returns the CSSM_DL_DB_HANDLE for a given keychain item reference.
 266     @param keyItemRef A keychain item reference.
 267     @param dldbHandle On return, a CSSM_DL_DB_HANDLE for the keychain database containing the given item. The handle is valid until the keychain reference is released.
 268     @result A result code.  See "Security Error Codes" (SecBase.h).
 269 */
 270 OSStatus SecKeychainItemGetDLDBHandle(SecKeychainItemRef keyItemRef, CSSM_DL_DB_HANDLE *dldbHandle);
 271
 272 /*!
 273         @function SecKeychainItemGetUniqueRecordID
 274         @abstract Returns a CSSM_DB_UNIQUE_RECORD for the given keychain item reference.
 275         @param itemRef A keychain item reference.
 276     @param uniqueRecordID On return, a pointer to a CSSM_DB_UNIQUE_RECORD structure for the given item.  The unique record is valid until the item reference is released.
 277     @result A result code.  See "Security Error Codes" (SecBase.h).
 278 */
 279 OSStatus SecKeychainItemGetUniqueRecordID(SecKeychainItemRef itemRef, const CSSM_DB_UNIQUE_RECORD **uniqueRecordID);
 280
 281 #pragma mark ÑÑÑÑ Keychain Item Access Management ÑÑÑÑ
 282 /*!
 283         @function SecKeychainItemCopyAccess
 284         @abstract Copies the access of a given keychain item.
 285         @param itemRef A reference to a keychain item.
 286     @param access On return, a pointer to the keychain item's access.
 287     @result A result code.  See "Security Error Codes" (SecBase.h).
 288 */
 289 OSStatus SecKeychainItemCopyAccess(SecKeychainItemRef itemRef, SecAccessRef *access);
 290
 291 /*!
 292         @function SecKeychainItemSetAccess
 293         @abstract Sets the access of a given keychain item.
 294         @param itemRef A reference to a keychain item.
 295     @param access A reference to an access to replace the keychain item's current access.
 296     @result A result code.  See "Security Error Codes" (SecBase.h).
 297 */
 298 OSStatus SecKeychainItemSetAccess(SecKeychainItemRef itemRef, SecAccessRef access);
 299
 300 #if defined(__cplusplus)
 301 }
 302 #endif
 303
 304 #endif /* !_SECURITY_SECKEYCHAINITEM_H_ */