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

func SecKeychainDelete(SecKeychain?)

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

class SecKeychain

An opaque type that represents a keychain.

func SecKeychainGetTypeID()

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

Locking and Unlocking

func SecKeychainLockAll()

Locks all keychains belonging to the current user.

Settings

struct SecKeychainSettings

A structure that contains information about keychain settings.

var SEC_KEYCHAIN_SETTINGS_VERS1: Int32

Defines the keychain settings version.

Keychain Management

func SecKeychainGetVersion(UnsafeMutablePointer<UInt32>)

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

func SecKeychainSetDefault(SecKeychain?)

Sets the default keychain.

func SecKeychainCopyDefault(UnsafeMutablePointer<SecKeychain?>)

Retrieves a pointer to the default keychain.

typealias SecKeychainStatus

A value that defines the current status of a keychain.

SecKeychainStatus Values

Valid values for the keychain status type.

Search

func SecKeychainSetSearchList(CFArray)

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

class SecKeychainSearch

An opaque type that contains information about a keychain search.

User Interaction

func SecKeychainSetUserInteractionAllowed(Bool)

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

func SecKeychainGetUserInteractionAllowed(UnsafeMutablePointer<DarwinBoolean>)

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

Callbacks

func SecKeychainRemoveCallback(SecKeychainCallback)

Unregisters your keychain event callback function.

typealias SecKeychainCallback

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

struct SecKeychainCallbackInfo

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

enum SecKeychainEvent

The list of keychain events that can trigger a callback.

struct SecKeychainEventMask

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

Preference Domains

func SecKeychainCopyDomainDefault(SecPreferencesDomain, UnsafeMutablePointer<SecKeychain?>)

Retrieves the default keychain from a specified preference domain.

func SecKeychainSetDomainDefault(SecPreferencesDomain, SecKeychain?)

Sets the default keychain for a specified preference domain.

func SecKeychainCopyDomainSearchList(SecPreferencesDomain, UnsafeMutablePointer<CFArray?>)

Retrieves the keychain search list for a specified preference domain.

func SecKeychainSetDomainSearchList(SecPreferencesDomain, CFArray)

Sets the keychain search list for a specified preference domain.

enum SecPreferencesDomain

The keychain preference domains.

Access

func SecKeychainSetAccess(SecKeychain?, SecAccess)

Sets the application access for a keychain.

Deprecated
func SecKeychainCopyAccess(SecKeychain?, UnsafeMutablePointer<SecAccess?>)

Retrieves the application access of a keychain.

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