This is a bare bones library for read-only access to F2fs metadata and files.
F2fs has two 1kb superblocks at offset 1kb and 2kb. These point at the checkpoint segment.
There are two checkpoints. These contain the NAT bitmap which is the primary means by which on-disk consistency is preserved. Checkpoints have a monotonically increasing version number. The most recent valid checkpoint is always used.
The “Node Address Table” (NAT) is a mapping from logical (inode/node id) to physical (block on disk). Again, pairs of segments are used here. The NAT bitmap (stored in the checkpoint) dictates which segment to read a given entry from for a given nid (node id). If the bitmap indicates the first copy, updates will be written to the second copy and the in-memory bitmap will be updated. After that checkpoint has been written out successfully, the other slot will be used. This ping-pong behaviour makes consistency guarantees easier to manage.
To avoid excessive flushing of the NAT to disk, there is a small cache of ‘dirty’ NAT entries stored in RAM. The size of this is bounded based on the number of entries that will fit in a single block (the so-called “summary block”).
F2fs divides devices into two regions -- ‘node’ and ‘data’. Internally F2fs has 3 write heads for each area named hot, warm and cold. Each of these write heads works on a segment at a time and calls them “current” segments. Summary blocks exist as the last block in “current” segments. The NAT summary block exists only in the “hot node” current segment. Because we are not writing to the filesystem, we can avoid but otherwise largely ignore the other “current” segments.
Lastly, a filesystem feature called ‘compact summaries’ allows for the NAT and SIT (Segment Information Table) along with per-segment summary information to be written out in a compact form together in one block, further reducing the cost of checkpointing. It seems this feature is used by our implementation of F2fs so support for this has been added.
These are stored partially inline and partially in a separate ‘nid’ to the inode itself. xattr are 4-byte aligned records consisting of an “index” which is really a label used to identify the type of xattr (security, verity, user, encryption, etc), a name and a value.
The device mapper default-key encryption uses aes256xts where the tweak is the physical partition block number and assumes a 4k block size.
f2fs stores fscrypt encryption contexts in an extended attribute with index 9 and name “c”. Critically, this context contains a hash of the main key required to read the encrypted data and a nonce that must be mixed with the main key to derive a 64-byte per-file key.
When a directory is marked as encrypted, entries in the directory are encrypted with aes256cts using an fscrypt HKDF that creates a key derived from the first 32 bytes of the per-file key.
Filenames shorter than 16 bytes are padded to 16 bytes with nulls before being encrypted. If the filenames are still shorter than 32 bytes (the minimum required for cypher-text-stealing), then aes256cbc is used instead.
These are stored as data. For encrypted symlinks, the encryption scheme used is the same as that used for filename encryption.
Files are encrypted with aes256xts using the per file key. The tweak used for content encryption is the logical block address.
A TEA-based hash is used for direntry hashing most of the time with a SipHash2-4 hash used in the case of casefold + encryption. The latter is seeded using a HKDF derived from the main key and nonce.
A custom, compact f2fs image will be submitted alongside this code as a preliminary validation. Longer term, we should look at something like the code at src/storage/f2fs/test/compatibility/compatibility.h for end-to-end interoperability testing. See this.