1.\" $OpenBSD: EVP_PKEY_derive.3,v 1.10 2024/03/05 19:21:31 tb Exp $ 2.\" full merge up to: OpenSSL 48e5119a Jan 19 10:49:22 2018 +0100 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 22.\" Copyright (c) 2006, 2009, 2013, 2018 The OpenSSL Project. 23.\" All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: March 5 2024 $ 70.Dt EVP_PKEY_DERIVE 3 71.Os 72.Sh NAME 73.Nm EVP_PKEY_derive_init , 74.Nm EVP_PKEY_derive_set_peer , 75.Nm EVP_PKEY_CTX_get0_peerkey , 76.Nm EVP_PKEY_derive 77.Nd derive public key algorithm shared secret 78.Sh SYNOPSIS 79.In openssl/evp.h 80.Ft int 81.Fo EVP_PKEY_derive_init 82.Fa "EVP_PKEY_CTX *ctx" 83.Fc 84.Ft int 85.Fo EVP_PKEY_derive_set_peer 86.Fa "EVP_PKEY_CTX *ctx" 87.Fa "EVP_PKEY *peerkey" 88.Fc 89.Ft EVP_PKEY * 90.Fo EVP_PKEY_CTX_get0_peerkey 91.Fa "EVP_PKEY_CTX *ctx" 92.Fc 93.Ft int 94.Fo EVP_PKEY_derive 95.Fa "EVP_PKEY_CTX *ctx" 96.Fa "unsigned char *key" 97.Fa "size_t *keylen" 98.Fc 99.Sh DESCRIPTION 100.Fn EVP_PKEY_derive_init 101initializes the public key algorithm context 102.Fa ctx 103for shared secret derivation using the 104.Vt EVP_PKEY 105object already stored in 106.Fa ctx . 107The library provides built-in support for keys with an 108.Xr EVP_PKEY_base_id 3 109of 110.Dv EVP_PKEY_DH , 111.Dv EVP_PKEY_EC , 112.Dv EVP_PKEY_HKDF , 113and 114.Dv EVP_PKEY_X25519 . 115.Pp 116After the call to 117.Fn EVP_PKEY_derive_init , 118algorithm specific control operations can optionally be performed 119to set any appropriate parameters for the operation. 120.Pp 121.Fn EVP_PKEY_derive_set_peer 122configures the 123.Fa ctx , 124which already needs to be initialized with 125.Fn EVP_PKEY_derive_init , 126.Xr EVP_PKEY_encrypt_init 3 , 127or 128.Xr EVP_PKEY_decrypt_init 3 , 129to use the 130.Fa peerkey , 131which is normally a public key. 132In case of success, the reference count of the 133.Fa peerkey 134is incremented by one. 135Consequently, the caller needs to call 136.Xr EVP_PKEY_free 3 137on the 138.Fa peerkey 139when the caller no longer needs it, even if it is still in use by 140.Fa ctx . 141.Pp 142.Fn EVP_PKEY_derive 143derives a shared secret using 144.Fa ctx . 145If 146.Fa key 147is 148.Dv NULL , 149then the maximum size of the output buffer is written to the 150.Fa keylen 151parameter. 152If 153.Fa key 154is not 155.Dv NULL 156then before the call the 157.Fa keylen 158parameter should contain the length of the 159.Fa key 160buffer. 161If the call is successful, the shared secret is written to 162.Fa key 163and the amount of data written to 164.Fa keylen . 165.Pp 166The function 167.Fn EVP_PKEY_derive 168can be called more than once on the same context if several operations 169are performed using the same parameters. 170.Sh RETURN VALUES 171.Fn EVP_PKEY_derive_init , 172.Fn EVP_PKEY_derive_set_peer , 173and 174.Fn EVP_PKEY_derive 175return 1 for success and 0 or a negative value for failure. 176In particular, a return value of \-2 indicates the operation is not 177supported by the public key algorithm. 178.Pp 179For 180.Fn EVP_PKEY_derive_set_peer , 181a return value of \-1 can for example occur if 182.Fa ctx 183is not properly initialized, does not contain an 184.Vt EVP_PKEY 185that can be retrieved with 186.Xr EVP_PKEY_CTX_get0_pkey 3 , 187the 188.Xr EVP_PKEY_id 3 189of both keys mismatch, or 190.Xr EVP_PKEY_cmp_parameters 3 191reports mismatching key parameters. 192.Pp 193.Fn EVP_PKEY_derive 194fails with a return value of \-1 for example if 195.Fa ctx 196has not been successfully initialized with 197.Fn EVP_PKEY_derive_init . 198.Pp 199.Fn EVP_PKEY_CTX_get0_peerkey 200returns an internal pointer to the 201.Fa peerkey 202used by 203.Fa ctx 204without incrementing its reference count. 205.Sh EXAMPLES 206Derive shared secret (for example DH or EC keys): 207.Bd -literal -offset indent 208#include <openssl/evp.h> 209#include <openssl/rsa.h> 210 211EVP_PKEY_CTX *ctx; 212ENGINE *eng; 213unsigned char *skey; 214size_t skeylen; 215EVP_PKEY *pkey, *peerkey; 216 217/* Assumes that pkey, eng, and peerkey have already been set up. */ 218ctx = EVP_PKEY_CTX_new(pkey, eng); 219if (!ctx) 220 /* Error occurred */ 221if (EVP_PKEY_derive_init(ctx) <= 0) 222 /* Error */ 223if (EVP_PKEY_derive_set_peer(ctx, peerkey) <= 0) 224 /* Error */ 225 226/* Determine buffer length */ 227if (EVP_PKEY_derive(ctx, NULL, &skeylen) <= 0) 228 /* Error */ 229 230skey = malloc(skeylen); 231 232if (!skey) 233 /* malloc failure */ 234 235if (EVP_PKEY_derive(ctx, skey, &skeylen) <= 0) 236 /* Error */ 237 238/* Shared secret is skey bytes written to buffer skey */ 239.Ed 240.Sh SEE ALSO 241.Xr EVP_PKEY_CTX_new 3 , 242.Xr EVP_PKEY_decrypt 3 , 243.Xr EVP_PKEY_encrypt 3 , 244.Xr EVP_PKEY_meth_set_derive 3 , 245.Xr EVP_PKEY_sign 3 , 246.Xr EVP_PKEY_verify 3 , 247.Xr EVP_PKEY_verify_recover 3 , 248.Xr X25519 3 249.Sh HISTORY 250.Fn EVP_PKEY_derive_init , 251.Fn EVP_PKEY_derive_set_peer , 252.Fn EVP_PKEY_CTX_get0_peerkey , 253and 254.Fn EVP_PKEY_derive 255first appeared in OpenSSL 1.0.0 and have been available since 256.Ox 4.9 . 257