feat: add PQ only policy support (#5545)

Author: CarolYeh910

tests/policy_snapshot/snapshots/test_pq_only

@@ -0,0 +1,42 @@
+name: test_pq_only
+min version: TLS1.3
+rules:
+- Perfect Forward Secrecy: no
+- FIPS 140-3 (2019): no
+cipher suites:
+- TLS_AES_128_GCM_SHA256
+- TLS_AES_256_GCM_SHA384
+- TLS_CHACHA20_POLY1305_SHA256
+signature schemes:
+- ecdsa_sha256
+- ecdsa_sha384
+- ecdsa_sha512
+- rsa_pss_pss_sha256
+- rsa_pss_pss_sha384
+- rsa_pss_pss_sha512
+- rsa_pss_rsae_sha256
+- rsa_pss_rsae_sha384
+- rsa_pss_rsae_sha512
+- rsa_pkcs1_sha256
+- rsa_pkcs1_sha384
+- rsa_pkcs1_sha512
+curves:
+certificate signature schemes:
+- ecdsa_sha256
+- ecdsa_sha384
+- ecdsa_sha512
+- rsa_pss_pss_sha256
+- rsa_pss_pss_sha384
+- rsa_pss_pss_sha512
+- rsa_pss_rsae_sha256
+- rsa_pss_rsae_sha384
+- rsa_pss_rsae_sha512
+- rsa_pkcs1_sha256
+- rsa_pkcs1_sha384
+- rsa_pkcs1_sha512
+pq:
+- revision: 5
+- kem groups:
+-- X25519MLKEM768
+-- SecP256r1MLKEM768
+-- SecP384r1MLKEM1024

tests/unit/s2n_pq_mlkem_policies_test.c

@@ -191,5 +191,86 @@ int main(int argc, char **argv)
         }
     }
 
+    /* Test configuring a PQ only policy on different libcryptos. */
+    {
+        DEFER_CLEANUP(struct s2n_config *config = s2n_config_new(), s2n_config_ptr_free);
+        EXPECT_NOT_NULL(config);
+        const char *policy = "test_pq_only";
+
+        if (!s2n_is_tls13_fully_supported()) {
+            EXPECT_FAILURE_WITH_ERRNO(s2n_config_set_cipher_preferences(config, policy), S2N_ERR_PROTOCOL_VERSION_UNSUPPORTED);
+        } else if (!s2n_libcrypto_supports_mlkem()) {
+            EXPECT_FAILURE_WITH_ERRNO(s2n_config_set_cipher_preferences(config, policy), S2N_ERR_INVALID_SECURITY_POLICY);
+        } else {
+            EXPECT_SUCCESS(s2n_config_set_cipher_preferences(config, policy));
+        }
+    }
+
+    /* Self-talk tests for PQ only policies on supported libcryptos. */
+    if (s2n_is_tls13_fully_supported() && s2n_libcrypto_supports_mlkem()) {
+        DEFER_CLEANUP(struct s2n_cert_chain_and_key *chain_and_key = NULL, s2n_cert_chain_and_key_ptr_free);
+        EXPECT_SUCCESS(s2n_test_cert_chain_and_key_new(&chain_and_key,
+                S2N_DEFAULT_TEST_CERT_CHAIN, S2N_DEFAULT_TEST_PRIVATE_KEY));
+
+        /* Test a PQ-only policy is able to negotiate. */
+        {
+            DEFER_CLEANUP(struct s2n_config *config = s2n_config_new(), s2n_config_ptr_free);
+            EXPECT_NOT_NULL(config);
+            EXPECT_SUCCESS(s2n_config_add_cert_chain_and_key_to_store(config, chain_and_key));
+            EXPECT_SUCCESS(s2n_config_set_verification_ca_location(config, S2N_DEFAULT_TEST_CERT_CHAIN, NULL));
+            EXPECT_SUCCESS(s2n_config_set_cipher_preferences(config, "test_pq_only"));
+
+            DEFER_CLEANUP(struct s2n_connection *client_conn = s2n_connection_new(S2N_CLIENT), s2n_connection_ptr_free);
+            EXPECT_NOT_NULL(client_conn);
+            EXPECT_SUCCESS(s2n_connection_set_config(client_conn, config));
+            EXPECT_SUCCESS(s2n_set_server_name(client_conn, "localhost"));
+
+            DEFER_CLEANUP(struct s2n_connection *server_conn = s2n_connection_new(S2N_SERVER), s2n_connection_ptr_free);
+            EXPECT_NOT_NULL(server_conn);
+            EXPECT_SUCCESS(s2n_connection_set_config(server_conn, config));
+
+            DEFER_CLEANUP(struct s2n_test_io_pair io_pair = { 0 }, s2n_io_pair_close);
+            EXPECT_SUCCESS(s2n_io_pair_init_non_blocking(&io_pair));
+            EXPECT_SUCCESS(s2n_connection_set_io_pair(client_conn, &io_pair));
+            EXPECT_SUCCESS(s2n_connection_set_io_pair(server_conn, &io_pair));
+
+            EXPECT_SUCCESS(s2n_negotiate_test_server_and_client(server_conn, client_conn));
+            /* Assert classical ECC is not negotiated & kem group is negotiated. */
+            EXPECT_NULL(server_conn->kex_params.server_ecc_evp_params.negotiated_curve);
+            EXPECT_NOT_NULL(server_conn->kex_params.server_kem_group_params.kem_group);
+        }
+
+        /* Expect failure when a non-PQ client attempts to negotiate with a PQ-only server. */
+        {
+            DEFER_CLEANUP(struct s2n_config *config = s2n_config_new(), s2n_config_ptr_free);
+            EXPECT_NOT_NULL(config);
+            EXPECT_SUCCESS(s2n_config_add_cert_chain_and_key_to_store(config, chain_and_key));
+            EXPECT_SUCCESS(s2n_config_set_verification_ca_location(config, S2N_DEFAULT_TEST_CERT_CHAIN, NULL));
+
+            DEFER_CLEANUP(struct s2n_connection *client_conn = s2n_connection_new(S2N_CLIENT), s2n_connection_ptr_free);
+            EXPECT_NOT_NULL(client_conn);
+            EXPECT_SUCCESS(s2n_connection_set_config(client_conn, config));
+            EXPECT_SUCCESS(s2n_connection_set_cipher_preferences(client_conn, "20240503"));
+            EXPECT_SUCCESS(s2n_set_server_name(client_conn, "localhost"));
+
+            DEFER_CLEANUP(struct s2n_connection *server_conn = s2n_connection_new(S2N_SERVER), s2n_connection_ptr_free);
+            EXPECT_NOT_NULL(server_conn);
+            EXPECT_SUCCESS(s2n_connection_set_config(server_conn, config));
+            EXPECT_SUCCESS(s2n_connection_set_cipher_preferences(server_conn, "test_pq_only"));
+            EXPECT_SUCCESS(s2n_connection_set_blinding(server_conn, S2N_SELF_SERVICE_BLINDING));
+
+            DEFER_CLEANUP(struct s2n_test_io_pair io_pair = { 0 }, s2n_io_pair_close);
+            EXPECT_SUCCESS(s2n_io_pair_init_non_blocking(&io_pair));
+            EXPECT_SUCCESS(s2n_connection_set_io_pair(client_conn, &io_pair));
+            EXPECT_SUCCESS(s2n_connection_set_io_pair(server_conn, &io_pair));
+
+            EXPECT_FAILURE_WITH_ERRNO(s2n_negotiate_test_server_and_client(server_conn, client_conn),
+                    S2N_ERR_ECDHE_UNSUPPORTED_CURVE);
+            /* Assert server negotiated_curve and kem_group are both NULL. */
+            EXPECT_NULL(server_conn->kex_params.server_ecc_evp_params.negotiated_curve);
+            EXPECT_NULL(server_conn->kex_params.server_kem_group_params.kem_group);
+        }
+    }
+
     END_TEST();
 }

tls/extensions/s2n_client_key_share.c

@@ -67,6 +67,11 @@ static int s2n_generate_default_ecc_key_share(struct s2n_connection *conn, struc
     POSIX_GUARD(s2n_connection_get_ecc_preferences(conn, &ecc_pref));
     POSIX_ENSURE_REF(ecc_pref);
 
+    /* Skip sending classical ECC curves for PQ only policies. */
+    if (ecc_pref->count == 0) {
+        return S2N_SUCCESS;
+    }
+
     /* We only ever send a single EC key share: either the share requested by the server
      * during a retry, or the most preferred share according to local preferences.
      */

tls/s2n_client_hello.c

@@ -23,6 +23,7 @@
 #include "api/unstable/fingerprint.h"
 #include "crypto/s2n_fips.h"
 #include "crypto/s2n_hash.h"
+#include "crypto/s2n_pq.h"
 #include "error/s2n_errno.h"
 #include "stuffer/s2n_stuffer.h"
 #include "tls/extensions/s2n_client_server_name.h"
@@ -551,13 +552,13 @@ int s2n_process_client_hello(struct s2n_connection *conn)
     const struct s2n_ecc_preferences *ecc_pref = NULL;
     POSIX_GUARD(s2n_connection_get_ecc_preferences(conn, &ecc_pref));
     POSIX_ENSURE_REF(ecc_pref);
-    POSIX_ENSURE_GT(ecc_pref->count, 0);
-    if (s2n_ecc_preferences_includes_curve(ecc_pref, TLS_EC_CURVE_SECP_256_R1)) {
+
+    if (ecc_pref->count == 0) {
+        conn->kex_params.server_ecc_evp_params.negotiated_curve = NULL;
+    } else if (s2n_ecc_preferences_includes_curve(ecc_pref, TLS_EC_CURVE_SECP_256_R1)) {
         conn->kex_params.server_ecc_evp_params.negotiated_curve = &s2n_ecc_curve_secp256r1;
     } else {
-        /* If P-256 isn't allowed by the current security policy, instead choose
-         * the first / most preferred curve.
-         */
+        /* If P-256 isn't allowed by the current security policy, choose the first / most preferred curve. */
         conn->kex_params.server_ecc_evp_params.negotiated_curve = ecc_pref->ecc_curves[0];
     }
 

tls/s2n_security_policies.c

@@ -16,6 +16,7 @@
 #include "tls/s2n_security_policies.h"
 
 #include "api/s2n.h"
+#include "crypto/s2n_pq.h"
 #include "tls/s2n_certificate_keys.h"
 #include "tls/s2n_connection.h"
 #include "utils/s2n_safety.h"
@@ -1398,6 +1399,15 @@ const struct s2n_security_policy security_policy_test_all_tls13 = {
     },
 };
 
+const struct s2n_security_policy security_policy_test_pq_only = {
+    .minimum_protocol_version = S2N_TLS13,
+    .cipher_preferences = &cipher_preferences_cloudfront_upstream_2025_08_08_tls13,
+    .kem_preferences = &kem_preferences_pq_tls_1_3_ietf_2025_07,
+    .signature_preferences = &s2n_signature_preferences_20240501,
+    .certificate_signature_preferences = &s2n_signature_preferences_20240501,
+    .ecc_preferences = &s2n_ecc_preferences_null,
+};
+
 const struct s2n_security_policy security_policy_20200207 = {
     .minimum_protocol_version = S2N_SSLv3,
     .cipher_preferences = &cipher_preferences_test_all_tls13,
@@ -1570,6 +1580,7 @@ struct s2n_security_policy_selection security_policy_selection[] = {
     { .version = "test_ecdsa_priority", .security_policy = &security_policy_test_ecdsa_priority, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "test_all_tls12", .security_policy = &security_policy_test_all_tls12, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "test_all_tls13", .security_policy = &security_policy_test_all_tls13, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
+    { .version = "test_pq_only", .security_policy = &security_policy_test_pq_only, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "null", .security_policy = &security_policy_null, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = NULL, .security_policy = NULL, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }
 };
@@ -1615,7 +1626,7 @@ int s2n_find_security_policy_from_version(const char *version, const struct s2n_
     POSIX_BAIL(S2N_ERR_INVALID_SECURITY_POLICY);
 }
 
-int s2n_config_set_security_policy(struct s2n_config *config, const struct s2n_security_policy *security_policy)
+static int s2n_config_validate_security_policy(struct s2n_config *config, const struct s2n_security_policy *security_policy)
 {
     POSIX_ENSURE_REF(config);
     POSIX_ENSURE_REF(security_policy);
@@ -1627,8 +1638,25 @@ int s2n_config_set_security_policy(struct s2n_config *config, const struct s2n_s
     /* If the security policy's minimum version is higher than what libcrypto supports, return an error. */
     POSIX_ENSURE((security_policy->minimum_protocol_version <= s2n_get_highest_fully_supported_tls_version()), S2N_ERR_PROTOCOL_VERSION_UNSUPPORTED);
 
+    if (security_policy == &security_policy_null) {
+        return S2N_SUCCESS;
+    }
+
+    /* Ensure that an ECC or PQ key exchange can occur. */
+    uint32_t ecc_available = security_policy->ecc_preferences->count;
+    uint32_t kem_groups_available = 0;
+    POSIX_GUARD_RESULT(s2n_kem_preferences_groups_available(security_policy->kem_preferences, &kem_groups_available));
+    POSIX_ENSURE(ecc_available + kem_groups_available > 0, S2N_ERR_INVALID_SECURITY_POLICY);
+
     /* If the config contains certificates violating the security policy cert preferences, return an error. */
     POSIX_GUARD_RESULT(s2n_config_validate_loaded_certificates(config, security_policy));
+    return S2N_SUCCESS;
+}
+
+int s2n_config_set_security_policy(struct s2n_config *config, const struct s2n_security_policy *security_policy)
+{
+    POSIX_ENSURE_REF(config);
+    POSIX_GUARD(s2n_config_validate_security_policy(config, security_policy));
     config->security_policy = security_policy;
     return 0;
 }
@@ -1644,19 +1672,7 @@ int s2n_config_set_cipher_preferences(struct s2n_config *config, const char *ver
 int s2n_connection_set_security_policy(struct s2n_connection *conn, const struct s2n_security_policy *security_policy)
 {
     POSIX_ENSURE_REF(conn);
-    POSIX_ENSURE_REF(security_policy);
-    POSIX_ENSURE_REF(security_policy->cipher_preferences);
-    POSIX_ENSURE_REF(security_policy->kem_preferences);
-    POSIX_ENSURE_REF(security_policy->signature_preferences);
-    POSIX_ENSURE_REF(security_policy->ecc_preferences);
-
-    /* If the security policy's minimum version is higher than what libcrypto supports, return an error. */
-    POSIX_ENSURE((security_policy->minimum_protocol_version <= s2n_get_highest_fully_supported_tls_version()), S2N_ERR_PROTOCOL_VERSION_UNSUPPORTED);
-
-    /* If the certificates loaded in the config are incompatible with the security 
-     * policy's certificate preferences, return an error. */
-    POSIX_GUARD_RESULT(s2n_config_validate_loaded_certificates(conn->config, security_policy));
-
+    POSIX_GUARD(s2n_config_validate_security_policy(conn->config, security_policy));
     conn->security_policy_override = security_policy;
     return 0;
 }
@@ -1688,8 +1704,15 @@ int s2n_security_policies_init()
         }
 
         if (security_policy != &security_policy_null) {
-            /* All policies must have at least one ecc curve configured. */
-            S2N_ERROR_IF(ecc_preference->count == 0, S2N_ERR_INVALID_SECURITY_POLICY);
+            /* All policies must have at least one ecc curve or PQ kem group configured. */
+            bool ecc_kx_supported = ecc_preference->count > 0;
+            bool pq_kx_supported = kem_preference->tls13_kem_group_count > 0;
+            POSIX_ENSURE(ecc_kx_supported || pq_kx_supported, S2N_ERR_INVALID_SECURITY_POLICY);
+
+            /* A PQ key exchange is only supported in TLS 1.3, so PQ-only policies must require TLS 1.3.*/
+            if (!ecc_kx_supported) {
+                POSIX_ENSURE(security_policy->minimum_protocol_version >= S2N_TLS13, S2N_ERR_INVALID_SECURITY_POLICY);
+            }
         }
 
         for (int j = 0; j < cipher_preference->count; j++) {

tls/s2n_signature_scheme.h

@@ -92,11 +92,11 @@ extern const struct s2n_signature_preferences s2n_signature_preferences_20240521
 extern const struct s2n_signature_preferences s2n_signature_preferences_20250429;
 extern const struct s2n_signature_preferences s2n_signature_preferences_20250820;
 extern const struct s2n_signature_preferences s2n_signature_preferences_20250821;
-extern const struct s2n_signature_preferences s2n_certificate_signature_preferences_20250429;
 extern const struct s2n_signature_preferences s2n_signature_preferences_default_fips;
 extern const struct s2n_signature_preferences s2n_signature_preferences_null;
 extern const struct s2n_signature_preferences s2n_signature_preferences_test_all_fips;
 extern const struct s2n_signature_preferences s2n_signature_preferences_all;
 
 extern const struct s2n_signature_preferences s2n_certificate_signature_preferences_20250512;
+extern const struct s2n_signature_preferences s2n_certificate_signature_preferences_20250429;
 extern const struct s2n_signature_preferences s2n_certificate_signature_preferences_20201110;