Arculus .arc Format Security Upgrades — Proposal & Implementation Plan (PIP1)

[Scrince]

Overview

This post outlines a planned series of cryptographic upgrades to the Arculus .arc encrypted seed backup format. The goal is to replace several hand-rolled or legacy cryptographic constructions with modern, standardized primitives available natively in the Web Crypto API with zero new external dependencies and full backward compatibility with all existing .arc files and keyfiles.

These changes will be implemented as a new format version (v3) alongside two supporting upgrades to the keyfile encryption scheme and the credential combination function. No existing decrypt paths will be modified. All currently valid .arc files and keyfiles will continue to work exactly as they do today.

---

Background and Motivation

The current v2 .arc format uses a custom stream cipher built from HMAC-SHA512 blocks XORed against the plaintext, with a separate HMAC-SHA512 MAC computed over the ciphertext and all metadata fields. While this construction is not broken, it has two meaningful weaknesses worth addressing.

First, the cipher is non-standard. It is not a vetted algorithm, it cannot be audited against published test vectors, and no external tooling can interoperate with it. Any future security review of Arculus would need to independently assess this construction rather than relying on the extensive public analysis that standard algorithms benefit from.

Second, the MAC preimage uses null-byte separators between fields rather than length-prefixed encoding. This is a minor structural issue that creates theoretical ambiguity in how the authenticated data is assembled, even though no practical attack exploits it in this specific context.

The encrypted keyfile format has the same cipher issue — it also uses HMAC-SHA512-CTR with a separate MAC rather than an authenticated encryption primitive.

Finally, the credential combination function that mixes a password and keyfile together uses a single SHA-256 hash over a concatenated string. SHA-256 is a hash function, not a key derivation function, and using it for key combination is technically incorrect even if it does not produce an exploitable weakness in practice.

None of these are critical vulnerabilities. The existing format is reasonably secure for most threat models. These upgrades are about correctness, auditability, and alignment with current cryptographic best practices — not emergency remediation.

---

Planned Changes

.arc Format v3

New saves will use AES-256-GCM instead of HMAC-SHA512-CTR. AES-GCM is an authenticated encryption with associated data (AEAD) primitive, meaning authentication is built into the cipher itself — no separate MAC field is needed. The entire bundle header (magic, format, version, created_at, KDF parameters, cipher name, and credential mode) will be passed as AES-GCM additional authenticated data, which cryptographically binds the header to the ciphertext. Any tampering with the header will cause decryption to fail.

The plaintext will be padded to a fixed 512 bytes before encryption. This eliminates a minor information leak where the ciphertext length reveals whether the mnemonic is 12 or 24 words.

A credential_mode field will be added to the v3 bundle to explicitly record whether the file was encrypted with a password, a keyfile, or both. This field is included in the AAD, so it cannot be stripped or altered without breaking authentication.

The KDF path will be split based on credential mode. Password-only mode will continue to use PBKDF2-SHA512 at 1,000,000 iterations, with a SHA-512 pre-hash of the password applied before stretching to correctly handle passwords longer than the HMAC block size. Keyfile-only and combined modes will use HKDF-SHA512 instead of PBKDF2, since the keyfile already supplies 512 bits of random entropy and iteration-based stretching adds no meaningful security at that entropy level.

Encrypted Keyfile Format v2

The .enc.key encrypted keyfile format will receive the same AES-256-GCM upgrade. A new encryptArcKeyfileBytes_v2 function will be added alongside the existing encryptArcKeyfileBytes, and new saves will use the v2 path. Old encrypted keyfiles will continue to be read by the existing decrypt function which will route based on the version field.

combinedArcSecret Upgrade

The function that combines a password and keyfile into a single credential will be upgraded from SHA-256 over a concatenated string to HKDF-SHA512 over the concatenated raw bytes, using the arc file's own salt as the HKDF salt and a fixed info string. This is the formally correct construction for combining key material from multiple sources. The existing SHA-256 combination logic will be preserved as combinedArcSecret_legacy and called explicitly inside decryptV2 so that existing combined-mode v2 files continue to decrypt correctly.

Memory Hygiene

Intermediate byte arrays holding raw password bytes, derived key material, and keyfile bytes will be zeroed with .fill(0) after use in all new v3 code paths, consistent with the pattern already used in the existing keyfile functions.

---

What Will Not Change

Every existing decrypt function — decryptV1, decryptV2, decryptArcKeyfileObject — will remain completely untouched. The decrypt router will gain a v3 branch at the top and nothing else will change. The BIP39 wordlist, all coin derivation logic, PDF export, QR code generation, address table rendering, all UI code, and all other application features are entirely unaffected. This is purely a cryptographic layer change.

---

Compatibility Matrix

File type | Existing files | New saves -- | -- | -- Compatibility Matrix .arc v1 (AES-GCM, SHA-256, 250k iterations)

Existing files: readable as before. New saves: no longer written.
.arc v1 (XOR-CTR, SHA-256, 250k iterations)

Existing files: readable as before. New saves: no longer written.
.arc v2 (HMAC-SHA512-CTR, 1M iterations)

Existing files: readable as before. New saves: no longer written.
.arc v3 (AES-256-GCM, 1M iterations)

Existing files: readable as before. New saves: written by default going forward.
.key plain keyfile

Existing files: readable as before. New saves: written unchanged.
.enc.key v1 encrypted keyfile (HMAC-SHA512-CTR)

Existing files: readable as before. New saves: no longer written.
.enc.key v2 encrypted keyfile (AES-256-GCM)

Existing files: readable as before. New saves: written by default going forward.

---

Why No External Dependencies

Argon2id would be the strongest possible KDF upgrade and is what tools like Bitwarden and 1Password use for exactly this use case. It is not being included here because it requires a WASM build, which would introduce an external dependency into what is deliberately a single self-contained HTML file. PBKDF2 at 1,000,000 iterations with SHA-512 is a reasonable baseline for most threat models. Argon2id remains the correct long-term answer if the single-file constraint is ever relaxed, and the v3 format is designed so the KDF field is explicitly recorded in the bundle, making a future v4 format with Argon2id straightforward to add without breaking anything.

---

Feedback Welcome

If you have concerns about any of the construction choices above, see an issue with the AAD composition, or have thoughts on the HKDF info strings or padding strategy, please comment below. The implementation has not been merged yet and this post exists specifically to gather review before it lands.

[Scrince]

This is currently being worked.

[CrumbleStack]

Naming convention has been changed to YellowSphere to reduce confusion.