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