Skip to main content

ARX-KW / DOCUMENTATION

Security boundaries

Input limits, determinism, context binding, and the scope of memory erasure.

Security and input limits

ARX-KW is deterministic: the same key and plaintext produce the same output. Use it for high-entropy secret keys. Repeated inputs remain recognizable; this is not a general-purpose encryption API for passwords, messages, or other predictable data. For new integrations use the versioned envelope API, which binds an application context through HKDF-SHA-256 and identifies the format version and variant. Legacy blobs remain available for compatibility; they require applications to manage protocol separation themselves.

Feature / typeWrapping keyMaximum plaintextCipher
e / E48 bytes64 bytesChaCha8
g / G32 bytes64 bytesChaCha8
ex / EX48 bytes1 MiBXChaCha8
gx / GX32 bytes1 MiBXChaCha8

All four variant features and envelope are enabled by default. EX/GX enforce a one-MiB input limit before hashing, key derivation, or output allocation. Output allocations use fallible reservation and return AllocationFailed on failure. E/G bounds exclude the authentication tag. Empty plaintexts are accepted. Every authentication tag is 16 bytes; blobs are tag || ciphertext, so a wrapped 32-byte key occupies 48 bytes. Blobs shorter than 16 bytes return an error. Decryption releases plaintext only after checking the tag with subtle::ConstantTimeEq.

This implementation has not been established by this review to have an independent cryptographic audit. Owned stream state, SipHash state, derived subkeys, KDF chaining buffers, and rejected plaintext buffers are wiped with zeroize. Use SecretKey for owned wrapping keys and decrypt_envelope or decrypt_secret for plaintext with drop-time erasure and redacted debug output. Legacy decrypt and decrypt_blob return ordinary vectors whose erasure is the caller's responsibility, as is the erasure of borrowed input or copied keys. Wiping owned storage cannot guarantee erasure of compiler-created copies, CPU registers, provider-internal scratch, swap, or crash dumps. Constant-time tag comparison does not establish whole-program constant-time behavior.

Report vulnerabilities privately using SECURITY.md.

Versioned envelopes and secret ownership

For new applications, enable envelope and use a stable, protocol-specific context with the envelope methods. The fixed key in this example is a test fixture; applications must supply cryptographically random wrapping keys.

use arx_kw::{gx::GX, ArxKW, SecretKey};
let key = SecretKey::new([0x42; 32]); // Test fixture only.
let context = b"example.com/key-storage/v1";
let envelope = GX::encrypt_envelope(&key, b"example key material", context)?;
let plaintext = GX::decrypt_envelope(&key, &envelope, context)?;
assert_eq!(plaintext.as_ref(), b"example key material");
// `key` and `plaintext` are wiped when they leave scope.

Envelope v1 is ARXK || 01 || variant || 0000 || tag || ciphertext: the first eight bytes contain magic, version, variant (E=1, G=2, EX=3, GX=4), and two reserved zero bytes. Context bytes are not stored; callers must supply exactly the same context (at most 4096 bytes) when opening an envelope. The per-context wrapping key is derived using RFC 5869 HKDF-SHA-256, with salt ARX-KW/context/v1, the original wrapping key as input key material, and header || context as info. Its length matches the original key length. This binds the header and context while preserving the paper's primitive for legacy blobs. Envelopes add 24 bytes in total. Unknown versions, variants, or reserved flags fail closed; the API never falls back to legacy decryption. Use one format explicitly at each storage boundary. Determinism still reveals repeated inputs within the same key and context.