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,12 @@ 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
     steps:
       - uses: actions/checkout@v3
         with:
@@ -276,12 +276,11 @@ 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
     steps:
       - uses: actions/checkout@v3
         with:
@@ -309,8 +308,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 +332,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 +413,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-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

aws-lc-rs-testing/benches/kem_benchmark.rs

@@ -0,0 +1,74 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0 OR ISC
+
+use aws_lc_rs::{
+    kem::DecapsulationKey,
+    unstable::kem::{get_algorithm, AlgorithmId},
+};
+use criterion::{criterion_group, criterion_main, Criterion};
+
+const UNSTABLE_ALGORITHMS: &[Option<&aws_lc_rs::kem::Algorithm<AlgorithmId>>] = &[
+    get_algorithm(AlgorithmId::Kyber512_R3),
+    get_algorithm(AlgorithmId::Kyber768_R3),
+    get_algorithm(AlgorithmId::Kyber1024_R3),
+];
+
+fn bench_kem_keygen(c: &mut Criterion) {
+    for ele in UNSTABLE_ALGORITHMS {
+        let ele = ele.unwrap();
+        let bench_group_name = format!("KEM/{:?}/keygen", ele.id());
+        let mut group = c.benchmark_group(bench_group_name);
+        group.bench_function("AWS-LC", |b| {
+            b.iter(|| {
+                aws_lc_rs::kem::DecapsulationKey::generate(ele).unwrap();
+            });
+        });
+    }
+}
+
+fn bench_kem_encapsulate(c: &mut Criterion) {
+    for ele in UNSTABLE_ALGORITHMS {
+        let ele = ele.unwrap();
+        let bench_group_name = format!("KEM/{:?}/encapsulate", ele.id());
+        let mut group = c.benchmark_group(bench_group_name);
+        group.bench_function("AWS-LC", |b| {
+            b.iter_batched(
+                || {
+                    let private = DecapsulationKey::generate(ele).unwrap();
+                    private.encapsulation_key().unwrap()
+                },
+                |key| key.encapsulate(),
+                criterion::BatchSize::LargeInput,
+            );
+        });
+    }
+}
+
+fn bench_kem_decapsulate(c: &mut Criterion) {
+    for ele in UNSTABLE_ALGORITHMS {
+        let ele = ele.unwrap();
+        let bench_group_name = format!("KEM/{:?}/decapsulate", ele.id());
+        let mut group = c.benchmark_group(bench_group_name);
+        group.bench_function("AWS-LC", |b| {
+            b.iter_batched(
+                || {
+                    let private = DecapsulationKey::generate(ele).unwrap();
+                    let public = private.encapsulation_key().unwrap();
+                    let (ciphertext, _) = public.encapsulate().unwrap();
+                    (private, ciphertext)
+                },
+                |(key, ciphertext)| key.decapsulate(ciphertext).unwrap(),
+                criterion::BatchSize::LargeInput,
+            );
+        });
+    }
+}
+
+fn bench_kem(c: &mut Criterion) {
+    bench_kem_keygen(c);
+    bench_kem_encapsulate(c);
+    bench_kem_decapsulate(c);
+}
+
+criterion_group!(benches, bench_kem);
+criterion_main!(benches);

aws-lc-rs/Cargo.toml

@@ -33,6 +33,7 @@ ring-sig-verify = ["dep:untrusted"]
 bindgen = ["aws-lc-sys?/bindgen", "aws-lc-fips-sys?/bindgen"]
 asan = ["aws-lc-sys?/asan", "aws-lc-fips-sys?/asan"]
 test_logging = []
+unstable = []
 
 # require non-FIPS
 non-fips = ["aws-lc-sys"]

aws-lc-rs/Makefile

@@ -24,17 +24,17 @@ coverage:
 	cargo llvm-cov --no-fail-fast --fail-under-lines 95 --ignore-filename-regex "aws-lc-sys/*"
 
 test:
-	cargo test --all-targets --features ring-benchmarks
+	cargo test --all-targets --features unstable
 	cargo test --release --all-targets
-	cargo test --release --all-targets --features bindgen
+	cargo test --release --all-targets --features bindgen,unstable
 ifeq ($(UNAME_S),Linux)
-	cargo test --release --all-targets --features fips
-	cargo test --no-default-features --features fips
+	cargo test --release --all-targets --features fips,unstable
+	cargo test --no-default-features --features fips,unstable
 endif
-	cargo test --no-default-features --features aws-lc-sys
-	cargo test --no-default-features --features aws-lc-sys,ring-sig-verify
-	cargo test --no-default-features --features aws-lc-sys,ring-io
-	cargo test --no-default-features --features aws-lc-sys,alloc
+	cargo test --no-default-features --features aws-lc-sys,unstable
+	cargo test --no-default-features --features aws-lc-sys,ring-sig-verify,unstable
+	cargo test --no-default-features --features aws-lc-sys,ring-io,unstable
+	cargo test --no-default-features --features aws-lc-sys,alloc,unstable
 
 msrv:
 	cargo msrv verify

aws-lc-rs/src/error.rs

@@ -112,7 +112,7 @@ impl From<core::array::TryFromSliceError> for Unspecified {
 ///    being used.
 ///
 ///  * Unexpected errors: Report this as a bug.
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, PartialEq)]
 pub struct KeyRejected(&'static str);
 
 impl KeyRejected {