Article 2: Architecting the V2 Vault JSON Envelope

2.1 The Need for a Universal Format

LockRoot operates across five operating systems (Android, iOS, Windows, Linux, macOS) utilizing three distinct programming languages. To enable seamless interoperability—allowing a user to export a vault from their Android phone and import it into their Linux desktop—the software required a strictly defined, parser-agnostic serialization format.

2.2 The V2 Envelope Structure

The V2 envelope is a UTF-8 encoded JSON object. It acts as an unencrypted header, providing the cryptographic parameters necessary for the client to derive the key and configure the cipher.

{
  "magic": "Lockroot_VAULT",
  "version": 2,
  "kdf": {
    "name": "argon2id",
    "memory": 65536,
    "iterations": 3,
    "parallelism": 2,
    "salt": "<base64>"
  },
  "cipher": {
    "name": "aes-256-gcm",
    "nonce": "<base64>"
  },
  "ciphertext": "<base64>",
  "tag": "<base64>"
}

2.3 The “Magic” Identifier

The magic string serves as an explicit file type identifier. LockRoot generates two distinct files: actual vaults (Lockroot_VAULT) and exports (Lockroot_EXPORT).

Exports are encrypted with a separate password and a unique salt. The differing magic strings ensure that the application parsers can instantly distinguish between the two contexts, preventing a user from accidentally importing a live vault file into the export flow.

2.4 Associated Data (AAD) Binding

A known vulnerability in envelope-based encryption is parameter tampering. An attacker could modify the plaintext JSON, changing the Argon2id iterations from 3 to 1.

To prevent this, LockRoot cryptographically binds the entire envelope to the AES-GCM tag via Associated Data (AAD). A pipe-delimited string is constructed: Lockroot_VAULT|2|argon2id|65536|3|2|<salt_b64>|aes-256-gcm|<nonce_b64>. This string is passed into the AES-GCM cipher. If the parsed JSON envelope does not perfectly match the AAD used during encryption, the authentication tag fails to validate, and the application throws an exception.

---