Merge branch 'main' into feat/update-fibs-policy

Author: johubertj

api/s2n.h

@@ -2650,6 +2650,7 @@ typedef enum {
     S2N_TLS_SIGNATURE_ANONYMOUS = 0,
     S2N_TLS_SIGNATURE_RSA = 1,
     S2N_TLS_SIGNATURE_ECDSA = 3,
+    S2N_TLS_SIGNATURE_MLDSA = 9,
 
     /* Use Private Range for RSA PSS since it's not defined there */
     S2N_TLS_SIGNATURE_RSA_PSS_RSAE = 224,
@@ -3482,6 +3483,9 @@ S2N_API extern int s2n_async_pkey_op_get_input_size(struct s2n_async_pkey_op *op
  *
  * When signing, the input is the digest to sign.
  * When decrypting, the input is the data to decrypt.
+ * 
+ * When signing with ML-DSA, the input is the "external mu" pre-hash value described in
+ * https://www.ietf.org/archive/id/draft-ietf-lamps-dilithium-certificates-09.html#appendix-D
  *
  * # Safety
  * * `data` must be sufficiently large to contain the input.

bin/echo.c

@@ -40,6 +40,7 @@ const char *sig_alg_strs[] = {
     [S2N_TLS_SIGNATURE_ECDSA] = "ECDSA",
     [S2N_TLS_SIGNATURE_RSA_PSS_RSAE] = "RSA-PSS-RSAE",
     [S2N_TLS_SIGNATURE_RSA_PSS_PSS] = "RSA-PSS-PSS",
+    [S2N_TLS_SIGNATURE_MLDSA] = "MLDSA",
 };
 
 const char *sig_hash_strs[] = {

bindings/rust/extended/s2n-tls/src/enums.rs

@@ -189,6 +189,7 @@ pub enum SignatureAlgorithm {
     RSA_PSS_RSAE,
     RSA_PSS_PSS,
     ECDSA,
+    MLDSA,
 }
 
 impl TryFrom<s2n_tls_signature_algorithm::Type> for SignatureAlgorithm {
@@ -200,6 +201,7 @@ impl TryFrom<s2n_tls_signature_algorithm::Type> for SignatureAlgorithm {
             s2n_tls_signature_algorithm::RSA_PSS_RSAE => Self::RSA_PSS_RSAE,
             s2n_tls_signature_algorithm::RSA_PSS_PSS => Self::RSA_PSS_PSS,
             s2n_tls_signature_algorithm::ECDSA => Self::ECDSA,
+            s2n_tls_signature_algorithm::MLDSA => Self::MLDSA,
             _ => return Err(Error::INVALID_INPUT),
         };
         Ok(version)

bindings/rust/standard/integration/Cargo.toml

@@ -16,7 +16,7 @@ no-network-tests = []
 
 # Not all libcryptos support PQ capabilities. Tests relying on PQ functionality
 # can be disabled by turning off this feature.
-pq = []
+pq = [ "s2n-tls/pq" ]
 
 [dependencies]
 s2n-tls = { path = "../../extended/s2n-tls", features = ["unstable-testing"]}
@@ -25,7 +25,9 @@ s2n-tls-tokio = { path = "../../extended/s2n-tls-tokio" }
 s2n-tls-sys = { path = "../../extended/s2n-tls-sys" }
 
 [dev-dependencies]
+openssl = { version = "0.10", features = ["vendored"] }
 tokio = { version = "1", features = ["macros", "test-util"] }
+tokio-openssl = { version = "0.6.5" }
 
 tracing = "0.1"
 tracing-subscriber = "0.3"
@@ -36,3 +38,10 @@ http-body-util = "0.1"
 bytes = "1.8"
 hyper = "1.5"
 hyper-util = "0.1"
+
+[build-dependencies]
+# The ML-DSA tests require the ML-DSA support added in Openssl-3.5
+# Since this overrides the dependency from the openssl-src crate,
+# the features are copied from the openssl-src crate's Cargo.toml:
+# https://github.com/sfackler/rust-openssl/blob/eb88fb0533c3593cc2fff6d03cf2befea8ecbe27/openssl-sys/Cargo.toml#L31
+openssl-src = { version = "300.5", optional = true, features = ["legacy"] }

bindings/rust/standard/integration/src/features/mldsa.rs

@@ -0,0 +1,102 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use openssl::ssl::{Ssl, SslContextBuilder, SslFiletype, SslMethod};
+use s2n_tls::{config::Config, enums::SignatureAlgorithm, security::DEFAULT_PQ};
+use s2n_tls_tokio::{TlsAcceptor, TlsConnector};
+use std::{fs, path::Path, pin::Pin};
+use tokio::net::{TcpListener, TcpStream};
+use tokio_openssl::SslStream;
+
+const TEST_PEMS_PATH: &'static str =
+    concat!(env!("CARGO_MANIFEST_DIR"), "/../../../../tests/pems/");
+
+pub async fn get_streams() -> Result<(TcpStream, TcpStream), tokio::io::Error> {
+    let localhost = "127.0.0.1".to_owned();
+    let listener = TcpListener::bind(format!("{}:0", localhost)).await?;
+    let addr = listener.local_addr()?;
+    let client_stream = TcpStream::connect(&addr).await?;
+    let (server_stream, _) = listener.accept().await?;
+    Ok((server_stream, client_stream))
+}
+
+#[test_log::test(tokio::test)]
+async fn s2n_client() -> Result<(), Box<dyn std::error::Error>> {
+    let cert_path = format!("{TEST_PEMS_PATH}mldsa/ML-DSA-87.crt");
+    let key_path = format!("{TEST_PEMS_PATH}mldsa/ML-DSA-87-seed.priv");
+
+    let (server_stream, client_stream) = get_streams().await?;
+
+    // Setup Openssl server with ML-DSA certs
+    let mut server = {
+        let mut builder = SslContextBuilder::new(SslMethod::tls())?;
+        builder.set_private_key_file(key_path, SslFiletype::PEM)?;
+        builder.set_certificate_chain_file(cert_path.clone())?;
+        let context = builder.build();
+        let ssl = Ssl::new(&context)?;
+        SslStream::new(ssl, server_stream)?
+    };
+
+    // Setup s2n-tls client with default_pq
+    let client = {
+        let mut config = Config::builder();
+        config.set_security_policy(&DEFAULT_PQ)?;
+        config.trust_location(Some(Path::new(&cert_path)), None)?;
+        TlsConnector::new(config.build()?)
+    };
+
+    let server_pin = Pin::new(&mut server);
+    let (_, client_result) = tokio::join!(
+        server_pin.accept(),
+        // The test certs are copied from the original RFC,
+        // so s2n-tls expects "LAMPS-WG" as the server name. See:
+        // https://github.com/lamps-wg/dilithium-certificates/blob/5b23428b08a53aacdb89d93422b81228433e34d8/examples/ML-DSA-87.crt.txt#L40-L42
+        client.connect("LAMPS WG", client_stream),
+    );
+
+    let client = client_result?;
+    let conn = client.as_ref();
+    assert_eq!(
+        conn.selected_signature_algorithm()?,
+        SignatureAlgorithm::MLDSA
+    );
+    Ok(())
+}
+
+#[test_log::test(tokio::test)]
+async fn s2n_server() -> Result<(), Box<dyn std::error::Error>> {
+    let cert_path = format!("{TEST_PEMS_PATH}mldsa/ML-DSA-87.crt");
+    let key_path = format!("{TEST_PEMS_PATH}mldsa/ML-DSA-87-seed.priv");
+
+    let (server_stream, client_stream) = get_streams().await?;
+
+    // Setup Openssl client
+    let mut client = {
+        let mut builder = SslContextBuilder::new(SslMethod::tls())?;
+        builder.set_ca_file(Path::new(&cert_path))?;
+        let context = builder.build();
+        let ssl = Ssl::new(&context)?;
+        SslStream::new(ssl, client_stream)?
+    };
+
+    // Setup s2n-tls server with ML-DSA certs
+    let server = {
+        let mut config = Config::builder();
+        config.set_security_policy(&DEFAULT_PQ)?;
+        let cert = fs::read(cert_path)?;
+        let key = fs::read(key_path)?;
+        config.load_pem(&cert, &key)?;
+        TlsAcceptor::new(config.build()?)
+    };
+
+    let client_pin = Pin::new(&mut client);
+    let (server_result, _) = tokio::join!(server.accept(server_stream), client_pin.connect(),);
+
+    let server = server_result?;
+    let conn = server.as_ref();
+    assert_eq!(
+        conn.selected_signature_algorithm()?,
+        SignatureAlgorithm::MLDSA
+    );
+    Ok(())
+}

bindings/rust/standard/integration/src/features/mod.rs

@@ -0,0 +1,5 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#[cfg(feature = "pq")]
+mod mldsa;

bindings/rust/standard/integration/src/lib.rs

@@ -1,6 +1,8 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+#[cfg(test)]
+mod features;
 #[cfg(all(not(feature = "no-network-tests"), test))]
 mod network;
 

docs/usage-guide/topics/ch15-post-quantum.md

@@ -1,16 +1,26 @@
 # 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
+s2n-tls supports both post-quantum key exchange and post-quantum authentication for TLS1.3.
 
-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.
+## Key Exchange: ML-KEM / Kyber
+
+Currently, only [ML-KEM](https://csrc.nist.gov/pubs/fips/203) / [Kyber](https://pq-crystals.org/kyber/) are supported for post-quantum key exchange. "ML-KEM" is the name given to the NIST standardized version of Kyber.
+
+Specifically, s2n-tls supports hybrid key exchange. PQ hybrid key exchange involves performing both classic ECDH key exchange and post-quantum 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: An s2n-tls server that enables post-quantum cryptography will mandate post-quantum key exchange with any client advertising post-quantum algorithms. This can result in a retry and an extra round trip if the client does not initially send a post-quantum key share. The rational behind this behavior is that post-quantum users prioritize security over the potential cost of an extra round trip.
 
+## Authentication: ML-DSA
+
+Currently, only [ML-DSA](https://csrc.nist.gov/pubs/fips/204) is supported for post-quantum authentication.
+
+In order to use ML-DSA, you must configure s2n-tls to use an ML-DSA certificate, just as you would configure an RSA or ECDSA certificate. See [certificates](./ch09-certificates.md).
+
 ## 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.
+s2n-tls must be built with aws-lc to use post-quantum algorithms. 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. For ML-DSA, you will need to use a version of AWS-LC >= v1.50.0 (API version 33).
 
 If you're unsure what cryptography library s2n-tls is built against, trying running s2nd or s2nc:
 ```
@@ -21,17 +31,18 @@ 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. 
+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 "20240730". For previous defaults, see the "Default Policy History" section below.
+"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 "20250512". 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        |
+| default_pq / 20250512 |          X         |         X       |         X          |          X          |         X          |        X        |
+| 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          |                 |
@@ -41,13 +52,29 @@ Other available PQ policies are compared in the tables below.
 | 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 Signature Schemes
+
+|        Version        | ML-DSA | ECDSA | RSA | RSA-PSS | Legacy SHA1 |
+|-----------------------|--------|-------|-----|---------|-------------|
+| default_pq / 20250512 |   X    |   X   |  X  |    X    |             |
+| 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 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     |     |     |
+| default_pq / 20250512 |     X     |   X    |     X     |     X     |     |     |
+| 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  |
@@ -61,7 +88,8 @@ If the peer doesn't support a PQ hybrid key exchange method, s2n-tls will fall b
 
 |        Version        | AES-CBC | AES-GCM | CHACHAPOLY | 3DES |
 |-----------------------|---------|---------|------------|------|
-| default_pq / 20240730 |    X    |    X    |     X      |      |
+| default_pq / 20250512 |    X    |    X    |     X      |      |
+| 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    |            |      |
@@ -72,25 +100,12 @@ If the peer doesn't support a PQ hybrid key exchange method, s2n-tls will fall b
 | 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  |
+| default_pq / 20250512 |  X  |  X  |
+| 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  |
@@ -103,7 +118,8 @@ If the peer doesn't support a PQ hybrid key exchange method, s2n-tls will fall b
 #### Default Policy History
 |  Version   | "default_pq" |
 |------------|--------------|
-|  v1.5.0   |   20240730   |
+|  v1.5.19   |   20250512   |
+|  v1.5.0    |   20240730   |
 
 ## Visibility
 Call `s2n_connection_get_kem_group_name` to determine if a TLS handshake negotiated PQ key exchange.

tests/unit/s2n_connection_test.c

@@ -302,6 +302,7 @@ int main(int argc, char **argv)
             [S2N_SIGNATURE_ECDSA] = S2N_TLS_SIGNATURE_ECDSA,
             [S2N_SIGNATURE_RSA_PSS_RSAE] = S2N_TLS_SIGNATURE_RSA_PSS_RSAE,
             [S2N_SIGNATURE_RSA_PSS_PSS] = S2N_TLS_SIGNATURE_RSA_PSS_PSS,
+            [S2N_SIGNATURE_MLDSA] = S2N_TLS_SIGNATURE_MLDSA,
         };
 
         for (size_t i = 0; i <= UINT16_MAX; i++) {