diff --git a/bin/s2nc.c b/bin/s2nc.c index 1c7421d2df4..39ac7b1dd54 100644 --- a/bin/s2nc.c +++ b/bin/s2nc.c @@ -563,6 +563,9 @@ int main(int argc, char *const *argv) } GUARD_EXIT(s2n_init(), "Error running s2n_init()"); +#if defined(SSLeay_version) && defined(SSLEAY_VERSION) + printf("libcrypto: %s\n", SSLeay_version(SSLEAY_VERSION)); +#endif 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..aadc0525d53 100644 --- a/bin/s2nd.c +++ b/bin/s2nd.c @@ -562,6 +562,9 @@ int main(int argc, char *const *argv) } GUARD_EXIT(s2n_init(), "Error running s2n_init()"); +#if defined(SSLeay_version) && defined(SSLEAY_VERSION) + printf("libcrypto: %s\n", SSLeay_version(SSLEAY_VERSION)); +#endif 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/BUILD.md b/docs/BUILD.md index a47ccc681d8..7c2640411ae 100644 --- a/docs/BUILD.md +++ b/docs/BUILD.md @@ -68,6 +68,10 @@ cmake --install build Note that we currently do not support building on Windows. See https://github.com/aws/s2n-tls/issues/497 for more information. +Using the commands above, the libraries and headers will be located in the `s2n-tls-install` directory. + +The s2nc and s2nd test utilities are not installed by default, but can be found in the `build/bin` directory. To also install s2nc and s2nd, add `-DS2N_INSTALL_S2NC_S2ND=1` to the cmake command. + ## Consuming s2n-tls via CMake s2n-tls ships with modern CMake finder scripts if CMake is used for the build. To take advantage of this from your CMake script, all you need to do to compile and link against s2n-tls in your project is: 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..b74129d9f22 --- /dev/null +++ b/docs/usage-guide/topics/ch15-post-quantum.md @@ -0,0 +1,106 @@ +# Post Quantum (PQ) Support + +s2n-tls supports post-quantum key exchange for TLS1.3. Currently, only [Kyber](https://pq-crystals.org/kyber/) is supported. See the draft IETF standard: https://datatracker.ietf.org/doc/html/draft-ietf-tls-hybrid-design + +Specifically, s2n-tls supports hybrid key exchange. PQ hybrid key exchange involves performing both classic ECDH key exchange and post-quantum Kyber key exchange, then combining the two resultant secrets. This strategy combines the high assurance of the classical key exchange algorithms with the quantum-resistance of the new post-quantum key exchange algorithms. If one of the two algorithms is compromised, either because advances in quantum computing make the classic algorithms insecure or because cryptographers find a flaw in the relatively new post-quantum algorithms, the secret is still secure. Hybrid post-quantum key exchange is more secure than standard key exchange, but is slower and requires more processing and more network bandwidth. + +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 +``` + +### 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 },