ML-KEM hybrids for TLS

- When used as KEMs in TLS the ECDHE algorithms are NOT subjected to
  HPKE Extract/Expand key derivation.  Instead the TLS HKDF is used
  as usual.

- Consequently these KEMs are just the usual ECDHE key exchange
  operations, be it with the encap ECDH private key unavoidably
  ephemeral.

- A new "MLX" KEM provider is added that supports four hybrids of EC/ECX
  DH with ML-KEM:

    * ML-KEM-768 + X25519
    * ML-KEM-1024 + X448
    * P-256 + ML-KEM-768
    * P-384 + ML-KEM-1024

- Support listing of implemented TLS groups.

  The SSL_CTX_get0_implemented_groups() function and new
  `openssl list -tls-groups` and `openssl list -all-tls-groups`
  commands make it possible to determine which groups are
  implemented by the SSL library for a particular TLS version
  or range of versions matching an SSL_CTX.

Reviewed-by: Tomas Mraz <[email protected]>
Reviewed-by: Tim Hudson <[email protected]>
(Merged from openssl#26220)

AUTHORS.md

@@ -12,6 +12,7 @@ Groups
 
  * OpenSSL Software Services, Inc.
  * OpenSSL Software Foundation, Inc.
+ * Google LLC
 
 Individuals
 -----------

apps/list.c

@@ -23,6 +23,8 @@
 #include <openssl/store.h>
 #include <openssl/core_names.h>
 #include <openssl/rand.h>
+#include <openssl/safestack.h>
+#include <openssl/ssl.h>
 #include <openssl/tls1.h>
 #include "apps.h"
 #include "app_params.h"
@@ -776,6 +778,42 @@ static int list_tls_sigalg_caps(OSSL_PROVIDER *provider, void *cbdata)
     return 1;
 }
 
+#if !defined(OPENSSL_NO_TLS1_3) || !defined(OPENSSL_NO_TLS1_2)
+static void list_tls_groups(int version, int all)
+{
+    SSL_CTX *ctx = NULL;
+    STACK_OF(OPENSSL_CSTRING) *groups;
+    size_t i, num;
+
+    if ((groups = sk_OPENSSL_CSTRING_new_null()) == NULL) {
+        BIO_printf(bio_err, "ERROR: Memory allocation\n");
+        return;
+    }
+    if ((ctx = SSL_CTX_new(TLS_method())) == NULL) {
+        BIO_printf(bio_err, "ERROR: Memory allocation\n");
+        goto err;
+    }
+    if (!SSL_CTX_set_min_proto_version(ctx, version)
+        || !SSL_CTX_set_max_proto_version(ctx, version)) {
+        BIO_printf(bio_err, "ERROR: setting TLS protocol version\n");
+        goto err;
+    }
+    if (!SSL_CTX_get0_implemented_groups(ctx, all, groups)) {
+        BIO_printf(bio_err, "ERROR: getting implemented TLS group list\n");
+        goto err;
+    }
+    num = sk_OPENSSL_CSTRING_num(groups);
+    for (i = 0; i < num; ++i) {
+        BIO_printf(bio_out, "%s%c", sk_OPENSSL_CSTRING_value(groups, i),
+                   (i < num - 1) ? ':' : '\n');
+    }
+  err:
+    SSL_CTX_free(ctx);
+    sk_OPENSSL_CSTRING_free(groups);
+    return;
+}
+#endif
+
 static void list_tls_signatures(void)
 {
     int tls_sigalg_listed = 0;
@@ -1514,6 +1552,15 @@ typedef enum HELPLIST_CHOICE {
     OPT_TLS_SIGNATURE_ALGORITHMS, OPT_ASYM_CIPHER_ALGORITHMS,
     OPT_STORE_LOADERS, OPT_PROVIDER_INFO, OPT_OBJECTS,
     OPT_SELECT_NAME,
+#if !defined(OPENSSL_NO_TLS1_3) || !defined(OPENSSL_NO_TLS1_2)
+    OPT_ALL_TLS_GROUPS, OPT_TLS_GROUPS,
+# if !defined(OPENSSL_NO_TLS1_2)
+    OPT_TLS1_2,
+# endif
+# if !defined(OPENSSL_NO_TLS1_3)
+    OPT_TLS1_3,
+# endif
+#endif
 #ifndef OPENSSL_NO_DEPRECATED_3_0
     OPT_ENGINES,
 #endif
@@ -1571,6 +1618,20 @@ const OPTIONS list_options[] = {
      "List of public key methods"},
     {"store-loaders", OPT_STORE_LOADERS, '-',
      "List of store loaders"},
+#if !defined(OPENSSL_NO_TLS1_2) || !defined(OPENSSL_NO_TLS1_3)
+    {"tls-groups", OPT_TLS_GROUPS, '-',
+     "List implemented TLS key exchange 'groups'" },
+    {"all-tls-groups", OPT_ALL_TLS_GROUPS, '-',
+     "List implemented TLS key exchange 'groups' and all aliases" },
+# ifndef OPENSSL_NO_TLS1_2
+    {"tls1_2", OPT_TLS1_2, '-',
+     "When listing 'groups', list those compatible with TLS1.2"},
+# endif
+# ifndef OPENSSL_NO_TLS1_3
+    {"tls1_3", OPT_TLS1_3, '-',
+     "When listing 'groups', list those compatible with TLS1.3"},
+# endif
+#endif
     {"providers", OPT_PROVIDER_INFO, '-',
      "List of provider information"},
 #ifndef OPENSSL_NO_DEPRECATED_3_0
@@ -1593,6 +1654,14 @@ int list_main(int argc, char **argv)
     HELPLIST_CHOICE o;
     int one = 0, done = 0;
     int print_newline = 0;
+#if !defined(OPENSSL_NO_TLS1_3) || !defined(OPENSSL_NO_TLS1_2)
+    int all_tls_groups = 0;
+# if !defined(OPENSSL_NO_TLS1_3)
+    unsigned int tls_version = TLS1_3_VERSION;
+# else
+    unsigned int tls_version = TLS1_2_VERSION;
+# endif
+#endif
     struct {
         unsigned int commands:1;
         unsigned int all_algorithms:1;
@@ -1611,6 +1680,7 @@ int list_main(int argc, char **argv)
         unsigned int tls_signature_algorithms:1;
         unsigned int keyexchange_algorithms:1;
         unsigned int kem_algorithms:1;
+        unsigned int tls_groups:1;
         unsigned int asym_cipher_algorithms:1;
         unsigned int pk_algorithms:1;
         unsigned int pk_method:1;
@@ -1691,6 +1761,25 @@ int list_main(int argc, char **argv)
         case OPT_KEM_ALGORITHMS:
             todo.kem_algorithms = 1;
             break;
+#if !defined(OPENSSL_NO_TLS1_3) || !defined(OPENSSL_NO_TLS1_2)
+        case OPT_TLS_GROUPS:
+            todo.tls_groups = 1;
+            break;
+        case OPT_ALL_TLS_GROUPS:
+            all_tls_groups = 1;
+            todo.tls_groups = 1;
+            break;
+# if !defined(OPENSSL_NO_TLS1_2)
+        case OPT_TLS1_2:
+            tls_version = TLS1_2_VERSION;
+            break;
+# endif
+# if !defined(OPENSSL_NO_TLS1_3)
+        case OPT_TLS1_3:
+            tls_version = TLS1_3_VERSION;
+            break;
+# endif
+#endif
         case OPT_ASYM_CIPHER_ALGORITHMS:
             todo.asym_cipher_algorithms = 1;
             break;
@@ -1810,6 +1899,10 @@ int list_main(int argc, char **argv)
         MAYBE_ADD_NL(list_keyexchanges());
     if (todo.kem_algorithms)
         MAYBE_ADD_NL(list_kems());
+#if !defined(OPENSSL_NO_TLS1_3) || !defined(OPENSSL_NO_TLS1_2)
+    if (todo.tls_groups)
+        MAYBE_ADD_NL(list_tls_groups(tls_version, all_tls_groups));
+#endif
     if (todo.pk_algorithms)
         MAYBE_ADD_NL(list_pkey());
     if (todo.pk_method)

crypto/err/openssl.txt

@@ -1,4 +1,4 @@
-# Copyright 1999-2024 The OpenSSL Project Authors. All Rights Reserved.
+# Copyright 1999-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
@@ -1133,6 +1133,8 @@ PROV_R_NOT_XOF_OR_INVALID_LENGTH:113:not xof or invalid length
 PROV_R_NO_INSTANCE_ALLOWED:242:no instance allowed
 PROV_R_NO_KEY_SET:114:no key set
 PROV_R_NO_PARAMETERS_SET:177:no parameters set
+PROV_R_NULL_LENGTH_POINTER:247:null length pointer
+PROV_R_NULL_OUTPUT_BUFFER:245:null output buffer
 PROV_R_ONESHOT_CALL_OUT_OF_ORDER:239:oneshot call out of order
 PROV_R_OPERATION_NOT_SUPPORTED_FOR_THIS_KEYTYPE:178:\
 	operation not supported for this keytype
@@ -1168,9 +1170,11 @@ PROV_R_UNSUPPORTED_CEK_ALG:145:unsupported cek alg
 PROV_R_UNSUPPORTED_KEY_SIZE:153:unsupported key size
 PROV_R_UNSUPPORTED_MAC_TYPE:137:unsupported mac type
 PROV_R_UNSUPPORTED_NUMBER_OF_ROUNDS:152:unsupported number of rounds
+PROV_R_UNSUPPORTED_SELECTION:248:unsupported selection
 PROV_R_UPDATE_CALL_OUT_OF_ORDER:240:update call out of order
 PROV_R_URI_AUTHORITY_UNSUPPORTED:223:uri authority unsupported
 PROV_R_VALUE_ERROR:138:value error
+PROV_R_WRONG_CIPHERTEXT_SIZE:246:wrong ciphertext size
 PROV_R_WRONG_FINAL_BLOCK_LENGTH:107:wrong final block length
 PROV_R_WRONG_OUTPUT_BUFFER_SIZE:139:wrong output buffer size
 PROV_R_XOF_DIGESTS_NOT_ALLOWED:183:xof digests not allowed

crypto/ml_kem/ml_kem.c

@@ -7,8 +7,6 @@
  * https://www.openssl.org/source/license.html
  */
 
-/* Copyright (c) 2024, Google Inc. */
-
 #include <internal/common.h>
 #include <internal/constant_time.h>
 #include <internal/sha3.h>

doc/man1/openssl-list.pod.in

@@ -32,6 +32,10 @@ B<openssl list>
 [B<-key-managers>]
 [B<-key-exchange-algorithms>]
 [B<-kem-algorithms>]
+[B<-tls-groups>]
+[B<-all-tls-groups>]
+[B<-tls1_2>]
+[B<-tls1_3>]
 [B<-signature-algorithms>]
 [B<-tls-signature-algorithms>]
 [B<-asymcipher-algorithms>]
@@ -191,6 +195,29 @@ Display a list of key exchange algorithms.
 
 Display a list of key encapsulation algorithms.
 
+=item B<-tls-groups>
+
+Display a list of the IANA names of all available (implemented) TLS groups.
+By default the listed groups are those compatible with TLS 1.3.
+
+=item B<-all-tls-groups>
+
+Display a list of the names of all available (implemented) TLS groups,
+including any aliases.
+Some groups are known under multiple names, for example, B<secp256r1> is also
+known as B<P-256>.
+By default the listed groups are those compatible with TLS 1.3.
+
+=item B<-tls1_2>
+
+When listing TLS groups, list those compatible with TLS 1.2
+
+=item B<-tls1_3>
+
+When listing TLS groups, output those compatible with TLS 1.3.
+TLS 1.3 is the current default protocol version, but the default version is
+subject to change, so best to specify the version explicitly.
+
 =item B<-signature-algorithms>
 
 Display a list of signature algorithms.

doc/man1/openssl-s_client.pod.in

@@ -669,11 +669,14 @@ For example strings, see L<SSL_CTX_set1_sigalgs(3)>
 Specifies the list of supported curves to be sent by the client. The curve is
 ultimately selected by the server.
 
-The list of all supported groups includes named EC parameters as well as X25519
-and X448 or FFDHE groups, and may also include groups implemented in 3rd-party
-providers. For a list of named EC parameters, use:
-
-    $ openssl ecparam -list_curves
+The list of available groups includes various built-in named EC curves, as well
+as X25519 and X448, FFDHE groups, and any additional groups implemented in the
+default or 3rd-party providers.
+The commands below list the available groups for TLS 1.2 and TLS 1.3,
+respectively:
+
+    $ openssl list -tls1_2 -tls-groups
+    $ openssl list -tls1_3 -tls-groups
 
 =item B<-cipher> I<cipherlist>
 

doc/man1/openssl-s_server.pod.in

@@ -675,11 +675,14 @@ Signature algorithms to support for client certificate authentication
 
 Specifies the elliptic curve to use. NOTE: this is single curve, not a list.
 
-The list of all supported groups includes named EC parameters as well as X25519
-and X448 or FFDHE groups, and may also include groups implemented in 3rd-party
-providers. For a list of named EC parameters, use:
-
-    $ openssl ecparam -list_curves
+The list of available groups includes various built-in named EC curves, as well
+as X25519 and X448, FFDHE groups, and any additional groups implemented in the
+default or 3rd-party providers.
+The commands below list the available groups for TLS 1.2 and TLS 1.3,
+respectively.
+
+    $ openssl list -tls1_2 -tls-groups
+    $ openssl list -tls1_3 -tls-groups
 
 =item B<-cipher> I<val>