mirror of https://github.com/openssl/openssl.git
142 lines
3.7 KiB
Plaintext
142 lines
3.7 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
EVP_PKEY-X25519, EVP_PKEY-X448, EVP_PKEY-ED25519, EVP_PKEY-ED448,
|
|
EVP_KEYMGMT-X25519, EVP_KEYMGMT-X448, EVP_KEYMGMT-ED25519, EVP_KEYMGMT-ED448
|
|
- EVP_PKEY X25519, X448, ED25519 and ED448 keytype and algorithm support
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The B<X25519>, B<X448>, B<ED25519> and B<ED448> keytypes are
|
|
implemented in OpenSSL's default and FIPS providers. These implementations
|
|
support the associated key, containing the public key I<pub> and the
|
|
private key I<priv>.
|
|
|
|
=head2 Common Keygen Parameters for X25519, X448, ED25519 and ED448
|
|
|
|
The following parameters can be used during key generation by calling
|
|
EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init().
|
|
|
|
=over 4
|
|
|
|
=item "properties" (B<OSSL_PKEY_PARAM_PROPERTIES>) <octet string>
|
|
|
|
The property query to use when fetching algorithms during the key generation
|
|
operation.
|
|
|
|
=back
|
|
|
|
=head2 Keygen Parameters for X25519 and X448
|
|
|
|
=over 4
|
|
|
|
=item "dhkem-ikm" (B<OSSL_PKEY_PARAM_DHKEM_IKM>) <octet string>
|
|
|
|
DHKEM requires the generation of a keypair using an input key material (seed).
|
|
Use this to specify the key material used for generation of the private key.
|
|
This value should not be reused for other purposes.
|
|
It should have a length of at least 32 for X25519, and 56 for X448.
|
|
|
|
=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
|
|
|
|
The group name must be "x25519" or "x448" respectively for those algorithms.
|
|
This is only present for consistency with other key exchange algorithms and is
|
|
typically not needed.
|
|
|
|
=back
|
|
|
|
=head2 Common Parameters for X25519, X448, ED25519 and ED448
|
|
|
|
In addition to the common parameters that all keytypes should support (see
|
|
L<provider-keymgmt(7)/Common parameters>), the implementation of these keytypes
|
|
support the following.
|
|
|
|
=over 4
|
|
|
|
=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
|
|
|
|
The public key value.
|
|
|
|
=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
|
|
|
|
The private key value.
|
|
|
|
=back
|
|
|
|
=head2 Parameters for X25519 and X448
|
|
|
|
=over 4
|
|
|
|
=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
|
|
|
|
Used for getting and setting the encoding of a public key for the B<X25519> and
|
|
B<X448> key types. Public keys are expected be encoded in a format as defined by
|
|
RFC7748.
|
|
|
|
=item "fips-indicator" (B<OSSL_PKEY_PARAM_FIPS_APPROVED_INDICATOR>) <integer>
|
|
|
|
This getter is only supported by X25519 and X448 OpenSSL FIPS provider.
|
|
Since X25519 and X448 are unapproved in FIPS 140-3 this getter returns 0.
|
|
|
|
=back
|
|
|
|
=head2 Parameters for ED25519 and ED448
|
|
|
|
=over 4
|
|
|
|
=item "mandatory-digest" (B<OSSL_PKEY_PARAM_MANDATORY_DIGEST>) <UTF8 string>
|
|
|
|
The empty string, signifying that no digest may be specified.
|
|
|
|
=back
|
|
|
|
=head1 CONFORMING TO
|
|
|
|
=over 4
|
|
|
|
=item RFC 8032
|
|
|
|
=item RFC 8410
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
An B<EVP_PKEY> context can be obtained by calling:
|
|
|
|
EVP_PKEY_CTX *pctx =
|
|
EVP_PKEY_CTX_new_from_name(NULL, "X25519", NULL);
|
|
|
|
EVP_PKEY_CTX *pctx =
|
|
EVP_PKEY_CTX_new_from_name(NULL, "X448", NULL);
|
|
|
|
EVP_PKEY_CTX *pctx =
|
|
EVP_PKEY_CTX_new_from_name(NULL, "ED25519", NULL);
|
|
|
|
EVP_PKEY_CTX *pctx =
|
|
EVP_PKEY_CTX_new_from_name(NULL, "ED448", NULL);
|
|
|
|
An B<X25519> key can be generated like this:
|
|
|
|
pkey = EVP_PKEY_Q_keygen(NULL, NULL, "X25519");
|
|
|
|
An B<X448>, B<ED25519>, or B<ED448> key can be generated likewise.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
|
|
L<EVP_KEYEXCH-X25519(7)>, L<EVP_KEYEXCH-X448(7)>,
|
|
L<EVP_SIGNATURE-ED25519(7)>, L<EVP_SIGNATURE-ED448(7)>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|