pub trait ArxKW {
type Key: Copy + Zeroize + AsRef<[u8]> + AsMut<[u8]>;
const VARIANT_ID: u8;
const MAX_INPUT_LENGTH: usize = MAX_INPUT_LENGTH;
// Required methods
fn encrypt(
key: &Self::Key,
plaintext: &[u8],
) -> Result<(Vec<u8>, AuthTag), ArxKwError>;
fn decrypt(
key: &Self::Key,
ciphertext: &[u8],
authentication_tag: &AuthTag,
) -> Result<Vec<u8>, ArxKwError>;
// Provided methods
fn encrypt_envelope(
key: &Self::Key,
plaintext: &[u8],
context: &[u8],
) -> Result<Vec<u8>, ArxKwError> { ... }
fn decrypt_envelope(
key: &Self::Key,
input: &[u8],
context: &[u8],
) -> Result<SecretBytes, ArxKwError> { ... }
fn decrypt_secret(
key: &Self::Key,
blob: &[u8],
) -> Result<SecretBytes, ArxKwError> { ... }
fn encrypt_blob(
key: &Self::Key,
plaintext: &[u8],
) -> Result<Vec<u8>, ArxKwError> { ... }
fn decrypt_blob(key: &Self::Key, blob: &[u8]) -> Result<Vec<u8>, ArxKwError> { ... }
}Expand description
Provides deterministic, authenticated key wrapping.
Keys are fixed-length arrays; E and EX use 48 bytes, G and GX use 32 bytes.
Plaintext and ciphertext are byte slices. E/G reject inputs over 64 bytes.
Blob methods encode the 16-byte tag followed by ciphertext; applications
can instead store the results of ArxKW::encrypt separately.
Required Associated Constants§
Sourceconst VARIANT_ID: u8
const VARIANT_ID: u8
Stable identifier stored in versioned envelopes (1=E, 2=G, 3=EX, 4=GX).
Provided Associated Constants§
Sourceconst MAX_INPUT_LENGTH: usize = MAX_INPUT_LENGTH
const MAX_INPUT_LENGTH: usize = MAX_INPUT_LENGTH
Maximum plaintext or ciphertext length accepted before allocation.
Required Associated Types§
Required Methods§
Sourcefn encrypt(
key: &Self::Key,
plaintext: &[u8],
) -> Result<(Vec<u8>, AuthTag), ArxKwError>
fn encrypt( key: &Self::Key, plaintext: &[u8], ) -> Result<(Vec<u8>, AuthTag), ArxKwError>
Encrypts the plaintext using ARX-KW and returns the encrypted ciphertext and an AuthTag
The authentication tag can be stored/transported alongside it and is needed (along with the key used to encrypt the plaintext) in order to decrypt the wrapped key.
§Errors
Returns an error if the plaintext exceeds the variant limit or the ChaCha stream is exhausted. Key lengths are checked by the type system.
Sourcefn decrypt(
key: &Self::Key,
ciphertext: &[u8],
authentication_tag: &AuthTag,
) -> Result<Vec<u8>, ArxKwError>
fn decrypt( key: &Self::Key, ciphertext: &[u8], authentication_tag: &AuthTag, ) -> Result<Vec<u8>, ArxKwError>
Attempts to decrypt the ciphertext using ARX-KW and returns the decrypted plaintext if
successful. As ARX-KW is a form of authenticated encryption, the authenticity of the
decrypted text is verified if the function returns an Ok value.
§Errors
Returns an error if the ciphertext exceeds the variant limit, authentication fails, or the ChaCha stream is exhausted. Key lengths are checked by the type system.
Provided Methods§
Sourcefn encrypt_envelope(
key: &Self::Key,
plaintext: &[u8],
context: &[u8],
) -> Result<Vec<u8>, ArxKwError>
fn encrypt_envelope( key: &Self::Key, plaintext: &[u8], context: &[u8], ) -> Result<Vec<u8>, ArxKwError>
Wraps key material into a versioned envelope bound to an application context.
Available with the envelope feature (enabled by default).
Use a stable, application-specific context such as b"example.com/storage/v1".
The context is not stored; supply exactly the same bytes during decryption.
§Errors
Returns an error for oversized inputs/context, allocation failure, or encryption failure.
Sourcefn decrypt_envelope(
key: &Self::Key,
input: &[u8],
context: &[u8],
) -> Result<SecretBytes, ArxKwError>
fn decrypt_envelope( key: &Self::Key, input: &[u8], context: &[u8], ) -> Result<SecretBytes, ArxKwError>
Opens a versioned envelope into plaintext that zeroizes when dropped.
Available with the envelope feature (enabled by default).
§Errors
Rejects invalid headers, wrong variants, oversized input/context, allocation failure, and authentication failure (including a changed context).
Sourcefn decrypt_secret(
key: &Self::Key,
blob: &[u8],
) -> Result<SecretBytes, ArxKwError>
fn decrypt_secret( key: &Self::Key, blob: &[u8], ) -> Result<SecretBytes, ArxKwError>
Decrypts a legacy blob into plaintext that zeroizes when dropped.
§Errors
Returns the same errors as ArxKW::decrypt_blob.
Sourcefn encrypt_blob(
key: &Self::Key,
plaintext: &[u8],
) -> Result<Vec<u8>, ArxKwError>
fn encrypt_blob( key: &Self::Key, plaintext: &[u8], ) -> Result<Vec<u8>, ArxKwError>
Encrypts the plaintext and returns a Vec<u8> containing both the authentication tag
and the ciphertext.
While ARX-KW by design eliminates the need for nonce management, it can
be further used to eliminate the complexity of managing authentication tags as well without
incurring a large storage overhead. The encrypt_blob and decrypt_blob methods allow for
this abstraction; the ciphertext and authentication tag can be treated as one opaque “blob” of bytes
and so authentication and decryption of that blob can be done with just the key,
eliminating the need to separately store a nonce or authentication tag. This gives a
user-friendly interface to deterministic and authenticated encryption.
§Errors
Returns an error if the plaintext exceeds the variant limit or the ChaCha stream is exhausted. Key lengths are checked by the type system.
use arx_kw::{ArxKW,gx::GX,assert_ct_eq,ConstantTimeEq};
extern crate hex;
use hex::FromHex;
let key = <[u8; 32]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f")?; // The key being used to encrypt the plaintext
let plaintext = <[u8; 32]>::from_hex("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")?; // The key that we are trying to encrypt, as plaintext
// The expected output: a "blob" consisting of the authentication tag followed by ciphertext. This can be treated as one opaque piece of data when using encrypt_blob and decrypt_blob
let blob_expected = <[u8; 48]>::from_hex("016325cf6a3c4b2e3b039675e1ccbc652f83f391c97f3606ccd5709c6ee15d66cd7e65a2aeb7dc3066636e8f6b0d39c3")?;
let blob = GX::encrypt_blob(&key, &plaintext)?; // The output of encrypt_blob, a Vec<u8>
assert_ct_eq!(blob, &blob_expected);Sourcefn decrypt_blob(key: &Self::Key, blob: &[u8]) -> Result<Vec<u8>, ArxKwError>
fn decrypt_blob(key: &Self::Key, blob: &[u8]) -> Result<Vec<u8>, ArxKwError>
Decrypts a blob containing an authentication tag followed by the corresponding ciphertext
If decryption is successful, returns a Vec<u8> containing the decrypted plaintext.
While ARX-KW by design eliminates the need for nonce management, it can
be further used to eliminate the complexity of managing authentication tags as well without
incurring a large storage overhead. The encrypt_blob and decrypt_blob methods allow for
this abstraction; the ciphertext and authentication tag can be treated as one opaque “blob” of bytes
and so authentication and decryption of that blob can be done with just the key,
eliminating the need to separately store a nonce or authentication tag. This gives a
user-friendly interface to deterministic and authenticated encryption.
§Errors
Returns an error if the ciphertext exceeds the variant limit, the authentication tag does not match the ciphertext that follows it, the blob contains fewer than 16 bytes, or if the end of the [X]ChaCha stream is reached unexpectedly
use arx_kw::{ArxKW,e::E,assert_ct_eq,ConstantTimeEq};
extern crate hex;
use hex::FromHex;
let key = <[u8; 48]>::from_hex("000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f")?;
let blob = <[u8; 48]>::from_hex("c4f21d3b4dbcc566c3a73bbc59790f2fe6457d24abaf7c2ebdb91416a18366d31a66db61a4e45c9f42a119c353bb1eb1")?;
let plaintext_expected = <[u8;32]>::from_hex("deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef")?;
let plaintext = E::decrypt_blob(&key, &blob)?;
assert_ct_eq!(plaintext, &plaintext_expected);Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety".