Add Security Policy Deprecation API (#5034)

Co-authored-by: James Mayclin <maycj@amazon.com>
Co-authored-by: Lindsay Stewart <stewart.r.lindsay@gmail.com>

docs/usage-guide/topics/ch06-security-policies.md

@@ -8,6 +8,9 @@ s2n-tls uses pre-made security policies to help avoid common misconfiguration mi
 
 Currently TLS 1.2 is our default version, but we recommend TLS 1.3 where possible. To use TLS 1.3 you need a security policy that supports TLS 1.3.
 
+## Deprecation of Security Policies
+
+s2n-tls may deprecate security policies. If s2n-tls drops support for an algorithm included in a security policy, the behavior of the security policy might unexpectedly change. Because s2n-tls promises that versioned policies will never change, we instead deprecate affected security policies. If a security policy is deprecated, users will receive a `S2N_ERR_DEPRECATED_SECURITY_POLICY` usage error when requesting that policy.
 ### SSL 3.0, TLS 1.0, and TLS 1.1
 s2n-tls supports older versions, but their use is not recommended.
 

error/s2n_errno.c

@@ -255,6 +255,7 @@ static const char *no_such_error = "Internal s2n error";
     ERR_ENTRY(S2N_ERR_UNSUPPORTED_EXTENSION, "Illegal use of a known, supported extension") \
     ERR_ENTRY(S2N_ERR_MISSING_EXTENSION, "Mandatory extension not received") \
     ERR_ENTRY(S2N_ERR_DUPLICATE_EXTENSION, "Extension block contains two or more extensions of the same type") \
+    ERR_ENTRY(S2N_ERR_DEPRECATED_SECURITY_POLICY, "Deprecated security policy. Please choose a different security policy.") \
     ERR_ENTRY(S2N_ERR_INVALID_SECURITY_POLICY, "Invalid security policy") \
     ERR_ENTRY(S2N_ERR_INVALID_KEM_PREFERENCES, "Invalid kem preferences version") \
     ERR_ENTRY(S2N_ERR_INVALID_PARSED_EXTENSIONS, "Invalid parsed extension data") \

error/s2n_errno.h

@@ -295,6 +295,7 @@ typedef enum {
     S2N_ERR_INVALID_SIGNATURE_ALGORITHMS_PREFERENCES,
     S2N_ERR_RSA_PSS_NOT_SUPPORTED,
     S2N_ERR_INVALID_ECC_PREFERENCES,
+    S2N_ERR_DEPRECATED_SECURITY_POLICY,
     S2N_ERR_INVALID_SECURITY_POLICY,
     S2N_ERR_INVALID_KEM_PREFERENCES,
     S2N_ERR_ASYNC_ALREADY_PERFORMED,

tests/unit/s2n_security_policies_test.c

@@ -172,6 +172,18 @@ int main(int argc, char **argv)
 
     const struct s2n_security_policy *security_policy = NULL;
 
+    /* Test Deprecated Security Policies */
+    {
+        /* Ensure that every policy in the deprecated list has been removed from the supported policies list */
+        for (size_t i = 0; i < deprecated_security_policies_len; i++) {
+            EXPECT_FAILURE_WITH_ERRNO(s2n_find_security_policy_from_version(deprecated_security_policies[i], &security_policy), S2N_ERR_DEPRECATED_SECURITY_POLICY);
+        }
+
+        /* Spot check a few deprecated security policies to ensure S2N_ERR_DEPRECATED_SECURITY_POLICY is returned as expected. */
+        EXPECT_FAILURE_WITH_ERRNO(s2n_find_security_policy_from_version("PQ-SIKE-TEST-TLS-1-0-2019-11", &security_policy), S2N_ERR_DEPRECATED_SECURITY_POLICY);
+        EXPECT_FAILURE_WITH_ERRNO(s2n_find_security_policy_from_version("PQ-SIKE-TEST-TLS-1-0-2020-02", &security_policy), S2N_ERR_DEPRECATED_SECURITY_POLICY);
+    }
+
     /* Test common known good cipher suites for expected configuration */
     {
         EXPECT_SUCCESS(s2n_find_security_policy_from_version("default", &security_policy));
@@ -241,24 +253,6 @@ int main(int argc, char **argv)
         EXPECT_NULL(security_policy->kem_preferences->tls13_kem_groups);
         EXPECT_EQUAL(0, security_policy->kem_preferences->tls13_kem_group_count);
 
-        security_policy = NULL;
-        EXPECT_SUCCESS(s2n_find_security_policy_from_version("PQ-SIKE-TEST-TLS-1-0-2019-11", &security_policy));
-        EXPECT_TRUE(s2n_ecc_is_extension_required(security_policy));
-        EXPECT_FALSE(s2n_pq_kem_is_extension_required(security_policy));
-        EXPECT_EQUAL(0, security_policy->kem_preferences->kem_count);
-        EXPECT_NULL(security_policy->kem_preferences->kems);
-        EXPECT_NULL(security_policy->kem_preferences->tls13_kem_groups);
-        EXPECT_EQUAL(0, security_policy->kem_preferences->tls13_kem_group_count);
-
-        security_policy = NULL;
-        EXPECT_SUCCESS(s2n_find_security_policy_from_version("PQ-SIKE-TEST-TLS-1-0-2020-02", &security_policy));
-        EXPECT_TRUE(s2n_ecc_is_extension_required(security_policy));
-        EXPECT_FALSE(s2n_pq_kem_is_extension_required(security_policy));
-        EXPECT_EQUAL(0, security_policy->kem_preferences->kem_count);
-        EXPECT_NULL(security_policy->kem_preferences->kems);
-        EXPECT_NULL(security_policy->kem_preferences->tls13_kem_groups);
-        EXPECT_EQUAL(0, security_policy->kem_preferences->tls13_kem_group_count);
-
         security_policy = NULL;
         EXPECT_SUCCESS(s2n_find_security_policy_from_version("KMS-PQ-TLS-1-0-2020-02", &security_policy));
         EXPECT_TRUE(s2n_ecc_is_extension_required(security_policy));
@@ -482,8 +476,6 @@ int main(int argc, char **argv)
             "KMS-PQ-TLS-1-0-2019-06",
             "KMS-PQ-TLS-1-0-2020-02",
             "KMS-PQ-TLS-1-0-2020-07",
-            "PQ-SIKE-TEST-TLS-1-0-2019-11",
-            "PQ-SIKE-TEST-TLS-1-0-2020-02",
             "KMS-FIPS-TLS-1-2-2018-10",
             "20140601",
             "20141001",

tls/s2n_cipher_preferences.c

@@ -1634,34 +1634,6 @@ const struct s2n_cipher_preferences cipher_preferences_kms_pq_tls_1_0_2020_02 =
     .allow_chacha20_boosting = false,
 };
 
-struct s2n_cipher_suite *cipher_suites_pq_sike_test_tls_1_0_2019_11[] = {
-    &s2n_ecdhe_rsa_with_aes_256_gcm_sha384,
-    &s2n_ecdhe_rsa_with_aes_128_gcm_sha256,
-    &s2n_ecdhe_rsa_with_aes_256_cbc_sha384,
-    &s2n_ecdhe_rsa_with_aes_256_cbc_sha,
-    &s2n_ecdhe_rsa_with_aes_128_cbc_sha256,
-    &s2n_ecdhe_rsa_with_3des_ede_cbc_sha,
-    &s2n_dhe_rsa_with_aes_256_cbc_sha256,
-    &s2n_dhe_rsa_with_aes_128_cbc_sha256,
-    &s2n_dhe_rsa_with_aes_256_cbc_sha,
-    &s2n_dhe_rsa_with_aes_128_cbc_sha,
-};
-
-/* Previously included only SIKE round 1 (for integration tests) */
-const struct s2n_cipher_preferences cipher_preferences_pq_sike_test_tls_1_0_2019_11 = {
-    .count = s2n_array_len(cipher_suites_pq_sike_test_tls_1_0_2019_11),
-    .suites = cipher_suites_pq_sike_test_tls_1_0_2019_11,
-    .allow_chacha20_boosting = false,
-};
-
-/* Previously included SIKE round 1 and round 2 (for integration tests). The cipher suite list
- * is the same as in cipher_preferences_pq_sike_test_tls_1_0_2019_11. */
-const struct s2n_cipher_preferences cipher_preferences_pq_sike_test_tls_1_0_2020_02 = {
-    .count = s2n_array_len(cipher_suites_pq_sike_test_tls_1_0_2019_11),
-    .suites = cipher_suites_pq_sike_test_tls_1_0_2019_11,
-    .allow_chacha20_boosting = false,
-};
-
 /* Includes Kyber PQ algorithm */
 struct s2n_cipher_suite *cipher_suites_kms_pq_tls_1_0_2020_07[] = {
     &s2n_ecdhe_kyber_rsa_with_aes_256_gcm_sha384,

tls/s2n_cipher_preferences.h

@@ -125,8 +125,6 @@ extern const struct s2n_cipher_preferences cipher_preferences_kms_fips_tls_1_2_2
 extern const struct s2n_cipher_preferences cipher_preferences_kms_pq_tls_1_0_2019_06;
 extern const struct s2n_cipher_preferences cipher_preferences_kms_pq_tls_1_0_2020_02;
 extern const struct s2n_cipher_preferences cipher_preferences_kms_pq_tls_1_0_2020_07;
-extern const struct s2n_cipher_preferences cipher_preferences_pq_sike_test_tls_1_0_2019_11;
-extern const struct s2n_cipher_preferences cipher_preferences_pq_sike_test_tls_1_0_2020_02;
 extern const struct s2n_cipher_preferences cipher_preferences_pq_tls_1_0_2020_12;
 extern const struct s2n_cipher_preferences cipher_preferences_pq_tls_1_1_2021_05_17;
 extern const struct s2n_cipher_preferences cipher_preferences_pq_tls_1_0_2021_05_18;

tls/s2n_security_policies.c

@@ -610,28 +610,6 @@ const struct s2n_security_policy security_policy_kms_pq_tls_1_0_2020_02 = {
     },
 };
 
-const struct s2n_security_policy security_policy_pq_sike_test_tls_1_0_2019_11 = {
-    .minimum_protocol_version = S2N_TLS10,
-    .cipher_preferences = &cipher_preferences_pq_sike_test_tls_1_0_2019_11,
-    .kem_preferences = &kem_preferences_null,
-    .signature_preferences = &s2n_signature_preferences_20140601,
-    .ecc_preferences = &s2n_ecc_preferences_20140601,
-    .rules = {
-            [S2N_PERFECT_FORWARD_SECRECY] = true,
-    },
-};
-
-const struct s2n_security_policy security_policy_pq_sike_test_tls_1_0_2020_02 = {
-    .minimum_protocol_version = S2N_TLS10,
-    .cipher_preferences = &cipher_preferences_pq_sike_test_tls_1_0_2020_02,
-    .kem_preferences = &kem_preferences_null,
-    .signature_preferences = &s2n_signature_preferences_20140601,
-    .ecc_preferences = &s2n_ecc_preferences_20140601,
-    .rules = {
-            [S2N_PERFECT_FORWARD_SECRECY] = true,
-    },
-};
-
 const struct s2n_security_policy security_policy_kms_pq_tls_1_0_2020_07 = {
     .minimum_protocol_version = S2N_TLS10,
     .cipher_preferences = &cipher_preferences_kms_pq_tls_1_0_2020_07,
@@ -1296,8 +1274,6 @@ struct s2n_security_policy_selection security_policy_selection[] = {
     { .version = "KMS-PQ-TLS-1-0-2019-06", .security_policy = &security_policy_kms_pq_tls_1_0_2019_06, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "KMS-PQ-TLS-1-0-2020-02", .security_policy = &security_policy_kms_pq_tls_1_0_2020_02, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "KMS-PQ-TLS-1-0-2020-07", .security_policy = &security_policy_kms_pq_tls_1_0_2020_07, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
-    { .version = "PQ-SIKE-TEST-TLS-1-0-2019-11", .security_policy = &security_policy_pq_sike_test_tls_1_0_2019_11, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
-    { .version = "PQ-SIKE-TEST-TLS-1-0-2020-02", .security_policy = &security_policy_pq_sike_test_tls_1_0_2020_02, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "PQ-TLS-1-0-2020-12", .security_policy = &security_policy_pq_tls_1_0_2020_12, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "PQ-TLS-1-1-2021-05-17", .security_policy = &security_policy_pq_tls_1_1_2021_05_17, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .version = "PQ-TLS-1-0-2021-05-18", .security_policy = &security_policy_pq_tls_1_0_2021_05_18, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
@@ -1367,6 +1343,12 @@ struct s2n_security_policy_selection security_policy_selection[] = {
     { .version = NULL, .security_policy = NULL, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }
 };
 
+const char *deprecated_security_policies[] = {
+    "PQ-SIKE-TEST-TLS-1-0-2019-11",
+    "PQ-SIKE-TEST-TLS-1-0-2020-02",
+};
+const size_t deprecated_security_policies_len = s2n_array_len(deprecated_security_policies);
+
 int s2n_find_security_policy_from_version(const char *version, const struct s2n_security_policy **security_policy)
 {
     POSIX_ENSURE_REF(version);
@@ -1379,6 +1361,12 @@ int s2n_find_security_policy_from_version(const char *version, const struct s2n_
         }
     }
 
+    for (size_t i = 0; i < deprecated_security_policies_len; i++) {
+        if (!strcasecmp(version, deprecated_security_policies[i])) {
+            POSIX_BAIL(S2N_ERR_DEPRECATED_SECURITY_POLICY);
+        }
+    }
+
     POSIX_BAIL(S2N_ERR_INVALID_SECURITY_POLICY);
 }
 

tls/s2n_security_policies.h

@@ -93,6 +93,8 @@ struct s2n_security_policy_selection {
 };
 
 extern struct s2n_security_policy_selection security_policy_selection[];
+extern const char *deprecated_security_policies[];
+extern const size_t deprecated_security_policies_len;
 
 /* Defaults as of 05/24 */
 extern const struct s2n_security_policy security_policy_20240501;
@@ -160,8 +162,6 @@ extern const struct s2n_security_policy security_policy_aws_crt_sdk_tls_13;
 extern const struct s2n_security_policy security_policy_kms_pq_tls_1_0_2019_06;
 extern const struct s2n_security_policy security_policy_kms_pq_tls_1_0_2020_02;
 extern const struct s2n_security_policy security_policy_kms_pq_tls_1_0_2020_07;
-extern const struct s2n_security_policy security_policy_pq_sike_test_tls_1_0_2019_11;
-extern const struct s2n_security_policy security_policy_pq_sike_test_tls_1_0_2020_02;
 extern const struct s2n_security_policy security_policy_pq_tls_1_0_2020_12;
 extern const struct s2n_security_policy security_policy_pq_tls_1_1_2021_05_17;
 extern const struct s2n_security_policy security_policy_pq_tls_1_0_2021_05_18;