1*4e4f5e48Stb.\" $OpenBSD: ECDH_compute_key.3,v 1.3 2023/08/29 10:07:42 tb Exp $ 2653997b5Sschwarze.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 3653997b5Sschwarze.\" 4653997b5Sschwarze.\" Permission to use, copy, modify, and distribute this software for any 5653997b5Sschwarze.\" purpose with or without fee is hereby granted, provided that the above 6653997b5Sschwarze.\" copyright notice and this permission notice appear in all copies. 7653997b5Sschwarze.\" 8653997b5Sschwarze.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9653997b5Sschwarze.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10653997b5Sschwarze.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11653997b5Sschwarze.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12653997b5Sschwarze.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13653997b5Sschwarze.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14653997b5Sschwarze.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15653997b5Sschwarze.\" 16*4e4f5e48Stb.Dd $Mdocdate: August 29 2023 $ 17653997b5Sschwarze.Dt ECDH_COMPUTE_KEY 3 18653997b5Sschwarze.Os 19653997b5Sschwarze.Sh NAME 20653997b5Sschwarze.Nm ECDH_compute_key , 21653997b5Sschwarze.Nm ECDH_size 22653997b5Sschwarze.Nd Elliptic Curve Diffie-Hellman key exchange 23653997b5Sschwarze.Sh SYNOPSIS 24*4e4f5e48Stb.In openssl/ec.h 25653997b5Sschwarze.Ft int 26653997b5Sschwarze.Fo ECDH_compute_key 27653997b5Sschwarze.Fa "void *out" 28653997b5Sschwarze.Fa "size_t outlen" 29653997b5Sschwarze.Fa "const EC_POINT *public_key" 30653997b5Sschwarze.Fa "EC_KEY *ecdh" 31653997b5Sschwarze.Fa "void *(*KDF)(const void *in, size_t inlen, void *out, size_t *outlen)" 32653997b5Sschwarze.Fc 33653997b5Sschwarze.Ft int 34653997b5Sschwarze.Fo ECDH_size 35653997b5Sschwarze.Fa "const EC_KEY *ecdh" 36653997b5Sschwarze.Fc 37653997b5Sschwarze.Sh DESCRIPTION 38653997b5Sschwarze.Fn ECDH_compute_key 39653997b5Sschwarzeperforms Elliptic Curve Diffie-Hellman key agreement. 40653997b5SschwarzeIt combines the private key contained in 41653997b5Sschwarze.Fa ecdh 42653997b5Sschwarzewith the other party's 43653997b5Sschwarze.Fa public_key , 44653997b5Sschwarzetakes the 45653997b5Sschwarze.Fa x 46653997b5Sschwarzecomponent of the affine coordinates, 47653997b5Sschwarzeand optionally applies the key derivation function 48653997b5Sschwarze.Fa KDF . 49653997b5SschwarzeIt stores the resulting symmetric key in the buffer 50653997b5Sschwarze.Fa out , 51653997b5Sschwarzewhich is 52653997b5Sschwarze.Fa outlen 53653997b5Sschwarzebytes long. 54653997b5SschwarzeIf 55653997b5Sschwarze.Fa KDF 56653997b5Sschwarzeis 57653997b5Sschwarze.Dv NULL , 58653997b5Sschwarze.Fa outlen 59653997b5Sschwarzemust be at least 60653997b5Sschwarze.Fn ECDH_size ecdh . 61653997b5Sschwarze.Pp 62653997b5Sschwarze.Fn ECDH_size 63653997b5Sschwarzereturns the number of bytes needed to store an affine coordinate of a 64653997b5Sschwarzepoint on the elliptic curve used by 65653997b5Sschwarze.Fa ecdh , 66c5d247d8Sjsgwhich is one eighth of the degree of the finite field underlying 67653997b5Sschwarzethat elliptic curve, rounded up to the next integer number. 68653997b5Sschwarze.Sh RETURN VALUES 69653997b5Sschwarze.Fn ECDH_compute_key 70653997b5Sschwarzereturns the length of the computed key in bytes or -1 if an error occurs. 71653997b5Sschwarze.Pp 72653997b5Sschwarze.Fn ECDH_size 73653997b5Sschwarzereturns the number of bytes needed to store an affine coordinate. 74653997b5Sschwarze.Sh SEE ALSO 75653997b5Sschwarze.Xr DH_generate_key 3 , 76653997b5Sschwarze.Xr DH_size 3 , 77653997b5Sschwarze.Xr EC_GROUP_new 3 , 78653997b5Sschwarze.Xr EC_KEY_new 3 , 79653997b5Sschwarze.Xr EC_POINT_new 3 , 80653997b5Sschwarze.Xr X25519 3 81653997b5Sschwarze.Sh HISTORY 82653997b5Sschwarze.Fn ECDH_compute_key 83653997b5Sschwarzefirst appeared in OpenSSL 0.9.8 and has been available since 84653997b5Sschwarze.Ox 4.5 . 85653997b5Sschwarze.Pp 86653997b5Sschwarze.Fn ECDH_size 87653997b5Sschwarzefirst appeared in 88653997b5Sschwarze.Ox 6.1 . 89