[thirdparty/openssl.git] / doc / man7 / EVP_PKEY-X25519.pod

=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 Keygen Parameters

=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.

This is only supported by X25519 and X448.

=back

Use EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init().

=head2 Common X25519, X448, ED25519 and ED448 parameters

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 "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>

This is only supported by X25519 and X448. 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.

=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.

=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.

=back

=head2 ED25519 and ED448 parameters

=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-2021 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
Commit	Line	Data
33df1cfd RL	1	=pod
	2
	3	=head1 NAME
	4
	5	EVP_PKEY-X25519, EVP_PKEY-X448, EVP_PKEY-ED25519, EVP_PKEY-ED448,
	6	EVP_KEYMGMT-X25519, EVP_KEYMGMT-X448, EVP_KEYMGMT-ED25519, EVP_KEYMGMT-ED448
	7	- EVP_PKEY X25519, X448, ED25519 and ED448 keytype and algorithm support
	8
	9	=head1 DESCRIPTION
	10
	11	The B<X25519>, B<X448>, B<ED25519> and B<ED448> keytypes are
8c30dfee P	12	implemented in OpenSSL's default and FIPS providers. These implementations
	13	support the associated key, containing the public key I<pub> and the
	14	private key I<priv>.
	15
78c44b05	16	=head2 Keygen Parameters
b8086652	17
78c44b05	18	=over 4
	19
	20	=item "dhkem-ikm" (B<OSSL_PKEY_PARAM_DHKEM_IKM>) <octet string>
	21
	22	DHKEM requires the generation of a keypair using an input key material (seed).
	23	Use this to specify the key material used for generation of the private key.
	24	This value should not be reused for other purposes.
	25	It should have a length of at least 32 for X25519, and 56 for X448.
	26
	27	This is only supported by X25519 and X448.
	28
	29	=back
	30
	31	Use EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init().
33df1cfd RL	32
	33	=head2 Common X25519, X448, ED25519 and ED448 parameters
	34
8c30dfee P	35	In addition to the common parameters that all keytypes should support (see
	36	L<provider-keymgmt(7)/Common parameters>), the implementation of these keytypes
	37	support the following.
33df1cfd RL	38
	39	=over 4
	40
90929138 MC	41	=item "group" (B<OSSL_PKEY_PARAM_GROUP_NAME>) <UTF8 string>
	42
	43	This is only supported by X25519 and X448. The group name must be "x25519" or
8c1cbc72	44	"x448" respectively for those algorithms. This is only present for consistency
90929138 MC	45	with other key exchange algorithms and is typically not needed.
90929138 MC	46
33df1cfd RL	47	=item "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>
	48
	49	The public key value.
	50
	51	=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>
	52
	53	The private key value.
	54
5ac8fb58	55	=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>
6a9bd929	56
5ac8fb58 MC	57	Used for getting and setting the encoding of a public key for the B<X25519> and
	58	B<X448> key types. Public keys are expected be encoded in a format as defined by
	59	RFC7748.
6a9bd929	60
33df1cfd RL	61	=back
33df1cfd RL	62
1a7328c8 RL	63	=head2 ED25519 and ED448 parameters
	64
	65	=over 4
	66
c9f18e59	67	=item "mandatory-digest" (B<OSSL_PKEY_PARAM_MANDATORY_DIGEST>) <UTF8 string>
1a7328c8 RL	68
	69	The empty string, signifying that no digest may be specified.
	70
	71	=back
	72
33df1cfd RL	73	=head1 CONFORMING TO
	74
	75	=over 4
	76
	77	=item RFC 8032
	78
b8086652 SL	79	=item RFC 8410
b8086652 SL	80
33df1cfd RL	81	=back
	82
	83	=head1 EXAMPLES
	84
	85	An B<EVP_PKEY> context can be obtained by calling:
	86
	87	EVP_PKEY_CTX *pctx =
	88	EVP_PKEY_CTX_new_from_name(NULL, "X25519", NULL);
	89
	90	EVP_PKEY_CTX *pctx =
	91	EVP_PKEY_CTX_new_from_name(NULL, "X448", NULL);
	92
	93	EVP_PKEY_CTX *pctx =
	94	EVP_PKEY_CTX_new_from_name(NULL, "ED25519", NULL);
	95
	96	EVP_PKEY_CTX *pctx =
	97	EVP_PKEY_CTX_new_from_name(NULL, "ED448", NULL);
	98
f9253152	99	An B<X25519> key can be generated like this:
33df1cfd	100
7f24110a	101	pkey = EVP_PKEY_Q_keygen(NULL, NULL, "X25519");
33df1cfd	102
f9253152	103	An B<X448>, B<ED25519>, or B<ED448> key can be generated likewise.
33df1cfd RL	104
	105	=head1 SEE ALSO
	106
	107	L<EVP_KEYMGMT(3)>, L<EVP_PKEY(3)>, L<provider-keymgmt(7)>,
	108	L<EVP_KEYEXCH-X25519(7)>, L<EVP_KEYEXCH-X448(7)>,
	109	L<EVP_SIGNATURE-ED25519(7)>, L<EVP_SIGNATURE-ED448(7)>
	110
	111	=head1 COPYRIGHT
	112
0789c7d8	113	Copyright 2020-2021 The OpenSSL Project Authors. All Rights Reserved.
33df1cfd RL	114
	115	Licensed under the Apache License 2.0 (the "License"). You may not use
	116	this file except in compliance with the License. You can obtain a copy
	117	in the file LICENSE in the source distribution or at
	118	L<https://www.openssl.org/source/license.html>.
	119
	120	=cut