Module orion::kdf

source ·
Available on crate feature safe_api only.
Expand description

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