KEM: Key-Encapsulation Mechanisms API Support

.github/workflows/ci.yml

@@ -222,6 +222,10 @@ jobs:
           - --no-default-features --features non-fips,ring-io
           - --no-default-features --features non-fips,ring-sig-verify
           - --no-default-features --features non-fips,alloc
+          - --no-default-features --features non-fips,bindgen
+        include:
+          - args: --no-default-features --features non-fips,bindgen
+            envs: AWS_LC_RUST_PRIVATE_INTERNALS=1
     steps:
       - uses: actions/checkout@v3
         with:
@@ -234,6 +238,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
@@ -256,6 +264,9 @@ jobs:
           - --no-default-features --features fips,ring-sig-verify
           - --no-default-features --features fips,alloc
           - --no-default-features --features fips,bindgen
+        include:
+          - args: --no-default-features --features fips,bindgen
+            envs: AWS_LC_RUST_PRIVATE_INTERNALS=1
     steps:
       - uses: actions/checkout@v3
         with:
@@ -273,6 +284,9 @@ 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
+        if: ${{ matrix.envs }}
+        run: env ${{ matrix.envs }} cargo test --tests ${{ matrix.args }}
 
   bindgen-test:
     name: aws-lc-rs bindgen-tests

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")
 }
@@ -162,7 +169,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");
@@ -292,9 +299,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;
 
@@ -377,6 +387,14 @@ fn main() {
     ] {
         println!("cargo:include={}", include_path.display());
     }
+
+    if is_private_api_enabled() {
+        println!(
+            "cargo:include={}",
+            get_aws_lc_rand_extra_path(&manifest_dir).display()
+        );
+    }
+
     if let Some(include_paths) = get_aws_lc_fips_sys_includes_path() {
         for path in include_paths {
             println!("cargo:include={}", path.display());
@@ -410,3 +428,18 @@ fn check_dependencies() {
         "Required build dependency is missing. Halting build."
     );
 }
+
+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"