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