1=pod
2
3=head1 NAME
4
5EVP_SIGNATURE-ED25519,
6EVP_SIGNATURE-ED448,
7Ed25519,
8Ed448
9- EVP_PKEY Ed25519 and Ed448 support
10
11=head1 DESCRIPTION
12
13The B<Ed25519> and B<Ed448> EVP_PKEY implementation supports key
14generation, one-shot digest-sign and digest-verify using the EdDSA
15signature schemes described in RFC 8032. It has associated private and
16public key formats compatible with RFC 8410.
17
18=head2 EdDSA Instances
19
20RFC 8032 describes five EdDSA instances: Ed25519, Ed25519ctx,
21Ed25519ph, Ed448, Ed448ph.
22
23The instances Ed25519, Ed25519ctx, Ed448 are referred to as B<PureEdDSA>
24schemes.  For these three instances, the sign and verify procedures
25require access to the complete message (not a digest of the message).
26
27The instances Ed25519ph, Ed448ph are referred to as B<HashEdDSA>
28schemes.  For these two instances, the sign and verify procedures do
29not require access to the complete message; they operate on a hash of
30the message.  For Ed25519ph, the hash function is SHA512.  For
31Ed448ph, the hash function is SHAKE256 with an output length of 512
32bits.
33
34The instances Ed25519ctx, Ed25519ph, Ed448, Ed448ph accept an optional
35B<context-string> as input to sign and verify operations (and for
36Ed25519ctx, the context-string must be nonempty).  For the Ed25519
37instance, a nonempty context-string is not permitted.
38
39These instances can be specified as signature parameters when using
40L<EVP_DigestSignInit(3)> and L<EVP_DigestVerifyInit(3)>, see
41L</ED25519 and ED448 Signature Parameters> below.
42
43These instances are also explicitly fetchable as algorithms using
44L<EVP_SIGNATURE_fetch(3)>, which can be used with
45L<EVP_PKEY_sign_init_ex2(3)>, L<EVP_PKEY_verify_init_ex2(3)>,
46L<EVP_PKEY_sign_message_init(3)> and L<EVP_PKEY_verify_message_init(3)>.
47
48=head2 ED25519 and ED448 Signature Parameters
49
50Two parameters can be set during signing or verification: the EdDSA
51B<instance name> and the B<context-string value>.  They can be set by
52passing an OSSL_PARAM array to EVP_DigestSignInit_ex().
53
54=over 4
55
56=item * "instance" (B<OSSL_SIGNATURE_PARAM_INSTANCE>) <utf8 string>
57
58One of the five strings "Ed25519", "Ed25519ctx", "Ed25519ph", "Ed448", "Ed448ph".
59
60"Ed25519", "Ed25519ctx", "Ed25519ph" are valid only for an Ed25519 EVP_PKEY.
61
62"Ed448", "Ed448ph" are valid only for an Ed448 EVP_PKEY.
63
64=item * "context-string" (B<OSSL_SIGNATURE_PARAM_CONTEXT_STRING>) <octet string>
65
66A string of octets with length at most 255.
67
68=back
69
70Both of these parameters are optional.
71
72When using L<EVP_DigestSignInit(3)> or L<EVP_DigestVerifyInit(3)>, the
73signature algorithm is derived from the key type name.  The key type name
74("Ed25519" or "Ed448") is also the default for the instance, but this can be
75changed with the "instance" parameter.
76
77Note that a message digest name must B<NOT> be specified when signing
78or verifying.
79
80When using L<EVP_PKEY_sign_init_ex2(3)>, L<EVP_PKEY_verify_init_ex2(3)>,
81L<EVP_PKEY_sign_message_init(3)> or L<EVP_PKEY_verify_message_init(3)>, the
82instance is the explicit signature algorithm name, and may not be changed
83(trying to give one with the "instance" parameter is therefore an error).
84
85If a context-string is not specified, then an empty context-string is
86used.
87
88See L<EVP_PKEY-X25519(7)> for information related to B<X25519> and B<X448> keys.
89
90The following signature parameters can be retrieved using
91EVP_PKEY_CTX_get_params().
92
93=over 4
94
95=item * "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string>
96
97=item * "instance" (B<OSSL_SIGNATURE_PARAM_INSTANCE>) <utf8 string>
98
99=item * "context-string" (B<OSSL_SIGNATURE_PARAM_CONTEXT_STRING>) <octet string>
100
101=back
102
103The parameters are described in L<provider-signature(7)>.
104
105=head1 NOTES
106
107The PureEdDSA instances do not support the streaming mechanism of
108other signature algorithms using, for example, EVP_DigestUpdate().
109The message to sign or verify must be passed using the one-shot
110EVP_DigestSign() and EVP_DigestVerify() functions.
111
112The HashEdDSA instances do not yet support the streaming mechanisms
113(so the one-shot functions must be used with HashEdDSA as well).
114
115When calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the
116digest I<type> parameter B<MUST> be set to NULL.
117
118Applications wishing to sign certificates (or other structures such as
119CRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign()
120or X509_sign_ctx() in the usual way.
121
122Ed25519 or Ed448 private keys can be set directly using
123L<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file
124using L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys
125can also be generated (see the example below). Setting a private key also sets
126the associated public key.
127
128Ed25519 or Ed448 public keys can be set directly using
129L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
130structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
131
132Ed25519 and Ed448 can be tested with the L<openssl-speed(1)> application
133since version 1.1.1.
134Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is
135specified, then both Ed25519 and Ed448 are benchmarked.
136
137=head1 EXAMPLES
138
139To sign a message using an ED25519 EVP_PKEY structure:
140
141    void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len)
142    {
143        size_t sig_len;
144        unsigned char *sig = NULL;
145        EVP_MD_CTX *md_ctx = EVP_MD_CTX_new();
146
147        const OSSL_PARAM params[] = {
148            OSSL_PARAM_utf8_string ("instance", "Ed25519ctx", 10),
149            OSSL_PARAM_octet_string("context-string", (unsigned char *)"A protocol defined context string", 33),
150            OSSL_PARAM_END
151        };
152
153        /* The input "params" is not needed if default options are acceptable.
154           Use NULL in place of "params" in that case. */
155        EVP_DigestSignInit_ex(md_ctx, NULL, NULL, NULL, NULL, ed_key, params);
156        /* Calculate the required size for the signature by passing a NULL buffer. */
157        EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len);
158        sig = OPENSSL_zalloc(sig_len);
159
160        EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len);
161        ...
162        OPENSSL_free(sig);
163        EVP_MD_CTX_free(md_ctx);
164    }
165
166=head1 SEE ALSO
167
168L<EVP_PKEY-X25519(7)>
169L<provider-signature(7)>,
170L<EVP_DigestSignInit(3)>,
171L<EVP_DigestVerifyInit(3)>,
172
173=head1 COPYRIGHT
174
175Copyright 2017-2024 The OpenSSL Project Authors. All Rights Reserved.
176
177Licensed under the Apache License 2.0 (the "License").  You may not use
178this file except in compliance with the License.  You can obtain a copy
179in the file LICENSE in the source distribution or at
180L<https://www.openssl.org/source/license.html>.
181
182=cut
183