mirror of
https://github.com/openssl/openssl.git
synced 2025-04-06 20:20:50 +08:00
05c05d43bf
Fix the references to OSSL_PROVIDER_add_conf_parameter in the 'SEE ALSO' section. Signed-off-by: Ingo Franzki <ifranzki@linux.ibm.com> Reviewed-by: Paul Dale <ppzgs1@gmail.com> Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/27077)
326 lines
11 KiB
Plaintext
326 lines
11 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
EVP_PKEY-ML-KEM,
|
|
EVP_KEYMGMT-ML-KEM,
|
|
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
|
|
- 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 by default include the seed.
|
|
When the seed was not initially known, or was not retained, B<PKCS#8> private
|
|
key files will contain only the private key in FIPS 203 C<dk> format.
|
|
|
|
=item "properties" (B<OSSL_PKEY_PARAM_PROPERTIES>) <UTF8 string>
|
|
|
|
Sets properties to be used when fetching algorithm implementations used for
|
|
ML-KEM hashing operations.
|
|
|
|
Use L<EVP_PKEY_CTX_set_params(3)> after calling L<EVP_PKEY_keygen_init(3)>.
|
|
|
|
=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 parameters listed below.
|
|
These are gettable using
|
|
L<EVP_PKEY_get_octet_string_param(3)> or L<EVP_PKEY_get_params(3)>.
|
|
They can be initialised via L<EVP_PKEY_fromdata(3)>, and are returned by
|
|
L<EVP_PKEY_todata(3)> given a suitable I<selection>.
|
|
Once a public or private key is configured, it can no longer be modified,
|
|
nor can another key component be added.
|
|
|
|
=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.import_pct_type> (B<OSSL_PKEY_PARAM_ML_KEM_IMPORT_PCT_TYPE>) <UTF8 string>
|
|
|
|
When an B<ML-KEM> key is imported as an explict FIPS 203 B<dk> decapsulation
|
|
key, rather than a seed, a pairwise consistency test (PCT) is optionally
|
|
performed.
|
|
By default, or when this parameter is set explicitly to C<random>, the PCT
|
|
is performed with a random entropy value for the encapsulation step.
|
|
Setting the parameter to C<fixed>, still runs the test, but the encapsulation
|
|
entropy is a fixed 32 byte value.
|
|
Specifying any other value of the parameter, e.g. C<none>, skips the test.
|
|
|
|
=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 B<PKCS#8> objects in which both the FIPS 203 64-byte
|
|
B<(d, z)> seed and the decapsulation key B<dk> are present in the private key
|
|
as part of the DER encoding of the ASN.1 sequence:
|
|
|
|
ML-KEM-PrivateKey ::= CHOICE {
|
|
seed [0] IMPLICIT OCTET STRING (SIZE (64)),
|
|
expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)),
|
|
both SEQUENCE {
|
|
seed OCTET STRING (SIZE (64)),
|
|
expandedKey OCTET STRING (SIZE (1632 | 2400 | 3168)) } }
|
|
|
|
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 B<PKCS#8> objects 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 B<PKCS#8> objects 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<oqskeypair>:
|
|
|
|
This format represents B<PKCS#8> objects in which the private key is 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>.
|
|
If the C<oqskeypair> format is not included in the list, this format will not be
|
|
recognised on input.
|
|
|
|
=item C<bare-seed>:
|
|
|
|
This format represents B<PKCS#8> objects in which the private key contains
|
|
the 64-byte FIPS 204 seed B<(d, z)> without any ASN.1 encapsulation.
|
|
If the C<bare-seed> format is not included in the list, this format will not be
|
|
recognised on input.
|
|
|
|
=item C<bare-priv>:
|
|
|
|
This format represents B<PKCS#8> objects in which the private key contains
|
|
the FIPS 204 decapsulation key B<dk> without any ASN.1 encapsulation.
|
|
If the C<bare-priv> 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 B<PKCS#8> files.
|
|
List elements are separated by commas, 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> first and C<priv-only> second, with
|
|
both seed and key output when the seed is available, and just the
|
|
key otherwise.
|
|
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<oqskeypair>, C<bare-seed> and C<bare-priv> formats can also be
|
|
output, by listing 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");
|
|
|
|
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 priv-only.pem
|
|
|
|
If you have a 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<OSSL_PROVIDER_add_conf_parameter(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-2025 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
|