mirror of
https://github.com/openssl/openssl.git
synced 2025-04-06 20:20:50 +08:00
Remaining batch of ML-KEM-related doc updates
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
7772dbb17c
commit
e04a604d0d
@ -98,8 +98,10 @@ it may be reasonable to avoid protecting it with a password, since
|
||||
otherwise someone would have to type in the password every time the
|
||||
server needs to access the key.
|
||||
|
||||
For X25519 and X448, it's treated as a distinct algorithm but not as one of
|
||||
the curves listed with 'ecparam -list_curves' option. You can use
|
||||
the following command to generate an X25519 key:
|
||||
X25519, X448, Ed25519 and Ed448 are treated as distinct algorithms and not as
|
||||
one of the EC curves listed with 'ecparam -list_curves' option. You can use the
|
||||
following command to generate an X25519 key:
|
||||
|
||||
openssl genpkey -algorithm X25519 -out xkey.pem
|
||||
|
||||
# TODO(ML-KEM) Likewise ML-KEM once we have codecs.
|
||||
|
||||
@ -275,8 +275,9 @@ There are a few places where we do not enforce key size that need to be addresse
|
||||
- DSA. Keygen and Signing are no longer approved, verify is still allowed.
|
||||
- ECDSA B & K curves are deprecated, but still approved according to (IG C.K Resolution 4).\
|
||||
If we chose not to remove them , then we need to check that OSSL_PKEY_PARAM_USE_COFACTOR_ECDH is set for key agreement if the cofactor is not 1.
|
||||
- ED25519/ED448 is now approved.
|
||||
- X25519/X448 is not approved currently. keygen and keyexchange would also need an indicator if we allow it?
|
||||
- ED25519 and ED448 are now approved.
|
||||
- X25519 and X448 are not approved currently. keygen and keyexchange would also need an indicator if we allow them?
|
||||
- ML-KEM-512/768/1024 are not yet included in the FIPS module.
|
||||
- RSA encryption(for key agreement/key transport) using PKCSV15 is no longer allowed. (Note that this breaks TLS 1.2 using RSA for KeyAgreement),
|
||||
Padding mode updates required. Check RSA KEM also.
|
||||
- RSA signing using PKCS1 is still allowed (i.e. signature uses shaXXXWithRSAEncryption)
|
||||
|
||||
@ -77,9 +77,9 @@ OpenSSL providers allow it for the following:
|
||||
|
||||
=over 4
|
||||
|
||||
=item DH, EC, X25519, X448:
|
||||
=item DH, EC, X25519, X448, ML-KEM (512, 768 and 1024):
|
||||
|
||||
It's possible to set the encoded public key. This is supported in
|
||||
It is possible to set the encoded public key. This is supported in
|
||||
particular through L<EVP_PKEY_set1_encoded_public_key(3)>.
|
||||
|
||||
=item EC:
|
||||
@ -198,7 +198,11 @@ reflected back in the provider key.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<provider-keymgmt(7)>
|
||||
L<provider-keymgmt(7)>,
|
||||
L<EVP_PKEY-DH(7)>,
|
||||
L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-X25519(7)>,
|
||||
L<EVP_PKEY-ML-KEM(7)>.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
|
||||
@ -87,6 +87,9 @@ the standard built-in ones.
|
||||
Valid built-in algorithm names for private key generation are RSA, RSA-PSS, EC,
|
||||
X25519, X448, ED25519 and ED448.
|
||||
|
||||
=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
|
||||
format (and a PEM header name) and encoders/decoders.
|
||||
|
||||
Valid built-in algorithm names for parameter generation (see the B<-genparam>
|
||||
option) are DH, DSA and EC.
|
||||
|
||||
@ -138,6 +141,9 @@ algorithm can vary. The options for the OpenSSL implementations are detailed
|
||||
below. There are no key generation options defined for the X25519, X448, ED25519
|
||||
or ED448 algorithms.
|
||||
|
||||
=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
|
||||
format (and a PEM header name) and encoders/decoders.
|
||||
|
||||
=head2 RSA Key Generation Options
|
||||
|
||||
=over 4
|
||||
@ -501,6 +507,9 @@ Generate an ED448 private key:
|
||||
|
||||
openssl genpkey -algorithm ED448 -out xkey.pem
|
||||
|
||||
=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
|
||||
format (and a PEM header name) and encoders/decoders.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
The ability to use NIST curve names, and to generate an EC key directly,
|
||||
@ -508,6 +517,9 @@ were added in OpenSSL 1.0.2.
|
||||
The ability to generate X25519 keys was added in OpenSSL 1.1.0.
|
||||
The ability to generate X448, ED25519 and ED448 keys was added in OpenSSL 1.1.1.
|
||||
|
||||
=for comment TODO(ML-KEM) Soon also ML-KEM, once we have a standard private key
|
||||
format (and a PEM header name) and encoders/decoders.
|
||||
|
||||
The B<-engine> option was deprecated in OpenSSL 3.0.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
@ -250,6 +250,11 @@ This is needed only for RSA, where B<RSASVE>, is not the default mode, even
|
||||
though it is presently the only RSA KEM supported.
|
||||
See L<EVP_PKEY_CTX_set_kem_op(3)> and L<EVP_KEM-RSA(7)>.
|
||||
|
||||
=for comment TODO(ML-KEM) Add ML-KEM, once we have encoder/decoder support the
|
||||
associated keys. Specifically, the private key format is yet to
|
||||
be decided (may need to support two versions, the full FIPS203
|
||||
encoding or just the seed).
|
||||
|
||||
=item B<-kdf> I<algorithm>
|
||||
|
||||
Use key derivation function I<algorithm>. The supported algorithms are
|
||||
@ -438,6 +443,8 @@ for the B<-pkeyopt> B<digest> option.
|
||||
The X25519 and X448 algorithms support key derivation only. Currently there are
|
||||
no additional options.
|
||||
|
||||
=for comment TODO(ML-KEM) Likewise for ML-KEM, once we have encoders/decoders.
|
||||
|
||||
=head1 ED25519 AND ED448 ALGORITHMS
|
||||
|
||||
These algorithms only support signing and verifying. OpenSSL only implements the
|
||||
|
||||
@ -654,9 +654,11 @@ EVP_PKEY_CTX_set_kem_op() sets the KEM operation to run. This can be set after
|
||||
EVP_PKEY_encapsulate_init() or EVP_PKEY_decapsulate_init() to select the kem
|
||||
operation. For the key types that support encapsulation and don't have the
|
||||
default operation, e.g. RSA, this function must be called before
|
||||
EVP_PKEY_encapsulate() or EVP_PKEY_decapsulate(). The supported values for the
|
||||
built-in algorithms are enumerated in L<EVP_KEM-RSA(7)>, L<EVP_KEM-EC(7)>,
|
||||
L<EVP_KEM-X25519(7)>, and L<EVP_KEM-X448(7)>.
|
||||
EVP_PKEY_encapsulate() or EVP_PKEY_decapsulate().
|
||||
|
||||
The supported parameters for the built-in algorithms are documented in
|
||||
L<EVP_KEM-RSA(7)>, L<EVP_KEM-EC(7)>, L<EVP_KEM-X25519(7)>,
|
||||
L<EVP_KEM-X448(7)>, and L<EVP_KEM-ML-KEM(7)>.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
|
||||
@ -57,6 +57,7 @@ L<EVP_PKEY-DH(7)/DH parameters>
|
||||
L<EVP_PKEY-DH(7)/DH key generation parameters>
|
||||
L<EVP_PKEY-EC(7)/Common EC parameters>
|
||||
L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>
|
||||
L<EVP_PKEY-ML-KEM(7)/Common parameters>
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
@ -84,6 +85,8 @@ L<EVP_PKEY_keygen(3)>
|
||||
|
||||
All functions were added in OpenSSL 3.0.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2020-2024 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -40,7 +40,7 @@ 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
|
||||
possible to determine the required buffer size at run time. Otherwise, the
|
||||
decapsulated secret data is written to I<unwrapped> and the length of shared
|
||||
secret is written to I<*unwrappedlen>.
|
||||
|
||||
@ -51,8 +51,8 @@ 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.
|
||||
The length returned via I<*unwrappedlen> SHOULD be used to determine the actual
|
||||
length of the output.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
|
||||
@ -58,7 +58,7 @@ 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
|
||||
The lengths returned via I<*wrappedkeylen> and I<*genkeylen> SHOULD
|
||||
be used to determine the actual lengths of the outputs.
|
||||
|
||||
=head1 NOTES
|
||||
|
||||
@ -34,8 +34,8 @@ EVP_PKEY_fromdata() creates the structure to store a key or key parameters,
|
||||
given data from I<params>, I<selection> and a context that's been initialized
|
||||
with EVP_PKEY_fromdata_init(). The result is written to I<*ppkey>.
|
||||
I<selection> is described in L</Selections>.
|
||||
The parameters that can be used for various types of key are as described by the
|
||||
diverse "Common parameters" sections of the
|
||||
The parameters that can be used for various types of key are as described by
|
||||
the various "Common parameters" sections of the
|
||||
L<B<EVP_PKEY-RSA>(7)|EVP_PKEY-RSA(7)/Common RSA parameters>,
|
||||
L<B<EVP_PKEY-DSA>(7)|EVP_PKEY-DSA(7)/Common DSA & DH parameters>,
|
||||
L<B<EVP_PKEY-DH>(7)|EVP_PKEY-DH(7)/Common DH parameters>,
|
||||
@ -43,7 +43,10 @@ L<B<EVP_PKEY-EC>(7)|EVP_PKEY-EC(7)/Common EC parameters>,
|
||||
L<B<EVP_PKEY-ED448>(7)|EVP_PKEY-ED448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
L<B<EVP_PKEY-X25519>(7)|EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
L<B<EVP_PKEY-X448>(7)|EVP_PKEY-X448(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
and L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters> pages.
|
||||
L<B<EVP_PKEY-ED25519>(7)|EVP_PKEY-ED25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
and
|
||||
L<EVP_PKEY-ML-KEM-512(7)|EVP_PKEY-ML-KEM-768(7)|EVP_PKEY-ML-KEM-1024(7)/Common parameters>
|
||||
pages.
|
||||
|
||||
=for comment the awful list of links above is made this way so we get nice
|
||||
rendering as a man-page while still getting proper links in HTML
|
||||
@ -257,16 +260,28 @@ example with L<OSSL_PARAM_allocate_from_text(3)>.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_CTX_new(3)>, L<provider(7)>, L<EVP_PKEY_gettable_params(3)>,
|
||||
L<OSSL_PARAM(3)>, L<EVP_PKEY_todata(3)>,
|
||||
L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ED25519(7)>, L<EVP_PKEY-ML-DSA(7)>
|
||||
L<EVP_PKEY_CTX_new(3)>,
|
||||
L<EVP_PKEY_todata(3)>,
|
||||
L<EVP_PKEY_gettable_params(3)>,
|
||||
L<OSSL_PARAM(3)>,
|
||||
L<provider(7)>,
|
||||
L<EVP_PKEY-RSA(7)>,
|
||||
L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-ED25519(7)>,
|
||||
L<EVP_PKEY-ED448(7)>,
|
||||
L<EVP_PKEY-DSA(7)>,
|
||||
L<EVP_PKEY-DH(7)>,
|
||||
L<EVP_PKEY-X25519(7)>,
|
||||
L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ML-DSA(7)>,
|
||||
L<EVP_PKEY-ML-KEM(7)>.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
These functions were added in OpenSSL 3.0.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -100,11 +100,18 @@ If I<type> is C<RSA>,
|
||||
a B<size_t> parameter must be given to specify the size of the RSA key.
|
||||
If I<type> is C<EC>,
|
||||
a string parameter must be given to specify the name of the EC curve.
|
||||
If I<type> is C<X25519>, C<X448>, C<ED25519>, C<ED448>, or C<SM2>
|
||||
no further parameter is needed. Starting from OpenSSL version 3.5, other
|
||||
key types may be possible if they are supplied by the loaded providers.
|
||||
EVP_PKEY_Q_keygen() may be usable with such key types as long as
|
||||
they do not require further parameters.
|
||||
If I<type> is:
|
||||
C<ED25519>,
|
||||
C<ED448>,
|
||||
C<SM2>,
|
||||
C<X25519>,
|
||||
C<X448>,
|
||||
C<ML-KEM-512>,
|
||||
C<ML-KEM-768>, or
|
||||
C<ML-KEM-1024>
|
||||
no further parameters are needed. Other key types may be possible if they are
|
||||
supplied by the loaded providers. EVP_PKEY_Q_keygen() may be usable with such
|
||||
key types as long as they do not require further parameters.
|
||||
|
||||
=head1 RETURN VALUES
|
||||
|
||||
|
||||
@ -94,8 +94,16 @@ EVP_PKEY_new_raw_private_key_ex() allocates a new B<EVP_PKEY>. Unless an
|
||||
engine should be used for the key type, a provider for the key is found using
|
||||
the library context I<libctx> and the property query string I<propq>. The
|
||||
I<keytype> argument indicates what kind of key this is. The value should be a
|
||||
string for a public key algorithm that supports raw private keys, i.e one of
|
||||
"X25519", "ED25519", "X448" or "ED448". I<key> points to the raw private key
|
||||
string for a public key algorithm that supports raw private keys, e.g., one of:
|
||||
C<ED25519>,
|
||||
C<ED448>,
|
||||
C<X25519>,
|
||||
C<X448>,
|
||||
C<ML-KEM-512>,
|
||||
C<ML-KEM-768>,
|
||||
or
|
||||
C<ML-KEM-1024>.
|
||||
I<key> points to the raw private key
|
||||
data for this B<EVP_PKEY> which should be of length I<keylen>. The length
|
||||
should be appropriate for the type of the key. The public key data will be
|
||||
automatically derived from the given private key data (if appropriate for the
|
||||
@ -119,13 +127,27 @@ EVP_PKEY_new_raw_public_key_ex() works in the same way as
|
||||
EVP_PKEY_new_raw_private_key_ex() except that I<key> points to the raw
|
||||
public key data. The B<EVP_PKEY> structure will be initialised without any
|
||||
private key information. Algorithm types that support raw public keys are
|
||||
"X25519", "ED25519", "X448" or "ED448".
|
||||
B<ED25519>,
|
||||
B<ED448>,
|
||||
B<X25519>,
|
||||
B<X448>,
|
||||
B<ML-KEM-512>,
|
||||
B<ML-KEM-768>,
|
||||
and
|
||||
B<ML-KEM-1024>.
|
||||
|
||||
EVP_PKEY_new_raw_public_key() works in the same way as
|
||||
EVP_PKEY_new_raw_private_key() except that I<key> points to the raw public key
|
||||
data. The B<EVP_PKEY> structure will be initialised without any private key
|
||||
information. Algorithm types that support raw public keys are
|
||||
B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
|
||||
B<ED448>.
|
||||
B<ED25519>,
|
||||
B<X25519>,
|
||||
B<X448>
|
||||
B<ML-KEM-512>,
|
||||
B<ML-KEM-768>,
|
||||
and
|
||||
B<ML-KEM-1024>.
|
||||
|
||||
EVP_PKEY_new_mac_key() works in the same way as EVP_PKEY_new_raw_private_key().
|
||||
New applications should use EVP_PKEY_new_raw_private_key() instead.
|
||||
@ -137,8 +159,19 @@ actually written. If the buffer I<priv> is NULL then I<*len> is populated with
|
||||
the number of bytes required to hold the key. The calling application is
|
||||
responsible for ensuring that the buffer is large enough to receive the private
|
||||
key data. This function only works for algorithms that support raw private keys.
|
||||
Currently this is: B<EVP_PKEY_HMAC>, B<EVP_PKEY_POLY1305>, B<EVP_PKEY_SIPHASH>,
|
||||
B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or B<EVP_PKEY_ED448>.
|
||||
These include:
|
||||
B<ED25519>,
|
||||
B<ED448>,
|
||||
B<X25519>,
|
||||
B<X448>,
|
||||
B<HMAC>,
|
||||
B<POLY1305>,
|
||||
and
|
||||
B<SIPHASH>.
|
||||
EVP_PKEY_get_raw_private_key() also works with B<ML-KEM-512>, B<ML-KEM-768> and
|
||||
B<ML-KEM-1024> keys, which don't have legacy numeric I<NID> assigments, but
|
||||
their raw form is nevertheless available.
|
||||
|
||||
|
||||
EVP_PKEY_get_raw_public_key() fills the buffer provided by I<pub> with raw
|
||||
public key data. The size of the I<pub> buffer should be in I<*len> on entry
|
||||
@ -147,8 +180,15 @@ actually written. If the buffer I<pub> is NULL then I<*len> is populated with
|
||||
the number of bytes required to hold the key. The calling application is
|
||||
responsible for ensuring that the buffer is large enough to receive the public
|
||||
key data. This function only works for algorithms that support raw public keys.
|
||||
Currently this is: B<EVP_PKEY_X25519>, B<EVP_PKEY_ED25519>, B<EVP_PKEY_X448> or
|
||||
B<EVP_PKEY_ED448>.
|
||||
These include:
|
||||
B<ED25519>,
|
||||
B<ED448>,
|
||||
B<X25519>,
|
||||
and
|
||||
B<X448>
|
||||
EVP_PKEY_get_raw_public_key() also works with B<ML-KEM-512>, B<ML-KEM-768> and
|
||||
B<ML-KEM-1024> keys, which don't have legacy numeric I<NID> assigments, but
|
||||
their raw form is nevertheless available.
|
||||
|
||||
EVP_PKEY_new_CMAC_key() works in the same way as EVP_PKEY_new_raw_private_key()
|
||||
except it is only for the B<EVP_PKEY_CMAC> algorithm type. In addition to the
|
||||
@ -183,8 +223,20 @@ EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_set1_RSA(3)>, L<EVP_PKEY_set1_DSA(3)>, L<EVP_PKEY_set1_DH(3)> or
|
||||
L<EVP_PKEY_set1_EC_KEY(3)>
|
||||
L<EVP_PKEY_set1_RSA(3)>,
|
||||
L<EVP_PKEY_set1_DSA(3)>,
|
||||
L<EVP_PKEY_set1_DH(3)>,
|
||||
L<EVP_PKEY_set1_EC_KEY(3)>,
|
||||
L<EVP_PKEY-ED25519(7)>,
|
||||
L<EVP_PKEY-ED448(7)>.
|
||||
L<EVP_PKEY-HMAC(7)>,
|
||||
L<EVP_PKEY-Poly1305(7)>,
|
||||
L<EVP_PKEY-Siphash(7)>,
|
||||
L<EVP_PKEY-X25519(7)>,
|
||||
L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ML-KEM-512(7)>,
|
||||
L<EVP_PKEY-ML-KEM-768(7)>,
|
||||
L<EVP_PKEY-ML-KEM-1024(7)>.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
@ -208,6 +260,8 @@ The documentation of B<EVP_PKEY> was amended in OpenSSL 3.0 to allow there to
|
||||
be the private part of the keypair without the public part, where this was
|
||||
previously implied to be disallowed.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2002-2022 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -27,18 +27,24 @@ see L<openssl_user_macros(7)>:
|
||||
=head1 DESCRIPTION
|
||||
|
||||
EVP_PKEY_set1_encoded_public_key() can be used to set the public key value
|
||||
within an existing EVP_PKEY object. For the built-in OpenSSL algorithms this
|
||||
currently only works for those that support key exchange. Parameters are not
|
||||
set as part of this operation, so typically an application will create an
|
||||
EVP_PKEY first, set the parameters on it, and then call this function.
|
||||
within an existing EVP_PKEY object, which does not yet have either a public or
|
||||
private key assigned.
|
||||
For the built-in OpenSSL algorithms this currently only works for those that
|
||||
support key exchange or key encapsulation.
|
||||
Parameters are not set as part of this operation, so typically an application
|
||||
will create an EVP_PKEY first, set the parameters on it, and then call this
|
||||
function.
|
||||
For example setting the parameters might be done using
|
||||
L<EVP_PKEY_copy_parameters(3)>.
|
||||
|
||||
The format for the encoded public key will depend on the algorithm in use. For
|
||||
DH it should be encoded as a positive integer in big-endian form. For EC is
|
||||
should be a point conforming to Sec. 2.3.4 of the SECG SEC 1 ("Elliptic
|
||||
Curve Cryptography") standard. For X25519 and X448 it should be encoded in a
|
||||
format as defined by RFC7748.
|
||||
Curve Cryptography") standard. For B<X25519> and B<X448> it should be encoded
|
||||
in the format defined by RFC7748.
|
||||
For B<ML-KEM-512>, B<ML-KEM-768> and B<ML-KEM-1024>, this is the public key
|
||||
format defined in B<FIPS 203> (the 12-bit per-coefficient encoded public I<t>
|
||||
vector and 32-byte matrix seed I<rho>).
|
||||
|
||||
The key to be updated is supplied in B<pkey>. The buffer containing the encoded
|
||||
key is pointed to be B<pub>. The length of the buffer is supplied in B<publen>.
|
||||
@ -117,9 +123,17 @@ performing a key exchange operation.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<EVP_PKEY_new(3)>, L<EVP_PKEY_copy_parameters(3)>,
|
||||
L<EVP_PKEY_derive_init(3)>, L<EVP_PKEY_derive(3)>,
|
||||
L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>
|
||||
L<EVP_PKEY_new(3)>,
|
||||
L<EVP_PKEY_copy_parameters(3)>,
|
||||
L<EVP_PKEY_derive_init(3)>,
|
||||
L<EVP_PKEY_derive(3)>,
|
||||
L<EVP_PKEY-DH(7)>,
|
||||
L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-X25519(7)>,
|
||||
L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ML-KEM-512(7)>,
|
||||
L<EVP_PKEY-ML-KEM-768(7)>,
|
||||
L<EVP_PKEY-ML-KEM-1024(7)>.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
@ -129,6 +143,8 @@ added in OpenSSL 3.0.
|
||||
EVP_PKEY_set1_tls_encodedpoint() and EVP_PKEY_get1_tls_encodedpoint() were
|
||||
deprecated in OpenSSL 3.0.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -41,16 +41,26 @@ EVP_PKEY_todata() and EVP_PKEY_export() return 1 for success and 0 for failure.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<OSSL_PARAM(3)>, L<openssl-core.h(7)>,
|
||||
L<OSSL_PARAM(3)>,
|
||||
L<openssl-core.h(7)>,
|
||||
L<EVP_PKEY_fromdata(3)>,
|
||||
L<EVP_PKEY-RSA(7)>, L<EVP_PKEY-DSA(7)>, L<EVP_PKEY-DH(7)>, L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-ED448(7)>, L<EVP_PKEY-X25519(7)>, L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ED25519(7)>, L<EVP_PKEY-ML-DSA(7)>
|
||||
L<EVP_PKEY-RSA(7)>,
|
||||
L<EVP_PKEY-EC(7)>,
|
||||
L<EVP_PKEY-DSA(7)>,
|
||||
L<EVP_PKEY-ED25519(7)>
|
||||
L<EVP_PKEY-ED448(7)>,
|
||||
L<EVP_PKEY-DH(7)>,
|
||||
L<EVP_PKEY-X25519(7)>,
|
||||
L<EVP_PKEY-X448(7)>,
|
||||
L<EVP_PKEY-ML-DSA(7)>,
|
||||
L<EVP_PKEY-ML-KEM(7)>.
|
||||
|
||||
=head1 HISTORY
|
||||
|
||||
These functions were added in OpenSSL 3.0.
|
||||
|
||||
Support for B<ML-KEM> and B<ML-DSA> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2021-2022 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -169,10 +169,25 @@ Since TLS 1.2 has neither keyshares nor a hello retry mechanism, with TLS 1.2
|
||||
the enriched syntax is ultimately equivalent to just a simple ordered list of
|
||||
groups, as with the simple form above.
|
||||
|
||||
Groups for B<TLSv1.3> in the default provider are B<P-256>, B<P-384>,
|
||||
B<P-521>, B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>,
|
||||
B<ffdhe6144>, B<ffdhe8192>, B<brainpoolP256r1tls13>,
|
||||
B<brainpoolP384r1tls13> and B<brainpoolP512r1tls13>.
|
||||
The supported groups for B<TLSv1.3> include:
|
||||
B<secp256r1>,
|
||||
B<secp384r1>,
|
||||
B<secp521r1>,
|
||||
B<x25519>,
|
||||
B<x448>,
|
||||
B<brainpoolP256r1tls13>,
|
||||
B<brainpoolP384r1tls13>,
|
||||
B<brainpoolP512r1tls13>,
|
||||
B<ffdhe2048>,
|
||||
B<ffdhe3072>,
|
||||
B<ffdhe4096>,
|
||||
B<ffdhe6144>,
|
||||
B<ffdhe8192>
|
||||
B<MLKEM512>,
|
||||
B<MLKEM768>,
|
||||
and
|
||||
B<MLKEM1024>.
|
||||
|
||||
Additional providers may make available further algorithms via the
|
||||
TLS-GROUP capability. See L<provider-base(7)>.
|
||||
|
||||
@ -441,9 +456,24 @@ applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
|
||||
(e.g. B<prime256v1>). Group names are case sensitive. The list should be in
|
||||
order of preference with the most preferred group first.
|
||||
|
||||
Currently supported groups for B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>,
|
||||
B<X25519>, B<X448>, B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144>,
|
||||
B<ffdhe8192>.
|
||||
The supported groups for B<TLSv1.3> include:
|
||||
B<secp256r1>,
|
||||
B<secp384r1>,
|
||||
B<secp521r1>,
|
||||
B<x25519>,
|
||||
B<x448>,
|
||||
B<brainpoolP256r1tls13>,
|
||||
B<brainpoolP384r1tls13>,
|
||||
B<brainpoolP512r1tls13>,
|
||||
B<ffdhe2048>,
|
||||
B<ffdhe3072>,
|
||||
B<ffdhe4096>,
|
||||
B<ffdhe6144>,
|
||||
B<ffdhe8192>
|
||||
B<MLKEM512>,
|
||||
B<MLKEM768>,
|
||||
and
|
||||
B<MLKEM1024>.
|
||||
|
||||
=item B<Curves>
|
||||
|
||||
@ -823,6 +853,8 @@ added in OpenSSL 3.2.
|
||||
|
||||
B<PreferNoDHEKEX> was added in OpenSSL 3.3.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
=head1 COPYRIGHT
|
||||
|
||||
Copyright 2012-2024 The OpenSSL Project Authors. All Rights Reserved.
|
||||
|
||||
@ -44,12 +44,22 @@ functions (i.e. SSL_CTX_set1_groups_list() and SSL_set1_groups_list()).
|
||||
|
||||
SSL_CTX_set1_groups() sets the supported groups for B<ctx> to B<glistlen>
|
||||
groups in the array B<glist>. The array consist of all NIDs of supported groups.
|
||||
Currently supported groups for B<TLSv1.3> are B<NID_X9_62_prime256v1>,
|
||||
B<NID_secp384r1>, B<NID_secp521r1>, B<NID_X25519>, B<NID_X448>,
|
||||
B<NID_brainpoolP256r1tls13>, B<NID_brainpoolP384r1tls13>,
|
||||
B<NID_brainpoolP512r1tls13>, B<NID_ffdhe2048>, B<NID_ffdhe3072>,
|
||||
B<NID_ffdhe4096>, B<NID_ffdhe6144> and B<NID_ffdhe8192>.
|
||||
OpenSSL will use this array in different ways depending on TLS role and version:
|
||||
The supported groups for B<TLSv1.3> include:
|
||||
B<NID_X9_62_prime256v1>,
|
||||
B<NID_secp384r1>,
|
||||
B<NID_secp521r1>,
|
||||
B<NID_X25519>,
|
||||
B<NID_X448>,
|
||||
B<NID_brainpoolP256r1tls13>,
|
||||
B<NID_brainpoolP384r1tls13>,
|
||||
B<NID_brainpoolP512r1tls13>,
|
||||
B<NID_ffdhe2048>,
|
||||
B<NID_ffdhe3072>,
|
||||
B<NID_ffdhe4096>,
|
||||
B<NID_ffdhe6144>, and
|
||||
B<NID_ffdhe8192>.
|
||||
OpenSSL will use this array in different ways based on the TLS version, and
|
||||
whether the groups are used in a client or server.
|
||||
|
||||
For a TLS client, the groups are used directly in the supported groups
|
||||
extension. The extension's preference order, to be evaluated by the server, is
|
||||
@ -73,11 +83,27 @@ to use SSL_CTX_set1_groups_list() with the ability to specify group tuples.
|
||||
|
||||
SSL_CTX_set1_groups_list() sets the supported groups for B<ctx> to
|
||||
string I<list>. In contrast to SSL_CTX_set1_groups(), the names of the
|
||||
groups, rather than their NIDs, are used. Currently supported groups for
|
||||
B<TLSv1.3> are B<P-256>, B<P-384>, B<P-521>, B<X25519>, B<X448>,
|
||||
B<brainpoolP256r1tls13>, B<brainpoolP384r1tls13>, B<brainpoolP512r1tls13>,
|
||||
B<ffdhe2048>, B<ffdhe3072>, B<ffdhe4096>, B<ffdhe6144> and B<ffdhe8192>. Support
|
||||
for other groups may be added by external providers.
|
||||
groups, rather than their NIDs, are used.
|
||||
|
||||
The supported groups for B<TLSv1.3> include:
|
||||
B<P-256>,
|
||||
B<P-384>,
|
||||
B<P-521>,
|
||||
B<X25519>,
|
||||
B<X448>,
|
||||
B<ffdhe2048>,
|
||||
B<ffdhe3072>,
|
||||
B<ffdhe4096>,
|
||||
B<ffdhe6144>
|
||||
B<ffdhe8192>,
|
||||
B<MLKEM512>,
|
||||
B<MLKEM768>,
|
||||
B<MLKEM1024>,
|
||||
B<brainpoolP256r1tls13>,
|
||||
B<brainpoolP384r1tls13>, and
|
||||
B<brainpoolP512r1tls13>.
|
||||
Support for other groups may be added by external providers.
|
||||
|
||||
Each group can be either the B<NIST> name (e.g. B<P-256>), some other commonly
|
||||
used name where applicable (e.g. B<X25519>, B<ffdhe2048>) or an OpenSSL OID name
|
||||
(e.g. B<prime256v1>). Group names are case sensitive. The preferred group names
|
||||
@ -247,6 +273,8 @@ was added in OpenSSL 3.0.0.
|
||||
Support for ignoring unknown groups in SSL_CTX_set1_groups_list() and
|
||||
SSL_set1_groups_list() was added in OpenSSL 3.3.
|
||||
|
||||
Support for B<ML-KEM> was added in OpenSSL 3.5.
|
||||
|
||||
Earlier versions of this document described the list as a preference order.
|
||||
However, OpenSSL's behavior as a TLS 1.3 server is to consider I<all>
|
||||
supported groups as comparable in security.
|
||||
|
||||
@ -140,6 +140,9 @@ This is an unapproved algorithm.
|
||||
|
||||
=item X448, see L<EVP_KEYEXCH-X448(7)>
|
||||
|
||||
=for comment TODO(ML-KEM) L<EVP_KEM-ML-KEM(7)> once ML-KEM is supported in the
|
||||
FIPS module.
|
||||
|
||||
=item TLS1-PRF
|
||||
|
||||
=item HKDF
|
||||
|
||||
@ -102,6 +102,8 @@ are also available in the default provider.
|
||||
|
||||
=item ML-DSA-87
|
||||
|
||||
=for comment TODO(ML-KEM): We don't yet have encoders for ML-KEM.
|
||||
|
||||
=back
|
||||
|
||||
In addition to this provider, all of these encoding algorithms are also
|
||||
@ -142,6 +144,8 @@ combination with the FIPS provider.
|
||||
|
||||
=item ML-DSA-87
|
||||
|
||||
=for comment We don't yet have decoders for MLKEM...
|
||||
|
||||
=back
|
||||
|
||||
In addition to this provider, all of these decoding algorithms are also
|
||||
|
||||
@ -247,10 +247,6 @@ The OpenSSL default provider supports these operations and algorithms:
|
||||
|
||||
=over 4
|
||||
|
||||
=item DH, see L<EVP_KEYMGMT-DH(7)>
|
||||
|
||||
=item DHX, see L<EVP_KEYMGMT-DHX(7)>
|
||||
|
||||
=item DSA, see L<EVP_KEYMGMT-DSA(7)>
|
||||
|
||||
=item RSA, see L<EVP_KEYMGMT-RSA(7)>
|
||||
@ -259,15 +255,31 @@ The OpenSSL default provider supports these operations and algorithms:
|
||||
|
||||
=item EC, see L<EVP_KEYMGMT-EC(7)>
|
||||
|
||||
=item X25519, see L<EVP_KEYMGMT-X25519(7)>
|
||||
|
||||
=item X448, see L<EVP_KEYMGMT-X448(7)>
|
||||
|
||||
=item ED25519, see L<EVP_KEYMGMT-ED25519(7)>
|
||||
|
||||
=item ED448, see L<EVP_KEYMGMT-ED448(7)>
|
||||
|
||||
=for comment We don't yet have the corresponding MLKEM doc in the works.
|
||||
=item SM2, see L<EVP_KEYMGMT-SM2(7)>
|
||||
|
||||
=item DH, see L<EVP_KEYMGMT-DH(7)>
|
||||
|
||||
=item DHX, see L<EVP_KEYMGMT-DHX(7)>
|
||||
|
||||
=item X25519, see L<EVP_KEYMGMT-X25519(7)>
|
||||
|
||||
=item X448, see L<EVP_KEYMGMT-X448(7)>
|
||||
|
||||
=item ML-DSA-44, see L<EVP_KEYMGMT-ML-DSA(7)>
|
||||
|
||||
=item ML-DSA-65, see L<EVP_KEYMGMT-ML-DSA(7)>
|
||||
|
||||
=item ML-DSA-87, see L<EVP_KEYMGMT-ML-DSA(7)>
|
||||
|
||||
=item MK-KEM-512, see L<EVP_KEYMGMT-ML-KEM-512(7)>
|
||||
|
||||
=item MK-KEM-768, see L<EVP_KEYMGMT-ML-KEM-768(7)>
|
||||
|
||||
=item MK-KEM-1024, see L<EVP_KEYMGMT-ML-KEM-1024(7)>
|
||||
|
||||
=item TLS1-PRF
|
||||
|
||||
@ -283,20 +295,6 @@ The OpenSSL default provider supports these operations and algorithms:
|
||||
|
||||
=item CMAC, see L<EVP_KEYMGMT-CMAC(7)>
|
||||
|
||||
=item SM2, see L<EVP_KEYMGMT-SM2(7)>
|
||||
|
||||
=item ML-DSA-44, see L<EVP_KEYMGMT-ML-DSA(7)>
|
||||
|
||||
=item ML-DSA-65, see L<EVP_KEYMGMT-ML-DSA(7)>
|
||||
|
||||
=item ML-DSA-87, see L<EVP_KEYMGMT-ML-DSA(7)>
|
||||
|
||||
=item ML-KEM-512, see L<EVP_KEYMGMT-ML-KEM-512(7)>
|
||||
|
||||
=item ML-KEM-768, see L<EVP_KEYMGMT-ML-KEM-768(7)>
|
||||
|
||||
=item ML-KEM-1024, see L<EVP_KEYMGMT-ML-KEM-1024(7)>
|
||||
|
||||
=back
|
||||
|
||||
=head2 Random Number Generation
|
||||
|
||||
@ -515,7 +515,7 @@ See L<EVP_PKEY-EC(7)/Common EC parameters>
|
||||
|
||||
"pkcs1" padding is no longer approved.
|
||||
|
||||
See L<EVP_ASYM_CIPHER-RSA(7)/RSA Asymmetric Cipher parameters> and
|
||||
See L<EVP_ASYM_CIPHER-RSA(7)/RSA Asymmetric Cipher parameters> and
|
||||
L<EVP_KEM-RSA(7)/RSA KEM parameters>
|
||||
|
||||
=item RSA Signatures
|
||||
@ -568,6 +568,8 @@ internally for non security purposes.
|
||||
The unapproved (non FIPS validated) algorithms have a property query value of
|
||||
"fips=no".
|
||||
|
||||
=for comment TODO(ML-KEM) Once in the FIPS module.
|
||||
|
||||
The following algorithms use a unique indicator and do not trigger the
|
||||
indicator callback.
|
||||
|
||||
|
||||
@ -421,7 +421,7 @@ EC EVP_PKEYs with the SM2 curve have been reworked to automatically become
|
||||
EVP_PKEY_SM2 rather than EVP_PKEY_EC.
|
||||
|
||||
Unlike in previous OpenSSL versions, this means that applications cannot
|
||||
call C<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
|
||||
call B<EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2)> to get SM2 computations.
|
||||
|
||||
Parameter and key generation is also reworked to make it possible
|
||||
to generate EVP_PKEY_SM2 parameters and keys. Applications must now generate
|
||||
@ -1058,14 +1058,23 @@ APIs, or alternatively use L<EVP_PKEY_fromdata(3)> or L<EVP_PKEY_todata(3)>.
|
||||
=head4 Deprecated low-level key parameter getters
|
||||
|
||||
Functions that access low-level objects directly such as L<RSA_get0_n(3)> are now
|
||||
deprecated. Applications should use one of L<EVP_PKEY_get_bn_param(3)>,
|
||||
L<EVP_PKEY_get_int_param(3)>, l<EVP_PKEY_get_size_t_param(3)>,
|
||||
L<EVP_PKEY_get_utf8_string_param(3)>, L<EVP_PKEY_get_octet_string_param(3)> or
|
||||
L<EVP_PKEY_get_params(3)> to access fields from an EVP_PKEY.
|
||||
Gettable parameters are listed in L<EVP_PKEY-RSA(7)/Common RSA parameters>,
|
||||
L<EVP_PKEY-DH(7)/DH parameters>, L<EVP_PKEY-DSA(7)/DSA parameters>,
|
||||
L<EVP_PKEY-FFC(7)/FFC parameters>, L<EVP_PKEY-EC(7)/Common EC parameters> and
|
||||
L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>.
|
||||
deprecated. Applications should use one of:
|
||||
L<EVP_PKEY_get_bn_param(3)>,
|
||||
L<EVP_PKEY_get_int_param(3)>,
|
||||
L<EVP_PKEY_get_size_t_param(3)>,
|
||||
L<EVP_PKEY_get_utf8_string_param(3)>,
|
||||
L<EVP_PKEY_get_octet_string_param(3)>, or
|
||||
L<EVP_PKEY_get_params(3)>,
|
||||
to access fields from an EVP_PKEY.
|
||||
Gettable parameters are listed in:
|
||||
L<EVP_PKEY-RSA(7)/Common RSA parameters>,
|
||||
L<EVP_PKEY-EC(7)/Common EC parameters>,
|
||||
L<EVP_PKEY-DSA(7)/DSA parameters>,
|
||||
L<EVP_PKEY-DH(7)/DH parameters>,
|
||||
L<EVP_PKEY-FFC(7)/FFC parameters>,
|
||||
L<EVP_PKEY-X25519(7)/Common X25519, X448, ED25519 and ED448 parameters>,
|
||||
and
|
||||
L<EVP_PKEY-ML-KEM(7)/Common parameters>.
|
||||
Applications may also use L<EVP_PKEY_todata(3)> to return all fields.
|
||||
|
||||
=head4 Deprecated low-level key parameter setters
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user