Struct Key 

pub struct Key<const BYTES: usize> { /* private fields */ }

Stores the secret key used in AEGIS encryption and decryption.

This type takes a const generic parameter (BYTES) specifying the number of key bytes. AEGIS-128[L|X] ciphers use 128 bit keys while AEGIS-256[X] ciphers use 256 bit keys. (All ciphers validate the provided Key size at compile time making it impossible to use an incorrect Key size.)

Since only 128 or 256 bit keys are valid for AEGIS ciphers, only values 16 and 32 are supported for the Key’s BYTES const generic parameter. This too is validated at compile time.

Key128 (for Key<16>) and Key256 (for Key<32>) type aliases are provided for convenience and should be preferred over raw Key usage.

Use Key::generate() to securely create random Keys instead of generating key bytes yourself and passing them to Key::new() or Key::from_bytes(). The Key::generate() method will use an appropriate cryptographically secure random number generator (CSRNG) provided by the OS.

You can access the internal key bytes with Key::expose_secret(). This method is also the only way to access secret bytes once they are stored in Key, making security audits easier.

Key uses a custom implementation of Debug that always redacts the key bytes to prevent accidental exposure of secrets through logs or other machinery.

This type is zeroized on Drop.

Note that derives for Eq and PartialEq are intentionally omitted to prevent accidental non-constant-time equality comparisons. Use Key::expose_secret() and the constant_time_eq crate if you need this. Clone is not implemented to prevent accidental secret duplication.

Implementations

impl<const BYTES: usize> Key<BYTES>

pub const BYTES: usize = BYTES

The length of Key in bytes.

pub fn generate() -> Result<Self>

Create a new, random Key from a cryptographically secure random number generator (CSRNG).

Errors

• Returns Error::RandError if there’s an error in fetching random bytes.

pub fn new(data: [u8; BYTES]) -> Result<Self>

Create a new Key from a correctly sized byte array.

Prefer Key::generate() over this method.

The bytes you provide must come from cryptographically secure random number generator (CSRNG). Do not use whatever RNG you found lying around.

Errors

• Returns Error::AllZeroNotAllowed if the provided byte array contains only zeros.

pub fn from_bytes<T: AsRef<[u8]>>(data: T) -> Result<Self>

Create a new Key from any T which implements AsRef<[u8]>. Thus it’s possible to pass a &[u8], a &mut [u8], a Vec<u8>, a Box<[u8]> etc.

Prefer Key::generate() over this method.

The bytes you provide must come from cryptographically secure random number generator (CSRNG). Do not use whatever RNG you found lying around.

Errors

• Returns Error::InputBufferWrongSize if the length of the provided byte slice is not exactly equal to BYTES.
• Returns Error::AllZeroNotAllowed if the provided byte slice contains only zeros.

pub fn expose_secret(&self) -> &[u8; BYTES]

Access the secret key bytes.

This method is named expose_secret instead of a more generic as_array to make it easier to grep for in a large codebase.

Trait Implementations

impl<const BYTES: usize> Debug for Key<BYTES>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const BYTES: usize> Drop for Key<BYTES>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.