Skip to main content

ArxKW

Trait ArxKW 

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

Source

const VARIANT_ID: u8

Stable identifier stored in versioned envelopes (1=E, 2=G, 3=EX, 4=GX).

Provided Associated Constants§

Source

const MAX_INPUT_LENGTH: usize = MAX_INPUT_LENGTH

Maximum plaintext or ciphertext length accepted before allocation.

Required Associated Types§

Source

type Key: Copy + Zeroize + AsRef<[u8]> + AsMut<[u8]>

The type of data which is used as a key for the type that impls this trait. Note that this is not the same for all variants of ARX-KW. E and EX use 48-byte keys; G and GX use 32-byte keys

Required Methods§

Source

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.

Source

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§

Source

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.

Source

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

Source

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.

Source

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);
Source

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

Implementors§