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. 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 KeyMaterialTrait::set_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 run inside of a do_hazardous_operations closure, see below.

🚨 Security 🚨

Additional security features:

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

Hazardous Operations

This object allows several types of manual-overrides, many of which are considered “hazardous operations” since by definition they are allowing you to bypass checks meant to detect conditions that could lead to security vulnerabilities. Consider, for example, that you are reading a symmetric key from somewhere outside the library, maybe from disk or from another process, but maybe you handed in the wrong variable and instead handed in an uninitialized (all-zero) buffer. Since this is a common bug that has catestrophic security implications, the library will normally check for all-zero KeyMoterial objects and throw an error. But there will be cases in which you really do need to use an all-zero key, so you can create one if you do it in hazardous operations mode.

Examples of hazardous conversions that are required to be run inside of a do_hazardous_operations() closure:

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

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.

See do_hazardous_operations for documentation and sample code.

Structs

KeyMaterial

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

KeyMaterialTrait

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

Functions

do_hazardous_operations

Runs the provided closure within which hazardous operations are allowed. All hazardous operations will return a KeyMaterialError::HazardousOperationNotPermitted if used outside of this closure.

Type Aliases

KeyMaterial0

For when it is necessary to get a zero-length dummy key (an empty HMAC salt, for example).

KeyMaterial128

Named type for a 128-bit (16-byte) key, for convenience.

KeyMaterial256

Named type for a 256-bit (32-byte) key, for convenience.

KeyMaterial512

Named type for a 512-bit (64-byte) key, for convenience.