Module secret_protected_key_envelope 

Secret protected key envelope is a cryptographic building block that allows sealing a symmetric key with a high-entropy secret (a random URL-fragment secret, a derived key, random bytes, etc.) of arbitrary length.

It is implemented by using a cheap KDF (HKDF-SHA256) combined with symmetric key encryption (AES-256-GCM). Unlike the crate::safe::PasswordProtectedKeyEnvelope, which protects a low-entropy secret (password, PIN) and therefore uses a hard KDF (Argon2ID, PBKDF2) to slow down brute-forcing, this envelope assumes the secret is high-entropy and not brute-forceable, so a cheap KDF is sufficient. The cheap KDF also natively accepts input material of arbitrary length.

For the consumer, the output is an opaque blob that can be later unsealed with the same secret. The KDF salt is contained in the envelope, and does not need to be provided for unsealing.

Internally, the envelope is a CoseEncrypt object that uses the standardized COSE “Direct Key with KDF” construction with the direct+HKDF-SHA-256 recipient algorithm, as described in RFC 9053 §6.1.2. The random HKDF salt is placed in the single recipient’s unprotected headers (the standardized salt header parameter), and the secret is used as the input keying material. The output from the KDF - “envelope key”, is used directly as the content-encryption key that wraps the symmetric key sealed by the envelope.

Note: AES-GCM is used here since the CEK is locally derived, so there is no nonce re-use problem.

Structs

HkdfSettings 🔒

Raw HKDF settings. The salt is a fixed size, randomly generated value. Unlike a memory-hard KDF, HKDF has no difficulty parameters to tune, since the input secret is assumed to be high-entropy.

SecretProtectedKeyEnvelope

A secret-protected key envelope can seal a symmetric key, and protect it with a high-entropy secret of arbitrary length.

Enums

SecretProtectedKeyEnvelopeError

Errors that can occur when sealing or unsealing a key with the SecretProtectedKeyEnvelope.

SecretProtectedKeyEnvelopeNamespace

The content-layer separation namespace for secret protected key envelopes.

Constants

ENVELOPE_HKDF_OUTPUT_KEY_SIZE 🔒

32 is chosen to match the size of an AES-256-GCM key

ENVELOPE_HKDF_SALT_SIZE 🔒

32 matches the SHA-256 output size (HashLen), which is the RECOMMENDED salt size for HKDF: https://datatracker.ietf.org/doc/html/rfc5869

HKDF_ALGORITHM 🔒

The recipient algorithm used by the envelope: direct+HKDF-SHA-256 (https://datatracker.ietf.org/doc/html/rfc9053#name-direct-key-with-kdf).

HKDF_SALT_LABEL 🔒

The standardized COSE salt header algorithm parameter label (-20).

Functions

content_encryption_algorithm 🔒

Reads the content-encryption algorithm declared in the protected header. This value is used as the AlgorithmID of the COSE_KDF_Context, binding the derived key to the message’s declared algorithm (RFC 9053 §6.1.2).

derive_cek 🔒

kdf_context_info 🔒

Builds the serialized COSE_KDF_Context used as the HKDF info parameter, as required by the COSE “Direct Key with KDF” construction (https://datatracker.ietf.org/doc/html/rfc9053#name-context-information-structu):

make_salt 🔒