[−][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. 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 thanu32::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 aSalt
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 |
Salt | A type to represent the |
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. |