Support all five EdDSA instances from RFC 8032

Fixes #6277

Description:
Make each of the five EdDSA instances defined in RFC 8032 -- Ed25519,
Ed25519ctx, Ed25519ph, Ed448, Ed448ph -- available via the EVP APIs.

The desired EdDSA instance is specified via an OSSL_PARAM.

All instances, except for Ed25519, allow context strings as input.
Context strings are passed via an OSSL_PARAM.  For Ed25519ctx, the
context string must be nonempty.

Ed25519, Ed25519ctx, Ed448 are PureEdDSA instances, which means that
the full message (not a digest) must be passed to sign and verify
operations.

Ed25519ph, Ed448ph are HashEdDSA instances, which means that the input
message is hashed before sign and verify.

Testing:
All 21 test vectors from RFC 8032 have been added to evppkey_ecx.txt
(thanks to Shane Lontis for showing how to do that).  Those 21 test
vectors are exercised by evp_test.c and cover all five instances.

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/19705)

1 files changed, 78 insertions, 14 deletions

diff --git a/doc/man7/EVP_SIGNATURE-ED25519.pod b/doc/man7/EVP_SIGNATURE-ED25519.pod
index 2183d83c2e..dbb7de3279 100644
--- a/doc/man7/EVP_SIGNATURE-ED25519.pod
+++ b/doc/man7/EVP_SIGNATURE-ED25519.pod
@@ -10,16 +10,65 @@ Ed448
 
 =head1 DESCRIPTION
 
-The B<Ed25519> and B<Ed448> EVP_PKEY implementation supports key generation,
-one-shot digest sign and digest verify using PureEdDSA and B<Ed25519> or B<Ed448>
-(see RFC8032). It has associated private and public key formats compatible with
-RFC 8410.
+The B<Ed25519> and B<Ed448> EVP_PKEY implementation supports key
+generation, one-shot digest-sign and digest-verify using the EdDSA
+signature scheme described in RFC 8032. It has associated private and
+public key formats compatible with RFC 8410.
+
+=head2 EdDSA Instances
+
+RFC 8032 describes five EdDSA instances: Ed25519, Ed25519ctx,
+Ed25519ph, Ed448, Ed448ph.
+
+The instances Ed25519, Ed25519ctx, Ed448 are referred to as B<PureEdDSA>
+schemes.  For these three instances, the sign and verify procedures
+require access to the complete message (not a digest of the message).
+
+The instances Ed25519ph, Ed448ph are referred to as B<HashEdDSA>
+schemes.  For these two instances, the sign and verify procedures do
+not require access to the complete message; they operate on a hash of
+the message.  For Ed25519ph, the hash function is SHA512.  For
+Ed448ph, the hash function is SHAKE256 with an output length of 512
+bits.
+
+The instances Ed25519ctx, Ed25519ph, Ed448, Ed448ph accept an optional
+B<context-string> as input to sign and verify operations (and for
+Ed25519ctx, the context-string must be nonempty).  For the Ed25519
+instance, a nonempty context-string is not permitted.
 
 =head2 ED25519 and ED448 Signature Parameters
 
-No additional parameters can be set during one-shot signing or verification.
-In particular, because PureEdDSA is used, a digest must B<NOT> be specified when
-signing or verifying.
+Two parameters can be set during signing or verification: the EdDSA
+B<instance name> and the B<context-string value>.  They can be set by
+passing an OSSL_PARAM array to EVP_DigestSignInit_ex().
+
+=over 4
+
+=item * "instance" (B<OSSL_SIGNATURE_PARAM_INSTANCE>) <utf8 string>
+
+One of the five strings "Ed25519", "Ed25519ctx", "Ed25519ph", "Ed448", "Ed448ph".
+
+"Ed25519", "Ed25519ctx", "Ed25519ph" are valid only for an Ed25519 EVP_PKEY.
+
+"Ed448", "Ed448ph" are valid only for an Ed448 EVP_PKEY.
+
+=item * "context-string" (B<OSSL_SIGNATURE_PARAM_CONTEXT_STRING>) <octet string>
+
+A string of octets with length at most 255.
+
+=back
+
+Both of these parameters are optional.
+
+If the instance name is not specified, then the default "Ed25519" or
+"Ed448" is used.
+
+If a context-string is not specified, then an empty context-string is
+used.
+
+Note that a message digest name must B<NOT> be specified when signing
+or verifying.
+
 See L<EVP_PKEY-X25519(7)> for information related to B<X25519> and B<X448> keys.
 
 The following signature parameters can be retrieved using
@@ -27,19 +76,26 @@ EVP_PKEY_CTX_get_params().
 
 =over 4
 
-=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
+=item * "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
 
-The parameters are described in L<provider-signature(7)>.
+=item * "instance" (B<OSSL_SIGNATURE_PARAM_INSTANCE>) <utf8 string>
+
+=item * "context-string" (B<OSSL_SIGNATURE_PARAM_CONTEXT_STRING>) <octet string>
 
 =back
 
+The parameters are described in L<provider-signature(7)>.
+
 =head1 NOTES
 
-The PureEdDSA algorithm does not support the streaming mechanism
-of other signature algorithms using, for example, EVP_DigestUpdate().
+The PureEdDSA instances do not support the streaming mechanism of
+other signature algorithms using, for example, EVP_DigestUpdate().
 The message to sign or verify must be passed using the one-shot
 EVP_DigestSign() and EVP_DigestVerify() functions.
 
+The HashEdDSA instances do not yet support the streaming mechanisms
+(so the one-shot functions must be used with HashEdDSA as well).
+
 When calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the
 digest I<type> parameter B<MUST> be set to NULL.
 
@@ -64,7 +120,7 @@ specified, then both Ed25519 and Ed448 are benchmarked.
 
 =head1 EXAMPLES
 
-To sign a message using a ED25519 or ED448 key:
+To sign a message using an ED25519 EVP_PKEY structure:
 
     void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len)
     {
@@ -72,8 +128,16 @@ To sign a message using a ED25519 or ED448 key:
         unsigned char *sig = NULL;
         EVP_MD_CTX *md_ctx = EVP_MD_CTX_new();
 
-        EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, ed_key);
-        /* Calculate the requires size for the signature by passing a NULL buffer */
+        const OSSL_PARAM params[] = {
+            OSSL_PARAM_utf8_string ("instance", "Ed25519ctx", 10),
+            OSSL_PARAM_octet_string("context-string", (unsigned char *)"A protocol defined context string", 33),
+            OSSL_PARAM_END
+        };
+
+        /* The input "params" is not needed if default options are acceptable.
+           Use NULL in place of "params" in that case. */
+        EVP_DigestSignInit_ex(md_ctx, NULL, NULL, NULL, NULL, ed_key, params);
+        /* Calculate the required size for the signature by passing a NULL buffer. */
         EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len);
         sig = OPENSSL_zalloc(sig_len);