hash_hkdf

Generate a HKDF key derivation of a supplied key input

&reftitle.description; `string` `hash_hkdf` `string` `algo` #[\SensitiveParameter]`string` `key` `int` `length` 0 `string` `info`"" `string` `salt`""
&reftitle.parameters;

`algo`

- Name of selected hashing algorithm (e.g. `"sha256"`). For a list of supported algorithms see `hash_hmac_algos`.

  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.

&reftitle.returnvalues;

Returns a string containing a raw binary representation of the derived key (also known as output keying material - OKM).

&reftitle.errors;

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).

&reftitle.changelog;

&Version; | &Description;
8.0.0 | Now throws a `ValueError` exception on error. Previously, &false; was returned and an `E_WARNING` message was emitted.

&reftitle.examples;

### `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)
    ?>

The above example 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.

&reftitle.seealso;

- `hash_pbkdf2`
- RFC 5869
- userland implementation