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