NAME
SYNOPSIS
DESCRIPTION
STRING CTRLS
NOTES
RETURN VALUES
EXAMPLES
CONFORMING TO
SEE ALSO
COPYRIGHT

NAME

EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt, EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info, EVP_PKEY_CTX_hkdf_mode - HMAC-based Extract-and-Expand key derivation algorithm

SYNOPSIS

 #include <openssl/kdf.h>
 
 int EVP_PKEY_CTX_hkdf_mode(EVP_PKEY_CTX *pctx, int mode);
 
 int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
 
 int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt,
                                 int saltlen);
 
 int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key,
                                int keylen);
 
 int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info,
                                 int infolen);

DESCRIPTION

The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function. HKDF follows the "extract-then-expand" paradigm, where the KDF logically consists of two modules. The first stage takes the input keying material and "extracts" from it a fixed-length pseudorandom key K. The second stage "expands" the key K into several additional pseudorandom keys (the output of the KDF).

EVP_PKEY_CTX_hkdf_mode() sets the mode for the HKDF operation. There are three modes that are currently defined:

EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND

This is the default mode. Calling EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY

In this mode calling EVP_PKEY_HKDEF_MODE_EXPAND_ONLY

In this mode calling STRING CTRLS

HKDF also supports string based control operations via NOTES

All these functions are implemented as macros.

A context for HKDF can be obtained by calling:

 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);

The total length of the info buffer cannot exceed 1024 bytes in length: this should be more than enough for any normal use of HKDF.

The output length of an HKDF expand operation is specified via the length parameter to the EVP_PKEY_derive(3) along with (a pointer initialized to) the desired length. Passing a NULL buffer to obtain the length is allowed when using EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY.

Optimised versions of HKDF can be implemented in an ENGINE.

RETURN VALUES

All these functions return 1 for success and 0 or a negative value for failure. In particular a return value of -2 indicates the operation is not supported by the public key algorithm.

EXAMPLES

This example derives 10 bytes using SHA-256 with the secret key "secret", salt value "salt" and info value "label":

 EVP_PKEY_CTX *pctx;
 unsigned char out[10];
 size_t outlen = sizeof(out);
 pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL);
 
 if (EVP_PKEY_derive_init(pctx) <= 0)
     /* Error */
 if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0)
     /* Error */
 if (EVP_PKEY_CTX_set1_hkdf_salt(pctx, "salt", 4) <= 0)
     /* Error */
 if (EVP_PKEY_CTX_set1_hkdf_key(pctx, "secret", 6) <= 0)
     /* Error */
 if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 5) <= 0)
     /* Error */
 if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
     /* Error */

CONFORMING TO

RFC 5869

OpenSSL.vip