In curve25519.h rev. 1.4 to 1.7, tb@ and jsing@ provided

ED25519_keypair(3), ED25519_sign(3), and ED25519_verify(3).
Document them.

1 files changed, 121 insertions, 11 deletions

diff --git a/lib/libcrypto/man/X25519.3 b/lib/libcrypto/man/X25519.3
index 8d8006fe96e..a327f8c7b25 100644
--- a/lib/libcrypto/man/X25519.3
+++ b/lib/libcrypto/man/X25519.3
@@ -1,9 +1,9 @@
-.\" $OpenBSD: X25519.3,v 1.6 2022/02/18 10:24:32 jsg Exp $
+.\" $OpenBSD: X25519.3,v 1.7 2022/12/15 17:20:48 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
 .\"
 .\" Copyright (c) 2015 Google Inc.
-.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2018, 2022 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and/or distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -17,13 +17,23 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: February 18 2022 $
+.\" According to the BoringSSL git history, those parts of the text in
+.\" the present manual page that are Copyrighted by Google were probably
+.\" written by Adam Langley <agl@google.com> in 2015.
+.\" I fail to see any such text in the public domain files written
+.\" by Daniel J. Bernstein and others that are included in SUPERCOP
+.\" and that Adam Langley's BoringSSL implementation is based on.
+.\"
+.Dd $Mdocdate: December 15 2022 $
 .Dt X25519 3
 .Os
 .Sh NAME
 .Nm X25519 ,
-.Nm X25519_keypair
-.Nd Elliptic Curve Diffie-Hellman primitive based on Curve25519
+.Nm X25519_keypair ,
+.Nm ED25519_keypair ,
+.Nm ED25519_sign ,
+.Nm ED25519_verify
+.Nd Elliptic Curve Diffie-Hellman and signature primitives based on Curve25519
 .Sh SYNOPSIS
 .In openssl/curve25519.h
 .Ft int
@@ -37,11 +47,32 @@
 .Fa "uint8_t out_public_value[X25519_KEY_LENGTH]"
 .Fa "uint8_t out_private_key[X25519_KEY_LENGTH]"
 .Fc
+.Ft void
+.Fo ED25519_keypair
+.Fa "uint8_t out_public_key[ED25519_PUBLIC_KEY_LENGTH]"
+.Fa "uint8_t out_private_key[ED25519_PRIVATE_KEY_LENGTH]"
+.Fc
+.Ft int
+.Fo ED25519_sign
+.Fa "uint8_t *out_sig"
+.Fa "const uint8_t *message"
+.Fa "size_t message_len"
+.Fa "const uint8_t public_key[ED25519_PUBLIC_KEY_LENGTH]"
+.Fa "const uint8_t private_key_seed[ED25519_PRIVATE_KEY_LENGTH]"
+.Fc
+.Ft int
+.Fo ED25519_verify
+.Fa "const uint8_t *message"
+.Fa "size_t message_len"
+.Fa "const uint8_t signature[ED25519_SIGNATURE_LENGTH]"
+.Fa "const uint8_t public_key[ED25519_PUBLIC_KEY_LENGTH]"
+.Fc
 .Sh DESCRIPTION
-Curve25519 is an elliptic curve over a prime field specified in RFC 7748.
+Curve25519 is an elliptic curve over a prime field
+specified in RFC 7748 section 4.1.
 The prime field is defined by the prime number 2^255 - 19.
 .Pp
-.Fn X25519
+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
@@ -85,17 +116,96 @@ by multiplying it with the Montgomery base point
 The size of a public and private key is
 .Dv X25519_KEY_LENGTH No = 32
 bytes each.
+.Pp
+Ed25519 is a signature scheme using a twisted Edwards curve
+that is birationally equivalent to Curve25519.
+.Pp
+.Fn ED25519_keypair
+sets
+.Fa out_public_key
+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
+.Fa out_public_key
+is calculated from the private key.
+.Pp
+.Fn ED25519_sign
+signs the
+.Fa message
+of
+.Fa message_len
+bytes using the
+.Fa public_key
+and the
+.Fa private_key
+and writes the signature to
+.Fa out_sig .
+.Pp
+.Fn ED25519_verify
+checks that signing the
+.Fa message
+of
+.Fa message_len
+bytes using the
+.Fa public_key
+would indeed result in the given
+.Fa signature .
+.Pp
+The sizes of a public and private keys are
+.Dv ED25519_PUBLIC_KEY_LENGTH
+and
+.Dv ED25519_PRIVATE_KEY_LENGTH ,
+which are both 32 bytes, and the size of a signature is
+.Dv ED25519_SIGNATURE_LENGTH No = 64
+bytes.
 .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.
+and
+.Fn ED25519_sign
+return 1 on success or 0 on error.
+.Fn X25519
+can fail if the input is a point of small order.
+.Fn ED25519_sign
+always succeeds in LibreSSL, but the API reserves the return value 0
+for memory allocation failure.
+.Pp
+.Fn ED25519_verify
+returns 1 if the
+.Fa signature
+is valid or 0 otherwise.
 .Sh SEE ALSO
-.Xr ECDH_compute_key 3
+.Xr ECDH_compute_key 3 ,
+.Xr EVP_DigestSign 3 ,
+.Xr EVP_DigestVerify 3 ,
+.Xr EVP_PKEY_derive 3 ,
+.Xr EVP_PKEY_keygen 3
 .Rs
-.%A D. J. Bernstein
+.%A Daniel J. Bernstein
 .%R A state-of-the-art Diffie-Hellman function:\
     How do I use Curve25519 in my own software?
 .%U https://cr.yp.to/ecdh.html
 .Re
+.Rs
+.%A Daniel J. Bernstein
+.%A Niels Duif
+.%A Tanja Lange
+.%A Peter Schwabe
+.%A Bo-Yin Yang
+.%T High-Speed High-Security Signatures
+.%B Cryptographic Hardware and Embedded Systems \(em CHES 2011
+.%I Springer
+.%J Lecture Notes in Computer Science
+.%V vol 6917
+.%U https://doi.org/10.1007/978-3-642-23951-9_9
+.%C Nara, Japan
+.%D September 29, 2011
+.Re
 .Sh STANDARDS
 RFC 7748: Elliptic Curves for Security
+.Pp
+RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)