Skip to content

Commit

Permalink
docs: add pq to usage guide
Browse files Browse the repository at this point in the history
  • Loading branch information
@lrstewart
lrstewart committed Jul 31, 2024
1 parent f68135d commit 4365f57
Show file tree
Hide file tree
Showing 7 changed files with 152 additions and 0 deletions.
1 change: 1 addition & 0 deletions bin/s2nc.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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));
Expand Down
1 change: 1 addition & 0 deletions bin/s2nd.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);

Expand Down
5 changes: 5 additions & 0 deletions bindings/rust/s2n-tls/src/security.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
];
1 change: 1 addition & 0 deletions docs/usage-guide/topics/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
107 changes: 107 additions & 0 deletions docs/usage-guide/topics/ch15-post-quantum.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
22 changes: 22 additions & 0 deletions tests/unit/s2n_security_policies_test.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
15 changes: 15 additions & 0 deletions tls/s2n_security_policies.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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 },
Expand Down

0 comments on commit 4365f57

Please sign in to comment.