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() -> CFTypeID

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?>?) -> OSStatus

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

Modifies items that match a search query.

func SecItemDelete(CFDictionary) -> OSStatus

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.

struct SecAccessControlCreateFlags

Access control constants 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() -> CFTypeID

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

Legacy Keychain Item Management

Use the functions in Keychain Item Search instead.

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

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?) -> OSStatus

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

func SecKeychainItemDelete(SecKeychainItem) -> OSStatus

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

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 keychain items in macOS.