[−][src]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
orexpected
is greater thanu32::max_value()
. - The length of the
salt
is greater thanu32::max_value()
or less than8
. - 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 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)?; assert!(kdf::derive_key_verify(&derived_key, &user_password, &salt, 3, 1<<16).is_ok());
Structs
Password | A type to represent the |
Salt | A type to represent the |
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. |