Module orion::kdf

Key derivation.

Use case:

orion::kdf can be used to derive higher-entropy keys from low-entropy keys. Also known as key stretching.

An example of this could be deriving a key from a user-submitted password and using this derived key in disk encryption. The disk encryption software VeraCrypt uses PBKDF2-HMAC-SHA512 to derive header keys, which in turn are used to encrypt/decrypt the master keys responsible for encrypting the data in a VeraCrypt volume.

About:

• Uses PBKDF2-HMAC-SHA512.

Parameters:

• password: The low-entropy input key to be used in key derivation.
• expected: The expected derived key.
• salt: The salt used for the key derivation.
• iterations: The number of iterations performed by PBKDF2, i.e. the cost parameter.
• length: The desired length of the derived key.

Errors:

An error will be returned if:

• iterations is 0.
• length is 0.
• length is not less than u32::max_value().
• The expected does not match the derived key.

Security:

• The iteration count should be set as high as feasible. The recommended minimum is 100000.
• The salt should always be generated using a CSPRNG. Salt::default() can be used for this, it will generate a Salt of 64 bytes.

Example:

use orion::kdf;

let user_password = kdf::Password::from_slice(b"User password")?;
let salt = kdf::Salt::default();

let derived_key = kdf::derive_key(&user_password, &salt, 100000, 64)?;

assert!(kdf::derive_key_verify(
	&derived_key,
	&user_password,
	&salt,
	100000
)?);

Structs

Password	A type to represent the Password that PBKDF2 hashes and uses for key derivation.
Salt	A type to represent the Salt that PBKDF2 uses during key derivation.
SecretKey	A type to represent a secret key.

Functions

derive_key	Derive a key using PBKDF2-HMAC-SHA512.
derive_key_verify	Derive and verify a key using PBKDF2-HMAC-SHA512.