Module kdf

Available on crate feature dep_orion only.

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.
• 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 is greater than isize::MAX.
• The length of the salt is greater than isize::MAX or less than 8.

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.

If the concrete cost parameters needed are unclear, please refer to OWASP for recommended minimum values.

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)?;

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.