1.\" $OpenBSD: EVP_PKEY_CTX_set_hkdf_md.3,v 1.4 2024/07/10 07:57:37 tb Exp $ 2.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 3.\" 4.\" This file was written by Alessandro Ghedini <alessandro@ghedini.me>, 5.\" Matt Caswell <matt@openssl.org>, and Viktor Dukhovni <viktor@dukhovni.org>. 6.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: July 10 2024 $ 53.Dt EVP_PKEY_CTX_SET_HKDF_MD 3 54.Os 55.Sh NAME 56.Nm EVP_PKEY_CTX_set_hkdf_md , 57.Nm EVP_PKEY_CTX_set1_hkdf_salt , 58.Nm EVP_PKEY_CTX_set1_hkdf_key , 59.Nm EVP_PKEY_CTX_add1_hkdf_info , 60.Nm EVP_PKEY_CTX_hkdf_mode 61.Nd HMAC-based Extract-and-Expand key derivation algorithm 62.Sh SYNOPSIS 63.In openssl/evp.h 64.In openssl/kdf.h 65.Ft int 66.Fo EVP_PKEY_CTX_hkdf_mode 67.Fa "EVP_PKEY_CTX *pctx" 68.Fa "int mode" 69.Fc 70.Ft int 71.Fo EVP_PKEY_CTX_set_hkdf_md 72.Fa "EVP_PKEY_CTX *pctx" 73.Fa "const EVP_MD *md" 74.Fc 75.Ft int 76.Fo EVP_PKEY_CTX_set1_hkdf_salt 77.Fa "EVP_PKEY_CTX *pctx" 78.Fa "unsigned char *salt" 79.Fa "int saltlen" 80.Fc 81.Ft int 82.Fo EVP_PKEY_CTX_set1_hkdf_key 83.Fa "EVP_PKEY_CTX *pctx" 84.Fa "unsigned char *key" 85.Fa "int keylen" 86.Fc 87.Ft int 88.Fo EVP_PKEY_CTX_add1_hkdf_info 89.Fa "EVP_PKEY_CTX *pctx" 90.Fa "unsigned char *info" 91.Fa "int infolen" 92.Fc 93.Sh DESCRIPTION 94The 95.Dv EVP_PKEY_HKDF 96algorithm implements the HKDF key derivation function. 97HKDF follows the "extract-then-expand" paradigm, where the KDF logically 98consists of two modules. 99The first stage takes the input keying material and "extracts" from it a 100fixed-length pseudorandom key K. 101The second stage "expands" the key K 102into several additional pseudorandom keys (the output of the KDF). 103.Pp 104.Fn EVP_PKEY_CTX_hkdf_mode 105sets the mode for the HKDF operation. 106There are three modes that are currently defined: 107.Bl -tag -width Ds 108.It Dv EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND 109This is the default mode. 110Calling 111.Xr EVP_PKEY_derive 3 112on an 113.Vt EVP_PKEY_CTX 114set up for HKDF will perform an extract followed by 115an expand operation in one go. 116The derived key returned will be the result after the expand operation. 117The intermediate fixed-length pseudorandom key K is not returned. 118.Pp 119In this mode the digest, key, salt and info values must be set before a 120key is derived or an error occurs. 121.It Dv EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY 122In this mode calling 123.Xr EVP_PKEY_derive 3 124will just perform the extract operation. 125The value returned will be the intermediate fixed-length pseudorandom 126key K. 127.Pp 128The digest, key and salt values must be set before a key is derived or 129an error occurs. 130.It Dv EVP_PKEY_HKDEF_MODE_EXPAND_ONLY 131In this mode calling 132.Xr EVP_PKEY_derive 3 133will just perform the expand operation. 134The input key should be set to the intermediate fixed-length 135pseudorandom key K returned from a previous extract operation. 136.Pp 137The digest, key and info values must be set before a key is derived or 138an error occurs. 139.El 140.Pp 141.Fn EVP_PKEY_CTX_set_hkdf_md 142sets the message digest associated with the HKDF. 143.Pp 144.Fn EVP_PKEY_CTX_set1_hkdf_salt 145sets the salt to 146.Fa saltlen 147bytes of the buffer 148.Fa salt . 149Any existing value is replaced. 150.Pp 151.Fn EVP_PKEY_CTX_set1_hkdf_key 152sets the key to 153.Fa keylen 154bytes of the buffer 155.Fa key . 156Any existing value is replaced. 157.Pp 158.Fn EVP_PKEY_CTX_add1_hkdf_info 159sets the info value to 160.Fa infolen 161bytes of the buffer 162.Fa info . 163If a value is already set, it is appended to the existing value. 164.Sh STRING CTRLS 165HKDF also supports string based control operations via 166.Xr EVP_PKEY_CTX_ctrl_str 3 . 167The 168.Fa type 169parameter "md" uses the supplied 170.Fa value 171as the name of the digest algorithm to use. 172The 173.Fa type 174parameter "mode" accepts "EXTRACT_AND_EXPAND", "EXTRACT_ONLY" 175and "EXPAND_ONLY" as 176.Fa value 177to determine the mode to use. 178The 179.Fa type 180parameters "salt", "key" and "info" use the supplied 181.Fa value 182parameter as a 183seed, key, or info. 184The names "hexsalt", "hexkey" and "hexinfo" are similar except they take 185a hex string which is converted to binary. 186.Sh NOTES 187All these functions are implemented as macros. 188.Pp 189A context for HKDF can be obtained by calling: 190.Bd -literal 191 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); 192.Ed 193.Pp 194The total length of the info buffer cannot exceed 1024 bytes in length: 195this should be more than enough for any normal use of HKDF. 196.Pp 197The output length of an HKDF expand operation is specified via the 198length parameter to the 199.Xr EVP_PKEY_derive 3 200function. 201Since the HKDF output length is variable, passing a 202.Dv NULL 203buffer as a means to obtain the requisite length is not meaningful with 204HKDF in any mode that performs an expand operation. 205Instead, the caller must allocate a buffer of the desired length, and 206pass that buffer to 207.Xr EVP_PKEY_derive 3 208along with (a pointer initialized to) the desired length. 209Passing a 210.Dv NULL 211buffer to obtain the length is allowed when using 212.Dv EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY . 213.Sh RETURN VALUES 214All these functions return 1 for success and 0 or a negative value for 215failure. 216In particular a return value of -2 indicates the operation is not 217supported by the public key algorithm. 218.Sh EXAMPLES 219This example derives 10 bytes using SHA-256 with the secret key 220"secret", salt value "salt" and info value "label": 221.Bd -literal 222EVP_PKEY_CTX *pctx; 223unsigned char out[10]; 224size_t outlen = sizeof(out); 225 226if ((pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL)) == NULL) 227 /* Error */ 228 229if (EVP_PKEY_derive_init(pctx) <= 0) 230 /* Error */ 231if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0) 232 /* Error */ 233if (EVP_PKEY_CTX_set1_hkdf_salt(pctx, "salt", 4) <= 0) 234 /* Error */ 235if (EVP_PKEY_CTX_set1_hkdf_key(pctx, "secret", 6) <= 0) 236 /* Error */ 237if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 5) <= 0) 238 /* Error */ 239if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) 240 /* Error */ 241.Ed 242.Sh SEE ALSO 243.Xr EVP_PKEY_CTX_ctrl_str 3 , 244.Xr EVP_PKEY_CTX_new 3 , 245.Xr EVP_PKEY_derive 3 246.Sh STANDARDS 247RFC 5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF) 248.Sh HISTORY 249.Fn EVP_PKEY_CTX_set_hkdf_md , 250.Fn EVP_PKEY_CTX_set1_hkdf_salt , 251.Fn EVP_PKEY_CTX_set1_hkdf_key , 252and 253.Fn EVP_PKEY_CTX_add1_hkdf_info 254first appeared in OpenSSL 1.1.0 and 255.Fn EVP_PKEY_CTX_hkdf_mode 256in OpenSSL 1.1.1. 257These functions have been available since 258.Ox 7.2 . 259