Keychain Services Reference

Framework
Security/Security.h
Companion guide
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

Overview

Keychain Services is a programming interface that enables you to find, add, modify, and delete keychain items.

If you want to look at some code that uses this API, you can find the source code for the security command-line tool in the SecurityTool project on Apple's Open Source website.

Functions by Task

Using Keychain Item Search Dictionaries

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.

Getting Information About Security Result Codes

Getting Information About Keychain Services and Types

Creating and Deleting a Keychain

Managing Keychains

Locking and Unlocking Keychains

Managing User Interaction

Managing Keychain Access

Storing and Retrieving Passwords

Searching for Keychain Items

Creating and Deleting Keychain Items

Exporting and Importing Keychain Items

Managing Keychain Items

Creating an Access Object

Managing Access Objects

Managing Access Control List Objects

Managing Trusted Applications

Managing Preference Domains

CSSM Bridge Functions

Adding and Removing Callbacks

Functions

SecAccessCopyACLList

Retrieves all the access control list entries of a given access object.

OSStatus SecAccessCopyACLList (
   SecAccessRef accessRef,
   CFArrayRef *aclList
);
Parameters
accessRef

The access object from which to retrieve the information.

aclList

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecAccess.h

SecAccessCopyMatchingACLList

Retrieves selected access control lists from a given access object.

CFArrayRef SecAccessCopyMatchingACLList (
   SecAccessRef accessRef,
   CFTypeRef authorizationTag
);
Parameters
accessRef

The access object from which to retrieve the information.

authorizationTag

An access control list authorization tag; the function returns only those access control list entries that apply to the operation indicated by this tag. See CSSM Authorization Tag Type Constants for details.

Return Value

Returns an array containing the selected access control lists. You must call the CFRelease function to release this object when you are finished using it.

Discussion

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecAccess.h

SecAccessCopyOwnerAndACL

Retrieves the owner and the access control list of a given access object.

OSStatus SecAccessCopyOwnerAndACL (
   SecAccessRef accessRef,
   uid_t *userId,
   gid_t *groupId,
   SecAccessOwnerType *ownerType,
   CFArrayRef *aclList
);
Parameters
accessRef

An access object from which to retrieve the owner and access control list.

userId

On return, the user ID that owns the access object.

groupId

On return, the user ID that owns the access object.

ownerType

On return, flags that indicate whether the specified user ID or group ID owns the resulting access control list. See “SecAccessOwnerType” for details.

aclList

On return, an array of access control list entries associated with the access object.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecAccess.h

SecAccessCopySelectedACLList

Deprecated. Retrieves selected access control lists from a given access object.

OSStatus SecAccessCopySelectedACLList (
   SecAccessRef accessRef,
   CSSM_ACL_AUTHORIZATION_TAG action,
   CFArrayRef *aclList
);
Parameters
accessRef

The access object from which to retrieve the information.

action

An access control list authorization tag; the function returns only those access control list entries that apply to the operation indicated by this tag.

aclList

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecAccessCopyMatchingACLList instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecAccess.h

SecAccessCreate

Creates a new access object.

OSStatus SecAccessCreate (
   CFStringRef descriptor,
   CFArrayRef trustedlist,
   SecAccessRef *accessRef
);
Parameters
descriptor

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.

trustedlist

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.

accessRef

On return, points to the new access object. You must call the CFRelease function to release this object when you are finished using it.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecAccess.h

SecAccessCreateFromOwnerAndACL

Deprecated. Creates 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
);
Parameters
owner

A pointer to a CSSM access control list owner.

aclCount

An unsigned 32-bit integer representing the number of items in the access control list.

acls

A pointer to the CSSM access control list.

accessRef

On return, points to the new access object. You must call the CFRelease function to release this object when you are finished using it.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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).

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecAccessCreateWithOwnerAndACL instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecAccess.h

SecAccessCreateWithOwnerAndACL

Creates a new access object using the owner and access control list you provide.

SecAccessRef SecAccessCreateWithOwnerAndACL (
   uid_t userId,
   gid_t groupId,
   SecAccessOwnerType ownerType,
   CFArrayRef acls,
   CFErrorRef *error
);
Parameters
userId

The user ID that owns this access control list.

groupId

The group ID that owns this access control list.

ownerType

Flags that control whether the specified user ID or group ID owns the resulting access control list. See “SecAccessOwnerType” for details.

acls

An array of access control list entries to associate with the access object.

error

The address of a CFErrorRef variable. On error, the return value is NULL, and the variable referenced by this parameter is overwritten with a CFError object that provides more information.

Return Value

Returns the new access object. You must call the CFRelease function to release this object when you are finished using it.

Discussion

You can use this function to create an access object for use with other Certificate, Key, and Trust API functions if you want to create the access control list yourself. This allows more complex access controls than you can construct with the Certificate, Key, and Trust API.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecAccess.h

SecAccessGetOwnerAndACL

Deprecated. Retrieves 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
);
Parameters
accessRef

An access object from which to retrieve the owner and access control list.

owner

On return, a pointer to a CSSM access control list owner.

aclCount

On return, a pointer to an unsigned 32-bit integer representing the number of items in the access control list.

acls

On return, a pointer to the CSSM access control list.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

This function returns CSSM structures for use with CSSM API functions.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecAccessCreateWithOwnerAndACL instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecAccess.h

SecAccessGetTypeID

Returns the unique identifier of the opaque type to which a SecAccessRef object belongs.

CFTypeID SecAccessGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecAccessRef object.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecAccess.h

SecACLCopyAuthorizations

Retrieves the authorization tags of a given access control list entry.

CFArrayRef SecACLCopyAuthorizations (
   SecACLRef acl
);
Parameters
acl

An ACL object that identifies the access control list entry from which you wish to retrieve the authorization tags.

Return Value

Returns a CFArrayRef object containing the authorizations for this ACL.

Discussion

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 SecACLCopyContents 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.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecACL.h

SecACLCopyContents

Returns the application list, description, and prompt selector for a given access control list entry.

OSStatus SecACLCopyContents (
   SecACLRef acl,
   CFArrayRef *applicationList,
   CFStringRef *description,
   SecKeychainPromptSelector *promptSelector
);
Parameters
acl

An ACL object that identifies the access control list entry from which you want information.

applicationList

The address of a CFArrayRef variable into which a copy of the application list should be stored on return. This array will contain SecTrustedApplication instances identifying applications that are allowed access to the keychain item without user confirmation.

If the resulting CFArrayRef value is NULL, then any application can use this item. If the resulting array reference is a valid pointer to 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.

description

The address of a CFStringRef variable into which a copy of the description should be stored on return. This description is 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 name 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.

promptSelector

The address of a SecKeychainPromptSelector variable into which a copy of the prompt selector should be stored on return.

On return, points to the prompt selector flag for the given access control list entry. If the kSecKeychainPromptRequirePassphase 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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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 SecACLCopyAuthorizations function to get the list of operations for an ACL object.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecACL.h

SecACLCopySimpleContents

Deprecated. 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
);
Parameters
acl

An ACL object that identifies the access control list entry from which you want information.

applicationList

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.

description

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.

promptSelector

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecACLCopyContents instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecACL.h

SecACLCreateFromSimpleContents

Deprecated. 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
);
Parameters
access

The access object to which to add the information.

applicationList

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.

description

The human readable name to be used to refer to this item when the user is prompted.

promptSelector

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.

newAcl

On return, points to an access control list object, which is a reference to the new access control list entry.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecACLCreateWithSimpleContents instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecACL.h

SecACLCreateWithSimpleContents

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 SecACLCreateWithSimpleContents (
   SecAccessRef access,
   CFArrayRef applicationList,
   CFStringRef description,
   SecKeychainPromptSelector promptSelector,
   SecACLRef *newAcl
);
Parameters
access

The access object to which to add the information.

applicationList

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.

description

The human readable name to be used to refer to this item when the user is prompted.

promptSelector

A set of prompt selector flags. See “SecKeychainPromptSelector” for possible values.

newAcl

On return, the variable referenced by this parameter will contain an object representing the new access control list entry.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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 SecACLUpdateAuthorizations function to set the list of operations for an ACL object.

The system allows exactly one owner ACL entry in each access object. The SecACLCreateWithSimpleContents function fails if you attempt to add a second owner ACL. To change owner access controls, use the SecAccessCopyMatchingACLList function to find the owner ACL (that is, the only ACL with a CSSM authorization tag of CSSM_ACL_AUTHORIZATION_CHANGE_ACL) and the SecACLSetContents function to change it as needed.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecACL.h

SecACLGetAuthorizations

Deprecated. Retrieves the CSSM authorization tags of a given access control list entry.

OSStatus SecACLGetAuthorizations (
   SecACLRef acl,
   CSSM_ACL_AUTHORIZATION_TAG *tags,
   uint32 *tagCount
);
Parameters
acl

An ACL object that identifies the access control list entry from which you wish to retrieve the authorization tags.

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.

tagCount

On entry, 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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecACLCopyAuthorizations instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecACL.h

SecACLGetTypeID

Returns the unique identifier of the opaque type to which a SecACLRef object belongs.

CFTypeID SecACLGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecACLRef object.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecACL.h

SecACLRemove

Removes the specified access control list entry.

OSStatus SecACLRemove (
   SecACLRef aclRef
);
Parameters
aclRef

An ACL object that identifies the access control list entry to remove.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecACL.h

SecACLSetAuthorizations

Deprecated. Sets the CSSM authorization tags for a given access control list entry.

OSStatus SecACLSetAuthorizations (
   SecACLRef acl,
   CSSM_ACL_AUTHORIZATION_TAG *tags,
   uint32 tagCount
);
Parameters
acl

An ACL object that identifies the access control list entry for which you wish to set authorization tags.

tags

An array of CSSM authorization tags.

tagCount

The number of tags in the CSSM authorization tag array.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecACLUpdateAuthorizations instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecACL.h

SecACLSetContents

Sets the application list, description, and prompt selector for a given access control list entry.

OSStatus SecACLSetContents (
   SecACLRef acl,
   CFArrayRef applicationList,
   CFStringRef description,
   SecKeychainPromptSelector promptSelector
);
Parameters
acl

An ACL object that identifies the access control list entry.

applicationList

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 all applications are treated as untrusted.

description

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.

promptSelector

The prompt selector flags for the given access control list entry. See “SecKeychainPromptSelector” for details.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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 to call a separate function to write a modified ACL object back into the access object.

Use the SecACLCopyAuthorizations function to get the list of operations for an ACL object.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecACL.h

SecACLSetSimpleContents

Deprecated. 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
);
Parameters
acl

An ACL object that identifies the access control list entry.

applicationList

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 all applications are treated as untrusted.

description

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.

promptSelector

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecACLSetContents instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecACL.h

SecACLUpdateAuthorizations

Sets the authorization tags for a given access control list entry.

OSStatus SecACLUpdateAuthorizations (
   SecACLRef acl,
   CFArrayRef authorizations
);
Parameters
acl

An ACL object that identifies the access control list entry for which you wish to set authorization tags.

authorizations

An array of authorization tags. See CSSM Authorization Tag Type Constants for details.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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 SecACLSetContents 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 to call a separate function to write a modified ACL object back into the access object.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecACL.h

SecCopyErrorMessageString

Returns a string explaining the meaning of a security result code.

CFStringRef SecCopyErrorMessageString (
   OSStatus status,
   void *reserved
);
Parameters
status

A result code of type OSStatus or CSSM_RETURN, returned by a security or CSSM function.

reserved

Reserved for future use. Pass NULL for this parameter.

Return Value

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.

Availability
  • Available in OS X v10.5 and later.
Declared In
SecBase.h

SecItemAdd

Adds one or more items to a keychain.

OSStatus SecItemAdd (
   CFDictionaryRef attributes,
   CFTypeRef *result
);
Parameters
attributes

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.

result

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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 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.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecItem.h

SecItemCopyMatching

Returns one or more keychain items that match a search query, or copies attributes of specific keychain items.

OSStatus SecItemCopyMatching (
   CFDictionaryRef query,
   CFTypeRef *result
);
Parameters
query

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.

result

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

You specify attributes defining a search by adding key-value pairs to the query dictionary.

A typical query consists of:

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 return type is specified (for example, kSecReturnRef and kSecReturnAttributes), the results are 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 and provide as its value a CFArrayRef object containing items of type 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.

Availability
  • Available in OS X v10.6 and later.
Related Sample Code
Declared In
SecItem.h

SecItemDelete

Deletes items that match a search query.

OSStatus SecItemDelete (
   CFDictionaryRef query
);
Parameters
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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecItem.h

SecItemExport

Exports one or more certificates, keys, or identities.

OSStatus SecItemExport (
   CFTypeRef secItemOrArray,
   SecExternalFormat outputFormat,
   SecItemImportExportFlags flags,
   const SecItemImportExportKeyParameters *keyParams,
   CFDataRef *exportedData
);
Parameters
secItemOrArray

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.

outputFormat

The format of the desired external representation for 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.”

flags

A flag field indicating whether the exported item should have PEM armor. PEM armor 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 armoring.

keyParams

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. For more information, see SecItemImportExportKeyParameters.

exportedData

On return, the variable referenced by this argument is overwritten with a CFDataRef object containing the external representation of the keychain item or items. You are responsible for releasing this object by calling CFRelease.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecImportExport.h

SecItemImport

Converts an external representation of a keychain item or items into SecKeychainItem objects and optionally imports them into a specified keychain.

OSStatus SecItemImport (
   CFDataRef importedData,
   CFStringRef fileNameOrExtension,
   SecExternalFormat *inputFormat,
   SecExternalItemType *itemType,
   SecItemImportExportFlags flags,
   const SecItemImportExportKeyParameters *keyParams,
   SecKeychainRef importKeychain,
   CFArrayRef *outItems
);
Parameters
importedData

A CFDataRef object containing the data to import.

fileNameOrExtension

Optional. The name of the file from which the external representation was previously read, or if that is unknown, then the file extension (.p7r, for example). This serves as a hint for the key format and key type detection code.

inputFormat

Optional. The address of a SecExternalFormat variable.

If you know what format the external representation is in, you should set the initial value of this variable to an appropriate format constant (“Keychain Item Import/Export Formats”) to eliminate the need to detect the format. If not, set it to kSecFormatUnknown.

On return, the variable referenced by this argument is set to the format that the function actually detected.

Pass NULL if you neither know nor care what format the external representation is in.

itemType

Optional. The address of a SecExternalItemType variable.

Before calling this function, if you know what type of key the external representation contains, you should set the variable to an appropriate type constant (“Keychain Item Type When Importing”) to eliminate the need to detect the key type. If not, set it to kSecItemTypeUnknown.

On return, the variable referenced by this argument is set to the type of key that the function actually detected.

Pass NULL if you neither know nor care what key type the external representation contains.

flags

A set of import flags (“Keychain Item Import/Export Flags”).

Note that PEM formatting is determined internally via inspection of the incoming data, so the kSecItemPemArmour flag is ignored.

keyParams

A pointer to a structure containing a set of input parameters for the function. For more information, see SecItemImportExportKeyParameters.

importKeychain

Optional. The keychain into which the item should be imported. Pass NULL if you do not want to import the item into a keychain.

outItems

Optional. The address of a CFArrayRef variable that, upon return, will contain a list of keychain items. Pass NULL if you do not want a copy of these items.

Upon return, the referenced variable is overwritten by a new CFArrayRef array that contains SecKeychainItem objects, each of which may be a SecCertificateRef, SecKeyRef, or SecIdentityRef object. The caller is responsible for releasing this CFArrayRef object.

Note: When importing a PKCS12 blob, typically one SecIdentityRef object and zero or more additional SecCertificateRef objects are returned in outItems. No SecKeyRef objects are returned unless a key is found in the incoming blob that does not have a matching certificate.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

The SecItemImport function uses the fileNameOrExtension, inputFormat, and itemType parameters to help it interpret the incoming data. In most cases, SecItemImport can correctly interpret an external item if none of these are specified, but it is unwise for an application to count on that ability.

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecImportExport.h

SecItemUpdate

Modifies items that match a search query.

OSStatus SecItemUpdate (
   CFDictionaryRef query,
   CFDictionaryRef attributesToUpdate
);
Parameters
query

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.

attributesToUpdate

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

See the discussion section of the SecItemCopyMatching function for information about how to construct a search dictionary.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecItem.h

SecKeychainAddCallback

Registers your keychain event callback function

OSStatus SecKeychainAddCallback (
   SecKeychainCallback callbackFunction,
   SecKeychainEventMask eventMask,
   void *userContext
);
Parameters
callbackFunction

A pointer to your keychain event callback function, described in SecKeychainCallback.

eventMask

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.

userContext

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainAddGenericPassword

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
);
Parameters
keychain

A reference to the keychain in which to store a generic password. Pass NULL to specify the default keychain.

serviceNameLength

The length of the serviceName character string.

serviceName

A UTF-8 encoded character string representing the service name.

accountNameLength

The length of the accountName character string.

accountName

A UTF-8 encoded character string representing the account name.

passwordLength

The length of the passwordData buffer.

passwordData

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.

itemRef

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.

Return Value

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 (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainAddInternetPassword

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
);
Parameters
keychain

A reference to the keychain in which to store an Internet password. Pass NULL to specify the user’s default keychain.

serverNameLength

The length of the serverName character string.

serverName

A UTF-8 encoded character string representing the server name.

securityDomainLength

The length of the securityDomain character string.

securityDomain

A UTF-8 encoded character string representing the security domain. This parameter is optional. Pass NULL if the protocol does not require it.

accountNameLength

The length of the accountName character string.

accountName

A UTF-8 encoded character string representing the account name.

pathLength

The length of the path character string.

path

A UTF-8 encoded character string representing the path.

port

The TCP/IP port number. If no specific port number is associated with this password, pass 0.

protocol

The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values.

authenticationType

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.

passwordLength

The length of the passwordData buffer.

passwordData

A pointer to a buffer containing the password data to be stored in the keychain.

itemRef

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.

Return Value

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 (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainAttributeInfoForItemID

Obtains tags for all possible attributes of a given item class.

OSStatus SecKeychainAttributeInfoForItemID (
   SecKeychainRef keychain,
   UInt32 itemID,
   SecKeychainAttributeInfo **info
);
Parameters
keychain

A keychain object.

itemID

The relation identifier of the item tags. An itemID is a CSSM_DB_RECORDTYPE type as defined in cssmtype.h.

info

On return, a pointer to the keychain attribute information. Your application should call the SecKeychainFreeAttributeInfo function to release this structure when done with it.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainCopyAccess

Retrieves the application access of a keychain.

OSStatus SecKeychainCopyAccess (
   SecKeychainRef keychain,
   SecAccessRef *access
);
Parameters
keychain

A reference to the keychain from which to copy the access object. Pass NULL to specify the default keychain.

access

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Special Considerations

Although this function is available in OS X v10.2, it was unimplemented before OS X v10.3 and returned an errSecUnimplemented error code if called.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainCopyDefault

Retrieves a pointer to the default keychain.

OSStatus SecKeychainCopyDefault (
   SecKeychainRef *keychain
);
Parameters
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.

Return Value

A result code. See “Keychain Services Result Codes.” The result code errSecNoDefaultKeychain indicates that there is no default keychain. Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainCopyDomainDefault

Retrieves the default keychain from a specified preference domain.

OSStatus SecKeychainCopyDomainDefault (
   SecPreferencesDomain domain,
   SecKeychainRef *keychain
);
Parameters
domain

The preference domain from which you wish to retrieve the default keychain. See “Keychain Preference Domain Constants” for possible domain values.

keychain

On return, a pointer to the keychain object of the default keychain in the specified preference domain.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecKeychain.h

SecKeychainCopyDomainSearchList

Retrieves the keychain search list for a specified preference domain.

OSStatus SecKeychainCopyDomainSearchList (
   SecPreferencesDomain domain,
   CFArrayRef *searchList
);
Parameters
domain

The preference domain from which you wish to retrieve the keychain search list. See “Keychain Preference Domain Constants” for possible domain values.

searchList

On return, a pointer to the keychain search list of the specified preference domain.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecKeychain.h

SecKeychainCopySearchList

Retrieves a keychain search list.

OSStatus SecKeychainCopySearchList (
   CFArrayRef *searchList
);
Parameters
searchList

On return, the returned keychain search list. You must call the CFRelease function to release this object when you are finished using it.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainCopySettings

Obtains a keychain’s settings.

OSStatus SecKeychainCopySettings (
   SecKeychainRef keychain,
   SecKeychainSettings *outSettings
);
Parameters
keychain

A reference to the keychain from which to copy its settings.

outSettings

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainCreate

Creates an empty keychain.

OSStatus SecKeychainCreate (
   const char *pathName,
   UInt32 passwordLength,
   const void *password,
   Boolean promptUser,
   SecAccessRef initialAccess,
   SecKeychainRef *keychain
);
Parameters
pathName

A constant character string representing the POSIX path indicating where to store the keychain.

passwordLength

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.

password

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.

promptUser

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.

initialAccess

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.

keychain

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainDelete

Deletes one or more keychains from the default keychain search list, and removes the keychain itself if it is a file.

OSStatus SecKeychainDelete (
   SecKeychainRef keychainOrArray
);
Parameters
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 OS X v10.3 and later, passing NULL to this parameter returns an errSecInvalidKeychain error code. In 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.

Return Value

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 (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainFindGenericPassword

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
);
Parameters
keychainOrArray

A reference to an array of keychains to search, a single keychain, or NULL to search the user’s default keychain search list.

serviceNameLength

The length of the serviceName character string.

serviceName

A UTF-8 encoded character string representing the service name.

accountNameLength

The length of the accountName character string.

accountName

A UTF-8 encoded character string representing the account name.

passwordLength

On return, the length of the buffer pointed to by passwordData.

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.

itemRef

On return, a pointer to the item object of the generic password. You are responsible for releasing your reference to this object. Pass NULL if you don’t want to obtain this object.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainFindInternetPassword

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
);
Parameters
keychainOrArray

A reference to an array of keychains to search, a single keychain or NULL to search the user’s default keychain search list.

serverNameLength

The length of the serverName character string.

serverName

A UTF-8 encoded character string representing the server name.

securityDomainLength

The length of the securityDomain character string.

securityDomain

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.

accountNameLength

The length of the accountName character string.

accountName

A UTF-8 encoded character string representing the account name.

pathLength

The length of the path character string.

path

A UTF-8 encoded character string representing the path.

port

The TCP/IP port number. Pass 0 to ignore the port number.

protocol

The protocol associated with this password. See “Keychain Protocol Type Constants” for a description of possible values.

authenticationType

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.

passwordLength

On return, the length of the buffer pointed to by passwordData.

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.

itemRef

On return, a pointer to the item object of the Internet password. You are responsible for releasing your reference to this object. Pass NULL if you don’t want to obtain this object.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainFreeAttributeInfo

Releases the memory acquired by calling the SecKeychainAttributeInfoForItemID function.

OSStatus SecKeychainFreeAttributeInfo (
   SecKeychainAttributeInfo *info
);
Parameters
info

A pointer to the keychain attribute information to release.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainGetCSPHandle

Returns the CSSM CSP handle for the given keychain object.

OSStatus SecKeychainGetCSPHandle (
   SecKeychainRef keychain,
   CSSM_CSP_HANDLE *cspHandle
);
Parameters
keychain

A keychain object.

cspHandle

On return, a pointer to the CSSM CSP handle for the given keychain. The handle is valid until the keychain object is released.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKeychain.h

SecKeychainGetDLDBHandle

Returns the CSSM database handle for a given keychain object.

OSStatus SecKeychainGetDLDBHandle (
   SecKeychainRef keychain,
   CSSM_DL_DB_HANDLE *dldbHandle
);
Parameters
keychain

A keychain object.

dldbHandle

On return, a pointer to the CSSM database handle for the given keychain. The handle is valid until the keychain object is released.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKeychain.h

SecKeychainGetPath

Determines the path of a keychain.

OSStatus SecKeychainGetPath (
   SecKeychainRef keychain,
   UInt32 *ioPathLength,
   char *pathName
);
Parameters
keychain

A reference to a keychain whose path you wish to obtain.

ioPathLength

On entry, a pointer to a variable containing the length (in bytes) of the buffer specified by pathName.

On return, the string length of pathName, not including the null termination.

pathName

On entry, a pointer to a buffer that you have allocated. On return, the buffer contains POSIX path of the keychain as a null-terminated UTF-8 encoded string. The function returns errSecBufferTooSmall if the provided buffer is too small to hold the string with the null terminator byte.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainGetPreferenceDomain

Gets the current keychain preference domain.

OSStatus SecKeychainGetPreferenceDomain (
   SecPreferencesDomain *domain
);
Parameters
domain

On return, a pointer to the keychain preference domain. See “Keychain Preference Domain Constants” for possible domain values.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecKeychain.h

SecKeychainGetStatus

Retrieves status information of a keychain.

OSStatus SecKeychainGetStatus (
   SecKeychainRef keychain,
   SecKeychainStatus *keychainStatus
);
Parameters
keychain

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.

keychainStatus

On return, a pointer to the status of the specified keychain. See “Keychain Status Masks” for valid status constants.

Return Value

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 (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainGetTypeID

Returns the unique identifier of the opaque type to which a SecKeychainRef object belongs.

CFTypeID SecKeychainGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecKeychainRef object.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainGetUserInteractionAllowed

Indicates whether Keychain Services functions that normally display a user interaction are allowed to do so.

OSStatus SecKeychainGetUserInteractionAllowed (
   Boolean *state
);
Parameters
state

On return, 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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainGetVersion

Determines the version of Keychain Services installed on the user’s system.

OSStatus SecKeychainGetVersion (
   UInt32 *returnVers
);
Parameters
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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

Your application can call the SecKeychainGetVersion function to find out which version of Keychain Services is installed on the user’s system.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainItemCopyAccess

Copies the access of a given keychain item.

OSStatus SecKeychainItemCopyAccess (
   SecKeychainItemRef itemRef,
   SecAccessRef *access
);
Parameters
itemRef

A reference to a keychain item.

access

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemCopyAttributesAndData

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
);
Parameters
itemRef

A reference to the keychain item from which you wish to retrieve data or attributes.

info

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.

itemClass

On return, the item’s class. Pass NULL if not required. See “Keychain Item Class Constants” for valid constants.

attrList

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.

length

On return, the actual length of the data returned in the outData parameter.

outData

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemCopyContent

Copies the data and attributes stored in the given keychain item.

OSStatus SecKeychainItemCopyContent (
   SecKeychainItemRef itemRef,
   SecItemClass *itemClass,
   SecKeychainAttributeList *attrList,
   UInt32 *length,
   void **outData
);
Parameters
itemRef

A reference to the keychain item to modify.

itemClass

On return, points to the item’s class. Pass NULL if it is not required. See “Keychain Item Class Constants” for valid constants.

attrList

On entry, the list of attributes to get in this item; on return 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.

length

On return, the length of the buffer pointed to by the outData parameter.

outData

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemCopyFromPersistentReference

Provides a keychain item reference, given a persistent reference.

OSStatus SecKeychainItemCopyFromPersistentReference (
   CFDataRef persistentItemRef,
   SecKeychainItemRef *itemRef
);
Parameters
persistentItemRef

A persistent reference for a keychain item.

itemRef

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

A persistent reference may be stored on disk or passed between processes. You use the SecKeychainItemCreatePersistentReference function to create a persistent reference.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecKeychainItem.h

SecKeychainItemCopyKeychain

Returns the keychain object of a given keychain item.

OSStatus SecKeychainItemCopyKeychain (
   SecKeychainItemRef itemRef,
   SecKeychainRef *keychainRef
);
Parameters
itemRef

A keychain item object.

keychainRef

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemCreateCopy

Copies a keychain item from one keychain to another.

OSStatus SecKeychainItemCreateCopy (
   SecKeychainItemRef itemRef,
   SecKeychainRef destKeychainRef,
   SecAccessRef initialAccess,
   SecKeychainItemRef *itemCopy
);
Parameters
itemRef

A reference to the keychain item to copy.

destKeychainRef

A reference to the keychain in which to insert the copied keychain item. Pass NULL to specify the default keychain.

initialAccess

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.

itemCopy

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemCreateFromContent

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
);
Parameters
itemClass

A constant identifying the class of item to create. See “Keychain Item Class Constants” for valid constants.

attrList

A pointer to the list of attributes for the item to create.

length

The length of the buffer pointed to by the data parameter.

data

A pointer to a buffer containing the data to store.

keychainRef

A reference to the keychain in which to add the item. Pass NULL to specify the default keychain.

initialAccess

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.

itemRef

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemCreatePersistentReference

Creates a persistent reference for a keychain item.

OSStatus SecKeychainItemCreatePersistentReference (
   SecKeychainItemRef itemRef,
   CFDataRef *persistentItemRef
);
Parameters
itemRef

A keychain item reference for the item for which you want a persistent reference.

persistentItemRef

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
SecKeychainItem.h

SecKeychainItemDelete

Deletes a keychain item from the default keychain’s permanent data store.

OSStatus SecKeychainItemDelete (
   SecKeychainItemRef itemRef
);
Parameters
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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemExport

Deprecated. Exports one or more certificates, keys, or identities.

OSStatus SecKeychainItemExport (
   CFTypeRef keychainItemOrArray,
   SecExternalFormat outputFormat,
   SecItemImportExportFlags flags,
   const SecKeyImportExportParameters *keyParams,
   CFDataRef *exportedData
);
Parameters
keychainItemOrArray

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.

outputFormat

The format of the desired external representation for 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.”

flags

A flag indicating whether the exported item should have PEM armor. PEM armor 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 armoring.

keyParams

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.

exportedData

On return, points to the external representation of the keychain item or items.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecItemExport instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecImportExport.h

SecKeychainItemFreeAttributesAndData

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
);
Parameters
attrList

A pointer to the attribute list to release. Pass NULL if there is no attribute list to release.

data

A pointer to the data buffer to release. Pass NULL if there is no data to release.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemFreeContent

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
);
Parameters
attrList

A pointer to the attribute list to release. Pass NULL if there is no attribute list to release.

data

A pointer to the data buffer to release. Pass NULL if there is no data to release.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemGetDLDBHandle

Returns the CSSM database handle for a given keychain item object.

OSStatus SecKeychainItemGetDLDBHandle (
   SecKeychainItemRef keyItemRef,
   CSSM_DL_DB_HANDLE *dldbHandle
);
Parameters
keyItemRef

A keychain item object.

dldbHandle

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKeychainItem.h

SecKeychainItemGetTypeID

Returns the unique identifier of the opaque type to which a SecKeychainItemRef object belongs.

CFTypeID SecKeychainItemGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecKeychainItemRef object.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemGetUniqueRecordID

Returns a CSSM unique record for the given keychain item object.

OSStatus SecKeychainItemGetUniqueRecordID (
   SecKeychainItemRef itemRef,
   const CSSM_DB_UNIQUE_RECORD **uniqueRecordID
);
Parameters
itemRef

A keychain item object.

uniqueRecordID

On return, a pointer to a CSSM unique record for the given item. The unique record is valid until the item object is released.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKeychainItem.h

SecKeychainItemImport

Deprecated. 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
);
Parameters
importedData

The external representation of the items to import.

fileNameOrExtension

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.

inputFormat

On entry, points to the format of the external representation. Pass kSecFormatUnknown if you do not know the exact format. On return, 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. For a list of formats, see “Keychain Item Import/Export Formats.”

itemType

On entry, 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 return, 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.

flags

Unused; pass in 0.

keyParams

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.”

importKeychain

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.

outItems

On return, 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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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 armored 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.

Special Considerations

This function is deprecated in OS X v10.7 and later; use SecItemImport instead.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecImportExport.h

SecKeychainItemModifyAttributesAndData

Updates an existing keychain item after changing its attributes or data.

OSStatus SecKeychainItemModifyAttributesAndData (
   SecKeychainItemRef itemRef,
   const SecKeychainAttributeList *attrList,
   UInt32 length,
   const void *data
);
Parameters
itemRef

A reference to the keychain item to modify.

attrList

A pointer to the list of attributes to modify and their new values. Pass NULL if you have no need to modify attributes.

length

The length of the buffer pointed to by the data parameter. Pass 0 if you pass NULL in the data parameter.

data

A pointer to a buffer containing the data to store. Pass NULL if you do not need to modify the data.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

The keychain item is written to the keychain’s permanent data store. If the keychain item has not previously been added to a keychain, a call to 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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemModifyContent

Updates an existing keychain item after changing its attributes and/or data.

OSStatus SecKeychainItemModifyContent (
   SecKeychainItemRef itemRef,
   const SecKeychainAttributeList *attrList,
   UInt32 length,
   const void *data
);
Parameters
itemRef

A reference to the keychain item to modify.

attrList

A pointer to the list of attributes to set and their new values. Pass NULL if you have no need to modify attributes.

length

The length of the buffer pointed to by the data parameter. Pass 0 if you pass NULL in the data parameter.

data

A pointer to a buffer containing the data to store. Pass NULL if you do not need to modify the data.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

The keychain item is written to the keychain’s permanent data store.

If the keychain item has not previously been added to a keychain, a call to 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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainItemSetAccess

Sets the access of a given keychain item.

OSStatus SecKeychainItemSetAccess (
   SecKeychainItemRef itemRef,
   SecAccessRef access
);
Parameters
itemRef

A reference to a keychain item.

access

An access object to replace the keychain item’s current access object. Use the SecAccessCreate function to create an access object.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainLock

Locks a keychain.

OSStatus SecKeychainLock (
   SecKeychainRef keychain
);
Parameters
keychain

A reference to the keychain to lock. Pass NULL to lock the default keychain.

Return Value

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 (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainLockAll

Locks all keychains belonging to the current user.

OSStatus SecKeychainLockAll (
   void
);
Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainOpen

Opens a keychain.

OSStatus SecKeychainOpen (
   const char *pathName,
   SecKeychainRef *keychain
);
Parameters
pathName

A constant character string representing the POSIX path to the keychain to open.

keychain

On return, a pointer to the keychain object. You must call the CFRelease function to release this object when you are finished using it.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainRemoveCallback

Unregisters your keychain event callback function.

OSStatus SecKeychainRemoveCallback (
   SecKeychainCallback callbackFunction
);
Parameters
callbackFunction

The callback function pointer to remove.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

Once removed, keychain events are not sent to the owner of the callback.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainSearchCopyNext

Finds the next keychain item matching the given search criteria.

OSStatus SecKeychainSearchCopyNext (
   SecKeychainSearchRef searchRef,
   SecKeychainItemRef *itemRef
);
Parameters
searchRef

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.

itemRef

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.

Return Value

A result code. When there are no more items that match, errSecItemNotFound is returned. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKeychainSearch.h

SecKeychainSearchCreateFromAttributes

Creates a search object matching a list of zero or more attributes.

OSStatus SecKeychainSearchCreateFromAttributes (
   CFTypeRef keychainOrArray,
   SecItemClass itemClass,
   const SecKeychainAttributeList *attrList,
   SecKeychainSearchRef *searchRef
);
Parameters
keychainOrArray

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.

itemClass

The keychain item class. See “Keychain Item Class Constants” for valid constants.

attrList

A pointer to a list of zero or more keychain attribute records to match. Pass NULL to match any keychain attribute.

searchRef

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKeychainSearch.h

SecKeychainSearchGetTypeID

Returns the unique identifier of the opaque type to which a SecKeychainSearchRef object belongs.

CFTypeID SecKeychainSearchGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecKeychainSearchRef object.

Discussion

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
SecKeychainSearch.h

SecKeychainSetAccess

Sets the application access for a keychain.

OSStatus SecKeychainSetAccess (
   SecKeychainRef keychain,
   SecAccessRef access
);
Parameters
keychain

A reference to the keychain for which to set the access. Pass NULL to specify the default keychain.

access

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

In addition to the ACLs for individual keychain items, the keychain itself has ACLs. However, they are currently unused and this function is unimplemented.

Special Considerations

Although this function is available in OS X v10.2 and later, it is unimplemented and returns an errSecUnimplemented error code if called.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainSetDefault

Sets the default keychain.

OSStatus SecKeychainSetDefault (
   SecKeychainRef keychain
);
Parameters
keychain

A reference to the keychain you wish to make the default.

Return Value

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 (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainSetDomainDefault

Sets the default keychain for a specified preference domain.

OSStatus SecKeychainSetDomainDefault (
   SecPreferencesDomain domain,
   SecKeychainRef keychain
);
Parameters
domain

The preference domain for which you wish to set the default keychain. See “Keychain Preference Domain Constants” for possible domain values.

keychain

A reference to the keychain you wish to set as default in the specified preference domain.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecKeychain.h

SecKeychainSetDomainSearchList

Sets the keychain search list for a specified preference domain.

OSStatus SecKeychainSetDomainSearchList (
   SecPreferencesDomain domain,
   CFArrayRef searchList
);
Parameters
domain

The preference domain for which you wish to set the default keychain search list. See “Keychain Preference Domain Constants”for possible domain values.

searchList

A pointer to a keychain search list to set in the preference domain.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecKeychain.h

SecKeychainSetPreferenceDomain

Sets the keychain preference domain.

OSStatus SecKeychainSetPreferenceDomain (
   SecPreferencesDomain domain
);
Parameters
domain

The keychain preference domain to set. See “Keychain Preference Domain Constants” for possible domain values.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
SecKeychain.h

SecKeychainSetSearchList

Specifies the list of keychains to use in the default keychain search list.

OSStatus SecKeychainSetSearchList (
   CFArrayRef searchList
);
Parameters
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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainSetSettings

Changes the settings of a keychain.

OSStatus SecKeychainSetSettings (
   SecKeychainRef keychain,
   const SecKeychainSettings *newSettings
);
Parameters
keychain

A reference to a keychain whose settings you wish to change. Pass NULL to change the settings of the default keychain.

newSettings

A pointer to a keychain settings structure that defines whether the keychain locks when sleeping, or locks after a set time period of inactivity.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainSetUserInteractionAllowed

Enables or disables the user interface for Keychain Services functions that automatically display a user interface.

OSStatus SecKeychainSetUserInteractionAllowed (
   Boolean state
);
Parameters
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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Special Considerations

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainUnlock

Unlocks a keychain.

OSStatus SecKeychainUnlock (
   SecKeychainRef keychain,
   UInt32 passwordLength,
   const void *password,
   Boolean usePassword
);
Parameters
keychain

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.

passwordLength

An unsigned 32-bit integer representing the length of the password buffer.

password

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 prompt the user for the keychain password.

usePassword

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.

Return Value

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 (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecTrustedApplicationCopyData

Retrieves the data of a trusted application object.

OSStatus SecTrustedApplicationCopyData (
   SecTrustedApplicationRef appRef,
   CFDataRef *data
);
Parameters
appRef

A trusted application object from which to retrieve data. Use the SecTrustedApplicationCreateFromPath function to create a trusted application object.

data

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecTrustedApplication.h

SecTrustedApplicationCreateFromPath

Creates a trusted application object based on the application specified by path.

OSStatus SecTrustedApplicationCreateFromPath (
   const char *path,
   SecTrustedApplicationRef *app
);
Parameters
path

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.

app

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.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecTrustedApplication.h

SecTrustedApplicationGetTypeID

Returns the unique identifier of the opaque type to which a SecTrustedApplication object belongs.

CFTypeID SecTrustedApplicationGetTypeID (
   void
);
Return Value

A value that identifies the opaque type of a SecTrustedApplicationRef object.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecTrustedApplication.h

SecTrustedApplicationSetData

Sets the data of a given trusted application object.

OSStatus SecTrustedApplicationSetData (
   SecTrustedApplicationRef appRef,
   CFDataRef data
);
Parameters
appRef

A trusted application object.

data

A reference to the data to set in the trusted application.

Return Value

A result code. See “Keychain Services Result Codes.” Call SecCopyErrorMessageString (OS X only) to get a human-readable string explaining the result.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecTrustedApplication.h

Callbacks

SecKeychainCallback

Defines 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
);

Parameters
keychainEvent

The keychain event that occurred. The type of event that can trigger your callback depends on the bit mask you passed in the eventMask parameter of the function SecKeychainAddCallback.

info

A pointer to a structure of type SecKeychainCallbackInfo. This structure provides your callback with information about the keychain event.

context

A pointer to application-defined storage that your application previously passed to the function SecKeychainAddCallback. You can use this value to provide information that the callback function needs in order to properly handle the event, such as an object on which the callback function should call a method.

Return Value

A result code. See “Keychain Services Result Codes.”

Discussion

To add your callback function, use the SecKeychainAddCallback function. To remove your callback function, use the SecKeychainRemoveCallback function.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

Data Types

SecAccessRef

Identifies a keychain or keychain item’s access information.

typedef struct OpaqueSecAccessRef *SecAccessRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecACLRef

Represents information about an access control list entry.

typedef struct OpaqueSecTrustRef *SecACLRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecAFPServerSignature

Represents a 16-byte Apple File Protocol server signature block.

typedef UInt8 SecAFPServerSignature[16];
Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychainItem.h

SecKeychainAttribute

Contains keychain attributes.

struct SecKeychainAttribute
{
SecKeychainAttrType tag;
UInt32 length;
void *data;
};
typedef struct SecKeychainAttribute SecKeychainAttribute;
Fields
tag

A 4-byte attribute tag. See “Keychain Item Attribute Constants” for valid attribute types.

length

The length of the buffer pointed to by data.

data

A pointer to the attribute data.

Availability
  • Available in OS X v10.0 and later.
Declared In
SecBase.h

SecKeychainAttributePtr

Represents a pointer to a keychain attribute structure.

typedef SecKeychainAttribute *SecKeychainAttributePtr;
Availability
  • Available in OS X v10.0 and later.
Declared In
SecBase.h

SecKeychainAttributeInfo

Represents an attribute.

struct SecKeychainAttributeInfo
{
UInt32 count;
UInt32 *tag;
UInt32 *format;
};
typedef struct SecKeychainAttributeInfo SecKeychainAttributeInfo;
Fields
count

The number of tag-format pairs in the respective arrays.

tag

A pointer to the first attribute tag in the array.

format

A pointer to the first attribute format in the array. Attribute formats are of type CSSM_DB_ATTRIBUTE_FORMAT (CSSM_DB_ATTRIBUTE_FORMAT_STRING, for example), and are defined in the cssmtype.h header.

Discussion

Each tag and format item form a pair.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecKeychainAttributeList

Represents a list of keychain attributes.

struct SecKeychainAttributeList
{
UInt32 count;
SecKeychainAttribute *attr;
};
typedef struct SecKeychainAttributeList SecKeychainAttributeList;
Fields
count

An unsigned 32-bit integer that represents the number of keychain attributes in the array.

attr

A pointer to the first keychain attribute in the array.

Availability
  • Available in OS X v10.0 and later.
Declared In
SecBase.h

SecKeychainAttrType

Represents a keychain attribute type.

typedef OSType SecKeychainAttrType;
Availability
  • Available in OS X v10.0 and later.
Declared In
SecBase.h

SecKeychainCallbackInfo

Contains information about a keychain event.

struct SecKeychainCallbackInfo
{
UInt32 version;
SecKeychainItemRef item;
SecKeychainRef keychain;
pid_t pid;
};
typedef struct SecKeychainCallbackInfo SecKeychainCallbackInfo;
Fields
version

The version of this structure. See “Keychain Settings Version” for valid constants.

item

A reference to the keychain item in which the event occurred. If the event did not involve an item, this field is not valid.

keychain

A reference to the keychain in which the event occurred. If the event did not involve a keychain, this field is not valid.

pid

The ID of the process that generated this event.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeychainItemRef

Contains information about a keychain item.

typedef struct OpaqueSecKeychainItemRef *SecKeychainItemRef;
Discussion

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
SecBase.h

SecKeychainRef

Contains information about a keychain.

typedef struct OpaqueSecKeychainRef *SecKeychainRef;
Availability
  • Available in OS X v10.0 and later.
Declared In
SecBase.h

SecKeychainSearchRef

Contains information about a keychain search.

typedef struct OpaqueSecKeychainSearchRef *SecKeychainSearchRef;
Availability
  • Available in OS X v10.0 and later.
Declared In
SecBase.h

SecKeychainSettings

Contains information about keychain settings.

struct SecKeychainSettings
{
UInt32          version;
Boolean         lockOnSleep;
Boolean         useLockInterval;
UInt32          lockInterval;
};
typedef struct SecKeychainSettings    SecKeychainSettings;
Fields
version

An unsigned 32-bit integer representing the keychain version.

lockOnSleep

A Boolean value indicating whether the keychain locks when the system sleeps.

useLockInterval

A Boolean value indicating whether the keychain automatically locks after a certain period of time.

lockInterval

An 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.

Discussion

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
SecKeychain.h

SecKeyImportExportParameters

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;
Fields
version

The version of this structure; the current value is SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION.

flags

A set of flag bits, defined in “Keychain Item Import/Export Parameter Flags.”

passphrase

A 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).

alertTitle

Title 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.

alertPrompt

Prompt 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.

accessRef

Specifies 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.

keyUsage

A 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.

keyAttributes

A 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.

Discussion

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
SecImportExport.h

SecItemImportExportKeyParameters

A parameter block used for SecItemImport and SecItemExport.

typedef struct
   {
      /* for import and export */
      uint32_t                                version;
      SecKeyImportExportFlags                 flags;
      CFTypeRef                               passphrase;
      CFStringRef                             alertTitle;
      CFStringRef                             alertPrompt;
      
      /* for import only */
      SecAccessRef                            accessRef;
      CFArrayRef                              keyUsage;
      
      CFArrayRef                              keyAttributes;
} SecItemImportExportKeyParameters;
Fields
version

The version of this data structure against which the code was compiled. Always set this value to SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION.

flags

A set of flags containing the bitwise OR of values from “Keychain Item Import/Export Flags.”

passphrase

A CFStringRef or CFDataRef object used or the passphrase. Only used for PKCS12 and wrapped formats.

alertTitle

The title that should be displayed in the secure passphrase alert panel.

alertPrompt

The prompt that should be displayed in the secure passphrase alert panel.

accessRef

Specifies the initial access control list for imported key or keys.

keyUsage

An array containing attributes from “Core-Foundation-based ACL Authorization Keys.”

keyAttributes

An array of CFNumberRef objects containing CSSM attribute constants. Currently, the only supported value is CSSM_KEYATTR_PERMANENT.

Availability
  • Available in OS X v10.7 and later.
Declared In
SecImportExport.h

SecTrustedApplicationRef

Contains information about a trusted application.

typedef struct OpaqueSecTrustedApplicationRef *SecTrustedApplicationRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
SecBase.h

SecPasswordRef

Contains information about a password.

typedef struct OpaqueSecPasswordRef *SecPasswordRef;
Availability
  • Available in OS X v10.4 and later.
Declared In
SecBase.h

Constants

OS X Keychain Services API Constants

Import/Export Parameters Version

Defines the version of an import/export parameters structure.

#define SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION        0
Constants
SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION

Defines the version number for a SecImportExportParameters structure used as input to the functions SecKeychainItemExport and SecKeychainItemImport.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

Keychain Authentication Type Constants

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 )
};
Constants
kSecAuthenticationTypeNTLM

Specifies Windows NT LAN Manager authentication.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeMSN

Specifies Microsoft Network default authentication.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeDPA

Specifies Distributed Password authentication.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeRPA

Specifies Remote Password authentication.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeHTTPBasic

Specifies HTTP Basic authentication.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeHTTPDigest

Specifies HTTP Digest Access authentication.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeHTMLForm

Specifies HTML form based authentication.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeDefault

Specifies the default authentication type.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAuthenticationTypeAny

Specifies 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 OS X v10.5 and later.

Declared in SecKeychain.h.

Keychain Event Constants

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
};
Constants
kSecLockEvent

Indicates 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 OS X v10.2 and later.

Declared in SecKeychain.h.

kSecUnlockEvent

Indicates 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 OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAddEvent

Indicates an item was added to a keychain.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecDeleteEvent

Indicates an item was deleted from a keychain.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecUpdateEvent

Indicates a keychain item was updated.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecPasswordChangedEvent

Indicates the keychain password was changed.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecDefaultChangedEvent

Indicates that a different keychain was specified as the default.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecDataAccessEvent

Indicates a process has accessed a keychain item’s data.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecKeychainListChangedEvent

Indicates the list of keychains has changed.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecTrustSettingsChangedEvent

Indicates trust settings have changed.

Available in OS X v10.5 and later.

Declared in SecKeychain.h.

Keychain Event Mask Constants

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
};
Constants
kSecLockEventMask

If the bit specified by this mask is set, your callback function is invoked when a keychain is locked.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecUnlockEventMask

If the bit specified by this mask is set, your callback function is invoked when a keychain is unlocked.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecAddEventMask

If the bit specified by this mask is set, your callback function is invoked when an item is added to a keychain.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecDeleteEventMask

If the bit specified by this mask is set, your callback function is invoked when an item is deleted from a keychain.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecUpdateEventMask

If the bit specified by this mask is set, your callback function is invoked when a keychain item is updated.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecPasswordChangedEventMask

If the bit specified by this mask is set, your callback function is invoked when the keychain password is changed.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecDefaultChangedEventMask

If the bit specified by this mask is set, your callback function is invoked when a different keychain is specified as the default.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecDataAccessEventMask

If the bit specified by this mask is set, your callback function is invoked when a process accesses a keychain item’s data.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecKeychainListChangedMask

If the bit specified by this mask is set, your callback function is invoked when a keychain list is changed.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecTrustSettingsChangedEventMask

If the bit specified by this mask is set, your callback function is invoked when there is a change in certificate trust settings.

Available in OS X v10.5 and later.

Declared in SecKeychain.h.

kSecEveryEventMask

If all the bits are set, your callback function is invoked whenever any event occurs.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

Keychain Item Attribute Constants

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'
};
Constants
kSecCreationDateItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecModDateItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecDescriptionItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecCommentItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecCreatorItemAttr

Identifies the creator attribute.

You use this tag to set or get a value of type FourCharCode that represents the item's creator.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecTypeItemAttr

Identifies the type attribute.

You use this tag to set or get a value of type FourCharCode that represents the item’s type.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecScriptCodeItemAttr

Identifies the script code attribute.

You use this tag to set or get a value of type ScriptCode that represents the script code for all strings. Use of this attribute is deprecated; string attributes should always be stored in UTF-8 encoding.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecLabelItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecInvisibleItemAttr

Identifies the invisible attribute.

You use this tag to set or get a value of type Boolean that indicates whether the item is invisible (that is, should not be displayed).

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecNegativeItemAttr

Identifies the negative attribute.

You use this tag to set or get a value of type Boolean that indicates whether there is a valid password associated with this keychain item. This is useful if your application doesn’t want a password for some particular service to be stored in the keychain, but prefers that it always be entered by the user. The item, which is typically invisible and with zero-length data, acts as a placeholder.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecCustomIconItemAttr

Identifies the custom icon attribute.

Use of this attribute is deprecated. Custom icons for keychains are not supported in OS X.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecAccountItemAttr

Identifies the account attribute.

You use this tag to set or get a string that represents the user account. It also applies to generic, Internet, and AppleShare password items. Keychain strings should use UTF-8 encoding.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecServiceItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecGenericItemAttr

Identifies the generic attribute.

You use this tag to set or get a value of untyped bytes that represents a user-defined attribute. This is unique to generic password attributes.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecSecurityDomainItemAttr

Identifies the security domain attribute.

You use this tag to set or get a value that represents the Internet security domain. This is unique to Internet password attributes.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecServerItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecAuthenticationTypeItemAttr

Identifies the authentication type attribute.

You use this tag to set or get a value of type SecAuthenticationType that represents the Internet authentication scheme. For possible authentication values, see “Keychain Authentication Type Constants.” This is unique to Internet password attributes.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecPortItemAttr

Identifies the port attribute.

You use this tag to set or get a value of type UInt32 that represents the Internet port number. This is unique to Internet password attributes.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecPathItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecVolumeItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecAddressItemAttr

Identifies the address attribute.

You use this tag to set or get a value of type string that represents the AppleTalk zone name, or the IP or domain name that represents the server address. This is unique to AppleShare password attributes. Keychain strings should use UTF-8 encoding.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecSignatureItemAttr

Identifies the server signature attribute.

You use this tag to set or get a value of type SecAFPServerSignature that represents the server signature block. This is unique to AppleShare password attributes.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecProtocolItemAttr

Identifies 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 OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecCertificateType

Indicates a CSSM_CERT_TYPE type.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecCertificateEncoding

Indicates a CSSM_CERT_ENCODING type.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecCrlType

Indicates a CSSM_CRL_TYPE type.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecCrlEncoding

Indicates a CSSM_CRL_ENCODING type.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecAlias

Indicates an alias.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

Discussion

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.”

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
};
Constants
kSecKeyKeyClass

Type uint32 (CSSM_KEYCLASS); value is one of CSSM_KEYCLASS_PUBLIC_KEY, CSSM_KEYCLASS_PRIVATE_KEY or CSSM_KEYCLASS_SESSION_KEY.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyPrintName

Type blob; human readable name of the key. Same as kSecLabelItemAttr for normal keychain items.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyAlias

Type blob; currently unused.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyPermanent

Type uint32; value is nonzero. This key is permanent (stored in some keychain) and is always 1.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyPrivate

Type uint32; value is nonzero. This key is protected by a user login, a password, or both.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyModifiable

Type uint32; value is nonzero. Attributes of this key can be modified.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyLabel

Type 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 OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyApplicationTag

Type blob; currently unused.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyKeyCreator

Type data. The data points to a CSSM_GUID structure representing the module ID of the CSP owning this key.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyKeyType

Type uint32; value is a CSSM algorithm (CSSM_ALGORITHMS) representing the algorithm associated with this key.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyKeySizeInBits

Type uint32; value is the number of bits in this key.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyEffectiveKeySize

Type 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 OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyStartDate

Type 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 OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyEndDate

Type 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 OS X v10.4 and later.

Declared in SecKey.h.

kSecKeySensitive

Type uint32; value is nonzero. This key cannot be wrapped with CSSM_ALGID_NONE.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyAlwaysSensitive

Type uint32; value is nonzero. This key has always been marked sensitive.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyExtractable

Type uint32; value is nonzero. This key can be wrapped.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyNeverExtractable

Type uint32; value is nonzero. This key was never marked extractable.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyEncrypt

Type uint32; value is nonzero. This key can be used in an encrypt operation.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyDecrypt

Type uint32; value is nonzero. This key can be used in a decrypt operation.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyDerive

Type uint32; value is nonzero. This key can be used in a key derivation operation.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeySign

Type uint32, value is nonzero. This key can be used in a sign operation.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyVerify

Type uint32, value is nonzero. This key can be used in a verify operation.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeySignRecover

Type uint32.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyVerifyRecover

Type uint32. This key can unwrap other keys.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyWrap

Type uint32; value is nonzero. This key can wrap other keys.

Available in OS X v10.4 and later.

Declared in SecKey.h.

kSecKeyUnwrap

Type uint32; value is nonzero. This key can unwrap other keys.

Available in OS X v10.4 and later.

Declared in SecKey.h.

Discussion

For attributes for items other than keys, see “Keychain Item Attribute Constants.”

Keychain Item Class 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
};
Constants
kSecInternetPasswordItemClass

Indicates that the item is an Internet password.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecGenericPasswordItemClass

Indicates that the item is a generic password.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecAppleSharePasswordItemClass

Indicates that the item is an AppleShare password.

Available in OS X v10.0 and later.

Deprecated in OS X v10.9.

Declared in SecKeychainItem.h.

kSecCertificateItemClass

Indicates that the item is an X509 certificate.

Available in OS X v10.2 and later.

Declared in SecKeychainItem.h.

kSecPublicKeyItemClass

Indicates that the item is a public key of a public-private pair.

Available in OS X v10.5 and later.

Declared in SecKeychainItem.h.

kSecPrivateKeyItemClass

Indicates that the item is a private key of a public-private pair.

Available in OS X v10.5 and later.

Declared in SecKeychainItem.h.

kSecSymmetricKeyItemClass

Indicates that the item is a private key used for symmetric-key encryption.

Available in OS X v10.5 and later.

Declared in SecKeychainItem.h.

CSSM_DL_DB_RECORD_ALL_KEYS

The item can be any type of key; used for searches only.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

Discussion

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.

Declared In
SecKeychainItem.h, cssmtype.h.

Keychain Item Import/Export Flags

Defines values for import and export flags.

enum
{
   kSecItemPemArmour           = 0x00000001,
};
typedef uint32_t SecItemImportExportFlags;
Constants
kSecItemPemArmour

The exported data should have PEM armor.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

Discussion

This enumeration lists values used by the flags parameter of the functions SecKeychainItemExport and SecKeychainItemImport.

PEM armor 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.)

Keychain Item Import/Export Parameter Flags

Defines values for the flags field of the import/export parameters.

enum
{
   kSecKeyImportOnlyOne        = 0x00000001,
   kSecKeySecurePassphrase     = 0x00000002,
   kSecKeyNoAccessControl      = 0x00000004
};
typedef uint32_t SecKeyImportExportFlags;
Constants
kSecKeyImportOnlyOne

Prevents 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 OS X v10.4 and later.

Declared in SecImportExport.h.

kSecKeySecurePassphrase

When 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 OS X v10.4 and later.

Declared in SecImportExport.h.

kSecKeyNoAccessControl

When 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 OS X v10.4 and later.

Declared in SecImportExport.h.

Discussion

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.

Keychain Item Import/Export Formats

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;
Constants
kSecFormatUnknown

When 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 OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatOpenSSL

Format 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 OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatSSH

OpenSSH 1 format for asymmetric (public/private) keys. OpenSSH is an OpenBSD implementation of the Secure Shell (SSH) protocol.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatBSAFE

Format for asymmetric keys. BSAFE is a standard from RSA Security for encryption, digital signatures, and privacy.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatSSHv2

OpenSSH 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 OS X v10.5 and later.

Declared in SecImportExport.h.

kSecFormatRawKey

Format for symmetric keys. Raw, unformatted key bits. This is the default for symmetric keys.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatWrappedPKCS8

Format for wrapped symmetric and private keys. PKCS8 is the Private-Key Information Syntax Standard from RSA Security.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatWrappedOpenSSL

Format for wrapped symmetric and private keys. OpenSSL is an open-source toolkit for Secure Sockets Layer (SSL) and Transport Layer Security (TLS).

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatWrappedSSH

OpenSSH 1 format for wrapped symmetric and private keys. OpenSSH is an OpenBSD implementation of the Secure Shell (SSH) protocol.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatWrappedLSH

Not supported.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatX509Cert

Format 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 OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatPEMSequence

Sequence of certificates and keys with PEM armor. PEM armor 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 OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatPKCS7

Sequence of certificates, no PEM armor. PKCS7 is the Cryptographic Message Syntax Standard from RSA Security, Inc.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatPKCS12

Set of certificates and private keys. PKCS12 is the Personal Information Exchange Syntax from RSA Security, Inc.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecFormatNetscapeCertSequence

Set of certificates in the Netscape Certificate Sequence format.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

Keychain Item Type When Importing

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;
Constants
kSecItemTypeUnknown

Indicates that the caller does not know the type of information being imported or exported.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecItemTypePrivateKey

Indicates a private key.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecItemTypePublicKey

Indicates a public key.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecItemTypeSessionKey

Indicates a session key.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecItemTypeCertificate

Indicates a certificate.

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

kSecItemTypeAggregate

Indicates a set of certificates or certificates and private keys, such as PKCS7, PKCS12, or kSecFormatPEMSequence formats (see “Keychain Item Import/Export Formats”).

Available in OS X v10.4 and later.

Declared in SecImportExport.h.

Keychain Import/Export Options

Predefined key constants used when passing dictionary-based arguments to import/export functions.

extern CFStringRef kSecImportExportPassphrase;
extern CFStringRef kSecImportExportKeychain;
extern CFStringRef kSecImportExportAccess;
Constants
kSecImportExportPassphrase

A passphrase (represented by a CFStringRef object) to be used when exporting to or importing from PKCS#12 format.

Available in OS X v10.6 and later.

Declared in SecImportExport.h.

kSecImportExportKeychain

A keychain represented by a SecKeychainRef to be used as the target when importing or exporting.

Available in OS X v10.7 and later.

Declared in SecImportExport.h.

kSecImportExportAccess

An initial access control list represented by a SecAccessRef object.

Available in OS X v10.7 and later.

Declared in SecImportExport.h.

Keychain Preference Domain Constants

Defines constants for the keychain preference domains.

typedef enum {
   kSecPreferencesDomainUser,
   kSecPreferencesDomainSystem,
   kSecPreferencesDomainCommon,
   kSecPreferencesDomainAlternate,
   kSecPreferencesDomainDynamic
} SecPreferencesDomain;
Constants
kSecPreferencesDomainUser

Indicates the user preference domain preferences.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecPreferencesDomainSystem

Indicates the system or daemon preference domain preferences.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecPreferencesDomainCommon

Indicates the preferences are common to everyone.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecPreferencesDomainAlternate

Indicates an alternate preference domain preferences.

Available in OS X v10.3 through OS X v10.3.

Declared in SecKeychain.h.

kSecPreferencesDomainDynamic

Indicates a dynamic search list (typically provided by removable keychains such as smart cards).

Available in OS X v10.4 and later.

Declared in SecKeychain.h.

Discussion

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.

Keychain Protocol Type Constants

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
};
Constants
kSecProtocolTypeFTP

Indicates FTP.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeFTPAccount

Indicates a client side FTP account. The usage of this constant is deprecated as of OS X v10.3.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeHTTP

Indicates HTTP.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeIRC

Indicates IRC.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeNNTP

Indicates NNTP.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypePOP3

Indicates POP3.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeSMTP

Indicates SMTP.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeSOCKS

Indicates SOCKS.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeIMAP

Indicates IMAP.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeLDAP

Indicates LDAP.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeAppleTalk

Indicates AFP over AppleTalk.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeAFP

Indicates AFP over TCP.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeTelnet

Indicates Telnet.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeSSH

Indicates SSH.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecProtocolTypeFTPS

Indicates FTP over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeHTTPS

Indicates HTTP over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeHTTPProxy

Indicates HTTP proxy.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeHTTPSProxy

Indicates HTTPS proxy.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeFTPProxy

Indicates FTP proxy.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeCIFS

Indicates CIFS.

Available in OS X v10.5 and later.

Declared in SecKeychain.h.

kSecProtocolTypeSMB

Indicates SMB.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeRTSP

Indicates RTSP.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeRTSPProxy

Indicates RTSP proxy.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeDAAP

Indicates DAAP.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeEPPC

Indicates Remote Apple Events.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeIPP

Indicates IPP.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeNNTPS

Indicates NNTP over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeLDAPS

Indicates LDAP over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeTelnetS

Indicates Telnet over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeIMAPS

Indicates IMAP4 over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeIRCS

Indicates IRC over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypePOP3S

Indicates POP3 over TLS/SSL.

Available in OS X v10.3 and later.

Declared in SecKeychain.h.

kSecProtocolTypeCVSpserver

Indicates CVS pserver.

Available in OS X v10.5 and later.

Declared in SecKeychain.h.

kSecProtocolTypeSVN

Indicates Subversion.

Available in OS X v10.5 and later.

Declared in SecKeychain.h.

kSecProtocolTypeAny

Indicates that any protocol is acceptable.

When performing a search, use this constant to avoid constraining your search results to a particular protocol.

Available in OS X v10.5 and later.

Declared in SecKeychain.h.

Keychain Settings Version

Defines the keychain settings version.

#define SEC_KEYCHAIN_SETTINGS_VERS1 1
Constants
SEC_KEYCHAIN_SETTINGS_VERS1

Defines the keychain settings version.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

Keychain Status Masks

Defines the current status of a keychain.

typedef UInt32 SecKeychainStatus;
enum
{
   kSecUnlockStateStatus        = 1,
   kSecReadPermStatus           = 2,
   kSecWritePermStatus          = 4
};
Constants
kSecUnlockStateStatus

Indicates the keychain is unlocked.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecReadPermStatus

Indicates the keychain is readable.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

kSecWritePermStatus

Indicates the keychain is writable.

Available in OS X v10.2 and later.

Declared in SecKeychain.h.

Discussion

You can use these masks in combination. For example, a keychain may be both readable and writable.

SecKeychainPromptSelector

Bits that define when using a keychain should require a passphrase.

   typedef uint16 SecKeychainPromptSelector;
   enum
   {
   kSecKeychainPromptRequirePassphase = 0x0001, /* require re-entering of passphrase */
   /* the following bits are ignored by 10.4 and earlier */
   kSecKeychainPromptUnsigned = 0x0010,                    /* prompt for unsigned clients */
   kSecKeychainPromptUnsignedAct = 0x0020,         /* UNSIGNED bit overrides system default */
   kSecKeychainPromptInvalid = 0x0040,                     /* prompt for invalid signed clients */
   kSecKeychainPromptInvalidAct = 0x0080,
};
   
Constants
kSecKeychainPromptRequirePassphase

Indicates that a passphrase should be required for every access.

Available in OS X v10.7 and later.

Declared in SecACL.h.

kSecKeychainPromptUnsigned

Indicates that a passphrase should be required when an unsigned application attempts to use the keychain, overriding the system default.

Available in OS X v10.7 and later.

Declared in SecACL.h.

kSecKeychainPromptUnsignedAct

Indicates that a passphrase should be required when an unsigned application attempts to use the keychain.

Available in OS X v10.7 and later.

Declared in SecACL.h.

kSecKeychainPromptInvalid

Indicates that a passphrase should be required when an application with an invalid signature attempts to use the keychain, overriding the system default.

Available in OS X v10.7 and later.

Declared in SecACL.h.

kSecKeychainPromptInvalidAct

Indicates that a passphrase should be required when an application with an invalid signature attempts to use the keychain.

Available in OS X v10.7 and later.

Declared in SecACL.h.

SecAccessOwnerType

Flags used when creating an access control list entry.

typedef UInt32  SecAccessOwnerType;
enum
{
   kSecUseOnlyUID = 1,
   kSecUseOnlyGID = 2,
   kSecHonorRoot = 0x100,
   kSecMatchBits = (kSecUseOnlyUID | kSecUseOnlyGID)
};
Constants
kSecUseOnlyUID

Specifies that the access control list generated should be owned by the user that matches the specified user ID parameter.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecUseOnlyGID

Specifies that the access control list generated should be owned by users that are members of a group that matches the specified group ID parameter.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecHonorRoot

Specifies that the access control list generated should treat the root user as a normal user for ownership purposes.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecMatchBits

Specifies that the access control list should be owned by users whose ID matches the specified user ID or who are members of a group whose ID matches the specified group ID parameter.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

Keychain Item Class Keys and Values

Constants used in a search dictionary to specify the class of items in the keychain. See SecItemCopyMatching for a description of a search dictionary.

Item Class Key Constant

Key constant used to set the item class value in a search dictionary.

   CFTypeRef kSecClass;
Constants
kSecClass

Dictionary key whose value is the item's class code.

Possible values for this key are listed in “Item Class Value Constants.”

Available in OS X v10.6 and later.

Declared in SecItem.h.

Item Class Value Constants

Values used with the kSecClass key in a search dictionary.

   CFTypeRef kSecClassGenericPassword;
   CFTypeRef kSecClassInternetPassword;
   CFTypeRef kSecClassCertificate;
   CFTypeRef kSecClassKey;
   CFTypeRef kSecClassIdentity;
Constants
kSecClassGenericPassword

Generic password item.

The following attribute types (“Attribute Item Keys and Values”) can be used with an item of this type:

  • kSecAttrAccessible

  • kSecAttrAccessGroup

  • kSecAttrCreationDate

  • kSecAttrModificationDate

  • kSecAttrDescription

  • kSecAttrComment

  • kSecAttrCreator

  • kSecAttrType

  • kSecAttrLabel

  • kSecAttrIsInvisible

  • kSecAttrIsNegative

  • kSecAttrAccount

  • kSecAttrService

  • kSecAttrGeneric

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecClassInternetPassword

Internet password item.

The following attribute types (“Attribute Item Keys and Values”) can be used with an item of this type:

  • kSecAttrAccessible

  • kSecAttrAccessGroup

  • kSecAttrCreationDate

  • kSecAttrModificationDate

  • kSecAttrDescription

  • kSecAttrComment

  • kSecAttrCreator

  • kSecAttrType

  • kSecAttrLabel

  • kSecAttrIsInvisible

  • kSecAttrIsNegative

  • kSecAttrAccount

  • kSecAttrSecurityDomain

  • kSecAttrServer

  • kSecAttrProtocol

  • kSecAttrAuthenticationType

  • kSecAttrPort

  • kSecAttrPath

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecClassCertificate

Certificate item.

The following attribute types (“Attribute Item Keys and Values”) can be used with an item of this type:

  • kSecAttrAccessible

  • kSecAttrAccessGroup

  • kSecAttrCertificateType

  • kSecAttrCertificateEncoding

  • kSecAttrLabel

  • kSecAttrSubject

  • kSecAttrIssuer

  • kSecAttrSerialNumber

  • kSecAttrSubjectKeyID

  • kSecAttrPublicKeyHash

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecClassKey

Cryptographic key item.

The following attribute types (“Attribute Item Keys and Values”) can be used with an item of this type:

  • kSecAttrAccessible

  • kSecAttrAccessGroup

  • kSecAttrKeyClass

  • kSecAttrLabel

  • kSecAttrApplicationLabel

  • kSecAttrIsPermanent

  • kSecAttrApplicationTag

  • kSecAttrKeyType

  • kSecAttrKeySizeInBits

  • kSecAttrEffectiveKeySize

  • kSecAttrCanEncrypt

  • kSecAttrCanDecrypt

  • kSecAttrCanDerive

  • kSecAttrCanSign

  • kSecAttrCanVerify

  • kSecAttrCanWrap

  • kSecAttrCanUnwrap

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecClassIdentity

Identity item.

An identity is a certificate together with its associated private key. Because an identity is the combination of a private key and a certificate, this class shares attributes of both kSecClassKey and kSecClassCertificate.

Available in OS X v10.7 and later.

Declared in SecItem.h.

Attribute Item Keys and Values

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.

Attribute Item 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 kSecAttrAccess;
   CFTypeRef kSecAttrAccessible;
   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 kSecAttrPRF;
   CFTypeRef kSecAttrSalt;
   CFTypeRef kSecAttrRounds;
   CFTypeRef kSecAttrKeyType;
   CFTypeRef kSecAttrKeySizeInBits;
   CFTypeRef kSecAttrEffectiveKeySize;
   CFTypeRef kSecAttrCanEncrypt;
   CFTypeRef kSecAttrCanDecrypt;
   CFTypeRef kSecAttrCanDerive;
   CFTypeRef kSecAttrCanSign;
   CFTypeRef kSecAttrCanVerify;
   CFTypeRef kSecAttrCanWrap;
   CFTypeRef kSecAttrCanUnwrap;
   CFTypeRef kSecAttrAccessGroup;
Constants
kSecAttrAccess

A SecAccessRef object describing the access control settings for this item.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrAccessible

A CFTypeRef (opaque) value that indicates when your app needs access to the data in a keychain item. You should choose the most restrictive option that meets your app’s needs so that iOS can protect that item to the greatest extent possible. For a list of possible values, see “Keychain Item Accessibility Constants.”

Note: The app must provide the contents of the keychain item (kSecValueData) when changing this attribute in iOS 4 and earlier.

Available in OS X v10.9 and later.

Declared in SecItem.h.

kSecAttrCreationDate

Creation date key.

The corresponding value is of type CFDateRef and represents the date the item was created. Read only.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrModificationDate

Modification date key.

The corresponding value is of type CFDateRef and represents the last time the item was updated. Read only.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrDescription

Description 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrComment

Comment attribute key.

The corresponding value is of type CFStringRef and contains the user-editable comment for this item.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCreator

Creator 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrType

Type 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrLabel

Label attribute key.

The corresponding value is of type CFStringRef and contains the user-visible label for this item.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrIsInvisible

Invisible 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrIsNegative

Negative 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAccount

Account 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrService

Service 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrGeneric

Generic attribute key.

The corresponding value is of type CFDataRef and contains a user-defined attribute. Items of class kSecClassGenericPassword have this attribute.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrSecurityDomain

Security 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrServer

Server 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocol

Protocol 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationType

Authentication type attribute key.

The corresponding value is of type CFNumberRef and denotes the authentication scheme for this item (see “Authentication Type Values”).

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrPort

Port attribute key.

The corresponding value is of type CFNumberRef and represents an Internet port number. Items of class kSecClassInternetPassword have this attribute.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrPath

Path 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrSubject

Subject 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrIssuer

Issuer 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrSerialNumber

Serial 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrSubjectKeyID

Subject 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrPublicKeyHash

Public 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCertificateType

Certificate 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCertificateEncoding

Certificate 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrKeyClass

Key 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrApplicationLabel

Application 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrIsPermanent

Permanence attribute key.

The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key is to be stored permanently.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrApplicationTag

Private tag attribute key.

The corresponding value is of type CFDataRef and contains private tag data.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrPRF

Pseudorandom function attribute. Possible values are described in “kSecAttrPRF Value Constants.”

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrSalt

A CFDataRef object containing the salt to use for this key.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrRounds

The number of rounds for the pseudorandom function specified by kSecAttrPRF.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyType

Algorithm 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 Values”).

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrKeySizeInBits

Number 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrEffectiveKeySize

Effective 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCanEncrypt

Encryption attribute key.

The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to encrypt data.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCanDecrypt

Decryption attribute key.

The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to decrypt data.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCanDerive

Derivation attribute key.

The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to derive another key.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCanSign

Signature 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCanVerify

Signature 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 OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCanWrap

Wrap attribute key.

The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to wrap another key.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrCanUnwrap

Unwrap attribute key.

The corresponding value is of type CFBooleanRef and indicates whether this cryptographic key can be used to unwrap another key.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAccessGroup

Access group key.

The corresponding value is of type CFStringRef and indicates which access group an item is in. Access groups can be used to share keychain items among two or more applications. For applications to share a keychain item, the applications must have a common access group listed in their keychain-access-groups entitlement, and the application adding the shared item to the keychain must specify this shared access-group name as the value for this key in the dictionary passed to the SecItemAdd function.

An application can be a member of any number of access groups. By default, the SecItemUpdate, SecItemDelete, and SecItemCopyMatching functions search all the access groups an application is a member of. Include this key in the search dictionary for these functions to specify which access group is searched.

A keychain item can be in only a single access group.

Available in OS X v10.9 and later.

Declared in SecItem.h.

Discussion

These predefined item attribute keys are used to get or set values in a dictionary. Not all attributes apply to each item class.

Protocol Values

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;
Constants
kSecAttrProtocolFTP

FTP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolFTPAccount

A client side FTP account.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolHTTP

HTTP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolIRC

IRC protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolNNTP

NNTP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolPOP3

POP3 protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolSMTP

SMTP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolSOCKS

SOCKS protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolIMAP

IMAP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolLDAP

LDAP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolAppleTalk

AFP over AppleTalk.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolAFP

AFP over TCP.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolTelnet

Telnet protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolSSH

SSH protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolFTPS

FTP over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolHTTPS

HTTP over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolHTTPProxy

HTTP proxy.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolHTTPSProxy

HTTPS proxy.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolFTPProxy

FTP proxy.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolSMB

SMB protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolRTSP

RTSP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolRTSPProxy

RTSP proxy.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolDAAP

DAAP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolEPPC

Remote Apple Events.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolIPP

IPP protocol.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolNNTPS

NNTP over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolLDAPS

LDAP over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolTelnetS

Telnet over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolIMAPS

IMAP over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolIRCS

IRC over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrProtocolPOP3S

POP3 over TLS/SSL.

Available in OS X v10.6 and later.

Declared in SecItem.h.

Authentication Type Values

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;
Constants
kSecAttrAuthenticationTypeNTLM

Windows NT LAN Manager authentication.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationTypeMSN

Microsoft Network default authentication.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationTypeDPA

Distributed Password authentication.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationTypeRPA

Remote Password authentication.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationTypeHTTPBasic

HTTP Basic authentication.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationTypeHTTPDigest

HTTP Digest Access authentication.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationTypeHTMLForm

HTML form based authentication.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecAttrAuthenticationTypeDefault

The default authentication type.

Available in OS X v10.6 and later.

Declared in SecItem.h.

Key Class Values

Values that can be used with the kSecAttrKeyClass attribute key.

   CFTypeRef kSecAttrKeyClassPublic;
   CFTypeRef kSecAttrKeyClassPrivate;
   CFTypeRef kSecAttrKeyClassSymmetric;
Constants
kSecAttrKeyClassPublic

A public key of a public-private pair.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyClassPrivate

A private key of a public-private pair.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyClassSymmetric

A private key used for symmetric-key encryption and decryption.

Available in OS X v10.7 and later.

Declared in SecItem.h.

Key Type Values

Values that can be used with the kSecAttrKeyType attribute key.

extern const CFTypeRef kSecAttrKeyTypeRSA;
extern const CFTypeRef kSecAttrKeyTypeDSA;
extern const CFTypeRef kSecAttrKeyTypeAES;
extern const CFTypeRef kSecAttrKeyTypeDES;
extern const CFTypeRef kSecAttrKeyType3DES;
extern const CFTypeRef kSecAttrKeyTypeRC4;
extern const CFTypeRef kSecAttrKeyTypeRC2;
extern const CFTypeRef kSecAttrKeyTypeCAST;
extern const CFTypeRef kSecAttrKeyTypeECDSA;
Constants
kSecAttrKeyTypeRSA

RSA algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyTypeDSA

DSA algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyTypeAES

AES algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyTypeDES

DES algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyType3DES

3DES algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyTypeRC4

RC4 algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyTypeRC2

RC2 algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyTypeCAST

CAST algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrKeyTypeECDSA

Elliptic curve DSA algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

Keychain Item Accessibility Constants

These constants are legal values for kSecAttrAccessible used for determining when a keychain item should be readable.

CFTypeRef kSecAttrAccessibleWhenUnlocked;
CFTypeRef kSecAttrAccessibleAfterFirstUnlock;
CFTypeRef kSecAttrAccessibleAlways;
CFTypeRef kSecAttrAccessibleWhenUnlockedThisDeviceOnly;
CFTypeRef kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly;
CFTypeRef kSecAttrAccessibleAlwaysThisDeviceOnly;
Constants
kSecAttrAccessibleAfterFirstUnlock

The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.

After the first unlock, the data remains accessible until the next restart. This is recommended for items that need to be accessed by background applications. Items with this attribute migrate to a new device when using encrypted backups.

Available in OS X v10.9 and later.

Declared in SecItem.h.

kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly

The data in the keychain item cannot be accessed after a restart until the device has been unlocked once by the user.

After the first unlock, the data remains accessible until the next restart. This is recommended for items that need to be accessed by background applications. Items with this attribute do not migrate to a new device. Thus, after restoring from a backup of a different device, these items will not be present.

Available in OS X v10.9 and later.

Declared in SecItem.h.

kSecAttrAccessibleAlways

The data in the keychain item can always be accessed regardless of whether the device is locked.

This is not recommended for application use. Items with this attribute migrate to a new device when using encrypted backups.

Available in OS X v10.9 and later.

Declared in SecItem.h.

kSecAttrAccessibleAlwaysThisDeviceOnly

The data in the keychain item can always be accessed regardless of whether the device is locked.

This is not recommended for application use. Items with this attribute do not migrate to a new device. Thus, after restoring from a backup of a different device, these items will not be present.

Available in OS X v10.9 and later.

Declared in SecItem.h.

kSecAttrAccessibleWhenUnlocked

The data in the keychain item can be accessed only while the device is unlocked by the user.

This is recommended for items that need to be accessible only while the application is in the foreground. Items with this attribute migrate to a new device when using encrypted backups.

This is the default value for keychain items added without explicitly setting an accessibility constant.

Available in OS X v10.9 and later.

Declared in SecItem.h.

kSecAttrAccessibleWhenUnlockedThisDeviceOnly

The data in the keychain item can be accessed only while the device is unlocked by the user.

This is recommended for items that need to be accessible only while the application is in the foreground. Items with this attribute do not migrate to a new device. Thus, after restoring from a backup of a different device, these items will not be present.

Available in OS X v10.9 and later.

Declared in SecItem.h.

kSecAttrPRF Value Constants

Constants used for the kSecAttrPRF key in the parameters dictionary passed to SecKeyDeriveFromPassword.

extern const CFTypeRef kSecAttrPRFHmacAlgSHA1;
extern const CFTypeRef kSecAttrPRFHmacAlgSHA224;
extern const CFTypeRef kSecAttrPRFHmacAlgSHA256;
extern const CFTypeRef kSecAttrPRFHmacAlgSHA384;
extern const CFTypeRef kSecAttrPRFHmacAlgSHA512;
Constants
kSecAttrPRFHmacAlgSHA1

Use the SHA1 algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrPRFHmacAlgSHA224

Use the SHA224 algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrPRFHmacAlgSHA256

Use the SHA256 algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrPRFHmacAlgSHA384

Use the SHA384 algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecAttrPRFHmacAlgSHA512

Use the SHA512 algorithm.

Available in OS X v10.7 and later.

Declared in SecItem.h.

Search Keys

Search Attribute Keys

Keys used to set search attributes in a keychain search dictionary. You can specify a combination of search attributes and item attributes (see “Attribute Item Keys and Values”) when looking for matching items with the SecItemCopyMatching function.

   CFTypeRef kSecMatchPolicy;
   CFTypeRef kSecMatchItemList;
   CFTypeRef kSecMatchSearchList;
   CFTypeRef kSecMatchIssuers;
   CFTypeRef kSecMatchEmailAddressIfPresent;
   CFTypeRef kSecMatchSubjectContains;
   CFTypeRef kSecMatchSubjectStartsWith;
   CFTypeRef kSecMatchSubjectEndsWith;
   CFTypeRef kSecMatchSubjectWholeString;
   CFTypeRef kSecMatchCaseInsensitive;
   CFTypeRef kSecMatchDiacriticInsensitive;
   CFTypeRef kSecMatchWidthInsensitive;
   CFTypeRef kSecMatchTrustedOnly;
   CFTypeRef kSecMatchValidOnDate;
   CFTypeRef kSecMatchLimit;
   CFTypeRef kSecMatchLimitOne;
   CFTypeRef kSecMatchLimitAll;
Constants
kSecMatchPolicy

Match policy attribute key.

The corresponding value is of type SecPolicyRef. If provided, returned certificates or identities must verify with this policy.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchItemList

Item list attribute key.

To provide your own set of items to be filtered by a search query rather than searching the keychain, specify this search key in a call to the SecItemCopyMatching function with a value that consists of an object of type CFArrayRef where the array contains either SecKeychainItemRef, SecKeyRef, SecCertificateRef, SecIdentityRef, or CFDataRef items. The objects in the provided array must all be of the same type.

To convert from persistent item references to normal item references, specify this search key in a call to the SecItemCopyMatching function with a value of type CFArrayRef where the array contains one or more CFDataRef elements (the persistent references), and a return-type key of kSecReturnRef whose value is kCFBooleanTrue.

To delete an item identified by a transient reference, specify the kSecMatchItemList search key in a call to the SecItemDelete function 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 in a call to the SecItemDelete function with a persistent reference returned by using the kSecReturnPersistentRef return type key to the SecItemCopyMatching or SecItemAdd functions.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchSearchList

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchIssuers

Issuers attribute key.

The corresponding value is of type CFArrayRef, where the array consists of X.500 names of type CFDataRef. If provided, returned certificates or identities are limited to those whose certificate chain contains one of the issuers provided in this list.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchEmailAddressIfPresent

Email address attribute key.

The corresponding value is of type CFStringRef and contains an RFC822 email address. If provided, returned certificates or identities are limited to those that either contain the address or do not contain any email address.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchSubjectContains

Subject attribute key.

The corresponding value is of type CFStringRef. If provided, returned certificates or identities are limited to those whose subject contains this string.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchSubjectStartsWith

Subject attribute key.

The corresponding value is of type CFStringRef. If provided, returned certificates or identities are limited to those whose subject starts with this string.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecMatchSubjectEndsWith

Subject attribute key.

The corresponding value is of type CFStringRef. If provided, returned certificates or identities are limited to those whose subject ends with this string.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecMatchSubjectWholeString

Subject attribute key.

The corresponding value is of type CFStringRef. If provided, returned certificates or identities are limited to those whose subject is exactly equal to this string.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecMatchCaseInsensitive

Case sensitivity attribute key.

The corresponding value is of type CFBooleanRef. If this value is kCFBooleanFalse, or if this attribute is not provided, then case-sensitive string matching is performed.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchDiacriticInsensitive

Case sensitivity attribute key.

The corresponding value is of type CFBooleanRef. If this value is kCFBooleanFalse, or if this attribute is not provided, then diacritic-sensitive string matching is performed.

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecMatchWidthInsensitive

Case sensitivity attribute key.

The corresponding value is of type CFBooleanRef. If this value is kCFBooleanFalse, or if this attribute is not provided, then width-sensitive string matching is performed (for example, the ASCII character a does not match the UTF-8 full-width letter a (U+FF41).

Available in OS X v10.7 and later.

Declared in SecItem.h.

kSecMatchTrustedOnly

Trusted anchor attribute key.

The corresponding value is of type CFBooleanRef. If this attribute is provided with A value of kCFBooleanTrue, only certificates that can be verified back to a trusted anchor are returned. If this value is kCFBooleanFalse or the attribute is not provided, then both trusted and untrusted certificates may be returned.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchValidOnDate

Valid-on-date attribute key.

The corresponding value is of type CFDateRef. If provided, returned keys, certificates or identities are limited to those that are valid for the given date. Pass a value of kCFNull to indicate the current date.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchLimit

Match limit attribute key.

The corresponding value is of type CFNumberRef. If provided, this value specifies the maximum number of results to return or otherwise act upon. For a single item, specify kSecMatchLimitOne. To specify all matching items, specify kSecMatchLimitAll. The default behavior is function-dependent.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchLimitOne

Results are limited to the first item found; used as a value for the kSecMatchLimit attribute key.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecMatchLimitAll

An unlimited number of results may be returned; used as a value for the kSecMatchLimit attribute key.

Available in OS X v10.6 and later.

Declared in SecItem.h.

Item List Key

Key used to specify a list of items to search or add.

   CFTypeRef kSecUseItemList;
Constants
kSecUseItemList

Item list key.

The corresponding value is of type CFArrayRef, where the array contains either SecKeychainItemRef, SecKeyRef, SecCertificateRef, SecIdentityRef, or (for persistent item references) CFDataRef items. If provided, this array is treated as the set of all possible items to search (or to add if the function being called is SecItemAdd). The items in the array must all be of the same type.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecUseKeychain

Keychain reference key.

Specifies a SecKeychainRef object that references the keychain to which SecItemAdd should add the provided items.

Available in OS X v10.7 and later.

Declared in SecItem.h.

Discussion

When this attribute is provided, no keychains are searched.

Search Results Constants

Return Type Keys

Keys used to specify the type of results that should be returned by the SecItemCopyMatching or SecItemAdd function.

   CFTypeRef kSecReturnData;
   CFTypeRef kSecReturnAttributes;
   CFTypeRef kSecReturnRef;
   CFTypeRef kSecReturnPersistentRef;
Constants
kSecReturnData

Return data attribute key.

The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that the data of an item should be returned in the form of a CFDataRef. For keys and password items, data is secret (encrypted) and may require the user to enter a password for access.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecReturnAttributes

Return attributes attribute key.

The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a dictionary of the (unencrypted) attributes of an item should be returned in the form of a CFDictionaryRef.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecReturnRef

Return reference attribute key.

The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a reference should be returned. Depending on the item class requested, the returned references may be of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, SecIdentityRef, or CFDataRef.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecReturnPersistentRef

Return persistent reference attribute key. A persistent reference to a credential can be stored on disk for later use or passed to other processes.

The corresponding value is of type CFBooleanRef. A value of kCFBooleanTrue indicates that a persistent reference to an item (CFDataRef) should be returned.

Available in OS X v10.6 and later.

Declared in SecItem.h.

Discussion

You can specify zero or more of these return types. If you specify more than one of these return types, Keychain Services returns the result as a CFDictionaryRef reference to a dictionary whose keys are the return types and whose values are the requested data.

Value Type Keys

Keys used in the results dictionary for SecItemCopyMatching or SecItemAdd, indicating the type of values returned. You can specify zero or more of these types depending on the function you are calling.

   CFTypeRef kSecValueData;
   CFTypeRef kSecValueRef;
   CFTypeRef kSecValuePersistentRef;
Constants
kSecValueData

Data attribute key. A persistent reference to a credential can be stored on disk for later use or passed to other processes.

The corresponding value is of type CFDataRef.  For keys and password items, the data is secret (encrypted) and may require the user to enter a password for access.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecValueRef

Reference attribute key.

The corresponding value, depending on the item class requested, is of type SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef.

Available in OS X v10.6 and later.

Declared in SecItem.h.

kSecValuePersistentRef

Persistent reference attribute key.

The corresponding value is of type CFDataRef. The bytes in this CFDataRef can be stored by the caller and used on a subsequent invocation of the application (or even a different application) to retrieve the item referenced by it.

Available in OS X v10.6 and later.

Declared in SecItem.h.

Authorization Keys

Core-Foundation-based ACL Authorization Keys

Defines constants that specify which operations an access control list entry applies to.

extern CFTypeRef kSecACLAuthorizationAny
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
   
extern CFTypeRef kSecACLAuthorizationLogin
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationGenKey
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationDelete
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationExportWrapped
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationExportClear
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationImportWrapped
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationImportClear
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationSign
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationEncrypt
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationDecrypt
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationMAC
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationDerive
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
   
/* Defined authorization tag values for Keychain */
extern CFTypeRef kSecACLAuthorizationKeychainCreate
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationKeychainDelete
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationKeychainItemRead
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationKeychainItemInsert
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationKeychainItemModify
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationKeychainItemDelete
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
   
extern CFTypeRef kSecACLAuthorizationChangeACL
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
extern CFTypeRef kSecACLAuthorizationChangeOwner
   __OSX_AVAILABLE_STARTING(__MAC_10_7,
   __IPHONE_NA);
Constants
kSecACLAuthorizationAny

No restrictions. This ACL entry applies to all operations available to the caller.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationLogin

Use for a CSP (smart card) login.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationGenKey

Generate a key.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationDelete

Delete this item.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationExportWrapped

Export 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 OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationExportClear

Export an unencrypted key.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationImportWrapped

Import 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 OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationImportClear

Import an unencrypted key.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationSign

Digitally sign data.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationEncrypt

Encrypt data.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationDecrypt

Decrypt data.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationMAC

Create or verify a message authentication code.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationDerive

Derive a new key from another key.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationKeychainCreate

Create a new keychain.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationKeychainDelete

Delete a keychain.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationKeychainItemRead

Read an item from a keychain.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationKeychainItemInsert

Insert an item into a keychain.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationKeychainItemModify

Modify an item in a keychain.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationKeychainItemDelete

Delete an item from a keychain.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationChangeACL

Change an access control list entry.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

kSecACLAuthorizationChangeOwner

For internal system use only. Use the CSSM_ACL_AUTHORIZATION_CHANGE_ACL tag for changes to owner ACL entries.

Available in OS X v10.7 and later.

Declared in SecAccess.h.

CSSM Authorization Tag Type Constants

Defines 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
};
Constants
CSSM_ACL_AUTHORIZATION_TAG_VENDOR_DEFINED_START

All vendor specific constants must be in the number range starting at this value.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_ANY

No restrictions. This ACL entry applies to all operations available to the caller.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_LOGIN

Use for a CSP (smart card) login.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_GENKEY

Generate a key.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_DELETE

Delete this item.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_EXPORT_WRAPPED

Export 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 OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_EXPORT_CLEAR

Export an unencrypted key.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_IMPORT_WRAPPED

Import 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 OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_IMPORT_CLEAR

Import an unencrypted key.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_SIGN

Digitally sign data.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_ENCRYPT

Encrypt data.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_DECRYPT

Decrypt data.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_MAC

Create or verify a message authentication code.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_DERIVE

Derive a new key from another key.

Available in OS X v10.0 and later.

Declared in cssmtype.h.

CSSM_ACL_AUTHORIZATION_CHANGE_ACL

Change an access control list entry.

Available in OS X v10.0 and later.

Declared in cssmapple.h.

CSSM_ACL_AUTHORIZATION_CHANGE_OWNER

For internal system use only. Use the CSSM_ACL_AUTHORIZATION_CHANGE_ACL tag for changes to owner ACL entries.

Available in OS X v10.0 and later.

Declared in cssmapple.h.

Result Codes

The most common result codes returned by Keychain Services are listed in the table below. The assigned error space for Keychain Services is discontinuous: –25240 through –25279 and –25290 through –25329. Keychain Item Services may also return noErr (0) or paramErr (–50), or CSSM result codes (see Common Security: CDSA and CSSM, version 2 (with corrigenda) from The Open Group (http://www.opengroup.org/security/cdsa.htm)).

Result CodeValueDescription
errSecSuccess0

No error.

Available in OS X v10.6 and later.

errSecUnimplemented-4

Function or operation not implemented.

Available in OS X v10.6 and later.

errSecParam-50

One or more parameters passed to the function were not valid.

Available in OS X v10.6 and later.

errSecAllocate-108

Failed to allocate memory.

Available in OS X v10.6 and later.

errSecNotAvailable–25291

No trust results are available.

Available in OS X v10.2 and later.

errSecReadOnly–25292

Read only error.

Available in OS X v10.2 and later.

errSecAuthFailed–25293

Authorization/Authentication failed.

Available in OS X v10.2 and later.

errSecNoSuchKeychain–25294

The keychain does not exist.

Available in OS X v10.2 and later.

errSecInvalidKeychain–25295

The keychain is not valid.

Available in OS X v10.2 and later.

errSecDuplicateKeychain–25296

A keychain with the same name already exists.

Available in OS X v10.2 and later.

errSecDuplicateCallback–25297

More than one callback of the same name exists.

Available in OS X v10.2 and later.

errSecInvalidCallback–25298

The callback is not valid.

Available in OS X v10.2 and later.

errSecDuplicateItem–25299

The item already exists.

Available in OS X v10.2 and later.

errSecItemNotFound–25300

The item cannot be found.

Available in OS X v10.2 and later.

errSecBufferTooSmall–25301

The buffer is too small.

Available in OS X v10.2 and later.

errSecDataTooLarge–25302

The data is too large for the particular data type.

Available in OS X v10.2 and later.

errSecNoSuchAttr–25303

The attribute does not exist.

Available in OS X v10.2 and later.

errSecInvalidItemRef–25304

The item reference is invalid.

Available in OS X v10.2 and later.

errSecInvalidSearchRef–25305

The search reference is invalid.

Available in OS X v10.2 and later.

errSecNoSuchClass–25306

The keychain item class does not exist.

Available in OS X v10.2 and later.

errSecNoDefaultKeychain–25307

A default keychain does not exist.

Available in OS X v10.2 and later.

errSecInteractionNotAllowed–25308

Interaction with the Security Server is not allowed.

Available in OS X v10.2 and later.

errSecReadOnlyAttr–25309

The attribute is read only.

Available in OS X v10.2 and later.

errSecWrongSecVersion–25310

The version is incorrect.

Available in OS X v10.2 and later.

errSecKeySizeNotAllowed–25311

The key size is not allowed.

Available in OS X v10.2 and later.

errSecNoStorageModule–25312

There is no storage module available.

Available in OS X v10.2 and later.

errSecNoCertificateModule–25313

There is no certificate module available.

Available in OS X v10.2 and later.

errSecNoPolicyModule–25314

There is no policy module available.

Available in OS X v10.2 and later.

errSecInteractionRequired–25315

User interaction is required.

Available in OS X v10.2 and later.

errSecDataNotAvailable–25316

The data is not available.

Available in OS X v10.2 and later.

errSecDataNotModifiable–25317

The data is not modifiable.

Available in OS X v10.2 and later.

errSecCreateChainFailed–25318

The attempt to create a certificate chain failed.

Available in OS X v10.2 and later.

errSecInvalidPrefsDomain–25319

The preference domain specified is invalid. This error is available in OS X v10.3 and later.

Available in OS X v10.3 and later.

errSecInDarkWake-25320

The user interface could not be displayed because the system is in a dark wake state.

Available in OS X v10.7 and later.

errSecACLNotSimple–25240

The access control list is not in standard simple form.

Available in OS X v10.2 and later.

errSecPolicyNotFound–25241

The policy specified cannot be found.

Available in OS X v10.2 and later.

errSecInvalidTrustSetting–25262

The trust setting is invalid.

Available in OS X v10.2 and later.

errSecNoAccessForItem–25243

The specified item has no access control.

Available in OS X v10.2 and later.

errSecInvalidOwnerEdit–25244

An invalid attempt to change the owner of an item.

Available in OS X v10.2 and later.

errSecTrustNotAvailable–25245

No trust results are available.

Available in OS X v10.3 and later.

errSecUnsupportedFormat–25256

The specified import or export format is not supported.

Available in OS X v10.4 and later.

errSecUnknownFormat–25257

The item you are trying to import has an unknown format.

Available in OS X v10.4 and later.

errSecKeyIsSensitive–25258

The key must be wrapped to be exported.

Available in OS X v10.4 and later.

errSecMultiplePrivKeys–25259

An attempt was made to import multiple private keys.

Available in OS X v10.4 and later.

errSecPassphraseRequired–25260

A password is required for import or export.

Available in OS X v10.4 and later.

errSecInvalidPasswordRef-25261

The password reference was invalid.

Available in OS X v10.4 and later.

errSecInvalidTrustSettings-25262

The trust settings record was corrupted.

Available in OS X v10.5 and later.

errSecNoTrustSettings-25263

No trust settings were found.

Available in OS X v10.5 and later.

errSecPkcs12VerifyFailure-25264

MAC verification failed during PKCS12 Import.

Available in OS X v10.5 and later.

errSecNotSigner-26267

The certificate was not signed by its proposed parent.

Available in OS X v10.7 and later.

errSecDecode-26275

Unable to decode the provided data.

Available in OS X v10.6 and later.

errSecServiceNotAvailable-67585

The required service is not available.

Available in OS X v10.7 and later.

errSecInsufficientClientID-67586

The client ID is not correct.

Available in OS X v10.7 and later.

errSecDeviceReset-67587

A device reset has occurred.

Available in OS X v10.7 and later.

errSecDeviceFailed-67588

A device failure has occurred.

Available in OS X v10.7 and later.

errSecAppleAddAppACLSubject-67589

Adding an application ACL subject failed.

Available in OS X v10.7 and later.

errSecApplePublicKeyIncomplete-67590

The public key is incomplete.

Available in OS X v10.7 and later.

errSecAppleSignatureMismatch-67591

A signature mismatch has occurred.

Available in OS X v10.7 and later.

errSecAppleInvalidKeyStartDate-67592

The specified key has an invalid start date.

Available in OS X v10.7 and later.

errSecAppleInvalidKeyEndDate-67593

The specified key has an invalid end date.

Available in OS X v10.7 and later.

errSecConversionError-67594

A conversion error has occurred.

Available in OS X v10.7 and later.

errSecAppleSSLv2Rollback-67595

A SSLv2 rollback error has occurred.

Available in OS X v10.7 and later.

errSecDiskFull-34

The disk is full.

Available in OS X v10.7 and later.

errSecQuotaExceeded-67596

The quota was exceeded.

Available in OS X v10.7 and later.

errSecFileTooBig-67597

The file is too big.

Available in OS X v10.7 and later.

errSecInvalidDatabaseBlob-67598

The specified database has an invalid blob.

Available in OS X v10.7 and later.

errSecInvalidKeyBlob-67599

The specified database has an invalid key blob.

Available in OS X v10.7 and later.

errSecIncompatibleDatabaseBlob-67600

The specified database has an incompatible blob.

Available in OS X v10.7 and later.

errSecIncompatibleKeyBlob-67601

The specified database has an incompatible key blob.

Available in OS X v10.7 and later.

errSecHostNameMismatch-67602

A host name mismatch has occurred.

Available in OS X v10.7 and later.

errSecUnknownCriticalExtensionFlag-67603

There is an unknown critical extension flag.

Available in OS X v10.7 and later.

errSecNoBasicConstraints-67604

No basic constraints were found.

Available in OS X v10.7 and later.

errSecNoBasicConstraintsCA-67605

No basic CA constraints were found.

Available in OS X v10.7 and later.

errSecInvalidAuthorityKeyID-67606

The authority key ID is not valid.

Available in OS X v10.7 and later.

errSecInvalidSubjectKeyID-67607

The subject key ID is not valid.

Available in OS X v10.7 and later.

errSecInvalidKeyUsageForPolicy-67608

The key usage is not valid for the specified policy.

Available in OS X v10.7 and later.

errSecInvalidExtendedKeyUsage-67609

The extended key usage is not valid.

Available in OS X v10.7 and later.

errSecInvalidIDLinkage-67610

The ID linkage is not valid.

Available in OS X v10.7 and later.

errSecPathLengthConstraintExceeded-67611

The path length constraint was exceeded.

Available in OS X v10.7 and later.

errSecInvalidRoot-67612

The root or anchor certificate is not valid.

Available in OS X v10.7 and later.

errSecCRLExpired-67613

The CRL has expired.

Available in OS X v10.7 and later.

errSecCRLNotValidYet-67614

The CRL is not yet valid.

Available in OS X v10.7 and later.

errSecCRLNotFound-67615

The CRL was not found.

Available in OS X v10.7 and later.

errSecCRLServerDown-67616

The CRL server is down.

Available in OS X v10.7 and later.

errSecCRLBadURI-67617

The CRL has a bad Uniform Resource Identifier.

Available in OS X v10.7 and later.

errSecUnknownCertExtension-67618

An unknown certificate extension was encountered.

Available in OS X v10.7 and later.

errSecUnknownCRLExtension-67619

An unknown CRL extension was encountered.

Available in OS X v10.7 and later.

errSecCRLNotTrusted-67620

The CRL is not trusted.

Available in OS X v10.7 and later.

errSecCRLPolicyFailed-67621

The CRL policy failed.

Available in OS X v10.7 and later.

errSecIDPFailure-67622

The issuing distribution point was not valid.

Available in OS X v10.7 and later.

errSecSMIMEEmailAddressesNotFound-67623

An email address mismatch was encountered.

Available in OS X v10.7 and later.

errSecSMIMEBadExtendedKeyUsage-67624

The appropriate extended key usage for SMIME was not found.

Available in OS X v10.7 and later.

errSecSMIMEBadKeyUsage-67625

The key usage is not compatible with SMIME.

Available in OS X v10.7 and later.

errSecSMIMEKeyUsageNotCritical-67626

The key usage extension is not marked as critical.

Available in OS X v10.7 and later.

errSecSMIMENoEmailAddress-67627

No email address was found in the certificate.

Available in OS X v10.7 and later.

errSecSMIMESubjAltNameNotCritical-67628

The subject alternative name extension is not marked as critical.

Available in OS X v10.7 and later.

errSecSSLBadExtendedKeyUsage-67629

The appropriate extended key usage for SSL was not found.

Available in OS X v10.7 and later.

errSecOCSPBadResponse-67630

The OCSP response was incorrect or could not be parsed.

Available in OS X v10.7 and later.

errSecOCSPBadRequest-67631

The OCSP request was incorrect or could not be parsed.

Available in OS X v10.7 and later.

errSecOCSPUnavailable-67632

OCSP service is unavailable.

Available in OS X v10.7 and later.

errSecOCSPStatusUnrecognized-67633

The OCSP server did not recognize this certificate.

Available in OS X v10.7 and later.

errSecEndOfData-67634

An end-of-data was detected.

Available in OS X v10.7 and later.

errSecIncompleteCertRevocationCheck-67635

An incomplete certificate revocation check occurred.

Available in OS X v10.7 and later.

errSecNetworkFailure-67636

A network failure occurred.

Available in OS X v10.7 and later.

errSecOCSPNotTrustedToAnchor-67637

The OCSP response was not trusted to a root or anchor certificate.

Available in OS X v10.7 and later.

errSecRecordModified-67638

The record was modified.

Available in OS X v10.7 and later.

errSecOCSPSignatureError-67639

The OCSP response had an invalid signature.

Available in OS X v10.7 and later.

errSecOCSPNoSigner-67640

The OCSP response had no signer.

Available in OS X v10.7 and later.

errSecOCSPResponderMalformedReq-67641

The OCSP responder was given a malformed request.

Available in OS X v10.7 and later.

errSecOCSPResponderInternalError-67642

The OCSP responder encountered an internal error.

Available in OS X v10.7 and later.

errSecOCSPResponderTryLater-67643

The OCSP responder is busy, try again later.

Available in OS X v10.7 and later.

errSecOCSPResponderSignatureRequired-67644

The OCSP responder requires a signature.

Available in OS X v10.7 and later.

errSecOCSPResponderUnauthorized-67645

The OCSP responder rejected this request as unauthorized.

Available in OS X v10.7 and later.

errSecOCSPResponseNonceMismatch-67646

The OCSP response nonce did not match the request.

Available in OS X v10.7 and later.

errSecCodeSigningBadCertChainLength-67647

Code signing encountered an incorrect certificate chain length.

Available in OS X v10.7 and later.

errSecCodeSigningNoBasicConstraints-67648

Code signing found no basic constraints.

Available in OS X v10.7 and later.

errSecCodeSigningBadPathLengthConstraint

Code signing encountered an incorrect path length constraint.

Available in OS X v10.7 and later.

errSecCodeSigningNoExtendedKeyUsage-67650

Code signing found no extended key usage.

Available in OS X v10.7 and later.

errSecCodeSigningDevelopment-67651

Code signing indicated use of a development-only certificate.

Available in OS X v10.7 and later.

errSecResourceSignBadCertChainLength-67652

Resource signing has encountered an incorrect certificate chain length.

Available in OS X v10.7 and later.

errSecResourceSignBadExtKeyUsage-67653

Resource signing has encountered an error in the extended key usage.

Available in OS X v10.7 and later.

errSecTrustSettingDeny-67654

The trust setting for this policy was set to Deny.

Available in OS X v10.7 and later.

errSecInvalidSubjectName-67655

An invalid certificate subject name was encountered.

Available in OS X v10.7 and later.

errSecUnknownQualifiedCertStatement-67656

An unknown qualified certificate statement was encountered.

Available in OS X v10.7 and later.

errSecMobileMeRequestQueued-67657

The MobileMe request will be sent during the next connection.

Available in OS X v10.7 and later.

errSecMobileMeRequestRedirected-67658

The MobileMe request was redirected.

Available in OS X v10.7 and later.

errSecMobileMeServerError-67659

A MobileMe server error occurred.

Available in OS X v10.7 and later.

errSecMobileMeServerNotAvailable-67660

The MobileMe server is not available.

Available in OS X v10.7 and later.

errSecMobileMeServerAlreadyExists-67661

The MobileMe server reported that the item already exists.

Available in OS X v10.7 and later.

errSecMobileMeServerServiceErr-67662

A MobileMe service error has occurred.

Available in OS X v10.7 and later.

errSecMobileMeRequestAlreadyPending-67663

A MobileMe request is already pending.

Available in OS X v10.7 and later.

errSecMobileMeNoRequestPending-67664

MobileMe has no request pending.

Available in OS X v10.7 and later.

errSecMobileMeCSRVerifyFailure-67665

A MobileMe CSR verification failure has occurred.

Available in OS X v10.7 and later.

errSecMobileMeFailedConsistencyCheck-67666

MobileMe has found a failed consistency check.

Available in OS X v10.7 and later.

errSecNotInitialized-67667

A function was called without initializing CSSM.

Available in OS X v10.7 and later.

errSecInvalidHandleUsage-67668

The CSSM handle does not match with the service type.

Available in OS X v10.7 and later.

errSecPVCReferentNotFound-67669

A reference to the calling module was not found in the list of authorized callers.

Available in OS X v10.7 and later.

errSecFunctionIntegrityFail-67670

A function address was not within the verified module.

Available in OS X v10.7 and later.

errSecInternalError-67671

An internal error has occurred.

Available in OS X v10.7 and later.

errSecMemoryError-67672

A memory error has occurred.

Available in OS X v10.7 and later.

errSecInvalidData-67673

Invalid data was encountered.

Available in OS X v10.7 and later.

errSecMDSError-67674

A Module Directory Service error has occurred.

Available in OS X v10.7 and later.

errSecInvalidPointer-67675

An invalid pointer was encountered.

Available in OS X v10.7 and later.

errSecSelfCheckFailed-67676

Self-check has failed.

Available in OS X v10.7 and later.

errSecFunctionFailed-67677

A function has failed.

Available in OS X v10.7 and later.

errSecModuleManifestVerifyFailed-67678

A module manifest verification failure has occurred.

Available in OS X v10.7 and later.

errSecInvalidGUID-67679

An invalid GUID was encountered.

Available in OS X v10.7 and later.

errSecInvalidHandle-67680

An invalid handle was encountered.

Available in OS X v10.7 and later.

errSecInvalidDBList-67681

An invalid DB list was encountered.

Available in OS X v10.7 and later.

errSecInvalidPassthroughID-67682

An invalid passthrough ID was encountered.

Available in OS X v10.7 and later.

errSecInvalidNetworkAddress-67683

An invalid network address was encountered.

Available in OS X v10.7 and later.

errSecCRLAlreadySigned-67684

The certificate revocation list is already signed.

Available in OS X v10.7 and later.

errSecInvalidNumberOfFields-67685

An invalid number of fields were encountered.

Available in OS X v10.7 and later.

errSecVerificationFailure-67686

A verification failure occurred.

Available in OS X v10.7 and later.

errSecUnknownTag-67687

An unknown tag was encountered.

Available in OS X v10.7 and later.

errSecInvalidSignature-67688

An invalid signature was encountered.

Available in OS X v10.7 and later.

errSecInvalidName-67689

An invalid name was encountered.

Available in OS X v10.7 and later.

errSecInvalidCertificateRef-67690

An invalid certificate reference was encountered.

Available in OS X v10.7 and later.

errSecInvalidCertificateGroup-67691

An invalid certificate group was encountered.

Available in OS X v10.7 and later.

errSecTagNotFound-67692

The specified tag was not found.

Available in OS X v10.7 and later.

errSecInvalidQuery-67693

The specified query was not valid.

Available in OS X v10.7 and later.

errSecInvalidValue-67694

An invalid value was detected.

Available in OS X v10.7 and later.

errSecCallbackFailed-67695

A callback has failed.

Available in OS X v10.7 and later.

errSecACLDeleteFailed-67696

An ACL delete operation has failed.

Available in OS X v10.7 and later.

errSecACLReplaceFailed-67697

An ACL replace operation has failed.

Available in OS X v10.7 and later.

errSecACLAddFailed-67698

An ACL add operation has failed.

Available in OS X v10.7 and later.

errSecACLChangeFailed-67699

An ACL change operation has failed.

Available in OS X v10.7 and later.

errSecInvalidAccessCredentials-67700

Invalid access credentials were encountered.

Available in OS X v10.7 and later.

errSecInvalidRecord-67701

An invalid record was encountered.

Available in OS X v10.7 and later.

errSecInvalidACL-67702

An invalid ACL was encountered.

Available in OS X v10.7 and later.

errSecInvalidSampleValue-67703

An invalid sample value was encountered.

Available in OS X v10.7 and later.

errSecIncompatibleVersion-67704

An incompatible version was encountered.

Available in OS X v10.7 and later.

errSecPrivilegeNotGranted-67705

The privilege was not granted.

Available in OS X v10.7 and later.

errSecInvalidScope-67706

An invalid scope was encountered.

Available in OS X v10.7 and later.

errSecPVCAlreadyConfigured-67707

The PVC is already configured.

Available in OS X v10.7 and later.

errSecInvalidPVC-67708

An invalid PVC was encountered.

Available in OS X v10.7 and later.

errSecEMMLoadFailed-67709

The EMM load has failed.

Available in OS X v10.7 and later.

errSecEMMUnloadFailed-67710

The EMM unload has failed.

Available in OS X v10.7 and later.

errSecAddinLoadFailed-67711

The add-in load operation has failed.

Available in OS X v10.7 and later.

errSecInvalidKeyRef-67712

An invalid key was encountered.

Available in OS X v10.7 and later.

errSecInvalidKeyHierarchy-67713

An invalid key hierarchy was encountered.

Available in OS X v10.7 and later.

errSecAddinUnloadFailed-67714

The add-in unload operation has failed.

Available in OS X v10.7 and later.

errSecLibraryReferenceNotFound-67715

A library reference was not found.

Available in OS X v10.7 and later.

errSecInvalidAddinFunctionTable-67716

An invalid add-in function table was encountered.

Available in OS X v10.7 and later.

errSecInvalidServiceMask-67717

An invalid service mask was encountered.

Available in OS X v10.7 and later.

errSecModuleNotLoaded-67718

A module was not loaded.

Available in OS X v10.7 and later.

errSecInvalidSubServiceID-67719

An invalid subservice ID was encountered.

Available in OS X v10.7 and later.

errSecAttributeNotInContext-67720

An attribute was not in the context.

Available in OS X v10.7 and later.

errSecModuleManagerInitializeFailed-67721

A module failed to initialize.

Available in OS X v10.7 and later.

errSecModuleManagerNotFound-67722

A module was not found.

Available in OS X v10.7 and later.

errSecEventNotificationCallbackNotFound-67723

An event notification callback was not found.

Available in OS X v10.7 and later.

errSecInputLengthError-67724

An input length error was encountered.

Available in OS X v10.7 and later.

errSecOutputLengthError-67725

An output length error was encountered.

Available in OS X v10.7 and later.

errSecPrivilegeNotSupported-67726

The privilege is not supported.

Available in OS X v10.7 and later.

errSecDeviceError-67727

A device error was encountered.

Available in OS X v10.7 and later.

errSecAttachHandleBusy-67728

The CSP handle was busy.

Available in OS X v10.7 and later.

errSecNotLoggedIn-67729

You are not logged in.

Available in OS X v10.7 and later.

errSecAlgorithmMismatch-67730

An algorithm mismatch was encountered.

Available in OS X v10.7 and later.

errSecKeyUsageIncorrect-67731

The key usage is incorrect.

Available in OS X v10.7 and later.

errSecKeyBlobTypeIncorrect-67732

The key blob type is incorrect.

Available in OS X v10.7 and later.

errSecKeyHeaderInconsistent-67733

The key header is inconsistent.

Available in OS X v10.7 and later.

errSecUnsupportedKeyFormat-67734

The key header format is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedKeySize-67735

The key size is not supported.

Available in OS X v10.7 and later.

errSecInvalidKeyUsageMask-67736

The key usage mask is not valid.

Available in OS X v10.7 and later.

errSecUnsupportedKeyUsageMask-67737

The key usage mask is not supported.

Available in OS X v10.7 and later.

errSecInvalidKeyAttributeMask-67738

The key attribute mask is not valid.

Available in OS X v10.7 and later.

errSecUnsupportedKeyAttributeMask-67739

The key attribute mask is not supported.

Available in OS X v10.7 and later.

errSecInvalidKeyLabel-67740

The key label is not valid.

Available in OS X v10.7 and later.

errSecUnsupportedKeyLabel-67741

The key label is not supported.

Available in OS X v10.7 and later.

errSecInvalidKeyFormat-67742

The key format is not valid.

Available in OS X v10.7 and later.

errSecUnsupportedVectorOfBuffers-67743

The vector of buffers is not supported.

Available in OS X v10.7 and later.

errSecInvalidInputVector-67744

The input vector is not valid.

Available in OS X v10.7 and later.

errSecInvalidOutputVector-67745

The output vector is not valid.

Available in OS X v10.7 and later.

errSecInvalidContext-67746

An invalid context was encountered.

Available in OS X v10.7 and later.

errSecInvalidAlgorithm-67747

An invalid algorithm was encountered.

Available in OS X v10.7 and later.

errSecInvalidAttributeKey-67748

A key attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeKey-67749

A key attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeInitVector-67750

An init vector attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeInitVector-67751

An init vector attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeSalt-67752

A salt attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeSalt-67753

A salt attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributePadding-67754

A padding attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributePadding-67755

A padding attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeRandom-67756

A random number attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeRandom-67757

A random number attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeSeed-67758

A seed attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeSeed-67759

A seed attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributePassphrase-67760

A passphrase attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributePassphrase-67761

A passphrase attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeKeyLength-67762

A key length attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeKeyLength-67763

A key length attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeBlockSize-67764

A block size attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeBlockSize-67765

A block size attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeOutputSize-67766

An output size attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeOutputSize-67767

An output size attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeRounds-67768

The number of rounds attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeRounds-67769

The number of rounds attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAlgorithmParms-67770

An algorithm parameters attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAlgorithmParms-67771

An algorithm parameters attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeLabel-67772

A label attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeLabel-67773

A label attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeKeyType-67774

A key type attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeKeyType-67775

A key type attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeMode-67776

A mode attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeMode-67777

A mode attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeEffectiveBits-67778

An effective bits attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeEffectiveBits-67779

An effective bits attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeStartDate-67780

A start date attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeStartDate-67781

A start date attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeEndDate-67782

An end date attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeEndDate-67783

An end date attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeVersion-67784

A version attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeVersion-67785

A version attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributePrime-67786

A prime attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributePrime-67787

A prime attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeBase-67788

A base attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeBase-67789

A base attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeSubprime-67790

A subprime attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeSubprime-67791

A subprime attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeIterationCount-67792

An iteration count attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeIterationCount-67793

An iteration count attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeDLDBHandle-67794

A database handle attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeDLDBHandle-67795

A database handle attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeAccessCredentials-67796

An access credentials attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeAccessCredentials-67797

An access credentials attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributePublicKeyFormat-67798

A public key format attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributePublicKeyFormat-67799

A public key format attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributePrivateKeyFormat-67800

A private key format attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributePrivateKeyFormat-67801

A private key format attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeSymmetricKeyFormat-67802

A symmetric key format attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeSymmetricKeyFormat-67803

A symmetric key format attribute was missing.

Available in OS X v10.7 and later.

errSecInvalidAttributeWrappedKeyFormat-67804

A wrapped key format attribute was not valid.

Available in OS X v10.7 and later.

errSecMissingAttributeWrappedKeyFormat-67805

A wrapped key format attribute was missing.

Available in OS X v10.7 and later.

errSecStagedOperationInProgress-67806

A staged operation is in progress.

Available in OS X v10.7 and later.

errSecStagedOperationNotStarted-67807

A staged operation was not started.

Available in OS X v10.7 and later.

errSecVerifyFailed-67808

A cryptographic verification failure has occurred.

Available in OS X v10.7 and later.

errSecQuerySizeUnknown-67809

The query size is unknown.

Available in OS X v10.7 and later.

errSecBlockSizeMismatch-67810

A block size mismatch occurred.

Available in OS X v10.7 and later.

errSecPublicKeyInconsistent-67811

The public key was inconsistent.

Available in OS X v10.7 and later.

errSecDeviceVerifyFailed-67812

A device verification failure has occurred.

Available in OS X v10.7 and later.

errSecInvalidLoginName-67813

An invalid login name was detected.

Available in OS X v10.7 and later.

errSecAlreadyLoggedIn-67814

The user is already logged in.

Available in OS X v10.7 and later.

errSecInvalidDigestAlgorithm-67815

An invalid digest algorithm was detected.

Available in OS X v10.7 and later.

errSecInvalidCRLGroup-67816

An invalid CRL group was detected.

Available in OS X v10.7 and later.

errSecCertificateCannotOperate-67817

The certificate cannot operate.

Available in OS X v10.7 and later.

errSecCertificateExpired-67818

An expired certificate was detected.

Available in OS X v10.7 and later.

errSecCertificateNotValidYet-67819

The certificate is not yet valid.

Available in OS X v10.7 and later.

errSecCertificateRevoked-67820

The certificate was revoked.

Available in OS X v10.7 and later.

errSecCertificateSuspended-67821

The certificate was suspended.

Available in OS X v10.7 and later.

errSecInsufficientCredentials-67822

Insufficient credentials were detected.

Available in OS X v10.7 and later.

errSecInvalidAction-67823

The action was not valid.

Available in OS X v10.7 and later.

errSecInvalidAuthority-67824

The authority was not valid.

Available in OS X v10.7 and later.

errSecVerifyActionFailed-67825

A verify action has failed.

Available in OS X v10.7 and later.

errSecInvalidCertAuthority-67826

The certificate authority was not valid.

Available in OS X v10.7 and later.

errSecInvaldCRLAuthority-67827

The CRL authority was not valid.

Available in OS X v10.7 and later.

errSecInvalidCRLEncoding-67828

The CRL encoding was not valid.

Available in OS X v10.7 and later.

errSecInvalidCRLType-67829

The CRL type was not valid.

Available in OS X v10.7 and later.

errSecInvalidCRL-67830

The CRL was not valid.

Available in OS X v10.7 and later.

errSecInvalidFormType-67831

The form type was not valid.

Available in OS X v10.7 and later.

errSecInvalidID-67832

The ID was not valid.

Available in OS X v10.7 and later.

errSecInvalidIdentifier-67833

The identifier was not valid.

Available in OS X v10.7 and later.

errSecInvalidIndex-67834

The index was not valid.

Available in OS X v10.7 and later.

errSecInvalidPolicyIdentifiers-67835

The policy identifiers are not valid.

Available in OS X v10.7 and later.

errSecInvalidTimeString-67836

The time specified was not valid.

Available in OS X v10.7 and later.

errSecInvalidReason-67837

The trust policy reason was not valid.

Available in OS X v10.7 and later.

errSecInvalidRequestInputs-67838

The request inputs are not valid.

Available in OS X v10.7 and later.

errSecInvalidResponseVector-67839

The response vector was not valid.

Available in OS X v10.7 and later.

errSecInvalidStopOnPolicy-67840

The stop-on policy was not valid.

Available in OS X v10.7 and later.

errSecInvalidTuple-67841

The tuple was not valid.

Available in OS X v10.7 and later.

errSecMultipleValuesUnsupported-67842

Multiple values are not supported.

Available in OS X v10.7 and later.

errSecNotTrusted-67843

The trust policy was not trusted.

Available in OS X v10.7 and later.

errSecNoDefaultAuthority-67844

No default authority was detected.

Available in OS X v10.7 and later.

errSecRejectedForm-67845

The trust policy had a rejected form.

Available in OS X v10.7 and later.

errSecRequestLost-67846

The request was lost.

Available in OS X v10.7 and later.

errSecRequestRejected-67847

The request was rejected.

Available in OS X v10.7 and later.

errSecUnsupportedAddressType-67848

The address type is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedService-67849

The service is not supported.

Available in OS X v10.7 and later.

errSecInvalidTupleGroup-67850

The tuple group was not valid.

Available in OS X v10.7 and later.

errSecInvalidBaseACLs-67851

The base ACLs are not valid.

Available in OS X v10.7 and later.

errSecInvalidTupleCredendtials-67852

The tuple credentials are not valid.

Available in OS X v10.7 and later.

errSecInvalidEncoding-67853

The encoding was not valid.

Available in OS X v10.7 and later.

errSecInvalidValidityPeriod-67854

The validity period was not valid.

Available in OS X v10.7 and later.

errSecInvalidRequestor-67855

The requestor was not valid.

Available in OS X v10.7 and later.

errSecRequestDescriptor-67856

The request descriptor was not valid.

Available in OS X v10.7 and later.

errSecInvalidBundleInfo-67857

The bundle information was not valid.

Available in OS X v10.7 and later.

errSecInvalidCRLIndex-67858

The CRL index was not valid.

Available in OS X v10.7 and later.

errSecNoFieldValues-67859

No field values were detected.

Available in OS X v10.7 and later.

errSecUnsupportedFieldFormat-67860

The field format is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedIndexInfo-67861

The index information is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedLocality-67862

The locality is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedNumAttributes-67863

The number of attributes is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedNumIndexes-67864

The number of indexes is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedNumRecordTypes-67865

The number of record types is not supported.

Available in OS X v10.7 and later.

errSecFieldSpecifiedMultiple-67866

Too many fields were specified.

Available in OS X v10.7 and later.

errSecIncompatibleFieldFormat-67867

The field format was incompatible.

Available in OS X v10.7 and later.

errSecInvalidParsingModule-67868

The parsing module was not valid.

Available in OS X v10.7 and later.

errSecDatabaseLocked-67869

The database is locked.

Available in OS X v10.7 and later.

errSecDatastoreIsOpen-67870

The data store is open.

Available in OS X v10.7 and later.

errSecMissingValue-67871

A missing value was detected.

Available in OS X v10.7 and later.

errSecUnsupportedQueryLimits-67872

The query limits are not supported.

Available in OS X v10.7 and later.

errSecUnsupportedNumSelectionPreds-67873

The number of selection predicates is not supported.

Available in OS X v10.7 and later.

errSecUnsupportedOperator-67874

The operator is not supported.

Available in OS X v10.7 and later.

errSecInvalidDBLocation-67875

The database location is not valid.

Available in OS X v10.7 and later.

errSecInvalidAccessRequest-67876

The access request is not valid.

Available in OS X v10.7 and later.

errSecInvalidIndexInfo-67877

The index information is not valid.

Available in OS X v10.7 and later.

errSecInvalidNewOwner-67878

The new owner is not valid.

Available in OS X v10.7 and later.

errSecInvalidModifyMode-67879

The modify mode is not valid.

Available in OS X v10.7 and later.

errSecMissingRequiredExtension-67880

A required certificate extension is missing.

Available in OS X v10.7 and later.

errSecExtendedKeyUsageNotCritical-67881

The extended key usage extension was not marked critical.

Available in OS X v10.7 and later.

errSecTimestampMissing-67882

A timestamp was expected but was not found.

Available in OS X v10.7 and later.

errSecTimestampInvalid-67883

The timestamp was not valid.

Available in OS X v10.7 and later.

errSecTimestampNotTrusted-67884

The timestamp was not trusted.

Available in OS X v10.7 and later.

errSecTimestampServiceNotAvailable-67885

The timestamp service is not available.

Available in OS X v10.7 and later.

errSecTimestampBadAlg-67886

Found an unrecognized or unsupported algorithm identifier (AI) in timestamp.

Available in OS X v10.7 and later.

errSecTimestampBadRequest-67887

The timestamp transaction is not permitted or supported.

Available in OS X v10.7 and later.

errSecTimestampBadDataFormat-67888

The timestamp data submitted has the wrong format.

Available in OS X v10.7 and later.

errSecTimestampTimeNotAvailable-67889

The time source for the timestamp authority is not available.

Available in OS X v10.7 and later.

errSecTimestampUnacceptedPolicy-67890

The requested policy is not supported by the timestamp authority.

Available in OS X v10.7 and later.

errSecTimestampUnacceptedExtension-67891

The requested extension is not supported by the timestamp authority.

Available in OS X v10.7 and later.

errSecTimestampAddInfoNotAvailable-67892

The additional information requested is not available.

Available in OS X v10.7 and later.

errSecTimestampSystemFailure-67893

The timestamp request cannot be handled due to a system failure .

Available in OS X v10.7 and later.

errSecSigningTimeMissing-67894

A signing time was expected but was not found.

Available in OS X v10.7 and later.

errSecTimestampRejection-67895

A timestamp transaction was rejected.

Available in OS X v10.7 and later.

errSecTimestampWaiting-67896

A timestamp transaction is waiting.

Available in OS X v10.7 and later.

errSecTimestampRevocationWarning-67897

A timestamp authority revocation warning was issued.

Available in OS X v10.7 and later.

errSecTimestampRevocationNotification-67898

A timestamp authority revocation notification was issued.

Available in OS X v10.7 and later.