Skip to main content

Crate arx_kw

Crate arx_kw 

Source
Expand description

§ARX-KW

Rust implementations of the ARX-KW-8-2-4 key-wrap constructions from Satō Shinichi’s paper. These combine SipHash-2-4 with 128-bit output and ChaCha8 or XChaCha8 to wrap secret key material.

Project website · API reference · Changelog

Version 0.5.0 requires Rust 1.88 or newer. See the changelog for migration notes and crates.io for published versions.

§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.

§Installation

Requires Rust 1.88 or later (including benchmark dependencies).

[dependencies]
arx-kw = "0.5"

To enable only GX:

[dependencies]
arx-kw = { version = "0.5", default-features = false, features = ["gx"] }

§Optional dependencies

Version 0.5 makes the context KDF optional; 0.4.0 included it unconditionally. Default builds keep the same API and byte formats.

FeatureOptional runtime dependencies / capabilities
e, gchacha20 and arrayref; ChaCha8 only
ex, gxchacha20 and arrayref, including XChaCha support
envelopehmac and sha2; context-bound envelope methods and constants

For a minimal raw GX build, disable default features and enable only gx. For context-bound wrapping, enable both features:

[dependencies]
arx-kw = { version = "0.5", default-features = false, features = ["gx", "envelope"] }

Migration for reduced-feature builds: unlike 0.4.0, enabling a variant alone no longer provides encrypt_envelope, decrypt_envelope, ENVELOPE_HEADER_LENGTH, or MAX_CONTEXT_LENGTH. Add envelope when using those APIs when migrating to 0.5. The default feature set keeps those APIs available.

Without any features, the crate provides shared types and the ArxKW trait, with no built-in cipher variant. zeroize, subtle, and thiserror remain required by those public types, constant-time comparison, and error handling. Example randomness uses a development-only getrandom dependency; it does not add a runtime dependency for library consumers.

§Example

The following uses the GX test vector from the paper. Generate wrapping keys with a cryptographically secure random source in applications; the fixed key here is for demonstration only.

use arx_kw::{gx::GX, ArxKW};
use hex::FromHex;

let key = <[u8; 32]>::from_hex(
    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
)?;
let plaintext = <[u8; 32]>::from_hex(
    "deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
)?;
let expected = hex::decode(
    "016325cf6a3c4b2e3b039675e1ccbc652f83f391c97f3606ccd5709c6ee15d66cd7e65a2aeb7dc3066636e8f6b0d39c3",
)?;
let blob = GX::encrypt_blob(&key, &plaintext)?;
assert_eq!(blob, expected);
assert_eq!(GX::decrypt_blob(&key, &blob)?, plaintext);

Add hex = "0.4.3" to run this example. Import ArxKW to call the methods. Use encrypt and decrypt when storing ciphertext and AuthTag separately. Treat every decryption error as a failure; do not use unauthenticated data.

§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.

§Runnable programs

Run these examples from a checkout of this release. Each uses OS randomness, checks recovery and rejection cases, and prints only sizes or status messages. They do not persist keys or write secret material to disk.

ProgramUse caseRequired features
wrap_keyBind a generated data key to a tenant contextgx,envelope
rotate_keyRewrap a data key under a new wrapping keygx,envelope
detached_tagStore ciphertext and authentication tag separatelyg
cargo run --example wrap_key --no-default-features --features gx,envelope
cargo run --example rotate_key --no-default-features --features gx,envelope
cargo run --example detached_tag --no-default-features --features g

The programs demonstrate the wrapping step, not complete key-management systems. Production applications must protect and retain wrapping keys, choose stable contexts, and commit rotations transactionally. Detached storage needs a dedicated key for protocol separation because it has no context field. See the example source programs.

§Release-specific recipes and tooling

Symposiast guidance for 0.5.0 provides compiled consumer recipes for tenant-bound wrapping, key rotation, and detached-tag storage, with minimal features and frozen source citations. It includes a portable Symposium skill and a full bundle for MCP retrieval and version checks. Generation and validation tooling is development-only and excluded from the crate.

§Development

cargo build
cargo test
cargo test --no-default-features --features gx
cargo test --no-default-features --features gx,envelope
python dev/check-features.py
cargo doc --no-deps
cargo bench

The unit tests include the paper’s vectors for all four variants, plus malformed-input, authentication, boundary, and stream-counter regressions. Frozen envelope v1 vectors preserve compatibility with the published 0.4.0 crate. Property tests generate keys, messages, contexts, and mutations; failures are shrunk and saved by Proptest for reproduction. Instrumented fuzz targets and local commands are documented in fuzz/README.md. Documentation examples run as doctests. Benchmarks use Criterion; use cargo bench --bench gx for one variant. No service or credentials are needed. Cargo.lock is intentionally ignored for this library; after initial resolution, use --locked to retain the local resolution.

§Migrating from 0.3

Version 0.4 updates all direct dependencies, including RustCrypto chacha20 0.10, thiserror 2, and Criterion 0.8. The legacy chacha, byteorder, and siphasher runtime dependencies have been removed. SipHash-2-4-128 uses zeroizing state and is checked against the independent siphasher oracle. Published paper-vector outputs are unchanged. EX/GX now reject inputs above one MiB, including legacy ciphertexts previously accepted at larger sizes; plan migration of such records using the earlier release before upgrading.

ArxKwError::BadTags is now a unit variant: authentication errors no longer expose a computed tag in their fields, display text, or debug output. InvalidBlobLength(usize) reports blobs missing a complete tag. Update exhaustive error matches accordingly. Custom ArxKW implementations must provide VARIANT_ID and key types supporting Copy, Zeroize, AsRef, and AsMut. New errors cover allocation, context, and envelope validation failures. The old nightly SIMD feature has been removed because the upstream implementation relies on obsolete compiler SIMD interfaces; the supported workflow uses stable Rust.

For the Stucco website build and deployment, see Website development. See the Release guide for automated verification and publishing.

§References and license

Modules§

e
Module containing items related to the ARX-KW-8-2-4-E variant
ex
Module containing items related to the ARX-KW-8-2-4-EX variant
g
Module containing items related to the ARX-KW-8-2-4-G variant
gx
Module containing items related to the ARX-KW-8-2-4-GX variant

Macros§

assert_ct_eq
Asserts equality using ConstantTimeEq. The second argument must be a reference.

Structs§

AuthTag
The 16-byte authentication tag stored alongside encrypted keys.
Choice
The Choice struct represents a choice for use in conditional assignment.
SecretBytes
Owned plaintext that is wiped on drop and redacted from debug output. Avoid making unguarded copies through the borrowed slice.
SecretKey
Owned wrapping key that is wiped on drop and redacted from debug output. Borrow with &*key when calling this crate. Caller-owned copies are not erased.
Zeroizing
Zeroizing is a wrapper for any Z: Zeroize type which implements a Drop handler which zeroizes dropped values.

Enums§

ArxKwError
The error type used by this crate.
InvalidLengthError
An error denoting that a value was of an invalid length. Typically this will be used as a variant of ArxKwError rather than on its own.

Constants§

ENVELOPE_HEADER_LENGTH
Length of the magic, version, variant, and reserved bytes preceding a legacy blob.
MAX_CONTEXT_LENGTH
Maximum application context length in bytes (four KiB).
MAX_INPUT_LENGTH
Maximum accepted plaintext size: one MiB. E/G retain their stricter 64-byte limit.

Traits§

ArxKW
Provides deterministic, authenticated key wrapping.
ConstantTimeEq
An Eq-like trait that produces a Choice instead of a bool.
Zeroize
Trait for securely erasing values from memory.

Derive Macros§

Zeroize
Derive the Zeroize trait.