Keychain Items

Embed confidential information in items that you store in a keychain.

Overview

When you want to store a secret such as a password or cryptographic key, you package it as a keychain item. Along with the data itself, you provide a set of publicly visible attributes both to control the item’s accessibility and to make it searchable. As shown in Figure 1, keychain services handles data encryption and storage (including data attributes) in a keychain, which is an encrypted database stored on disk. Later, authorized processes use keychain services to find the item and decrypt its data.

Figure 1

Putting data and attributes into a keychain

Diagram showing data being encrypted and then combined with attributes into a keychain item before being stored in a keychain.

Topics

First Steps

Using the Keychain to Manage User Secrets

Relieve the user of remembering small secrets by storing them in the keychain.

SecKeychainItemRef

An opaque type that represents a keychain item.

SecKeychainItemGetTypeID

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

Adding Keychain Items

Adding a Password to the Keychain

Add network credentials to the keychain on behalf of the user.

SecItemAdd

Adds one or more items to a keychain.

Item Class Keys and Values

Specify the class of a keychain item.

Item Attribute Keys and Values

Specify the attributes of keychain items.

Keychain Item Search

Searching for Keychain Items

Find keychain items based on search criteria that you specify.

SecItemCopyMatching

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

Item Return Result Keys

Specify how you want returned keychain item data formatted.

Keychain Item Modification

Updating and Deleting Keychain Items

Modify items in the keychain when the user’s data changes.

SecItemUpdate

Modifies items that match a search query.

SecItemDelete

Deletes items that match a search query.

Keychain Item Access

Sharing Access to Keychain Items Among a Collection of Apps

Enable apps to share keychain items with each other by adding the apps to an access group.

Restricting Keychain Item Accessibility

Set the conditions under which an app can access a keychain item such as a password.

SecAccessControlCreateWithFlags

Creates a new access control object with the specified protection type and flags.

SecAccessControlCreateFlags

Access control constants that dictate how a keychain item may be used.

SecAccessControlRef

An opaque type that contains information about how a keychain item may be used.

SecAccessControlGetTypeID

Returns the unique identifier of the opaque type to which a keychain item access control object belongs.

Import and Export

SecItemImport

Imports one or more certificates, keys, or identities and optionally adds them to a keychain.

SecItemExport

Exports one or more certificates, keys, or identities.

SecExternalFormat

The external format of a keychain item.

SecExternalItemType

The import item type.

SecItemImportExportFlags

The import and export function flags.

SecItemImportExportKeyParameters

The import/export parameter structure.

SecKeyImportExportFlags

The import/export parameter structure flags.

SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION

The import/export parameter structure version.

SecKeychainItemImport

Imports one or more certificates, keys, or identities and adds them to a keychain.

Deprecated
SecKeychainItemExport

Exports one or more certificates, keys, or identities.

Deprecated
SecKeyImportExportParameters

The legacy import/export parameter structure.

Legacy Keychain Item Creation

Use the functions in Adding Keychain Items instead.

SecKeychainItemCreateFromContent

Creates a new keychain item from the supplied parameters.

SecKeychainItemCreateCopy

Copies a keychain item from one keychain to another.

SecKeychainItemCreatePersistentReference

Creates a persistent reference for a keychain item.

SecKeychainItemCopyFromPersistentReference

Provides a keychain item reference, given a persistent reference.

SecItemClass

Specifies a keychain item’s class code.

Legacy Keychain Item Management

Use the functions in Keychain Item Search instead.

SecKeychainItemCopyAttributesAndData

Retrieves the data and/or attributes stored in the given keychain item.

SecKeychainItemModifyAttributesAndData

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

SecKeychainItemFreeAttributesAndData

Releases the memory used by the keychain attribute list and/or the keychain data retrieved in a call to SecKeychainItemCopyAttributesAndData.

SecKeychainItemCopyContent

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

SecKeychainItemModifyContent

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

SecKeychainItemFreeContent

Releases the memory used by the keychain attribute list and the keychain data retrieved in a call to the SecKeychainItemCopyContent function.

SecKeychainItemCopyKeychain

Returns the keychain object of a given keychain item.

SecKeychainItemDelete

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

SecKeychainAttrType

The keychain attribute type.

SecKeychainAttribute

A structure that holds a single keychain attribute.

SecKeychainAttributePtr

A pointer to a keychain attribute structure.

SecKeychainAttributeList

A list of keychain attributes.

Legacy Attribute Info

Use the functions in Adding Keychain Items and Keychain Item Search instead.

SecKeychainAttributeInfoForItemID

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

SecKeychainFreeAttributeInfo

Releases the memory acquired by calling the SecKeychainAttributeInfoForItemID function.

SecKeychainAttributeInfo

A structure that represents an attribute.

SecItemAttr

Specifies a keychain item’s attributes.

Keychain Item Attribute Constants For Keys

Specifies the attributes for a key item in a keychain.

SecAFPServerSignature

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

Legacy Password Storage

Use the functions in Adding Keychain Items and Keychain Item Search instead.

SecKeychainAddInternetPassword

Adds a new Internet password to a keychain.

SecKeychainFindInternetPassword

Finds the first Internet password based on the attributes passed.

SecKeychainAddGenericPassword

Adds a new generic password to a keychain.

SecKeychainFindGenericPassword

Finds the first generic password based on the attributes passed.

SecProtocolType

The protocol type associated with an Internet password.

SecAuthenticationType

The authentication type to use for an Internet password.

SecPasswordRef

Contains information about a password.

See Also

API Components

Keychains

Create and manage entire keychains in macOS.

Access Control Lists

Control which apps have access to keychain items in macOS.