hash_hkdf
Generate a HKDF key derivation of a supplied key input
Description
string hash_hkdf(
string $algo,
#[\SensitiveParameter]string $key,
int $length = 0,
string $info = "",
string $salt = ""
)
Parameters
-
algo
-
Name of selected hashing algorithm (e.g. "sha256").
For a list of supported algorithms see hash_hmac_algos.
Note:
Non-cryptographic hash functions are not allowed.
-
key
-
Input keying material (raw binary). Cannot be empty.
-
length
-
Desired output length in bytes.
Cannot be greater than 255 times the chosen hash function size.
If length is 0, the output length
will default to the chosen hash function size.
-
info
-
Application/context-specific info string.
-
salt
-
Salt to use during derivation.
While optional, adding random salt significantly improves the strength of HKDF.
Return Values
Returns a string containing a raw binary representation of the derived key
(also known as output keying material - OKM).
Errors/Exceptions
Throws a ValueError exception if key
is empty, algo is unknown/non-cryptographic,
length is less than 0 or too large
(greater than 255 times the size of the hash function).
Examples
The example below produces a pair of separate keys, suitable for creation
of an encrypt-then-HMAC construct, using AES-256 and SHA-256 for encryption
and authentication respectively.
Example #1 hash_hkdf example
<?php
// Generate a random key, and salt to strengthen it during derivation.
$inputKey = random_bytes(32);
$salt = random_bytes(16);
// Derive a pair of separate keys, using the same input created above.
$encryptionKey = hash_hkdf('sha256', $inputKey, 32, 'aes-256-encryption', $salt);
$authenticationKey = hash_hkdf('sha256', $inputKey, 32, 'sha-256-authentication', $salt);
var_dump($encryptionKey !== $authenticationKey); // bool(true)
?>