How APFS mounts encrypted volumes, snapshots, cryptexes and more

In the previous article I stepped through how APFS in Ventura 13.2.1 mounts a simple unencrypted volume on an external disk. To follow on from that, this article looks at two more types of mounting, of an encrypted volume and a snapshot, at how volumes are unmounted, and concludes with how APFS grafts a Cryptex into the system.

Encrypted volume

This example looks at a single APFS (Encrypted) volume being mounted from an external Thunderbolt 3 SSD, well after startup and login have completed.

APFSencryptedMount1

Rather than trace this from the start, this diagram begins with the mounting of the container, here disk8. This proceeds in the normal way until the disk metazone and allocation zone have been initialised. At that stage, APFS knows it has to mount an encrypted volume disk8s2 within that container, and requires Effaceable Storage to handle that.

There is ambiguity in the log entries here: the entry is titled effaceable_is_disabled, and proclaims no-effaceable-storage is ON, which could mean that there is no effaceable storage enabled. However, I suspect that this type of storage is required to handle the volume key. Effaceable Storage is a dedicated area of NAND storage that can be addressed directly and erased securely, and is typically used to store such crypto keys.

APFS (Encrypted) volumes are used where hardware encryption isn’t available. Each encrypted volume has its own volume encryption key or VEK, used to encrypt and decrypt the volume. The VEK is in turn protected by wrapping with the key encryption key or KEK, which can be unwrapped by the password.

The container’s keybag contains each encrypted volume’s wrapped VEK and the location of that volume’s keybag. Each encrypted volume’s keybag contains copies of the volume’s KEK that have been wrapped with the password or a recovery key. A fuller account is given in the APFS reference, although that only describes software encryption. Apple doesn’t provide any equivalent information covering the hardware encryption used by the Data volume on internal storage.

Once the status of Effaceable Storage has been confirmed, APFS tries to unwrap the VEK, but as no password has been provided to unwrap the KEK with which to unwrap the VEK, it can’t. It therefore proceeds to mount the unencrypted volume disk8s1 in the normal way, and will continue to scan for free blocks and trim when appropriate.

Once the correct password has been entered, disk8s2 is mounted with the normal sequence of log entries.

Snapshot

Mounting a snapshot is normally quick and simple. This example is taken from a snapshot on a Time Machine backup store, again on an external disk.

APFSsnapshotMount1

The only unusual log entries here are adjustments to the COW exempt count, which follow successful mounting. These are files which don’t use standard copy-on-write (COW), and are peculiar to Time Machine backups. Their numbers appear small, and multiple entries of that log message can occur after a snapshot has been mounted successfully.

Unmount

Performing a clean unmount of an APFS volume is also straightforward, although sometimes the order of events differs slightly.

APFSdiskUnmount1

This procedure starts with the declaration that only buffered and not raw disk access is allowed, and the cessation of all background work. APFS next checks that the volume isn’t the current boot System or Data volume, which can’t be unmounted until shutdown. It then waits for the ‘purgatory cleaner’ to finish, to ensure that all disk operations are complete, and the number of volumes in that container is stated.

If the container is to be unmounted, and the number of remaining mounted volumes in that container has reached 0, the container will be unloaded. APFS reports the total memory allocated, then reports completion with the total number of APFS volumes that are still mounted. It finally announces that it’s going home, and Disk Arbitration reports the unmounting was successful before making callbacks to register the change in FSEvents, and to many other processes.

Cryptex grafting

Cryptexes are a recent addition to macOS, and are summarised here. Currently, macOS 13.3 has three standard Cryptexes, app.dmg, os.dmg, and os.clone.dmg, to which will be added any installed as Rapid Security Responses (RSRs). Each of these standard Cryptexes is added into place in the system in a process termed grafting.

APFSCryptexMount1

This starts with validation of the payload and its manifest. It then undergoes a sequence of processes similar to the mounting of an APFS volume, with a checkpoint search to establish stable checkpoint indices, and a check to discover whether there’s anything to recover, which seems improbable.

The graft is then performed in a series of opaque steps, with root hash authentication and validation. The OBJID (object ID?) is found, and the graft completed.

Once this has been completed for each of the three standard Cryptexes and any installed RSRs, the contents of those Cryptexes are effectively part of the system, as a hybrid of the SSV and Cryptexes.

As with the current boot System and Data volumes, grafted Cryptexes aren’t unmounted or ungrafted until shutdown.

Next

The remaining routines performed by APFS that I have yet to cover are those involving the mounting of Boot Volume Groups, whether being used for that Mac to boot from, or inactive, such as on an external disk. Those involve many of the same basic procedures, with the notable addition of stitching firmlinks into place between the System and Data volumes, and the automatic unmounting of volumes such as Preboot.