Keybags for Data Protection
The keys for both file and keychain Data Protection classes are collected and managed in keybags on iOS, iPadOS, tvOS, and watchOS. These operating systems use the following keybags: user, device, backup, escrow, and iCloud Backup.
User keybag
The user keybag is where the wrapped class keys used in normal operation of the device are stored. For example, when a passcode is entered, NSFileProtectionComplete is loaded from the user keybag and unwrapped. It is a binary property list (.plist) file stored in the No Protection class.
For devices with SoCs earlier than the A9, the .plist file contents are encrypted with a key held in Effaceable Storage. To give forward security to keybags, this key is wiped and regenerated each time a user changes their passcode.
For devices with the A9 or later SoCs, the .plist file contains a key which indicates that the keybag is stored in a locker protected by the Secure Enclave–controlled anti-replay value.
The Secure Enclave manages the user keybag and can be queried regarding a device’s lock state. It reports that the device is unlocked only if all the class keys in the user keybag are accessible and have been unwrapped successfully.
Device keybag
The device keybag is used to store the wrapped class keys used for operations involving device-specific data. iPadOS devices configured for shared use sometimes need access to credentials before any user has logged in; therefore, a keybag that isn’t protected by the user’s passcode is required.
iOS and iPadOS don’t support cryptographic separation of per-user file system content, which means the system uses class keys from the device keybag to wrap per-file keys. The keychain, however, uses class keys from the user keybag to protect items in the user keychain. In iPhone and iPad devices configured for use by a single user (the default configuration), the device keybag and the user keybag are one and the same, and are protected by the user’s passcode.
Backup keybag
The backup keybag is created when an encrypted backup is made by the Finder (macOS 10.15 or later) or iTunes (in macOS 10.14 or earlier) and stored on the computer to which the device is backed up. A new keybag is created with a new set of keys, and the backed-up data is reencrypted to these new keys. As explained previously, nonmigratory keychain items remain wrapped with the UID-derived key, allowing them to be restored to the device they were originally backed up from but rendering them inaccessible on a different device.
The keybag—protected with the password set—is run through 10 million iterations of the key derivation function PBKDF2. Despite this large iteration count, there’s no tie to a specific device, and therefore a brute-force attack parallelized across many computers could theoretically be attempted on the backup keybag. This threat can be mitigated with a sufficiently strong password.
If a user chooses not to encrypt the backup, the files aren’t encrypted regardless of their Data Protection class but the keychain remains protected with a UID-derived key. This is why keychain items migrate to a new device only if a backup password is set.
Escrow keybag
The escrow keybag is used for syncing with the Finder (macOS 10.15 or later) or iTunes (in macOS 10.14 or earlier) through USB and mobile device management (MDM). This keybag allows the Finder or iTunes to back up and sync without requiring the user to enter a passcode, and it allows an MDM solution to remotely clear a user’s passcode. It is stored on the computer that’s used to sync with the Finder or iTunes, or on the MDM solution that remotely manages the device.
The escrow keybag improves the user experience during device syncing, which potentially requires access to all classes of data. When a passcode-locked device is first connected to the Finder or iTunes, the user is prompted to enter a passcode. The device then creates an escrow keybag containing the same class keys used on the device, protected by a newly generated key. The escrow keybag and the key protecting it are split between the device and the host or server, with the data stored on the device in the Protected Until First User Authentication class. This is why the device passcode must be entered before the user backs up with the Finder or iTunes for the first time after a reboot.
In the case of an over-the-air (OTA) software update, the user is prompted for their passcode when initiating the update. This is used to securely create a one-time unlock token, which unlocks the user keybag after the update. This token can’t be generated without entering the user’s passcode, and any previously generated token is invalidated if the user’s passcode changed.
One-time unlock tokens are either for attended or unattended installation of a software update. They’re encrypted with a key derived from the current value of a monotonic counter in the Secure Enclave, the UUID of the keybag, and the Secure Enclave UID.
On A9 (or later) SoCs, one-time Unlock token no longer relies on counters or Effaceable Storage. Instead, it’s protected by Secure Enclave–controlled anti-replay value.
The one-time unlock token for attended software updates expires after 20 minutes. In iOS 13 and iPadOS 13.1, or later, the token is stored in a locker protected by the Secure Enclave. Prior to iOS 13, this token was exported from the Secure Enclave and written to Effaceable Storage or was protected by the Secure Enclave anti-replay mechanism. A policy timer incremented the counter if the device hadn’t rebooted within 20 minutes.
Unattended software updates occur when the system detects an update is available and when one of the following is true:
Automatic updates are configured in iOS 12 or later.
The user chooses Install Later when notified of the update.
After the user enters their passcode, a one-time unlock token is generated and can remain valid in Secure Enclave for up to 8 hours. If the update hasn’t yet occurred, this one-time unlock token is destroyed on every lock and re-created on every subsequent unlock. Each unlock restarts the 8 hour window. After 8 hours a policy timer invalidates the one-time unlock token.
iCloud Backup keybag
The iCloud Backup keybag is similar to the backup keybag. All the class keys in this keybag are asymmetric (using Curve25519, like the Protected Unless Open Data Protection class) does. An asymmetric keybag is also used to protect the backed-up keychain for iCloud Keychain recovery.