docs: add pq to usage guide (#4677)

lrstewart · web-flow · commit 6578f88c394d · 2024-08-09T22:20:30.000-07:00
diff --git a/bin/s2nc.c b/bin/s2nc.c
@@ -33,6 +33,7 @@
 #include "api/unstable/npn.h"
 #include "api/unstable/renegotiate.h"
 #include "common.h"
+#include "crypto/s2n_libcrypto.h"
 #include "error/s2n_errno.h"
 #include "tls/s2n_connection.h"
 
@@ -591,6 +592,7 @@ int main(int argc, char *const *argv)
     }
 
     GUARD_EXIT(s2n_init(), "Error running s2n_init()");
+    printf("libcrypto: %s\n", s2n_libcrypto_get_version_name());
 
     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
@@ -34,6 +34,7 @@
 #include "api/s2n.h"
 #include "api/unstable/npn.h"
 #include "common.h"
+#include "crypto/s2n_libcrypto.h"
 #include "utils/s2n_safety.h"
 
 #define MAX_CERTIFICATES 50
@@ -565,6 +566,7 @@ int main(int argc, char *const *argv)
     }
 
     GUARD_EXIT(s2n_init(), "Error running s2n_init()");
+    printf("libcrypto: %s\n", s2n_libcrypto_get_version_name());
 
     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
@@ -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/crypto/s2n_libcrypto.c b/crypto/s2n_libcrypto.c
@@ -55,7 +55,7 @@
  * symbol OpenSSL_version binded to at link-time. This can be used as
  * verification at run-time that s2n linked against the expected libcrypto.
  */
-static const char *s2n_libcrypto_get_version_name(void)
+const char *s2n_libcrypto_get_version_name(void)
 {
     return SSLeay_version(SSLEAY_VERSION);
 }
diff --git a/crypto/s2n_libcrypto.h b/crypto/s2n_libcrypto.h
@@ -18,5 +18,5 @@
 #include "utils/s2n_result.h"
 
 S2N_RESULT s2n_libcrypto_validate_runtime(void);
-
+const char *s2n_libcrypto_get_version_name(void);
 bool s2n_libcrypto_supports_flag_no_check_time();
diff --git 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
@@ -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
@@ -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.5.0   |   20240730   |
diff --git 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
@@ -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,13 +1137,15 @@ 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 },
     { .version = "20230317", .security_policy = &security_policy_20230317, .ecc_extension_required = 0, .pq_kem_extension_required = 0 },
     { .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 },

Original file line number	Diff line number	Diff line change
`@@ -55,7 +55,7 @@`
`55`	`55`	`* symbol OpenSSL_version binded to at link-time. This can be used as`
`56`	`56`	`* verification at run-time that s2n linked against the expected libcrypto.`
`57`	`57`	`*/`
`58`		`-static const char *s2n_libcrypto_get_version_name(void)`
	`58`	`+const char *s2n_libcrypto_get_version_name(void)`
`59`	`59`	`{`
`60`	`60`	`return SSLeay_version(SSLEAY_VERSION);`
`61`	`61`	`}`