Struct KeyMaterial 

pub struct KeyMaterial<const KEY_LEN: usize> { /* private fields */ }

A wrapper for holding bytes-like key material (symmetric keys or seeds) which aims to apply a strict typing system to prevent many kinds of mis-use mistakes. The capacity of the internal buffer can be set at compile-time via the <KEY_LEN> param.

Implementations

impl<const KEY_LEN: usize> KeyMaterial<KEY_LEN>

pub fn new() -> Self

Creates a new empty instance (key_len = 0, key_type = Zeroized). If you want a properly populated instance, use KeyMaterial::from_rng.

pub fn from_rng(rng: &mut impl RNG) -> Result<Self, KeyMaterialError>

Creates a new instance of KeyMaterial containing random bytes from the provided random number generator.

pub fn from_bytes(source: &[u8]) -> Result<Self, KeyMaterialError>

Constructor. Loads the provided data into a new KeyMaterial of type KeyType::Unknown. It will detect if you give it all-zero source data and set the key type to KeyType::Zeroized instead.

pub fn from_bytes_as_type( source: &[u8], key_type: KeyType, ) -> Result<Self, KeyMaterialError>

Constructor. Loads the provided data into a new KeyMaterial of the specified type. This is discouraged unless the caller knows the provenance of the data, such as loading it from a cryptographic private key file. It will detect if you give it all-zero source data and set the key type to KeyType::Zeroized instead.

Will set the SecurityStrength automatically according to the following rules:

• If KeyType is KeyType::Zeroized or KeyType::Unknown then it will be SecurityStrength::None.
• Otherwise it will set it based on the length of the provided source bytes.

pub fn from_key(other: &impl KeyMaterialTrait) -> Result<Self, KeyMaterialError>

Copy constructor

Trait Implementations

impl<const KEY_LEN: usize> Clone for KeyMaterial<KEY_LEN>

fn clone(&self) -> KeyMaterial<KEY_LEN>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const KEY_LEN: usize> Debug for KeyMaterial<KEY_LEN>

Block accidental logging of the internal key material buffer.

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

Formats the value using the given formatter.

impl<const KEY_LEN: usize> Default for KeyMaterial<KEY_LEN>

fn default() -> Self

Create a new empty (zeroized) instance.

impl<const KEY_LEN: usize> Display for KeyMaterial<KEY_LEN>

Block accidental logging of the internal key material buffer.

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

Formats the value using the given formatter.

impl<const KEY_LEN: usize> KeyMaterialTrait for KeyMaterial<KEY_LEN>

fn set_bytes_as_type( &mut self, source: &[u8], key_type: KeyType, ) -> Result<(), KeyMaterialError>

Loads the provided data into a new KeyMaterial of the specified type. This is discouraged unless the caller knows the provenance of the data, such as loading it from a cryptographic private key file.

fn ref_to_bytes(&self) -> &[u8]

Get a reference to the underlying key material bytes.

fn ref_to_bytes_mut(&mut self) -> Result<&mut [u8], KeyMaterialError>

Get a mutable reference to the underlying key material bytes so that you can read or write to the underlying bytes without needing to create a temporary buffer, especially useful in cases where the required size of that buffer may be tricky to figure out at compile-time.

fn capacity(&self) -> usize

The size of the internal buffer; ie the largest key that this instance can hold. Equivalent to the <KEY_LEN> constant param this object was created with.

fn key_len(&self) -> usize

Length of the key material in bytes.

fn set_key_len(&mut self, key_len: usize) -> Result<(), KeyMaterialError>

Sets the internal key length without changing the capacity of the KeyMaterial. Primarily intended for truncation if you are provided with a key that is larger than you need, or to extend the length of an undersized KeyMaterial.

fn key_type(&self) -> KeyType

Returns the KeyType of this KeyMaterial object.

fn set_key_type(&mut self, key_type: KeyType) -> Result<(), KeyMaterialError>

Sets (or safely converts) the KeyType of this KeyMaterial object. Does not perform any operations on the actual key material, other than changing the key_type field.

fn security_strength(&self) -> SecurityStrength

Security Strength, as used here, aligns with NIST SP 800-90A guidance for random number generation, specifically section 8.4.

fn set_security_strength( &mut self, strength: SecurityStrength, ) -> Result<(), KeyMaterialError>

Set the SecurityStrength of the KeyMaterial.

fn is_full_entropy(&self) -> bool

Whether or not the KeyMaterial is one of the full entropy key types.

fn zeroize(&mut self)

Securely resets the contents to all zeroes. Note that KeyMaterial will automatically zeroize itself when dropped, so it is not necessary to call this method simply because the object is going out of scope, but it provided in case you want to zeroize it early, or before re-using the same instance of KeyMaterial to hold a different key, potentially of a different length.

fn equals(&self, other: &dyn KeyMaterialTrait) -> bool

Perform a constant-time comparison between the two key material buffers, ignoring differences in capacity, KeyType, SecurityStrength, etc.

fn truncate(self, into: &mut dyn KeyMaterialTrait)

Truncate this key material into the provided destination. Not an error to provide a destination which is larger than the source. Consumes self, use clone() if you intend to make a copy.

impl<const KEY_LEN: usize> PartialEq for KeyMaterial<KEY_LEN>

Checks for equality of the key data (using a constant-time comparison), but does not check that the two keys have the same type. Therefore, for example, two keys loaded from the same bytes, one with type KeyType::Unknown and the other with KeyType::MACKey will be considered equal.

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const KEY_LEN: usize> Eq for KeyMaterial<KEY_LEN>