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 (Argon2ID) combined with secret key encryption (XChaCha20-Poly1305). The KDF prevents brute-force by requiring work to be done to derive the key from the password.

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.

Enums

PasswordProtectedKeyEnvelopeError

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

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/

Functions

derive_key 🔒

make_salt 🔒