Module key_material 

A helper class used across the bc-rust library to hold bytes-like key material. The main purpose is to hold metadata about the contained key material such as the key type and entropy content to prevent accidental misuse security bugs, such as deriving cryptographic keys from uninitialized data.

This object allows several types of manual-overrides, which typically require setting the KeyMaterialInternal::allow_hazardous_operations flag. For example, the raw bytes data can be extracted, or the key forced to a certain type, but well-designed use of the bc-rust.test library should not need to ever set the KeyMaterialInternal::allow_hazardous_operations flag. The core idea of this wrapper is to keep track of the usage of the key material, including the amount of entropy that it is presumed to contain in order to prevent users from accidentally using it inappropriately in a way that could lead to security weaknesses.

Various operations within the bc-rs library will consume or produce KeyMaterial objects with specific key types. In normal use of the bc-rs APIs, users should never have to manually convert the type of a KeyMaterial object because the various function calls will set the key type appropriately.

Some typical workflows would be:

• Hash functions take in [u8] byte data and return a KeyMaterial of type RawUnknownEntropy.
• Password-based key derivation functions act on KeyMaterial of any type, and in the case of RawFullEntropy, RawLowEntropy, or RawUnknownEntropy, will preserve the entropy rating.
• Keyed KDFs that are given a key of RawFullEntropy or KeyedHashKey a KeyMaterial data of type RawLowEntropy or RawUnknownEntropy will promote it into RawFullEntropy.
• Symmetric ciphers or asymmetric ciphers such as X25519 or ML-KEM that accept private key seeds will expect KeyMaterial of type AsymmetricPrivateKeySeed.

However, there is a KeyMaterialInternal::convert_key_type for cases where the user has more context knowledge than the library. Some conversions, such as converting a key of type RawLowEntropy into a SymmetricCipherKey, will fail unless the user has explicitly allowed them via calling allow_hazardous_operations() prior to the conversion.

Examples of hazardous conversions that require allow_hazardous_operations() to be called first:

• Converting a KeyMaterial of type RawLowEntropy or RawUnknownEntropy into RawFullEntropy or any other full-entropy key type.
• Converting any algorithm-specific key type into a different algorithm-specific key type, which is considered hazardous since key reuse between different cryptographic algorithms is generally discouraged and can sometimes lead to key leakage.

Additional security features:

• Zeroizes on destruction.
• Implementing Display and Debug to print metadata but not key material to prevent accidental logging.

As with all wrappers of this nature, the intent is to protect the user from making silly mistakes, not to prevent expert users from doing what they need to do. It as always possible, for example, to extract the bytes from a KeyMaterial object, manipulate them, and then re-wrap them in a new KeyMaterial object.

Structs

KeyMaterialInternal

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.

Enums

KeyType

Traits

KeyMaterial

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

Type Aliases

KeyMaterial0

Sometimes you just need a zero-length dummy key.

KeyMaterial128

KeyMaterial256

KeyMaterial512