NAME¶

derive-key - (encryption)

PURPOSE¶

Derive a key.

SYNTAX¶

derive-key <key> from <source> length <length> \


    [ binary [ <binary> ] ] \


    [ from-length <source length> ] \


    [ digest <digest algorithm> ] \


    [ salt <salt> [ salt-length <salt length> ] ] \


    [ iterations <iterations> ] 

DESCRIPTION¶

derive-key derives <key> from string <source> in "from" clause. If <source length> in "from-length" clause is specified, exactly <source length> bytes of <source> are used. Otherwise, the length of <source> string is used as the number of bytes (see string-length).

The desired length of derived key is given by <length> in "length" clause. The method for key generation is PBKDF2. By default the digest used is "SHA256". You can use a different <digest algorithm> in "digest" clause (for example "SHA3-256"). To see a list of available digests:

#get digests
openssl list -digest-algorithms

The salt for key derivation can be given with <salt> in "salt" clause. If "salt-length" clause is not specified, then the entire length of salt is used (see string-length), otherwise <salt length> bytes are used as salt.

The number of iterations is given by <iterations> in "iterations" clause. The default is 1000 per RFC 8018, though depending on your needs and the quality of <source> you may choose a different value.

By default, the derived key is produced in a hexadecimal form, where each byte is encoded as two-character hexadecimal characters, so its length is 2*<length>. If "binary" clause is used without boolean variable <binary>, or if <binary> evaluates to true, then the output is a binary string of <length> bytes.

Key derivation is often used when storing password-derivatives in the database (with salt), and also for symmetrical key generation.

EXAMPLES¶

Derived key is in variable "mk":

random-string to rs9 length 16
derive-key mk from "clave secreta" digest "sha-256" salt rs9 salt-length 10 iterations 2000 length 16

SEE ALSO¶

Encryption

decrypt-data derive-key encrypt-data hash-string hmac-string random-crypto random-string See all documentation