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 thanisize::MAX
. - The length of the
salt
is greater thanisize::MAX
or less than8
.
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 aSalt
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)?;
Structs
A type to represent the
Password
that Argon2i hashes and uses for key derivation.A type to represent the
Salt
that Argon2i uses during key derivation.A type to represent a secret key.
Functions
Derive a key using Argon2i.