Add initial support for MLKEM768 (without any new Security Policies)

crypto/s2n_libcrypto.h

@@ -17,6 +17,8 @@
 
 #include "utils/s2n_result.h"
 
+uint64_t s2n_libcrypto_awslc_api_version(void);
+bool s2n_libcrypto_is_awslc();
 S2N_RESULT s2n_libcrypto_validate_runtime(void);
 const char *s2n_libcrypto_get_version_name(void);
 bool s2n_libcrypto_supports_flag_no_check_time();

crypto/s2n_pq.c

@@ -33,3 +33,15 @@ bool s2n_pq_is_enabled()
 {
     return s2n_libcrypto_supports_evp_kem();
 }
+
+bool s2n_libcrypto_supports_mlkem()
+{
+    /* S2N_LIBCRYPTO_SUPPORTS_MLKEM will be auto-detected and #defined if
+     * ./tests/features/S2N_LIBCRYPTO_SUPPORTS_MLKEM.c successfully compiles
+     */
+#if defined(S2N_LIBCRYPTO_SUPPORTS_MLKEM)
+    return true;
+#else
+    return false;
+#endif
+}

crypto/s2n_pq.h

@@ -23,3 +23,4 @@
 
 bool s2n_pq_is_enabled(void);
 bool s2n_libcrypto_supports_evp_kem(void);
+bool s2n_libcrypto_supports_mlkem(void);

tests/features/S2N_LIBCRYPTO_SUPPORTS_MLKEM.c

@@ -0,0 +1,31 @@
+/*
+* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+*
+* Licensed under the Apache License, Version 2.0 (the "License").
+* You may not use this file except in compliance with the License.
+* A copy of the License is located at
+*
+*  http://aws.amazon.com/apache2.0
+*
+* or in the "license" file accompanying this file. This file is distributed
+* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+* express or implied. See the License for the specific language governing
+* permissions and limitations under the License.
+*/
+
+#include <openssl/evp.h>
+#include <openssl/nid.h>
+
+int main()
+{
+    EVP_PKEY_CTX *ctx = EVP_PKEY_CTX_new_id(EVP_PKEY_KEM, NULL);
+    if (ctx == NULL) {
+        return 1;
+    }
+    if (!EVP_PKEY_CTX_kem_set_params(ctx, NID_MLKEM768)) {
+        EVP_PKEY_CTX_free(ctx);
+        return 1;
+    }
+    EVP_PKEY_CTX_free(ctx);
+    return 0;
+}

tests/unit/kats/generate_pq_hybrid_tls13_handshake_kats.py

@@ -208,6 +208,34 @@
         "pq_shared_secret": "B10F7394926AD3B49C5D62D5AEB531D5757538BCC0DA9E550D438F1B61BD7419",
         "transcript_hash": "35412cebcf35cb8a7af8f78278a486fc798f8702eaebd067c97acb27bffe13524d8426a4ed57956b4fd0ffdc4c90be52",
     },
+    {
+        "group_name": "X25519MLKEM768",
+        "cipher_suite": "TLS_AES_128_GCM_SHA256",
+        "ec_shared_secret": "519be87fa0599077e5673d6f2d910aa150d7fef783c5e1491961fdf63b255910",
+        "pq_shared_secret": "B408D5D115713F0A93047DBBEA832E4340787686D59A9A2D106BD662BA0AA035",
+        "transcript_hash": "f5f7f7867668be4b792159d4d194a03ec5cfa238b6409b5ca2ddccfddcc92a2b",
+    },
+    {
+        "group_name": "X25519MLKEM768",
+        "cipher_suite": "TLS_AES_256_GCM_SHA384",
+        "ec_shared_secret": "519be87fa0599077e5673d6f2d910aa150d7fef783c5e1491961fdf63b255910",
+        "pq_shared_secret": "B408D5D115713F0A93047DBBEA832E4340787686D59A9A2D106BD662BA0AA035",
+        "transcript_hash": "35412cebcf35cb8a7af8f78278a486fc798f8702eaebd067c97acb27bffe13524d8426a4ed57956b4fd0ffdc4c90be52",
+    },
+    {
+        "group_name": "SecP256r1MLKEM768",
+        "cipher_suite": "TLS_AES_128_GCM_SHA256",
+        "ec_shared_secret": "9348e27655539e08fffe46b35f863dd634e7437cc6bc11c7d329ef5484ec3b60",
+        "pq_shared_secret": "B408D5D115713F0A93047DBBEA832E4340787686D59A9A2D106BD662BA0AA035",
+        "transcript_hash": "f5f7f7867668be4b792159d4d194a03ec5cfa238b6409b5ca2ddccfddcc92a2b",
+    },
+    {
+        "group_name": "SecP256r1MLKEM768",
+        "cipher_suite": "TLS_AES_256_GCM_SHA384",
+        "ec_shared_secret": "9348e27655539e08fffe46b35f863dd634e7437cc6bc11c7d329ef5484ec3b60",
+        "pq_shared_secret": "B408D5D115713F0A93047DBBEA832E4340787686D59A9A2D106BD662BA0AA035",
+        "transcript_hash": "35412cebcf35cb8a7af8f78278a486fc798f8702eaebd067c97acb27bffe13524d8426a4ed57956b4fd0ffdc4c90be52",
+    },
 ]
 
 
@@ -233,6 +261,9 @@ def hkdf_expand_label(key: bytes, label: str, context: bytes, hash_alg: str):
 
 def compute_secrets(input_vector: dict):
     shared_secret = bytes.fromhex(input_vector["ec_shared_secret"] + input_vector["pq_shared_secret"])
+    if (input_vector["group_name"] == "X25519MLKEM768"):
+        shared_secret = bytes.fromhex(input_vector["pq_shared_secret"] + input_vector["ec_shared_secret"])
+
     hash_alg = input_vector["cipher_suite"].split("_")[-1].lower()
     zeros = bytearray([0] * hashlib.new(hash_alg).digest_size)
     transcript_hash = bytes.fromhex(input_vector["transcript_hash"])

tests/unit/s2n_kem_preferences_test.c

@@ -25,6 +25,8 @@ int main(int argc, char **argv)
     BEGIN_TEST();
     EXPECT_SUCCESS(s2n_disable_tls13_in_test());
 
+    EXPECT_FALSE(s2n_kem_preferences_includes_tls13_kem_group(&kem_preferences_null, TLS_PQ_KEM_GROUP_ID_SECP256R1_MLKEM_768));
+    EXPECT_FALSE(s2n_kem_preferences_includes_tls13_kem_group(&kem_preferences_null, TLS_PQ_KEM_GROUP_ID_X25519_MLKEM_768));
     EXPECT_FALSE(s2n_kem_preferences_includes_tls13_kem_group(&kem_preferences_null, TLS_PQ_KEM_GROUP_ID_X25519_KYBER_512_R3));
     EXPECT_FALSE(s2n_kem_preferences_includes_tls13_kem_group(&kem_preferences_null, TLS_PQ_KEM_GROUP_ID_X25519_KYBER_768_R3));
     EXPECT_FALSE(s2n_kem_preferences_includes_tls13_kem_group(&kem_preferences_null, TLS_PQ_KEM_GROUP_ID_SECP256R1_KYBER_512_R3));
@@ -34,6 +36,8 @@ int main(int argc, char **argv)
 
     {
         const struct s2n_kem_group *test_kem_groups[] = {
+            &s2n_secp256r1_mlkem_768,
+            &s2n_x25519_mlkem_768,
             &s2n_secp256r1_kyber_512_r3,
             &s2n_x25519_kyber_512_r3,
             &s2n_secp384r1_kyber_768_r3,
@@ -49,6 +53,8 @@ int main(int argc, char **argv)
             .tls13_kem_groups = test_kem_groups,
         };
 
+        EXPECT_TRUE(s2n_kem_preferences_includes_tls13_kem_group(&test_prefs, TLS_PQ_KEM_GROUP_ID_SECP256R1_MLKEM_768));
+        EXPECT_TRUE(s2n_kem_preferences_includes_tls13_kem_group(&test_prefs, TLS_PQ_KEM_GROUP_ID_X25519_MLKEM_768));
         EXPECT_TRUE(s2n_kem_preferences_includes_tls13_kem_group(&test_prefs, TLS_PQ_KEM_GROUP_ID_X25519_KYBER_512_R3));
         EXPECT_TRUE(s2n_kem_preferences_includes_tls13_kem_group(&test_prefs, TLS_PQ_KEM_GROUP_ID_X25519_KYBER_768_R3));
         EXPECT_TRUE(s2n_kem_preferences_includes_tls13_kem_group(&test_prefs, TLS_PQ_KEM_GROUP_ID_SECP256R1_KYBER_512_R3));
@@ -69,13 +75,24 @@ int main(int argc, char **argv)
                 EXPECT_FALSE(s2n_kem_group_is_available(&s2n_x25519_kyber_512_r3));
                 EXPECT_FALSE(s2n_kem_group_is_available(&s2n_x25519_kyber_768_r3));
             }
+
+            if (s2n_libcrypto_supports_mlkem()) {
+                EXPECT_TRUE(s2n_kem_group_is_available(&s2n_secp256r1_mlkem_768));
+                if (s2n_is_evp_apis_supported()) {
+                    EXPECT_TRUE(s2n_kem_group_is_available(&s2n_x25519_mlkem_768));
+                } else {
+                    EXPECT_FALSE(s2n_kem_group_is_available(&s2n_x25519_mlkem_768));
+                }
+            }
         } else {
             EXPECT_FALSE(s2n_kem_group_is_available(&s2n_secp256r1_kyber_512_r3));
             EXPECT_FALSE(s2n_kem_group_is_available(&s2n_x25519_kyber_512_r3));
             EXPECT_FALSE(s2n_kem_group_is_available(&s2n_x25519_kyber_768_r3));
             EXPECT_FALSE(s2n_kem_group_is_available(&s2n_secp256r1_kyber_768_r3));
             EXPECT_FALSE(s2n_kem_group_is_available(&s2n_secp384r1_kyber_768_r3));
             EXPECT_FALSE(s2n_kem_group_is_available(&s2n_secp521r1_kyber_1024_r3));
+            EXPECT_FALSE(s2n_kem_group_is_available(&s2n_secp256r1_mlkem_768));
+            EXPECT_FALSE(s2n_kem_group_is_available(&s2n_x25519_mlkem_768));
         }
     };
 

tests/unit/s2n_mlkem_test.c

@@ -0,0 +1,33 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+#include "api/s2n.h"
+#include "crypto/s2n_libcrypto.h"
+#include "crypto/s2n_pq.h"
+#include "s2n_test.h"
+#include "testlib/s2n_testlib.h"
+
+int main()
+{
+    BEGIN_TEST();
+    /* MLKEM Support was added to AWSLC when AWSLC_API_VERSION == 29 */
+    if (s2n_libcrypto_is_awslc() && s2n_libcrypto_awslc_api_version() >= 30) {
+        EXPECT_TRUE(s2n_libcrypto_supports_mlkem());
+    } else if (s2n_libcrypto_is_awslc() && s2n_libcrypto_awslc_api_version() < 29) {
+        EXPECT_FALSE(s2n_libcrypto_supports_mlkem());
+    }
+
+    END_TEST();
+}

tests/unit/s2n_pq_kem_test.c

@@ -24,6 +24,7 @@
 #include "utils/s2n_safety.h"
 
 static const struct s2n_kem *test_vectors[] = {
+    &s2n_mlkem_768,
     &s2n_kyber_512_r3,
     &s2n_kyber_768_r3,
     &s2n_kyber_1024_r3,
@@ -63,25 +64,26 @@ int main()
         DEFER_CLEANUP(struct s2n_blob ciphertext = { 0 }, s2n_free);
         EXPECT_SUCCESS(s2n_alloc(&ciphertext, kem->ciphertext_length));
 
-        if (s2n_pq_is_enabled()) {
-            /* Test a successful round-trip: keygen->enc->dec */
-            EXPECT_PQ_KEM_SUCCESS(kem->generate_keypair(kem, public_key.data, private_key.data));
-            EXPECT_PQ_KEM_SUCCESS(kem->encapsulate(kem, ciphertext.data, client_shared_secret.data, public_key.data));
-            EXPECT_PQ_KEM_SUCCESS(kem->decapsulate(kem, server_shared_secret.data, ciphertext.data, private_key.data));
-            EXPECT_BYTEARRAY_EQUAL(server_shared_secret.data, client_shared_secret.data, kem->shared_secret_key_length);
-
-            /* By design, if an invalid private key + ciphertext pair is provided to decapsulate(),
-             * the function should still succeed (return S2N_SUCCESS); however, the shared secret
-             * that was "decapsulated" will be a garbage random value. */
-            ciphertext.data[0] ^= 1; /* Flip a bit to invalidate the ciphertext */
-
-            EXPECT_PQ_KEM_SUCCESS(kem->decapsulate(kem, server_shared_secret.data, ciphertext.data, private_key.data));
-            EXPECT_BYTEARRAY_NOT_EQUAL(server_shared_secret.data, client_shared_secret.data, kem->shared_secret_key_length);
-        } else {
+        if (!s2m_kem_is_available(kem)) {
             EXPECT_FAILURE_WITH_ERRNO(kem->generate_keypair(kem, public_key.data, private_key.data), S2N_ERR_UNIMPLEMENTED);
             EXPECT_FAILURE_WITH_ERRNO(kem->encapsulate(kem, ciphertext.data, client_shared_secret.data, public_key.data), S2N_ERR_UNIMPLEMENTED);
             EXPECT_FAILURE_WITH_ERRNO(kem->decapsulate(kem, server_shared_secret.data, ciphertext.data, private_key.data), S2N_ERR_UNIMPLEMENTED);
+            continue;
         }
+
+        /* Test a successful round-trip: keygen->enc->dec */
+        EXPECT_PQ_KEM_SUCCESS(kem->generate_keypair(kem, public_key.data, private_key.data));
+        EXPECT_PQ_KEM_SUCCESS(kem->encapsulate(kem, ciphertext.data, client_shared_secret.data, public_key.data));
+        EXPECT_PQ_KEM_SUCCESS(kem->decapsulate(kem, server_shared_secret.data, ciphertext.data, private_key.data));
+        EXPECT_BYTEARRAY_EQUAL(server_shared_secret.data, client_shared_secret.data, kem->shared_secret_key_length);
+
+        /* By design, if an invalid private key + ciphertext pair is provided to decapsulate(),
+         * the function should still succeed (return S2N_SUCCESS); however, the shared secret
+         * that was "decapsulated" will be a garbage random value. */
+        ciphertext.data[0] ^= 1; /* Flip a bit to invalidate the ciphertext */
+
+        EXPECT_PQ_KEM_SUCCESS(kem->decapsulate(kem, server_shared_secret.data, ciphertext.data, private_key.data));
+        EXPECT_BYTEARRAY_NOT_EQUAL(server_shared_secret.data, client_shared_secret.data, kem->shared_secret_key_length);
     }
 
     END_TEST();

tests/unit/s2n_security_policies_test.c

@@ -198,15 +198,23 @@ int main(int argc, char **argv)
         EXPECT_EQUAL(1, security_policy->kem_preferences->kem_count);
         EXPECT_NOT_NULL(security_policy->kem_preferences->kems);
         EXPECT_EQUAL(&s2n_kyber_512_r3, security_policy->kem_preferences->kems[0]);
-        EXPECT_EQUAL(security_policy->kem_preferences->tls13_kem_groups, pq_kem_groups_r3_2023_06);
+        EXPECT_EQUAL(security_policy->kem_preferences->tls13_kem_groups, ALL_SUPPORTED_KEM_GROUPS);
         /* All supported kem groups should be in the preference list, but not all of them may be available. */
-        EXPECT_EQUAL(6, security_policy->kem_preferences->tls13_kem_group_count);
+        EXPECT_EQUAL(S2N_KEM_GROUPS_COUNT, security_policy->kem_preferences->tls13_kem_group_count);
         uint32_t available_groups = 0;
         EXPECT_OK(s2n_kem_preferences_groups_available(security_policy->kem_preferences, &available_groups));
         if (s2n_libcrypto_supports_evp_kem() && s2n_is_evp_apis_supported()) {
-            EXPECT_EQUAL(6, available_groups);
+            if (s2n_libcrypto_supports_mlkem()) {
+                EXPECT_EQUAL(S2N_KEM_GROUPS_COUNT, available_groups);
+            } else {
+                EXPECT_EQUAL(6, available_groups);
+            }
         } else if (s2n_libcrypto_supports_evp_kem() && !s2n_is_evp_apis_supported()) {
-            EXPECT_EQUAL(4, available_groups);
+            if (s2n_libcrypto_supports_mlkem()) {
+                EXPECT_EQUAL(5, available_groups);
+            } else {
+                EXPECT_EQUAL(4, available_groups);
+            }
         } else {
             EXPECT_EQUAL(0, available_groups);
         }

tests/unit/s2n_server_key_share_extension_test.c

@@ -885,15 +885,23 @@ int main(int argc, char **argv)
                     S2N_STUFFER_READ_EXPECT_EQUAL(&stuffer, kem_group->iana_id, uint16);
                     S2N_STUFFER_READ_EXPECT_EQUAL(&stuffer, expected_hybrid_share_size, uint16);
 
+                    uint16_t expected_first_share_size = kem_group->curve->share_size;
+                    uint16_t expected_second_share_size = kem_group->kem->ciphertext_length;
+
+                    if (kem_group->send_kem_first) {
+                        expected_first_share_size = kem_group->kem->ciphertext_length;
+                        expected_second_share_size = kem_group->curve->share_size;
+                    }
+
                     if (len_prefixed) {
-                        S2N_STUFFER_READ_EXPECT_EQUAL(&stuffer, kem_group->curve->share_size, uint16);
+                        S2N_STUFFER_READ_EXPECT_EQUAL(&stuffer, expected_first_share_size, uint16);
                     }
-                    EXPECT_SUCCESS(s2n_stuffer_skip_read(&stuffer, kem_group->curve->share_size));
+                    EXPECT_SUCCESS(s2n_stuffer_skip_read(&stuffer, expected_first_share_size));
 
                     if (len_prefixed) {
-                        S2N_STUFFER_READ_EXPECT_EQUAL(&stuffer, kem_group->kem->ciphertext_length, uint16);
+                        S2N_STUFFER_READ_EXPECT_EQUAL(&stuffer, expected_second_share_size, uint16);
                     }
-                    S2N_STUFFER_LENGTH_WRITTEN_EXPECT_EQUAL(&stuffer, kem_group->kem->ciphertext_length);
+                    S2N_STUFFER_LENGTH_WRITTEN_EXPECT_EQUAL(&stuffer, expected_second_share_size);
 
                     EXPECT_NULL(conn->kex_params.server_ecc_evp_params.negotiated_curve);
                     EXPECT_EQUAL(server_params->kem_group, kem_group);