What is APFS “Disk User” and how to add multiple crypto users via diskutil?

I recently learned that it is possible to encrypt an APFS volume within a container from the CLI using the diskutil command like so:

diskutil apfs encrypt -user disk disk3s1


where disk3s1 is the only volume in the APFS container on my external drive.

The disk user is mentioned in the diskutil man page, but I do not understand what it is. Additionally, if I understand correctly, encrypting the MacOS startup disk using the typical "System Preferences" -> "Security and Privacy" -> "FileVault" tab -> "Turn on FileVault" button achieves essentially the same thing. From what I can see, the difference between the two approaches has to do with the users that can decrypt the disk. Using the "System Preferences" approach, my user (BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB below) has permission to decrypt the disk as does the recovery key (user CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC below) that was generated when I hit the "Turn on FileVault" button. The differences can be seen using diskutil once again:

# Volume on the external drive:
diskutil apfs listkeys disk3s1
# Cryptographic user for disk3s1 (1 found)
# |
# +-- AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA
#     Type: Disk User

# Data volume on my MacBook's internal drive:
diskutil apfs listkeys disk1s2
# Cryptographic users for disk1s2 (2 found)
# |
# +-- BBBBBBBB-BBBB-BBBB-BBBB-BBBBBBBBBBBB
# |   Type: Local Open Directory User
# |
# +-- CCCCCCCC-CCCC-CCCC-CCCC-CCCCCCCCCCCC
#     Type: Personal Recovery User


I did some internet searching but I could not find satisfactory answers to the following questions; any help is appreciated. Thanks in advance.

1. What is the "disk" user? Is it special? Is it universal among all MacOS installs?
2. Can I add additional crypto users to disk3s1 via diskutil or some other CLI command?
3. Can I add a personal recovery user/recovery key after the fact (e.g. to disk3s1 as shown above) via diskutil or another CLI command?
4. Can I remove crypto users after the fact?

References

Here are some articles I read before I created this post, listed in no particular order, some more relevant than others.

Short version:

1. The disk "user" is the equivalent of having only a single password for decrypting the disk.

2. You can add additional users for the boot volume using the fdesetup add command. (see fdesetup help for details)

3. You can add or change the recovery key after the fact using fdesetup changerecovery

4. You can remove users later using fdesetup remove and you can also remove the recovery key with fdesetup removerecovery

I don't yet know how to add or remove users/keys to encrypted apfs disks that are not the boot volume.

Long Version:

The convention of having multiple cryptographic users on a disk was done primarily to facilitate FileVault boot disks. Because of this convention, the concept of a disk "user" was created to allow disks to be encrypted with a single encryption key for non-boot disks.

The disk "user" is what would be created if you encrypted a disk using a method other than the "Turn on FileVault" method you described above. This is the equivalent of having a disk encrypted by a single password, instead of having multiple users able to decrypt the disk with their own passwords.

Having multiple users able to decrypt a disk is important for a startup disk with FileVault as it allows them to enter their own username and password at boot to decrypt the disk and login. Without it, they would have to know the disk encryption password (the disk "user") and enter that at boot, then login with their own user credentials at the login screen once boot is complete.

This is why FileVault automatically adds additional encryption keys for users to your boot drive when you enable it (in this case, one for your user and one for the FileVault master recovery key in case a user forgets their password and needs to reset it). But if you are encrypting a non-startup disk, having access for multiple users may not be useful or even desirable. This is why encrypting the disk from the CLI only creates the disk "user". (I believe this is also the case when encrypting using the Disk Utility app or from the Finder).

You can, of course, encrypt a boot disk with only a single disk "user" and no other cryptographic users or recovery keys. You will be presented with a password prompt at boot and it will display a disk icon instead of a user icon, and you will have to enter the disk encryption password instead of your user password. Any users on the machine who do not know this password will be unable to decrypt the disk and login to the machine.

Edit: Just want to add the following: Note that the disk "user" will only be added to the list of cryptographic users when you first encrypt the disk using the cli (diskutil apfs) or via Finder or Disk Utility. The disk user will not be added if you enable FileVault in the System Preferences, and it cannot later be added to a disk that already has cryptographic users.

Also of note, the disk user will always have the UUID of the disk itself.

• Thanks for the comprehensive response. Do you know the versions of APFS/MacOS for which your response is true? I'm not trying to nitpick, I just wanted to know before I mark this answer as "accepted." Also Also of note, the disk user will always have the UUID of the disk itself. is a great detail. Thanks again! – joshua.r.smith Dec 20 '20 at 17:59
• Good question, not a nitpick at all. I don't know which versions of APFS this is valid for (or if it is indeed still valid for the most recent APFS/macOS version). Unfortunately, the most recent man pages for fdesetup and diskutil I can find are from 2018. If you're on the latest version of macOS, can you run man fdesetup and man diskutil and see what their published date is? (it'll be at the very end of the output). if it is newer than "17 January 2018", then we'll have to check if anything material has changed that would invalidate my answer before accepting it. – bowmasters Dec 21 '20 at 18:48
• Correction, the newest I could find is from 08 July 2018 – bowmasters Dec 21 '20 at 19:05
• fdesetup -> July 02, 2019, diskutil -> 1 July 2019. I'm on Catalina version 10.15.7 (19H114). FWIW, the date formats on these two man pages are different; I simply copy/pasted. ¯_(ツ)_/¯ – joshua.r.smith Dec 21 '20 at 20:19