From d3c60fbc3b4a3cce424b7ba1ec26f0637266f961 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 19 Aug 2019 13:08:26 +0000 Subject: document ECDH_compute_key(3) and ECDH_size(3); feedback and OK tb@ --- src/lib/libcrypto/man/DH_generate_key.3 | 7 +-- src/lib/libcrypto/man/ECDH_compute_key.3 | 88 ++++++++++++++++++++++++++++++++ src/lib/libcrypto/man/EC_GROUP_new.3 | 5 +- src/lib/libcrypto/man/EC_KEY_new.3 | 5 +- src/lib/libcrypto/man/EC_POINT_new.3 | 7 +-- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/X25519.3 | 5 +- src/lib/libcrypto/man/crypto.3 | 5 +- 8 files changed, 110 insertions(+), 15 deletions(-) create mode 100644 src/lib/libcrypto/man/ECDH_compute_key.3 (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/DH_generate_key.3 b/src/lib/libcrypto/man/DH_generate_key.3 index 43d642bf26..076b49f7a1 100644 --- a/src/lib/libcrypto/man/DH_generate_key.3 +++ b/src/lib/libcrypto/man/DH_generate_key.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: DH_generate_key.3,v 1.11 2019/06/10 14:58:48 schwarze Exp $ +.\" $OpenBSD: DH_generate_key.3,v 1.12 2019/08/19 13:08:26 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" .\" This file was written by Ulf Moeller . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: August 19 2019 $ .Dt DH_GENERATE_KEY 3 .Os .Sh NAME @@ -112,7 +112,8 @@ The error codes can be obtained by .Sh SEE ALSO .Xr DH_get0_key 3 , .Xr DH_new 3 , -.Xr DH_size 3 +.Xr DH_size 3 , +.Xr ECDH_compute_key 3 .Sh HISTORY .Fn DH_generate_key and diff --git a/src/lib/libcrypto/man/ECDH_compute_key.3 b/src/lib/libcrypto/man/ECDH_compute_key.3 new file mode 100644 index 0000000000..973ce4289c --- /dev/null +++ b/src/lib/libcrypto/man/ECDH_compute_key.3 @@ -0,0 +1,88 @@ +.\" $OpenBSD: ECDH_compute_key.3,v 1.1 2019/08/19 13:08:26 schwarze Exp $ +.\" Copyright (c) 2019 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: August 19 2019 $ +.Dt ECDH_COMPUTE_KEY 3 +.Os +.Sh NAME +.Nm ECDH_compute_key , +.Nm ECDH_size +.Nd Elliptic Curve Diffie-Hellman key exchange +.Sh SYNOPSIS +.In openssl/ecdh.h +.Ft int +.Fo ECDH_compute_key +.Fa "void *out" +.Fa "size_t outlen" +.Fa "const EC_POINT *public_key" +.Fa "EC_KEY *ecdh" +.Fa "void *(*KDF)(const void *in, size_t inlen, void *out, size_t *outlen)" +.Fc +.Ft int +.Fo ECDH_size +.Fa "const EC_KEY *ecdh" +.Fc +.Sh DESCRIPTION +.Fn ECDH_compute_key +performs Elliptic Curve Diffie-Hellman key agreement. +It combines the private key contained in +.Fa ecdh +with the other party's +.Fa public_key , +takes the +.Fa x +component of the affine coordinates, +and optionally applies the key derivation function +.Fa KDF . +It stores the resulting symmetric key in the buffer +.Fa out , +which is +.Fa outlen +bytes long. +If +.Fa KDF +is +.Dv NULL , +.Fa outlen +must be at least +.Fn ECDH_size ecdh . +.Pp +.Fn ECDH_size +returns the number of bytes needed to store an affine coordinate of a +point on the elliptic curve used by +.Fa ecdh , +which is one eigth of the degree of the finite field underlying +that elliptic curve, rounded up to the next integer number. +.Sh RETURN VALUES +.Fn ECDH_compute_key +returns the length of the computed key in bytes or -1 if an error occurs. +.Pp +.Fn ECDH_size +returns the number of bytes needed to store an affine coordinate. +.Sh SEE ALSO +.Xr DH_generate_key 3 , +.Xr DH_size 3 , +.Xr EC_GROUP_new 3 , +.Xr EC_KEY_new 3 , +.Xr EC_POINT_new 3 , +.Xr X25519 3 +.Sh HISTORY +.Fn ECDH_compute_key +first appeared in OpenSSL 0.9.8 and has been available since +.Ox 4.5 . +.Pp +.Fn ECDH_size +first appeared in +.Ox 6.1 . diff --git a/src/lib/libcrypto/man/EC_GROUP_new.3 b/src/lib/libcrypto/man/EC_GROUP_new.3 index 33f2987f33..3e005117ff 100644 --- a/src/lib/libcrypto/man/EC_GROUP_new.3 +++ b/src/lib/libcrypto/man/EC_GROUP_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_GROUP_new.3,v 1.10 2019/06/10 09:49:48 schwarze Exp $ +.\" $OpenBSD: EC_GROUP_new.3,v 1.11 2019/08/19 13:08:26 schwarze Exp $ .\" OpenSSL 9b86974e Mon Aug 17 15:21:33 2015 -0400 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 10 2019 $ +.Dd $Mdocdate: August 19 2019 $ .Dt EC_GROUP_NEW 3 .Os .Sh NAME @@ -306,6 +306,7 @@ return 1 on success or 0 on error. .Xr EC_KEY_new 3 , .Xr EC_POINT_add 3 , .Xr EC_POINT_new 3 , +.Xr ECDH_compute_key 3 , .Xr ECDSA_SIG_new 3 .Sh HISTORY .Fn EC_GROUP_new , diff --git a/src/lib/libcrypto/man/EC_KEY_new.3 b/src/lib/libcrypto/man/EC_KEY_new.3 index 70e3a655f8..ba0774ccd4 100644 --- a/src/lib/libcrypto/man/EC_KEY_new.3 +++ b/src/lib/libcrypto/man/EC_KEY_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_KEY_new.3,v 1.14 2019/08/16 16:20:23 schwarze Exp $ +.\" $OpenBSD: EC_KEY_new.3,v 1.15 2019/08/19 13:08:26 schwarze Exp $ .\" full merge up to: OpenSSL 3aef36ff Jan 5 13:06:03 2016 -0500 .\" partial merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100 .\" @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: August 16 2019 $ +.Dd $Mdocdate: August 19 2019 $ .Dt EC_KEY_NEW 3 .Os .Sh NAME @@ -527,6 +527,7 @@ returns the point_conversion_form for the .Xr EC_KEY_METHOD_new 3 , .Xr EC_POINT_add 3 , .Xr EC_POINT_new 3 , +.Xr ECDH_compute_key 3 , .Xr ECDSA_SIG_new 3 , .Xr EVP_PKEY_set1_EC_KEY 3 .Sh HISTORY diff --git a/src/lib/libcrypto/man/EC_POINT_new.3 b/src/lib/libcrypto/man/EC_POINT_new.3 index 06a15fb62a..94ab9054bf 100644 --- a/src/lib/libcrypto/man/EC_POINT_new.3 +++ b/src/lib/libcrypto/man/EC_POINT_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EC_POINT_new.3,v 1.10 2019/03/18 12:58:00 schwarze Exp $ +.\" $OpenBSD: EC_POINT_new.3,v 1.11 2019/08/19 13:08:26 schwarze Exp $ .\" full merge up to: OpenSSL ddc1caac Mar 6 14:00:24 2018 -0500 .\" .\" This file was written by Matt Caswell . @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 18 2019 $ +.Dd $Mdocdate: August 19 2019 $ .Dt EC_POINT_NEW 3 .Os .Sh NAME @@ -482,7 +482,8 @@ on error. .Xr EC_GROUP_copy 3 , .Xr EC_GROUP_new 3 , .Xr EC_KEY_new 3 , -.Xr EC_POINT_add 3 +.Xr EC_POINT_add 3 , +.Xr ECDH_compute_key 3 .Sh HISTORY .Fn EC_POINT_new , .Fn EC_POINT_free , diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index e347c3dc98..92e3c1b6f0 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.149 2019/08/16 16:15:50 schwarze Exp $ +# $OpenBSD: Makefile,v 1.150 2019/08/19 13:08:26 schwarze Exp $ .include @@ -91,6 +91,7 @@ MAN= \ DSA_set_method.3 \ DSA_sign.3 \ DSA_size.3 \ + ECDH_compute_key.3 \ ECDSA_SIG_new.3 \ EC_GFp_simple_method.3 \ EC_GROUP_copy.3 \ diff --git a/src/lib/libcrypto/man/X25519.3 b/src/lib/libcrypto/man/X25519.3 index 13f013e8a2..64eda4bf85 100644 --- a/src/lib/libcrypto/man/X25519.3 +++ b/src/lib/libcrypto/man/X25519.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X25519.3,v 1.4 2018/08/10 17:28:48 jsing Exp $ +.\" $OpenBSD: X25519.3,v 1.5 2019/08/19 13:08:26 schwarze Exp $ .\" contains some text from: BoringSSL curve25519.h, curve25519.c .\" content also checked up to: OpenSSL f929439f Mar 15 12:19:16 2018 +0000 .\" @@ -17,7 +17,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: August 10 2018 $ +.Dd $Mdocdate: August 19 2019 $ .Dt X25519 3 .Os .Sh NAME @@ -90,6 +90,7 @@ bytes each. returns 1 on success or 0 on error. Failure can occur when the input is a point of small order. .Sh SEE ALSO +.Xr ECDH_compute_key 3 .Rs .%A D. J. Bernstein .%R A state-of-the-art Diffie-Hellman function:\ diff --git a/src/lib/libcrypto/man/crypto.3 b/src/lib/libcrypto/man/crypto.3 index 23a9a4e5a9..bd244ebf4b 100644 --- a/src/lib/libcrypto/man/crypto.3 +++ b/src/lib/libcrypto/man/crypto.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: crypto.3,v 1.20 2019/06/06 01:06:59 schwarze Exp $ +.\" $OpenBSD: crypto.3,v 1.21 2019/08/19 13:08:26 schwarze Exp $ .\" OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100 .\" .\" This file was written by Ulf Moeller and @@ -49,7 +49,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 6 2019 $ +.Dd $Mdocdate: August 19 2019 $ .Dt CRYPTO 3 .Os .Sh NAME @@ -75,6 +75,7 @@ and .Sy Public key cryptography and key agreement are provided by .Xr DH_new 3 , +.Xr ECDH_compute_key 3 , .Xr X25519 3 , .Xr DSA_new 3 , .Xr ECDSA_SIG_new 3 , -- cgit v1.2.3-55-g6feb