mirror of
https://github.com/openssl/openssl.git
synced 2025-03-31 20:10:45 +08:00
Initial batch of ML-KEM doc updates.
With the soon-to-be-merged ML-KEM #26172 as the merge base. Reviewed-by: Matt Caswell <matt@openssl.org> Reviewed-by: Tim Hudson <tjh@openssl.org> Reviewed-by: Tomas Mraz <tomas@openssl.org> Reviewed-by: Neil Horman <nhorman@openssl.org> (Merged from https://github.com/openssl/openssl/pull/26217)
This commit is contained in:
Viktor Dukhovni
Tomas Mraz
parent
63e9a3b1f3
commit
7772dbb17c
@ -1,122 +1,156 @@
|
||||
ML-KEM Design
|
||||
=============
|
||||
|
||||
This document covers OpenSSL specific ML-KEM implementation details.
|
||||
[FIPS 203](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf)
|
||||
clearly states most of the requirements of ML-KEM and has comprehensive
|
||||
pseudo code for all its algorithms.
|
||||
This document covers OpenSSL-specific ML-KEM implementation details.
|
||||
**ML-KEM** is specified in [FIPS 203], which includes comprehensive pseudo-code
|
||||
for all its algorithms.
|
||||
|
||||
ML-KEM Parameters & Functions
|
||||
-----------------------------
|
||||
|
||||
There are 3 different parameter sets in FIPS 203 (see Section 8).
|
||||
There are constants related to these, as well as there being a group of
|
||||
functions associated with each set.
|
||||
|
||||
To support these variants, OpenSSL will have 3 different key managers and 3
|
||||
corresponding KEM function sets. The names used are of the form "ML-KEM-768".
|
||||
To support these variants, OpenSSL has 3 associated key managers and 3
|
||||
corresponding KEM function sets.
|
||||
The key management and KEM algorithm names are **ML-KEM-512**, **ML-KEM-768**
|
||||
and **ML-KEM-1024**.
|
||||
At the TLS layer, the associated key exchange *groups* are, respectively,
|
||||
**MLKEM512**, **MLKEM768** and **MLKEM1024**.
|
||||
|
||||
The key problem implementing the different variants lies in the significant
|
||||
differences in (dimensions of) vectors and matrics required. For this reason,
|
||||
[boringssl](https://boringssl.googlesource.com/boringssl/+/HEAD/crypto/mlkem)
|
||||
chose to use C++ templates to represent the different parameter sets.
|
||||
As C++ cannot be used in OpenSSL, (object) code duplication by way of use
|
||||
of macros to minimize source code duplication is used. Note that C++ templates are also specialised at compile time to the specific types at which they are instantiated, so there's not in fact much difference in the resulting code size. Templates are in this regard just a cleaner, more expressive "macro" system.
|
||||
|
||||
ML-KEM makes extensive use of SHA3 primitives, SHA3-256, SHA3-512, SHAKE256 and SHAKE128.
|
||||
To improve ML-KEM execution performance the EVP handles for these are pre-fetched during ML-KEM
|
||||
key initialisation and stored in an ossl_ml_kem_ctx object.
|
||||
**ML-KEM** makes extensive use of four **SHA3** primitives: **SHA3-256**,
|
||||
**SHA3-512**, **SHAKE128** and **SHAKE256**.
|
||||
To improve **ML-KEM** execution performance, the EVP handles for these are
|
||||
pre-fetched during **ML-KEM** key initialisation and stored with each key.
|
||||
These are then used in key generation, encapsulation and decapsulation.
|
||||
The context is also duplicated (EVP_MD handles uprefed) when the ML-KEM key is duplicated.
|
||||
|
||||
This ossl_ml_kem_ctx is then passed to all functions.
|
||||
As already noted, it is presently allocated on a per-key basis in the providers'
|
||||
ML-KEM key context, but if there's some way to do this just once during provider
|
||||
initialisation, or once per thread, ... performance might noticeably improve.
|
||||
These are also duplicated by reference (**EVP_MD** handles uprefed) when an
|
||||
**ML-KEM** key is duplicated.
|
||||
|
||||
ML-KEM keys
|
||||
-----------
|
||||
|
||||
As expected, ML-KEM has both public and private keys.
|
||||
**ML-KEM** is an asymmetric algorithm, and has both public and private keys.
|
||||
Since the public key is exchanged between the two parties as part of key
|
||||
agreement, the encoding (wire-form) of the public key is clearly defined and
|
||||
agreement, the encoding (*wire-form*) of the public key is clearly defined and
|
||||
there are unambiguous choices for its encoding and decoding functions.
|
||||
|
||||
It may be noted that the wire-form public key is "compressed".
|
||||
It may be noted that the *wire-form* public key is "compressed".
|
||||
Instead of the bulky "A" ("m" in the code) matrix, which represents the majority
|
||||
of the storage required for ML-KEM public and private keys, the wire-form public
|
||||
key, holds a 32-byte seed from which one can regenerate the matrix.
|
||||
The full matrix is in memory in the internal form (needed for computations) of
|
||||
the public key (which in our implementation is simply a reference into the internal
|
||||
form of the private key when both are known).
|
||||
It is possible to save space and compute the matrix elements just-in-time, as-needed,
|
||||
which would not have a performance impact on the encapsulation step (typically server)
|
||||
where each matrix element is used exactly once!
|
||||
of the storage required for ML-KEM public and private keys, the *wire-form* public
|
||||
key, holds a 32-byte seed from which the the matrix is regenerated by the recipient
|
||||
of the public key.
|
||||
In the OpenSSL implementation, the matrix is *eagerly* evaluated as part of
|
||||
decoding the public key, and stored in memory in the internal form needed for
|
||||
subsequent computations (encapsulation).
|
||||
Since the private key includes the public key as one of its components, the matrix
|
||||
is also pre-computed and stored with the private key, and then need not be
|
||||
regenerated during decapsulation.
|
||||
During encapsulation (typically peformed by servers), it is in principle
|
||||
possible to save space and compute the matrix elements *just-in-time*, as each
|
||||
matrix element is used exactly once.
|
||||
This is not currently implemented, and the matrix is pre-computed in full.
|
||||
|
||||
However, the same matrix is used both during key generation and decapsulation and
|
||||
computing it twice would have a noticeable performance impact (typically on the client).
|
||||
If we wanted to do just-in-time matrix computation for decapsulation, we'd need to have
|
||||
a different memory layout for public keys when only the public key is known, and to change
|
||||
the algorithm code to generate matrix elements on demand during encapsulation. This can
|
||||
be considered later, if it is determined that the space savings (9*512 bytes in memory for
|
||||
ML-KEM-768, for the full matrix, instead of 512 bytes for a just-in-time element) this could
|
||||
be considered later, but the server will generally destroy the client public key soon after the
|
||||
shared secret is computed, so these don't stay in memory long, so briefly saving ~2KB may
|
||||
not to be of much benefit).
|
||||
However, the same matrix is used both during key generation and decapsulation
|
||||
and computing it twice would have a noticeable performance impact (typically on
|
||||
the client).
|
||||
If we wanted to do *just-in-time* matrix computation for decapsulation, we'd
|
||||
need to have a different memory layout for public keys when only the public key
|
||||
is known, and to change the algorithm code to generate matrix elements on
|
||||
demand during encapsulation.
|
||||
This can be considered later, if it is determined that the space savings (9 *
|
||||
512 bytes in memory for ML-KEM-768, for the full matrix, instead of 512 bytes
|
||||
for a just-in-time element).
|
||||
Since servers will generally destroy the client public key soon after the
|
||||
shared secret is computed, these don't stay in memory long, and briefly saving
|
||||
~2KB may not to be of much benefit).
|
||||
|
||||
The private key format is somewhat ad hoc, though (to be able to fully describe the algorithms)
|
||||
FIPS 203 documents a format that is commonly referred to as the "extended"
|
||||
format and also exportable/importable via encoding functions in well-defined
|
||||
sizes. The IETF voices interest in using the "seed-based" format (the (d,z) seed
|
||||
pair from which the key is generated and can be recovered). This is supported by the
|
||||
FIPS 203 internal deterministic key generation functions, which are "testing only".
|
||||
We naturally use this for running the Known Answer Tests, but our private key encoding
|
||||
format is the full expanded key, not the 64 byte (d,z) seed pair.
|
||||
The private key format is yet to be clearly standardised, though (to be able to
|
||||
fully describe the algorithms) FIPS 203 documents a format that is commonly
|
||||
referred to as the "extended" format.
|
||||
This is the private key format supported by our key management provider
|
||||
interface.
|
||||
The IETF voices interest in using the "seed-based" format (the 64-byte (*d*,
|
||||
*z*) seed pair from which the key is generated and can be recovered).
|
||||
Recovery of the key from the seed (*d*, *z* pair) is supported by the [FIPS
|
||||
203] internal deterministic key generation functions, which are used in the
|
||||
*keygen* portion of the Known Answer Tests (KATs).
|
||||
|
||||
The design therefore caters to both options: The default key generation and
|
||||
KEM encapsulation/decapsulation functions operate on/with "extended keys".
|
||||
It is also possible to use the "seed-based" format by way of providing
|
||||
specific OSSL_PARAMs made available for that purpose -- but again, as per
|
||||
NIST guidance, only for testing. If the seed version is retrieved from a
|
||||
normal key generation operation, it shall be subject to the same level of
|
||||
protection given to private key material.
|
||||
The design therefore caters to both options: The default key generation and KEM
|
||||
encapsulation/decapsulation functions operate on "extended keys" in the
|
||||
[FIPS 203] format, but it will be possible to use the "seed-based" private key
|
||||
format by using the (currently test-only) deterministic *keygen* interface.
|
||||
When keys are generated randomly, we don't presently provide a mechanism
|
||||
to obtain and store the seed.
|
||||
This can be added later if required.
|
||||
|
||||
Key generation API
|
||||
------------------
|
||||
|
||||
Keys can therefore be generated as "usual" by way of the EVP functions
|
||||
EVP_PKEY_generate() and EVP_PKEY_Q_keygen().
|
||||
Keys can be generated via the usual **EVP_PKEY_generate()** and
|
||||
**EVP_PKEY_Q_keygen()** functions.
|
||||
|
||||
An explicit seed can be specified by setting the OSSL_PARAM value
|
||||
"OSSL_PKEY_PARAM_ML_KEM_SEED" to a 64-byte octet-string before key generation.
|
||||
The octet-string value must be the concatenation of the B<d> and B<z> strings in that
|
||||
order.
|
||||
An explicit seed can be specified by setting the key generation
|
||||
**OSSL_PKEY_PARAM_ML_KEM_SEED** parameter to a 64-byte octet-string
|
||||
(concatentation of the **d** and **z** values (32-bytes each) in that order).
|
||||
|
||||
KEM API
|
||||
-------
|
||||
|
||||
ML-KEM is meant to be a simple replacement for existing KEM algorithms.
|
||||
Therefore, simple use should be
|
||||
**ML-KEM** is meant to be a drop-in replacement for existing KEM algorithms.
|
||||
Accessed in the usual way via:
|
||||
|
||||
EVP_PKEY_encapsulate_init(), EVP_PKEY_encapsulate(),
|
||||
EVP_PKEY_decapsulate_init(), EVP_PKEY_decapsulate().
|
||||
- **EVP_PKEY_encapsulate_init()**,
|
||||
- **EVP_PKEY_encapsulate()**,
|
||||
- **EVP_PKEY_decapsulate_init()**, and
|
||||
- **EVP_PKEY_decapsulate()**.
|
||||
|
||||
For the encapsulation operation, a test-only option exists to avoid the
|
||||
otherwise mandatory use of a random number generator for passing in a
|
||||
known "entropy" by way of the OSSL_PARAM "OSSL_KEM_PARAM_IKME".
|
||||
For the encapsulation operation, a test-only option exists to bypass the random
|
||||
number generator (secret random inputs are required for security) and pass in
|
||||
a pre-determined 32-byte random value, by setting of the
|
||||
**OSSL_KEM_PARAM_IKME** parameter.
|
||||
|
||||
Buffers
|
||||
-------
|
||||
|
||||
There are many functions passing buffers of sizes dependent on algorithm
|
||||
(version). It therefore is required to properly check/allocate buffers of
|
||||
suitable sizes as defined in the core "mlkem.h" header file. These size
|
||||
checks are performed within the provider logic. The core crypto APIs for
|
||||
any ML-KEM algorithm are not to be exposed and called by external users.
|
||||
The **ML-KEM** key management and KEM providers interface with the underlying
|
||||
libcrypto implementation via functions that validate the sizes of all provided
|
||||
input/output buffers (encoded keys, ciphertext, shared secrets and seeds) against
|
||||
the values expected for the provider's ML-KEM variant (a pointer to the variant
|
||||
parameters is stored with each key).
|
||||
|
||||
The underlying libcrypto **ML-KEM** APIs are not directly exposed to users,
|
||||
only the abstracted key management and KEM **EVP** APIs are public interfaces.
|
||||
|
||||
Constant Time Considerations
|
||||
----------------------------
|
||||
|
||||
The usual constant time methods are used in the implementation. All possible
|
||||
error conditions that can be detected are passed up the call stack to provide
|
||||
the usual OK/NOK status for all required functions.
|
||||
The usual constant time methods are used in the implementation.
|
||||
However, we avoid using a *value-barrier* to set the masks that perform
|
||||
constant-time *select* between one of two values.
|
||||
This avoids a 30-50% performance penalty and is expected to be robust even in
|
||||
the face of plausible future compiler optimisations.
|
||||
Remainders module the prime are computed via Barret Reduction and the decoding
|
||||
and decompression of the decrypted *message* has been tested to not be
|
||||
vulnerable to the "clangover" attack in our implementation.
|
||||
|
||||
All the libcrypto functions (other than **ML_KEM_KEY** allocation, which
|
||||
returns **NULL** on error) return 1 for success or zero on error.
|
||||
It should be noted that to avoid chosen-ciphertext attacks, the
|
||||
**decapsulate** implementation **must** return success and a synthetic
|
||||
shared secret (generated in constant-time whether synthetic or successfully
|
||||
decrypted) whenever the input is a well-formed ciphertext.
|
||||
|
||||
The only exception to the above is when, unexpectedly, one of the **SHA3**
|
||||
functions fails, in that case all hope of constant-time computation is
|
||||
lost, but we don't expect such failures to be influenced by the content
|
||||
of chosen-ciphertexts, so this should not be an issue).
|
||||
|
||||
Nevertheless, even then we fall back on returning a shared secret from the RNG
|
||||
along with an error indication only when the key derivation function
|
||||
for the synthetic shared secret fails.
|
||||
In all other conditions we return success and, as appropriate, either
|
||||
the correct shared secret, or the synthetic alternative generated by the KDF.
|
||||
|
||||
<!-- Links -->
|
||||
|
||||
[FIPS 203]:
|
||||
<https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.203.pdf>
|
||||
|
||||
@ -30,14 +30,29 @@ key that is used during decapsulation.
|
||||
|
||||
The EVP_PKEY_decapsulate() function performs a private key decapsulation
|
||||
operation using I<ctx>. The data to be decapsulated is specified using the
|
||||
I<wrapped> and I<wrappedlen> parameters.
|
||||
If I<unwrapped> is NULL then the size of the output secret buffer
|
||||
is written to I<*unwrappedlen>. If I<unwrapped> is not NULL and the
|
||||
call is successful then the decapsulated secret data is written to I<unwrapped>
|
||||
and the amount of data written to I<*unwrappedlen>. Note that, if I<unwrappedlen>
|
||||
is not NULL in this call, the value it points to must be initialised to the length of
|
||||
I<unwrapped>, so that the call can validate it is of sufficient size to hold the
|
||||
result of the operation.
|
||||
I<wrapped> and I<wrappedlen> parameters (which must both non-NULL).
|
||||
|
||||
The I<wrapped> parameter is an output argument, to which the decapsulated
|
||||
shared secret is written.
|
||||
The shared secret may not match the peer's value even when decapsulation
|
||||
returns success.
|
||||
Instead, the shared secret must be used to derive a key that is used to
|
||||
authenticate data subsequently received from the peer.
|
||||
If I<unwrapped> is NULL then the size of the output shared secret buffer is
|
||||
written to I<*unwrappedlen> and no decapsulation is performed, this makes it
|
||||
possible to determine the required buffer size at runtime. Otherwise, the
|
||||
decapsulated secret data is written to I<unwrapped> and the length of shared
|
||||
secret is written to I<*unwrappedlen>.
|
||||
|
||||
Note that the value pointed to by I<unwrappedlen> (which must NOT be B<NULL>)
|
||||
must be initialised to the length of I<unwrapped>, so that the call can
|
||||
validate it is of sufficient size to hold the result of the operation.
|
||||
|
||||
Absent detailed prior knowledge of the internals of the specific KEM
|
||||
algorithm, callers SHOULD NOT assume that the returned shared secret
|
||||
is necessarily of the maximum possible length.
|
||||
The actual length returned via I<*unwrappedlen> SHOULD be used to determine the
|
||||
actual length of the output.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
@ -93,8 +108,12 @@ Decapsulate data using RSA:
|
||||
|
||||
L<EVP_PKEY_CTX_new_from_pkey(3)>,
|
||||
L<EVP_PKEY_encapsulate(3)>,
|
||||
L<EVP_KEM-RSA(7)>, L<EVP_KEM-X25519(7)>, L<EVP_KEM-EC(7)>,
|
||||
L<EVP_KEM-ML-KEM-512(7)>, L<EVP_KEM-ML-KEM-768(7)>, L<EVP_KEM-ML-KEM-1024(7)>
|
||||
L<EVP_KEM-RSA(7)>,
|
||||
L<EVP_KEM-X25519(7)>,
|
||||
L<EVP_KEM-EC(7)>,
|
||||
L<EVP_KEM-ML-KEM-512(7)>,
|
||||
L<EVP_KEM-ML-KEM-768(7)>,
|
||||
L<EVP_KEM-ML-KEM-1024(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
@ -103,6 +122,8 @@ in OpenSSL 3.0.
|
||||
|
||||
The function EVP_PKEY_auth_decapsulate_init() was added in OpenSSL 3.2.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -30,25 +30,40 @@ key that is used during encapsulation.
|
||||
|
||||
The EVP_PKEY_encapsulate() function performs a public key encapsulation
|
||||
operation using I<ctx>.
|
||||
The symmetric secret generated in I<genkey> can be used as key material.
|
||||
The ciphertext in I<wrappedkey> is its encapsulated form, which can be sent
|
||||
to another party, who can use L<EVP_PKEY_decapsulate(3)> to retrieve it
|
||||
using their private key.
|
||||
If I<wrappedkey> is NULL then the maximum size of the output buffer
|
||||
is written to the I<*wrappedkeylen> parameter unless I<wrappedkeylen> is NULL
|
||||
and the maximum size of the generated key buffer is written to I<*genkeylen>
|
||||
unless I<genkeylen> is NULL.
|
||||
If I<wrappedkey> is not NULL and the call is successful then the
|
||||
internally generated key is written to I<genkey> and its size is written to
|
||||
I<*genkeylen>. The encapsulated version of the generated key is written to
|
||||
I<wrappedkey> and its size is written to I<*wrappedkeylen>. Note that if
|
||||
I<wrappedlen> is not NULL, then the value it points to must initially hold the size of
|
||||
the I<unwrapped> buffer so that its size can be validated by the call, ensuring
|
||||
it is large enough to hold the result written to I<wrapped>.
|
||||
The shared secret writen to I<genkey> can be used as an input for key
|
||||
derivation, typically for various symmetric algorithms.
|
||||
Its size is written to I<genkeylen>, which must be initialised to the
|
||||
size of the provided buffer.
|
||||
|
||||
The ciphertext written to I<wrappedkey> is an encapsulated form, which
|
||||
is expected to be only usable by the holder of the private key corresponding
|
||||
to wthe public key associated with I<ctx>.
|
||||
This ciphertext is then communicated to the private-key holder, who can use
|
||||
L<EVP_PKEY_decapsulate(3)> to securely recover the same shared secret.
|
||||
|
||||
If I<wrappedkey> is NULL then the maximum size of the output buffer is written
|
||||
to the I<*wrappedkeylen> parameter unless I<wrappedkeylen> is NULL and the
|
||||
maximum size of the generated key buffer is written to I<*genkeylen> unless
|
||||
I<genkeylen> is NULL.
|
||||
|
||||
If I<wrappedkey> is not NULL and the call is successful then the generated
|
||||
shared secret is written to I<genkey> and its size is written to
|
||||
I<*genkeylen> (which must be non-NULL).
|
||||
The encapsulated ciphertext is written to I<wrappedkey> and
|
||||
its size is written to I<*wrappedkeylen> (must also be non-NULL),
|
||||
The value pointed to by I<wrappedlen> initially hold the size of the
|
||||
I<unwrapped> buffer so that its size can be validated by the call, ensuring it
|
||||
is large enough to hold the result written to I<wrapped>.
|
||||
|
||||
Absent detailed prior knowledge of the internals of the specific KEM
|
||||
algorithm, callers SHOULD NOT assume that the returned shared secret and
|
||||
ciphertext are necessarily of the maximum possible length.
|
||||
The actual lengths returned via I<*wrappedkeylen> and I<*genkeylen> SHOULD
|
||||
be used to determine the actual lengths of the outputs.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
After the call to EVP_PKEY_encapsulate_init() algorithm-specific parameters
|
||||
After the call to EVP_PKEY_encapsulate_init(), algorithm-specific parameters
|
||||
for the operation may be set or modified using L<EVP_PKEY_CTX_set_params(3)>.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
@ -102,15 +117,21 @@ Encapsulate an RSASVE key (for RSA keys).
|
||||
|
||||
L<EVP_PKEY_CTX_new_from_pkey(3)>,
|
||||
L<EVP_PKEY_decapsulate(3)>,
|
||||
L<EVP_KEM-RSA(7)>, L<EVP_KEM-X25519(7)>, L<EVP_KEM-EC(7)>,
|
||||
L<EVP_KEM-ML-KEM-512(7)>, L<EVP_KEM-ML-KEM-768(7)>, L<EVP_KEM-ML-KEM-1024(7)>
|
||||
L<EVP_KEM-RSA(7)>,
|
||||
L<EVP_KEM-X25519(7)>,
|
||||
L<EVP_KEM-EC(7)>,
|
||||
L<EVP_KEM-ML-KEM-512(7)>,
|
||||
L<EVP_KEM-ML-KEM-768(7)>,
|
||||
L<EVP_KEM-ML-KEM-1024(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
These functions EVP_PKEY_encapsulate_init() and EVP_PKEY_encapsulate() were
|
||||
The functions EVP_PKEY_encapsulate_init() and EVP_PKEY_encapsulate() were
|
||||
added in OpenSSL 3.0.
|
||||
The function EVP_PKEY_auth_encapsulate_init() was added in OpenSSL 3.2.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2020-2023 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -2,14 +2,14 @@
|
||||
|
||||
=head1 NAME
|
||||
|
||||
EVP_KEM-ML-KEM-512,EVP_KEM-ML-KEM-768,EVP_KEM-ML-KEM-1024,EVP_KEM-ML-KEM
|
||||
EVP_KEM-ML-KEM-512, EVP_KEM-ML-KEM-768, EVP_KEM-ML-KEM-1024, EVP_KEM-ML-KEM
|
||||
- EVP_KEM ML-KEM keytype and algorithm support
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<ML-KEM> keytypes and parameters are described in L<EVP_PKEY-ML-KEM(7)>.
|
||||
See L<EVP_PKEY_encapsulate(3)> and L<EVP_PKEY_decapsulate(3)> for more info
|
||||
regarding the basic KEM operations.
|
||||
See L<EVP_PKEY_encapsulate(3)> and L<EVP_PKEY_decapsulate(3)> for more details
|
||||
about basic KEM operations.
|
||||
|
||||
=head2 ML-KEM KEM parameters
|
||||
|
||||
@ -18,10 +18,10 @@ regarding the basic KEM operations.
|
||||
=item "ikme" (B<OSSL_KEM_PARAM_IKME>)<UTF8 string>
|
||||
|
||||
The OpenSSL ML-KEM encapsulation mechanism can only be modified by
|
||||
setting randomness during encapsulation facilitating testing as per
|
||||
setting randomness during encapsulation, this enables testing, as per
|
||||
FIPS 203, section 6.2, algorithm 17.
|
||||
|
||||
This parameter is not to be set for other purposes than testing.
|
||||
This parameter should not be used for purposes other than testing.
|
||||
This parameter is disabled for use in the FIPS provider (TODO(ML-KEM)).
|
||||
|
||||
When this parameter is not set, encapsulation proceeds as per FIPS 203,
|
||||
@ -44,7 +44,7 @@ This can be set when using EVP_PKEY_encapsulate_init().
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_encapsulate(3)>,
|
||||
L<EVP_PKEY_decapsulate(3)>
|
||||
L<EVP_PKEY_decapsulate(3)>,
|
||||
L<EVP_KEYMGMT(3)>,
|
||||
L<EVP_PKEY(3)>,
|
||||
L<provider-keymgmt(7)>
|
||||
|
||||
@ -13,8 +13,8 @@ EVP_PKEY-ML-KEM
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
The B<ML-KEM-512>, B<ML-KEM-768>, and B<ML-KEM-1024> keytypes are implemented in
|
||||
OpenSSL's default provider.
|
||||
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).
|
||||
|
||||
@ -26,15 +26,17 @@ By default, no parameters are required for generating a key pair.
|
||||
|
||||
=item "seed" (B<OSSL_PKEY_PARAM_ML_KEM_SEED>) <octet string>
|
||||
|
||||
ML-KEM internally requires the generation of a keypair using a random value (seed).
|
||||
This optional parameter can be used to set the value prior to key pair 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.
|
||||
The length of the seed is 64 bytes.
|
||||
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.
|
||||
See L<provider-keymgmt(7)/Common Information Parameters> for further
|
||||
information.
|
||||
|
||||
=back
|
||||
|
||||
@ -52,20 +54,24 @@ support the following.
|
||||
|
||||
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.
|
||||
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 public key value with the
|
||||
EVP_PKEY_fromdata() and EVP_PKEY_todata() functions.
|
||||
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. Public keys are
|
||||
expected be encoded in a format as defined by FIPS 203.
|
||||
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.
|
||||
|
||||
@ -90,11 +96,13 @@ An B<ML-KEM-768> key can be generated like this:
|
||||
|
||||
pkey = EVP_PKEY_Q_keygen(NULL, NULL, "ML-KEM-768");
|
||||
|
||||
Equivalent calls are possible for B<ML-KEM-512> and B<ML-KEM-1024>.
|
||||
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_KEYMGMT(3)>,
|
||||
L<EVP_PKEY(3)>,
|
||||
L<provider-keymgmt(7)>,
|
||||
L<EVP_KEM-ML-KEM(7)>
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
@ -167,6 +167,12 @@ The OpenSSL default provider supports these operations and algorithms:
|
||||
|
||||
=item X448, see L<EVP_KEYEXCH-X448(7)>
|
||||
|
||||
=item ML-KEM-512, see L<EVP_KEM-ML-KEM-512(7)>
|
||||
|
||||
=item ML-KEM-768, see L<EVP_KEM-ML-KEM-768(7)>
|
||||
|
||||
=item ML-KEM-1024, see L<EVP_KEM-ML-KEM-1024(7)>
|
||||
|
||||
=item TLS1-PRF
|
||||
|
||||
=item HKDF
|
||||
@ -261,6 +267,8 @@ The OpenSSL default provider supports these operations and algorithms:
|
||||
|
||||
=item ED448, see L<EVP_KEYMGMT-ED448(7)>
|
||||
|
||||
=for comment We don't yet have the corresponding MLKEM doc in the works.
|
||||
|
||||
=item TLS1-PRF
|
||||
|
||||
=item HKDF
|
||||
@ -344,6 +352,8 @@ are also available in the base provider.
|
||||
|
||||
=item ML-DSA-87
|
||||
|
||||
=for comment Some day encoders for MLKEM...
|
||||
|
||||
=back
|
||||
|
||||
In addition to this provider, all of these encoding algorithms are also
|
||||
@ -384,6 +394,8 @@ combination with the FIPS provider.
|
||||
|
||||
=item DER
|
||||
|
||||
=for comment Some day decoders for MLKEM...
|
||||
|
||||
=back
|
||||
|
||||
In addition to this provider, all of these decoding algorithms are also
|
||||
|
||||
@ -500,9 +500,15 @@ L<EVP_PKEY_get_size(3)>,
|
||||
L<EVP_PKEY_get_bits(3)>,
|
||||
L<EVP_PKEY_get_security_bits(3)>,
|
||||
L<provider(7)>,
|
||||
L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>, L<EVP_PKEY-ED25519(7)>,
|
||||
L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-RSA(7)>,
|
||||
L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-ML-DSA(7)>,
|
||||
L<EVP_PKEY-X25519(7)>,
|
||||
L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ED25519(7)>,
|
||||
L<EVP_PKEY-ED448(7)>,
|
||||
L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-RSA(7)>,
|
||||
L<EVP_PKEY-DSA(7)>,
|
||||
L<EVP_PKEY-DH(7)>,
|
||||
L<EVP_PKEY-ML-DSA(7)>,
|
||||
L<EVP_PKEY-ML-KEM(7)>.
|
||||
|
||||
=head1 HISTORY
|
||||
@ -517,6 +523,8 @@ OSSL_FUNC_keymgmt_gen_gettable_params() were added in OpenSSL 3.4.
|
||||
|
||||
The parameters "sign-check" and "fips-indicator" were added in OpenSSL 3.4.
|
||||
|
||||
Support for the B<ML-DSA> and B<ML-KEM> algorithms was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user