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 / type | Wrapping key | Maximum plaintext | Cipher |
|---|---|---|---|
e / E | 48 bytes | 64 bytes | ChaCha8 |
g / G | 32 bytes | 64 bytes | ChaCha8 |
ex / EX | 48 bytes | 1 MiB | XChaCha8 |
gx / GX | 32 bytes | 1 MiB | XChaCha8 |
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.