({{, (RefLink[GenerateDerivedKey, paclet:ref/GenerateDerivedKey])[password] 
generates a (RefLink[DerivedKey, paclet:ref/DerivedKey]) object from the password given.}, {, (RefLink[GenerateDerivedKey, paclet:ref/GenerateDerivedKey])[password,salt]
generates a (RefLink[DerivedKey, paclet:ref/DerivedKey]) object from the password and salt given.}})

OpenersNotesSection(Spacer1)Details and Options

(RefLink[GenerateDerivedKey, paclet:ref/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 (RefLink[ByteArray, paclet:ref/ByteArray]) objects.

(RefLink[GenerateDerivedKey, paclet:ref/GenerateDerivedKey])[password] is equivalent to (RefLink[GenerateDerivedKey, paclet:ref/GenerateDerivedKey])[password,(RefLink[Automatic, paclet:ref/Automatic])]. If salt is not provided, it is randomly generated.

(RefLink[GenerateDerivedKey, paclet:ref/GenerateDerivedKey]) takes a (RefLink[Method, paclet:ref/Method]) option, which uses an (RefLink[Association, paclet:ref/Association]) to specify a key derivation function and parameters.

Typical settings for (RefLink[Method, paclet:ref/Method]) include:

Supported key derivation functions are: "scrypt", "Argon2d", "Argon2i", "Argon2id".

Parameters for the "scrypt" key derivation function are an (RefLink[Association, paclet:ref/Association]), which includes:

The value of "N" must be an integer power of 2 greater than 1.

Parameters for the "Argon2" key derivation functions are an (RefLink[Association, paclet:ref/Association]), which includes:

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.

OpenersPrimaryExamplesSection(Spacer1)Examples  (23)

OpenersExampleSection0(Spacer1)Basic Examples  (13)

Generate derived key:

GenerateDerivedKey["password"]

Generate derived key using password and salt:

GenerateDerivedKey["password","salt"]

Generate derived key using a list of integers as a password:

GenerateDerivedKey[{1,2,3}]

Generate derived key using (RefLink[ByteArray, paclet:ref/ByteArray]) as a password:

GenerateDerivedKey[ByteArray[{1,2,3}]]

Generate derived key using a list of integers as a salt:

GenerateDerivedKey["password",{1,2,3}]

Generate a derived key using specified key derivation function:

GenerateDerivedKey["password","somesalt",Method-><|"Function"->"Argon2i"|>]

Specify a key derivation function:

GenerateDerivedKey["password","somesalt", Method-><|"Function"->"Argon2d"|>]

Generate derived key using "scrypt" and specified parameters:

GenerateDerivedKey["password",Method-><|"Parameters"-><|"KeySize"->64,"N"->16,"r"->1,"p"->1|>|>]

Generate derived key with specific parameters using password and salt:

GenerateDerivedKey["password","somesalt",Method-><|"Parameters"-><|"KeySize"->64,"N"->16,"r"->1,"p"->1|>|>]

Generate string representation of (RefLink[DerivedKey, paclet:ref/DerivedKey]):

GenerateDerivedKey["password"]["PHCString"]

key =GenerateDerivedKey["password","somesalt", Method-><|"Function"->"Argon2d","Parameters"-><|"KeySize"->32,"t"->2,"m"->2^16,"p"->1|>|>];
key["PHCString"]

Construct (RefLink[DerivedKey, paclet:ref/DerivedKey]) from its string representation:

DerivedKey["$argon2d$t=2,m=65536,p=1$c29tZXNhbHQ$lV5dWxY6G2C7o1/DbQSWR0+6T2tZrVNihmbwf7L5Pq8"]

Generate a (RefLink[ByteArray, paclet:ref/ByteArray]) from the password:

GenerateDerivedKey["Apple1"]["DerivedKey"]

Specify a key derivation function and parameters:

GenerateDerivedKey["password","somesalt", Method-><|"Function"->"Argon2d","Parameters"-><|"KeySize"->32,"t"->2,"m"->2^16,"p"->1|>|>]

OpenersExampleSection1(Spacer1)Scope  (1)

Computation time increases linearly with r and p in "scrypt":

Grid[Table[{r,First[
AbsoluteTiming[GenerateDerivedKey["password","salt",Method-><|"Parameters"-><|"KeySize"->64,"N"->2^16,"r"->r,"p"->1|>|>]]]},
{r,{1,10,30,50,90}}],Alignment->Left,Dividers->All]

Grid[Table[{p,First[
AbsoluteTiming[GenerateDerivedKey["password","salt",Method-><|"Parameters"-><|"KeySize"->64,"N"->2^16,"r"->1,"p"->p|>|>]]]},{p,{1,10,30,50,70}}],Alignment->Left,Dividers->All]

OpenersExampleSection3(Spacer1)Applications  (3)

Generate cryptographically strong password hash from a simple password string:

GenerateDerivedKey["Apple1"]["PHCString"]

Verify the password:

key=GenerateDerivedKey["Apple1"]

VerifyDerivedKey[key,"Apple1"]

Verify the password using derived key in the string representation:

key=GenerateDerivedKey["Apple1"]["PHCString"]

VerifyDerivedKey[key,"Apple1"]

OpenersExampleSection4(Spacer1)Properties & Relations  (3)

The same (RefLink[DerivedKey, paclet:ref/DerivedKey]) can be generated given the same password and salt:

GenerateDerivedKey["password","salt"]===GenerateDerivedKey["password","salt"]

Generate (RefLink[SymmetricKey, paclet:ref/SymmetricKey]) from (RefLink[DerivedKey, paclet:ref/DerivedKey]):

key = GenerateDerivedKey["pass"]

GenerateSymmetricKey[key]

Compare keys created by derivation function and obtained from string representation of derived key:

key=GenerateDerivedKey["pass","salt", Method-><|"Parameters"-><|"KeySize"->64,"N"->16,"r"->1,"p"->1|>|>]

key2=DerivedKey[key["PHCString"]]

key==key2

OpenersExampleSection5(Spacer1)Possible Issues  (3)

For certain parameters, generation of derived key may take significant time:

AbsoluteTiming[GenerateDerivedKey["password","salt",Method-><|"Parameters"-><|"KeySize"->64,"N"->2^16,"r"->100,"p"->1|>|>];]

AbsoluteTiming[GenerateDerivedKey["password","salt",Method-><|"Parameters"-><|"KeySize"->64,"N"->2^16,"r"->200,"p"->1|>|>];]

Parameters of key derivation function must be machine-size integers:

GenerateDerivedKey["password","salt",Method-><|"Parameters"-><|"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"|>]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[DerivedKey, paclet:ref/DerivedKey])  ▪  (RefLink[VerifyDerivedKey, paclet:ref/VerifyDerivedKey])  ▪  (RefLink[GenerateSymmetricKey, paclet:ref/GenerateSymmetricKey])  ▪  (RefLink[Hash, paclet:ref/Hash])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Cryptography, paclet:guide/Cryptography])}})}})