1*b077aed3SPierre Pronchery=pod 2*b077aed3SPierre Pronchery 3*b077aed3SPierre Pronchery=head1 NAME 4*b077aed3SPierre Pronchery 5*b077aed3SPierre ProncheryEVP_SIGNATURE-ED25519, 6*b077aed3SPierre ProncheryEVP_SIGNATURE-ED448, 7*b077aed3SPierre ProncheryEd25519, 8*b077aed3SPierre ProncheryEd448 9*b077aed3SPierre Pronchery- EVP_PKEY Ed25519 and Ed448 support 10*b077aed3SPierre Pronchery 11*b077aed3SPierre Pronchery=head1 DESCRIPTION 12*b077aed3SPierre Pronchery 13*b077aed3SPierre ProncheryThe B<Ed25519> and B<Ed448> EVP_PKEY implementation supports key generation, 14*b077aed3SPierre Proncheryone-shot digest sign and digest verify using PureEdDSA and B<Ed25519> or B<Ed448> 15*b077aed3SPierre Pronchery(see RFC8032). It has associated private and public key formats compatible with 16*b077aed3SPierre ProncheryRFC 8410. 17*b077aed3SPierre Pronchery 18*b077aed3SPierre Pronchery=head2 ED25519 and ED448 Signature Parameters 19*b077aed3SPierre Pronchery 20*b077aed3SPierre ProncheryNo additional parameters can be set during one-shot signing or verification. 21*b077aed3SPierre ProncheryIn particular, because PureEdDSA is used, a digest must B<NOT> be specified when 22*b077aed3SPierre Proncherysigning or verifying. 23*b077aed3SPierre ProncherySee L<EVP_PKEY-X25519(7)> for information related to B<X25519> and B<X448> keys. 24*b077aed3SPierre Pronchery 25*b077aed3SPierre ProncheryThe following signature parameters can be retrieved using 26*b077aed3SPierre ProncheryEVP_PKEY_CTX_get_params(). 27*b077aed3SPierre Pronchery 28*b077aed3SPierre Pronchery=over 4 29*b077aed3SPierre Pronchery 30*b077aed3SPierre Pronchery=item "algorithm-id" (B<OSSL_SIGNATURE_PARAM_ALGORITHM_ID>) <octet string> 31*b077aed3SPierre Pronchery 32*b077aed3SPierre ProncheryThe parameters are described in L<provider-signature(7)>. 33*b077aed3SPierre Pronchery 34*b077aed3SPierre Pronchery=back 35*b077aed3SPierre Pronchery 36*b077aed3SPierre Pronchery=head1 NOTES 37*b077aed3SPierre Pronchery 38*b077aed3SPierre ProncheryThe PureEdDSA algorithm does not support the streaming mechanism 39*b077aed3SPierre Proncheryof other signature algorithms using, for example, EVP_DigestUpdate(). 40*b077aed3SPierre ProncheryThe message to sign or verify must be passed using the one-shot 41*b077aed3SPierre ProncheryEVP_DigestSign() and EVP_DigestVerify() functions. 42*b077aed3SPierre Pronchery 43*b077aed3SPierre ProncheryWhen calling EVP_DigestSignInit() or EVP_DigestVerifyInit(), the 44*b077aed3SPierre Proncherydigest I<type> parameter B<MUST> be set to NULL. 45*b077aed3SPierre Pronchery 46*b077aed3SPierre ProncheryApplications wishing to sign certificates (or other structures such as 47*b077aed3SPierre ProncheryCRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign() 48*b077aed3SPierre Proncheryor X509_sign_ctx() in the usual way. 49*b077aed3SPierre Pronchery 50*b077aed3SPierre ProncheryEd25519 or Ed448 private keys can be set directly using 51*b077aed3SPierre ProncheryL<EVP_PKEY_new_raw_private_key(3)> or loaded from a PKCS#8 private key file 52*b077aed3SPierre Proncheryusing L<PEM_read_bio_PrivateKey(3)> (or similar function). Completely new keys 53*b077aed3SPierre Proncherycan also be generated (see the example below). Setting a private key also sets 54*b077aed3SPierre Proncherythe associated public key. 55*b077aed3SPierre Pronchery 56*b077aed3SPierre ProncheryEd25519 or Ed448 public keys can be set directly using 57*b077aed3SPierre ProncheryL<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo 58*b077aed3SPierre Proncherystructure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function). 59*b077aed3SPierre Pronchery 60*b077aed3SPierre ProncheryEd25519 and Ed448 can be tested with the L<openssl-speed(1)> application 61*b077aed3SPierre Proncherysince version 1.1.1. 62*b077aed3SPierre ProncheryValid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is 63*b077aed3SPierre Proncheryspecified, then both Ed25519 and Ed448 are benchmarked. 64*b077aed3SPierre Pronchery 65*b077aed3SPierre Pronchery=head1 EXAMPLES 66*b077aed3SPierre Pronchery 67*b077aed3SPierre ProncheryTo sign a message using a ED25519 or ED448 key: 68*b077aed3SPierre Pronchery 69*b077aed3SPierre Pronchery void do_sign(EVP_PKEY *ed_key, unsigned char *msg, size_t msg_len) 70*b077aed3SPierre Pronchery { 71*b077aed3SPierre Pronchery size_t sig_len; 72*b077aed3SPierre Pronchery unsigned char *sig = NULL; 73*b077aed3SPierre Pronchery EVP_MD_CTX *md_ctx = EVP_MD_CTX_new(); 74*b077aed3SPierre Pronchery 75*b077aed3SPierre Pronchery EVP_DigestSignInit(md_ctx, NULL, NULL, NULL, ed_key); 76*b077aed3SPierre Pronchery /* Calculate the requires size for the signature by passing a NULL buffer */ 77*b077aed3SPierre Pronchery EVP_DigestSign(md_ctx, NULL, &sig_len, msg, msg_len); 78*b077aed3SPierre Pronchery sig = OPENSSL_zalloc(sig_len); 79*b077aed3SPierre Pronchery 80*b077aed3SPierre Pronchery EVP_DigestSign(md_ctx, sig, &sig_len, msg, msg_len); 81*b077aed3SPierre Pronchery ... 82*b077aed3SPierre Pronchery OPENSSL_free(sig); 83*b077aed3SPierre Pronchery EVP_MD_CTX_free(md_ctx); 84*b077aed3SPierre Pronchery } 85*b077aed3SPierre Pronchery 86*b077aed3SPierre Pronchery=head1 SEE ALSO 87*b077aed3SPierre Pronchery 88*b077aed3SPierre ProncheryL<EVP_PKEY-X25519(7)> 89*b077aed3SPierre ProncheryL<provider-signature(7)>, 90*b077aed3SPierre ProncheryL<EVP_DigestSignInit(3)>, 91*b077aed3SPierre ProncheryL<EVP_DigestVerifyInit(3)>, 92*b077aed3SPierre Pronchery 93*b077aed3SPierre Pronchery=head1 COPYRIGHT 94*b077aed3SPierre Pronchery 95*b077aed3SPierre ProncheryCopyright 2017-2021 The OpenSSL Project Authors. All Rights Reserved. 96*b077aed3SPierre Pronchery 97*b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 98*b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 99*b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 100*b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 101*b077aed3SPierre Pronchery 102*b077aed3SPierre Pronchery=cut 103