openssl/doc/man7/EVP_PKEY-ML-KEM.pod

=pod

=head1 NAME

EVP_PKEY-ML-KEM-512,
EVP_PKEY-ML-KEM-768,
EVP_PKEY-ML-KEM-1024,
EVP_KEYMGMT-ML-KEM-512,
EVP_KEYMGMT-ML-KEM-768,
EVP_KEYMGMT-ML-KEM-1024,
EVP_PKEY-ML-KEM
- ML-KEM keytype and algorithm support

=head1 DESCRIPTION

The B<ML-KEM-512>, B<ML-KEM-768>, and B<ML-KEM-1024> keytypes are implemented
in OpenSSL's default and FIPS providers.

=for comment (TODO(ML-KEM): Add FIPS support).

=head2 Keygen Parameters

By default, no parameters are required for generating a key pair.

=over 4

=item "seed" (B<OSSL_PKEY_PARAM_ML_KEM_SEED>) <octet string>

Internally, ML-KEM generates keys using a 64-byte random value (seed), which is
the concatenation of the 32-byte I<d> and I<z> parameters described in FIPS 203.
The optional parameter can be used to set a pre-determined seed prior to
keypair generation.
According to FIPS 203, section 3.3, this parameter should only be used for test
purposes and be treated with the same care as private key material.

This parameter is only settable.

See L<provider-keymgmt(7)/Common Information Parameters> for further
information.

=back

Use EVP_PKEY_CTX_set_params() after calling EVP_PKEY_keygen_init().

=head2 Common 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 "pub" (B<OSSL_PKEY_PARAM_PUB_KEY>) <octet string>

The public key value.

This parameter is used when importing or exporting the public key value with
the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.  The same underlying
FIPS 203 (Algorithm 16: B<ML-KEM.KeyGen_internal>) B<ek> public key format is
used for import, export, get and set operations.

=item "priv" (B<OSSL_PKEY_PARAM_PRIV_KEY>) <octet string>

The private key, in seed form when available.

This parameter is used when importing or exporting the private key value with
the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.
On import, the private key key length is used to infer the key format.
If the key length is 64 bytes, the key format is assumed to be the 64-byte
input seed of FIPS 203, Algorithm 16: B<ML-KEM.KeyGen_internal>, with the B<d>
and B<z> values concatenated in that order.
If, on the other hand, the key length is that of the FIPS 203 (Algorithm 16:
B<ML-KEM.KeyGen_internal>) B<dk> private key for the given ML-KEM variant, then
the key is assumed to be in that format.

Keys originally imported in the B<dk> FIPS 203 form cannot be exported in seed
form as the B<d> seed is not available in that case, and the exported key will
then be the FIPS 203 B<dk> format in which the key was imported.
Generated keys retain the seed value, and are exported in seed form.

=item "encoded-pub-key" (B<OSSL_PKEY_PARAM_ENCODED_PUBLIC_KEY>) <octet string>

Used for getting and setting the encoding of a public key.
The key format is that of B<ek> in FIPS 203, Algorithm 16:
B<ML-KEM.KeyGen_internal>.
Updates of the public and private key components are only allowed on keys that
are empty.
Once a public or private key component is set, no further changes are allowed.

This parameter is gettable and settable.

=item "encoded-priv-key" (B<PKEY_PARAM_ENCODED_PRIVATE_KEY>) <octet string>

Used for getting the I<expanded> encoding of a private key.
The key format is that of B<dk> in FIPS 203, Algorithm 16: B<ML-KEM.KeyGen_internal>.
The private key format returned from key export is the B<(d, z)> seed, when
available, but is otherwise the same as the encoded form.

This parameter is only gettable.

=back

=head1 CONFORMING TO

=over 4

=item FIPS 203

=back

=head1 EXAMPLES

An B<EVP_PKEY> context can be obtained by calling:

    EVP_PKEY_CTX *pctx =
        EVP_PKEY_CTX_new_from_name(NULL, "ML-KEM-768", NULL);

An B<ML-KEM-768> key can be generated like this:

    pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML-KEM-768");

Equivalent calls are available for B<ML-KEM-512> and B<ML-KEM-1024>.

=head1 SEE ALSO

L<EVP_KEYMGMT(3)>,
L<EVP_PKEY(3)>,
L<provider-keymgmt(7)>,
L<EVP_KEM-ML-KEM(7)>

=head1 HISTORY

This functionality was added in OpenSSL 3.5.

=head1 COPYRIGHT

Copyright 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