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.

About:

• Uses Argon2i.

Note:

This implementation only supports a single thread/lane.

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: Iterations cost parameter for Argon2i.
• memory: Memory (in kibibytes (KiB)) cost parameter for Argon2i.
• length: The desired length of the derived key.

Errors:

An error will be returned if:

• iterations is less than 3.
• length is less than 4.
• memory is less than 8.
• The length of the password or expected is greater than u32::max_value().
• The length of the salt is greater than u32::max_value() or less than 8.
• The expected does not match the derived key.

Security:

• Choosing the correct cost parameters is important for security. Please refer to libsodium's docs for a description of how to do this.
• The salt should always be generated using a CSPRNG. Salt::default() can be used for this, it will generate a Salt of 16 bytes.
• The recommended minimum size for a salt is 16 bytes.
• The recommended minimum size for a derived key is 16 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, 3, 1<<16, 32)?;

assert!(kdf::derive_key_verify(&derived_key, &user_password, &salt, 3, 1<<16).is_ok());

Structs

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

Functions

derive_key	Derive a key using Argon2i.
derive_key_verify	Derive and verify a key using Argon2i.