1.\" $OpenBSD: ECDH_compute_key.3,v 1.2 2021/03/12 05:18:00 jsg Exp $ 2.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.Dd $Mdocdate: March 12 2021 $ 17.Dt ECDH_COMPUTE_KEY 3 18.Os 19.Sh NAME 20.Nm ECDH_compute_key , 21.Nm ECDH_size 22.Nd Elliptic Curve Diffie-Hellman key exchange 23.Sh SYNOPSIS 24.In openssl/ecdh.h 25.Ft int 26.Fo ECDH_compute_key 27.Fa "void *out" 28.Fa "size_t outlen" 29.Fa "const EC_POINT *public_key" 30.Fa "EC_KEY *ecdh" 31.Fa "void *(*KDF)(const void *in, size_t inlen, void *out, size_t *outlen)" 32.Fc 33.Ft int 34.Fo ECDH_size 35.Fa "const EC_KEY *ecdh" 36.Fc 37.Sh DESCRIPTION 38.Fn ECDH_compute_key 39performs Elliptic Curve Diffie-Hellman key agreement. 40It combines the private key contained in 41.Fa ecdh 42with the other party's 43.Fa public_key , 44takes the 45.Fa x 46component of the affine coordinates, 47and optionally applies the key derivation function 48.Fa KDF . 49It stores the resulting symmetric key in the buffer 50.Fa out , 51which is 52.Fa outlen 53bytes long. 54If 55.Fa KDF 56is 57.Dv NULL , 58.Fa outlen 59must be at least 60.Fn ECDH_size ecdh . 61.Pp 62.Fn ECDH_size 63returns the number of bytes needed to store an affine coordinate of a 64point on the elliptic curve used by 65.Fa ecdh , 66which is one eighth of the degree of the finite field underlying 67that elliptic curve, rounded up to the next integer number. 68.Sh RETURN VALUES 69.Fn ECDH_compute_key 70returns the length of the computed key in bytes or -1 if an error occurs. 71.Pp 72.Fn ECDH_size 73returns the number of bytes needed to store an affine coordinate. 74.Sh SEE ALSO 75.Xr DH_generate_key 3 , 76.Xr DH_size 3 , 77.Xr EC_GROUP_new 3 , 78.Xr EC_KEY_new 3 , 79.Xr EC_POINT_new 3 , 80.Xr X25519 3 81.Sh HISTORY 82.Fn ECDH_compute_key 83first appeared in OpenSSL 0.9.8 and has been available since 84.Ox 4.5 . 85.Pp 86.Fn ECDH_size 87first appeared in 88.Ox 6.1 . 89