Support for encryption has been designed into APFS from the outset, and is one of its major changes over HFS+, where it had to be retro-fitted. Early announcements promised a range of encryption options, including whole-volume and multi-key encryption with different files/folders protected by different keys, even a separate key for metadata. Although the latter don’t appear to be supported at present, whole-volume multi-key encryption is widely used and documented by Apple.

What Apple didn’t announce as a feature in APFS was support for checking the integrity of file data. Although that hasn’t been offered in any more general form, macOS 11 introduced sealing of the System volume using cryptographic hashes to produce the SSV, the Signed System Volume. This article opens with a description of whole-volume software encryption, and concludes with a brief explanation of sealing.

Key wrapping

Encryption keys must be well protected at all times, and an established technique for doing that is to encrypt and encapsulate them using a process known as wrapping. APFS uses the AES Key Wrap Specification in RFC 3394, which uses a secret such as a password to maintain confidentiality of every key.

APFS also uses separate volume and key encryption keys (VEK and KEK), so enabling the use of multiple KEKs for a single VEK, and the potential to change a KEK without having to decrypt and re-encrypt the whole volume, as used in hardware encryption implemented for FileVault. In APFS, VEKs and KEKs are stored in and accessed from Keybags associated with both containers and volumes.

The Container Keybag contains wrapped VEKs for each encrypted volume within that container, together with the location of each encrypted volume’s keybag. The Volume Keybag contains one or more wrapped KEKs for that volume, and an optional passphrase hint. These are shown in the diagram below.

Apple’s reference documentation refers to several secrets that can be used to wrap a KEK, including a user password, an individual recovery key, an institutional recovery key, and an unspecified mechanism implemented through iCloud. Currently, for normal software encryption in APFS, only two of those appear accessible: a user password is supported in both Disk Utility and diskutil‘s apfs verb, while diskutil also supports use of an institutional recovery key through its -recoverykeychain options. Individual and iCloud recovery keys only appear available when using FileVault, in this case implemented in software, either on Intel Macs without a T2 chip, or on all Macs when encrypting an external volume.

Unwrapping

Before the VEK for any volume can be used, it must be unwrapped. To access the VEK for a given volume:

• Find the location of the Container Keybag from the container’s superblock.
• Unwrap the Container Keybag using the container UUID.
• Locate the wrapped VEK for the volume, listed by volume UUID.
• Find the location of that Volume’s Keybag using the volume UUID.
• Unwrap the Volume Keybag using the volume UUID.
• Locate the appropriate wrapped KEK according to the password or key provided, e.g. the KEK wrapped by the user password.
• Unwrap the KEK using the password/key.
• Unwrap the VEK for that volume in the Container Keybag using that KEK.

Encryption/decryption

Once the VEK for an encrypted volume has been unwrapped, it can then be used as an AES-XTS key to decrypt that volume’s root file system. A file’s extent record can be obtained from that, and the encryption state record for that ID can be found with the extent. The VEK is then used again as an AES-XTS key to decrypt the data blocks of the file.

Apple’s APFS reference also features a section on encryption rolling, but without a single word of description its usefulness is severely limited.

Sealing

Introduced with the Signed System Volume in macOS 11, sealing is an ingenious method of verifying the contents and structure of the System volume using a tree of cryptographic hashes. Its great strength is that verification is performed when reading from the volume, so proceeds piecemeal rather than requiring time-consuming verification across the whole volume at once. A range of hash algorithms is available, from the default SHA-256 up to SHA-512, but currently it appears that only the default is used in practice.

Hashes are stored first in the leaves of the volume’s root file system B+tree, then the hash of each complete child node is stored in the parent non-leaf nodes in the tree, alongside the OID of that child node. This is repeated all the way up the nodes to the root, where the hash is the volume’s seal. Flags are set on all nodes to indicate the B+tree is hashed. When the seal on a sealed volume is broken by modifying any of its nodes, the XID of that transaction is recorded in the integrity metadata for that volume, and a flag is set to indicate the seal has been broken.

The volume seal (of the root node in the tree) is hashed again to provide that volume’s signature, which is compared against the signature signed by Apple. Only when they match does the bootloader of an Apple silicon Mac transfer control to the kernel, for the start of the kernel phase of booting that Mac. On an Intel Mac with a T2 chip, the kernel performs the verification before mounting the root file system.

From then on, reading from the SSV is accompanied by recomputation of the hash of the data, which is compared against the hash stored in the root file system tree to validate the data as read. This not only guards against tampering with the contents of the SSV, but also detects read errors.

Summary

• APFS has integrated whole-volume multi-key software encryption.
• Each encrypted volume has a Volume Encryption Key (VEK) stored in the container Keybag, and wrapped with a Key Encryption Key (KEK).
• KEKs are stored in the volume Keybag, where they’re wrapped by a password, or by a secret key, perhaps used for recovery.
• Unwrapping a VEK for use requires unwrapping its KEK first.
• When unwrapped, the VEK is used as an AES-XTS key to decrypt that volume’s root file system, and the data blocks of each file.
• From macOS 11, the entire contents of the System volume are verified against a tree of SHA-256 hashes stored in the volume’s root file system tree.
• Verification is performed when reading from the SSV, so avoiding lengthy verification of the whole volume at once.
• Verification of the volume seal (of the root node hash) is required before or at the start of the kernel phase of booting.

Articles in this series

1. Files and clones
2. Directories and names
3. Containers and volumes
4. Snapshots

References

Apple’s APFS Reference (PDF), last revised 22 June 2020.
Apple Platform Security Guide.