Module password_protected_key_envelope 

Password protected key envelope is a cryptographic building block that allows sealing a symmetric key with a low entropy secret (password, PIN, etc.).

It is implemented by using a KDF combined with secret key encryption. The KDF prevents brute-force by requiring work to be done to derive the key from the password. The algorithms depend on the key store’s CipherSuite: the standard suite uses Argon2id + AES-256-GCM, while the FIPS suite uses the FIPS-approved PBKDF2 + AES-256-GCM.

For the consumer, the output is an opaque blob that can be later unsealed with the same password. The KDF parameters and salt are contained in the envelope, and don’t need to be provided for unsealing.

Internally, the envelope is a CoseEncrypt object. The KDF parameters / salt are placed in the single recipient’s unprotected headers. The output from the KDF - “envelope key”, is used to wrap the symmetric key, that is sealed by the envelope.

Structs

Argon2RawSettings 🔒

Raw argon2 settings differ from the crate::keys::Kdf::Argon2id struct defined for existing master-password unlock. The memory is represented in kibibytes (KiB) instead of mebibytes (MiB), and the salt is a fixed size of 32 bytes, and randomly generated, instead of being derived from the email.

PasswordProtectedKeyEnvelope

A password-protected key envelope can seal a symmetric key, and protect it with a password. It does so by using a Key Derivation Function (KDF), to increase the difficulty of brute-forcing the password.

Pbkdf2RawSettings 🔒

Raw PBKDF2-HMAC-SHA256 settings for FIPS envelopes. Like Argon2RawSettings, the salt is a fixed size and randomly generated, and lives in the envelope alongside the iteration count.

Enums

EnvelopeKdf 🔒

The KDF used to derive the envelope key from the password. The variant, and thus the algorithm, is selected from the key store’s CipherSuite at seal time and recorded in the envelope’s recipient so unsealing can dispatch on it.

PasswordProtectedKeyEnvelopeError

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

PasswordProtectedKeyEnvelopeNamespace

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

Constants

ENVELOPE_ARGON2_OUTPUT_KEY_SIZE 🔒

32 is chosen to match the size of an XChaCha20-Poly1305 key

ENVELOPE_ARGON2_SALT_SIZE 🔒

16 is the RECOMMENDED salt size for all applications: https://datatracker.ietf.org/doc/rfc9106/

ENVELOPE_PBKDF2_ITERATIONS 🔒

Default PBKDF2-HMAC-SHA256 iteration count for FIPS envelopes

ENVELOPE_PBKDF2_SALT_SIZE 🔒

Functions

derive_argon2_key 🔒

derive_key 🔒

Derives the envelope key from the password using the configured KDF.

derive_pbkdf2_key 🔒

suite_kdf 🔒

Returns the KDF settings for the given cipher suite.