Abcrypt Encrypted Data Format

abcrypt is a modern file encryption format with the data authenticity. This document describes the abcrypt encrypted data format.

Table of Contents

Introduction
Conventions used in this document
Format overview
Key derivation
Header format
File body
ABNF definition of the file format
Format changelog

Introduction

abcrypt is a modern file encryption format inspired by the scrypt encrypted data format. abcrypt uses Argon2id for key derivation, BLAKE2b-512-MAC for header integrity checking and XChaCha20-Poly1305 for encryption.

Conventions used in this document

Argon2 is the key derivation function from RFC 9106.

BLAKE2b-512-MAC is the keyed hash function based on BLAKE2 standardized in RFC 7693. This uses BLAKE2b and always outputs a 64-byte MAC.

XChaCha20-Poly1305 is the AEAD algorithm from draft-arciszewski-xchacha-03.

Format overview

An abcrypt file is composed of two parts: a header containing the required data and a file body encrypted with the derived key.

abcrypt files may use the extension .abcrypt.

Table 1. The structure of the abcrypt format
Offset	Bytes	Description	Detail
		Magic number ("abcrypt").	Header format
		Version number.	Version number
		Memory size `m` (`memoryCost`).	Argon2 parameters
		Number of iterations `t` (`timeCost`).	Argon2 parameters
		Degree of parallelism `p` (`parallelism`).	Argon2 parameters
		Salt.	Salt
		Nonce.	Nonce
		MAC of the header.	Header MAC
		Ciphertext.	File body
		MAC of the ciphertext.	File body

All multibyte values are stored in little-endian.

Key derivation

The derived key for computing the header MAC and the derived key for encryption are produced by Argon2. The abcrypt format uses Argon2id as the type and 0x13 (19) as the version.

The derived key is produced as follows

derived_key = Argon2(
    memoryCost = header[8..12],
    timeCost = header[12..16],
    parallelism = header[16..20],
    output_len = 96,
    algorithm = Argon2id,
    version = 0x13,
    pwd = password,
    salt = header[20..52],
)

The resulting derived key (derived_key) length is 96 bytes. The first 32 bytes of derived_key are for encryption (XChaCha20-Poly1305 key), and the last 64 bytes are for computing the header MAC (BLAKE2b-512-MAC key).

memoryCost, timeCost, parallelism, and salt used when encrypting are stored in the header, and these stored values are used when decrypting.

Header format

Magic number

A 7-byte string for identifying the abcrypt format. The value is "abcrypt" (61 62 63 72 79 70 74 in hex).

Version number

A 1-byte version number of the abcrypt format. The current value is 0.

Argon2 parameters

Table 2. Argon2 has the following parameters that control
Parameter	Minimum value	Maximum value	Description
`memoryCost`			Memory size in KiB.
`timeCost`			Number of iterations.
`parallelism`			Degree of parallelism.

Each parameter is represented as 4 bytes in little-endian.

Salt

A 32-byte salt for Argon2.

The salt should be generated from a CSPRNG.

Nonce

A 24-byte nonce for XChaCha20-Poly1305.

The nonce should be generated from a CSPRNG.

Header MAC

The MAC (authentication tag) of the header. The MAC is computed with BLAKE2b-512-MAC over the whole header up to and including the nonce (first 76 bytes of the header).

The MAC is computed as follows

mac = BLAKE2b(
    data = header[..76],
    output_size = 64,
    key = derived_key[32..],
    salt = [],
    person = [],
)

The size of salt and person (personalization string) is zero (empty).

File body

The file body is encrypted with XChaCha20-Poly1305.

The ciphertext is computed as follows

ciphertext = XChaCha20-Poly1305(
    key = derived_key[..32],
    nonce = header[20..52],
    plaintext = plaintext,
    aad = [],
)

The size of aad (additional authenticated data) is zero (empty).

The abcrypt format uses a postfix tag.

ABNF definition of the file format

abcrypt = header payload

; Header

header = signature version-number argon2-parameters salt nonce header-mac

signature      = %s"abcrypt" ; magic number
version-number = OCTET
salt           = 32OCTET     ; 32-byte salt for Argon2
nonce          = 24OCTET     ; 24-byte nonce for XChaCha20-Poly1305
header-mac     = 64OCTET     ; BLAKE2b-512-MAC of the header

; Argon2 parameters

argon2-parameters = memory-cost time-cost parallelism

memory-cost = %x00000008-FFFFFFFF ; memory size in KiB
time-cost   = %x00000001-FFFFFFFF ; number of iterations
parallelism = %x00000001-00FFFFFF ; degree of parallelism

; Payload

payload = ciphertext ciphertext-mac

ciphertext     = *OCTET  ; encrypted with XChaCha20
ciphertext-mac = 16OCTET ; Poly1305 of the ciphertext

Format changelog

Version 0: Initial release.