GenerateDerivedKey
GenerateDerivedKey[password]
generates a DerivedKey object from the password given.
GenerateDerivedKey[password,salt]
generates a DerivedKey object from the password and salt given.
Details and Options
- GenerateDerivedKey uses a computation-intensive key derivation function to generate a cryptographically strong key hash.
- password and salt can be strings, lists of integers representing byte values or ByteArray objects.
- GenerateDerivedKey[password] is equivalent to GenerateDerivedKey[password,Automatic]. If salt is not provided, it is randomly generated.
- GenerateDerivedKey takes a Method option, which uses an Association to specify a key derivation function and parameters.
- Typical settings for Method include:
-
"Function" key derivation function "FunctionParameters" key derivation function parameters - Supported key derivation functions are: "scrypt", "Argon2d", "Argon2i", "Argon2id".
- Function parameters for the "scrypt" key derivation function are an Association, which includes:
-
"KeySize" 64 desired key length in bytes "N" 2^15 computational cost factor "r" 8 block size factor "p" 1 parallelization factor - The value of "N" must be an integer power of 2 greater than 1.
- Function parameters for the "Argon2x" key derivation functions are an Association, which includes:
-
"KeySize" 64 desired key length in bytes "t" 2 number of iterations "m" 2^16 memory size to use in kibibytes "p" 1 parallelization factor - The value of "m" must be an integer power of 2.
- To generate a cryptographically secure key, parameters of the key derivation function are usually adjusted for the computation on a specific computer to take just below a fraction of a second.
Examples
open all close allBasic Examples (2)
Scope (8)
Generate a derived key using a list of integers as a password:
GenerateDerivedKey[{1, 2, 3}]Generate a derived key using ByteArray as a password:
GenerateDerivedKey[ByteArray[{1, 2, 3}]]Generate a derived key using a list of integers as a salt:
GenerateDerivedKey["password", {1, 2, 3}]Customize the parameters for the default "scrypt" method:
GenerateDerivedKey["password", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 16, "r" -> 1, "p" -> 1|>|>]Use an alternate key derivation function to generate a derived key:
GenerateDerivedKey["password", "somesalt", Method -> <|"Function" -> "Argon2i"|>]Specify a key derivation function and parameters:
GenerateDerivedKey["password", "somesalt", Method -> <|"Function" -> "Argon2d", "FunctionParameters" -> <|"KeySize" -> 32, "t" -> 2, "m" -> 2 ^ 16, "p" -> 1|>|>]Generate string representation of DerivedKey:
key = GenerateDerivedKey["password"];
key["PHCString"]Reconstruct the key from its string representation using DerivedKey:
DerivedKey[%]The new key is identical to the original:
% === keyGenerate a ByteArray from the password:
DerivedKey[Association["Function" -> "scrypt",
"DerivedKey" -> ByteArray[
"IpvdeaIaDUgAKgZeZxD1uIEzLD62zFMmCiJceu3Sg5F10vJmlzc84E6ZXBdbecisZ19zOXg/+4179PA7Zd8+GQ=="],
"Salt" -> ByteArray["vSmisIaQxauR5nR2n0j8hVEgg6AxbxVHnuyTfC2zrAo="],
"FunctionParameters" -> Association["KeySize" -> 64, "N" -> 32768, "r" -> 8, "p" -> 1]]]["DerivedKey"]Options (2)
Method (2)
If only the key "FunctionParameters" is specified, it customizes the default method "scrypt":
GenerateDerivedKey["password", "somesalt", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 16, "r" -> 1, "p" -> 1|>|>]Use the alternate key derivation function "Argon2id" with default parameters:
GenerateDerivedKey["password", Method -> <|"Function" -> "Argon2id"|>]Specify the parameters as well:
GenerateDerivedKey["password", Method -> <|"Function" -> "Argon2id", "FunctionParameters" -> <|"KeySize" -> 32, "t" -> 2, "m" -> 2 ^ 16, "p" -> 1|>|>]Applications (3)
Generate cryptographically strong password hash from a simple password string:
GenerateDerivedKey["Apple1"]["PHCString"]key = GenerateDerivedKey["Apple1"]VerifyDerivedKey[key, "Apple1"]Verify the password using derived key in the string representation:
key = GenerateDerivedKey["Apple1"]["PHCString"]VerifyDerivedKey[key, "Apple1"]Properties & Relations (3)
DerivedKey is generated deterministically from the given the same password and salt:
GenerateDerivedKey["password", "salt"] === GenerateDerivedKey["password", "salt"]This also applies to generating keys from their string representation:
key = GenerateDerivedKey["pass", "salt", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 16, "r" -> 1, "p" -> 1|>|>];
key === DerivedKey[key["PHCString"]]Computation time increases linearly with "r" in "scrypt":
Grid[Table[{r, First[
AbsoluteTiming[GenerateDerivedKey["password", "salt", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 2 ^ 16, "r" -> r, "p" -> 1|>|>]]]},
{r, {2, 10, 30, 50, 90}}], Alignment -> Left, Dividers -> All]It increases linearly in "p" as well:
Grid[Table[{p, First[
AbsoluteTiming[GenerateDerivedKey["password", "salt", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 2 ^ 16, "r" -> 2, "p" -> p|>|>]]]}, {p, {2, 10, 30, 50, 70}}], Alignment -> Left, Dividers -> All]Generate SymmetricKey from DerivedKey:
key = GenerateDerivedKey["pass"]GenerateSymmetricKey[key]Possible Issues (4)
For certain parameters, generation of derived key may take significant time:
AbsoluteTiming[GenerateDerivedKey["password", "salt", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 2 ^ 16, "r" -> 100, "p" -> 1|>|>];]AbsoluteTiming[GenerateDerivedKey["password", "salt", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 2 ^ 16, "r" -> 200, "p" -> 1|>|>];]Parameters of key derivation function must be machine-size integers:
GenerateDerivedKey["password", "salt", Method -> <|"FunctionParameters" -> <|"KeySize" -> 64, "N" -> 2 ^ 64, "r" -> 2, "p" -> 1|>|>]
Some key derivation functions have restrictions on password and salt sizes:
GenerateDerivedKey["password", "salt", Method -> <|"Function" -> "Argon2i"|>]
GenerateDerivedKey["password", "moresalt", Method -> <|"Function" -> "Argon2i"|>]When creating a symmetric key, random data taken from a derived key may be truncated to fit the new key size:
derived = GenerateDerivedKey["pass"]symmetric = GenerateSymmetricKey[derived]derived["KeySize"]
symmetric["KeySize"]In order to generate a derived key of the desired size, the key size must be specified explicitly:
derived = GenerateDerivedKey["pass", Method -> <|"FunctionParameters" -> <|"KeySize" -> 32|>|>];
derived["KeySize"]Text
Wolfram Research (2019), GenerateDerivedKey, Wolfram Language function, https://reference.wolfram.com/language/ref/GenerateDerivedKey.html (updated 2020).
CMS
Wolfram Language. 2019. "GenerateDerivedKey." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2020. https://reference.wolfram.com/language/ref/GenerateDerivedKey.html.
APA
Wolfram Language. (2019). GenerateDerivedKey. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/GenerateDerivedKey.html