From 4365f574f3e04898b51450c77c6cedd7e8990b46 Mon Sep 17 00:00:00 2001 From: Lindsay Stewart Date: Tue, 30 Jul 2024 23:37:22 -0700 Subject: [PATCH] docs: add pq to usage guide --- bin/s2nc.c | 1 + bin/s2nd.c | 1 + bindings/rust/s2n-tls/src/security.rs | 5 + docs/usage-guide/topics/SUMMARY.md | 1 + docs/usage-guide/topics/ch15-post-quantum.md | 107 +++++++++++++++++++ tests/unit/s2n_security_policies_test.c | 22 ++++ tls/s2n_security_policies.c | 15 +++ 7 files changed, 152 insertions(+) create mode 100644 docs/usage-guide/topics/ch15-post-quantum.md diff --git a/bin/s2nc.c b/bin/s2nc.c index 1c7421d2df4..b82e7ef78f8 100644 --- a/bin/s2nc.c +++ b/bin/s2nc.c @@ -563,6 +563,7 @@ int main(int argc, char *const *argv) } GUARD_EXIT(s2n_init(), "Error running s2n_init()"); + printf("libcrypto: %s\n", SSLeay_version(SSLEAY_VERSION)); if ((r = getaddrinfo(host, port, &hints, &ai_list)) != 0) { fprintf(stderr, "error: %s\n", gai_strerror(r)); diff --git a/bin/s2nd.c b/bin/s2nd.c index 886c50b3e35..401fd57344f 100644 --- a/bin/s2nd.c +++ b/bin/s2nd.c @@ -562,6 +562,7 @@ int main(int argc, char *const *argv) } GUARD_EXIT(s2n_init(), "Error running s2n_init()"); + printf("libcrypto: %s\n", SSLeay_version(SSLEAY_VERSION)); printf("Listening on %s:%s\n", host, port); diff --git a/bindings/rust/s2n-tls/src/security.rs b/bindings/rust/s2n-tls/src/security.rs index e3684a67336..8b23307c1cd 100644 --- a/bindings/rust/s2n-tls/src/security.rs +++ b/bindings/rust/s2n-tls/src/security.rs @@ -87,9 +87,14 @@ pub const DEFAULT_TLS13: Policy = policy!("default_tls13"); #[cfg(feature = "pq")] pub const TESTING_PQ: Policy = policy!("PQ-TLS-1-0-2021-05-26"); +#[cfg(feature = "pq")] +pub const DEFAULT_PQ: Policy = policy!("default_pq"); + pub const ALL_POLICIES: &[Policy] = &[ DEFAULT, DEFAULT_TLS13, #[cfg(feature = "pq")] TESTING_PQ, + #[cfg(feature = "pq")] + DEFAULT_PQ, ]; diff --git a/docs/usage-guide/topics/SUMMARY.md b/docs/usage-guide/topics/SUMMARY.md index b365246a4ca..308864e4cec 100644 --- a/docs/usage-guide/topics/SUMMARY.md +++ b/docs/usage-guide/topics/SUMMARY.md @@ -15,3 +15,4 @@ - [Offloading Private Key Operations](./ch12-private-key-ops.md) - [Pre-shared Keys](./ch13-preshared-keys.md) - [Early Data](./ch14-early-data.md) +- [Post Quantum Support](./ch15-post-quantum.md) diff --git a/docs/usage-guide/topics/ch15-post-quantum.md b/docs/usage-guide/topics/ch15-post-quantum.md new file mode 100644 index 00000000000..ef6394db494 --- /dev/null +++ b/docs/usage-guide/topics/ch15-post-quantum.md @@ -0,0 +1,107 @@ +# Post Quantum (PQ) Support + +s2n-tls supports post-quantum key exchange for TLS1.3. Currently, only [Kyber](https://pq-crystals.org/kyber/) is supported. + +Specifically, s2n-tls supports hybrid key exchange. s2n-tls uses both classic and post-quantum key exchange algorithms at the same time, combining the two secrets. If one of the algorithms is compromised, either because advances in quantum computing make the classic algorithm insecure or because cryptographers find a flaw in the relatively new post-quantum algorithm, the secret is still secure. Hybrid post-quantum key exchange is more secure than standard key exchange, but slower and more expensive. + +Careful: if an s2n-tls server is configured to support post-quantum key exchange, the server will require that any client that advertises support ultimately uses post-quantum key exchange. That will result in a retry and an extra round trip if the client does not intially provide a post-quantum key share. + +## Requirements + +### AWS-LC + +s2n-tls must be built with aws-lc to use post-quantum key exchange. See the [s2n-tls build documentation](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-with-a-specific-libcrypto) for how to build with aws-lc. + +If you're unsure what cryptography library s2n-tls is built against, trying running s2nd or s2nc: +``` +> s2nd localhost 8000 +libcrypto: AWS-LC +Listening on localhost:8000 +``` +If you built s2n-tls with the [cmake build instructions](https://github.com/aws/s2n-tls/blob/main/docs/BUILD.md#building-s2n-tls), s2nd and s2nc can be found in `build/bin`. + +### Security Policy + +Post-quantum key exchange is enabled by configuring a security policy (see [Security Policies](./ch06-security-policies.md)) that supports post-quantum key exchange 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 "20240730". For previous defaults, see the "Default Policy History" section below. + +Other available PQ policies are compared in the tables below. + +### Chart: Security Policy Version To PQ Hybrid Key Exchange Methods + +| Version | secp256r1+kyber768 | x25519+kyber768 | secp384r1+kyber768 | secp521r1+kyber1024 | secp256r1+kyber512 | x25519+kyber512 | +|-----------------------|--------------------|-----------------|--------------------|---------------------|--------------------|-----------------| +| default_pq / 20240730 | X | X | X | X | X | X | +| PQ-TLS-1-2-2023-12-15 | X | | X | X | X | | +| PQ-TLS-1-2-2023-12-14 | X | | X | X | X | | +| PQ-TLS-1-2-2023-12-13 | X | | X | X | X | | +| PQ-TLS-1-2-2023-10-10 | X | X | X | X | X | X | +| PQ-TLS-1-2-2023-10-09 | X | X | X | X | X | X | +| PQ-TLS-1-2-2023-10-08 | X | X | X | X | X | X | +| PQ-TLS-1-2-2023-10-07 | X | X | X | X | X | X | +| PQ-TLS-1-3-2023-06-01 | X | X | X | X | X | X | + +### Chart: Security Policy Version To Classic Key Exchange + +If the peer doesn't support a PQ hybrid key exchange method, s2n-tls will fall back to a classical option. + +| Version | secp256r1 | x25519 | secp384r1 | secp521r1 | DHE | RSA | +|-----------------------|-----------|--------|-----------|-----------|-----|-----| +| default_pq / 20240730 | X | X | X | X | | | +| PQ-TLS-1-2-2023-12-15 | X | | X | X | X | | +| PQ-TLS-1-2-2023-12-14 | X | | X | X | | | +| PQ-TLS-1-2-2023-12-13 | X | | X | X | | X | +| PQ-TLS-1-2-2023-10-10 | X | X | X | | X | X | +| PQ-TLS-1-2-2023-10-09 | X | X | X | | X | | +| PQ-TLS-1-2-2023-10-08 | X | X | X | | X | X | +| PQ-TLS-1-2-2023-10-07 | X | X | X | | | X | +| PQ-TLS-1-3-2023-06-01 | X | | X | X | X | X | + +### Chart: Security Policy Version To Ciphers + +| Version | AES-CBC | AES-GCM | CHACHAPOLY | 3DES | +|-----------------------|---------|---------|------------|------| +| default_pq / 20240730 | X | X | X | | +| PQ-TLS-1-2-2023-12-15 | X | X | | | +| PQ-TLS-1-2-2023-12-14 | X | X | | | +| PQ-TLS-1-2-2023-12-13 | X | X | | | +| PQ-TLS-1-2-2023-10-10 | X | X | X* | X | +| PQ-TLS-1-2-2023-10-09 | X | X | X* | X | +| PQ-TLS-1-2-2023-10-08 | X | X | X* | X | +| PQ-TLS-1-2-2023-10-07 | X | X | X* | | +| PQ-TLS-1-3-2023-06-01 | X | X | X* | X | +* only for TLS1.3 + +### Chart: Security Policy Version To Signature Schemes + +| Version | ECDSA | RSA | RSA-PSS | Legacy SHA1 | +|-----------------------|---------|-----|---------|-------------| +| default_pq / 20240730 | X | X | X | | +| PQ-TLS-1-2-2023-12-15 | X | X | X | | +| PQ-TLS-1-2-2023-12-14 | X | X | X | | +| PQ-TLS-1-2-2023-12-13 | X | X | X | | +| PQ-TLS-1-2-2023-10-10 | X | X | X | X | +| PQ-TLS-1-2-2023-10-09 | X | X | X | X | +| PQ-TLS-1-2-2023-10-08 | X | X | X | X | +| PQ-TLS-1-2-2023-10-07 | X | X | X | X | +| PQ-TLS-1-3-2023-06-01 | X | X | X | X | + +### Chart: Security Policy Version To TLS Protocol Version + +| Version | 1.2 | 1.3 | +|-----------------------|-----|-----| +| default_pq / 20240730 | X | X | +| PQ-TLS-1-2-2023-12-15 | X | X | +| PQ-TLS-1-2-2023-12-14 | X | X | +| PQ-TLS-1-2-2023-12-13 | X | X | +| PQ-TLS-1-2-2023-10-10 | X | X | +| PQ-TLS-1-2-2023-10-09 | X | X | +| PQ-TLS-1-2-2023-10-08 | X | X | +| PQ-TLS-1-2-2023-10-07 | X | X | +| PQ-TLS-1-3-2023-06-01 | X | X | + +#### Default Policy History +| Version | "default_pq" | +|------------|--------------| +| v1.4.19 | 20240730 | diff --git a/tests/unit/s2n_security_policies_test.c b/tests/unit/s2n_security_policies_test.c index 6f3e2b27ced..1672ca883e2 100644 --- a/tests/unit/s2n_security_policies_test.c +++ b/tests/unit/s2n_security_policies_test.c @@ -1090,5 +1090,27 @@ int main(int argc, char **argv) }; }; + /* Test that default_pq always matches default_tls13 */ + { + 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); + + /* If we ignore kem preferences, the two policies match */ + 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->signature_preferences, default_tls13->signature_preferences); + EXPECT_EQUAL(default_pq->certificate_signature_preferences, + default_tls13->certificate_signature_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); + }; + END_TEST(); } diff --git a/tls/s2n_security_policies.c b/tls/s2n_security_policies.c index c36515bd3c1..d6a833ab2f8 100644 --- a/tls/s2n_security_policies.c +++ b/tls/s2n_security_policies.c @@ -59,6 +59,19 @@ const struct s2n_security_policy security_policy_20240503 = { }, }; +/* PQ default as of 07/24 */ +const struct s2n_security_policy security_policy_20240730 = { + .minimum_protocol_version = S2N_TLS12, + .cipher_preferences = &cipher_preferences_cloudfront_tls_1_2_2019, + .kem_preferences = &kem_preferences_pq_tls_1_3_2023_06, + .signature_preferences = &s2n_signature_preferences_20240501, + .certificate_signature_preferences = &s2n_certificate_signature_preferences_20201110, + .ecc_preferences = &s2n_ecc_preferences_20240501, + .rules = { + [S2N_PERFECT_FORWARD_SECRECY] = true, + }, +}; + const struct s2n_security_policy security_policy_20240603 = { .minimum_protocol_version = S2N_TLS12, .cipher_preferences = &cipher_preferences_20240603, @@ -1124,6 +1137,7 @@ struct s2n_security_policy_selection security_policy_selection[] = { { .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 }, + { .version = "default_pq", .security_policy = &security_policy_20240730, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, { .version = "20240501", .security_policy = &security_policy_20240501, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, { .version = "20240502", .security_policy = &security_policy_20240502, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, { .version = "20240503", .security_policy = &security_policy_20240503, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, @@ -1131,6 +1145,7 @@ struct s2n_security_policy_selection security_policy_selection[] = { { .version = "20240331", .security_policy = &security_policy_20240331, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, { .version = "20240417", .security_policy = &security_policy_20240417, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, { .version = "20240416", .security_policy = &security_policy_20240416, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, + { .version = "20240730", .security_policy = &security_policy_20240730, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, { .version = "ELBSecurityPolicy-TLS-1-0-2015-04", .security_policy = &security_policy_elb_2015_04, .ecc_extension_required = 0, .pq_kem_extension_required = 0 }, /* Not a mistake. TLS-1-0-2015-05 and 2016-08 are equivalent */ { .version = "ELBSecurityPolicy-TLS-1-0-2015-05", .security_policy = &security_policy_elb_2016_08, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },