Keychain data protection
Many apps need to handle passwords and other short but sensitive bits of data, such as keys and login tokens. The keychain provides a secure way to store these items. The various Apple operating systems use differing mechanisms to enforce the guarantees associated with the different keychain protection classes. On devices with macOS, Data Protection isn’t used directly to enforce these guarantees.
Overview
Keychain items are encrypted using two different AES-256-GCM keys: a table key (metadata) and a per-row key (secret key). Keychain metadata (all attributes other than kSecValue) is encrypted with the metadata key to speed searches, and the secret value (kSecValueData) is encrypted with the secret key. The metadata key is protected by the Secure Enclave but is cached in the Application Processor to allow fast queries of the keychain. The secret key always requires a round trip through the Secure Enclave.
The keychain is implemented as a SQLite database, stored on the file system. There is only one database, and the securityd daemon determines which keychain items each process or app can access. Keychain Access APIs result in calls to the daemon, which queries the app’s “Keychain-access-groups,” “application-identifier,” and “application-group” entitlements. Rather than limiting access to a single process, access groups allow keychain items to be shared between apps.
Keychain items can be shared only between apps from the same developer. To share keychain items, third-party apps use access groups with a prefix allocated to them through the Apple Developer Program in their application groups. The prefix requirement and application group uniqueness are enforced through code signing, provisioning profiles, and the Apple Developer Program.
Keychain data is protected using a class structure similar to the one used in file Data Protection. These classes have behaviors equivalent to file Data Protection classes but use distinct keys and functions.
Availability | File data protection | Keychain data protection | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
When unlocked | NSFileProtectionComplete | kSecAttrAccessibleWhenUnlocked | |||||||||
While locked | NSFileProtectionComplete UnlessOpen |
| |||||||||
After first unlock | NSFileProtectionComplete UntilFirstUserAuthentication | kSecAttrAccessibleAfterFirstUnlock | |||||||||
Always | NSFileProtectionNone | kSecAttrAccessibleAlways | |||||||||
Passcode enabled |
| kSecAttrAccessibleWhen PasscodeSetThisDeviceOnly | |||||||||
Apps that use background refresh services can use kSecAttrAccessibleAfterFirstUnlock for keychain items that need to be accessed during background updates.
The class kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly behaves the same as kSecAttrAccessibleWhenUnlocked; however, it’s available only when the device is configured with a passcode. This class exists only in the system keybag; they:
Don’t sync to iCloud Keychain
Aren’t backed up
Aren’t included in escrow keybags
If the passcode is removed or reset, the items are rendered useless by discarding the class keys.
Other keychain classes have a “This device only” counterpart, which is always protected with the UID when being copied from the device during a backup, rendering it useless if it’s restored to a different device. Apple has carefully balanced security and usability by choosing keychain classes that vary according to the type of information being secured and when it’s needed by iOS, iPadOS, and visionOS.
Keychain data class protections
The class protections listed below are enforced for keychain items.
Item | Accessible |
|---|---|
Wi-Fi passwords | After first unlock |
Mail accounts | After first unlock |
Microsoft Exchange ActiveSync accounts | After first unlock |
VPN passwords | After first unlock |
LDAP, CalDAV, CardDAV | After first unlock |
Social network account tokens | After first unlock |
Handoff advertisement encryption keys | After first unlock |
iCloud token | After first unlock |
iMessage keys | After first unlock |
Home sharing password | When unlocked |
Safari passwords | When unlocked |
Safari bookmarks | When unlocked |
Finder/iTunes backup | When unlocked, nonmigratory |
VPN certificates | After first unlock, nonmigratory |
Bluetooth® keys | Always, nonmigratory |
Apple Push Notification service (APNs) token | Always, nonmigratory |
iCloud certificates and private key | Always, nonmigratory |
SIM PIN | Always, nonmigratory |
Find My token | Always |
Voicemail | Always |
On macOS, all keychain items installed by configuration profiles are always available. On iOS, iPadOS, and visionOS, keychain items installed by a configuration profile have different accessibility depending on their type, how they’re referenced, and when they were installed. By default, keychain items installed using configuration profiles are available after first unlock and nonmigratory. However, a keychain item installed by a configuration profile is always available if it:
Was installed before upgrading to iOS 15, iPadOS 15, or later
Is a certificate (not an identity)
Is an identity referenced by the
IdentityCertificateUUIDin acom.apple.mdmpayload
Keychain access control
Keychains can use access control lists (ACLs) to set policies for accessibility and authentication requirements. Items can establish conditions that require user presence by specifying that they can’t be accessed unless authenticated using Optic ID, Face ID, Touch ID, or by entering the device’s passcode or password. Access to items can also be limited by specifying that Optic ID, Face ID, or Touch ID enrollment hasn’t changed since the item was added. This limitation helps prevent an attacker from adding their own fingerprint to access a keychain item. ACLs are evaluated inside the Secure Enclave and are released to the kernel only if their specified constraints are met.
Keychain architecture in macOS
macOS also provides access to the keychain to conveniently and securely stores user names and passwords, digital identities, encryption keys, and secure notes. It can be accessed by opening the Keychain Access app in /Applications/Utilities/. Using a keychain eliminates the requirement to enter—or even remember—the credentials for each resource. An initial default keychain is created for each Mac user, though users can create other keychains for specific purposes.
In addition to relying on user keychains, macOS relies on a number of system-level keychains that maintain authentication assets that aren’t user specific, such as network credentials and public key infrastructure (PKI) identities. One of these keychains, System Roots, is immutable and stores internet PKI root certificate authority (CA) certificates to facilitate common tasks like online banking and e-commerce. The user can similarly deploy internally provisioned CA certificates to managed Mac computers to help validate internal sites and services.