| Framework | Security/Security.h |
| Declared in | SecACL.h SecAccess.h SecBase.h SecImportExport.h SecItem.h SecKey.h SecKeychain.h SecKeychainItem.h SecKeychainSearch.h SecTrustedApplication.h cssmapple.h cssmtype.h |
Keychain Services is a programming interface that enables you to find, add, modify, and delete keychain items.
For this interface, keychain items are found or defined by a CFDictionary of key-value pairs. Each key in the dictionary identifies one attribute of the keychain item, or a search option. For example, you can use the kSecClass key to specify that the keychain item is an Internet password, that it has a specific creation date, that it is for the HTTPS protocol, and that only the first match found should be returned. The keys that can be used for this purpose and the possible values for each key are listed in the “Keychain Services Constants” section.
See the discussion section of the SecItemCopyMatching function for information about how to construct a keychain-item search dictionary.
SecKeychainGetVersion
SecKeychainGetTypeID
SecKeychainItemGetTypeID
SecKeychainSearchGetTypeID
SecAccessGetTypeID
SecACLGetTypeID
SecTrustedApplicationGetTypeID
SecKeychainOpen
SecKeychainSetDefault
SecKeychainCopyDefault
SecKeychainGetStatus
SecKeychainGetPath
SecKeychainSetSettings
SecKeychainCopySettings
SecKeychainAddInternetPassword
SecKeychainFindInternetPassword
SecKeychainAddGenericPassword
SecKeychainFindGenericPassword
SecKeychainSetSearchList
SecKeychainCopySearchList
SecKeychainSearchCreateFromAttributes
SecKeychainSearchCopyNext
SecKeychainItemCreateFromContent
SecKeychainItemCreateCopy
SecKeychainItemCreatePersistentReference
SecKeychainItemCopyFromPersistentReference
SecKeychainItemDelete
SecKeychainItemCopyAttributesAndData
SecKeychainItemModifyAttributesAndData
SecKeychainItemFreeAttributesAndData
SecKeychainItemCopyContent
SecKeychainItemModifyContent
SecKeychainItemFreeContent
SecKeychainAttributeInfoForItemID
SecKeychainFreeAttributeInfo
SecKeychainItemCopyKeychain
SecKeychainItemSetAccess
SecKeychainItemCopyAccess
SecACLCreateFromSimpleContents
SecACLRemove
SecACLCopySimpleContents
SecACLSetSimpleContents
SecACLGetAuthorizations
SecACLSetAuthorizations
SecKeychainGetPreferenceDomain
SecKeychainSetPreferenceDomain
SecKeychainCopyDomainDefault
SecKeychainSetDomainDefault
SecKeychainCopyDomainSearchList
SecKeychainSetDomainSearchList
SecKeychainGetCSPHandle
SecKeychainGetDLDBHandle
SecKeychainItemGetDLDBHandle
SecKeychainItemGetUniqueRecordID
Retrieves all the access control list entries of a given access object.
OSStatus SecAccessCopyACLList ( SecAccessRef accessRef, CFArrayRef *aclList );
The access object from which to retrieve the information.
On return, a pointer to a reference of a newly created CFArray of SecACLRef instances. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
An access object can have any number of access control list (ACL) entries for specific operations or sets of operations. To retrieve ACL entries for specific operations, use the SecAccessCopySelectedACLList function.
SecAccess.h
Retrieves selected access control lists from a given access object.
OSStatus SecAccessCopySelectedACLList ( SecAccessRef accessRef, CSSM_ACL_AUTHORIZATION_TAG action, CFArrayRef *aclList );
The access object from which to retrieve the information.
An access control list authorization tag; the function returns only those access control list entries that apply to the operation indicated by this tag.
On return, a pointer to the selected access control lists. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
An access object can have any number of access control list (ACL) entries for specific operations or sets of operations. To retrieve all the ACL entries for an access object, use the SecAccessCopyACLList function.
SecAccess.h
Creates a new access object.
OSStatus SecAccessCreate ( CFStringRef descriptor, CFArrayRef trustedlist, SecAccessRef *accessRef );
A CFString object representing the name of the keychain item as it should appear in security dialogs. Note that this is not necessarily the same name as appears for that item in the Keychain Access application.
A reference to an array of trusted application objects (values of type SecTrustedApplicationRef) specifying which applications should be allowed to access the item without triggering confirmation dialogs. Use the SecTrustedApplicationCreateFromPath function to create trusted application objects. If you pass NULL for this parameter, the access control list is automatically set to the application creating the item. To set no applications, pass a CFArrayRef with no elements.
On return, points to the new access object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Each protected keychain item (such as a password or private key) has an associated access object. The access object contains access control list (ACL) entries, which specify trusted applications and the operations for which those operations are trusted. When an application attempts to access a keychain item for a particular purpose (such as to sign a document), the system determines whether that application is trusted to access the item for that purpose. If it is trusted, then the application is given access and no user confirmation is required. If the application is not trusted, but there is an ACL entry for that operation, then the user is asked to confirm whether the application should be given access. If there is no ACL entry for that operation, then access is denied and it is up to the calling application to try something else or to notify the user.
This function creates an access object with three ACL entries: The first, referred to as owner access, determines who can modify the access object itself. By default, there are no trusted applications for owner access; the user is always prompted for permission if someone tries to change access controls. The second is for operations considered safe, such as encrypting data. This ACL entry applies to all applications. The third ACL entry is for operations that should be restricted, such as decrypting, signing, deriving keys, and exporting keys. This ACL entry applies to the trusted applications listed in the trustedlist parameter.
To retrieve all the ACL entries of an access object, use the SecAccessCopyACLList function. To retrieve specific ACL entries, use the SecAccessCopySelectedACLList function. To create a new ACL entry and add it to an access object, use SecACLCreateFromSimpleContents. To modify an existing ACL entry, use SecACLSetSimpleContents. To modify the operations for which an ACL entry is used, call the SecACLSetAuthorizations function.
Because an ACL object is always associated with an access object, when you modify an ACL entry, you are modifying the access object as well. Therefore, there is no need for a separate function to write a modified ACL object back into the access object.
SecAccess.hCreates a new access object using the owner and access control list you provide.
OSStatus SecAccessCreateFromOwnerAndACL ( const CSSM_ACL_OWNER_PROTOTYPE *owner, uint32 aclCount, const CSSM_ACL_ENTRY_INFO *acls, SecAccessRef *accessRef );
A pointer to a CSSM access control list owner.
An unsigned 32-bit integer representing the number of items in the access control list.
A pointer to the CSSM access control list.
On return, points to the new access object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function creates an access object from CSSM structures. You can use this function to create an access object for use with other Certificate, Key, and Trust API functions if you want to use CSSM to create the access control list. CSSM allows more complex access controls than you can construct with the Certificate, Key, and Trust API. For more information about the CSSM API, see Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm).
SecAccess.hRetrieves the owner and the access control list of a given access object.
OSStatus SecAccessGetOwnerAndACL ( SecAccessRef accessRef, CSSM_ACL_OWNER_PROTOTYPE_PTR *owner, uint32 *aclCount, CSSM_ACL_ENTRY_INFO_PTR *acls );
An access object from which to retrieve the owner and access control list.
On return, a pointer to a CSSM access control list owner.
On return, a pointer to an unsigned 32-bit integer representing the number of items in the access control list.
On return, a pointer to the CSSM access control list.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function returns CSSM structures for use with CSSM API functions.
SecAccess.hReturns the unique identifier of the opaque type to which a SecAccessRef object belongs.
CFTypeID SecAccessGetTypeID ( void );
A value that identifies the opaque type of a SecAccessRef object.
This function returns a value that uniquely identifies the opaque type of a SecAccessRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.
SecAccess.h
Returns the application list, description, and CSSM prompt selector for a given access control list entry.
OSStatus SecACLCopySimpleContents ( SecACLRef acl, CFArrayRef *applicationList, CFStringRef *description, CSSM_ACL_KEYCHAIN_PROMPT_SELECTOR *promptSelector );
An ACL object that identifies the access control list entry from which you want information.
On return, points to an array of SecTrustedApplication instances identifying applications that are allowed access to the keychain item without user confirmation. If this parameter returns NULL, then any application can use this item. If this parameter returns a valid pointer but the array is empty, then there are no trusted applications. You must call the CFRelease function to release this object when you are finished using it.
On return, the name of the keychain item that appears in the dialog box when the user is prompted for permission to use the item. Note that this name is not necessarily the same as the one displayed for the item by the Keychain Access application. You must call the CFRelease function to release this object when you are finished using it.
On return, points to the prompt selector flag for the given access control list entry. If the CSSM_ACL_KEYCHAIN_PROMPT_REQUIRE_PASSPHRASE bit is set, the user is prompted for the keychain password each time a non-trusted application attempts to access this item, even if the keychain is already unlocked.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
An access control list entry applies to a specific use or set of uses for a specific keychain item. The ACL object includes a list of trusted applications (see SecTrustedApplicationCreateFromPath), the name of the keychain item as it appears in user prompts, the prompt selector flag, and a list of one or more operations to which this ACL object applies. Use the SecACLGetAuthorizations function to get the list of operations for an ACL object.
SecACL.h
Creates a new access control list entry from the application list, description, and prompt selector provided and adds it to an item’s access object.
OSStatus SecACLCreateFromSimpleContents ( SecAccessRef access, CFArrayRef applicationList, CFStringRef description, const CSSM_ACL_KEYCHAIN_PROMPT_SELECTOR *promptSelector, SecACLRef *newAcl );
The access object to which to add the information.
An array of trusted application objects (that is, SecTrustedApplication instances) identifying applications that are allowed access to the keychain item without user confirmation. Use the SecTrustedApplicationCreateFromPath function to create trusted application objects. If you set this parameter to NULL, then any application can use this item. If you pass an empty array, then there are no trusted applications. You must call the CFRelease function to release this object when you are finished using it.
The human readable name to be used to refer to this item when the user is prompted.
A pointer to a prompt selector. If you set the CSSM_ACL_KEYCHAIN_PROMPT_REQUIRE_PASSPHRASE bit, the user is prompted for the keychain password each time a non-trusted application attempts to access this item, even if the keychain is already unlocked.
On return, points to an access control list object, which is a reference to the new access control list entry.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
The ACL object returned by this function is a reference to an access control list (ACL) entry. The ACL entry includes a list of trusted applications (see SecTrustedApplicationCreateFromPath), the name of the keychain item as it appears in user prompts, the prompt selector flag, and a list of one or more operations to which this ACL entry applies. By default, a new ACL entry applies to all operations (the CSSM authorization tag is set to CSSM_ACL_AUTHORIZATION_ANY). Use the SecACLSetAuthorizations function to set the list of operations for an ACL object.
The system allows exactly one owner ACL entry in each access object. The SecACLCreateFromSimpleContents function fails if you attempt to add a second owner ACL. To change owner access controls, use the SecAccessCopySelectedACLList function to find the owner ACL (that is, the only ACL with a CSSM authorization tag of CSSM_ACL_AUTHORIZATION_CHANGE_ACL) and the SecACLSetSimpleContents function to change it as needed.
SecACL.h
Retrieves the CSSM authorization tags of a given access control list entry.
OSStatus SecACLGetAuthorizations ( SecACLRef acl, CSSM_ACL_AUTHORIZATION_TAG *tags, uint32 *tagCount );
An ACL object that identifies the access control list entry from which you wish to retrieve the authorization tags.
A pointer to an array of CSSM authorization tags. You must allocate this array before calling the function. On return, this array contains the authorization tags of the specified ACL entry.
On input, points to the number of elements in the array you passed in the tags parameter. On return, points to the number of tags actually returned or, in the case of an overflow, the number of tags required.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
An ACL object includes a list of trusted applications (see SecTrustedApplicationCreateFromPath), the name of the keychain item as it appears in user prompts, the prompt selector flag, and a list of one or more operations to which this ACL object applies. Use this function to retrieve the list of operations for an ACL object. Use the SecACLCopySimpleContents function to retrieve the other information.
The SecACLGetAuthorizations function returns an error if there are more tags to return than the number of elements you allocated in the tags array. A 20-element array should suffice for most purposes; however, you can test for the errSecBufferTooSmall error and increase the size of the array before calling the function again if necessary. Alternatively, you can call the function with a tag count of 0, read the value returned in the tagCount parameter, and then call the function again using that value.
SecACL.hReturns the unique identifier of the opaque type to which a SecACLRef object belongs.
CFTypeID SecACLGetTypeID ( void );
A value that identifies the opaque type of a SecACLRef object.
This function returns a value that uniquely identifies the opaque type of a SecACLRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.
SecACL.hRemoves the specified access control list entry.
OSStatus SecACLRemove ( SecACLRef aclRef );
An ACL object that identifies the access control list entry to remove.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
The system allows exactly one owner ACL entry in each access object. The SecACLRemove function fails if you attempt to remove the owner ACL entry. To change owner access controls, use the SecAccessCopySelectedACLList function to find the owner ACL (that is, the only ACL with a CSSM authorization tag of CSSM_ACL_AUTHORIZATION_CHANGE_ACL) and the SecACLSetSimpleContents function to change it as needed.
SecACL.h
Sets the CSSM authorization tags for a given access control list entry.
OSStatus SecACLSetAuthorizations ( SecACLRef acl, CSSM_ACL_AUTHORIZATION_TAG *tags, uint32 tagCount );
An ACL object that identifies the access control list entry for which you wish to set authorization tags.
An array of CSSM authorization tags.
The number of tags in the CSSM authorization tag array.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
An ACL object includes a list of trusted applications (see SecTrustedApplicationCreateFromPath), the name of the keychain item as it appears in user prompts, the prompt selector flag, and a list of one or more operations to which this ACL object applies. Use this function to set a list of operations for an ACL object, or set the CSSM_ACL_AUTHORIZATION_ANY tag to allow all operations. Use the SecACLSetSimpleContents function to set the other information.
Because an ACL object is always associated with an access object, when you modify an ACL entry, you are modifying the access object as well. There is no need for a separate function to write a modified ACL object back into the access object.
SecACL.h
Sets the application list, description, and prompt selector for a given access control list entry.
OSStatus SecACLSetSimpleContents ( SecACLRef acl, CFArrayRef applicationList, CFStringRef description, const CSSM_ACL_KEYCHAIN_PROMPT_SELECTOR *promptSelector );
An ACL object that identifies the access control list entry.
An array of trusted application objects (that is, SecTrustedApplication instances) identifying applications that are allowed access to the keychain item without user confirmation. Use the SecTrustedApplicationCreateFromPath function to create trusted application objects. If you set this parameter to NULL, then any application can use this item. If you pass an empty array, then there are no trusted applications. You must call the CFRelease function to release this object when you are finished using it.
The name of the keychain item that appears in the dialog box when the user is prompted for permission to use the item. Note that this name is not necessarily the same as the one displayed for the item by the Keychain Access application. You must call the CFRelease function to release this object when you are finished using it.
The prompt selector flag for the given access control list entry. Set the CSSM_ACL_KEYCHAIN_PROMPT_REQUIRE_PASSPHRASE bit to have the user prompted for the keychain password each time a non-trusted application attempts to access this item, even if the keychain is already unlocked.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Because an ACL object is always associated with an access object, when you modify an ACL entry, you are modifying the access object as well. There is no need for a separate function to write a modified ACL object back into the access object.
Use the SecACLGetAuthorizations function to get the list of operations for an ACL object.
SecACL.hReturns a string explaining the meaning of a security result code.
CFStringRef SecCopyErrorMessageString( OSStatus status, void *reserved );
A result code of type OSStatus or CSSM_RETURN, returned by a security or CSSM function.
Reserved for future use. Pass NULL for this parameter.
A human-readable string describing the result, or NULL if no string is available for the specified result code. You must call the CFRelease function to release this object when you are finished using it.
SecBase.hAdds one or more items to a keychain.
OSStatus SecItemAdd ( CFDictionaryRef attributes, CFTypeRef *result );
A dictionary containing an item class key-value pair (“Keychain Item Class Keys and Values”) and optional attribute key-value pairs (“Attribute Item Keys and Values”) specifying the item's attribute values.
On return, a reference to the newly added items. The exact type of the result is based on the values supplied in attributes, as discussed below. Pass NULL if this result is not required.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
You specify attributes defining an item by adding key-value pairs to the attributes dictionary. To add multiple items to a keychain at once use the kSecUseItemList key (see section “Item List Key”) with an array of items as its value. This is currently only supported for non-password items.
If you want the new keychain item to be shared among multiple applications, include the kSecAttrAccessGroup key in the attributes dictionary. The value of this key must be the name of a keychain access group to which all of the programs that will share this item belong.
When you use Xcode to create an application, Xcode adds an application-identifier entitlement to the application bundle. Keychain Services uses this entitlement to grant the application access to its own keychain items. You can also add a keychain-access-groups entitlement to the application and, in the entitlement property list file, specify an array of keychain access groups to which the application belongs. The property list file can have any name you like (for example, keychain-access-groups.plist). The Xcode build variable CODE_SIGN_ENTITLEMENTS should contain the SRCROOT relative path to the entitlement property list file. The property list file itself should be a dictionary with a top-level key called keychain-access-groups whose value is an array of strings. If you add such a property-list file to the application bundle, then the access group corresponding to the application-identifier entitlement is treated as the last element in the access groups array. If you do not include the kSecAttrAccessGroup key in the attributes dictionary when you call the SecItemAdd function to add an item to the keychain, the function uses the first access group in the array by default. If there is no kSecAttrAccessGroup key in the attributes dictionary and there is no keychain-access-groups entitlement in the application bundle, then the access group of a newly created item is the value of the application-identifier entitlement.
For example, a development group in Apple might have the ID:
659823F3DC53.com.apple
and the application identifiers of their two applications might be:
659823F3DC53.com.apple.oneappleapp and
659823F3DC53.com.apple.twoappleapp
If both applications add a keychain-access-groups entitlement with one value in the array of access groups:
659823F3DC53.com.apple.netaccount
then both applications would add new keychain items to the 659823F3DC53.com.apple.netaccount access group by default and both applications would have access to keychain items in that group. In addition, each application would still have access to its own private keychain items: OneAppleApp would have access to items in keychain access group 659823F3DC53.com.apple.oneappleapp and TwoAppleApp would have access to items in 659823F3DC53.com.apple.twoappleapp.
Return types (“Search Results Constants”) are specified as follows:
To obtain the data of the added item as an object of type CFDataRef, specify the return type key kSecReturnData with a value of kCFBooleanTrue.
To obtain all the attributes of the added item as objects of type CFDictionaryRef, specify kSecReturnAttributes with a value of kCFBooleanTrue.
To obtain a reference to the added item of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef with a value of kCFBooleanTrue. This is the default behavior if a return type is not explicitly specified.
To obtain a persistent reference to the added item (an object of type CFDataRef), specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that unlike normal references, a persistent reference may be stored on disk or passed between processes.
If more than one of these return types is specified, the result is returned as an object of type CFDictionaryRef containing all the requested data.
SecItem.hReturns one or more keychain items that match a search query.
OSStatus SecItemCopyMatching ( CFDictionaryRef query, CFTypeRef *result );
A dictionary containing an item class specification (“Keychain Item Class Keys and Values”) and optional attributes for controlling the search. See “Keychain Services Constants” for a description of currently defined search attributes.
On return, a reference to the found items. The exact type of the result is based on the search attributes supplied in the query, as discussed below.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
You specify attributes defining a search by adding key-value pairs to the query dictionary.
A typical query consists of:
The class key (“Item Class Key Constant”) and a class value constant (“Item Class Value Constants”), which specifies the class of items for which to search.
One or more attribute key-value pairs (“Attribute Item Keys and Values”), which specify the attribute data to be matched.
One or more search key-value pairs (“Search Keys”), which specify values that further refine the search.
A return-type key-value pair (“Search Results Constants”), specifying the type of results you desire.
Return types (“Search Results Constants”) are specified as follows:
To obtain a reference (of type CFDataRef) to the data of a matching item, specify kSecReturnData with a value of kCFBooleanTrue.
To obtain a dictionary (of type CFDictionaryRef) containing the attributes of a matching item, specify kSecReturnAttributes with a value of kCFBooleanTrue.
To obtain a reference (of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef) to a matching item, specify kSecReturnRef with a value of kCFBooleanTrue.
To obtain a persistent reference (of type CFDataRef) to a matching item, specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that unlike normal references, a persistent reference may be stored on disk or passed between processes.
If more than one of these return types is specified, the result is returned as a dictionary (that is, an object of type CFDictionaryRef) containing all the requested data.
By default, this function returns only the first match found. To obtain more than one matching item at a time, specify the search key kSecMatchLimit with a value greater than 1. The result will be an object of type CFArrayRef containing up to that number of matching items.
By default, this function searches for items in the keychain. To instead provide your own set of items to be filtered by this search query, specify the search key kSecMatchItemList with a value that consists of an object of type CFArrayRef referencing an array that contains items of type either SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef. The objects in the provided array must all be of the same type.
To convert from persistent item references to normal item references, specify the search key kSecMatchItemList with a value that consists of an object of type CFArrayRef referencing an array containing one or more elements of type CFDataRef (the persistent references), and a return-type key of kSecReturnRef whose value is kCFBooleanTrue. The objects in the provided array must all be of the same type.
When you use Xcode to create an application, Xcode adds an application-identifier entitlement to the application bundle. Keychain Services uses this entitlement to grant the application access to its own keychain items. You can also add a keychain-access-groups entitlement to the application and, in the entitlement property list file, specify an array of keychain access groups to which the application belongs. The property list file can have any name you like (for example, keychain-access-groups.plist). The Xcode build variable CODE_SIGN_ENTITLEMENTS should contain the SRCROOT relative path to the entitlement property list file. The property list file itself should be a dictionary with a top-level key called keychain-access-groups whose value is an array of strings. When you call the SecItemAdd function to add an item to the keychain, you can specify the access group to which that item should belong. By default, the SecItemCopyMatching function searches all the access groups to which the application belongs. However, you can add the kSecAttrAccessGroup key to the search dictionary to specify which access group to search for keychain items.
SecItem.hDeletes items that match a search query.
OSStatus SecItemDelete ( CFDictionaryRef query );
A dictionary containing an item class specification and optional attributes for controlling the search. See “Search Keys” for a description of currently defined search attributes.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
See the discussion section of the SecItemCopyMatching function for information about how to construct a search dictionary.
By default, this function deletes all items matching the specified query. You can change this behavior by specifying a key, as follows:
To delete an item identified by a transient reference, specify the kSecMatchItemList search key with a reference returned by using the kSecReturnRef return type key in a previous call to the SecItemCopyMatching or SecItemAdd functions.
To delete an item identified by a persistent reference, specify the kSecMatchItemList search key with a persistent reference returned by using the kSecReturnPersistentRef return type key to the SecItemCopyMatching or SecItemAdd functions.
If more than one of these return keys is specified, the behavior is undefined.
SecItem.hModifies items that match a search query.
OSStatus SecItemUpdate ( CFDictionaryRef query, CFDictionaryRef attributesToUpdate );
A dictionary containing an item class specification and optional attributes for controlling the search. Specify the items whose values you wish to change. See “Search Keys” for a description of currently defined search attributes.
A dictionary containing the attributes whose values should be changed, along with the new values. Only real keychain attributes are permitted in this dictionary (no "meta" attributes are allowed.) See “Attribute Item Keys and Values” for a description of currently defined value attributes.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
See the discussion section of the SecItemCopyMatching function for information about how to construct a search dictionary.
SecItem.h
Registers your keychain event callback function
OSStatus SecKeychainAddCallback ( SecKeychainCallback callbackFunction, SecKeychainEventMask eventMask, void *userContext );
A pointer to your keychain event callback function, described in SecKeychainCallback.
A bit mask indicating the keychain events of which your application wishes to be notified. Keychain Services tests this mask to determine the keychain events that you wish to receive, and passes these events in the keychainEvent parameter of your callback function.
A pointer to application-defined storage that will be passed to your callback function. Your application can use this to associate any particular call of this function with any particular call of your keychain event callback function.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
It is important to note that the current Foundation or Core Foundation run loop must be active when making this call or the callbacks are not registered. In multithreaded programs, the notifications are registered in the run loop of the thread calling SecKeychainAddCallback; therefore, delivery of notifications depends on the functioning of that thread’s run loop. If that thread terminates, or is so busy that it doesn't operate its run loop in a timely manner, notifications will be delayed, and may eventually be dropped without any notification.
For that reason, it is inadvisable for your program to depend on delivery of notifications caused by your own actions (such as depending on receiving a deletion notification before updating a UI view) unless your program is multithreaded and can take notifications on a thread different from the one generating the events.
SecKeychain.h
Adds a new generic password to a keychain.
OSStatus SecKeychainAddGenericPassword ( SecKeychainRef keychain, UInt32 serviceNameLength, const char *serviceName, UInt32 accountNameLength, const char *accountName, UInt32 passwordLength, const void *passwordData, SecKeychainItemRef *itemRef );
A reference to the keychain in which to store a generic password. Pass NULL to specify the default keychain.
The length of the serviceName character string.
A UTF-8 encoded character string representing the service name.
The length of the accountName character string.
A UTF-8 encoded character string representing the account name.
The length of the passwordData buffer.
A pointer to a buffer containing the password data to be stored in the keychain. Before calling this function, allocate enough memory for the buffer to hold the data you want to store.
On return, a pointer to a reference to the new keychain item. Pass NULL if you don’t want to obtain this object. You must allocate the memory for this pointer. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” The result code errSecNoDefaultKeychain indicates that no default keychain could be found. The result code errSecDuplicateItem indicates that you tried to add a password that already exists in the keychain. The result code errSecDataTooLarge indicates that you tried to add more data than is allowed for a structure of this type. Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function adds a new generic password to the specified keychain. Required parameters to identify the password are serviceName and accountName, which are application-defined strings. This function optionally returns a reference to the newly added item.
You can use this function to add passwords for accounts other than the Internet. For example, you might add AppleShare passwords, or passwords for your database or scheduling programs.
This function sets the initial access rights for the new keychain item so that the application creating the item is given trusted access.
This function automatically calls the function SecKeychainUnlock to display the Unlock Keychain dialog box if the keychain is currently locked.
SecKeychain.h
Adds a new Internet password to a keychain.
OSStatus SecKeychainAddInternetPassword ( SecKeychainRef keychain, UInt32 serverNameLength, const char *serverName, UInt32 securityDomainLength, const char *securityDomain, UInt32 accountNameLength, const char *accountName, UInt32 pathLength, const char *path, UInt16 port, SecProtocolType protocol, SecAuthenticationType authenticationType, UInt32 passwordLength, const void *passwordData, SecKeychainItemRef *itemRef );
A reference to the keychain in which to store an Internet password. Pass NULL to specify the user’s default keychain.
The length of the serverName character string.
A UTF-8 encoded character string representing the server name.
The length of the securityDomain character string.
A UTF-8 encoded character string representing the security domain. This parameter is optional. Pass NULL if the protocol does not require it.
The length of the accountName character string.
A UTF-8 encoded character string representing the account name.
The length of the path character string.
A UTF-8 encoded character string representing the path.
The TCP/IP port number. If no specific port number is associated with this password, pass 0.
The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values.
The authentication scheme used. See “Keychain Authentication Type Constants” for a description of possible values. Pass the constant kSecAuthenticationTypeDefault, to specify the default authentication scheme.
The length of the passwordData buffer.
A pointer to a buffer containing the password data to be stored in the keychain.
On return, a pointer to a reference to the new keychain item. Pass NULL if you don’t want to obtain this object. You must allocate the memory for this pointer. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” The result code errSecNoDefaultKeychain indicates that no default keychain could be found. The result code errSecDuplicateItem indicates that you tried to add a password that already exists in the keychain. The result code errSecDataTooLarge indicates that you tried to add more data than is allowed for a structure of this type. Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function adds a new Internet server password to the specified keychain. Required parameters to identify the password are serverName and accountName (you cannot pass NULL for both parameters). In addition, some protocols may require an optional securityDomain when authentication is requested. This function optionally returns a reference to the newly added item.
This function sets the initial access rights for the new keychain item so that the application creating the item is given trusted access.
This function automatically calls the function SecKeychainUnlock to display the Unlock Keychain dialog box if the keychain is currently locked.
SecKeychain.hObtains tags for all possible attributes of a given item class.
OSStatus SecKeychainAttributeInfoForItemID ( SecKeychainRef keychain, UInt32 itemID, SecKeychainAttributeInfo **info );
A keychain object.
The relation identifier of the item tags. An itemID is a CSSM_DB_RECORDTYPE type as defined in cssmtype.h.
On return, a pointer to the keychain attribute information. Your application should call the SecKeychainFreeAttributeInfo function to release this structure when done with it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This call returns more attributes than are supported by the old style Keychain API and passing them into older calls yields an invalid attribute error. The recommended call to retrieve the attribute values is the SecKeychainItemCopyAttributesAndData function.
SecKeychain.hRetrieves the application access of a keychain.
OSStatus SecKeychainCopyAccess ( SecKeychainRef keychain, SecAccessRef *access );
A reference to the keychain from which to copy the access object. Pass NULL to specify the default keychain.
A pointer to an access object. On return, this points to the access object of the specified keychain. See “Managing Access Objects” for information on manipulating access objects.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Although this function is available in Mac OS X v10.2, it was unimplemented before Mac OS X v10.3 and returned an unimpErr error code if called.
SecKeychain.h
Retrieves a pointer to the default keychain.
OSStatus SecKeychainCopyDefault ( SecKeychainRef *keychain );
On return, a pointer to the default keychain object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” The result code errSecNoDefaultKeychain indicates that there is no default keychain. Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hRetrieves the default keychain from a specified preference domain.
OSStatus SecKeychainCopyDomainDefault ( SecPreferencesDomain domain, SecKeychainRef *keychain );
The preference domain from which you wish to retrieve the default keychain. See “Keychain Preference Domain Constants” for possible domain values.
On return, a pointer to the keychain object of the default keychain in the specified preference domain.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
A preference domain is a set of security-related preferences, such as the default keychain and the current keychain search list. Use this function if you want to retrieve the default keychain for a specific preference domain. Use the SecKeychainCopyDefault function if you want the default keychain for the current preference domain. See the SecKeychainSetPreferenceDomain function for a discussion of current and default preference domains.
SecKeychain.hRetrieves the keychain search list for a specified preference domain.
OSStatus SecKeychainCopyDomainSearchList ( SecPreferencesDomain domain, CFArrayRef *searchList );
The preference domain from which you wish to retrieve the keychain search list. See “Keychain Preference Domain Constants” for possible domain values.
On return, a pointer to the keychain search list of the specified preference domain.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
A preference domain is a set of security-related preferences, such as the default keychain and the current keychain search list. Use this function if you want to retrieve the keychain search list for a specific preference domain. Use the SecKeychainCopySearchList function if you want the keychain search list for the current preference domain. See the SecKeychainSetPreferenceDomain function for a discussion of current and default preference domains.
SecKeychain.h
Retrieves a keychain search list.
OSStatus SecKeychainCopySearchList ( CFArrayRef *searchList );
The returned keychain search list. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.h
Obtains a keychain’s settings.
OSStatus SecKeychainCopySettings ( SecKeychainRef keychain, SecKeychainSettings *outSettings );
A reference to the keychain from which to copy its settings.
On return, a pointer to a keychain settings structure. Since this structure is versioned, you must allocate the memory for it and fill in the version of the structure before passing it to the function.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hCreates an empty keychain.
OSStatus SecKeychainCreate ( const char *pathName, UInt32 passwordLength, const void *password, Boolean promptUser, SecAccessRef initialAccess, SecKeychainRef *keychain );
A constant character string representing the POSIX path indicating where to store the keychain.
An unsigned 32-bit integer representing the length of the buffer pointed to by password. Pass 0 if the value of password is NULL and the value of promptUser is TRUE.
A pointer to the buffer containing the password which is used to protect the new keychain. The password must be in canonical UTF-8 encoding. Pass NULL if the value of passwordLength is 0 and the value of promptUser is TRUE.
A Boolean value representing whether to display a password dialog to the user. Set this value to TRUE to display a password dialog or FALSE otherwise. If you pass TRUE, any values passed for passwordLength and password are ignored, and a dialog for the user to enter a password is presented.
An access object indicating the initial access rights for the keychain. A keychain’s access rights determine which applications have permission to use the keychain. You may pass NULL for the standard access rights.
On return, a pointer to a keychain object. You must call the CFRelease function to release this object when you are finished using it. Pass NULL if you do not need the pointer to the keychain object returned.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function creates an empty keychain. The keychain, password, and initialAccess parameters are optional. If user interaction to create a keychain is posted, the newly-created keychain is automatically unlocked after creation.
The system ensures that a default keychain is created for the user at login, thus, in most cases, you do not need to call this function yourself. Users can create additional keychains, or change the default, by using the Keychain Access application. However, a missing default keychain is not recreated automatically, and you may receive an errSecNoDefaultKeychain error from other functions if a default keychain does not exist. In that case, you can use this function followed by SecKeychainSetDefault, to create a new default keychain. You can also call this function to create a private temporary keychain for your application’s use, in cases where no user interaction can occur.
SecKeychain.hDeletes one or more keychains from the default keychain search list, and removes the keychain itself if it is a file.
OSStatus SecKeychainDelete ( SecKeychainRef keychainOrArray );
A single keychain object or a reference to an array of keychains you wish to delete. To delete more than one keychain, create a CFArray of keychain references (type SecKeychainRef) and pass a reference to the array.
In Mac OS X v10.3 and later, passing NULL to this parameter returns an errSecInvalidKeychain error code. In Mac OS X v10.2, this parameter was named keychain and only took a single keychain object. Passing NULL to this parameter deleted the user’s default keychain.
A result code. See “Keychain Services Result Codes.” The result code errSecInvalidKeychain is returned if the specified keychain is invalid or if the value of the keychainOrArray parameter is invalid (NULL). Call SecCopyErrorMessageString to get a human-readable string explaining the result.
The keychain may be a file stored locally, a smart card, or retrieved from a network server using non-file-based database protocols. This function deletes the keychain only if it is a local file.
This function does not release the memory used by the keychain object; you must call the CFRelease function to release each keychain object when you are finished with it.
SecKeychain.h
Finds the first generic password based on the attributes passed.
OSStatus SecKeychainFindGenericPassword ( CFTypeRef keychainOrArray, UInt32 serviceNameLength, const char *serviceName, UInt32 accountNameLength, const char *accountName, UInt32 *passwordLength, void **passwordData, SecKeychainItemRef *itemRef );
A reference to an array of keychains to search, a single keychain, or NULL to search the user’s default keychain search list.
The length of the serviceName character string.
A UTF-8 encoded character string representing the service name.
The length of the accountName character string.
A UTF-8 encoded character string representing the account name.
On return, the length of the buffer pointed to by passwordData.
On return, a pointer to a buffer that holds the password data. Pass NULL if you want to obtain the item object but not the password data. In this case, you must also pass NULL in the passwordLength parameter. You should use the SecKeychainItemFreeContent function to free the memory pointed to by this parameter.
On return, a pointer to the item object of the generic password. Pass NULL if you don’t want to obtain this object.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function finds the first generic password item that matches the attributes you provide. Most attributes are optional; you should pass only as many as you need to narrow the search sufficiently for your application’s intended use. This function optionally returns a reference to the found item.
This function decrypts the password before returning it to you. If the calling application is not in the list of trusted applications, the user is prompted before access is allowed. If the access controls for this item do not allow decryption, the function returns the errSecAuthFailed result code.
This function automatically calls the function SecKeychainUnlock to display the Unlock Keychain dialog box if the keychain is currently locked.
SecKeychain.h
Finds the first Internet password based on the attributes passed.
OSStatus SecKeychainFindInternetPassword ( CFTypeRef keychainOrArray, UInt32 serverNameLength, const char *serverName, UInt32 securityDomainLength, const char *securityDomain, UInt32 accountNameLength, const char *accountName, UInt32 pathLength, const char *path, UInt16 port, SecProtocolType protocol, SecAuthenticationType authenticationType, UInt32 *passwordLength, void **passwordData, SecKeychainItemRef *itemRef );
A reference to an array of keychains to search, a single keychain or NULL to search the user’s default keychain search list.
The length of the serverName character string.
A UTF-8 encoded character string representing the server name.
The length of the securityDomain character string.
A UTF-8 encoded character string representing the security domain. This parameter is optional, as not all protocols require it. Pass NULL if it is not required.
The length of the accountName character string.
A UTF-8 encoded character string representing the account name.
The length of the path character string.
A UTF-8 encoded character string representing the path.
The TCP/IP port number. Pass 0 to ignore the port number.
The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values.
The authentication scheme used. See “Keychain Authentication Type Constants” for a description of possible values. Pass the constant kSecAuthenticationTypeDefault, to specify the default authentication scheme.
On return, the length of the buffer pointed to by passwordData.
On return, a pointer to a buffer containing the password data. Pass NULL if you want to obtain the item object but not the password data. In this case, you must also pass NULL in the passwordLength parameter. You should use the SecKeychainItemFreeContent function to free the memory pointed to by this parameter.
On return, a pointer to the item object of the Internet password. Pass NULL if you don’t want to obtain this object.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function finds the first Internet password item that matches the attributes you provide. This function optionally returns a reference to the found item.
This function decrypts the password before returning it to you. If the calling application is not in the list of trusted applications, the user is prompted before access is allowed. If the access controls for this item do not allow decryption, the function returns the errSecAuthFailed result code.
This function automatically calls the function SecKeychainUnlock to display the Unlock Keychain dialog box if the keychain is currently locked.
SecKeychain.h
Releases the memory acquired by calling the SecKeychainAttributeInfoForItemID function.
OSStatus SecKeychainFreeAttributeInfo ( SecKeychainAttributeInfo *info );
A pointer to the keychain attribute information to release.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hReturns the CSSM CSP handle for the given keychain object.
OSStatus SecKeychainGetCSPHandle ( SecKeychainRef keychain, CSSM_CSP_HANDLE *cspHandle );
A keychain object.
On return, a pointer to the CSSM CSP handle for the given keychain. The handle is valid until the keychain object is released.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hReturns the CSSM database handle for a given keychain object.
OSStatus SecKeychainGetDLDBHandle ( SecKeychainRef keychain, CSSM_DL_DB_HANDLE *dldbHandle );
A keychain object.
On return, a pointer to the CSSM database handle for the given keychain. The handle is valid until the keychain object is released.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hDetermines the path of a keychain.
OSStatus SecKeychainGetPath ( SecKeychainRef keychain, UInt32 *ioPathLength, char *pathName );
A reference to a keychain whose path you wish to obtain.
On input, a pointer to the size of the character string pathName. On return, the size of pathName without the zero termination.
On input, a pointer to a buffer that you have allocated. On output, the buffer contains the POSIX path of the keychain as a UTF-8 encoded string. The function returns errSecBufferTooSmall if the provided buffer is too small.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hGets the current keychain preference domain.
OSStatus SecKeychainGetPreferenceDomain ( SecPreferencesDomain *domain );
On return, a pointer to the keychain preference domain. See “Keychain Preference Domain Constants” for possible domain values.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
A preference domain is a set of security-related preferences, such as the default keychain and the current keychain search list. The default preference domain for system daemons (that is, for daemons running in the root session) is the system domain. The default preference domain for all other programs is the user domain. Use the SecKeychainSetPreferenceDomain function to change the preference domain.
SecKeychain.h
Retrieves status information of a keychain.
OSStatus SecKeychainGetStatus ( SecKeychainRef keychain, SecKeychainStatus *keychainStatus );
A keychain object of the keychain whose status you wish to determine for the user session. Pass NULL to obtain the status of the default keychain.
On return, a pointer to the status of the specified keychain. See “Keychain Status Masks” for valid status constants.
A result code. See “Keychain Services Result Codes.” The result code errSecNoSuchKeychain indicates that the specified keychain could not be found. The result code errSecInvalidKeychain indicates that the specified keychain is invalid. Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function retrieves the status of a specified keychain. You can use this function to determine if the keychain is unlocked, readable, or writable. Note that the lock status of a keychain can change at any time due to user or system activity. Because the system automatically prompts the user to unlock a keychain when necessary, you do not usually have to worry about the lock status of a keychain. If you do need to track the lock status of a keychain, use the SecKeychainAddCallback function to register for keychain notifications.
SecKeychain.hReturns the unique identifier of the opaque type to which a SecKeychainRef object belongs.
CFTypeID SecKeychainGetTypeID ( void );
A value that identifies the opaque type of a SecKeychainRef object.
This function returns a value that uniquely identifies the opaque type of a SecKeychainRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.
SecKeychain.hIndicates whether Keychain Services functions that normally display a user interaction are allowed to do so.
OSStatus SecKeychainGetUserInteractionAllowed ( Boolean *state );
A Boolean value indicating whether user interaction is permitted. If true, user interaction is allowed, and Keychain Services functions that display a user interface can do so as appropriate.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hDetermines the version of Keychain Services installed on the user’s system.
OSStatus SecKeychainGetVersion ( UInt32 *returnVers );
On return, a pointer to the version number of Keychain Services installed on the current system. See “Keychain Settings Version” for a list of values.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Your application can call the SecKeychainGetVersion function to find out which version of Keychain Services is installed on the user’s system.
SecKeychain.h
Copies the access of a given keychain item.
OSStatus SecKeychainItemCopyAccess ( SecKeychainItemRef itemRef, SecAccessRef *access );
A reference to a keychain item.
On return, points to the keychain item’s access object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Each protected keychain item (such as a password or private key) has an associated access object. The access object contains access control list (ACL) entries, which specify trusted applications and the operations for which those operations are trusted. You can use this function together with the SecKeychainItemSetAccess function to copy access controls from one keychain item to another. You can use the functions in the section “Managing Access Control List Objects” to modify the contents of an access object.
SecKeychainItem.h
Retrieves the data and/or attributes stored in the given keychain item.
OSStatus SecKeychainItemCopyAttributesAndData ( SecKeychainItemRef itemRef, SecKeychainAttributeInfo *info, SecItemClass *itemClass, SecKeychainAttributeList **attrList, UInt32 *length, void **outData );
A reference to the keychain item from which you wish to retrieve data or attributes.
A pointer to a list of tags and formats of attributes to retrieve. You can call SecKeychainAttributeInfoForItemID to obtain a list of all possible attribute tags and formats for the item's class. Pass NULL if you don’t wish to retrieve any attributes.
On return, the item’s class. Pass NULL if not required. See “Keychain Item Class Constants” for valid constants.
On return, the retrieved attributes and their values . Pass NULL if not required. You must call the function SecKeychainItemFreeAttributesAndData when you no longer need the attributes and values.
On return, the actual length of the data returned in the outData parameter.
On return, the data in this item. Pass NULL if not required. You must call the function SecKeychainItemFreeAttributesAndData when you no longer need the data.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function returns the data and attributes of a specific keychain item. You can use the SecKeychainSearchCopyNext function to search for a keychain item if you don’t already have the item’s reference object. To find and obtain data from a password keychain item, use the SecKeychainFindInternetPassword or SecKeychainFindGenericPassword function.
You should pair the SecKeychainItemCopyAttributesAndData function with the SecKeychainItemModifyAttributesAndData function, as these functions handle more attributes than are support by the old Keychain Manager and passing them into older calls yields an invalid attribute error. Use the functions SecKeychainItemModifyContent and SecKeychainItemCopyContent when dealing with older Keychain Manager functions.
If the keychain item data is encrypted, this function decrypts the data before returning it to you. If the calling application is not in the list of trusted applications, the user is prompted before access is allowed. If the access controls for this item do not allow decryption, the function returns the errSecAuthFailed result code.
SecKeychainItem.h
Copies the data and attributes stored in the given keychain item.
OSStatus SecKeychainItemCopyContent ( SecKeychainItemRef itemRef, SecItemClass *itemClass, SecKeychainAttributeList *attrList, UInt32 *length, void **outData );
A reference to the keychain item to modify.
On return, points to the item’s class. Pass NULL if it is not required. See “Keychain Item Class Constants” for valid constants.
On input, the list of attributes to get in this item; on output the attributes are filled in. Pass NULL if you don’t need to retrieve any attributes. You must call SecKeychainItemFreeContent when you no longer need the attributes and data.
On return, the length of the buffer pointed to by the outData parameter.
On return, a pointer to a buffer containing the data in this item. Pass NULL if you don’t need this data. You must call SecKeychainItemFreeContent when you no longer need the attributes and data.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function returns the data and attributes of a specific keychain item. You can use the SecKeychainSearchCopyNext function to search for a keychain item if you don’t already have the item’s reference object. To find and obtain data from a password keychain item, use the SecKeychainFindInternetPassword or SecKeychainFindGenericPassword function.
You should pair the SecKeychainItemModifyContent function with the SecKeychainItemCopyContent function when dealing with older Keychain Manager functions. The SecKeychainItemCopyAttributesAndData and SecKeychainItemModifyAttributesAndData functions handle more attributes than are supported by the old Keychain Manager; however, passing them into older calls yields an invalid attribute error.
If the keychain item data is encrypted, this function decrypts the data before returning it to you. If the calling application is not in the list of trusted applications, the user is prompted before access is allowed. If the access controls for this item do not allow decryption, the function returns the errSecAuthFailed result code.
SecKeychainItem.hProvides a keychain item reference, given a persistent reference.
OSStatus SecKeychainItemCopyFromPersistentReference( CFDataRef persistentItemRef, SecKeychainItemRef *itemRef);
A persistent reference for a keychain item.
On return, a keychain item reference for the item for which you provided a persistent reference. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
A persistent reference may be stored on disk or passed between processes. You use the SecKeychainItemCreatePersistentReference function to create a persistent reference.
SecKeychainItem.hReturns the keychain object of a given keychain item.
OSStatus SecKeychainItemCopyKeychain ( SecKeychainItemRef itemRef, SecKeychainRef *keychainRef );
A keychain item object.
On return, a pointer to a keychain object referencing the given keychain item. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychainItem.hCopies a keychain item from one keychain to another.
OSStatus SecKeychainItemCreateCopy ( SecKeychainItemRef itemRef, SecKeychainRef destKeychainRef, SecAccessRef initialAccess, SecKeychainItemRef *itemCopy );
A reference to the keychain item to copy.
A reference to the keychain in which to insert the copied keychain item. Pass NULL to specify the default keychain.
The initial access for the copied keychain item. Use the SecAccessCreate function to create an access object or the SecKeychainItemCopyAccess function to copy an access object from another keychain item. If you pass NULL for this parameter, the access defaults to the application creating the item.
On return, a pointer to a copy of the keychain item referenced by the itemRef parameter. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychainItem.h
Creates a new keychain item from the supplied parameters.
OSStatus SecKeychainItemCreateFromContent ( SecItemClass itemClass, SecKeychainAttributeList *attrList, UInt32 length, const void *data, SecKeychainRef keychainRef, SecAccessRef initialAccess, SecKeychainItemRef *itemRef );
A constant identifying the class of item to create. See “Keychain Item Class Constants” for valid constants.
A pointer to the list of attributes for the item to create.
The length of the buffer pointed to by the data parameter.
A pointer to a buffer containing the data to store.
A reference to the keychain in which to add the item. Pass NULL to specify the default keychain.
An access object for this keychain item. Use the SecAccessCreate function to create an access object or the SecKeychainItemCopyAccess function to copy an access object from another keychain item. If you pass NULL for this parameter, the access defaults to the application creating the item.
On return, a pointer to a reference to the newly created keychain item. This parameter is optional. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Each item stored in the keychain contains data (such as a certificate), which is indexed by the item’s attributes. Use this function to create a keychain item from its attributes and data. To create keychain items that hold passwords, use the SecKeychainAddInternetPassword or SecKeychainAddGenericPassword functions.
A SecKeychainItemRef object for a certificate that is stored in a keychain can be safely cast to a SecCertificateRef for use with the Certificate, Key, and Trust API.
SecKeychainItem.hCreates a persistent reference for a keychain item.
OSStatus SecKeychainItemCreatePersistentReference( SecKeychainItemRef itemRef, CFDataRef *persistentItemRef);
A keychain item reference for the item for which you want a persistent reference.
On return, a persistent reference for the keychain item. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Unlike normal references, a persistent reference may be stored on disk or passed between processes. You can convert a persistent reference into an ordinary keychain item reference (SecKeychainItemRef) by calling the SecKeychainItemCopyFromPersistentReference function.
SecKeychainItemCopyFromPersistentReferenceSecKeychainItemCreateFromContentSecKeychainSearchCopyNextSecKeychainItem.hDeletes a keychain item from the default keychain’s permanent data store.
OSStatus SecKeychainItemDelete ( SecKeychainItemRef itemRef );
A keychain item object of the item to delete. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
If the keychain item has not previously been added to the keychain, this function does nothing and returns noErr.
Do not delete a keychain item and recreate it in order to modify it; instead, use the SecKeychainItemModifyContent or SecKeychainItemModifyAttributesAndData function to modify an existing keychain item. When you delete a keychain item, you lose any access controls and trust settings added by the user or by other applications.
SecKeychainItem.h
Exports one or more certificates, keys, or identities.
OSStatus SecKeychainItemExport ( CFTypeRef keychainItemOrArray, SecExternalFormat outputFormat, SecItemImportExportFlags flags, const SecKeyImportExportParameters *keyParams, CFDataRef *exportedData );
The keychain item or items to export. You can export only the following types of keychain items: SecCertificateRef, SecKeyRef, and SecIdentityRef. If you are exporting exactly one item, you can specify a SecKeychainItemRef object. Otherwise this parameter is a CFArrayRef object containing a number of items of type SecKeychainItemRef.
The format of the external representation of the item. Set this parameter to kSecFormatUnknown to use the default for that item type. Possible values for this parameter and default values are enumerated in “Keychain Item Import/Export Formats.”
A flag indicating whether the exported item should have PEM armour. PEM armour refers to a way of expressing binary data as an ASCII string so that it can be transferred over text-only channels such as email. Set this flag to kSecItemPemArmour if you want PEM armouring.
A pointer to a structure containing a set of input parameters for the function. If no key items are being exported, these parameters are optional and you can set the keyParams parameter to NULL.
On return, points to the external representation of the keychain item or items.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function works only with keys, certificates, and identities. An identity is the combination of a certificate and its associated private key. Although public keys are commonly stored in certificates, they can be stored separately in the keychain as well; for example, when you call the SecKeyCreatePair function to create a key pair, both the public and private keys are stored in the keychain. Use the SecKeychainSearchCopyNext function to find a key or certificate. Use the SecIdentitySearchCopyNext function in the Certificate, Key, and Trust API to find an identity.
SecImportExport.h
Releases the memory used by the keychain attribute list and/or the keychain data retrieved in a call to SecKeychainItemCopyAttributesAndData.
OSStatus SecKeychainItemFreeAttributesAndData ( SecKeychainAttributeList *attrList, void *data );
A pointer to the attribute list to release. Pass NULL if there is no attribute list to release.
A pointer to the data buffer to release. Pass NULL if there is no data to release.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychainItem.h
Releases the memory used by the keychain attribute list and the keychain data retrieved in a call to the SecKeychainItemCopyContent function.
OSStatus SecKeychainItemFreeContent ( SecKeychainAttributeList *attrList, void *data );
A pointer to the attribute list to release. Pass NULL if there is no attribute list to release.
A pointer to the data buffer to release. Pass NULL if there is no data to release.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Because the SecKeychainFindInternetPassword and SecKeychainFindGenericPassword functions call the SecKeychainItemCopyContent function, you must call SecKeychainItemFreeContent to release the data buffers after calls to those functions as well.
Because the SecKeychainItemCopyContent function does not allocate buffers until they are needed, you should not call the SecKeychainItemFreeContent function unless data is actually returned to you.
SecKeychainItem.hReturns the CSSM database handle for a given keychain item object.
OSStatus SecKeychainItemGetDLDBHandle ( SecKeychainItemRef keyItemRef, CSSM_DL_DB_HANDLE *dldbHandle );
A keychain item object.
On return, a pointer to a CSSM database handle for the keychain database containing the given item. The handle is valid until the keychain item object is released.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychainItem.hReturns the unique identifier of the opaque type to which a SecKeychainItemRef object belongs.
CFTypeID SecKeychainItemGetTypeID ( void );
A value that identifies the opaque type of a SecKeychainItemRef object.
This function returns a value that uniquely identifies the opaque type of a SecKeychainItemRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.
SecKeychainItem.hReturns a CSSM unique record for the given keychain item object.
OSStatus SecKeychainItemGetUniqueRecordID ( SecKeychainItemRef itemRef, const CSSM_DB_UNIQUE_RECORD **uniqueRecordID );
A keychain item object.
On return, a pointer to a CSSM unique record for the given item. The unique record is valid until the item object is released.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychainItem.h
Imports one or more certificates, keys, or identities and adds them to a keychain.
OSStatus SecKeychainItemImport ( CFDataRef importedData, CFStringRef fileNameOrExtension, SecExternalFormat *inputFormat, SecExternalItemType *itemType, SecItemImportExportFlags flags, const SecKeyImportExportParameters *keyParams, SecKeychainRef importKeychain, CFArrayRef *outItems );
The external representation of the items to import.
The name or extension of the file from which the external representation was obtained. Pass NULL if you don’t know the name or extension.
On input, points to the format of the external representation. Pass kSecFormatUnknown if you do not know the exact format. On output, points to the format that the function has determined the external representation to be in. Pass NULL if you don’t know the format and don’t want the format returned to you.
On input, points to the item type of the item or items contained in the external representation. Pass kSecItemTypeUnknown if you do not know the item type. On output, points to the item type that the function has determined the external representation to contain. Pass NULL if you don’t know the item type and don’t want the type returned to you.
Unused; pass in 0.
A pointer to a structure containing a set of input parameters for the function. If no key items are being imported, these parameters are optional and you can set the keyParams parameter to NULL. If you pass NULL for the importKeychain parameter, the kSecKeyImportOnlyOne bit in the flags field of the SecKeyImportExportParameters structure is ignored. Otherwise, if the kSecKeyImportOnlyOne bit is set and there is more than one private key in the incoming external representation, no items are imported to the specified keychain and the error errSecMultiplePrivKeys is returned. The possible values for the flags field are described in “Keychain Item Import/Export Parameter Flags.”
A keychain object indicating the keychain to which the key or certificate should be imported. If you pass NULL, the item is not imported. Use the SecKeychainCopyDefault function to get a reference to the default keychain.
On output, points to an array of SecKeychainItemRef objects for the imported items. You must provide a valid pointer to a CFArrayRef object to receive this information. If you pass NULL for this parameter, the function does not return the imported items. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
When you pass this function a CFDataRef object containing the external representation of one or more keys, certificates, or identities, SecKeychainItemImport attempts to determine the format and contents of the data. To ensure that this process is successful, you should specify values for one or more of the parameters fileNameOrExtension, inputFormat, and itemType. To have the function add the imported items to a keychain, specify a non-NULL value for the importKeychain parameter. To have the function return SecKeychainItemRef objects for the imported items, specify a non-NULL value for the outItems parameter.
Because the SecKeychainItemImport function determines whether the item is PEM armoured by inspecting the data, the flags parameter is not used in calling this function.
After the function returns, you can determine the nature of the keychain items from the values returned in the inputFormat and itemType parameters. Depending on the nature of each item, once it is imported to a keychain you can safely cast the SecKeychainItemRef object to a SecKeyRef, SecCertificateRef, or SecIdentityRef object.
Note that when you import data in PKCS12 format, typically one SecIdentityRef object is returned in the outItems parameter. The data might also include one or more SecCertificateRef objects. The output data will not include any SecKeyRef objects unless the incoming data includes a key with no matching certificate.
When the output item type is kSecItemTypeAggregate, you can use the CFGetTypeID function to determine the Core Foundation type of each item and the functions in “Getting Information About Keychain Services and Types” to determine the keychain item type of each item. For example, the following code determines whether the item is a certificate:
CFTypeID theID = CFGetTypeID(theItem); |
if (SecCertificateGetTypeID() == theID) |
You can pass in NULL for both outItems and importKeychain to determine what is inside a given external data representation. When you do, the function returns the input format and the item type without modifying the data in any way.
SecImportExport.h
Updates an existing keychain item after changing its attributes or data.
OSStatus SecKeychainItemModifyAttributesAndData ( SecKeychainItemRef itemRef, const SecKeychainAttributeList *attrList, UInt32 length, const void *data );
A reference to the keychain item to modify.
A pointer to the list of attributes to modify and their new values. Pass NULL if you have no need to modify attributes.
The length of the buffer pointed to by the data parameter. Pass 0 if you pass NULL in the data parameter.
A pointer to a buffer containing the data to store. Pass NULL if you do not need to modify the data.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
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 this function does nothing and returns noErr.
Note that when you use this function to modify a keychain item, Keychain Services updates the modification date of the item. Therefore, you cannot use this function to modify the modification date, as the value you specify will be overwritten with the current time. If you want to change the modification date to something other than the current time, use a CSSM function to do so.
You should pair the SecKeychainItemCopyAttributesAndData function with the SecKeychainItemModifyAttributesAndData function, as these functions handle more attributes than are support by the old Keychain Manager and passing them into older calls yields an invalid attribute error. Use the functions SecKeychainItemModifyContent and SecKeychainItemCopyContent when dealing with older Keychain Manager functions.
SecKeychainItem.h
Updates an existing keychain item after changing its attributes and/or data.
OSStatus SecKeychainItemModifyContent ( SecKeychainItemRef itemRef, const SecKeychainAttributeList *attrList, UInt32 length, const void *data );
A reference to the keychain item to modify.
A pointer to the list of attributes to set and their new values. Pass NULL if you have no need to modify attributes.
The length of the buffer pointed to by the data parameter. Pass 0 if you pass NULL in the data parameter.
A pointer to a buffer containing the data to store. Pass NULL if you do not need to modify the data.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
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 this function does nothing and returns noErr.
Note that when you use this function to modify a keychain item, Keychain Services updates the modification date of the item. Therefore, you cannot use this function to modify the modification date, as the value you specify will be overwritten with the current time. If you want to change the modification date to something other than the current time, use a CSSM function to do so.
You should pair the SecKeychainItemModifyContent function with the SecKeychainItemCopyContent function when dealing with older Keychain Manager functions. The SecKeychainItemCopyAttributesAndData and SecKeychainItemModifyAttributesAndData functions handle more attributes than are support by the old Keychain Manager; however, passing them into older calls yields an invalid attribute error.
SecKeychainItem.h
Sets the access of a given keychain item.
OSStatus SecKeychainItemSetAccess ( SecKeychainItemRef itemRef, SecAccessRef access );
A reference to a keychain item.
An access object to replace the keychain item’s current access object. Use the SecAccessCreate function to create an access object.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Each protected keychain item (such as a password or private key) has an associated access object. The access object contains access control list (ACL) entries, which specify trusted applications and the operations for which those operations are trusted. When an application attempts to access a keychain item for a particular purpose (such as to sign a document), the system determines whether that application is trusted to access the item for that purpose. If it is trusted, then the application is given access and no user confirmation is required. If the application is not trusted, but there is an ACL entry for that operation, then the user is asked to confirm whether the application should be given access. If there is no ACL entry for that operation, then access is denied and it is up to the calling application to try something else or to notify the user.
For more information about ACL entries, see the SecACLCreateFromSimpleContents function.
SecKeychainItem.h
Locks a keychain.
OSStatus SecKeychainLock ( SecKeychainRef keychain );
A reference to the keychain to lock. Pass NULL to lock the default keychain.
A result code. See “Keychain Services Result Codes.”The result code errSecNoSuchKeychain indicates that specified keychain could not be found. The result code errSecInvalidKeychain indicates that the specified keychain is invalid. Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Your application should not call this function unless you are responding to a user’s request to lock a keychain. In general, you should leave the keychain unlocked so that the user does not have to unlock it again in another application.
SecKeychain.hLocks all keychains belonging to the current user.
OSStatus SecKeychainLockAll ( void );
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Your application should not call this function unless you are responding to a user’s request to lock a keychain. In general, you should leave the keychain unlocked so that the user does not have to unlock it again in another application.
SecKeychain.hOpens a keychain.
OSStatus SecKeychainOpen ( const char *pathName, SecKeychainRef *keychain );
A constant character string representing the POSIX path to the keychain to open.
On return, a pointer to the keychain object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
You may use this function to retrieve a pointer to a keychain object given the path of the keychain. You do not need to close the keychain, but you should release the memory that the pointer occupies when you are finished with it.
SecKeychain.h
Unregisters your keychain event callback function.
OSStatus SecKeychainRemoveCallback ( SecKeychainCallback callbackFunction );
The callback function pointer to remove.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Once removed, keychain events are not sent to the owner of the callback.
SecKeychain.h
Finds the next keychain item matching the given search criteria.
OSStatus SecKeychainSearchCopyNext ( SecKeychainSearchRef searchRef, SecKeychainItemRef *itemRef );
A reference to the current search criteria. The search object is created in the SecKeychainSearchCreateFromAttributes function and must be released by calling the CFRelease function when you are done with it.
On return, a pointer to a keychain item object of the next matching keychain item, if any. You must call the CFRelease function to release this object when you are finished using it.
A result code. When there are no more items that match, errSecItemNotFound is returned. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Each item stored in the keychain contains data (such as a certificate), which is indexed by the item’s attributes. Use the SecKeychainSearchCreateFromAttributes function to specify attributes to search for. If the SecKeychainSearchCopyNext function finds a match, you can use the SecKeychainItemCopyAttributesAndData function to retrieve the item’s data.
A SecKeychainItemRef object for a certificate that is stored in a keychain can be safely cast to a SecCertificateRef for use with the Certificate, Key, and Trust API.
To find and obtain data from a password keychain item, use the SecKeychainFindInternetPassword or SecKeychainFindGenericPassword function.
SecKeychainSearch.h
Creates a search object matching a list of zero or more attributes.
OSStatus SecKeychainSearchCreateFromAttributes ( CFTypeRef keychainOrArray, SecItemClass itemClass, const SecKeychainAttributeList *attrList, SecKeychainSearchRef *searchRef );
A reference to an array of keychains to search, a single keychain, or NULL to search the user’s current keychain search list. Use the function SecKeychainCopySearchList to retrieve the user’s default search list.
The keychain item class. See “Keychain Item Class Constants” for valid constants.
A pointer to a list of zero or more keychain attribute records to match. Pass NULL to match any keychain attribute.
On return, a pointer to the current search object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Each item stored in the keychain contains data (such as a certificate), which is indexed by the item’s attributes. You look up an item in a keychain by its attributes. If you find a match, you can then retrieve the item’s data. Use the search object created by this function as input to the SecKeychainSearchCopyNext function to find a a keychain item and the SecKeychainItemCopyAttributesAndData function to retrieve the item’s data.
To find and obtain data from a password keychain item, use the SecKeychainFindInternetPassword or SecKeychainFindGenericPassword function.
SecKeychainSearch.hReturns the unique identifier of the opaque type to which a SecKeychainSearchRef object belongs.
CFTypeID SecKeychainSearchGetTypeID ( void );
A value that identifies the opaque type of a SecKeychainSearchRef object.
This function returns a value that uniquely identifies the opaque type of a SecKeychainSearchRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.
SecKeychainSearch.hSets the application access for a keychain.
OSStatus SecKeychainSetAccess ( SecKeychainRef keychain, SecAccessRef access );
A reference to the keychain for which to set the access. Pass NULL to specify the default keychain.
An access object of type SecAccessRef containing access control lists for the keychain. See “Creating an Access Object” for instructions on creating an access object.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
In addition to the ACLs for individual keychain items, the keychain itself has ACLs. However, they are currently unused and this function is unimplemented.
Although this function is available in Mac OS X v10.2 and later, it is unimplemented and returns an unimpErr error code if called.
SecKeychain.h
Sets the default keychain.
OSStatus SecKeychainSetDefault ( SecKeychainRef keychain );
A reference to the keychain you wish to make the default.
A result code. See “Keychain Services Result Codes.” The result code errSecNoSuchKeychain indicates that the specified keychain could not be found. The result code errSecInvalidKeychain indicates that the specified keychain is invalid. Call SecCopyErrorMessageString to get a human-readable string explaining the result.
In most cases, your application should not need to set the default keychain, because this is a choice normally made by the user. You may call this function to change where a password or other keychain items are added, but since this is a user choice, you should set the default keychain back to the user specified keychain when you are done.
SecKeychain.hSets the default keychain for a specified preference domain.
OSStatus SecKeychainSetDomainDefault ( SecPreferencesDomain domain, SecKeychainRef keychain );
The preference domain for which you wish to set the default keychain. See “Keychain Preference Domain Constants” for possible domain values.
A reference to the keychain you wish to set as default in the specified preference domain.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
A preference domain is a set of security-related preferences, such as the default keychain and the current keychain search list. Use this function if you want to set the default keychain for a specific preference domain. Use the SecKeychainSetDefault function if you want to set the default keychain for the current preference domain. See the SecKeychainSetPreferenceDomain function for a discussion of current and default preference domains.
SecKeychain.hSets the keychain search list for a specified preference domain.
OSStatus SecKeychainSetDomainSearchList ( SecPreferencesDomain domain, CFArrayRef searchList );
The preference domain for which you wish to set the default keychain search list. See “Keychain Preference Domain Constants”for possible domain values.
A pointer to a keychain search list to set in the preference domain.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
A preference domain is a set of security-related preferences, such as the default keychain and the current keychain search list. Use this function if you want to set the keychain search list for a specific preference domain. Use the SecKeychainSetSearchList function if you want to set the keychain search list for the current preference domain. See the SecKeychainSetPreferenceDomain function for a discussion of current and default preference domains.
SecKeychain.h
Sets the keychain preference domain.
OSStatus SecKeychainSetPreferenceDomain ( SecPreferencesDomain domain );
The keychain preference domain to set. See “Keychain Preference Domain Constants” for possible domain values.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
A preference domain is a set of security-related preferences, such as the default keychain and the current keychain search list. The default preference domain for system daemons (that is, for daemons running in the root session) is the system domain. The default preference domain for all other programs is the user domain.
This function changes the preference domain for all subsequent function calls; for example, if you change from the system domain to the user domain and then call SecKeychainLock specifying NULL for the keychain, the function locks the default system keychain rather than the default user keychain. You might want to use this function, for example, when launching a system daemon from a user session so that the daemon uses system preferences rather than user preferences.
SecKeychain.h
Specifies the list of keychains to use in the default keychain search list.
OSStatus SecKeychainSetSearchList ( CFArrayRef searchList );
An array of keychain references (of type SecKeychainRef) specifying the list of keychains to use in the default keychain search list. Passing an empty array clears the search list.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
The default keychain search list is used by several functions; see for example SecKeychainSearchCreateFromAttributes, SecKeychainFindInternetPassword, or SecKeychainFindGenericPassword. To obtain the current default keychain search list, use the SecKeychainCopySearchList function.
The default keychain search list is displayed as the keychain list in the Keychain Access utility. If you use SecKeychainSetSearchList to change the keychain search list, the list displayed in Keychain Access changes accordingly.
SecKeychain.h
Changes the settings of a keychain.
OSStatus SecKeychainSetSettings ( SecKeychainRef keychain, const SecKeychainSettings *newSettings );
A reference to a keychain whose settings you wish to change. Pass NULL to change the settings of the default keychain.
A pointer to a keychain settings structure that defines whether the keychain locks when sleeping, or locks after a set time period of inactivity.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
SecKeychain.hEnables or disables the user interface for Keychain Services functions that automatically display a user interface.
OSStatus SecKeychainSetUserInteractionAllowed ( Boolean state );
A flag that indicates whether the Keychain Services will display a user interface. If you pass TRUE, user interaction is allowed. This is the default value. If FALSE, Keychain Services functions that normally display a user interface will instead return an error.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
Certain Keychain Services functions that require the presence of a keychain automatically display a Keychain Not Found dialog if there is none. Functions that require the keychain to be unlocked automatically display the Unlock Keychain dialog. The SecKeychainSetUserInteractionAllowed function enables you to control whether these functions display a user interface. By default, user interaction is permitted.
If you are writing an application that must run unattended on a server, you may wish to disable the user interface so that any subsequent keychain calls that normally bring up the unlock UI will instead return immediately with an errSecInteractionRequired result). In this case you must programmatically create a keychain or unlock the keychain when necessary.
If you disable user interaction before calling a Keychain Services function, be sure to reenable it when you are finished. Failure to reenable user interaction will affect other clients of the Keychain Services.
SecKeychain.h
Unlocks a keychain.
OSStatus SecKeychainUnlock ( SecKeychainRef keychain, UInt32 passwordLength, const void *password, Boolean usePassword );
A reference to the keychain to unlock. Pass NULL to specify the default keychain. If you pass a locked keychain, this function displays the Unlock Keychain dialog box if you have not provided a password. If the specified keychain is currently unlocked, the Unlock Keychain dialog box is not displayed and this function returns noErr. You must call the CFRelease function to release this object when you are finished using it.
An unsigned 32-bit integer representing the length of the password buffer.
A buffer containing the password for the keychain. Pass NULL if the user password is unknown. In this case, this function displays the Unlock Keychain dialog to request the user for the keychain password.
A Boolean value indicating whether the password parameter is used. You should pass TRUE if you are passing a password or FALSE if it is to be ignored.
A result code. See “Keychain Services Result Codes.” The result code userCanceledErr indicates that the user pressed the Cancel button in the Unlock Keychain dialog box. The result code errSecAuthFailed indicates that authentication failed because of too many unsuccessful retries. The result code errSecInteractionRequired indicates that user interaction is required to unlock the keychain. Call SecCopyErrorMessageString to get a human-readable string explaining the result.
In most cases, your application does not need to call this function directly, since most Keychain Services functions that require an unlocked keychain do so for you. If your application needs to verify that a keychain is unlocked, call the function SecKeychainGetStatus.
SecKeychain.h
Retrieves the data of a trusted application object.
OSStatus SecTrustedApplicationCopyData ( SecTrustedApplicationRef appRef, CFDataRef *data );
A trusted application object from which to retrieve data. Use the SecTrustedApplicationCreateFromPath function to create a trusted application object.
On return, points to a data object for the data of the trusted application object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
The trusted application object created by the SecTrustedApplicationCreateFromPath function includes data that uniquely identifies the application, such as a cryptographic hash of the application. The operating system can use this data to verify that the application has not been altered since the trusted application object was created. When an application requests access to an item in the keychain for which it is designated as a trusted application, for example, the operating system checks this data before granting access. You can use the SecTrustedApplicationCopyData function to extract this data from the trusted application object for storage or for transmittal to another location (such as over a network). Use the SecTrustedApplicationSetData function to insert the data back into a trusted application object. Note that this data is in a private format; there is no supported way to read or interpret it.
SecTrustedApplication.h
Creates a trusted application object based on the application specified by path.
OSStatus SecTrustedApplicationCreateFromPath ( const char *path, SecTrustedApplicationRef *app );
The path to the application or tool to trust. For application bundles, use the path to the bundle directory. Pass NULL to refer to the application or tool making this call.
On return, points to the newly created trusted application object. You must call the CFRelease function to release this object when you are finished using it.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
This function creates a trusted application object, which both identifies an application and provides data that can be used to ensure that the application has not been altered since the object was created. The application object is used as input to the SecAccessCreate function, which creates an access object. The access object, in turn, is used as input to the SecKeychainItemSetAccess function to specify the set of applications that are trusted to access a specific keychain item.
SecTrustedApplication.hReturns the unique identifier of the opaque type to which a SecTrustedApplication object belongs.
CFTypeID SecTrustedApplicationGetTypeID ( void );
A value that identifies the opaque type of a SecTrustedApplicationRef object.
This function returns a value that uniquely identifies the opaque type of a SecTrustedApplicationRef object. You can compare this value to the CFTypeID identifier obtained by calling the CFGetTypeID function on a specific object. These values might change from release to release or platform to platform.
SecTrustedApplication.h
Sets the data of a given trusted application object.
OSStatus SecTrustedApplicationSetData ( SecTrustedApplicationRef appRef, CFDataRef data );
A trusted application object.
A reference to the data to set in the trusted application.
A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString to get a human-readable string explaining the result.
If you used the SecTrustedApplicationCopyData function to extract the data from a trusted application object for storage or to transmit it to a different location, you can use the SecTrustedApplicationSetData function to insert the data into a new trusted application object. Doing so would create an object that identifies the same application as the original trusted application object.
SecTrustedApplication.hDefines a pointer to a customized callback function that Keychain Services calls when a keychain event has occurred.
typedef OSStatus (*SecKeychainCallback) ( SecKeychainEvent keychainEvent, SecKeychainCallbackInfo *info, void *context );
You would declare your keychain callback function like this
if you were to name it MyKeychainCallback:
OSStatus MyKeychainCallback ( SecKeychainEvent keychainEvent, SecKeychainCallbackInfo *info, void *context );
The keychain event of which your application
wishes to be notified. The type of event that can trigger your callback
depends on the bit mask you passed in the eventMask parameter
of the function SecKeychainAddCallback.
A pointer to a structure of type SecKeychainCallbackInfo.
On return, the structure contains information about the keychain
event that occurred. The Keychain Manager passes this information
to your callback function through this parameter.
A pointer to application-defined storage that
your application previously passed to the function SecKeychainAddCallback. You can use
this value to perform operations such as tracking which instance
of a function is operating.
A result code. See “Keychain Services Result Codes.”
To add your callback function, use the SecKeychainAddCallback function. To
remove your callback function, use the SecKeychainRemoveCallback function.
SecKeychain.hIdentifies a keychain or keychain item’s access information.
typedef struct OpaqueSecAccessRef *SecAccessRef;
SecBase.h
Represents information about an access control list entry.
typedef struct OpaqueSecTrustRef *SecACLRef;
SecBase.h
Represents a 16-byte Apple File Protocol server signature block.
typedef UInt8 SecAFPServerSignature[16];
This type represents a 16-byte Apple File Protocol server signature block. You can pass a value of this type in the serverSignature parameter of the functions KCAddAppleSharePassword and KCFindAppleSharePassword to represent an Apple File Protocol server signature. You can use a value of this type with the keychain item attribute constant kSecSignatureItemAttr to specify an Apple File Protocol server signature.
SecKeychainItem.h
Contains keychain attributes.
struct SecKeychainAttribute
{
SecKeychainAttrType tag;
UInt32 length;
void *data;
};
typedef struct SecKeychainAttribute SecKeychainAttribute;
typedef SecKeychainAttribute *SecKeychainAttributePtr;
tagA 4-byte attribute tag. See “Keychain Item Attribute Constants” for valid attribute types.
lengthThe length of the buffer pointed to by data.
dataA pointer to the attribute data.
SecBase.h
Represents an attribute.
struct SecKeychainAttributeInfo
{
UInt32 count;
UInt32 *tag;
UInt32 *format;
};
typedef struct SecKeychainAttributeInfo SecKeychainAttributeInfo;
countThe number of tag-format pairs in the respective arrays.
tagA pointer to the first attribute tag in the array.
formatA pointer to the first attribute format in the array. Attribute formats are of type CSSM_DB_ATTRIBUTE_FORMAT.
Each tag and format item form a pair.
SecBase.h
Represents a list of keychain attributes.
struct SecKeychainAttributeList
{
UInt32 count;
SecKeychainAttribute *attr;
};
typedef struct SecKeychainAttributeList SecKeychainAttributeList;
countAn unsigned 32-bit integer that represents the number of keychain attributes in the array.
attrA pointer to the first keychain attribute in the array.
SecBase.h
Represents a keychain attribute type.
typedef OSType SecKeychainAttrType;
SecBase.h
Contains information about a keychain event.
struct SecKeychainCallbackInfo
{
UInt32 version;
SecKeychainItemRef item;
SecKeychainRef keychain;
pid_t pid;
};
typedef struct SecKeychainCallbackInfo SecKeychainCallbackInfo;
versionThe version of this structure. See “Keychain Settings Version” for valid constants.
itemA reference to the keychain item in which the event occurred. If the event did not involve an item, this field is not valid.
keychainA reference to the keychain in which the event occurred. If the event did not involve a keychain, this field is not valid.
pidThe ID of the process that generated this event.
This structure contains information about the keychain event of which your application wants to be notified. Keychain Services passes a pointer to this structure in the info parameter of your callback function. For information on how to write a keychain event callback function, see SecKeychainCallback.
SecKeychain.h
Contains information about a keychain item.
typedef struct OpaqueSecKeychainItemRef *SecKeychainItemRef;
A SecKeychainItemRef object for a certificate that is stored in a keychain can be safely cast to a SecCertificateRef for use with the Certificate, Key, and Trust API.
SecBase.h
Contains information about a keychain.
typedef struct OpaqueSecKeychainRef *SecKeychainRef;
SecBase.h
Contains information about a keychain search.
typedef struct OpaqueSecKeychainSearchRef *SecKeychainSearchRef;
SecBase.h
Contains information about keychain settings.
struct SecKeychainSettings
{
UInt32 version;
Boolean lockOnSleep;
Boolean useLockInterval;
UInt32 lockInterval;
};
typedef struct SecKeychainSettings SecKeychainSettings;
versionAn unsigned 32-bit integer representing the keychain version.
lockOnSleepA Boolean value indicating whether the keychain locks when the system sleeps.
useLockIntervalA Boolean value indicating whether the keychain automatically locks after a certain period of time.
lockIntervalAn unsigned 32-bit integer representing the number of seconds before the keychain locks. If you set useLockInterval to FALSE, set lockInterval to INT_MAX to indicate that the keychain never locks.
This structure contains information about a keychain’s settings such as locking on sleep and the lock time interval. You can use the SecKeychainSetSettings and SecKeychainCopySettings functions to set and copy a keychain’s settings.
SecKeychain.h
Contains input parameters for import and export functions.
typedef struct
{
/* for import and export */
uint32_t version;
SecKeyImportExportFlags flags;
CFTypeRef passphrase;
CFStringRef alertTitle;
CFStringRef alertPrompt;
/* for import only */
SecAccessRef accessRef;
CSSM_KEYUSE keyUsage;
CSSM_KEYATTR_FLAGS keyAttributes;
} SecKeyImportExportParameters;
versionThe version of this structure; the current value is SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION.
flagsA set of flag bits, defined in “Keychain Item Import/Export Parameter Flags.”
passphraseA password, used for kSecFormatPKCS12 and kSecFormatWrapped formats only. (A password is sometimes referred to as a passphrase to emphasize the fact that a longer string that includes non-letter characters, such as numbers, punctuation, and spaces, is more secure than a simple word.) Legal types are CFStringRef and CFDataRef. PKCS12 requires passwords to be in Unicode format; passing in a CFStringRef as the password is the safest way to ensure that this requirement is met (and that the result is compatible with other implementations). If a CFDataRef object is supplied as the password for a PKCS12 export operation, the data is assumed to be in UTF8 form and is converted as appropriate.
When importing or exporting keys (SecKeyRef objects) in one of the wrapped formats (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH, or kSecFormatWrappedPKCS8) or in PKCS12 format, you must either explicitly specify the passphrase field or set the kSecKeySecurePassphrase bit in the Flags field (to prompt the user for the password).
alertTitleTitle of secure password alert panel. When importing or exporting a key, if you set the kSecKeySecurePassphrase flag bit, you can optionally use this field to specify a string for the password panel’s title bar.
alertPromptPrompt in secure password alert panel. When importing or exporting a key, if you set the kSecKeySecurePassphrase flag bit, you can optionally use this field to specify a string for the prompt that appears in the password panel.
accessRefSpecifies the initial access controls of imported private keys. If more than one private key is being imported, all private keys get the same initial access controls. If this field is NULL when private keys are being imported, then the access object for the keychain item for an imported private key depends on the kSecKeyNoAccessControl bit in the flags parameter. If this bit is 0 (or keyParams is NULL), the default access control is used. If this bit is 1, no access object is attached to the keychain item for imported private keys.
keyUsageA word of bits constituting the low-level use flags for imported keys as defined in cssmtype.h. If this field is 0 or keyParams is NULL, the default value is CSSM_KEYUSE_ANY.
keyAttributesA word of bits constituting the low-level attribute flags for imported keys. The default value is CSSM_KEYATTR_SENSITIVE | CSSM_KEYATTR_EXTRACTABLE; the CSSM_KEYATTR_PERMANENT bit is also added to the default if a non-NULL value is specified for the importKeychain parameter.
The following are valid values for these flags: CSSM_KEYATTR_PERMANENT, CSSM_KEYATTR_SENSITIVE, and CSSM_KEYATTR_EXTRACTABLE.
If the CSSM_KEYATTR_PERMANENT bit is set, the importKeychain parameter is not valid, and if any keys are found in the external representation, then the error errSecInvalidKeychain is returned.
The CSSM_KEYATTR_SENSITIVE bit indicates that the key can only be extracted in wrapped form.
Important: If you do not set the CSSM_KEYATTR_EXTRACTABLE bit, you cannot extract the imported key from the keychain in any form, including in wrapped form.
The CSSM_KEYATTR_FLAGS enumeration is defined in cssmtype.h. Note that the CSSM_KEYATTR_RETURN_xxx bits are always forced to CSSM_KEYATTR_RETURN_REF regardless of how they are specified in the keyAttributes field.
This structure is passed in the keyParams parameter as input to the functions SecKeychainItemExport and SecKeychainItemImport.
PKCS12 is an abbreviation for Public-Key Cryptography Standard # 12. This standard, by RSA Security, provides a format for external representation of keys and certificates and is described in PKCS 12 v1.0: Personal Information Exchange Syntax.
SecImportExport.h
Contains information about a trusted application.
typedef struct OpaqueSecTrustedApplicationRef *SecTrustedApplicationRef;
SecBase.hDefines constants that specify which operations an access control list entry applies to.
typedef sint32 CSSM_ACL_AUTHORIZATION_TAG;
enum {
CSSM_ACL_AUTHORIZATION_TAG_VENDOR_DEFINED_START =
x00010000,
CSSM_ACL_AUTHORIZATION_ANY = CSSM_WORDID__STAR_,
CSSM_ACL_AUTHORIZATION_LOGIN = CSSM_WORDID_LOGIN,
CSSM_ACL_AUTHORIZATION_GENKEY = CSSM_WORDID_GENKEY,
CSSM_ACL_AUTHORIZATION_DELETE = CSSM_WORDID_DELETE,
CSSM_ACL_AUTHORIZATION_EXPORT_WRAPPED =
CSSM_WORDID_EXPORT_WRAPPED,
CSSM_ACL_AUTHORIZATION_EXPORT_CLEAR =CSSM_WORDID_EXPORT_CLEAR,
CSSM_ACL_AUTHORIZATION_IMPORT_WRAPPED =
CSSM_WORDID_IMPORT_WRAPPED,
CSSM_ACL_AUTHORIZATION_IMPORT_CLEAR =CSSM_WORDID_IMPORT_CLEAR,
CSSM_ACL_AUTHORIZATION_SIGN = CSSM_WORDID_SIGN,
CSSM_ACL_AUTHORIZATION_ENCRYPT = CSSM_WORDID_ENCRYPT,
CSSM_ACL_AUTHORIZATION_DECRYPT = CSSM_WORDID_DECRYPT,
CSSM_ACL_AUTHORIZATION_MAC = CSSM_WORDID_MAC,
CSSM_ACL_AUTHORIZATION_DERIVE = CSSM_WORDID_DERIVE
};
/* Apple-defined ACL authorization tags */
enum {
CSSM_ACL_AUTHORIZATION_CHANGE_ACL =
CSSM_ACL_AUTHORIZATION_TAG_VENDOR_DEFINED_START,
CSSM_ACL_AUTHORIZATION_CHANGE_OWNER
};
CSSM_ACL_AUTHORIZATION_TAG_VENDOR_DEFINED_STARTAll vendor specific constants must be in the number range starting at this value.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_ANYNo restrictions. This ACL entry applies to all operations available to the caller.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_LOGINUse for a CSP (smart card) login.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_GENKEYGenerate a key.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_DELETEDelete this item.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_EXPORT_WRAPPEDExport a wrapped (that is, encrypted) key. This tag is checked on the key being exported; in addition, the CSSM_ACL_AUTHORIZATION_ENCRYPT tag is checked for any key used in the wrapping operation.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_EXPORT_CLEARExport an unencrypted key.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_IMPORT_WRAPPEDImport an encrypted key. This tag is checked on the key being imported; in addition, the CSSM_ACL_AUTHORIZATION_DECRYPT tag is checked for any key used in the unwrapping operation.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_IMPORT_CLEARImport an unencrypted key.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_SIGNDigitally sign data.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_ENCRYPTEncrypt data.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_DECRYPTDecrypt data.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_MACCreate or verify a message authentication code.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_DERIVEDerive a new key from another key.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
CSSM_ACL_AUTHORIZATION_CHANGE_ACLChange an access control list entry.
Available in Mac OS X v10.0 and later.
Declared in cssmapple.h.
CSSM_ACL_AUTHORIZATION_CHANGE_OWNERFor internal system use only. Use the CSSM_ACL_AUTHORIZATION_CHANGE_ACL tag for changes to owner ACL entries.
Available in Mac OS X v10.0 and later.
Declared in cssmapple.h.
Defines the version of an import/export parameters structure.
#define SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION 0
SEC_KEY_IMPORT_EXPORT_PARAMS_VERSIONDefines the version number for a SecImportExportParameters structure used as input to the functions SecKeychainItemExport and SecKeychainItemImport.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
Defines constants you can use to identify the type of authentication to use for an Internet password.
typedef FourCharCode SecAuthenticationType;
enum
{
kSecAuthenticationTypeNTLM = AUTH_TYPE_FIX_ ('ntlm'),
kSecAuthenticationTypeMSN = AUTH_TYPE_FIX_ ('msna'),
kSecAuthenticationTypeDPA = AUTH_TYPE_FIX_ ('dpaa'),
kSecAuthenticationTypeRPA = AUTH_TYPE_FIX_ ('rpaa'),
kSecAuthenticationTypeHTTPBasic = AUTH_TYPE_FIX_ ('http'),
kSecAuthenticationTypeHTTPDigest = AUTH_TYPE_FIX_ ('httd'),
kSecAuthenticationTypeHTMLForm = AUTH_TYPE_FIX_ ('form'),
kSecAuthenticationTypeDefault = AUTH_TYPE_FIX_ ('dflt'),
kSecAuthenticationTypeAny = AUTH_TYPE_FIX_ ( 0 )
};
kSecAuthenticationTypeNTLMSpecifies Windows NT LAN Manager authentication.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeMSNSpecifies Microsoft Network default authentication.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeDPASpecifies Distributed Password authentication.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeRPASpecifies Remote Password authentication.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeHTTPBasicSpecifies HTTP Basic authentication.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeHTTPDigestSpecifies HTTP Digest Access authentication.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeHTMLFormSpecifies HTML form based authentication.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeDefaultSpecifies the default authentication type.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAuthenticationTypeAnySpecifies that any authentication type is acceptable.
When performing a search, use this value to avoid constraining your search results to a particular authentication type.
Available in Mac OS X v10.5 and later.
Declared in SecKeychain.h.
Defines the keychain-related event.
typedef UInt32 SecKeychainEvent;
enum
{
kSecLockEvent = 1,
kSecUnlockEvent = 2,
kSecAddEvent = 3,
kSecDeleteEvent = 4,
kSecUpdateEvent = 5,
kSecPasswordChangedEvent = 6,
kSecDefaultChangedEvent = 9,
kSecDataAccessEvent = 10,
kSecKeychainListChangedEvent = 11,
kSecTrustSettingsChangedEvent = 12
};
kSecLockEventIndicates a keychain was locked.
It is impossible to distinguish between a lock event caused by an explicit request and one caused by a keychain that locked itself because of a timeout. Therefore, the pid parameter in the SecKeychainCallbackInfo structure does not contain useful information for this event. Note that when the login session terminates, all keychains become effectively locked; however, no kSecLockEvent events are generated in this case.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecUnlockEventIndicates a keychain was successfully unlocked.
It is impossible to distinguish between an unlock event caused by an explicit request and one that occurred automatically because the keychain was needed to perform an operation. In either case, however, the pid parameter in the SecKeychainCallbackInfo structure does return the ID of the process whose actions caused the unlock event.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAddEventIndicates an item was added to a keychain.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecDeleteEventIndicates an item was deleted from a keychain.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecUpdateEventIndicates a keychain item was updated.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecPasswordChangedEventIndicates the keychain password was changed.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecDefaultChangedEventIndicates that a different keychain was specified as the default.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecDataAccessEventIndicates a process has accessed a keychain item’s data.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecKeychainListChangedEventIndicates the list of keychains has changed.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecTrustSettingsChangedEventIndicates trust settings have changed.
Available in Mac OS X v10.5 and later.
Declared in SecKeychain.h.
Defines bit masks for keychain event constants
typedef UInt32 SecKeychainEventMask;
enum
{
kSecLockEventMask = 1 << kSecLockEvent,
kSecUnlockEventMask = 1 << kSecUnlockEvent,
kSecAddEventMask = 1 << kSecAddEvent,
kSecDeleteEventMask = 1 << kSecDeleteEvent,
kSecUpdateEventMask = 1 << kSecUpdateEvent,
kSecPasswordChangedEventMask = 1 << kSecPasswordChangedEvent,
kSecDefaultChangedEventMask = 1 << kSecDefaultChangedEvent,
kSecDataAccessEventMask = 1 << kSecDataAccessEvent,
kSecKeychainListChangedMask = 1 << kSecKeychainListChangedEvent,
kSecTrustSettingsChangedEventMask = 1 << kSecTrustSettingsChangedEvent,
kSecEveryEventMask = 0xffffffff
};
kSecLockEventMaskIf the bit specified by this mask is set, your callback function is invoked when a keychain is locked.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecUnlockEventMaskIf the bit specified by this mask is set, your callback function is invoked when a keychain is unlocked.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecAddEventMaskIf the bit specified by this mask is set, your callback function is invoked when an item is added to a keychain.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecDeleteEventMaskIf the bit specified by this mask is set, your callback function is invoked when an item is deleted from a keychain.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecUpdateEventMaskIf the bit specified by this mask is set, your callback function is invoked when a keychain item is updated.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecPasswordChangedEventMaskIf the bit specified by this mask is set, your callback function is invoked when the keychain password is changed.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecDefaultChangedEventMaskIf the bit specified by this mask is set, your callback function is invoked when a different keychain is specified as the default.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecDataAccessEventMaskIf the bit specified by this mask is set, your callback function is invoked when a process accesses a keychain item’s data.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecKeychainListChangedMaskIf the bit specified by this mask is set, your callback function is invoked when a keychain list is changed.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecTrustSettingsChangedEventMaskIf the bit specified by this mask is set, your callback function is invoked when there is a change in certificate trust settings.
Available in Mac OS X v10.5 and later.
Declared in SecKeychain.h.
kSecEveryEventMaskIf all the bits are set, your callback function is invoked whenever any event occurs.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
Specifies a keychain item’s attributes.
typedef FourCharCode SecItemAttr;
enum
{
kSecCreationDateItemAttr = 'cdat',
kSecModDateItemAttr = 'mdat',
kSecDescriptionItemAttr = 'desc',
kSecCommentItemAttr = 'icmt',
kSecCreatorItemAttr = 'crtr',
kSecTypeItemAttr = 'type',
kSecScriptCodeItemAttr = 'scrp',
kSecLabelItemAttr = 'labl',
kSecInvisibleItemAttr = 'invi',
kSecNegativeItemAttr = 'nega',
kSecCustomIconItemAttr = 'cusi',
kSecAccountItemAttr = 'acct',
kSecServiceItemAttr = 'svce',
kSecGenericItemAttr = 'gena',
kSecSecurityDomainItemAttr = 'sdmn',
kSecServerItemAttr = 'srvr',
kSecAuthenticationTypeItemAttr = 'atyp',
kSecPortItemAttr = 'port',
kSecPathItemAttr = 'path',
kSecVolumeItemAttr = 'vlme',
kSecAddressItemAttr = 'addr',
kSecSignatureItemAttr = 'ssig',
kSecProtocolItemAttr = 'ptcl',
kSecCertificateType = 'ctyp',
kSecCertificateEncoding = 'cenc',
kSecCrlType = 'crtp',
kSecCrlEncoding = 'crnc',
kSecAlias = 'alis'
};
kSecCreationDateItemAttrIdentifies the creation date attribute.
You use this tag to get a string value that represents the date the item was created, expressed in Zulu Time format ("YYYYMMDDhhmmssZ"). This is the native format for stored time values in the CDSA specification (defined as CSSM_DB_ATTRIBUTE_FORMAT_TIME_DATE in the CSSM_DB_ATTRIBUTE_FORMAT enumeration, Section 17.2.6.). When specifying the creation date as input to a function (for example, SecKeychainSearchCreateFromAttributes), you may alternatively provide a numeric value of type UInt32 or SInt64, expressed as seconds since 01 January 1904.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecModDateItemAttrIdentifies the modification date attribute.
You use this tag to get a string value that represents the date the item was created, expressed in Zulu Time format ("YYYYMMDDhhmmssZ"). This is the native format for stored time values in the CDSA specification (defined as CSSM_DB_ATTRIBUTE_FORMAT_TIME_DATE in the CSSM_DB_ATTRIBUTE_FORMAT enumeration, Section 17.2.6.). When specifying the creation date as input to a function (for example, SecKeychainSearchCreateFromAttributes), you may alternatively provide a numeric value of type UInt32 or SInt64, expressed as seconds since 01 January 1904.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecDescriptionItemAttrIdentifies the description attribute.
You use this tag to set or get a string value that represents a user-visible string describing this particular kind of item, for example “disk image password”. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCommentItemAttrIdentifies the comment attribute.
You use this tag to set or get a string value that represents a user-editable string containing comments for this item. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCreatorItemAttrIdentifies the creator attribute.
You use this tag to set or get a value of type FourCharCode that represents the item's creator.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecTypeItemAttrIdentifies the type attribute.
You use this tag to set or get a value of type FourCharCode that represents the item’s type.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecScriptCodeItemAttrIdentifies 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. Use of this attribute is deprecated; string attributes should always be stored in UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecLabelItemAttrIdentifies the label attribute.
You use this tag to set or get a string value that represents a user-editable string containing the label for this item. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecInvisibleItemAttrIdentifies the invisible attribute.
You use this tag to set or get a value of type Boolean that indicates whether the item is invisible (that is, should not be displayed).
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecNegativeItemAttrIdentifies 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, which is typically invisible and with zero-length data, acts as a placeholder.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCustomIconItemAttrIdentifies the custom icon attribute.
Use of this attribute is deprecated. Custom icons for keychains are not supported in Mac OS X.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecAccountItemAttrIdentifies the account attribute.
You use this tag to set or get a string that represents the user account. It also applies to generic, Internet, and AppleShare password items. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecServiceItemAttrIdentifies the service attribute.
You use this tag to set or get a string that represents the service associated with this item, for example, “iTools”. This is unique to generic password attributes. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecGenericItemAttrIdentifies 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.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecSecurityDomainItemAttrIdentifies 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.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecServerItemAttrIdentifies the server attribute.
You use this tag to set or get a string that represents the Internet server’s domain name or IP address. This is unique to Internet password attributes. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecAuthenticationTypeItemAttrIdentifies the authentication type attribute.
You use this tag to set or get a value of type SecAuthenticationType that represents the Internet authentication scheme. For possible authentication values, see “Keychain Authentication Type Constants.” This is unique to Internet password attributes.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecPortItemAttrIdentifies 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.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecPathItemAttrIdentifies the path attribute.
You use this tag to set or get a string value that represents the path. This is unique to Internet password attributes. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecVolumeItemAttrIdentifies the volume attribute.
You use this tag to set or get a string value that represents the AppleShare volume. This is unique to AppleShare password attributes. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecAddressItemAttrIdentifies 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. Keychain strings should use UTF-8 encoding.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecSignatureItemAttrIdentifies 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.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecProtocolItemAttrIdentifies the protocol attribute.
You use this tag to set or get a value of type SecProtocolType that represents the Internet protocol. For possible protocol type values, see “Keychain Protocol Type Constants.” This is unique to AppleShare and Internet password attributes.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCertificateTypeIndicates a CSSM_CERT_TYPE type.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCertificateEncodingIndicates a CSSM_CERT_ENCODING type.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCrlTypeIndicates a CSSM_CRL_TYPE type.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCrlEncodingIndicates a CSSM_CRL_ENCODING type.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecAliasIndicates an alias.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
Not all of these attributes are used for all types of items. Which set of attributes exist for each type of item is documented in the “Data Storage Library Services” chapter of Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm) for standard items and in the DL section of the Security Release Notes for Apple-defined item types (if any).
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.
For attributes for keys, see “Keychain Item Attribute Constants For Keys.”
Specifies the attributes for a key item in a keychain.
enum
{
kSecKeyKeyClass =0,
kSecKeyPrintName =1,
kSecKeyAlias =2,
kSecKeyPermanent =3,
kSecKeyPrivate =4,
kSecKeyModifiable =5,
kSecKeyLabel =6,
kSecKeyApplicationTag =7,
kSecKeyKeyCreator =8,
kSecKeyKeyType =9,
kSecKeyKeySizeInBits =10,
kSecKeyEffectiveKeySize =11,
kSecKeyStartDate =12,
kSecKeyEndDate =13,
kSecKeySensitive =14,
kSecKeyAlwaysSensitive =15,
kSecKeyExtractable =16,
kSecKeyNeverExtractable =17,
kSecKeyEncrypt =18,
kSecKeyDecrypt =19,
kSecKeyDerive =20,
kSecKeySign =21,
kSecKeyVerify =22,
kSecKeySignRecover =23,
kSecKeyVerifyRecover =24,
kSecKeyWrap =25,
kSecKeyUnwrap =26
};
kSecKeyKeyClassType uint32 (CSSM_KEYCLASS); value is one of CSSM_KEYCLASS_PUBLIC_KEY, CSSM_KEYCLASS_PRIVATE_KEY or CSSM_KEYCLASS_SESSION_KEY.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyPrintNameType blob; human readable name of the key. Same as kSecLabelItemAttr for normal keychain items.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyAliasType blob; currently unused.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyPermanentType uint32; value is nonzero. This key is permanent (stored in some keychain) and is always 1.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyPrivateType uint32; value is nonzero. This key is protected by a user login, a password, or both.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyModifiableType uint32; value is nonzero. Attributes of this key can be modified.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyLabelType blob; for private and public keys this contains the hash of the public key. This is used to associate certificates and keys. Its value matches the value of the kSecPublicKeyHashItemAttr attribute of a certificate and it's used to construct an identity from a certificate and a key. For symmetric keys this is whatever the creator of the key passed in when they generated the key.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyApplicationTagType blob; currently unused.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyKeyCreatorType data. The data points to a CSSM_GUID structure representing the module ID of the CSP owning this key.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyKeyTypeType uint32; value is a CSSM algorithm (CSSM_ALGORITHMS) representing the algorithm associated with this key.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyKeySizeInBitsType uint32; value is the number of bits in this key.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyEffectiveKeySizeType uint32; value is the effective number of bits in this key. For example, a DES key has a key size in bits (kSecKeyKeySizeInBits) of 64 but a value for kSecKeyEffectiveKeySize of 56.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyStartDateType CSSM_DATE. Earliest date at which this key may be used. If the value is all zeros or not present, no restriction applies.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyEndDateType CSSM_DATE. Latest date at which this key may be used. If the value is all zeros or not present, no restriction applies.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeySensitiveType uint32; value is nonzero. This key cannot be wrapped with CSSM_ALGID_NONE.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyAlwaysSensitiveType uint32; value is nonzero. This key has always been marked sensitive.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyExtractableType uint32; value is nonzero. This key can be wrapped.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyNeverExtractableType uint32; value is nonzero. This key was never marked extractable.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyEncryptType uint32; value is nonzero. This key can be used in an encrypt operation.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyDecryptType uint32; value is nonzero. This key can be used in a decrypt operation.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyDeriveType uint32; value is nonzero. This key can be used in a key derivation operation.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeySignType uint32, value is nonzero. This key can be used in a sign operation.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyVerifyType uint32, value is nonzero. This key can be used in a verify operation.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeySignRecoverType uint32.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyVerifyRecoverType uint32. This key can unwrap other keys.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyWrapType uint32; value is nonzero. This key can wrap other keys.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
kSecKeyUnwrapType uint32; value is nonzero. This key can unwrap other keys.
Available in Mac OS X v10.4 and later.
Declared in SecKey.h.
For attributes for items other than keys, see “Keychain Item Attribute Constants.”
Specifies a keychain item’s class code.
typedef FourCharCode SecItemClass;
enum
{
/* SecKeychainItem.h */
kSecInternetPasswordItemClass = 'inet',
kSecGenericPasswordItemClass = 'genp',
kSecAppleSharePasswordItemClass = 'ashp',
kSecCertificateItemClass =
CSSM_DL_DB_RECORD_X509_CERTIFICATE,
kSecPublicKeyItemClass =
CSSM_DL_DB_RECORD_PUBLIC_KEY,
kSecPrivateKeyItemClass =
CSSM_DL_DB_RECORD_PRIVATE_KEY,
kSecSymmetricKeyItemClass =
CSSM_DL_DB_RECORD_SYMMETRIC_KEY
};
enum
{
/* Record Type defined in The Open Group Application Name Space */
/* cssmtype.h */
CSSM_DL_DB_RECORD_ALL_KEYS =
CSSM_DB_RECORDTYPE_OPEN_GROUP_START + 8
};
kSecInternetPasswordItemClassIndicates that the item is an Internet password.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecGenericPasswordItemClassIndicates that the item is a generic password.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecAppleSharePasswordItemClassIndicates that the item is an AppleShare password.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecCertificateItemClassIndicates that the item is an X509 certificate.
Available in Mac OS X v10.2 and later.
Declared in SecKeychainItem.h.
kSecPublicKeyItemClassIndicates that the item is a public key of a public-private pair.
Available in Mac OS X v10.5 and later.
Declared in SecKeychainItem.h.
kSecPrivateKeyItemClassIndicates that the item is a private key of a public-private pair.
Available in Mac OS X v10.5 and later.
Declared in SecKeychainItem.h.
kSecSymmetricKeyItemClassIndicates that the item is a private key used for symmetric-key encryption.
Available in Mac OS X v10.5 and later.
Declared in SecKeychainItem.h.
CSSM_DL_DB_RECORD_ALL_KEYSThe item can be any type of key; used for searches only.
Available in Mac OS X v10.0 and later.
Declared in cssmtype.h.
These enumerations define 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.
SecKeychainItem.h, cssmtype.h.
Defines values for import and export flags.
enum
{
kSecItemPemArmour = 0x00000001,
};
typedef uint32_t SecItemImportExportFlags;
kSecItemPemArmourThe exported data should have PEM armour.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
This enumeration lists values used by the flags parameter of the functions SecKeychainItemExport and SecKeychainItemImport.
PEM armour refers to a way of expressing binary data as an ASCII string so that it can be transferred over text-only channels such as email. (PEM stands for an Internet standard, Privacy Enhanced Mail.)
Defines values for the flags field of the import/export parameters.
enum
{
kSecKeyImportOnlyOne = 0x00000001,
kSecKeySecurePassphrase = 0x00000002,
kSecKeyNoAccessControl = 0x00000004
};
typedef uint32_t SecKeyImportExportFlags;
kSecKeyImportOnlyOnePrevents the importing of more than one private key by the SecKeychainItemImport function. If the importKeychain parameter is NULL, this bit is ignored. Otherwise, if this bit is set and there is more than one key in the incoming external representation, no items are imported to the specified keychain and the error errSecMultipleKeys is returned.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecKeySecurePassphraseWhen set, the password for import or export is obtained by user prompt. (A password is sometimes referred to as a passphrase to emphasize the fact that a longer string that includes non-letter characters, such as numbers, punctuation, and spaces, is more secure than a simple word.) Otherwise, you must provide the password in the passphrase field of the SecKeyImportExportParameters structure. A user-supplied password is preferred, because it avoids having the cleartext password appear in the application’s address space at any time.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecKeyNoAccessControlWhen set, imported private keys have no access object attached to them. In the absence of both this bit and the accessRef field in SecKeyImportExportParameters, imported private keys are given default access controls.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
These flags are used as input to the import/export parameters structure (SecKeyImportExportParameters, which in turn is used as input to the functions SecKeychainItemExport and SecKeychainItemImport.
Specifies the format of an item after export from or before import to the keychain.
enum
{
kSecFormatUnknown = 0,
/* Asymmetric Key Formats */
kSecFormatOpenSSL,
kSecFormatSSH,
kSecFormatBSAFE,
kSecFormatSSHv2,
/* Symmetric Key Formats */
kSecFormatRawKey,
/* Formats for wrapped symmetric and private keys */
kSecFormatWrappedPKCS8,
kSecFormatWrappedOpenSSL,
kSecFormatWrappedSSH,
kSecFormatWrappedLSH, //not supported
/* Formats for certificates */
kSecFormatX509Cert,
/* Aggregate Types */
kSecFormatPEMSequence,
kSecFormatPKCS7,
kSecFormatPKCS12,
kSecFormatNetscapeCertSequence
};
typedef uint32_t SecExternalFormat;
kSecFormatUnknownWhen importing, indicates the format is unknown. When exporting, use the default format for the item. For asymmetric keys, the default is kSecFormatOpenSSL. For symmetric keys, the default is kSecFormatRawKey. For certificates, the default is kSecFormatX509Cert. For multiple items, the default is kSecFormatPEMSequence.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatOpenSSLFormat for asymmetric (public/private) keys. OpenSSL is an open source toolkit for Secure Sockets Layer (SSL) and Transport Layer Security (TLS). Also known as X.509 for public keys.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatSSHOpenSSH 1 format for asymmetric (public/private) keys. OpenSSH is an OpenBSD implementation of the Secure Shell (SSH) protocol.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatBSAFEFormat for asymmetric keys. BSAFE is a standard from RSA Security for encryption, digital signatures, and privacy.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatSSHv2OpenSSH 2 format for public keys. OpenSSH version 2 private keys are in format kSecFormatOpenSSL or kSecFormatWrappedOpenSSL. OpenSSH is an OpenBSD implementation of the Secure Shell (SSH) protocol.
Available in Mac OS X v10.5 and later.
Declared in SecImportExport.h.
kSecFormatRawKeyFormat for symmetric keys. Raw, unformatted key bits. This is the default for symmetric keys.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatWrappedPKCS8Format for wrapped symmetric and private keys. PKCS8 is the Private-Key Information Syntax Standard from RSA Security.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatWrappedOpenSSLFormat for wrapped symmetric and private keys. OpenSSL is an open-source toolkit for Secure Sockets Layer (SSL) and Transport Layer Security (TLS).
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatWrappedSSHOpenSSH 1 format for wrapped symmetric and private keys. OpenSSH is an OpenBSD implementation of the Secure Shell (SSH) protocol.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatWrappedLSHNot supported.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatX509CertFormat for certificates. DER (distinguished encoding rules) encoded. X.509 is a standard for digital certificates from the International Telecommunication Union (ITU). This is the default for certificates.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatPEMSequenceSequence of certificates and keys with PEM armour. PEM armour refers to a way of expressing binary data as an ASCII string so that it can be transferred over text-only channels such as email. This is the default format for multiple items.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatPKCS7Sequence of certificates, no PEM armour. PKCS7 is the Cryptographic Message Syntax Standard from RSA Security, Inc.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatPKCS12Set of certificates and private keys. PKCS12 is the Personal Information Exchange Syntax from RSA Security, Inc.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecFormatNetscapeCertSequenceSet of certificates in the Netscape Certificate Sequence format.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
Specifies the type of keychain item being imported.
enum {
kSecItemTypeUnknown, /* caller doesn't know what this is */
kSecItemTypePrivateKey,
kSecItemTypePublicKey,
kSecItemTypeSessionKey,
kSecItemTypeCertificate,
kSecItemTypeAggregate
};
typedef uint32_t SecExternalItemType;
kSecItemTypePrivateKeyIndicates a private key.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecItemTypePublicKeyIndicates a public key.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecItemTypeSessionKeyIndicates a session key.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecItemTypeCertificateIndicates a certificate.
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
kSecItemTypeAggregateIndicates a set of certificates or certificates and private keys, such as PKCS7, PKCS12, or kSecFormatPEMSequence formats (see “Keychain Item Import/Export Formats”).
Available in Mac OS X v10.4 and later.
Declared in SecImportExport.h.
Defines constants for the keychain preference domains.
typedef enum {
kSecPreferencesDomainUser,
kSecPreferencesDomainSystem,
kSecPreferencesDomainCommon,
kSecPreferencesDomainAlternate } SecPreferencesDomain;
kSecPreferencesDomainUserIndicates the user preference domain preferences.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecPreferencesDomainSystemIndicates the system or daemon preference domain preferences.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecPreferencesDomainCommonIndicates the preferences are common to everyone.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecPreferencesDomainAlternateIndicates an alternate preference domain preferences.
Available in Mac OS X v10.3 through Mac OS X v10.3.
Declared in SecKeychain.h.
A preference domain is a set of security-related preferences, such as the default keychain and the current keychain search list. The default preference domain for system daemons (that is, for daemons running in the root session) is the system domain. The default preference domain for all other programs is the user domain. A common preference appears for all users and the system; for example, if you add a keychain to the keychain search list using kSecPreferencesDomainCommon for the preference domain, the keychain is added to the search list for all users and the system.
Defines the protocol type associated with an AppleShare or Internet password.
typedef FourCharCode SecProtocolType;
enum
{
kSecProtocolTypeFTP = 'ftp ',
kSecProtocolTypeFTPAccount = 'ftpa',
kSecProtocolTypeHTTP = 'http',
kSecProtocolTypeIRC = 'irc ',
kSecProtocolTypeNNTP = 'nntp',
kSecProtocolTypePOP3 = 'pop3',
kSecProtocolTypeSMTP = 'smtp',
kSecProtocolTypeSOCKS = 'sox ',
kSecProtocolTypeIMAP = 'imap',
kSecProtocolTypeLDAP = 'ldap',
kSecProtocolTypeAppleTalk = 'atlk',
kSecProtocolTypeAFP = 'afp ',
kSecProtocolTypeTelnet = 'teln',
kSecProtocolTypeSSH = 'ssh ',
kSecProtocolTypeFTPS = 'ftps',
kSecProtocolTypeHTTPS = 'htps',
kSecProtocolTypeHTTPProxy = 'htpx',
kSecProtocolTypeHTTPSProx = 'htsx',
kSecProtocolTypeFTPProxy = 'ftpx',
kSecProtocolTypeCIFS = 'cifs',
kSecProtocolTypeSMB = 'smb ',
kSecProtocolTypeRTSP = 'rtsp',
kSecProtocolTypeRTSPProxy = 'rtsx',
kSecProtocolTypeDAAP = 'daap',
kSecProtocolTypeEPPC = 'eppc',
kSecProtocolTypeIPP = 'ipp ',
kSecProtocolTypeNNTPS = 'ntps',
kSecProtocolTypeLDAPS = 'ldps',
kSecProtocolTypeTelnetS = 'tels',
kSecProtocolTypeIMAPS = 'imps',
kSecProtocolTypeIRCS = 'ircs',
kSecProtocolTypePOP3S = 'pops',
kSecProtocolTypeCVSpserver = 'cvsp',
kSecProtocolTypeSVN = 'svn ',
kSecProtocolTypeAny = 0
};
kSecProtocolTypeFTPIndicates FTP.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeFTPAccountIndicates a client side FTP account. The usage of this constant is deprecated as of Mac OS X v10.3.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeHTTPIndicates HTTP.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeIRCIndicates IRC.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeNNTPIndicates NNTP.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypePOP3Indicates POP3.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeSMTPIndicates SMTP.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeSOCKSIndicates SOCKS.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeIMAPIndicates IMAP.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeLDAPIndicates LDAP.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeAppleTalkIndicates AFP over AppleTalk.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeAFPIndicates AFP over TCP.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeTelnetIndicates Telnet.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeSSHIndicates SSH.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecProtocolTypeFTPSIndicates FTP over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeHTTPSIndicates HTTP over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeHTTPProxyIndicates HTTP proxy.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeHTTPSProxyIndicates HTTPS proxy.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeFTPProxyIndicates FTP proxy.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeCIFSIndicates CIFS.
Available in Mac OS X v10.5 and later.
Declared in SecKeychain.h.
kSecProtocolTypeSMBIndicates SMB.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeRTSPIndicates RTSP.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeRTSPProxyIndicates RTSP proxy.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeDAAPIndicates DAAP.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeEPPCIndicates Remote Apple Events.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeIPPIndicates IPP.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeNNTPSIndicates NNTP over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeLDAPSIndicates LDAP over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeTelnetSIndicates Telnet over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeIMAPSIndicates IMAP4 over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeIRCSIndicates IRC over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypePOP3SIndicates POP3 over TLS/SSL.
Available in Mac OS X v10.3 and later.
Declared in SecKeychain.h.
kSecProtocolTypeCVSpserverIndicates CVS pserver.
Available in Mac OS X v10.5 and later.
Declared in SecKeychain.h.
kSecProtocolTypeSVNIndicates Subversion.
Available in Mac OS X v10.5 and later.
Declared in SecKeychain.h.
kSecProtocolTypeAnyIndicates that any protocol is acceptable.
When performing a search, use this constant to avoid constraining your search results to a particular protocol.
Available in Mac OS X v10.5 and later.
Declared in SecKeychain.h.
Defines the keychain settings version.
#define SEC_KEYCHAIN_SETTINGS_VERS1 1
SEC_KEYCHAIN_SETTINGS_VERS1Defines the keychain settings version.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
Defines the current status of a keychain.
typedef UInt32 SecKeychainStatus;
enum
{
kSecUnlockStateStatus = 1,
kSecReadPermStatus = 2,
kSecWritePermStatus = 4
};
kSecUnlockStateStatusIndicates the keychain is unlocked.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecReadPermStatusIndicates the keychain is readable.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
kSecWritePermStatusIndicates the keychain is writable.
Available in Mac OS X v10.2 and later.
Declared in SecKeychain.h.
You can use these masks in combination. For example, a keychain may be both readable and writable.
Constants used in a search dictionary to specify the class of items in the keychain. See SecItemCopyMatching for a description of a search dictionary.
Key constant used to set the item class value in a search dictionary.
CFTypeRef kSecClass;
kSecClassDictionary key whose value is the item's class code.
Possible values for this key are listed in “Item Class Value Constants.”
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
Values used with the kSecClass key in a search dictionary.
CFTypeRef kSecClassInternetPassword;
kSecClassInternetPasswordInternet password item.
The following attribute types (“Attribute Item Keys and Values”) can be used with an item of this type:
kSecAttrAccessGroup
kSecAttrCreationDate
kSecAttrModificationDate
kSecAttrDescription
kSecAttrComment
kSecAttrCreator
kSecAttrType
kSecAttrLabel
kSecAttrIsInvisible
kSecAttrIsNegative
kSecAttrAccount
kSecAttrSecurityDomain
kSecAttrServer
kSecAttrProtocol
kSecAttrAuthenticationType
kSecAttrPort
kSecAttrPath
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
You use keys in a search dictionary to specify the keychain items for which to search. You can specify a combination of item attributes and search attributes (see “Search Keys”) when looking for matching items with the SecItemCopyMatching function. This section lists all the keys that specify keychain item attributes. The description of each item indicates what the possible values are for that key. In a few cases, the programming interface provides a set of constants that you can use as values for a specific key. Those value constants are also in this section, following the descriptions of the keys.
Each type of keychain item can have a number of attributes describing that item. For the possible types of keychain item and the attributes that can be specified for each, see “Keychain Item Class Keys and Values.”
CFTypeRef kSecAttrCreationDate; CFTypeRef kSecAttrModificationDate; CFTypeRef kSecAttrDescription; CFTypeRef kSecAttrComment; CFTypeRef kSecAttrCreator; CFTypeRef kSecAttrType; CFTypeRef kSecAttrLabel; CFTypeRef kSecAttrIsInvisible; CFTypeRef kSecAttrIsNegative; CFTypeRef kSecAttrAccount; CFTypeRef kSecAttrService; CFTypeRef kSecAttrGeneric; CFTypeRef kSecAttrSecurityDomain; CFTypeRef kSecAttrServer; CFTypeRef kSecAttrProtocol; CFTypeRef kSecAttrAuthenticationType; CFTypeRef kSecAttrPort; CFTypeRef kSecAttrPath; CFTypeRef kSecAttrSubject; CFTypeRef kSecAttrIssuer; CFTypeRef kSecAttrSerialNumber; CFTypeRef kSecAttrSubjectKeyID; CFTypeRef kSecAttrPublicKeyHash; CFTypeRef kSecAttrCertificateType; CFTypeRef kSecAttrCertificateEncoding; CFTypeRef kSecAttrKeyClass; CFTypeRef kSecAttrApplicationLabel; CFTypeRef kSecAttrIsPermanent; CFTypeRef kSecAttrApplicationTag; CFTypeRef kSecAttrKeyType; CFTypeRef kSecAttrKeySizeInBits; CFTypeRef kSecAttrEffectiveKeySize; CFTypeRef kSecAttrCanEncrypt; CFTypeRef kSecAttrCanDecrypt; CFTypeRef kSecAttrCanDerive; CFTypeRef kSecAttrCanSign; CFTypeRef kSecAttrCanVerify; CFTypeRef kSecAttrCanWrap; CFTypeRef kSecAttrCanUnwrap;
kSecAttrCreationDateCreation date key.
The corresponding value is of type CFDateRef and represents the date the item was created. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrModificationDateModification date key.
The corresponding value is of type CFDateRef and represents the last time the item was updated. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrDescriptionDescription attribute key.
The corresponding value is of type CFStringRef and specifies a user-visible string describing this kind of item (for example, "Disk image password").
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCommentComment attribute key.
The corresponding value is of type CFStringRef and contains the user-editable comment for this item.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCreatorCreator attribute key.
The corresponding value is of type CFNumberRef and represents the item's creator. This number is the unsigned integer representation of a four-character code (for example, 'aCrt').
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrTypeType attribute key.
The corresponding value is of type CFNumberRef and represents the item's type. This number is the unsigned integer representation of a four-character code (for example, 'aTyp').
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrLabelLabel attribute key.
The corresponding value is of type CFStringRef and contains the user-visible label for this item.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrIsInvisibleInvisible attribute key.
The corresponding value is of type CFBooleanRef and is kCFBooleanTrue if the item is invisible (that is, should not be displayed).
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrIsNegativeNegative attribute key.
The corresponding value is of type CFBooleanRef and 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.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrAccountAccount attribute key.
The corresponding value is of type CFStringRef and contains an account name. Items of class kSecClassGenericPassword and kSecClassInternetPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrServiceService attribute key.
The corresponding value is a string of type CFStringRef that represents the service associated with this item. Items of class kSecClassGenericPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrGenericGeneric attribute key.
The corresponding value is of type CFDataRef and contains a user-defined attribute. Items of class kSecClassGenericPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrSecurityDomainSecurity domain attribute key.
The corresponding value is of type CFStringRef and represents the Internet security domain. Items of class kSecClassInternetPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrServerServer attribute key.
The corresponding value is of type CFStringRef and contains the server's domain name or IP address. Items of class kSecClassInternetPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolProtocol attribute key.
The corresponding value is of type CFNumberRef and denotes the protocol for this item (see “Protocol Values”). Items of class kSecClassInternetPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrAuthenticationTypeAuthentication type attribute key.
The corresponding value is of type CFNumberRef and denotes the authentication scheme for this item (see “Authentication Type Values”).
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrPortPort attribute key.
The corresponding value is of type CFNumberRef and represents an Internet port number. Items of class kSecClassInternetPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrPathPath attribute key.
The corresponding value is of type CFStringRef and represents a path, typically the path component of the URL. Items of class kSecClassInternetPassword have this attribute.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrSubjectSubject attribute key.
The corresponding value is of type CFDataRef and contains the X.500 subject name of a certificate. Items of class kSecClassCertificate have this attribute. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrIssuerIssuer attribute key.
The corresponding value is of type CFDataRef and contains the X.500 issuer name of a certificate. Items of class kSecClassCertificate have this attribute. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrSerialNumberSerial number attribute key.
The corresponding value is of type CFDataRef and contains the serial number data of a certificate. Items of class kSecClassCertificate have this attribute. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrSubjectKeyIDSubject key ID attribute key.
The corresponding value is of type CFDataRef and contains the subject key ID of a certificate. Items of class kSecClassCertificate have this attribute. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrPublicKeyHashPublic key hash attribute key.
The corresponding value is of type CFDataRef and contains the hash of a certificate's public key. Items of class kSecClassCertificate have this attribute. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCertificateTypeCertificate type attribute key.
The corresponding value is of type CFNumberRef and denotes the certificate type (see the CSSM_CERT_TYPE enumeration in cssmtype.h). Items of class kSecClassCertificate have this attribute. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCertificateEncodingCertificate encoding attribute key.
The corresponding value is of type CFNumberRef and denotes the certificate encoding (see the CSSM_CERT_ENCODING enumeration in cssmtype.h). Items of class kSecClassCertificate have this attribute. Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrKeyClassKey class attribute key.
The corresponding value is of type CFTypeRef and specifies a type of cryptographic key. Possible values are listed in “Key Class Values.” Read only.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrApplicationLabelApplication label attribute key.
The corresponding value is of type CFStringRef and contains a label for this item. This attribute is different from the kSecAttrLabel attribute, which is intended to be human-readable. This attribute is used to look up a key programmatically; in particular, for keys of class kSecAttrKeyClassPublic and kSecAttrKeyClassPrivate, the value of this attribute is the hash of the public key.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrIsPermanentPermanence attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key is to be stored permanently.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrApplicationTagPrivate tag attribute key.
The corresponding value is of type CFDataRef and contains private tag data.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrKeyTypeAlgorithm attribute key.
The corresponding value is of type CFNumberRef and indicates the algorithm associated with this cryptographic key (see the CSSM_ALGORITHMS enumeration in cssmtype.h and “Key Type Value”).
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrKeySizeInBitsNumber of bits attribute key.
The corresponding value is of type CFNumberRef and indicates the total number of bits in this cryptographic key. Compare with kSecAttrEffectiveKeySize.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrEffectiveKeySizeEffective number of bits attribute key.
The corresponding value is of type CFNumberRef and indicates the effective number of bits in this cryptographic key. For example, a DES key has a kSecAttrKeySizeInBits of 64, but a kSecAttrEffectiveKeySize of 56 bits.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCanEncryptEncryption attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to encrypt data.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCanDecryptDecryption attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to decrypt data.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCanDeriveDerivation attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to derive another key.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCanSignSignature attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to create a digital signature.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCanVerifySignature verification attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to verify a digital signature.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCanWrapWrap attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to wrap another key.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrCanUnwrapUnwrap attribute key.
The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to unwrap another key.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
These predefined item attribute keys are used to get or set values in a dictionary. Not all attributes apply to each item class.
Values that can be used with the kSecAttrProtocol attribute key.
CFTypeRef kSecAttrProtocolFTP; CFTypeRef kSecAttrProtocolFTPAccount; CFTypeRef kSecAttrProtocolHTTP; CFTypeRef kSecAttrProtocolIRC; CFTypeRef kSecAttrProtocolNNTP; CFTypeRef kSecAttrProtocolPOP3; CFTypeRef kSecAttrProtocolSMTP; CFTypeRef kSecAttrProtocolSOCKS; CFTypeRef kSecAttrProtocolIMAP; CFTypeRef kSecAttrProtocolLDAP; CFTypeRef kSecAttrProtocolAppleTalk; CFTypeRef kSecAttrProtocolAFP; CFTypeRef kSecAttrProtocolTelnet; CFTypeRef kSecAttrProtocolSSH; CFTypeRef kSecAttrProtocolFTPS; CFTypeRef kSecAttrProtocolHTTPS; CFTypeRef kSecAttrProtocolHTTPProxy; CFTypeRef kSecAttrProtocolHTTPSProxy; CFTypeRef kSecAttrProtocolFTPProxy; CFTypeRef kSecAttrProtocolSMB; CFTypeRef kSecAttrProtocolRTSP; CFTypeRef kSecAttrProtocolRTSPProxy; CFTypeRef kSecAttrProtocolDAAP; CFTypeRef kSecAttrProtocolEPPC; CFTypeRef kSecAttrProtocolIPP; CFTypeRef kSecAttrProtocolNNTPS; CFTypeRef kSecAttrProtocolLDAPS; CFTypeRef kSecAttrProtocolTelnetS; CFTypeRef kSecAttrProtocolIMAPS; CFTypeRef kSecAttrProtocolIRCS; CFTypeRef kSecAttrProtocolPOP3S;
kSecAttrProtocolFTPFTP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolFTPAccountA client side FTP account.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolHTTPHTTP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolIRCIRC protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolNNTPNNTP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolPOP3POP3 protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolSMTPSMTP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolSOCKSSOCKS protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolIMAPIMAP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolLDAPLDAP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolAppleTalkAFP over AppleTalk.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolAFPAFP over TCP.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolTelnetTelnet protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolSSHSSH protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolFTPSFTP over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolHTTPSHTTP over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolHTTPProxyHTTP proxy.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolHTTPSProxyHTTPS proxy.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolFTPProxyFTP proxy.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolSMBSMB protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolRTSPRTSP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolRTSPProxyRTSP proxy.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolDAAPDAAP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolEPPCRemote Apple Events.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolIPPIPP protocol.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolNNTPSNNTP over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolLDAPSLDAP over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolTelnetSTelnet over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolIMAPSIMAP over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolIRCSIRC over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrProtocolPOP3SPOP3 over TLS/SSL.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
Values that can be used with the kSecAttrAuthenticationType attribute key.
CFTypeRef kSecAttrAuthenticationTypeNTLM; CFTypeRef kSecAttrAuthenticationTypeMSN; CFTypeRef kSecAttrAuthenticationTypeDPA; CFTypeRef kSecAttrAuthenticationTypeRPA; CFTypeRef kSecAttrAuthenticationTypeHTTPBasic; CFTypeRef kSecAttrAuthenticationTypeHTTPDigest; CFTypeRef kSecAttrAuthenticationTypeHTMLForm; CFTypeRef kSecAttrAuthenticationTypeDefault;
kSecAttrAuthenticationTypeNTLMWindows NT LAN Manager authentication.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrAuthenticationTypeMSNMicrosoft Network default authentication.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrAuthenticationTypeDPADistributed Password authentication.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.
kSecAttrAuthenticationTypeRPARemote Password authentication.
Available in Mac OS X v10.6 and later.
Declared in SecItem.h.