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 B<default> provider.

=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 public key format is used for import, import, get and set operations.

=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 format is that of B<dk> in FIPS 203, Algorithm 16:
B<ML-KEM.KeyGen_internal>.

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

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

=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