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

SecAccessCreate

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

SecAccessCreateWithOwnerAndACL

Creates a new access instance using the owner and ACL entries you provide.

SecAccessOwnerType

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

SecAccessOwnerType Values

Flags that enable you to configure ACL ownership.

SecAccessRef

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

SecAccessGetTypeID

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

Access Query

SecAccessCopyACLList

Retrieves all the ACL entries of a given access instance.

SecAccessCopyMatchingACLList

Retrieves selected ACL entries from a given access instance.

SecAccessCopyOwnerAndACL

Retrieves the owner and the ACL entries of a given access instance.

Access Control List Entries

SecACLCreateWithSimpleContents

Creates a new ACL entry with the given characteristics, and adds it to an access instance.

SecACLRemove

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

ACL Authorization Keys

The operations an access control list entry applies to.

SecKeychainPromptSelector

Bits that define when a keychain should require a passphrase.

SecACLRef

An opaque type that represents information about an ACL entry.

SecACLGetTypeID

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

Access Control List Configuration

SecACLCopyContents

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

SecACLSetContents

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

SecACLCopyAuthorizations

Retrieves the authorization tags of a given ACL entry.

SecACLUpdateAuthorizations

Sets the authorization tags for a given ACL.

Trusted Applications

SecTrustedApplicationCreateFromPath

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

Deprecated
SecTrustedApplicationCopyData

Retrieves the data of a trusted app instance.

Deprecated
SecTrustedApplicationSetData

Sets the data of a given trusted app instance.

Deprecated
SecTrustedApplicationRef

An opaque type that contains information about a trusted app.

SecTrustedApplicationGetTypeID

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

Keychain Item Access

SecKeychainItemSetAccess

Sets the access of a given keychain item.

SecKeychainItemCopyAccess

Retrieves the access of a given keychain item.

Legacy Access Control Operations

SecACLCreateFromSimpleContents

Creates a new access control list entry from the application list, description, and prompt selector provided and adds it to an item’s access object.

Deprecated
SecACLCopySimpleContents

Returns the application list, description, and CSSM prompt selector for a given access control list entry.

Deprecated
SecACLSetSimpleContents

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

Deprecated
SecACLGetAuthorizations

Retrieves the CSSM authorization tags of a given access control list entry.

Deprecated
SecACLSetAuthorizations

Sets the CSSM authorization tags for a given access control list entry.

Deprecated
SecAccessCopySelectedACLList

Retrieves selected access control lists from a given access object.

Deprecated
SecAccessCreateFromOwnerAndACL

Creates a new access object using the owner and access control list you provide.

Deprecated
SecAccessGetOwnerAndACL

Retrieves the owner and the access control list of a given access object.

Deprecated

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.