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.
To set explicit parameters, use EVP_PKEY_CTX_set_params() after calling
EVP_PKEY_keygen_init().

=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 (by default) regenerated from the seed even when also provided on import.
See L</Provider configuration parameters> below for related controls.

When the seed is retained, it is also available as a B<gettable> parameter,
and private key output to B<PKCS#8> files will default to 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.

=back

=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 key length and content is that of the FIPS 203 (Algorithm 16:
B<ML-KEM.KeyGen_internal>) B<ek> public key for the given ML-KEM variant.
Initial import aside, this parameter 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 is that of the FIPS 203 (Algorithm 16:
B<ML-KEM.KeyGen_internal>) B<dk> private key for the given ML-KEM variant.
Initial import aside, this parameter 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 (once only).

=back

=head2 Provider configuration parameters

See the description of the B<-provparam> option in L<openssl(1)> to learn
how to set provider configuration parameters in the command line tools.
See L<OSSL_PROVIDER_add_conf_parameter(3)> to learn how to set provider
configuration options programmatically.

=over 4

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

When set to a string representing a false boolean value (see
L<OSSL_PROVIDER_conf_get_bool(3)>), the seed will not be retained after key
generation or key import from a seed value.
If the resulting key is then written to a PKCS#8 object, it will contain
only the FIPS 203 C<dk> key.

=item C<ml-kem.prefer_seed> (B<OSSL_PKEY_PARAM_ML_KEM_PREFER_SEED>) <UTF8 string>

When decoding PKCS#8 objects that contain both a seed and the FIPS 203 C<dk>
private key, the seed is by default used to regenerate the key, and the
companion key is ignored.
When this configuration parameter is set to a string representing a false
boolean value (see L<OSSL_PROVIDER_conf_get_bool(3)>), the seed is ignored
(neither used to regenerate the key, nor retained), and the companion key is
used instead.

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

List of enabled private key input formats when parsing PKCS#8 objects.
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 (see also L<OSSL_PROVIDER_add_conf_parameter(3)>).

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_OUTPUT_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.
The default order is equivalent to C<seed-priv> and C<priv-only> second, with
both seed and key output when the seed is available, and otherwise just the
key is output.
If C<seed-only> is listed first, then the seed will be output without the key
when available, otherwise the output will have just the key.
If C<priv-only> is listed first, then just the key is output regardless of
whether the seed is present.
The legacy C<oqs> formats can also be output, by listing either of those first.

=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 the FIPS
203 B<dk> format by running:

    $ openssl pkey -provparam ml-kem.retain_seed=no \
        -in seed-only.pem -out priv-only.pem

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

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

If you have B<PKCS#8> file with both a seed and a key, and prefer to import the
companion key rather than the seed, you can run:

    $ openssl pkey -provparam ml-kem.prefer_seed=no \
        -in seed-priv.pem -out priv-only.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]
    prefer_seed = yes
    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
    # Or perhaps just: base = 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