ssl: Add support for ML-KEM

Author: IngelaAndin

lib/ssl/src/ssl_cipher.erl

@@ -1240,6 +1240,10 @@ generate_key_exchange(x25519) ->
     crypto:generate_key(ecdh, x25519);
 generate_key_exchange(x448) ->
     crypto:generate_key(ecdh, x448);
+generate_key_exchange(MLKem) when MLKem == mlkem512;
+                                  MLKem == mlkem768;
+                                  MLKem == mlkem1024 ->
+    crypto:generate_key(MLKem, []);
 generate_key_exchange(FFDHE) ->
     public_key:generate_key(ssl_dh_groups:dh_params(FFDHE)).
 

lib/ssl/src/tls_handshake_1_3.erl

@@ -915,8 +915,9 @@ handle_secrets(State0) ->
     State3 =  State2#state{protocol_specific = PS#{exporter_master_secret => ExporterSecret}},
     forget_master_secret(State3).
 
-calculate_handshake_secrets(PublicKey, PrivateKey, SelectedGroup, PSK,
+calculate_handshake_secrets(PublicKey, PrivateKeyOrSecret, SelectedGroup, PSK,
                               #state{connection_states = ConnectionStates,
+                                     static_env = #static_env{role = Role},
                                      handshake_env =
                                          #handshake_env{
                                             tls_handshake_history = HHistory}} = State0) ->
@@ -926,8 +927,15 @@ calculate_handshake_secrets(PublicKey, PrivateKey, SelectedGroup, PSK,
                          cipher_suite = CipherSuite} = SecParamsR,
     EarlySecret = tls_v1:key_schedule(early_secret, HKDFAlgo , {psk, PSK}),
 
-    IKM = calculate_shared_secret(PublicKey, PrivateKey, SelectedGroup),
-    HandshakeSecret = tls_v1:key_schedule(handshake_secret, HKDFAlgo, IKM, EarlySecret),
+    HandshakeSecret =
+        case is_mlkem(SelectedGroup) of
+            true ->
+                IKM = mlkem_calculate_shared_secret(Role, SelectedGroup, PublicKey, PrivateKeyOrSecret),
+                tls_v1:key_schedule(handshake_secret, HKDFAlgo, IKM, EarlySecret);
+            false ->
+                IKM = calculate_shared_secret(PublicKey, PrivateKeyOrSecret, SelectedGroup),
+                tls_v1:key_schedule(handshake_secret, HKDFAlgo, IKM, EarlySecret)
+        end,
 
     %% Calculate [sender]_handshake_traffic_secret
     {Messages, _} =  HHistory,
@@ -1155,6 +1163,10 @@ calculate_shared_secret(OthersKey, MyKey = #'ECPrivateKey'{}, _Group)
     Point = #'ECPoint'{point = OthersKey},
     public_key:compute_key(Point, MyKey).
 
+mlkem_calculate_shared_secret(client, Group, CipherText, PrivKey) ->
+    crypto:decapsulate_key(Group, PrivKey, CipherText);
+mlkem_calculate_shared_secret(server, _, _, Secret) ->
+    Secret.
 
 maybe_calculate_resumption_master_secret(#state{ssl_options = #{session_tickets := disabled}} = State) ->
     State;
@@ -2032,3 +2044,10 @@ plausible_missing_chain([_] = EncodedChain, undefined, SignAlg, Key, Session0) -
                     };
 plausible_missing_chain(_,Plausible,_,_,_) ->
     Plausible.
+
+is_mlkem(Group) when Group == mlkem512;
+                     Group == mlkem768;
+                     Group == mlkem1024 ->
+    true;
+is_mlkem(_) ->
+    false.

lib/ssl/src/tls_handshake_1_3.hrl

@@ -180,6 +180,11 @@
 -define(BRAINPOOLP384R1TLS13, 16#0020).
 -define(BRAINPOOLP512R1TLS13, 16#0021).
 
+%% ML-KEM
+-define(MLKEM512, 16#0200).
+-define(MLKEM768, 16#0201).
+-define(MLKEM1024, 16#0202).
+
 %% RFC 8446 Finite Field Groups (DHE)
 -define(FFDHE2048, 16#0100).
 -define(FFDHE3072, 16#0101).

lib/ssl/src/tls_server_connection_1_3.erl

@@ -462,7 +462,7 @@ do_handle_client_hello(#client_hello{cipher_suites = ClientCiphers,
         {Group, ClientPubKey} = select_client_public_key(Groups, ClientShares),
 
         %% Generate server_share
-        KeyShare = ssl_cipher:generate_server_share(Group),
+        KeyShare = generate_server_share(Group, ClientPubKey),
 
         State2 = case maps:get(max_frag_enum, Extensions, undefined) of
                       MaxFragEnum when is_record(MaxFragEnum, max_frag_enum) ->
@@ -763,6 +763,25 @@ default_or_fallback({fallback, _}, #session{} = Default) ->
 default_or_fallback(Default, _) ->
     Default.
 
+is_mlkem(Group) when Group == mlkem512;
+                     Group == mlkem768;
+                     Group == mlkem1024 ->
+    true;
+is_mlkem(_) ->
+    false.
+
+generate_server_share(Group, OtherPubKey) ->
+    case is_mlkem(Group) of
+        true ->
+            {Secret, CipherText} = crypto:encapsulate_key(Group, OtherPubKey),
+            #key_share_server_hello{server_share = #key_share_entry{
+                                                      group = Group,
+                                                      key_exchange = {CipherText, Secret}
+                                                     }};
+        false ->
+            ssl_cipher:generate_server_share(Group)
+    end.
+
 select_server_private_key(#key_share_server_hello{server_share = ServerShare}) ->
     select_private_key(ServerShare).
 

lib/ssl/src/tls_v1.erl

@@ -1227,6 +1227,9 @@ groups(all) ->
      brainpoolP256r1tls13,
      brainpoolP384r1tls13,
      brainpoolP512r1tls13,
+     mlkem512,
+     mlkem768,
+     mlkem1024,
      ffdhe2048,
      ffdhe3072,
      ffdhe4096,
@@ -1240,7 +1243,10 @@ groups(default) ->
      secp256r1,
      brainpoolP512r1tls13,
      brainpoolP384r1tls13,
-     brainpoolP256r1tls13
+     brainpoolP256r1tls13,
+     mlkem512,
+     mlkem768,
+     mlkem1024
     ];
 groups(TLSGroups) when is_list(TLSGroups) ->
     CryptoGroups = crypto_supported_groups(),
@@ -1251,7 +1257,7 @@ default_groups() ->
     groups(TLSGroups).
 
 crypto_supported_groups() ->
-    crypto:supports(curves) ++
+    crypto:supports(curves) ++ crypto:supports(kems) ++
         [ffdhe2048,ffdhe3072,ffdhe4096,ffdhe6144,ffdhe8192].
 
 group_to_enum(secp256r1) -> ?SECP256R1;
@@ -1262,6 +1268,9 @@ group_to_enum(x448)      -> ?X448;
 group_to_enum(brainpoolP256r1tls13) -> ?BRAINPOOLP256R1TLS13;
 group_to_enum(brainpoolP384r1tls13) -> ?BRAINPOOLP384R1TLS13;
 group_to_enum(brainpoolP512r1tls13) -> ?BRAINPOOLP512R1TLS13;
+group_to_enum(mlkem512)  -> ?MLKEM512;
+group_to_enum(mlkem768)  -> ?MLKEM768;
+group_to_enum(mlkem1024) -> ?MLKEM1024;
 group_to_enum(ffdhe2048) -> ?FFDHE2048;
 group_to_enum(ffdhe3072) -> ?FFDHE3072;
 group_to_enum(ffdhe4096) -> ?FFDHE4096;
@@ -1276,6 +1285,9 @@ enum_to_group(?X448) -> x448;
 enum_to_group(?BRAINPOOLP256R1TLS13) -> brainpoolP256r1tls13;
 enum_to_group(?BRAINPOOLP384R1TLS13) -> brainpoolP384r1tls13;
 enum_to_group(?BRAINPOOLP512R1TLS13) -> brainpoolP512r1tls13;
+enum_to_group(?MLKEM512)  -> mlkem512;
+enum_to_group(?MLKEM768)  -> mlkem768;
+enum_to_group(?MLKEM1024) -> mlkem1024;
 enum_to_group(?FFDHE2048) -> ffdhe2048;
 enum_to_group(?FFDHE3072) -> ffdhe3072;
 enum_to_group(?FFDHE4096) -> ffdhe4096;

lib/ssl/test/openssl_client_cert_SUITE.erl

@@ -62,6 +62,8 @@
          hello_retry_request/1,
          custom_groups/0,
          custom_groups/1,
+         mlkem_groups/0,
+         mlkem_groups/1,
          hello_retry_client_auth/0,
          hello_retry_client_auth/1,
          hello_retry_client_auth_empty_cert_accepted/0,
@@ -142,6 +144,7 @@ tls_1_3_tests() ->
     [
      hello_retry_request,
      custom_groups,
+     mlkem_groups,
      hello_retry_client_auth,
      hello_retry_client_auth_empty_cert_accepted,
      hello_retry_client_auth_empty_cert_rejected
@@ -540,6 +543,10 @@ custom_groups() ->
  ssl_cert_tests:custom_groups().
 custom_groups(Config) ->
   ssl_cert_tests:custom_groups(Config).
+mlkem_groups() ->
+    ssl_cert_tests:mlkem_groups().
+mlkem_groups(Config) ->
+    ssl_cert_tests:mlkem_groups(Config).
 unsupported_sign_algo_cert_client_auth() ->
  ssl_cert_tests:unsupported_sign_algo_cert_client_auth().
 unsupported_sign_algo_cert_client_auth(Config) ->

lib/ssl/test/openssl_server_cert_SUITE.erl

@@ -59,6 +59,8 @@
          hello_retry_request/1,
          custom_groups/0,
          custom_groups/1,
+         mlkem_groups/0,
+         mlkem_groups/1,
          hello_retry_client_auth/0,
          hello_retry_client_auth/1,
          hello_retry_client_auth_empty_cert_accepted/0,
@@ -135,6 +137,7 @@ tls_1_3_tests() ->
     [
      hello_retry_request,
      custom_groups,
+     mlkem_groups,
      hello_retry_client_auth,
      hello_retry_client_auth_empty_cert_accepted,
      hello_retry_client_auth_empty_cert_rejected
@@ -459,6 +462,10 @@ custom_groups() ->
     ssl_cert_tests:custom_groups().
 custom_groups(Config) ->
     ssl_cert_tests:custom_groups(Config).
+mlkem_groups() ->
+    ssl_cert_tests:mlkem_groups().
+mlkem_groups(Config) ->
+    ssl_cert_tests:mlkem_groups(Config).
 unsupported_sign_algo_cert_client_auth() ->
     ssl_cert_tests:unsupported_sign_algo_cert_client_auth().
 unsupported_sign_algo_cert_client_auth(Config) ->

lib/ssl/test/ssl_cert_SUITE.erl

@@ -127,6 +127,8 @@
          hello_retry_request/1,
          custom_groups/0,
          custom_groups/1,
+         mlkem_groups/0,
+         mlkem_groups/1,
          hello_retry_client_auth/0,
          hello_retry_client_auth/1,
          hello_retry_client_auth_empty_cert_accepted/0,
@@ -180,7 +182,7 @@ groups() ->
      {rsa_pss_rsae_1_3, [parallel], all_version_tests() ++ rsa_tests() ++ tls_1_3_tests() ++ tls_1_3_rsa_tests()},
      {rsa_pss_pss, [parallel], all_version_tests()},
      {rsa_pss_pss_1_3, [parallel], all_version_tests() ++ rsa_tests() ++ tls_1_3_tests() ++ tls_1_3_rsa_tests()},
-     {ecdsa_1_3, [parallel], all_version_tests() ++ tls_1_3_tests() ++ partial_chain_with_ecdsa()
+     {ecdsa_1_3, [parallel], all_version_tests() ++ tls_1_3_tests() ++ partial_chain_with_ecdsa() ++
           [signature_algorithms_bad_curve_secp256r1,
            signature_algorithms_bad_curve_secp384r1,
            signature_algorithms_bad_curve_secp521r1]},
@@ -213,6 +215,7 @@ tls_1_3_tests() ->
     [
      hello_retry_request,
      custom_groups,
+     mlkem_groups,
      client_auth_no_suitable_chain,
      cert_auth_in_first_ca,
      hello_retry_client_auth,
@@ -488,7 +491,7 @@ end_per_group(GroupName, Config) ->
   ssl_test_lib:end_per_group(GroupName, Config).
 
 
-init_per_group(mlkem_groups, Config) ->
+init_per_testcase(mlkem_groups, Config) ->
     case  [] =/= crypto:supports(kems) of
         true ->
             Config;
@@ -1364,6 +1367,26 @@ custom_groups(Config) ->
     ClientOpts = [{supported_groups,[secp384r1, secp256r1, x25519]}|ClientOpts1],
     ssl_test_lib:basic_test(ClientOpts, ServerOpts, Config).
 
+%%--------------------------------------------------------------------
+mlkem_groups() ->
+    [{doc,"Test that ssl server can select a common group for key-exchange"}].
+
+mlkem_groups(Config) ->
+    ClientOpts0 = ssl_test_lib:ssl_options(client_cert_opts, Config),
+    ServerOpts0 = ssl_test_lib:ssl_options(server_cert_opts, Config),
+
+    mlkem_kex(mlkem512, ClientOpts0, ServerOpts0, Config),
+    mlkem_kex(mlkem768, ClientOpts0, ServerOpts0, Config),
+    mlkem_kex(mlkem1024, ClientOpts0, ServerOpts0, Config).
+
+mlkem_kex(MLKem, ClientOpts0, ServerOpts0, Config) ->
+    %% Set versions
+    ServerOpts = [{versions, ['tlsv1.3']},
+                  {supported_groups, [MLKem]}|ServerOpts0],
+    ClientOpts1 = [{versions, ['tlsv1.2','tlsv1.3']}|ClientOpts0],
+    ClientOpts = [{supported_groups,[ MLKem, secp384r1, secp256r1, x25519]}|ClientOpts1],
+    ssl_test_lib:basic_test(ClientOpts, ServerOpts, Config).
+
 %%--------------------------------------------------------------------
 %% Triggers a Server Alert as ssl client does not have a certificate with a
 %% signature algorithm supported by the server (signature_algorithms_cert extension

lib/ssl/test/ssl_cert_tests.erl

@@ -63,6 +63,8 @@
          hello_retry_request/1,
          custom_groups/0,
          custom_groups/1,
+         mlkem_groups/0,
+         mlkem_groups/1,
          hello_retry_client_auth/0,
          hello_retry_client_auth/1,
          hello_retry_client_auth_empty_cert_accepted/0,
@@ -404,6 +406,25 @@ custom_groups(Config) ->
 
     ssl_test_lib:basic_test(ClientOpts, ServerOpts, Config).
 
+%%--------------------------------------------------------------------
+mlkem_groups() ->
+    [{doc,"Test that ssl server can select a common mlkem group for key-exchange"}].
+
+mlkem_groups(Config) ->
+    test_mlkem(Config, mlkem512),
+    test_mlkem(Config, mlkem768),
+    test_mlkem(Config, mlkem1024).
+
+test_mlkem(Config, MLKemGroup) ->
+    ClientOpts0 = ssl_test_lib:ssl_options(client_cert_opts, Config),
+    ServerOpts0 = ssl_test_lib:ssl_options(server_cert_opts, Config),
+
+    {ServerOpts, ClientOpts} = group_config_mlkem(Config,
+                                                  [{versions, ['tlsv1.3']} | ServerOpts0],
+                                                  [{versions, ['tlsv1.3']} | ClientOpts0], MLKemGroup),
+
+    ssl_test_lib:basic_test(ClientOpts, ServerOpts, Config).
+
 %%--------------------------------------------------------------------
 %% Triggers a Server Alert as ssl client does not have a certificate with a
 %% signature algorithm supported by the server (signature_algorithms_cert extension
@@ -566,6 +587,24 @@ group_config(Config, ServerOpts, ClientOpts) ->
                  [{groups,"P-256:X25519"} | ClientOpts]}
         end.
 
+
+group_config_mlkem(Config, ServerOpts, ClientOpts, Group) ->
+        case proplists:get_value(client_type, Config) of
+            erlang ->
+                {[{groups, openssl_mlkem(Group)} | ServerOpts],
+                 [{supported_groups, [Group]} | ClientOpts]};
+            openssl ->
+                {[{supported_groups, [Group]} | ServerOpts],
+                 [{groups, openssl_mlkem(Group)} | ClientOpts]}
+        end.
+
+openssl_mlkem(mlkem512) ->
+    "MLKEM512";
+openssl_mlkem(mlkem768) ->
+    "MLKEM768";
+openssl_mlkem(mlkem1024) ->
+    "MLKEM1024".
+
 choose_custom_key(#'RSAPrivateKey'{} = Key, Version)
   when (Version == 'dtlsv1') or (Version == 'tlsv1') or (Version == 'tlsv1.1') ->
     EFun = fun (PlainText, Options) ->