FORMAT.adoc

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
  • Magic number
  • Version number
  • Argon2 parameters
  • Salt
  • Nonce
  • Header MAC
• 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 encrypted data format

Offset	Bytes	Description	Detail
\$0\$	\$7\$	Magic number ("abcrypt").	Header format
\$7\$	\$1\$	Version number.	Version number
\$8\$	\$4\$	Memory size m (memoryCost).	Argon2 parameters
\$12\$	\$4\$	Number of iterations t (timeCost).	Argon2 parameters
\$16\$	\$4\$	Degree of parallelism p (parallelism).	Argon2 parameters
\$20\$	\$32\$	Salt.	Salt
\$52\$	\$24\$	Nonce.	Nonce
\$76\$	\$64\$	MAC of the header.	Header MAC
\$140\$	\$n\$	Ciphertext.	File body
\$140 + n\$	\$16\$	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 encrypted data 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 encrypted data format. The value is "abcrypt" (61 62 63 72 79 70 74 in hex).

Version number

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

Argon2 parameters

Table 2. Argon2 has the following parameters that control

Parameter	Minimum value	Maximum value	Description
memoryCost	\$8 xx p\$	\$2^(32) - 1\$	Memory size in KiB.
timeCost	\$1\$	\$2^(32) - 1\$	Number of iterations.
parallelism	\$1\$	\$2^(24) - 1\$	Degree of parallelism.

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

Salt

A 32-byte salt for Argon2.

Note	The salt should be generated from a CSPRNG.

Nonce

A 24-byte nonce for XChaCha20-Poly1305.

Note	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).

Important

The abcrypt encrypted data format uses a postfix tag.

ABNF definition of the file format

link:abcrypt.abnf[role=include]

Format changelog

Version 0

Initial release.