KEM: Key-Encapsulation Mechanisms API Support

.github/workflows/ci.yml

@@ -179,10 +179,10 @@ jobs:
       - name: Cross-compilation
         if: ${{ matrix.target == 'aarch64-unknown-linux-gnu' || matrix.target == 'i686-unknown-linux-gnu' }}
         working-directory: ./aws-lc-rs
-        run: cross test --target ${{ matrix.target }}
+        run: cross test --features unstable --target ${{ matrix.target }}
       - name: Cross-compilation w/ bindgen
         working-directory: ./aws-lc-rs
-        run: cross test --release --features bindgen --target ${{ matrix.target }}
+        run: cross test --release --features bindgen,unstable --target ${{ matrix.target }}
 
   aws-lc-rs-platform-build:
     name: Cross-platform build
@@ -205,7 +205,7 @@ jobs:
           target: ${{ matrix.target }}
       - name: Run cargo test
         working-directory: ./aws-lc-rs
-        run: cargo test --features bindgen --target ${{ matrix.target }}
+        run: cargo test --features bindgen,unstable --target ${{ matrix.target }}
         env:
           DYLD_ROOT_PATH: "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS.simruntime/Contents/Resources/RuntimeRoot"
 
@@ -242,12 +242,16 @@ jobs:
         rust: [ stable ]
         os: [ ubuntu-latest, macos-12, macos-13-xlarge ]
         args:
-          - --all-targets
-          - --release --all-targets
-          - --no-default-features --features non-fips
-          - --no-default-features --features non-fips,ring-io
-          - --no-default-features --features non-fips,ring-sig-verify
-          - --no-default-features --features non-fips,alloc
+          - --all-targets --features unstable
+          - --release --all-targets --features unstable
+          - --no-default-features --features non-fips,unstable
+          - --no-default-features --features non-fips,ring-io,unstable
+          - --no-default-features --features non-fips,ring-sig-verify,unstable
+          - --no-default-features --features non-fips,alloc,unstable
+          - --no-default-features --features non-fips,bindgen,unstable
+        include:
+          - args: --no-default-features --features non-fips,bindgen,unstable
+            envs: AWS_LC_RUST_PRIVATE_INTERNALS=1
     steps:
       - uses: actions/checkout@v3
         with:
@@ -260,6 +264,10 @@ jobs:
       - name: Run cargo test
         working-directory: ./aws-lc-rs
         run: cargo test ${{ matrix.args }}
+      - name: Run cargo test w/ environment
+        if: ${{ matrix.envs }}
+        working-directory: ./aws-lc-rs
+        run: env ${{ matrix.envs }} cargo test ${{ matrix.args }}
       - name: Run extra tests
         working-directory: ./aws-lc-rs-testing
         run: cargo test --all-targets
@@ -276,12 +284,15 @@ jobs:
         rust: [ stable ]
         os: [ ubuntu-latest, macos-12, macos-13-xlarge ]
         args:
-          - --release --all-targets --features fips
-          - --no-default-features --features fips
-          - --no-default-features --features fips,ring-io
-          - --no-default-features --features fips,ring-sig-verify
-          - --no-default-features --features fips,alloc
-          - --no-default-features --features fips,bindgen
+          - --release --all-targets --features fips,unstable
+          - --no-default-features --features fips,unstable
+          - --no-default-features --features fips,ring-io,unstable
+          - --no-default-features --features fips,ring-sig-verify,unstable
+          - --no-default-features --features fips,alloc,unstable
+          - --no-default-features --features fips,bindgen,unstable
+        include:
+          - args: --no-default-features --features fips,bindgen,unstable
+            envs: AWS_LC_RUST_PRIVATE_INTERNALS=1
     steps:
       - uses: actions/checkout@v3
         with:
@@ -299,6 +310,10 @@ jobs:
         # Doc-tests fail to link with dynamic build
         # See: https://github.com/rust-lang/cargo/issues/8531
         run: cargo test --tests ${{ matrix.args }}
+      - name: Run cargo test w/ environment
+        working-directory: ./aws-lc-rs
+        if: ${{ matrix.envs }}
+        run: env ${{ matrix.envs }} cargo test --tests ${{ matrix.args }}
 
   bindgen-test:
     name: aws-lc-rs bindgen-tests
@@ -309,8 +324,8 @@ jobs:
         rust: [ stable ]
         os: [ ubuntu-latest, macos-12, macos-13-xlarge ]
         args:
-          - --no-default-features --features aws-lc-sys,bindgen
-          - --release --all-targets --features bindgen
+          - --no-default-features --features aws-lc-sys,bindgen,unstable
+          - --release --all-targets --features bindgen,unstable
     steps:
       - uses: actions/checkout@v3
         with:
@@ -333,13 +348,13 @@ jobs:
         rust: [ stable ]
         os: [ windows-2019 ]
         args:
-          - --all-targets
-          - --all-targets --features bindgen
-          - --release --all-targets
-          - --no-default-features --features non-fips
-          - --no-default-features --features non-fips,ring-io
-          - --no-default-features --features non-fips,ring-sig-verify
-          - --no-default-features --features non-fips,alloc
+          - --all-targets --features unstable
+          - --all-targets --features bindgen,unstable
+          - --release --all-targets --features unstable
+          - --no-default-features --features non-fips,unstable
+          - --no-default-features --features non-fips,ring-io,unstable
+          - --no-default-features --features non-fips,ring-sig-verify,unstable
+          - --no-default-features --features non-fips,alloc,unstable
     steps:
       - uses: ilammy/setup-nasm@v1
       - uses: actions/checkout@v3
@@ -414,7 +429,7 @@ jobs:
 
       - name: Run coverage
         working-directory: ./aws-lc-rs
-        run: cargo llvm-cov --workspace --no-fail-fast --ignore-filename-regex "aws-lc-(fips-)?sys/.*" --lcov --output-path ${{ runner.temp }}/lcov.info
+        run: cargo llvm-cov --workspace --features unstable --no-fail-fast --ignore-filename-regex "aws-lc-(fips-)?sys/.*" --lcov --output-path ${{ runner.temp }}/lcov.info
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v3
         env:

aws-lc-fips-sys/builder/bindgen.rs

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0 OR ISC
 
 use crate::{
-    get_aws_lc_fips_sys_includes_path, get_aws_lc_include_path, get_generated_include_path,
-    get_rust_include_path,
+    get_aws_lc_fips_sys_includes_path, get_aws_lc_include_path, get_aws_lc_rand_extra_path,
+    get_generated_include_path, get_rust_include_path, is_private_api_enabled,
 };
 use bindgen::callbacks::{ItemInfo, ParseCallbacks};
 use std::fmt::Debug;
@@ -59,6 +59,15 @@ fn prepare_clang_args(manifest_dir: &Path) -> Vec<String> {
         get_aws_lc_include_path(manifest_dir).display().to_string(),
     );
 
+    if is_private_api_enabled() {
+        clang_args.push("-I".to_string());
+        clang_args.push(
+            get_aws_lc_rand_extra_path(manifest_dir)
+                .display()
+                .to_string(),
+        );
+    }
+
     if let Some(include_paths) = get_aws_lc_fips_sys_includes_path() {
         for path in include_paths {
             add_header_include_path(&mut clang_args, path.display().to_string());
@@ -136,6 +145,12 @@ fn prepare_bindings_builder(manifest_dir: &Path, options: &BindingOptions<'_>) -
         builder = builder.clang_arg("-DAWS_LC_RUST_INCLUDE_SSL");
     }
 
+    if is_private_api_enabled() {
+        builder = builder
+            .clang_arg("-DAWS_LC_RUST_PRIVATE_INTERNALS")
+            .allowlist_file(r".*(/|\\)pq_custom_randombytes\.h");
+    }
+
     builder = builder.parse_callbacks(Box::new(StripPrefixCallback::new(options.build_prefix)));
 
     builder

aws-lc-fips-sys/builder/main.rs

@@ -23,6 +23,13 @@ pub(crate) fn get_aws_lc_include_path(manifest_dir: &Path) -> PathBuf {
     manifest_dir.join("aws-lc").join("include")
 }
 
+pub(crate) fn get_aws_lc_rand_extra_path(manifest_dir: &Path) -> PathBuf {
+    manifest_dir
+        .join("aws-lc")
+        .join("crypto")
+        .join("rand_extra")
+}
+
 pub(crate) fn get_rust_include_path(manifest_dir: &Path) -> PathBuf {
     manifest_dir.join("include")
 }
@@ -161,7 +168,7 @@ fn prepare_cmake_build(manifest_dir: &PathBuf, build_prefix: String) -> cmake::C
         cmake_cfg.define("BUILD_SHARED_LIBS", "0");
     }
 
-    let opt_level = env::var("OPT_LEVEL").unwrap_or_else(|_| "0".to_string());
+    let opt_level = get_env_flag("OPT_LEVEL", "0");
     if opt_level.ne("0") {
         if opt_level.eq("1") || opt_level.eq("2") {
             cmake_cfg.define("CMAKE_BUILD_TYPE", "relwithdebinfo");
@@ -295,9 +302,12 @@ fn main() {
 
     let mut is_bindgen_required = cfg!(feature = "bindgen");
 
-    let is_internal_generate = env::var("AWS_LC_RUST_INTERNAL_BINDGEN")
-        .unwrap_or_else(|_| String::from("0"))
-        .eq("1");
+    let is_internal_generate = is_internal_generate_enabled();
+
+    assert!(
+        !(is_internal_generate && is_private_api_enabled()),
+        "AWS_LC_RUST_PRIVATE_INTERNALS=1 is not supported when AWS_LC_RUST_INTERNAL_BINDGEN=1"
+    );
 
     let pregenerated = !is_bindgen_required || is_internal_generate;
 
@@ -413,6 +423,10 @@ fn setup_include_paths(out_dir: &Path, manifest_dir: &Path) -> PathBuf {
         get_aws_lc_include_path(manifest_dir),
     ];
 
+    if is_private_api_enabled() {
+        include_paths.push(get_aws_lc_rand_extra_path(manifest_dir));
+    }
+
     if let Some(extra_paths) = get_aws_lc_fips_sys_includes_path() {
         include_paths.extend(extra_paths);
     }
@@ -441,3 +455,18 @@ fn setup_include_paths(out_dir: &Path, manifest_dir: &Path) -> PathBuf {
 
     include_dir
 }
+
+fn is_internal_generate_enabled() -> bool {
+    get_env_flag("AWS_LC_RUST_INTERNAL_BINDGEN", "0").eq("1")
+}
+
+fn is_private_api_enabled() -> bool {
+    get_env_flag("AWS_LC_RUST_PRIVATE_INTERNALS", "0").eq("1")
+}
+
+fn get_env_flag<T>(key: &'static str, default: T) -> String
+where
+    T: Into<String>,
+{
+    env::var(key).unwrap_or(default.into())
+}

aws-lc-fips-sys/include/rust_wrapper.h

@@ -101,6 +101,10 @@ int ERR_GET_FUNC_RUST(uint32_t packed_error);
 #include "openssl/x509_vfy.h"
 #include "openssl/x509v3.h"
 
+#if defined(AWS_LC_RUST_PRIVATE_INTERNALS)
+#include "pq_custom_randombytes.h"
+#endif
+
 #if defined(AWS_LC_RUST_INCLUDE_SSL)
 #include "openssl/ssl.h"
 #include "openssl/ssl3.h"

aws-lc-rs-testing/Cargo.toml

@@ -14,7 +14,7 @@ fips = ["aws-lc-rs/fips"]
 asan = ["aws-lc-rs/asan"]
 
 [dependencies]
-aws-lc-rs = { version = "1.0", path = "../aws-lc-rs", features = ["ring-sig-verify"] }
+aws-lc-rs = { version = "1.0", path = "../aws-lc-rs", features = ["ring-sig-verify", "unstable"] }
 untrusted = { version = "0.7" }
 
 [dev-dependencies]
@@ -66,3 +66,7 @@ harness = false
 [[bench]]
 name = "cipher_benchmark"
 harness = false
+
+[[bench]]
+name = "kem_benchmark"
+harness = false