OverviewSignetSemaForeCuriousLee
Assurance record Published engineering decision

Backup file format

The accepted engineering decision defining Attomus Signet's authenticated, cross-platform backup format.

AUTH-ADR-0027 — Backup File Format Ratification (P0-05 Close)

Status: ACCEPTED — 2026-04-14 Decision authority: Attomus Security Architecture Resolves: P0-05 (MASTER-DELIVERY-PLAN.md §5) — backup format self-describing header Supersedes: Nothing. Ratifies an existing definition.

Context

MASTER-DELIVERY-PLAN.md §5 listed P0-05 as a blocking pre-condition for Phase 2:

“Current backup format lacks KDF identifier, Argon2id parameters, cipher identifier, and plaintext schema version in the authenticated header. Future migrations without this are impossible without breaking backward compatibility.”

During Design Review 1, design review 1/crypto-architecture.md §3.4 was updated to define a complete, self-describing backup file format including the authenticated 28-byte header. That update resolved P0-05 at the source, but no ADR was raised to formally close the item. This ADR closes it.

Decision

The canonical backup file format for Attomus Signet is defined in design review 1/crypto-architecture.md §3.4 and is hereby ratified without change. The format is summarised here for traceability; the specification document is authoritative.

Header (28 bytes, AEAD associated data)

Offset  Length  Field              Value (v1)    Description
------  ------  -----              ----------    -----------
0       4       magic              0x41544D53    ASCII "ATMS"
4       2       format_version     0x0001        Increment on breaking change
6       1       kdf_id             0x01          0x01 = Argon2id
7       1       argon2_version     0x13          Argon2 algorithm version 1.3
8       4       argon2_m           0x00010000    Memory cost KiB (65536 = 64 MB), big-endian
12      2       argon2_t           0x0003        Iterations (3), big-endian
14      2       argon2_p           0x0004        Parallelism (4), big-endian
16      2       salt_len           0x0020        Salt length in bytes (32), big-endian
18      2       nonce_len          0x000C        Nonce length in bytes (12), big-endian
20      1       cipher_id          0x01          0x01 = AES-256-GCM
21      2       plaintext_schema   0x0001        Plaintext JSON schema version (see below)
23      2       key_len            0x0020        Derived key length in bytes (32), big-endian
25      2       reserved           0x0000        Must be zero; reserved for future flags
27      1       header_len         0x1C          Length of this header in bytes (28)

Full file layout

[header:28][salt:32][nonce:12][ciphertext+tag:(N+16)]

The full 28-byte header is the AES-GCM additional authenticated data (AAD). Any modification to any header byte causes GCM tag verification to fail before decryption is attempted.

Plaintext format (schema version 1)

The plaintext is UTF-8 JSON matching the schema in the cryptographic architecture record. Key structural points:

  • Top-level field "schema": 1 must match plaintext_schema in the header
  • "accounts" array; each entry is a complete account record including Base32-encoded secret
  • HOTP accounts include "counter" (integer); TOTP accounts include "period" (integer); "counter" is null for TOTP entries

File extension and MIME type

Extension:  .attomusauth
MIME type:  application/x-attomus-auth

These must be registered in Info.plist (iOS) and the Android manifest respectively.

Rationale

The format defined in Design Review 1 satisfies all P0-05 requirements:

  • The KDF identifier (kdf_id) and all Argon2id parameters are in the authenticated header, so a future parameter change does not break files written with the old parameters
  • The format_version field allows the parser to reject or handle files from newer app versions
  • The plaintext_schema version field allows the plaintext format to evolve independently of the encryption envelope
  • The header_len field allows header extension without ambiguity
  • All of these fields are covered by the GCM authentication tag, preventing a downgrade attack that forges weaker Argon2id parameters

Cross-platform compatibility requirement

The binary format — byte offsets, field widths, byte order, all values — must be identical across iOS (Swift) and Android (Kotlin). A backup file created on iOS must be restorable on Android and vice versa. Any proposed change to the format requires a new ADR and must be implemented simultaneously on both platforms.

Consequences

Immediate

  • P0-05 is CLOSED. The Phase 2 pre-condition check for P0-05 is satisfied.
  • All Phase 2 prompts that listed P0-05 as an open item are to be read as confirmed.
  • The authoritative format reference is design review 1/crypto-architecture.md §3.4.

Implementation contracts

  • Dev 1 (AttomusOTP Swift): encodeExportDocument returns UTF-8 JSON Data (Foundation only, no CryptoKit). decodeExportDocument validates "schema": 1.
  • Dev 2 (iOS app): file extension .attomusauth, MIME type application/x-attomus-auth. Argon2id parameters are read from the header on import — do not hard-code them at the call site.
  • Dev 3 (Android): same file extension and MIME type. Kotlin implementation must produce byte-identical output to the iOS implementation for a given input.

Prohibited deviations (require a new ADR)

  • Changing the file extension or MIME type
  • Changing any byte offset or field width in the header
  • Changing format_version without a corresponding ADR covering migration behaviour
  • Using a plaintext format other than UTF-8 JSON for schema version 1
  • Hard-coding Argon2id parameters at any call site — they must always be read from the header on import and written from named constants on export