Merge branch 'main' into entropy-invalid-fd

.github/s2n_osx.sh

@@ -28,3 +28,12 @@ cmake . -Bbuild -GNinja \
 
 cmake --build ./build -j $(nproc)
 time CTEST_PARALLEL_LEVEL=$(nproc) ninja -C build test
+
+# Build shared library
+cmake . -Bbuild -GNinja \
+-DCMAKE_BUILD_TYPE=Debug \
+-DCMAKE_PREFIX_PATH=${OPENSSL_1_1_1_INSTALL_DIR} .. \
+-DBUILD_SHARED_LIBS=ON
+
+cmake --build ./build -j $(nproc)
+time CTEST_PARALLEL_LEVEL=$(nproc) ninja -C build test

.github/workflows/usage_guide.yml

@@ -0,0 +1,73 @@
+name: Publish Usage Guide
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  CDN: https://d3fqnyekunr9xg.cloudfront.net
+
+# By default dependabot only receives read permissions. Explicitly give it write
+# permissions which is needed by the ouzi-dev/commit-status-updater task.
+#
+# Updating status is relatively safe (doesnt modify source code) and caution
+# should be taken before adding more permissions.
+permissions:
+  contents: write
+  statuses: write
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout s2n-tls repo
+        uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Set override
+        run: rustup override set stable
+
+      - uses: camshaft/install@v1
+        with:
+          crate: mdbook
+
+      - name: Build book
+        run: |
+          cd docs/usage-guide
+          mdbook build
+      
+      - name: Deploy documentation to gh-pages
+        uses: JamesIves/[email protected]
+        if: github.event_name == 'push'
+        with:
+          target-folder: usage-guide
+          folder: docs/usage-guide/book
+
+      - name: Configure AWS credentials
+        uses: aws-actions/[email protected]
+        if: github.event_name == 'push' || github.repository == github.event.pull_request.head.repo.full_name
+        with:
+          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          aws-region: us-west-1
+
+      - name: Upload to S3
+        if: github.event_name == 'push' || github.repository == github.event.pull_request.head.repo.full_name
+        id: s3
+        run: |
+          TARGET="${{ github.sha }}/book"
+          aws s3 sync docs/usage-guide/book "s3://s2n-tls-ci-artifacts/$TARGET" --acl private --follow-symlinks
+          URL="$CDN/$TARGET/index.html"
+          echo "URL=$URL" >> $GITHUB_OUTPUT
+      
+      - name: Output mdbook url 
+        uses: ouzi-dev/[email protected]
+        if: github.event_name == 'push' || github.repository == github.event.pull_request.head.repo.full_name
+        with:
+          name: "book / url"
+          status: "success"
+          url: "${{ steps.s3.outputs.URL }}"

README.md

@@ -44,7 +44,7 @@ If you have any questions about submitting PRs, s2n-tls API usage, or something
 
 ## Documentation
 
-s2n-tls uses [Doxygen](https://doxygen.nl/index.html) to document its public API. The latest s2n-tls documentation can be found on [GitHub pages](https://aws.github.io/s2n-tls/doxygen/). The [Usage Guide](docs/usage-guide/) explains how different TLS features can be configured and used.
+s2n-tls uses [Doxygen](https://doxygen.nl/index.html) to document its public API. The latest s2n-tls documentation can be found on [GitHub pages](https://aws.github.io/s2n-tls/doxygen/). The [Usage Guide](https://aws.github.io/s2n-tls/usage-guide/) explains how different TLS features can be configured and used.
 
 Documentation for older versions or branches of s2n-tls can be generated locally. To generate the documentation, install doxygen and run `doxygen docs/doxygen/Doxyfile`. The doxygen documentation can now be found at `docs/doxygen/output/html/index.html`.
 
@@ -77,7 +77,7 @@ int bytes_written;
 bytes_written = s2n_send(conn, "Hello World", sizeof("Hello World"), &blocked);
 ```
 
-For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [usage guide][Usage Guide](docs/usage-guide).
+For details on building the s2n-tls library and how to use s2n-tls in an application you are developing, see the [Usage Guide](https://aws.github.io/s2n-tls/usage-guide).
 
 ## s2n-tls features
 

api/s2n.h

@@ -1393,6 +1393,35 @@ struct s2n_client_hello;
  */
 S2N_API extern struct s2n_client_hello *s2n_connection_get_client_hello(struct s2n_connection *conn);
 
+/**
+ * Creates an s2n_client_hello from bytes representing a ClientHello message.
+ *
+ * The input bytes should include the message header (message type and length),
+ * but not the record header.
+ *
+ * Unlike s2n_connection_get_client_hello, the s2n_client_hello returned by this
+ * method is owned by the application and must be freed with s2n_client_hello_free.
+ *
+ * This method does not support SSLv2 ClientHellos.
+ *
+ * @param bytes The raw bytes representing the ClientHello.
+ * @param size The size of raw_message.
+ * @returns A new s2n_client_hello on success, or NULL on failure.
+ */
+S2N_API extern struct s2n_client_hello *s2n_client_hello_parse_message(const uint8_t *bytes, uint32_t size);
+
+/**
+ * Frees an s2n_client_hello structure.
+ *
+ * This method should be called to free s2n_client_hellos returned by
+ * s2n_client_hello_parse_message. It will error if passed an s2n_client_hello
+ * returned by s2n_connection_get_client_hello and owned by the connection.
+ *
+ * @param ch The structure to be freed.
+ * @returns S2N_SUCCESS on success, S2N_FAILURE on failure.
+ */
+S2N_API extern int s2n_client_hello_free(struct s2n_client_hello **ch);
+
 /**
  * Function to determine the size of the raw Client Hello buffer. 
  *

api/unstable/fingerprint.h

@@ -74,29 +74,3 @@ S2N_API int s2n_client_hello_get_fingerprint_hash(struct s2n_client_hello *ch,
 S2N_API int s2n_client_hello_get_fingerprint_string(struct s2n_client_hello *ch,
         s2n_fingerprint_type type, uint32_t max_size,
         uint8_t *output, uint32_t *output_size);
-
-/**
- * Creates an s2n_client_hello from bytes representing a ClientHello message.
- *
- * Unlike s2n_connection_get_client_hello, the s2n_client_hello returned by this
- * method is owned by the application and must be freed with s2n_client_hello_free.
- *
- * This method does not support SSLv2 ClientHellos.
- *
- * @param bytes The raw bytes representing the ClientHello.
- * @param size The size of raw_message.
- * @returns A new s2n_client_hello on success, or NULL on failure.
- */
-S2N_API struct s2n_client_hello *s2n_client_hello_parse_message(const uint8_t *bytes, uint32_t size);
-
-/**
- * Frees an s2n_client_hello structure.
- *
- * This method should be called to free s2n_client_hellos returned by
- * s2n_client_hello_parse_message. It will error if passed an s2n_client_hello
- * returned by s2n_connection_get_client_hello and owned by the connection.
- *
- * @param ch The structure to be freed.
- * @returns S2N_SUCCESS on success, S2N_FAILURE on failure.
- */
-S2N_API int s2n_client_hello_free(struct s2n_client_hello **ch);

api/unstable/ktls.h

@@ -44,7 +44,8 @@
  * Enables sending using kTLS on a given connection.
  *
  * See above for the limitations on when kTLS can be enabled. Additionally,
- * s2n_connection_ktls_enable_send must be called after the handshake completes.
+ * s2n_connection_ktls_enable_send must be called after the handshake completes
+ * but before the handshake is freed with s2n_connection_free_handshake.
  * It may be called after some application data is sent and received without kTLS,
  * but there must be no pending application data that requires flushing. If these
  * requirements are not met, enabling kTLS will fail with an error.
@@ -74,7 +75,8 @@ S2N_API int s2n_connection_ktls_enable_send(struct s2n_connection *conn);
  * Enables receiving using kTLS on a given connection.
  *
  * See above for the limitations on when kTLS can be enabled. Additionally,
- * s2n_connection_ktls_enable_recv must be called after the handshake completes.
+ * s2n_connection_ktls_enable_recv must be called after the handshake completes
+ * but before the handshake is freed with s2n_connection_free_handshake.
  * It may be called after some application data is sent and received without kTLS,
  * but there must be no buffered application data that requires draining. If these
  * requirements are not met, enabling kTLS will fail with an error.
@@ -100,6 +102,8 @@ S2N_API int s2n_connection_ktls_enable_recv(struct s2n_connection *conn);
  *
  * Enabling TLS1.3 with this method is considered "unsafe" because the kernel
  * currently doesn't support updating encryption keys, which is required in TLS1.3.
+ * s2n_connection_get_key_update_counts can be used to gather metrics on whether
+ * key updates are occurring on your connections before enabling TLS1.3.
  *
  * In order to safely enable TLS1.3, an application must ensure that its peer will
  * not send any KeyUpdate messages. If s2n-tls receives a KeyUpdate message while
@@ -117,6 +121,22 @@ S2N_API int s2n_connection_ktls_enable_recv(struct s2n_connection *conn);
  */
 S2N_API int s2n_config_ktls_enable_unsafe_tls13(struct s2n_config *config);
 
+/**
+ * Reports the number of times sending and receiving keys have been updated.
+ *
+ * This only applies to TLS1.3. Earlier versions do not support key updates.
+ *
+ * @warning s2n-tls only tracks up to UINT8_MAX (255) key updates. If this method
+ * reports 255 updates, then more than 255 updates may have occurred.
+ *
+ * @param conn A pointer to the connection.
+ * @param send_key_updates Number of times the sending key was updated.
+ * @param recv_key_updates Number of times the receiving key was updated.
+ * @returns S2N_SUCCESS if successful, S2N_FAILURE otherwise.
+ */
+S2N_API int s2n_connection_get_key_update_counts(struct s2n_connection *conn,
+        uint8_t *send_key_updates, uint8_t *recv_key_updates);
+
 /**
  * Sends the contents of a file as application data.
  *

bindings/rust/s2n-tls-sys/build.rs

@@ -8,17 +8,6 @@ fn main() {
     if external.is_enabled() {
         external.link();
     } else {
-        #[cfg(feature = "cmake")]
-        {
-            // branch on a runtime value so we don't get unused code warnings
-            if option_env("CARGO_FEATURE_CMAKE").is_some() {
-                build_cmake();
-            } else {
-                build_vendored();
-            }
-        }
-
-        #[cfg(not(feature = "cmake"))]
         build_vendored();
     }
 }
@@ -93,26 +82,7 @@ fn build_vendored() {
 
     let mut build = builder(&libcrypto);
 
-    // TODO: update rust bindings to handle no pq-crypto dir
-
-    let pq = option_env("CARGO_FEATURE_PQ").is_some();
-
-    // TODO each pq section needs to be built separately since it
-    //      has its own relative include paths
-    assert!(!pq, "pq builds are not currently supported without cmake");
-
-    build.files(include!("./files.rs").iter().copied().filter(|file| {
-        // the pq entry file is still needed
-        if *file == "lib/pq-crypto/s2n_pq.c" {
-            return true;
-        }
-
-        if file.starts_with("lib/pq-crypto/") {
-            return pq;
-        }
-
-        true
-    }));
+    build.files(include!("./files.rs"));
 
     if env("PROFILE") == "release" {
         // fortify source is only available in release mode
@@ -127,10 +97,6 @@ fn build_vendored() {
         }
     }
 
-    if !pq {
-        build.define("S2N_NO_PQ", "1");
-    }
-
     let out_dir = PathBuf::from(env("OUT_DIR"));
 
     let features = FeatureDetector::new(&out_dir, &libcrypto);
@@ -214,49 +180,6 @@ fn builder(libcrypto: &Libcrypto) -> cc::Build {
     build
 }
 
-#[cfg(feature = "cmake")]
-fn build_cmake() {
-    let mut config = cmake::Config::new("lib");
-
-    let libcrypto = Libcrypto::default();
-
-    config
-        .register_dep(&format!("aws_lc_{}", libcrypto.version))
-        .configure_arg("-DBUILD_TESTING=off");
-
-    if option_env("CARGO_FEATURE_PQ").is_none() {
-        config.configure_arg("-DS2N_NO_PQ=on");
-    }
-
-    let dst = config.build();
-
-    let lib = search(dst.join("lib64"))
-        .or_else(|| search(dst.join("lib")))
-        .or_else(|| search(dst.join("build").join("lib")))
-        .expect("could not build libs2n");
-
-    // link the built artifact
-    if lib.join("libs2n.a").exists() {
-        println!("cargo:rustc-link-lib=static=s2n");
-    } else {
-        println!("cargo:rustc-link-lib=s2n");
-    }
-
-    println!("cargo:include={}", dst.join("include").display());
-
-    // tell rust we're linking with libcrypto
-    println!("cargo:rustc-link-lib={}", libcrypto.link);
-
-    fn search(path: PathBuf) -> Option<PathBuf> {
-        if path.exists() {
-            println!("cargo:rustc-link-search={}", path.display());
-            Some(path)
-        } else {
-            None
-        }
-    }
-}
-
 #[derive(PartialEq, Eq, PartialOrd, Ord)]
 struct Libcrypto {
     version: String,

bindings/rust/s2n-tls-sys/templates/Cargo.template

@@ -24,8 +24,10 @@ include = [
 
 [features]
 default = []
+# preserve the cmake feature in case any consumers had it enabled before
+cmake = []
 quic = []
-pq = ["cmake"] # the pq build logic is complicated so just use cmake instead
+pq = []
 internal = []
 stacktrace = []
 <TOKEN_REPLACED_WITH_UNSTABLE_FEATURES>
@@ -38,7 +40,6 @@ libc = "0.2"
 
 [build-dependencies]
 cc = { version = "1.0", features = ["parallel"] }
-cmake = { version = "0.1", optional = true }
 
 [dev-dependencies]
 jobserver = "=0.1.26" # newer versions require rust 1.66, see https://github.com/aws/s2n-tls/issues/4241