Algebraicdir Format Specification

Overview

The algebraicdir format specification describes the format for the extended attribute named org.littleroot.algebraic.dirname.

Algebraic offers the ability to encrypt directory names: during encryption Algebraic encrypts the directory name and places it in an extended attribute; during decryption Algebraic recovers the directory name from an extended attribute. Algebraic uses the org.littleroot.algebraic.dirname extended attribute for this purpose.

The current version of the format is version 3.

The attribute value is composed of 4 sections:

Structure

1. Identifier section

The identifier section is binary-encoded in big-endian order. It is made of one field:

version  1 byte

The version field is the algebraicdir format version as an integer; for example, for version 3 of the format the value is 0x03. Programs that read an algebraicdir should read the identifier section, and based on the version number adjust their parsing behavior for the remaining sections.

2. Header section

The primary header section is binary-encoded in big-endian order. It consists of:

salt     16 byte
time     4 byte
mem      4 byte
threads  1 byte
nonce    24 byte

The salt, time, mem, and threads fields are parameters for Argon2id key derivation. The mem value must be in unit kibibyte (KiB). The nonce field is the nonce to use with XChaCha20-Poly1305.

3. Data section

The data section is made all bytes after the header section but before the checksum section. The section consists of a JSON-encoded object, encrypted with XChaCha20-Poly1305. The section byte size includes the Poly1305 authentication tag (in other words, the AEAD overhead). The nonce for the encryption is the nonce value in the header section. The encryption key is derived by hashing a user-supplied password with Argon2id; the parameters for Argon2id must match the values in the primary header section.

The structure of the JSON-encoded object is:

{
    d: string // directory name, final path element only, base64-encoded.
}

The d property must exist in the encoded JSON and be non-empty.

4. Checksum section

The 32-byte checksum is the SHA-256 sum of all the bytes in the preceding sections. Readers may forgo checksum verification.