Skip to content

apfsck: "Keybag entry: is too big" on containers with an encrypted volume #25

Open

Description

@logicalangel

Hi,

apfsck stops with Keybag entry: is too big. on every container where macOS 27.0.1 has created an encrypted volume. It's the same message ozzycattt ran into in linux-apfs/linux-apfs-rw#130. To reproduce:

# macOS
mkfile -n 1g enc.img
diskutil image attach --noMount enc.img       # comes up as diskN
diskutil eraseDisk APFS Plain GPT diskN       # the container is diskM
diskutil apfs addVolume diskM APFS Enc -passprompt
diskutil eject diskN

# Linux, apfsck from master (1bd1c1c)
losetup -P -f --show enc.img                  # /dev/loop0
apfsck -cw /dev/loop0p1
Keybag entry: is too big.

fsck_apfs accepts the image.

I decrypted the container keybag (AES-XTS with the container uuid, like check_keybag_ciphertext_block() does) and walked it by hand. It holds two entries for the encrypted volume:

locker: version 2, 2 keys, kl_nbytes 224
+0    tag 3 (unlock records)  keylen 16    24 + 16  = 40, padded to 48
+48   tag 2 (volume key)      keylen 124   24 + 124 = 148, padded to 160
+208  zeros

That differs from what apfsck expects in three places:

  1. Entries are padded to a multiple of 16 bytes, and apfs-fuse rounds them up the same way. apfsck reads them back to back, so it reads the second header 8 bytes early and gets a keylen of 59992. The padding isn't zeroed (after the volume key it held leftovers of another key blob), so it can't be checked.
  2. The volume key entry is not the bare 0x28-byte wrapped key that check_volume_key_entry() wants. It's a DER blob, which apfs-fuse also parses:
    30 7a                   sequence
      80 01 00              version
      81 20 <32 bytes>      HMAC
      82 08 <8 bytes>       salt
      a3 49                 sequence
        80 01 00            version
        81 10 <16 bytes>    volume uuid, same as the entry's
        82 08 <8 bytes>     flags
        83 28 <40 bytes>    wrapped key
    
  3. kl_nbytes includes the 16-byte locker header: 224 = 16 + 48 + 160. That would also explain the leftover of 0x18 bytes mentioned in check_keybag_locker(): with the volume key entry first and a 40-byte unlock records entry last, what's left is the header plus 8 bytes of padding.

Keybags that macOS wrote for two encrypted volumes, a volume with a passphrase hint, a changed passphrase, and a volume encrypted after it was created all have the same layout (two volumes give four entries and kl_nbytes 432).

Once the keybag passes, apfsck goes on to the encrypted volume and stops at a bad checksum on one of its catalog nodes. I think that's expected: the container uses software encryption (NX_CRYPTO_SW), so those nodes are encrypted with the volume key.

I have a fix on my fork that pads the entries, checks the layout of the blob (including the size of the wrapped key and the volume uuid), still accepts a bare 0x28-byte key, and counts the header in kl_nbytes: logicalangel@79fcc1e. It was written with an LLM, and I know from linux-apfs/linux-apfs-rw#132 that you'd rather write fixes yourself, so feel free to ignore it. I'm happy to test whatever you come up with on more macOS images.

Activity

  1. eafer commented on Nov 18, 2026

    @eafer
    Member

    Thanks for the report. I expect a lot of issues with encryption, but I think I may get to work on it soon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions