1.\" $OpenBSD: EVP_PKEY_CTX_set_tls1_prf_md.3,v 1.2 2024/07/10 10:22:03 tb Exp $ 2.\" full merge up to: OpenSSL 1cb7eff4 Sep 10 13:56:40 2019 +0100 3.\" 4.\" This file was written by Dr Stephen Henson <steve@openssl.org>, 5.\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: July 10 2024 $ 52.Dt EVP_PKEY_CTX_SET_TLS1_PRF_MD 3 53.Os 54.Sh NAME 55.Nm EVP_PKEY_CTX_set_tls1_prf_md , 56.Nm EVP_PKEY_CTX_set1_tls1_prf_secret , 57.Nm EVP_PKEY_CTX_add1_tls1_prf_seed 58.Nd TLS PRF key derivation algorithm 59.Sh SYNOPSIS 60.In openssl/evp.h 61.In openssl/kdf.h 62.Ft int 63.Fo EVP_PKEY_CTX_set_tls1_prf_md 64.Fa "EVP_PKEY_CTX *pctx" 65.Fa "const EVP_MD *md" 66.Fc 67.Ft int 68.Fo EVP_PKEY_CTX_set1_tls1_prf_secret 69.Fa "EVP_PKEY_CTX *pctx" 70.Fa "unsigned char *sec" 71.Fa "int seclen" 72.Fc 73.Ft int 74.Fo EVP_PKEY_CTX_add1_tls1_prf_seed 75.Fa "EVP_PKEY_CTX *pctx" 76.Fa "unsigned char *seed" 77.Fa "int seedlen" 78.Fc 79.Sh DESCRIPTION 80The 81.Dv EVP_PKEY_TLS1_PRF 82algorithm implements the PRF key derivation function for TLS. 83It has no associated private key and only implements key derivation using 84.Xr EVP_PKEY_derive 3 . 85.Pp 86.Fn EVP_PKEY_set_tls1_prf_md 87sets the message digest associated with the TLS PRF. 88.Xr EVP_md5_sha1 3 89is treated as a special case which uses the PRF algorithm using both 90MD5 and SHA1 as used in TLS 1.0 and 1.1. 91.Pp 92.Fn EVP_PKEY_CTX_set_tls1_prf_secret 93sets the secret value of the TLS PRF to 94.Fa seclen 95bytes of the buffer 96.Fa sec . 97Any existing secret value is replaced and any seed is reset. 98.Pp 99.Fn EVP_PKEY_CTX_add1_tls1_prf_seed 100sets the seed to 101.Fa seedlen 102bytes of 103.Fa seed . 104If a seed is already set it is appended to the existing value. 105.Sh STRING CTRLS 106The TLS PRF also supports string based control operations using 107.Xr EVP_PKEY_CTX_ctrl_str 3 . 108The 109.Fa type 110parameter "md" uses the supplied 111.Fa value 112as the name of the digest algorithm to use. 113The 114.Fa type 115parameters "secret" and "seed" use the supplied 116.Fa value 117parameter as a secret or seed value. 118The names "hexsecret" and "hexseed" are similar except they take a hex 119string which is converted to binary. 120.Sh NOTES 121All these functions are implemented as macros. 122.Pp 123A context for the TLS PRF can be obtained by calling: 124.Bd -literal 125 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); 126.Ed 127.Pp 128The digest, secret value and seed must be set before a key is derived or 129an error occurs. 130.Pp 131The total length of all seeds cannot exceed 1024 bytes in length: this 132should be more than enough for any normal use of the TLS PRF. 133.Pp 134The output length of the PRF is specified by the length parameter in the 135.Xr EVP_PKEY_derive 3 136function. 137Since the output length is variable, setting the buffer to 138.Dv NULL 139is not meaningful for the TLS PRF. 140.Sh RETURN VALUES 141All these functions return 1 for success and 0 or a negative value for 142failure. 143In particular a return value of -2 indicates the operation is not 144supported by the public key algorithm. 145.Sh EXAMPLES 146This example derives 10 bytes using SHA-256 with the secret key "secret" 147and seed value "seed": 148.Bd -literal 149 EVP_PKEY_CTX *pctx; 150 unsigned char out[10]; 151 size_t outlen = sizeof(out); 152 153 pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); 154 if (EVP_PKEY_derive_init(pctx) <= 0) 155 /* Error */ 156 if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0) 157 /* Error */ 158 if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0) 159 /* Error */ 160 if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0) 161 /* Error */ 162 if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) 163 /* Error */ 164.Ed 165.Sh SEE ALSO 166.Xr EVP_PKEY_CTX_ctrl_str 3 , 167.Xr EVP_PKEY_CTX_new 3 , 168.Xr EVP_PKEY_derive 3 169.Sh HISTORY 170These functions first appeared in OpenSSL 1.1.0 and have been available since 171.Ox 7.6 . 172