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.

=head2 Keygen Parameters

No mandatory 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.
This optional parameter can be used to set a pre-determined seed prior to
keypair generation.

Generated keys default to retaining the seed used.
The seed is also by default retained when keys are loaded from B<PKCS#8> files
in the seed format.
When available, the seed parameter is also used during key export and import,
with keys regenerated from the seed even if separately provided on import.

When the seed is retained, it is also available as a B<gettable> parameter,
and private key output to B<PKCS#8> files will be in seed format.
When the seed is not available, because not included in the B<PKCS#8> file, not
available on import, or not retained, B<PKCS#8> private key files will have the
private key in FIPS 203 C<dk> format, without DER octet-string wrapping.

Retention of the seed can be disabled by setting the C<pkey_seed_retain>
parameter of the C<default> provider to C<no>.
See the description of the B<-provparam> option in L<openssl(1)> to learn
how to set provider options in the command line tools.
See L<OSSL_PROVIDER_add_conf_parameter(3)> to learn how to set provider
configuration options programmatically.
When using the FIPS provider, the parameter may need to be set in the C<base>
provider instead (or perhaps in all providers) if the intent is to retain seeds
read from PKCS#8 files.

In addition to its use in key generation, this parameter is also gettable and
settable.

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

=item C<ml-kem.retain_seed> (B<OSSL_PKEY_PARAM_ML_KEM_RETAIN_SEED>) <int>

This parameter is used only in key generation.
When keys are generated, by default the seed is retained and used as the
private key form on output when encoding.
When this parameter is set to a nonzero value, the seed is retained during key
generation, when set to 0, the seed is not retained.
When this parameter is simply omitted, and the C<ml-kem.retain_seed> provider
configuration parameter is set to a false boolean value, the seed is not
retained, otherwise it is retained (see also L<OSSL_PROVIDER_conf_get_bool(3)>).

=item C<ml-kem.input_formats> (B<OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS>) <UTF8 string>

List of enabled private key input formats in PKCS#8 files.
List elements are separated by commas and/or spaces or tabs.
The list of enabled formats can be specified in the configuration file, as seen
in the L</EXAMPLES> section below, or the via the B<-provparam> command-line
option.

Values specified on the command-line override any configuration file settings.
By default all the supported formats are enabled.
The supported formats are:

=over 4

=item C<seed-priv>:

This format represents keys in which both the 64-byte B<(d, z)> seed and the
FIPS 203 decapsulation private key B<dk> are present in the PKCS#8 private key
as part of the DER encoding of the ASN.1 sequence:

 PrivateKey ::= SEQUENCE {
    seed OCTET STRING OPTIONAL,
    expandedKey [1] IMPLICIT OCTET STRING OPTIONAL }
   (WITH COMPONENTS {..., seed  PRESENT } |
    WITH COMPONENTS {..., expandedKey  PRESENT })

If the C<seed-priv> format is not included in the list, this format will not be
recognised on input.

=item C<seed-only>:

This format represents keys in which only the 64-byte B<(d, z)> seed is present
in the above sequence.
If the C<seed-only> format is not included in the list, this format will not be
recognised on input.

=item C<priv-only>:

This format represents keys in which only the FIPS 203 decapsulation key B<dk>
is present in the above sequence.
If the C<priv-only> format is not included in the list, this format will not be
recognised on input.

=item C<priv-oqs>:

This format represents keys in which the private key value is a DER encoding of an
octet string containing the FIPS 203 decapsulation key B<dk>.
This format is used in some builds of the C<oqsprovider>, with a non-NIST value of
the algorithm OID by default.
For interoperability with OpenSSL, environment variable settings, such as
C<OQS_OID_MLKEM768=2.16.840.1.101.3.4.4.2>, need to be used to configure
C<oqsprovider> to use the expected NIST OIDs for B<ML-kEM>.
If the C<priv-oqs> format is not included in the list, this format will not be
recognised on input.

=item C<pair-oqs>:

This format represents keys in which the private keys a DER encoding of an
octet string containing the concatenaton of the FIPS 203 decapsulation key B<dk> and
the encapsulation key B<ek>.
This encoding is used in some builds of the C<oqsprovider>, with a non-NIST
value of the OID by default.
For interoperability with OpenSSL, environment variable settings, such as
C<OQS_OID_MLKEM512=2.16.840.1.101.3.4.4.1>, need to be used to configure
C<oqsprovider> to use the expected NIST OIDs for B<ML-kEM>.
If the C<pair-oqs> format is not included in the list, this format will not be
recognised on input.

=back

=item C<ml-kem.output_formats> (B<OSSL_PKEY_PARAM_ML_KEM_INPUT_FORMATS>) <UTF8 string>

Ordered list of enabled private key output formats when writing PKCS#8 files.
List elements are separated by commas and/or spaces or tabs.
The list of enabled formats can be specified in the configuration file, as seen
in the L</EXAMPLES> section below, or the via the B<-provparam> command-line
option.

This supports the same set of formats as described under C<ml-kem.input_formats>
above.
The order in which elements are listed is important, the selected format will be
the first one that is possible to output.
If the key seed is known, the first listed format will be selected.
If the key seed is not known, the first format that omits the seed will be selected.
By default C<seed-priv> is listed first and C<priv-only> second.

=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 Information Parameters>), B<ML-KEM> keys
keys 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.
It is otherwise only gettable.

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

The private key value.

This parameter is used when importing or exporting the private key value with
the EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.
The key length and content must be that of the FIPS 203 (Algorithm 16:
B<ML-KEM.KeyGen_internal>) B<dk> private key for the given ML-KEM variant.
It is otherwise only gettable.

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

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

An B<ML-KEM> private key in seed format can be converted to a key in expanded
FIPS 203 B<dk> format by running:

    $ openssl pkey -provparam ml-kem.retain_seed=no -in seed.pem -out long.pem

To generate an, e.g., B<ML-KEM-768> key, in expanded format, you can run:

    $ openssl genpkey -provparam ml-kem.retain_seed=no \
        -algorithm ml-kem-768 -out long.pem

In the B<openssl.cnf> file, this looks like:

 openssl_conf = openssl_init

 [openssl_init]
 providers = providers_sect

 # Can be referenced in one or more provider sections
 [ml_kem_sect]
 retain_seed = yes
 # OQS legacy formats disabled
 input_formats = seed-priv, seed-only, priv-only
 # Output either the seed alone, or else the key alone
 output_formats = seed-only, priv-only

 [providers_sect]
 default = default_sect
 base = base_sect

 [default_sect]
 ml-kem = ml_kem_sect

 [base_sect]
 ml-kem = ml_kem_sect

=head1 SEE ALSO

L<openssl(1)>,
L<openssl-pkey(1)>,
L<openssl-genpkey(1)>,
L<EVP_KEYMGMT(3)>,
L<EVP_PKEY(3)>,
L<EVP_PKEY_get_raw_private_key(3)>,
L<EVP_PKEY_get_raw_public_key(3)>,
L<EVP_PKEY_get1_encoded_public_key(3)>,
L<provider-keymgmt(7)>,
L<EVP_KEM-ML-KEM(7)>,
LOSSL_PROVIDER_add_conf_parameter(3)>

=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