tc_key_wrap 0.1.0

RFC 3394, RFC 5649 and RFC 3211 key wrapping over block ciphers, with shared key-wrap traits.
Documentation

tc_key_wrap

crates.io docs.rs CI license rustc

Key wrapping for block ciphers: RFC 3394 (AES key wrap), RFC 5649 (AES key wrap with padding) and the RFC 3211 key wrap for password-based recipients. Every wrapper runs over an engine that implements the tc_block_cipher traits, such as tc_aes. The crate also defines the KeyWrap and KeyWrapInit contracts that algorithm-specific wrappers implement. Ported from Bouncy Castle C#.

The crate is no_std, needs no allocator by default and contains no unsafe code. The default build depends on tc_block_cipher and tc_zeroize and provides the traits, parameter types and errors; each algorithm is behind its own feature.

Requires Rust 1.85 or later (edition 2024) for the default build and the rfc3394, rfc5649 and alloc features. The rfc3211 feature follows the minimum Rust version of the rand_core crate instead, which is 1.85 for rand_core 0.10.1.

Types

  • Rfc3394WrapEngine (rfc3394) — RFC 3394 key wrap over a cipher with 16-byte blocks.
  • Rfc5649WrapEngine (rfc5649) — RFC 5649 key wrap with padding, for keys of any length.
  • Rfc3211WrapEngine (rfc3211) — RFC 3211 key wrap over a cipher with blocks of 4 bytes or more.
  • KeyWithIvRef, KeyWithIvFixed, KeyWithIvOwned (alloc) — a key and a required IV that borrow, or own and wipe, their bytes.
  • KeyWithIvOptRef, KeyWithIvOptFixed, KeyWithIvOptOwned (alloc) — a key and an optional IV; None selects the wrapper's standard IV.
  • WrapDirection — wrapping or unwrapping, chosen at init.
  • KeyWrapError, KeyWrapInitError — processing and initialization errors that wrap the cipher's.

RFC 3394 wraps a key of 8 bytes or more, in multiples of 8, and adds 8 bytes. Its IV defaults to A6A6A6A6A6A6A6A6; a custom IV is 8 bytes. Rfc3394WrapEngine::with_reverse_direction wraps with the cipher's decryption direction, as Bouncy Castle's useReverseDirection does. RFC 5649 wraps from 1 byte up to 2^32 - 1 bytes and outputs the key rounded up to a multiple of 8, plus 8. Its alternative-IV prefix defaults to A65959A6; a custom prefix is 4 bytes. Bouncy Castle's AesWrapEngine, AriaWrapEngine and the matching *WrapPadEngine classes are these two wrappers over the named cipher.

RFC 3211 wraps a key of up to 255 bytes under an IV of one block. It pads with random bytes from a rand_core::CryptoRng passed to new, so an instance used only for unwrapping also takes a generator.

wrapped_len returns the exact output size and max_unwrapped_len a sufficient capacity; unwrap_into returns how many key bytes it recovered. Every call before init, or in the other direction, returns an error without touching the output. Display writes the cipher's name and the algorithm, such as "AES/RFC3394Wrap".

Traits

  • KeyWrap — sizing, wrap_into and unwrap_into over caller-provided buffers; usable as dyn KeyWrap<Error = E>.
  • KeyWrapInit — initializes a wrapper for a direction from parameters of type P.
  • IvParams — the IV a parameter type provides alongside the cipher's KeyParams.
  • IvOptParams — an IV that may be absent; every IvParams type implements it.

Features

  • rfc3394 (off by default) — adds Rfc3394WrapEngine and the tc_constant_time dependency.
  • rfc5649 (off by default) — adds Rfc5649WrapEngine; enables rfc3394.
  • rfc3211 (off by default) — adds Rfc3211WrapEngine; enables alloc and the rand_core dependency.
  • alloc (off by default) — adds the owned parameter types; does not require the standard library.

Usage

[dependencies]
tc_key_wrap = { version = "0.1.0", features = ["rfc3394"] }
tc_aes = "0.1.0"
use tc_aes::AesEngine;
use tc_key_wrap::{KeyWithIvOptRef, KeyWrap, KeyWrapInit, Rfc3394WrapEngine, WrapDirection};

let (kek, key) = ([0x42; 16], [0x11; 16]);
let mut wrapper = Rfc3394WrapEngine::new(AesEngine::new());
wrapper.init(WrapDirection::Wrap, &KeyWithIvOptRef::new(&kek, None)).expect("valid KEK");
let mut wrapped = [0; 24];
wrapper.wrap_into(&key, &mut wrapped).expect("initialized, valid key length");

The type documentation carries an executable example for every wrapper.

Security

RFC 3394 and RFC 5649 are deterministic: the same key-encryption key and key always give the same output. They authenticate the key with a 64-bit check, which suits key material but not general messages.

RFC 3211 checks only a length byte and 3 check bytes. They catch a wrong key-encryption key but are no strong integrity check: a forged blob passes with a probability near 2^-24. Give every wrap a fresh random IV. The engine takes a key-encryption key, not a password; derive the key from the password first, for example with PBKDF2.

Rfc3394WrapEngine is constant time exactly when its cipher is. Rfc5649WrapEngine is too, except that the padding check follows the recovered length, which a successful unwrap reveals. Rfc3211WrapEngine is constant time exactly when its cipher is, apart from the key length and whether the check passed; wrapping adds the generator's own time. tc_aes::AesEngine, for example, is constant time with AES-NI or its rustcrypto feature and variable time otherwise.

A failed wrap wipes the output. A failed RFC 3394 or RFC 5649 unwrap wipes the output, and a failed RFC 3211 unwrap leaves it untouched. The fixed and owned parameter types wipe their bytes on drop, every parameter type's Debug redacts the key and IV, and the cipher wipes its own key schedule. Wiping does not reach the caller's buffers, copies left in registers and on the stack, or a value that is leaked or forgotten.

Validation

Rfc3394WrapEngine is tested against the six RFC 3394 vectors and Rfc5649WrapEngine against the two RFC 5649 vectors, plus three independent ARIA vectors. Rfc3211WrapEngine is tested against Bouncy Castle's DES, Triple-DES, AES and ARIA vectors and a round trip with a seeded StdRng. Contract tests cover custom IVs, trait objects, tampering, direction and sizing errors, short outputs and IV validation. A test requires every public API to document whether it is constant or variable time.

Missing public documentation and unsafe code are rejected by crate-level lints.

Run these commands from the workspace root:

cargo test -p tc_key_wrap --locked
cargo test -p tc_key_wrap --locked --all-features
cargo clippy -p tc_key_wrap --all-targets --all-features --locked -- -D warnings
cargo fmt -p tc_key_wrap --check
cargo doc -p tc_key_wrap --no-deps --all-features --locked

Before a release, check the archive contents and run publication validation from a committed checkout:

cargo package -p tc_key_wrap --list --locked
cargo publish -p tc_key_wrap --dry-run --locked

The archive includes both license texts, this README, the changelog, the source and the integration tests. It must not include target/ or other build artifacts.

License

Licensed under either the MIT license or the Apache License, Version 2.0, at your option.