APFS filesystem format

By Jonas Plum on Apr 22, 2017

I started to reverse engineer APFS and want to share what I found out so far. You can send me feedback and ideas on this post via Twitter.

Notice: I created a test image with macOS Sierra 10.12.3 (16D32). All results are guesses and the reverse engineering is work in progress. Also newer versions of APFS might change structures. The information below is neither complete nor proven to be correct.

Update 2017-04-30: Added a section for the checksum Update 2017-06-16: Add apfs.ksy respository

Contents #

• Overview
• General information
• Structures
  • Block header
    • Checksum
  • Container Superblock
  • Node
  • Spacemanager
  • Allocation Info File
  • Unknown
  • B-Tree
  • Checkpoint
  • Volume Superblock
  • Allocation File

Overview #

APFS is structured in a single container that can contain multiple APFS volumes. A container needs to be >512 MB to contain more than one volume, >1024MB to contain more than two volumes and so on. The following image shows an overview of the APFs structure.

Each element of this structure (except for the allocation file) starts with a 32 byte block header, which contains some general information about the block. Afterwards the body of the structure is following. The following types exist:

• 0x01: Container Superblock
• 0x02: Node
• 0x05: Spacemanager
• 0x07: Allocation Info File
• 0x11: Unknown
• 0x0B: B-Tree
• 0x0C: Checkpoint
• 0x0D: Volume Superblock

Each of this structures is described in detail below. A more detailed version of the APFS structure is available as a Kaitai struct file: apfs.ksy. You can use it to examine APFS dumps in the Kaitai IDE or create parsers for various languages. This .ksy file must considered experimental.

General information: #

• The filesystem uses litte-endian values for storing information
• Timestamps are 64bit nanoseconds (1 / 1,000,000,000 seconds!) starting from 1.1.1970 UTC (unix epoch). The current timestamp is around 0x14b11800f375e000.
• Standard block size seems to be 4096 byte per block.
• APFS is a copy-on-write filesystem so each block is copied before changes are applied so a history of all unoverwritten files and filesystem structures exists. This might result in a huge amount of forensic artefacts.

Structures #

Block header #

Each filesystem structure in APFS starts with a block header. This header starts with a checksum for the whole block. Other informations in the header include the copy-on-write version of the block, the block id and the block type.

Checksum #

According to the apple docs the Fletcher's checksum algorithm is used. Apple uses a variant of the algorithm described in a paper by John Kodis. The following algorithm shows this procedure. The input is the block without the first 8 byte.

 1func createChecksum(data []byte) uint64 {
 2    var sum1, sum2 uint64
 3
 4    modValue := uint64(2<<31 - 1)
 5
 6    for i := 0; i < len(data)/4; i++ {
 7        d := binary.LittleEndian.Uint32(data[i*4 : (i+1)*4])
 8        sum1 = (sum1 + uint64(d)) % modValue
 9        sum2 = (sum2 + sum1) % modValue
10    }
11
12    check1 := modValue - ((sum1 + sum2) % modValue)
13    check2 := modValue - ((sum1 + check1) % modValue)
14
15    return (check2 << 32) | check1
16}

The nice feature of the algorithm is, that when you check a block in APFS with the following algorithm you should get null as a result. Note that the input in this case is the whole block, including the checksum.

 1func checkChecksum(data []byte) uint64 {
 2    var sum1, sum2 uint64
 3
 4    modValue := uint64(2<<31 - 1)
 5
 6    for i := 0; i < len(data)/4; i++ {
 7        d := binary.LittleEndian.Uint32(data[i*4 : (i+1)*4])
 8        sum1 = (sum1 + uint64(d)) % modValue
 9        sum2 = (sum2 + sum1) % modValue
10    }
11
12    return (sum2 << 32) | sum1
13}

Container Superblock #

The container superblock is the entry point to the filesystem. Because of the structure with containers and flexible volumes, allocation needs to handled on a container level. The container superblock contains information on the blocksize, the number of blocks and pointers to the spacemanager for this task. Additionally the block IDs of all volumes are stored in the superblock. To map block IDs to block offsets a pointer to a block map b-tree is stored. This b-tree contains entries for each volume with its ID and offset.

Node #

Nodes are flexible containers that are used for storing different kinds entries. They can be part of a B-tree or exist on their own. Nodes can either contain flexible or fixed sized entries. A node starts with a list of pointers to the entry keys and entry records. This way for each entry the node contains an entry header at the beginning of the node, an entry key in the middle of the node and an entry record at the end of the node.

Spacemanager #

The spacemanager (sometimes called spaceman) is used to manage allocated blocks in the APFS container. The number of free blocks and a pointer to the allocation info file(s?) are stored here.

Allocation Info File #

The allocation info file works as a missing header for the allocation file. The allocation files length, version and the offset of the allocation file are stored here.

Unknown #

The structure with type 0x11 is quite empty and seems to be related to the spacemanager as it occurs adjacent to it. Its purpose it unknown.

B-Tree #

B-trees manage multiple nodes. They contain the offset of the root node.

Checkpoint #

A checkpoint structure exists for every container superblock. But I have no clue what it is good for.

Volume Superblock #

A volume superblock exists for each volume in the filesystem. It contains the name of the volume, an ID and a timestamp. Similarly to the container superblock it contains a pointer to a block map which maps block IDs to bock offsets. Additionally a pointer to the root directory, which is stored as a node, is stored in the volume superblock.

Allocation File #

Allocation files are simple bitmaps. They do not have a block header and therefore no type id.