Access Control Lists

Control which apps have access to keychain items in macOS.

Overview

In macOS, for items not stored on the iCloud keychain, each protected keychain item—like a password or private key—has an associated access instance that contains an access control list (ACL). The entries in this list in turn each contain an array of operations and an array of apps trusted to carry out those operations with the item. The collection of ACL entries govern the accessibility of the corresponding keychain item.

Diagram showing the detailed contents of access attribute of a kechain item, namely an access control list composed of entries for different operations and trusted apps.

When an app attempts to access a keychain item for a particular purpose—like using a private key to sign a document—the system looks for an entry in the item’s ACL containing the operation. If there’s no entry that lists the operation, then the system denies access and it’s up to the calling app to try something else or to notify the user.

If there is an entry that lists the operation, the system checks whether the calling app is among the entry’s trusted apps. If so, the system grants access. Otherwise, the system prompts the user for confirmation. The user may choose to Deny, Allow, or Always Allow the access. In the latter case, the system adds the app to the list of trusted apps for that entry, enabling the app to gain access in the future without prompting the user again.

Topics

Access Creation

func SecAccessCreate(CFString, CFArray?, UnsafeMutablePointer<SecAccess?>) -> OSStatus

Creates a new access instance associated with a given protected keychain item.

typealias SecAccessOwnerType

A type for flags that enable you to configure ACL ownership.

SecAccessOwnerType Values

Flags that enable you to configure ACL ownership.

class SecAccess

An opaque type that identifies a keychain item’s access information.

func SecAccessGetTypeID() -> CFTypeID

Returns the unique identifier of the opaque type to which an access instance belongs.

Access Control List Entries

func SecACLRemove(SecACL) -> OSStatus

Removes the specified ACL entry from the access instance that contains it.

ACL Authorization Keys

The operations an access control list entry applies to.

struct SecKeychainPromptSelector

Bits that define when a keychain should require a passphrase.

class SecACL

An opaque type that represents information about an ACL entry.

func SecACLGetTypeID() -> CFTypeID

Returns the unique identifier of the opaque type to which an ACL entry belongs.

Access Control List Configuration

func SecACLSetContents(SecACL, CFArray?, CFString, SecKeychainPromptSelector) -> OSStatus

Sets the application list, description, and prompt selector for a given ACL entry.

func SecACLCopyAuthorizations(SecACL) -> CFArray

Retrieves the authorization tags of a given ACL entry.

func SecACLUpdateAuthorizations(SecACL, CFArray) -> OSStatus

Sets the authorization tags for a given ACL.

Trusted Applications

func SecTrustedApplicationCreateFromPath(UnsafePointer<Int8>?, UnsafeMutablePointer<SecTrustedApplication?>) -> OSStatus

Creates a trusted app instance based on the app at the given path in the file system.

class SecTrustedApplication

An opaque type that contains information about a trusted app.

func SecTrustedApplicationGetTypeID() -> CFTypeID

Returns the unique identifier of the opaque type to which a trusted app instance belongs.

See Also

API Components

Keychain Items

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

Keychains

Create and manage entire keychains in macOS.