Keychains

Create and manage entire keychains in macOS.

Overview

In iOS, apps have access to a single keychain (which logically encompasses the iCloud keychain). This keychain is automatically unlocked when the user unlocks the device and then locked when the device is locked. An app can access only its own keychain items, or those shared with a group to which the app belongs. It can't manage the keychain container itself.

In macOS, however, the system supports an arbitrary number of keychains. You typically rely on the user to manage these with the Keychain Access app and work implicitly with the default keychain, much as you would in iOS. Nevertheless, the keychain services API does provide functions that you can use to manipulate keychains directly. For example, you can create and manage a keychain that is private to your app. On the other hand, robust access control mechanisms typically make this unnecessary for anything other than an app trying to replicate the keychain access utility.

Topics

Creation and Deletion

SecKeychainCreate

Creates an empty keychain.

SecKeychainDelete

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

SecKeychainRef

An opaque type that represents a keychain.

SecKeychainGetTypeID

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

Locking and Unlocking

SecKeychainLock

Locks a keychain.

SecKeychainLockAll

Locks all keychains belonging to the current user.

SecKeychainUnlock

Unlocks a keychain.

Settings

SecKeychainSetSettings

Changes the settings of a keychain.

SecKeychainCopySettings

Obtains a keychain’s settings.

SecKeychainSettings

A structure that contains information about keychain settings.

SEC_KEYCHAIN_SETTINGS_VERS1

Defines the keychain settings version.

Keychain Management

SecKeychainGetVersion

Determines the version of keychain services installed on the user’s system.

SecKeychainOpen

Opens a keychain.

SecKeychainSetDefault

Sets the default keychain.

SecKeychainCopyDefault

Retrieves a pointer to the default keychain.

SecKeychainGetPath

Determines the path of a keychain.

SecKeychainGetStatus

Retrieves status information of a keychain.

SecKeychainStatus

A value that defines the current status of a keychain.

SecKeychainStatus Values

Valid values for the keychain status type.

Search

SecKeychainSetSearchList

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

SecKeychainCopySearchList

Retrieves a keychain search list.

SecKeychainSearchRef

An opaque type that contains information about a keychain search.

SecKeychainSearchGetTypeID

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

Deprecated
SecKeychainSearchCreateFromAttributes

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

Deprecated
SecKeychainSearchCopyNext

Finds the next keychain item matching the given search criteria.

Deprecated

User Interaction

SecKeychainSetUserInteractionAllowed

Enables or disables the user interface for keychain services functions that automatically display a user interface.

SecKeychainGetUserInteractionAllowed

Indicates whether keychain services functions that normally display a user interaction are allowed to do so.

Callbacks

SecKeychainAddCallback

Registers your keychain event callback function.

SecKeychainRemoveCallback

Unregisters your keychain event callback function.

SecKeychainCallback

A customized callback function that keychain services call when a keychain event has occurred.

SecKeychainCallbackInfo

Information about a keychain event that keychain services deliver to your app via a callback function.

SecKeychainEvent

The list of keychain events that can trigger a callback.

SecKeychainEventMask

Bit masks corresponding to the events that can trigger a keychain callback.

Preference Domains

SecKeychainGetPreferenceDomain

Gets the current keychain preference domain.

SecKeychainSetPreferenceDomain

Sets the keychain preference domain.

SecKeychainCopyDomainDefault

Retrieves the default keychain from a specified preference domain.

SecKeychainSetDomainDefault

Sets the default keychain for a specified preference domain.

SecKeychainCopyDomainSearchList

Retrieves the keychain search list for a specified preference domain.

SecKeychainSetDomainSearchList

Sets the keychain search list for a specified preference domain.

SecPreferencesDomain

The keychain preference domains.

Access

SecKeychainSetAccess

Sets the application access for a keychain.

Deprecated
SecKeychainCopyAccess

Retrieves the application access of a keychain.

Deprecated

Legacy Symbols

SecKeychainGetCSPHandle

Returns the CSSM CSP handle for the given keychain object.

Deprecated
SecKeychainGetDLDBHandle

Returns the CSSM database handle for a given keychain object.

Deprecated
SecKeychainItemGetDLDBHandle

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

Deprecated
SecKeychainItemGetUniqueRecordID

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

Deprecated

See Also

API Components

Keychain Items

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

Access Control Lists

Control which apps have access to keychain items in macOS.