Skip to content

feat: deprecate default tls13, pq policies #6038

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.

Sign up for GitHub

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
jmayclin wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: deprecate default tls13, pq policies #6038

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8a1b80
feat: deprecate default tls13, pq policies
jmayclin Aug 14, 2026
7aa56d8
update policy snapshots
jmayclin Aug 14, 2026
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
2 changes: 1 addition & 1 deletion docs/FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Have you already configure a trust store to be able to trust your peer's certifi
s2n-tls sleeps for a random period between 10 and 30 seconds after specific errors occur to avoid leaking any secret information via timing data. This technique is called blinding and it is utilized to prevent timing side-channel attacks. See [blinding](usage-guide/topics/ch03-error-handling.md#blinding).

### Which security policy should I use if I want to make sure that it will never be altered?
Our numbered security policies are guaranteed to never change. We will not alter or update them based on changing cryptography standards. However, our named security policies (like “default” or “default_tls13”) change based on new cryptography standards that come out. See [security policies](usage-guide/topics/ch06-security-policies.md).
Our numbered security policies are guaranteed to never change. We will not alter or update them based on changing cryptography standards. However, our named security policies (like “default” or “default_fips”) change based on new cryptography standards that come out. See [security policies](usage-guide/topics/ch06-security-policies.md).

### Why does s2n-tls have a dependency on OpenSSL? Isn't s2n-tls a replacement for OpenSSL?
OpenSSL includes both a TLS library, called libssl, and a cryptography library, called libcrypto. s2n-tls implements a TLS library, but does not implement a cryptography library. Instead, s2n-tls links to a separate libcrypto in order to perform cryptographic operations. Libcryptos other than OpenSSL can be used, such as [AWS-LC](https://github.com/aws/aws-lc).
Expand Down
27 changes: 12 additions & 15 deletions docs/usage-guide/topics/ch06-security-policies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,8 @@ The following chart maps the security policy version to protocol version and cip

| version | TLS1.0 | TLS1.1 | TLS1.2 | TLS1.3 | AES-CBC | AES-GCM | CHACHAPOLY | 3DES | RC4 | DHE | ECDHE | RSA kx |
|---------------|--------|--------|--------|--------|---------|---------|------------|------|-----|-----|-------|--------|
| default | | | X | X | X | X | X | | | | X | |
| default_fips | | | X | X | X | X | | | | | X | |
| default_tls13 | | | X | X | X | X | X | | | | X | |
| default | | | X | X | | X | X | | | | X | |
| default_fips | | | X | X | | X | | | | | X | |
| 20240501 | | | X | | X | X | | | | | X | |
| 20240502 | | | X | | X | X | | | | | X | |
| 20240503 | | | X | X | X | X | | | | | X | |
Expand All @@ -55,17 +54,17 @@ The following chart maps the security policy version to protocol version and cip
| 20200207 | | | | X | | X | X | | | | X | |
| rfc9151 | | | X | X | | X | | | | | X | |

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.
The "default" 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 for the named policies for the current version and
historical s2n versions are in the "Named Policy History" below. The current
matching fixed versions are:

| "default" | "default_fips" | "default_tls13" | "rfc9151" |
|-----------|----------------|-----------------|-----------|
| 20251014 | 20251015 | 20240503 | 20251013 |
| "default" | "default_fips" | "rfc9151" |
|-----------|----------------|-----------|
| 20251014 | 20251015 | 20251013 |

"rfc9151" is derived from [Commercial National Security Algorithm (CNSA) Suite Profile for TLS and DTLS 1.2 and 1.3](https://datatracker.ietf.org/doc/html/rfc9151). This policy restricts the algorithms allowed for signatures on certificates in the certificate chain to RSA or ECDSA with sha384, which may require you to update your certificates.
Like the default policies, this policy may also change if the source RFC definition changes.
Expand All @@ -89,7 +88,6 @@ s2n-tls usually prefers AES over ChaCha20. However, some clients-- particularly
|---------------|-----------|-------|--------------|---------|
| default | X | X | | X |
| default_fips | X | X | | X |
| default_tls13 | X | X | | X |
| 20240501 | X | X | | X |
| 20240502 | X | X | | X |
| 20240503 | X | X | | X |
Expand Down Expand Up @@ -124,7 +122,6 @@ s2n-tls usually prefers AES over ChaCha20. However, some clients-- particularly
|---------------|-----------|-----------|--------|
| default | X | X | X |
| default_fips | X | X | |
| default_tls13 | X | X | X |
| 20240501 | X | X | X |
| 20240502 | X | X | |
| 20240503 | X | X | X |
Expand All @@ -151,11 +148,11 @@ s2n-tls usually prefers AES over ChaCha20. However, some clients-- particularly

### Named Policy History

| Version | "default" | "default_fips" | "default_tls13" | "rfc9151" |
|------------|-----------|----------------|-----------------|-----------|
| v1.6.0 | 20251014 | 20251015 | 20240503 | 20251013 |
| v1.5.25 | 20240501 | 20240502 | 20240503 | 20250429 |
| v1.4.16 | 20240501 | 20240502 | 20240503 | (*) |
| Older | 20170210 | 20240416 | 20240417 | (*) |
| Version | "default" | "default_fips" | "rfc9151" |
|------------|-----------|----------------|-----------|
| v1.6.0 | 20251014 | 20251015 | 20251013 |
| v1.5.25 | 20240501 | 20240502 | 20250429 |
| v1.4.16 | 20240501 | 20240502 | (*) |
| Older | 20170210 | 20240416 | (*) |

(*): No fixed policy available.
12 changes: 6 additions & 6 deletions docs/usage-guide/topics/ch16-post-quantum.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Listening on localhost:8000

Post-quantum algorithms are enabled by configuring a security policy (see [Security Policies](./ch06-security-policies.md)) that supports post-quantum algorithms.

"default_pq" is the equivalent of "default_tls13", but with PQ support. Like the other default policies, "default_pq" may change as a result of library updates. The fixed, numbered equivalent of "default_pq" is currently "20250721". For previous defaults, see the "Default Policy History" section below.
Post quantum algorithms are enabled in the "default" policy. For previous defaults, see the "Default Policy History" section below.

"cnsa_2" is derived from [Commercial National Security Algorithm (CNSA) Suite Profile for TLS 1.3](https://datatracker.ietf.org/doc/draft-becker-cnsa2-tls-profile/). This is a TLS 1.3 PQ only policy that requires pure ML-KEM-1024 for key exchange and ML-DSA-87 for signature and certificate verification.

Expand All @@ -49,7 +49,7 @@ Other available PQ policies are compared in the tables below.

| Version | x25519+mlkem768 | secp256r1+mlkem768 | secp384r1+mlkem1024 | mlkem1024 |
|-----------------------|-----------------|--------------------|---------------------|-----------|
| default_pq / 20250721 | X | X | X | |
| default / 20251014 | X | X | X | |
| 20250512 | X | X | | |
| cnsa_2 | | | | X |
| cnsa_1_2_interop | | | | X |
Expand All @@ -58,7 +58,7 @@ Other available PQ policies are compared in the tables below.

| Version | ML-DSA | ECDSA | RSA | RSA-PSS | Legacy SHA1 |
|-----------------------|--------|-------|-----|---------|-------------|
| default_pq / 20250721 | X | X | X | X | |
| default / 20251014 | X | X | X | X | |
| 20250512 | X | X | X | X | |
| cnsa_2 | 87 | | | | |
| cnsa_1_2_interop | 87 | X | X | X | |
Expand All @@ -71,15 +71,15 @@ Note: the "cnsa_2" policy only allows ML-KEM-1024, thus there is no fallback to

| Version | secp256r1 | x25519 | secp384r1 | secp521r1 | DHE | RSA |
|-----------------------|-----------|--------|-----------|-----------|-----|-----|
| default_pq / 20250721 | X | X | X | X | | |
| default / 20251014 | X | X | X | X | | |
| 20250512 | X | X | X | X | | |
| cnsa_1_2_interop | | | X | | | |

### Chart: Security Policy Version To Ciphers

| Version | AES-CBC | AES-GCM | CHACHAPOLY | 3DES |
|-----------------------|---------|---------|------------|------|
| default_pq / 20250721 | X | X | X | |
| default / 20251014 | X | X | X | |
| 20250512 | X | X | X | |
| cnsa_2 | | X | | |
| cnsa_1_2_interop | | X | | |
Expand All @@ -88,7 +88,7 @@ Note: the "cnsa_2" policy only allows ML-KEM-1024, thus there is no fallback to

| Version | 1.2 | 1.3 |
|-----------------------|-----|-----|
| default_pq / 20250721 | X | X |
| default / 20251014 | X | X |
| 20250512 | X | X |
| cnsa_2 | | X |
| cnsa_1_2_interop | X | X |
Expand Down
29 changes: 1 addition & 28 deletions tests/policy_snapshot/snapshots/default_pq
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,10 @@ cipher suites:
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
Comment on lines -13 to -18

@jouho jouho Aug 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Is this a safe change to make? If customers are using this policy and relying on CBC or ChaChaPolyciphers, won't removing them here break clients that only support those suites?

@jmayclin jmayclin Aug 17, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

In a way no, not a safe change to make. But the explicit stance of the default_* policies is that we do not promising stability for them.

Basically, this is the exact same tradeoff that we made when we dropped the old ciphers for our default policy. #5560

@jouho jouho Aug 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Ah true. Since this is a pretty large policy change, could we include a release note in the PR description?

signature schemes:
- mldsa44
- mldsa65
- mldsa87
- ecdsa_sha256
- ecdsa_sha384
- ecdsa_sha512
Expand All @@ -37,24 +28,6 @@ curves:
- x25519
- secp384r1
- secp521r1
certificate signature schemes:
- mldsa44
- mldsa65
- mldsa87
- 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
- legacy_rsa_sha224
- ecdsa_sha256
- ecdsa_sha384
- ecdsa_sha512
- legacy_ecdsa_sha224
pq:
- revision: 5
- kem groups:
Expand Down
29 changes: 7 additions & 22 deletions tests/policy_snapshot/snapshots/default_tls13
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,15 +7,9 @@ cipher suites:
- TLS_AES_256_GCM_SHA384
- TLS_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
signature schemes:
- ecdsa_sha256
- ecdsa_sha384
Expand All @@ -34,18 +28,9 @@ curves:
- x25519
- secp384r1
- secp521r1
certificate signature schemes:
- 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
- legacy_rsa_sha224
- ecdsa_sha256
- ecdsa_sha384
- ecdsa_sha512
- legacy_ecdsa_sha224
pq:
- revision: 5
- kem groups:
-- X25519MLKEM768
-- SecP256r1MLKEM768
-- SecP384r1MLKEM1024
94 changes: 23 additions & 71 deletions tests/unit/s2n_security_policies_test.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -235,11 +235,11 @@ int main(int argc, char **argv)
EXPECT_SUCCESS(s2n_find_security_policy_from_version("default_tls13", &security_policy));
EXPECT_TRUE(s2n_ecc_is_extension_required(security_policy));
EXPECT_FALSE(s2n_pq_kem_is_extension_required(security_policy));
EXPECT_TRUE(s2n_security_policy_supports_tls13(security_policy));
EXPECT_EQUAL(0, 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);
EXPECT_NULL(security_policy->kem_preferences->kems);
EXPECT_EQUAL(0, security_policy->kem_preferences->kem_count);
EXPECT_EQUAL(security_policy->kem_preferences, &kem_preferences_pq_tls_1_3_ietf_2025_07);
EXPECT_EQUAL(3, security_policy->kem_preferences->tls13_kem_group_count);
EXPECT_TRUE(s2n_security_policy_supports_tls13(security_policy));

/* The "all" security policy contains both TLS 1.2 KEM extension and TLS 1.3 KEM SupportedGroup entries*/
security_policy = NULL;
Expand Down Expand Up @@ -1086,6 +1086,7 @@ int main(int argc, char **argv)
const struct s2n_security_policy *versioned_policies[] = {
&security_policy_20240417,
&security_policy_20240503,
&security_policy_20251014,
};

DEFER_CLEANUP(struct s2n_test_cert_chain_list cert_chains = { 0 },
Expand Down Expand Up @@ -1125,6 +1126,7 @@ int main(int argc, char **argv)
&security_policy_20241001,
&security_policy_20250512,
&security_policy_20250721,
&security_policy_20251014,
};

DEFER_CLEANUP(struct s2n_test_cert_chain_list cert_chains = { 0 },
Expand Down Expand Up @@ -1156,79 +1158,24 @@ int main(int argc, char **argv)
};
};

/* Test that default_pq always matches default_tls13 */
/* Test that default, default_pq, and default_tls13 are all aliases of the
* same security policy */
{
const struct s2n_security_policy *default_policy = NULL;
EXPECT_SUCCESS(s2n_find_security_policy_from_version("default", &default_policy));

const struct s2n_security_policy *default_pq = NULL;
EXPECT_SUCCESS(s2n_find_security_policy_from_version("default_pq", &default_pq));
EXPECT_NOT_EQUAL(default_pq->kem_preferences, &kem_preferences_null);

const struct s2n_security_policy *default_tls13 = NULL;
EXPECT_SUCCESS(s2n_find_security_policy_from_version("default_tls13", &default_tls13));
EXPECT_EQUAL(default_tls13->kem_preferences, &kem_preferences_null);

/* Except for PQ algorithms, the two policies should match */

/* Most fields can be compared directly. We just ignore kem_preferences. */
EXPECT_EQUAL(default_pq->minimum_protocol_version, default_tls13->minimum_protocol_version);
EXPECT_EQUAL(default_pq->cipher_preferences, default_tls13->cipher_preferences);
EXPECT_EQUAL(default_pq->ecc_preferences, default_tls13->ecc_preferences);
EXPECT_EQUAL(default_pq->certificate_key_preferences, default_tls13->certificate_key_preferences);
EXPECT_EQUAL(default_pq->certificate_preferences_apply_locally,
default_tls13->certificate_preferences_apply_locally);

/* The signature preferences match,
* EXCEPT for the added PQ algorithms, which should come first.
*/
{
const struct s2n_signature_preferences *pq_sig_prefs = default_pq->signature_preferences;
const struct s2n_signature_preferences *tls13_sig_prefs = default_tls13->signature_preferences;

/* Count how many PQ sig schemes */
size_t pq_count = 0;
while (pq_count < pq_sig_prefs->count) {
if (pq_sig_prefs->signature_schemes[pq_count]->sig_alg
== S2N_SIGNATURE_MLDSA) {
pq_count++;
} else {
break;
}
}
EXPECT_TRUE(pq_count > 0);

/* Compare the two preference lists, minus the PQ sig schemes */
EXPECT_EQUAL(pq_sig_prefs->count - pq_count, tls13_sig_prefs->count);
for (size_t i = 0; i < default_tls13->signature_preferences->count; i++) {
EXPECT_EQUAL(pq_sig_prefs->signature_schemes[i + pq_count],
tls13_sig_prefs->signature_schemes[i]);
}
}
EXPECT_NOT_EQUAL(default_tls13->kem_preferences, &kem_preferences_null);

/* The certificate signature preferences match,
* EXCEPT for the added PQ algorithms, which should come first.
*/
{
const struct s2n_signature_preferences *pq_sig_prefs = default_pq->certificate_signature_preferences;
const struct s2n_signature_preferences *tls13_sig_prefs = default_tls13->certificate_signature_preferences;

/* Count how many PQ sig schemes */
size_t pq_count = 0;
while (pq_count < pq_sig_prefs->count) {
if (pq_sig_prefs->signature_schemes[pq_count]->sig_alg
== S2N_SIGNATURE_MLDSA) {
pq_count++;
} else {
break;
}
}
EXPECT_TRUE(pq_count > 0);

/* Compare the two preference lists, minus the PQ sig schemes */
EXPECT_EQUAL(pq_sig_prefs->count - pq_count, tls13_sig_prefs->count);
for (size_t i = 0; i < default_tls13->signature_preferences->count; i++) {
EXPECT_EQUAL(pq_sig_prefs->signature_schemes[i + pq_count],
tls13_sig_prefs->signature_schemes[i]);
}
}
/* All three default policies now alias the same underlying policy */
EXPECT_EQUAL(default_pq, default_policy);
EXPECT_EQUAL(default_tls13, default_policy);
EXPECT_EQUAL(default_pq, default_tls13);
};

/* s2n_find_version_from_security_policy */
Expand All @@ -1245,11 +1192,16 @@ int main(int argc, char **argv)
EXPECT_STRING_EQUAL(s2n_find_version_from_security_policy(policy), "20240501");
};

/* Returns correct version for default_tls13 */
/* Returns correct version for default_tls13.
*
* default, default_tls13, and default_pq all alias the same underlying
* policy. Since "default" is the first entry in the table with that
* policy pointer, it is the version returned.
*/
{
const struct s2n_security_policy *policy = NULL;
EXPECT_SUCCESS(s2n_find_security_policy_from_version("default_tls13", &policy));
EXPECT_STRING_EQUAL(s2n_find_version_from_security_policy(policy), "default_tls13");
EXPECT_STRING_EQUAL(s2n_find_version_from_security_policy(policy), "default");
};

/* Returns "unknown" for a policy not in the selection table */
Expand Down
Loading
Loading