jsing@ points out to me that our X25519 interface was copied from

BoringSSL rather than from OpenSSL and that it is not hooked into evp(3).

So delete all text from OpenSSL including the Copyright and license
and replace it by some text assembled from comments in BoringSSL
code and headers and some text written myself, all under ISC license.
In particular, also describe X25519_keypair(3), add SYNOPSIS, RETURN
VALUES, STANDARDS, and a reference to D. J. Bernsteins instructions
on how to use the algorithm.  Delete the text related to EVP_PKEY
describing features we do not support.

1 files changed, 85 insertions, 98 deletions

diff --git a/src/lib/libcrypto/man/X25519.3 b/src/lib/libcrypto/man/X25519.3
index 6292d33ff5..b2812149b1 100644
--- a/src/lib/libcrypto/man/X25519.3
+++ b/src/lib/libcrypto/man/X25519.3
@@ -1,112 +1,99 @@
-.\" $OpenBSD: X25519.3,v 1.2 2018/03/30 01:03:51 schwarze Exp $
-.\" full merge up to: OpenSSL man7/X25519 69687aa8 Mar 28 23:57:28 2017 +0200
-.\" selective merge up to: OpenSSL f929439f Mar 15 12:19:16 2018 +0000
+.\" $OpenBSD: X25519.3,v 1.3 2018/03/30 18:38:22 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
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
-.\" and Matt Caswell <matt@openssl.org>.
-.\" Copyright (c) 2017, 2018 The OpenSSL Project.  All rights reserved.
+.\" Copyright (c) 2015 Google Inc.
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
+.\" Permission to use, copy, modify, and/or 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.
 .\"
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\"
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in
-.\"    the documentation and/or other materials provided with the
-.\"    distribution.
-.\"
-.\" 3. All advertising materials mentioning features or use of this
-.\"    software must display the following acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
-.\"
-.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
-.\"    endorse or promote products derived from this software without
-.\"    prior written permission. For written permission, please contact
-.\"    openssl-core@openssl.org.
-.\"
-.\" 5. Products derived from this software may not be called "OpenSSL"
-.\"    nor may "OpenSSL" appear in their names without prior written
-.\"    permission of the OpenSSL Project.
-.\"
-.\" 6. Redistributions of any form whatsoever must retain the following
-.\"    acknowledgment:
-.\"    "This product includes software developed by the OpenSSL Project
-.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
-.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
-.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
-.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS 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: March 30 2018 $
 .Dt X25519 3
 .Os
 .Sh NAME
-.Nm X25519
-.Nd EVP_PKEY X25519 support
+.Nm X25519 ,
+.Nm X25519_keypair
+.Nd Elliptic Curve Diffie-Hellman primitive based on Curve25519
+.Sh SYNOPSIS
+.Ft int
+.Fo X25519
+.Fa "uint8_t out_shared_key[X25519_KEY_LENGTH]"
+.Fa "const uint8_t private_key[X25519_KEY_LENGTH]"
+.Fa "const uint8_t peer_public_value[X25519_KEY_LENGTH]"
+.Fc
+.Ft void
+.Fo X25519_keypair
+.Fa "uint8_t out_public_value[X25519_KEY_LENGTH]"
+.Fa "uint8_t out_private_key[X25519_KEY_LENGTH]"
+.Fc
 .Sh DESCRIPTION
-The
-.Nm
-.Vt EVP_PKEY
-implementation supports key generation and key derivation using X25519.
-It has associated private and public key formats compatible with
-draft-ietf-curdle-pkix-03.
-.Pp
-No additional parameters can be set during key generation.
-.Pp
-The peer public key must be set using
-.Xr EVP_PKEY_derive_set_peer 3
-when performing key derivation.
-.Pp
-A context for the
-.Nm
-algorithm can be obtained by calling:
+Curve25519 is an elliptic curve over a prime field specified in RFC 7748.
+The prime field is defined by the prime number 2^255 - 19.
 .Pp
-.Dl EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(NID_X25519, NULL);
+.Fn X25519
+is the Diffie-Hellman primitive built from Curve25519 as described
+in RFC 7748 section 5.
+Section 6.1 describes the intended use in an Elliptic Curve Diffie-Hellman
+(ECDH) protocol.
 .Pp
-X25519 private keys can be loaded from a PKCS#8 private key file using
-.Xr PEM_read_bio_PrivateKey 3
-or similar functions.
-Setting a private key also sets the associated public key.
+.Fn X25519
+writes a shared key to
+.Fa out_shared_key
+that is calculated from the given
+.Fa private_key
+and the
+.Fa peer_public_value
+by scalar multiplication.
+Do not use the shared key directly, rather use a key derivation
+function and also include the two public values as inputs.
 .Pp
-X25519 public keys can be loaded from a SubjectPublicKeyInfo
-structure in a PEM file using
-.Xr PEM_read_bio_PUBKEY 3
-or similar functions.
-.Sh EXAMPLES
-Generate an
-.Nm
-private key and write it to standard output in PEM format:
-.Bd -literal
-#include <openssl/evp.h>
-#include <openssl/pem.h>
-
-EVP_PKEY *pkey = NULL;
-EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(NID_X25519, NULL);
-EVP_PKEY_keygen_init(pctx);
-EVP_PKEY_keygen(pctx, &pkey);
-EVP_PKEY_CTX_free(pctx);
-PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);
-.Ed
+.Fn X25519_keypair
+sets
+.Fa out_public_value
+and
+.Fa out_private_key
+to a freshly generated public/private key pair.
+First, the
+.Fa out_private_key
+is generated with
+.Xr arc4random_buf 3 .
+Then, the opposite of the masking described in RFC 7748 section 5
+is applied to it to make sure that the generated private key is never
+correctly masked.
+The purpose is to cause incorrect implementations on the peer side
+to consistently fail.
+Correct implementations will decode the key correctly even when it is
+not correctly masked.
+Finally, the
+.Fa out_public_value
+is calculated from the
+.Fa out_private_key
+by multiplying it with the Montgomery base point
+.Vt uint8_t u[32] No = Brq 9 .
 .Pp
-The key derivation example in
-.Xr EVP_PKEY_derive 3
-can be used with
-.Nm .
+The size of a public and private key is
+.Dv X25519_KEY_LENGTH No = 32
+bytes each.
+.Sh RETURN VALUES
+.Fn X25519
+returns 1 on success or 0 on error.
+Failure can occur when the input is a point of small order.
 .Sh SEE ALSO
-.Xr EVP_PKEY_CTX_new 3 ,
-.Xr EVP_PKEY_derive 3 ,
-.Xr EVP_PKEY_keygen 3 ,
-.Xr PEM_read_bio_PrivateKey 3
+.Rs
+.%A D. J. Bernstein
+.%R A state-of-the-art Diffie-Hellman function:\
+    How do I use Curve25519 in my own software?
+.%U http://cr.yp.to/ecdh.html
+.Re
+.Sh STANDARDS
+RFC 7748: Elliptic Curves for Security