Module orion::kdf

source ·
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. 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.

Exceptions:

An exception will be thrown if:

  • iterations is 0.
  • length is 0.
  • length is not less than u32::max_value().
  • The OsRng fails to initialize or read from its source.
  • 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").unwrap();
let salt = kdf::Salt::default();

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

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

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.