document ECDH_compute_key(3) and ECDH_size(3);

feedback and OK tb@

8 files changed, 110 insertions, 15 deletions

diff --git a/lib/libcrypto/man/DH_generate_key.3 b/lib/libcrypto/man/DH_generate_key.3
index 43d642bf26b..076b49f7a15 100644
--- a/lib/libcrypto/man/DH_generate_key.3
+++ b/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 <ulf@openssl.org>.
@@ -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/lib/libcrypto/man/ECDH_compute_key.3 b/lib/libcrypto/man/ECDH_compute_key.3
new file mode 100644
index 00000000000..973ce4289ca
--- /dev/null
+++ b/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 <schwarze@openbsd.org>
+.\"
+.\" 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/lib/libcrypto/man/EC_GROUP_new.3 b/lib/libcrypto/man/EC_GROUP_new.3
index 33f2987f333..3e005117ff5 100644
--- a/lib/libcrypto/man/EC_GROUP_new.3
+++ b/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 <matt@openssl.org>.
@@ -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/lib/libcrypto/man/EC_KEY_new.3 b/lib/libcrypto/man/EC_KEY_new.3
index 70e3a655f85..ba0774ccd43 100644
--- a/lib/libcrypto/man/EC_KEY_new.3
+++ b/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/lib/libcrypto/man/EC_POINT_new.3 b/lib/libcrypto/man/EC_POINT_new.3
index 06a15fb62ad..94ab9054bf6 100644
--- a/lib/libcrypto/man/EC_POINT_new.3
+++ b/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 <matt@openssl.org>.
@@ -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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index e347c3dc988..92e3c1b6f03 100644
--- a/lib/libcrypto/man/Makefile
+++ b/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 <bsd.own.mk>
 
@@ -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/lib/libcrypto/man/X25519.3 b/lib/libcrypto/man/X25519.3
index 13f013e8a26..64eda4bf855 100644
--- a/lib/libcrypto/man/X25519.3
+++ b/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/lib/libcrypto/man/crypto.3 b/lib/libcrypto/man/crypto.3
index 23a9a4e5a9d..bd244ebf4b0 100644
--- a/lib/libcrypto/man/crypto.3
+++ b/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 <ulf@openssl.org> 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 ,