Article 5: The One-Way Cryptographic Migration Process

5.1 The Legacy Debt of XChaCha20

During its initial development phase, LockRoot implemented XChaCha20-Poly1305 on mobile platforms. This cipher, provided by libsodium, offers superior software performance on older ARM processors lacking AES-NI hardware acceleration.

However, the desktop applications (built in C#) exclusively utilized AES-256-GCM, as it is heavily optimized in the .NET framework. This fragmentation meant a user could not natively import an Android vault (XChaCha20) into the Windows app (AES-GCM).

5.2 Designing the V2 Universal Envelope

To resolve this, LockRoot standardized on AES-256-GCM across all platforms, establishing the universal V2 JSON envelope. The engineering challenge was migrating existing mobile users without forcing them to manually re-encrypt their data or navigate complex upgrade prompts.

5.3 Opportunistic Migration Logic

The mobile applications were updated to include the new AES-GCM logic while retaining the legacy lazysodium bindings for XChaCha20.

The migration was implemented opportunistically:

1. The user enters their password.
2. The application parses the vault file. It sees cipher: "xchacha20-poly1305" and version: 1.
3. The app derives the Argon2id key and successfully decrypts the vault using the legacy libsodium bindings.
4. Immediately following a successful decryption, the VaultRepository evaluates the envelope state. Recognizing the legacy format, it triggers the migration routine.
5. The app generates a fresh AES-GCM nonce, re-encrypts the plaintext vault data in memory using the already-derived key, formats the V2 JSON envelope, and overwrites the legacy file on disk.

This process occurs in milliseconds, entirely transparent to the user. By tying the migration to the standard authentication flow, LockRoot successfully unified its cryptographic stack without introducing UX friction or requiring users to manage multiple file formats.