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.

class SecKeychainItem

An opaque type that represents a keychain item.

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

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.

func SecItemCopyMatching(CFDictionary, UnsafeMutablePointer<CFTypeRef?>?)

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.

func SecItemUpdate(CFDictionary, CFDictionary)

Modifies items that match a search query.

func SecItemDelete(CFDictionary)

Deletes items that match a search query.

Keychain Item Access

struct SecAccessControlCreateFlags

The constants you apply to an access control object that dictate how a keychain item may be used.

class SecAccessControl

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

func SecAccessControlGetTypeID()

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

Import and Export

Legacy Keychain Item Management

Use the functions in Keychain Item Search instead.

func SecKeychainItemFreeAttributesAndData(UnsafeMutablePointer<SecKeychainAttributeList>?, UnsafeMutableRawPointer?)

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

func SecKeychainItemFreeContent(UnsafeMutablePointer<SecKeychainAttributeList>?, UnsafeMutableRawPointer?)

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

func SecKeychainItemDelete(SecKeychainItem)

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

typealias SecKeychainAttrType

The keychain attribute type.

struct SecKeychainAttribute

A structure that holds a single keychain attribute.

typealias SecKeychainAttributePtr

A pointer to a keychain attribute structure.

struct SecKeychainAttributeList

A list of keychain attributes.

Legacy Attribute Info

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

func SecKeychainFreeAttributeInfo(UnsafeMutablePointer<SecKeychainAttributeInfo>)

Releases the memory acquired by calling the SecKeychainAttributeInfoForItemID function.

struct SecKeychainAttributeInfo

A structure that represents an attribute.

enum SecItemAttr

Specifies a keychain item’s attributes.

Keychain Item Attribute Constants For Keys

Specifies the attributes for a key item in a keychain.

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

See Also

API Components

Keychains

Create and manage entire keychains in macOS.

Access Control Lists

Control which apps have access to keychains and keychain items in macOS.