Commit a2eecb5d authored by Matt Caswell's avatar Matt Caswell
Browse files

Update some documentation for X448/Ed448 



Reviewed-by: default avatarRich Salz <rsalz@openssl.org>
Reviewed-by: default avatarKurt Roeckx <kurt@roeckx.be>
(Merged from https://github.com/openssl/openssl/pull/5481)
parent 13735cfe

doc/HOWTO/keys.txt

+1 −1
Original line number Diff line number Diff line
@@ -98,7 +98,7 @@ it may be reasonable to avoid protecting it with a password, since 
otherwise someone would have to type in the password every time the

server needs to access the key.



For X25519, it's treated as a distinct algorithm but not as one of

For X25519 and X448, it's treated as a distinct algorithm but not as one of

the curves listed with 'ecparam -list_curves' option. You can use

the following command to generate an X25519 key:

doc/man1/genpkey.pod

+3 −3
Original line number Diff line number Diff line
@@ -241,10 +241,10 @@ numeric OID. Following parameter sets are supported: 


=back



=head1 X25519 KEY GENERATION OPTIONS



The X25519 algorithm does not currently support any key generation options.

=head1 X25519 and X448 KEY GENERATION OPTIONS



The X25519 and X448 algorithms do not currently support any key generation

options.



=head1 NOTES

doc/man1/pkeyutl.pod

+3 −3
Original line number Diff line number Diff line
@@ -282,10 +282,10 @@ verify operations use ECDSA and derive uses ECDH. Currently there are no 
additional options other than B<digest>. Only the SHA1 digest can be used and

this digest is assumed by default.



=head1 X25519 ALGORITHM

=head1 X25519 and X448 ALGORITHMS



The X25519 algorithm supports key derivation only. Currently there are no

additional options.

The X25519 and X448 algorithms support key derivation only. Currently there are

no additional options.



=head1 EXAMPLES

doc/man7/Ed25519.pod

+14 −8
Original line number Diff line number Diff line
@@ -2,16 +2,18 @@ 


=head1 NAME



Ed25519 - EVP_PKEY Ed25519 support

Ed25519,

Ed448

- EVP_PKEY Ed25519 and Ed448 support



=head1 DESCRIPTION



The B<Ed25519> EVP_PKEY implementation supports key generation, one shot

digest sign and digest verify using PureEdDSA and B<Ed25519> (see RFC8032).

It has associated private and public key formats compatible with

The B<Ed25519> and B<Ed448> EVP_PKEY implementation supports key generation,

one-shot digest sign and digest verify using PureEdDSA and B<Ed25519> or B<Ed448>

(see RFC8032). It has associated private and public key formats compatible with

draft-ietf-curdle-pkix-04.



No additional parameters can be set during key generation one shot signing or

No additional parameters can be set during key generation one-shot signing or

verification. In particular, because PureEdDSA is used, when signing or

verifying a digest must B<NOT> be specified.
@@ -19,20 +21,24 @@ verifying a digest must B<NOT> be specified. 


The PureEdDSA algorithm does not support the streaming mechanism

of other signature algorithms using, for example, EVP_DigestUpdate().

The message to sign or verify must be passed using the one shot

The message to sign or verify must be passed using the one-shot

EVP_DigestSign() asn EVP_DigestVerify() functions.



When calling EVP_DigestSignInit() or EVP_DigestSignUpdate() the

digest parameter B<MUST> be set to B<NULL>.



Applications wishing to sign certificates (or other structures such as

CRLs or certificate requests) using Ed25519 can either use X509_sign()

CRLs or certificate requests) using Ed25519 or Ed448 can either use X509_sign()

or X509_sign_ctx() in the usual way.



A context for the B<Ed25519> algorithm can be obtained by calling:



 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED25519, NULL);



For the B<Ed448> algorithm a context can be obtained by calling:



 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_ED448, NULL);



=head1 EXAMPLE



This example generates an B<ED25519> private key and writes it to standard
@@ -57,7 +63,7 @@ L<EVP_DigestVerifyInit(3)>, 


=head1 COPYRIGHT



Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.



Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

doc/man7/X25519.pod

+12 −6
Original line number Diff line number Diff line
@@ -2,13 +2,15 @@ 


=head1 NAME



X25519 - EVP_PKEY X25519 support

X25519,

X448

- EVP_PKEY X25519 and X448 support



=head1 DESCRIPTION



The B<X25519> EVP_PKEY implementation supports key generation and key

derivation using B<X25519>. It has associated private and public key formats

compatible with draft-ietf-curdle-pkix-03.

The B<X25519> and B<X448> EVP_PKEY implementation supports key generation and

key derivation using B<X25519> and B<X448>. It has associated private and public

key formats compatible with draft-ietf-curdle-pkix-03.



No additional parameters can be set during key generation.
@@ -21,6 +23,10 @@ A context for the B<X25519> algorithm can be obtained by calling: 


 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X25519, NULL);



For the B<X448> algorithm a context can be obtained by calling:



 EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_X448, NULL);



=head1 EXAMPLE



This example generates an B<X25519> private key and writes it to standard
@@ -37,7 +43,7 @@ output in PEM format: 
 PEM_write_PrivateKey(stdout, pkey, NULL, NULL, 0, NULL, NULL);



The key derivation example in L<EVP_PKEY_derive(3)> can be used with

B<X25519>.

B<X25519> and B<X448>.



=head1 SEE ALSO
@@ -48,7 +54,7 @@ L<EVP_PKEY_derive_set_peer(3)> 


=head1 COPYRIGHT



Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.

Copyright 2017-2018 The OpenSSL Project Authors. All Rights Reserved.



Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy