Skip to content

Add fixed version of the rfc9151 policy #5277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions docs/usage-guide/topics/ch06-security-policies.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,11 @@ The following chart maps the security policy version to protocol version and cip

The "default", "default_tls13", and "default_fips" versions are special in that they will be updated with future s2n-tls changes to keep up-to-date with current security best practices. Ciphersuites, protocol versions, and other options may be added or removed, or their internal order of preference might change. **Warning**: this means that the default policies may change as a result of library updates, which could break peers that rely on legacy options.

In contrast, numbered or dated versions are fixed and will never change. The numbered equivalents of the default policies are currently:
* "default": "20240501"
* "default_fips": "20240502"
* "default_tls13": "20240503"
For previous defaults, see the "Default Policy History" section below.
In contrast, numbered or dated versions are fixed and will never change.

The numbered equivalents of the default policies are currently:

Comment on lines +60 to +63
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what you were aiming for with this section, but I don't think you finished?

If you were trying to remove all the default mappings to rely on the history info below, I don't think I agree with that change. I like the "fixed" versions being very obvious up here, and the full history is much more verbose and less useful.

The numbered equivalents for the named policies for the current version and historical s2n versions are in the "Named Policy History" below.

"default_fips" does not currently support TLS1.3. If you need a policy that supports both FIPS and TLS1.3, choose "20230317". We plan to add TLS1.3 support to both "default" and "default_fips" in the future.

Expand Down Expand Up @@ -147,8 +147,17 @@ s2n-tls usually prefers AES over ChaCha20. However, some clients-- particularly
| 20200207 | X | X | X |
| rfc9151 | | X | |

### Default Policy History
| Version | "default" | "default_fips" | "default_tls13" |
|------------|-----------|----------------|-----------------|
| v1.4.16 | 20240501 | 20240502 | 20240503 |
| Older | 20170210 | 20240416 | 20240417 |
### Named Policy History

* "default"
* v1.4.16 - 20240501
* Older - 20170210
Comment on lines +152 to +154
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I prefer the table format. I worry the bulleted list is less readable and won't grow well. But with only two entries for each it probably doesn't really matter yet?

* "default_fips"
* v1.4.16 - 20240502
* Older - 20240416
* "default_tls13"
* v1.4.16 - 20240503
* Older - 20240417
* "rfc9151"
* v1.5.20 - 20250429
* Older - no versioned policy
28 changes: 28 additions & 0 deletions tests/policy_snapshot/snapshots/20250429
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: 20250429
min version: TLS1.2
rules:
- Perfect Forward Secrecy: no
- FIPS 140-3 (2019): no
cipher suites:
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_RSA_WITH_AES_256_GCM_SHA384
- TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_AES_256_GCM_SHA384
signature schemes:
- ecdsa_sha384
- rsa_pss_pss_sha384
- rsa_pss_rsae_sha384
- rsa_pkcs1_sha384
curves:
- secp384r1
certificate preferences apply locally
certificate signature schemes:
- ecdsa_sha384
- rsa_pkcs1_sha384
certificate keys:
- ecdsa_p384
- rsa_3072
- rsa_4096
- rsa_pss_3072
- rsa_pss_4096
6 changes: 3 additions & 3 deletions tests/unit/s2n_config_test.c
Original file line number Diff line number Diff line change
Expand Up @@ -1093,7 +1093,7 @@ int main(int argc, char **argv)
EXPECT_SUCCESS(s2n_test_cert_permutation_load_server_chain(&invalid_cert, "ec", "ecdsa", "p384", "sha256"));
EXPECT_SUCCESS(s2n_test_cert_permutation_load_server_chain(&valid_cert, "ec", "ecdsa", "p384", "sha384"));

struct s2n_security_policy rfc9151_applied_locally = security_policy_rfc9151;
struct s2n_security_policy rfc9151_applied_locally = security_policy_20250429;
rfc9151_applied_locally.certificate_preferences_apply_locally = true;

/* rfc9151 doesn't allow SHA256 signatures, but does allow SHA384 signatures,
Expand All @@ -1108,7 +1108,7 @@ int main(int argc, char **argv)

/* when cert preferences don't apply locally, invalid certs are accepted */
{
struct s2n_security_policy non_local_rfc9151 = security_policy_rfc9151;
struct s2n_security_policy non_local_rfc9151 = security_policy_20250429;
non_local_rfc9151.certificate_preferences_apply_locally = false;

DEFER_CLEANUP(struct s2n_config *config = s2n_config_new(), s2n_config_ptr_free);
Expand Down Expand Up @@ -1158,7 +1158,7 @@ int main(int argc, char **argv)
* over every certificate without performing any validation is expensive.
*/
{
struct s2n_security_policy non_local_rfc9151 = security_policy_rfc9151;
struct s2n_security_policy non_local_rfc9151 = security_policy_20250429;

/* Assert that the security policy WOULD apply,
* if certificate_preferences_apply_locally was true.
Expand Down
2 changes: 1 addition & 1 deletion tests/unit/s2n_connection_test.c
Original file line number Diff line number Diff line change
Expand Up @@ -636,7 +636,7 @@ int main(int argc, char **argv)
* s2n_connection_set_config will fail
*/
{
struct s2n_security_policy rfc9151_applied_locally = security_policy_rfc9151;
struct s2n_security_policy rfc9151_applied_locally = security_policy_20250429;
rfc9151_applied_locally.certificate_preferences_apply_locally = true;

DEFER_CLEANUP(struct s2n_config *config = s2n_config_new(), s2n_config_ptr_free);
Expand Down
12 changes: 6 additions & 6 deletions tests/unit/s2n_security_policies_test.c
Original file line number Diff line number Diff line change
Expand Up @@ -816,9 +816,9 @@ int main(int argc, char **argv)
if (s2n_is_tls13_fully_supported()) {
/* 20250211 */
{
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_rfc9151, "default_tls13", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_rfc9151, "default_fips", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_rfc9151, "20250211", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20250429, "default_tls13", ecdsa_sha384_chain_and_key));
Comment on lines -821 to +819
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did this test actually want a non-fixed RFC9151? Same question for below.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current API for s2n_test_security_policies_compatible doesn't really let us chose anything else for the base policy (not the one that's by string).

Technically, what the test wants is the full set of all past/future rfc9151 policies, but that's hard to express in the current framework. If we did change rfc9151 we'd ideally extend this test to include coverage for both the previous & next version of it. I'm not sure of a good way to indicate that -- open to thoughts.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what we did for the default policies:

/* Sanity check that changes to default security policies are not completely
* backwards incompatible.
*
* If we get into a situation where the current default has NO options in
* common with a past version of the default, then updating s2n-tls becomes
* very dangerous. Fleets with a mix of the old default and the new default
* may be unable to communicate.
*
* This check only performs one basic handshake, so isn't exhaustive.
*/
{
/* "default" */
{
const struct s2n_security_policy *versioned_policies[] = {
&security_policy_20170210,
&security_policy_20240501,
};
const struct s2n_supported_cert supported_certs[] = {
{ .cert = rsa_chain_and_key },
{ .cert = ecdsa_chain_and_key, .start_index = 1 },
};
EXPECT_OK(s2n_test_default_backwards_compatible("default",
versioned_policies, s2n_array_len(versioned_policies),
supported_certs, s2n_array_len(supported_certs)));
};
/* "default_tls13" */
if (s2n_is_rsa_pss_certs_supported()) {
const struct s2n_security_policy *versioned_policies[] = {
&security_policy_20240417,
&security_policy_20240503,
};
const struct s2n_supported_cert supported_certs[] = {
{ .cert = rsa_chain_and_key },
{ .cert = ecdsa_chain_and_key },
{ .cert = rsa_pss_chain_and_key },
};
EXPECT_OK(s2n_test_default_backwards_compatible("default_tls13",
versioned_policies, s2n_array_len(versioned_policies),
supported_certs, s2n_array_len(supported_certs)));
};
/* "default_fips" */
{
const struct s2n_security_policy *versioned_policies[] = {
&security_policy_20240416,
&security_policy_20240502,
};
const struct s2n_supported_cert supported_certs[] = {
{ .cert = rsa_chain_and_key },
{ .cert = ecdsa_chain_and_key },
};
EXPECT_OK(s2n_test_default_backwards_compatible("default_fips",
versioned_policies, s2n_array_len(versioned_policies),
supported_certs, s2n_array_len(supported_certs)));
};
};
We made lists of the default policies.

EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20250429, "default_fips", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20250429, "20250211", ecdsa_sha384_chain_and_key));

/* default_tls13 is currently 20240503 */
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20240503, "rfc9151", ecdsa_sha384_chain_and_key));
Expand All @@ -837,9 +837,9 @@ int main(int argc, char **argv)

/* 20250414 */
{
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_rfc9151, "default_tls13", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_rfc9151, "default_fips", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_rfc9151, "20250414", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20250429, "default_tls13", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20250429, "default_fips", ecdsa_sha384_chain_and_key));
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20250429, "20250414", ecdsa_sha384_chain_and_key));

/* default_tls13 is currently 20240503 */
EXPECT_OK(s2n_test_security_policies_compatible(&security_policy_20240503, "rfc9151", ecdsa_sha384_chain_and_key));
Expand Down
2 changes: 1 addition & 1 deletion tests/unit/s2n_x509_validator_test.c
Original file line number Diff line number Diff line change
Expand Up @@ -2192,7 +2192,7 @@ int main(int argc, char **argv)
EXPECT_SUCCESS(s2n_read_test_pem_and_len(S2N_MIXED_CHAIN_CERTS, &chain_pem[0], &chain_pem_len,
S2N_MAX_TEST_PEM_SIZE));

struct s2n_security_policy security_policy_not_local = security_policy_rfc9151;
struct s2n_security_policy security_policy_not_local = security_policy_20250429;
security_policy_not_local.certificate_preferences_apply_locally = false;

/* when the peer sends the full chain with a non-compliant CA, verification fails when reading in the certs */
Expand Down
8 changes: 4 additions & 4 deletions tls/s2n_certificate_keys.c
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ const struct s2n_certificate_key s2n_ec_p521 = {
.bits = 521,
};

const struct s2n_certificate_key *s2n_certificate_keys_rfc9151[] = {
const struct s2n_certificate_key *s2n_certificate_keys_20250429[] = {
/**
*= https://www.rfc-editor.org/rfc/rfc9151#section-5.1
*# CNSA (D)TLS connections MUST use secp384r1
Expand All @@ -103,7 +103,7 @@ const struct s2n_certificate_key *s2n_certificate_keys_rfc9151[] = {
&s2n_rsa_pss_4096,
};

struct s2n_certificate_key_preferences s2n_certificate_key_preferences_rfc9151 = {
.count = s2n_array_len(s2n_certificate_keys_rfc9151),
.certificate_keys = s2n_certificate_keys_rfc9151,
struct s2n_certificate_key_preferences s2n_certificate_key_preferences_20250429 = {
.count = s2n_array_len(s2n_certificate_keys_20250429),
.certificate_keys = s2n_certificate_keys_20250429,
};
2 changes: 1 addition & 1 deletion tls/s2n_certificate_keys.h
Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,4 @@ extern const struct s2n_certificate_key s2n_ec_p256;
extern const struct s2n_certificate_key s2n_ec_p384;
extern const struct s2n_certificate_key s2n_ec_p521;

extern struct s2n_certificate_key_preferences s2n_certificate_key_preferences_rfc9151;
extern struct s2n_certificate_key_preferences s2n_certificate_key_preferences_20250429;
8 changes: 4 additions & 4 deletions tls/s2n_cipher_preferences.c
Original file line number Diff line number Diff line change
Expand Up @@ -2152,7 +2152,7 @@ const struct s2n_cipher_preferences cipher_preferences_20240603 = {
.allow_chacha20_boosting = true,
};

struct s2n_cipher_suite *cipher_suites_rfc9151[] = {
struct s2n_cipher_suite *cipher_suites_20250429[] = {
/* TLS1.2 */
&s2n_ecdhe_ecdsa_with_aes_256_gcm_sha384,
&s2n_ecdhe_rsa_with_aes_256_gcm_sha384,
Expand All @@ -2163,9 +2163,9 @@ struct s2n_cipher_suite *cipher_suites_rfc9151[] = {
&s2n_tls13_aes_256_gcm_sha384,
};

const struct s2n_cipher_preferences cipher_preferences_rfc9151 = {
.count = s2n_array_len(cipher_suites_rfc9151),
.suites = cipher_suites_rfc9151,
const struct s2n_cipher_preferences cipher_preferences_20250429 = {
.count = s2n_array_len(cipher_suites_20250429),
.suites = cipher_suites_20250429,
.allow_chacha20_boosting = false,
};

Expand Down
2 changes: 1 addition & 1 deletion tls/s2n_cipher_preferences.h
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,6 @@ extern const struct s2n_cipher_preferences cipher_preferences_20190801;
extern const struct s2n_cipher_preferences cipher_preferences_20190120;
extern const struct s2n_cipher_preferences cipher_preferences_20190121;
extern const struct s2n_cipher_preferences cipher_preferences_20190122;
extern const struct s2n_cipher_preferences cipher_preferences_rfc9151;
extern const struct s2n_cipher_preferences cipher_preferences_20210816;
extern const struct s2n_cipher_preferences cipher_preferences_20210816_gcm;
extern const struct s2n_cipher_preferences cipher_preferences_20210825;
Expand All @@ -63,6 +62,7 @@ extern const struct s2n_cipher_preferences cipher_preferences_20241008;
extern const struct s2n_cipher_preferences cipher_preferences_20241008_gcm;
extern const struct s2n_cipher_preferences cipher_preferences_20241009;
extern const struct s2n_cipher_preferences cipher_preferences_20250211;
extern const struct s2n_cipher_preferences cipher_preferences_20250429;

extern const struct s2n_cipher_preferences cipher_preferences_default_fips;

Expand Down
17 changes: 10 additions & 7 deletions tls/s2n_security_policies.c
Original file line number Diff line number Diff line change
Expand Up @@ -1133,13 +1133,13 @@ const struct s2n_security_policy security_policy_20210816_gcm = {
* This security policy is derived from the following specification:
* https://datatracker.ietf.org/doc/html/rfc9151
*/
const struct s2n_security_policy security_policy_rfc9151 = {
const struct s2n_security_policy security_policy_20250429 = {
.minimum_protocol_version = S2N_TLS12,
.cipher_preferences = &cipher_preferences_rfc9151,
.cipher_preferences = &cipher_preferences_20250429,
.kem_preferences = &kem_preferences_null,
.signature_preferences = &s2n_signature_preferences_rfc9151,
.certificate_signature_preferences = &s2n_certificate_signature_preferences_rfc9151,
.certificate_key_preferences = &s2n_certificate_key_preferences_rfc9151,
.signature_preferences = &s2n_signature_preferences_20250429,
.certificate_signature_preferences = &s2n_certificate_signature_preferences_20250429,
.certificate_key_preferences = &s2n_certificate_key_preferences_20250429,
.ecc_preferences = &s2n_ecc_preferences_20210816,
.certificate_preferences_apply_locally = true,
};
Expand All @@ -1155,7 +1155,7 @@ const struct s2n_security_policy security_policy_20250211 = {
.minimum_protocol_version = S2N_TLS13,
.cipher_preferences = &cipher_preferences_20250211,
.kem_preferences = &kem_preferences_null,
.signature_preferences = &s2n_signature_preferences_rfc9151,
.signature_preferences = &s2n_signature_preferences_20250429,
.certificate_signature_preferences = &s2n_certificate_signature_preferences_20201110,
.ecc_preferences = &s2n_ecc_preferences_20210816,
.rules = {
Expand Down Expand Up @@ -1266,6 +1266,7 @@ const struct s2n_security_policy security_policy_null = {
};

struct s2n_security_policy_selection security_policy_selection[] = {
/* If changing named policies, please update the usage guide's docs on the corresponding policy. */
{ .version = "default", .security_policy = &security_policy_20240501, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "default_tls13", .security_policy = &security_policy_20240503, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "default_fips", .security_policy = &security_policy_20240502, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
Expand Down Expand Up @@ -1381,7 +1382,9 @@ struct s2n_security_policy_selection security_policy_selection[] = {
{ .version = "20240603", .security_policy = &security_policy_20240603, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "20250211", .security_policy = &security_policy_20250211, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "20250414", .security_policy = &security_policy_20250414, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "rfc9151", .security_policy = &security_policy_rfc9151, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "20250429", .security_policy = &security_policy_20250429, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
/* If changing this, please update the usage guide's docs on the corresponding policy. */
{ .version = "rfc9151", .security_policy = &security_policy_20250429, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "test_all", .security_policy = &security_policy_test_all, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "test_all_fips", .security_policy = &security_policy_test_all_fips, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
{ .version = "test_all_ecdsa", .security_policy = &security_policy_test_all_ecdsa, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
Expand Down
2 changes: 1 addition & 1 deletion tls/s2n_security_policies.h
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ extern const struct s2n_security_policy security_policy_20241001_pq_mixed;
extern const struct s2n_security_policy security_policy_20250211;
extern const struct s2n_security_policy security_policy_20250414;

extern const struct s2n_security_policy security_policy_rfc9151;
extern const struct s2n_security_policy security_policy_20250429;
extern const struct s2n_security_policy security_policy_test_all;

extern const struct s2n_security_policy security_policy_test_all_tls12;
Expand Down
16 changes: 8 additions & 8 deletions tls/s2n_signature_scheme.c
Original file line number Diff line number Diff line change
Expand Up @@ -557,7 +557,7 @@ const struct s2n_signature_preferences s2n_signature_preferences_20210816 = {
.signature_schemes = s2n_sig_scheme_pref_list_20210816
};

const struct s2n_signature_scheme* const s2n_sig_scheme_pref_list_rfc9151[] = {
const struct s2n_signature_scheme* const s2n_sig_scheme_pref_list_20250429[] = {
/* ECDSA */
&s2n_ecdsa_sha384,

Expand All @@ -570,7 +570,7 @@ const struct s2n_signature_scheme* const s2n_sig_scheme_pref_list_rfc9151[] = {
&s2n_rsa_pkcs1_sha384,
};

const struct s2n_signature_scheme* const s2n_cert_sig_scheme_pref_list_rfc9151[] = {
const struct s2n_signature_scheme* const s2n_cert_sig_scheme_pref_list_20250429[] = {
/* ECDSA */
&s2n_ecdsa_sha384,

Expand All @@ -589,14 +589,14 @@ const struct s2n_signature_scheme* const s2n_cert_sig_scheme_pref_list_rfc9151[]
&s2n_rsa_pkcs1_sha384,
};

const struct s2n_signature_preferences s2n_signature_preferences_rfc9151 = {
.count = s2n_array_len(s2n_sig_scheme_pref_list_rfc9151),
.signature_schemes = s2n_sig_scheme_pref_list_rfc9151
const struct s2n_signature_preferences s2n_signature_preferences_20250429 = {
.count = s2n_array_len(s2n_sig_scheme_pref_list_20250429),
.signature_schemes = s2n_sig_scheme_pref_list_20250429
};

const struct s2n_signature_preferences s2n_certificate_signature_preferences_rfc9151 = {
.count = s2n_array_len(s2n_cert_sig_scheme_pref_list_rfc9151),
.signature_schemes = s2n_cert_sig_scheme_pref_list_rfc9151
const struct s2n_signature_preferences s2n_certificate_signature_preferences_20250429 = {
.count = s2n_array_len(s2n_cert_sig_scheme_pref_list_20250429),
.signature_schemes = s2n_cert_sig_scheme_pref_list_20250429
};

/*
Expand Down
4 changes: 2 additions & 2 deletions tls/s2n_signature_scheme.h
Original file line number Diff line number Diff line change
Expand Up @@ -83,8 +83,8 @@ extern const struct s2n_signature_preferences s2n_signature_preferences_20200207
extern const struct s2n_signature_preferences s2n_signature_preferences_20201021;
extern const struct s2n_signature_preferences s2n_signature_preferences_20210816;
extern const struct s2n_signature_preferences s2n_signature_preferences_20240521;
extern const struct s2n_signature_preferences s2n_signature_preferences_rfc9151;
extern const struct s2n_signature_preferences s2n_certificate_signature_preferences_rfc9151;
extern const struct s2n_signature_preferences s2n_signature_preferences_20250429;
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;
Expand Down
Loading