Add Feature "prebuilt-nasm"; Update documentation (#511)

* Support for 'prebuilt-nasm' feature

* Update READMEs

* Update User Guide

* Cleanup; Address #495

* PR Feedback

* Update verbiage in aws-lc-sys/README and User Guide

* Feedback: stricter bool env var parsing

.github/workflows/integration.yml

@@ -141,6 +141,40 @@ jobs:
         # See: https://github.com/rust-lang/cargo/issues/8531
         run: AWS_LC_SYS_STATIC=0 AWS_LC_FIPS_SYS_STATIC=0 cargo publish --dry-run
 
+  ## Verify that prebuilt-nasm objects were published properly
+  publish-dry-run-prebuild-nasm:
+    if: github.repository_owner == 'aws'
+    name: publish dry-run prebuilt-nasm
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        crate: [ aws-lc-sys, aws-lc-rs ]
+        args:
+          - publish --dry-run
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: 'recursive'
+      - uses: dtolnay/rust-toolchain@master
+        id: toolchain
+        with:
+          toolchain: stable
+      - name: Set Rust toolchain override
+        run: rustup override set ${{ steps.toolchain.outputs.name }}
+      - name: Verify NASM not available
+        shell: bash
+        run: |
+          if nasm --version; then
+             exit 1
+          else
+            exit 0;
+          fi
+      - name: ${{ matrix.crate }}
+        working-directory: ./${{ matrix.crate }}
+        shell: bash
+        run: AWS_LC_SYS_PREBUILT_NASM=1 cargo publish --dry-run
+
   msrv:
     name: Minimum Supported Rust Version
     if: github.repository_owner == 'aws'

.github/workflows/tests.yml

@@ -238,6 +238,36 @@ jobs:
         # See: https://github.com/rust-lang/cargo/issues/8531
         run: cargo test -p aws-lc-rs --tests
 
+  build-prebuild-nasm-test:
+    if: github.repository_owner == 'aws'
+    name: prebuilt-nasm usage
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target:
+          - 'x86_64-pc-windows-msvc'
+          - 'x86_64-pc-windows-gnu'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Verify NASM not available
+        shell: bash
+        run: |
+          if nasm --version; then
+             exit 1
+          else
+            exit 0;
+          fi
+      - name: Run cargo test w/ prebuilt-nasm feature
+        shell: bash
+        run: cargo test --tests -p aws-lc-rs --release --no-default-features --features aws-lc-sys,prebuilt-nasm
+      - name: Run cargo test w/ AWS_LC_SYS_PREBUILT_NASM=1
+        shell: bash
+        run: AWS_LC_SYS_PREBUILT_NASM=1 cargo test --tests -p aws-lc-rs --release --no-default-features --features aws-lc-sys
+
   build-env-nasm-test:
     if: github.repository_owner == 'aws'
     name: prebuilt NASM verification

README.md

@@ -17,7 +17,7 @@ repository for invoking *AWS-LC*.
 ### [aws-lc-rs](aws-lc-rs/README.md)
 
 A *ring*-compatible crypto library using the cryptographic operations provided by
-[*AWS-LC*](https://github.com/awslabs/aws-lc) using either *aws-lc-sys* or *aws-lc-fips-sys*.
+[*AWS-LC*](https://github.com/aws/aws-lc) using either *aws-lc-sys* or *aws-lc-fips-sys*.
 
 ### [aws-lc-sys](aws-lc-sys/README.md)
 
@@ -54,11 +54,11 @@ cryptographic requirements can seamlessly integrate aws-lc-rs into their applica
 
 ## Questions, Feedback and Contributing
 
-* [Submit an non-security Bug/Issue/Request](https://github.com/awslabs/aws-lc-rs/issues/new/choose)
+* [Submit an non-security Bug/Issue/Request](https://github.com/aws/aws-lc-rs/issues/new/choose)
 * [API documentation](https://docs.rs/aws-lc-rs/)
-* [Fork our repo](https://github.com/awslabs/aws-lc-rs/fork)
+* [Fork our repo](https://github.com/aws/aws-lc-rs/fork)
 
-We use [GitHub Issues](https://github.com/awslabs/aws-lc-rs/issues/new/choose) for managing feature requests, bug
+We use [GitHub Issues](https://github.com/aws/aws-lc-rs/issues/new/choose) for managing feature requests, bug
 reports, or questions about aws-lc-rs API usage.
 
 Otherwise, if you think you might have found a security impacting issue, please instead

aws-lc-fips-sys/README.md

@@ -30,10 +30,18 @@ The platforms which `aws-lc-fips-sys` builds on is limited to the platforms wher
 
 ### Pregenerated Bindings Availability
 
-CPU|OS
--------------|-------------
-x86-64|Linux
-arm-64|Linux
+Targets
+---------------------
+aarch64_apple_darwin
+aarch64_unknown_linux_gnu
+aarch64_unknown_linux_musl
+x86_64_apple_darwin
+x86_64_unknown_linux_gnu
+x86_64_unknown_linux_musl
+
+### Prebuilt NASM objects
+
+Prebuilt NASM objects are *not* available for this crate.
 
 ### Tested AWS-LC FIPS Build Environments
 

aws-lc-rs/Cargo.toml

@@ -10,8 +10,8 @@ keywords = ["crypto", "cryptography", "security"]
 license = "ISC AND (Apache-2.0 OR ISC)"
 description = "aws-lc-rs is a cryptographic library using AWS-LC for its cryptographic operations. This library strives to be API-compatible with the popular Rust library named ring."
 documentation = "https://docs.rs/crate/aws-lc-rs"
-homepage = "https://github.com/awslabs/aws-lc-rs"
-repository = "https://github.com/awslabs/aws-lc-rs"
+homepage = "https://github.com/aws/aws-lc-rs"
+repository = "https://github.com/aws/aws-lc-rs"
 # Exclude tests and test data from published crate
 exclude = [
     "third_party/NIST/*",
@@ -37,6 +37,7 @@ bindgen = ["aws-lc-sys?/bindgen", "aws-lc-fips-sys?/bindgen"]
 asan = ["aws-lc-sys?/asan", "aws-lc-fips-sys?/asan"]
 test_logging = []
 unstable = []
+prebuilt-nasm = ["aws-lc-sys?/prebuilt-nasm"]
 
 # require non-FIPS
 non-fips = ["aws-lc-sys"]

aws-lc-rs/Makefile

@@ -49,4 +49,7 @@ clippy:
 
 ci: format clippy msrv test coverage api-diff-pub
 
+readme:
+	cargo readme | tee README.md
+
 .PHONY: asan asan-fips asan-release ci clippy coverage coverage-fips test msrv clippy

aws-lc-rs/README.md

@@ -1,10 +1,10 @@
 # AWS Libcrypto for Rust (aws-lc-rs)
 
 [![Crates.io](https://img.shields.io/crates/v/aws-lc-rs.svg)](https://crates.io/crates/aws-lc-rs)
-[![GitHub](https://img.shields.io/badge/GitHub-awslabs%2Faws--lc--rs-blue)](https://github.com/awslabs/aws-lc-rs)
+[![GitHub](https://img.shields.io/badge/GitHub-aws%2Faws--lc--rs-blue)](https://github.com/aws/aws-lc-rs)
 
 A [*ring*](https://github.com/briansmith/ring)-compatible crypto library using the cryptographic
-operations provided by [*AWS-LC*](https://github.com/awslabs/aws-lc). It uses either the
+operations provided by [*AWS-LC*](https://github.com/aws/aws-lc). It uses either the
 auto-generated [*aws-lc-sys*](https://crates.io/crates/aws-lc-sys) or
 [*aws-lc-fips-sys*](https://crates.io/crates/aws-lc-fips-sys)
 Foreign Function Interface (FFI) crates found in this repository for invoking *AWS-LC*.
@@ -19,12 +19,12 @@ using `Cargo.toml`:
 [dependencies]
 aws-lc-rs = "1.0.0"
 ```
+
 Consuming projects will need a C Compiler (Clang or GCC) to build.
 For some platforms, the build may also require CMake.
 Building with the "fips" feature on any platform requires **CMake** and **Go**.
 
-See our [User Guide](https://awslabs.github.io/aws-lc-rs/) for guidance on installing build requirements.
-
+See our [User Guide](https://aws.github.io/aws-lc-rs/) for guidance on installing build requirements.
 
 ## Feature Flags
 
@@ -70,6 +70,42 @@ the pre-generated bindings. This feature requires `libclang` to be installed. Se
 [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html)
 for [rust-bindgen](https://github.com/rust-lang/rust-bindgen)
 
+##### prebuilt-nasm
+
+Enables the use of crate provided prebuilt NASM objects under certain conditions. This only affects builds for
+Windows x86-64 platforms. This feature is ignored if the "fips" feature is also enabled.
+
+Use of prebuilt NASM objects is prevented if either of the following conditions are true:
+* The NASM assembler is detected in the build environment
+* `AWS_LC_SYS_PREBUILT_NASM` environment variable is set with a value of `0`
+
+Be aware that [features are additive](https://doc.rust-lang.org/cargo/reference/features.html#feature-unification);
+by enabling this feature, it is enabled for crates within the same build.
+
+## Use of prebuilt NASM objects
+
+For Windows x86 and x86-64, NASM is required for assembly code compilation. On these platforms,
+we recommend that you install [the NASM assembler](https://www.nasm.us/). If NASM is
+detected in the build environment *it is used* to compile the assembly files. However,
+if a NASM assembler is not available, and the "fips" feature is not enabled, then the build fails unless one of the following conditions are true:
+
+* You are building for `x86-64` and either:
+   * The `AWS_LC_SYS_PREBUILT_NASM` environment variable is found and has a value of "1"; OR
+   * `AWS_LC_SYS_PREBUILT_NASM` is *not found* in the environment AND the "prebuilt-nasm" feature has been enabled.
+
+If the above cases apply, then the crate provided prebuilt NASM objects will be used for the build. To prevent usage of prebuilt NASM
+objects, install NASM in the build environment and/or set the variable `AWS_LC_SYS_PREBUILT_NASM` to `0` in the build environment to prevent their use.
+
+### About prebuilt NASM objects
+
+Prebuilt NASM objects are generated using automation similar to the crate provided pregenerated bindings. See the repositories
+[GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml) for more information.
+The prebuilt NASM objects are checked into the repository
+and are [available for inspection](https://github.com/aws/aws-lc-rs/tree/main/aws-lc-sys/builder/prebuilt-nasm).
+For each PR submitted,
+[CI verifies](https://github.com/aws/aws-lc-rs/blob/8fb6869fc7bde92529a5cca40cf79513820984f7/.github/workflows/tests.yml#L209-L241)
+that the NASM objects newly built from source match the NASM objects currently in the repository.
+
 ## *ring*-compatibility
 
 Although this library attempts to be fully compatible with *ring* (v0.16.x), there are a few places where our
@@ -100,6 +136,7 @@ and deploy them into AWS Regions.
 For those who would like to contribute to our project or build it directly from our repository,
 a few more packages may be needed. The listing below shows the steps needed for you to begin
 building and testing our project locally.
+
 ```shell
 # Install dependencies needed for build and testing
 sudo yum install -y cmake3 clang git clang-libs golang openssl-devel perl-FindBin
@@ -109,7 +146,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 source "$HOME/.cargo/env"
 
 # Clone and initialize a local repository
-git clone https://github.com/awslabs/aws-lc-rs.git
+git clone https://github.com/aws/aws-lc-rs.git
 cd aws-lc-rs
 git submodule update --init --recursive
 
@@ -120,11 +157,11 @@ cargo test
 
 ## Questions, Feedback and Contributing
 
-* [Submit an non-security Bug/Issue/Request](https://github.com/awslabs/aws-lc-rs/issues/new/choose)
+* [Submit an non-security Bug/Issue/Request](https://github.com/aws/aws-lc-rs/issues/new/choose)
 * [API documentation](https://docs.rs/aws-lc-rs/)
-* [Fork our repo](https://github.com/awslabs/aws-lc-rs/fork)
+* [Fork our repo](https://github.com/aws/aws-lc-rs/fork)
 
-We use [GitHub Issues](https://github.com/awslabs/aws-lc-rs/issues/new/choose) for managing feature requests, bug
+We use [GitHub Issues](https://github.com/aws/aws-lc-rs/issues/new/choose) for managing feature requests, bug
 reports, or questions about aws-lc-rs API usage.
 
 Otherwise, if you think you might have found a security impacting issue, please instead

aws-lc-rs/README.tpl

@@ -1,7 +1,7 @@
 # AWS Libcrypto for Rust ({{crate}})
 
 [![Crates.io](https://img.shields.io/crates/v/aws-lc-rs.svg)](https://crates.io/crates/aws-lc-rs)
-[![GitHub](https://img.shields.io/badge/GitHub-awslabs%2Faws--lc--rs-blue)](https://github.com/awslabs/aws-lc-rs)
+[![GitHub](https://img.shields.io/badge/GitHub-aws%2Faws--lc--rs-blue)](https://github.com/aws/aws-lc-rs)
 
 {{readme}}
 
@@ -10,6 +10,7 @@
 For those who would like to contribute to our project or build it directly from our repository,
 a few more packages may be needed. The listing below shows the steps needed for you to begin
 building and testing our project locally.
+
 ```shell
 # Install dependencies needed for build and testing
 sudo yum install -y cmake3 clang git clang-libs golang openssl-devel perl-FindBin
@@ -19,7 +20,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 source "$HOME/.cargo/env"
 
 # Clone and initialize a local repository
-git clone https://github.com/awslabs/aws-lc-rs.git
+git clone https://github.com/aws/aws-lc-rs.git
 cd aws-lc-rs
 git submodule update --init --recursive
 
@@ -30,11 +31,11 @@ cargo test
 
 ## Questions, Feedback and Contributing
 
-* [Submit an non-security Bug/Issue/Request](https://github.com/awslabs/aws-lc-rs/issues/new/choose)
+* [Submit an non-security Bug/Issue/Request](https://github.com/aws/aws-lc-rs/issues/new/choose)
 * [API documentation](https://docs.rs/aws-lc-rs/)
-* [Fork our repo](https://github.com/awslabs/aws-lc-rs/fork)
+* [Fork our repo](https://github.com/aws/aws-lc-rs/fork)
 
-We use [GitHub Issues](https://github.com/awslabs/aws-lc-rs/issues/new/choose) for managing feature requests, bug
+We use [GitHub Issues](https://github.com/aws/aws-lc-rs/issues/new/choose) for managing feature requests, bug
 reports, or questions about aws-lc-rs API usage.
 
 Otherwise, if you think you might have found a security impacting issue, please instead

aws-lc-rs/src/lib.rs

@@ -5,7 +5,7 @@
 
 #![allow(clippy::doc_markdown)]
 //! A [*ring*](https://github.com/briansmith/ring)-compatible crypto library using the cryptographic
-//! operations provided by [*AWS-LC*](https://github.com/awslabs/aws-lc). It uses either the
+//! operations provided by [*AWS-LC*](https://github.com/aws/aws-lc). It uses either the
 //! auto-generated [*aws-lc-sys*](https://crates.io/crates/aws-lc-sys) or
 //! [*aws-lc-fips-sys*](https://crates.io/crates/aws-lc-fips-sys)
 //! Foreign Function Interface (FFI) crates found in this repository for invoking *AWS-LC*.
@@ -20,12 +20,12 @@
 //! [dependencies]
 //! aws-lc-rs = "1.0.0"
 //! ```
+//!
 //! Consuming projects will need a C Compiler (Clang or GCC) to build.
 //! For some platforms, the build may also require CMake.
 //! Building with the "fips" feature on any platform requires **CMake** and **Go**.
 //!
-//! See our [User Guide](https://awslabs.github.io/aws-lc-rs/) for guidance on installing build requirements.
-//!
+//! See our [User Guide](https://aws.github.io/aws-lc-rs/) for guidance on installing build requirements.
 //!
 //! # Feature Flags
 //!
@@ -71,6 +71,42 @@
 //! [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html)
 //! for [rust-bindgen](https://github.com/rust-lang/rust-bindgen)
 //!
+//! #### prebuilt-nasm
+//!
+//! Enables the use of crate provided prebuilt NASM objects under certain conditions. This only affects builds for
+//! Windows x86-64 platforms. This feature is ignored if the "fips" feature is also enabled.
+//!
+//! Use of prebuilt NASM objects is prevented if either of the following conditions are true:
+//! * The NASM assembler is detected in the build environment
+//! * `AWS_LC_SYS_PREBUILT_NASM` environment variable is set with a value of `0`
+//!
+//! Be aware that [features are additive](https://doc.rust-lang.org/cargo/reference/features.html#feature-unification);
+//! by enabling this feature, it is enabled for crates within the same build.
+//!
+//! # Use of prebuilt NASM objects
+//!
+//! For Windows x86 and x86-64, NASM is required for assembly code compilation. On these platforms,
+//! we recommend that you install [the NASM assembler](https://www.nasm.us/). If NASM is
+//! detected in the build environment *it is used* to compile the assembly files. However,
+//! if a NASM assembler is not available, and the "fips" feature is not enabled, then the build fails unless one of the following conditions are true:
+//!
+//! * You are building for `x86-64` and either:
+//!    * The `AWS_LC_SYS_PREBUILT_NASM` environment variable is found and has a value of "1"; OR
+//!    * `AWS_LC_SYS_PREBUILT_NASM` is *not found* in the environment AND the "prebuilt-nasm" feature has been enabled.
+//!
+//! If the above cases apply, then the crate provided prebuilt NASM objects will be used for the build. To prevent usage of prebuilt NASM
+//! objects, install NASM in the build environment and/or set the variable `AWS_LC_SYS_PREBUILT_NASM` to `0` in the build environment to prevent their use.
+//!
+//! ## About prebuilt NASM objects
+//!
+//! Prebuilt NASM objects are generated using automation similar to the crate provided pregenerated bindings. See the repositories
+//! [GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml) for more information.
+//! The prebuilt NASM objects are checked into the repository
+//! and are [available for inspection](https://github.com/aws/aws-lc-rs/tree/main/aws-lc-sys/builder/prebuilt-nasm).
+//! For each PR submitted,
+//! [CI verifies](https://github.com/aws/aws-lc-rs/blob/8fb6869fc7bde92529a5cca40cf79513820984f7/.github/workflows/tests.yml#L209-L241)
+//! that the NASM objects newly built from source match the NASM objects currently in the repository.
+//!
 //! # *ring*-compatibility
 //!
 //! Although this library attempts to be fully compatible with *ring* (v0.16.x), there are a few places where our

aws-lc-sys/Cargo.toml

@@ -36,6 +36,8 @@ include = [
     "/aws-lc/util/fipstools/**/*.c",
     "/CMakeLists.txt",
     "/builder/**/*.rs",
+    "/builder/**/*.bat",
+    "/builder/**/*.obj",
     "/Cargo.toml",
     "/generated-include/**",
     "/include/**",
@@ -49,6 +51,7 @@ build = "builder/main.rs"
 asan = []
 ssl = ['bindgen']
 bindgen = ["dep:bindgen"] # Generate the bindings on the targetted platform as a fallback mechanism.
+prebuilt-nasm = []
 
 [build-dependencies]
 cmake = "0.1.48"