Debian Codegraph @

upstream/debian-unstable/man7/EVP_SIGNATURE-ED25519.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_SIGNATURE-ED25519 7SSL"
58 .TH EVP_SIGNATURE-ED25519 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_SIGNATURE\-ED25519,
65 EVP_SIGNATURE\-ED448,
66 Ed25519,
67 Ed448
68 \&\- The EVP_PKEY Ed25519 and Ed448 signature implementations
69 .SH DESCRIPTION
70 .IX Header "DESCRIPTION"
71 The \fBEd25519\fR and \fBEd448\fR EVP_PKEY implementation supports key
72 generation, one-shot digest-sign and digest-verify using the EdDSA
73 signature schemes described in RFC 8032. It has associated private and
74 public key formats compatible with RFC 8410.
75 .SS "EdDSA Instances"
76 .IX Subsection "EdDSA Instances"
77 RFC 8032 describes five EdDSA instances: Ed25519, Ed25519ctx,
78 Ed25519ph, Ed448, Ed448ph.
79 .PP
80 The instances Ed25519, Ed25519ctx, Ed448 are referred to as \fBPureEdDSA\fR
81 schemes. For these three instances, the sign and verify procedures
82 require access to the complete message (not a digest of the message).
83 .PP
84 The instances Ed25519ph, Ed448ph are referred to as \fBHashEdDSA\fR
85 schemes. For these two instances, the sign and verify procedures do
86 not require access to the complete message; they operate on a hash of
87 the message. For Ed25519ph, the hash function is SHA512. For
88 Ed448ph, the hash function is SHAKE256 with an output length of 512
89 bits.
90 .PP
91 The instances Ed25519ctx, Ed25519ph, Ed448, Ed448ph accept an optional
92 \&\fBcontext-string\fR as input to sign and verify operations (and for
93 Ed25519ctx, the context-string must be nonempty). For the Ed25519
94 instance, a nonempty context-string is not permitted.
95 .PP
96 These instances can be specified as signature parameters when using
97 \&\fBEVP_DigestSignInit\fR\|(3) and \fBEVP_DigestVerifyInit\fR\|(3), see
98 "ED25519 and ED448 Signature Parameters" below.
99 .PP
100 These instances are also explicitly fetchable as algorithms using
101 \&\fBEVP_SIGNATURE_fetch\fR\|(3), which can be used with
102 \&\fBEVP_PKEY_sign_init_ex2\fR\|(3), \fBEVP_PKEY_verify_init_ex2\fR\|(3),
103 \&\fBEVP_PKEY_sign_message_init\fR\|(3) and \fBEVP_PKEY_verify_message_init\fR\|(3).
104 .SS "ED25519 and ED448 Signature Parameters"
105 .IX Subsection "ED25519 and ED448 Signature Parameters"
106 Two parameters can be set during signing or verification: the EdDSA
107 \&\fBinstance name\fR and the \fBcontext-string value\fR. They can be set by
108 passing an OSSL_PARAM array to \fBEVP_DigestSignInit_ex()\fR.
109 .IP \(bu 4
110 "instance" (\fBOSSL_SIGNATURE_PARAM_INSTANCE\fR) <utf8 string>
111 .Sp
112 One of the five strings "Ed25519", "Ed25519ctx", "Ed25519ph", "Ed448", "Ed448ph".
113 .Sp
114 "Ed25519", "Ed25519ctx", "Ed25519ph" are valid only for an Ed25519 EVP_PKEY.
115 .Sp
116 "Ed448", "Ed448ph" are valid only for an Ed448 EVP_PKEY.
117 .IP \(bu 4
118 "context-string" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) <octet string>
119 .Sp
120 A string of octets with length at most 255.
121 .PP
122 Both of these parameters are optional.
123 .PP
124 When using \fBEVP_DigestSignInit\fR\|(3) or \fBEVP_DigestVerifyInit\fR\|(3), the
125 signature algorithm is derived from the key type name. The key type name
126 ("Ed25519" or "Ed448") is also the default for the instance, but this can be
127 changed with the "instance" parameter.
128 .PP
129 Note that a message digest name must \fBNOT\fR be specified when signing
130 or verifying.
131 .PP
132 When using \fBEVP_PKEY_sign_init_ex2\fR\|(3), \fBEVP_PKEY_verify_init_ex2\fR\|(3),
133 \&\fBEVP_PKEY_sign_message_init\fR\|(3) or \fBEVP_PKEY_verify_message_init\fR\|(3), the
134 instance is the explicit signature algorithm name, and may not be changed
135 (trying to give one with the "instance" parameter is therefore an error).
136 .PP
137 If a context-string is not specified, then an empty context-string is
138 used.
139 .PP
140 See \fBEVP_PKEY\-X25519\fR\|(7) for information related to \fBX25519\fR and \fBX448\fR keys.
141 .PP
142 The following signature parameters can be retrieved using
143 \&\fBEVP_PKEY_CTX_get_params()\fR.
144 .IP \(bu 4
145 "algorithm-id" (\fBOSSL_SIGNATURE_PARAM_ALGORITHM_ID\fR) <octet string>
146 .IP \(bu 4
147 "instance" (\fBOSSL_SIGNATURE_PARAM_INSTANCE\fR) <utf8 string>
148 .IP \(bu 4
149 "context-string" (\fBOSSL_SIGNATURE_PARAM_CONTEXT_STRING\fR) <octet string>
150 .PP
151 The parameters are described in \fBprovider\-signature\fR\|(7).
152 .SH NOTES
153 .IX Header "NOTES"
154 The PureEdDSA instances do not support the streaming mechanism of
155 other signature algorithms using, for example, \fBEVP_DigestUpdate()\fR.
156 The message to sign or verify must be passed using the one-shot
157 \&\fBEVP_DigestSign()\fR and \fBEVP_DigestVerify()\fR functions.
158 .PP
159 The HashEdDSA instances do not yet support the streaming mechanisms
160 (so the one-shot functions must be used with HashEdDSA as well).
161 .PP
162 When calling \fBEVP_DigestSignInit()\fR or \fBEVP_DigestVerifyInit()\fR, the
163 digest \fItype\fR parameter \fBMUST\fR be set to NULL.
164 .PP
165 Applications wishing to sign certificates (or other structures such as
166 CRLs or certificate requests) using Ed25519 or Ed448 can either use \fBX509_sign()\fR
167 or \fBX509_sign_ctx()\fR in the usual way.
168 .PP
169 Ed25519 or Ed448 private keys can be set directly using
170 \&\fBEVP_PKEY_new_raw_private_key\fR\|(3) or loaded from a PKCS#8 private key file
171 using \fBPEM_read_bio_PrivateKey\fR\|(3) (or similar function). Completely new keys
172 can also be generated (see the example below). Setting a private key also sets
173 the associated public key.
174 .PP
175 Ed25519 or Ed448 public keys can be set directly using
176 \&\fBEVP_PKEY_new_raw_public_key\fR\|(3) or loaded from a SubjectPublicKeyInfo
177 structure in a PEM file using \fBPEM_read_bio_PUBKEY\fR\|(3) (or similar function).
178 .PP
179 Ed25519 and Ed448 can be tested with the \fBopenssl\-speed\fR\|(1) application
180 since version 1.1.1.
181 Valid algorithm names are \fBed25519\fR, \fBed448\fR and \fBeddsa\fR. If \fBeddsa\fR is
182 specified, then both Ed25519 and Ed448 are benchmarked.
183 .PP
184 Since Ed25519ctx is not included in FIPS 186\-5, it is not present
185 in the FIPS provider.
186 .SH EXAMPLES
187 .IX Header "EXAMPLES"
188 To sign a message using an ED25519 EVP_PKEY structure:
189 .PP
190 .Vb 5
191 \& void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len)
192 \& {
193 \& size_t sig_len;
194 \& unsigned char *sig = NULL;
195 \& EVP_MD_CTX *md_ctx = EVP_MD_CTX_new();
196 \&
197 \& const OSSL_PARAM params[] = {
198 \& OSSL_PARAM_utf8_string ("instance", "Ed25519ctx", 10),
199 \& OSSL_PARAM_octet_string("context\-string", (unsigned char *)"A protocol defined context string", 33),
200 \& OSSL_PARAM_END
201 \& };
202 \&
203 \& /* The input "params" is not needed if default options are acceptable.
204 \& Use NULL in place of "params" in that case. */
205 \& EVP_DigestSignInit_ex(md_ctx, NULL, NULL, NULL, NULL, ed_key, params);
206 \& /* Calculate the required size for the signature by passing a NULL buffer. */
207 \& EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len);
208 \& sig = OPENSSL_zalloc(sig_len);
209 \&
210 \& EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len);
211 \& ...
212 \& OPENSSL_free(sig);
213 \& EVP_MD_CTX_free(md_ctx);
214 \& }
215 .Ve
216 .SH "SEE ALSO"
217 .IX Header "SEE ALSO"
218 \&\fBEVP_PKEY\-X25519\fR\|(7)
219 \&\fBprovider\-signature\fR\|(7),
220 \&\fBEVP_DigestSignInit\fR\|(3),
221 \&\fBEVP_DigestVerifyInit\fR\|(3),
222 .SH COPYRIGHT
223 .IX Header "COPYRIGHT"
224 Copyright 2017\-2026 The OpenSSL Project Authors. All Rights Reserved.
225 .PP
226 Licensed under the Apache License 2.0 (the "License"). You may not use
227 this file except in compliance with the License. You can obtain a copy
228 in the file LICENSE in the source distribution or at
229 <https://www.openssl.org/source/license.html>.