Trait KeyMaterial 

pub trait KeyMaterial {
    // Required methods
    fn set_bytes_as_type(
        &mut self,
        source: &[u8],
        key_type: KeyType,
    ) -> Result<(), KeyMaterialError>;
    fn ref_to_bytes(&self) -> &[u8] ;
    fn mut_ref_to_bytes(&mut self) -> Result<&mut [u8], KeyMaterialError>;
    fn capacity(&self) -> usize;
    fn key_len(&self) -> usize;
    fn set_key_len(&mut self, key_len: usize) -> Result<(), KeyMaterialError>;
    fn key_type(&self) -> KeyType;
    fn set_key_type(
        &mut self,
        key_type: KeyType,
    ) -> Result<(), KeyMaterialError>;
    fn security_strength(&self) -> SecurityStrength;
    fn set_security_strength(
        &mut self,
        strength: SecurityStrength,
    ) -> Result<(), KeyMaterialError>;
    fn allow_hazardous_operations(&mut self);
    fn drop_hazardous_operations(&mut self);
    fn convert_key_type(
        &mut self,
        new_key_type: KeyType,
    ) -> Result<(), KeyMaterialError>;
    fn is_full_entropy(&self) -> bool;
    fn zeroize(&mut self);
    fn truncate(&mut self, new_len: usize) -> Result<(), KeyMaterialError>;
    fn concatenate(
        &mut self,
        other: &dyn KeyMaterial,
    ) -> Result<usize, KeyMaterialError>;
    fn equals(&self, other: &dyn KeyMaterial) -> bool;
}

A helper class used across the bc-rust.test library to hold bytes-like key material. See KeyMaterialInternal for for details, such as constructors.

Required Methods

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. It will detect if you give it all-zero source data and set the key type to KeyType::Zeroized instead. Since this zeroizes and resets the key material, this is considered a dangerous conversion.

The only hazardous operation here that requires setting KeyMaterial::allow_hazardous_operations is giving it an all-zero key, which is checked as a courtesy to catch mistakes of feeding an initialized buffer instead of an actual key. See the note on KeyMaterialInternal::set_bytes_as_type for suggestions for handling this.

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

Get a reference to the underlying key material bytes.

By reading the key bytes out of the KeyMaterial object, you lose the protections that it offers, however, this does not require KeyMaterial::allow_hazardous_operations in the name of API ergonomics: setting KeyMaterial::allow_hazardous_operations requires a mutable reference and reading the bytes is not an operation that should require mutability.

fn mut_ref_to_bytes(&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. This requires KeyMaterial::allow_hazardous_operations to be set. When writing directly to the buffer, you are responsible for setting the key_len and key_type afterwards, and you should KeyMaterial::drop_hazardous_operations.

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>

Requires KeyMaterial::allow_hazardous_operations.

fn key_type(&self) -> KeyType

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

Requires KeyMaterial::allow_hazardous_operations.

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.

The idea is to be able to track for cryptographic seeds and bytes-like key objects across the entire library, the instatiated security level of the RNG that generated it, and whether it was handled by any intermediate objects, such as Key Derivation Functions, that have a smaller internal security level and therefore result in downgrading the security level of the key material.

Note that while security strength is closely related to entropy, it is a property of the algorithms that touched the key material and not of the key material data itself, and therefore it is tracked independantly from key length and entropy level / key type.

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

Requires KeyMaterial::allow_hazardous_operations to raise the security strength, but not to lower it. Throws KeyMaterialError::HazardousOperationNotPermitted on a request to raise the security level without KeyMaterial::allow_hazardous_operations set. Throws KeyMaterialError::InvalidLength on a request to set the security level higher than the current key length.

fn allow_hazardous_operations(&mut self)

Sets this instance to be able to perform potentially hazardous conversions such as casting a KeyMaterial of type RawUnknownEntropy or RawLowEntropy into RawFullEntropy or SymmetricCipherKey, or manually setting the key bytes via KeyMaterial::mut_ref_to_bytes, which then requires you to be responsible for setting the key_len and key_type afterwards.

The purpose of the hazardous_conversions guard is not to prevent the user from accessing their data, but rather to make the developer think carefully about the operation they are about to perform, and to give static analysis tools an obvious marker that a given KeyMaterial variable warrants further inspection.

fn drop_hazardous_operations(&mut self)

Resets this instance to not be able to perform potentially hazardous conversions.

fn convert_key_type( &mut self, new_key_type: KeyType, ) -> Result<(), KeyMaterialError>

Sets the key_type of this KeyMaterial object. Does not perform any operations on the actual key material, other than changing the key_type field. If allow_hazardous_operations is true, this method will allow conversion to any KeyType, otherwise checking is performed to ensure that the conversion is “safe”. This drops the allow_hazardous_operations flag, so if you need to do multiple hazardous conversions on the same instance, then you’ll need to call .allow_hazardous_operations() each time.

fn is_full_entropy(&self) -> bool

fn zeroize(&mut self)

fn truncate(&mut self, new_len: usize) -> Result<(), KeyMaterialError>

Is simply an alias to KeyMaterial::set_key_len, however, this does not require KeyMaterial::allow_hazardous_operations since truncation is a safe operation. If truncating below the current security strength, the security strength will be lowered accordingly.

fn concatenate( &mut self, other: &dyn KeyMaterial, ) -> Result<usize, KeyMaterialError>

Adds the other KeyMaterial into this one, assuming there is space. Does not require KeyMaterial::allow_hazardous_operations. Throws KeyMaterialError::InvalidLength if this object does not have enough space to add the other one. The resulting KeyType and security strength will be the lesser of the two keys. In other words, concatenating two 128-bit full entropy keys generated at a 128-bit DRBG security level will result in a 256-bit full entropy key still at the 128-bit DRBG security level. Concatenating a full entropy key with a low entropy key will result in a low entropy key.

Returns the new key_len.

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

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

Implementors

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