From a435c4672253ad748e466f9cf9c4de058df85ead Mon Sep 17 00:00:00 2001 From: Justin W Smith <103147162+justsmth@users.noreply.github.com> Date: Thu, 5 Sep 2024 17:20:58 -0400 Subject: [PATCH] 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 | 34 ++++++++++++ .github/workflows/tests.yml | 30 +++++++++++ README.md | 8 +-- aws-lc-fips-sys/README.md | 16 ++++-- aws-lc-rs/Cargo.toml | 5 +- aws-lc-rs/Makefile | 3 ++ aws-lc-rs/README.md | 53 ++++++++++++++++--- aws-lc-rs/README.tpl | 11 ++-- aws-lc-rs/src/lib.rs | 42 +++++++++++++-- aws-lc-sys/Cargo.toml | 3 ++ aws-lc-sys/README.md | 81 +++++++++++++++++++++++------ aws-lc-sys/builder/cmake_builder.rs | 22 ++++---- aws-lc-sys/builder/main.rs | 32 +++++++++--- book/src/requirements/apple.md | 6 +++ book/src/requirements/windows.md | 48 +++++++++++++++-- book/src/resources.md | 7 +++ 16 files changed, 337 insertions(+), 64 deletions(-) diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml index f2add737e2e..50ba720a43c 100644 --- a/.github/workflows/integration.yml +++ b/.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' diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 5dfd651c490..84ec179587a 100644 --- a/.github/workflows/tests.yml +++ b/.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 diff --git a/README.md b/README.md index 10b2e46f7c4..586c02a03d9 100644 --- a/README.md +++ b/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 diff --git a/aws-lc-fips-sys/README.md b/aws-lc-fips-sys/README.md index 928e2d38d76..958d864f952 100644 --- a/aws-lc-fips-sys/README.md +++ b/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 diff --git a/aws-lc-rs/Cargo.toml b/aws-lc-rs/Cargo.toml index 939e102125d..8b7568d6f5f 100644 --- a/aws-lc-rs/Cargo.toml +++ b/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"] diff --git a/aws-lc-rs/Makefile b/aws-lc-rs/Makefile index e49d171ee08..38a431ceaf8 100644 --- a/aws-lc-rs/Makefile +++ b/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 diff --git a/aws-lc-rs/README.md b/aws-lc-rs/README.md index 4f5d510b996..e366c937fc6 100644 --- a/aws-lc-rs/README.md +++ b/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 diff --git a/aws-lc-rs/README.tpl b/aws-lc-rs/README.tpl index 3dbff0cb674..99603f2f1d0 100644 --- a/aws-lc-rs/README.tpl +++ b/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 diff --git a/aws-lc-rs/src/lib.rs b/aws-lc-rs/src/lib.rs index 4a8692207f4..5632ec4c9d1 100644 --- a/aws-lc-rs/src/lib.rs +++ b/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 diff --git a/aws-lc-sys/Cargo.toml b/aws-lc-sys/Cargo.toml index 8e40d203f64..685332902aa 100644 --- a/aws-lc-sys/Cargo.toml +++ b/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" diff --git a/aws-lc-sys/README.md b/aws-lc-sys/README.md index ab9c21118d3..1f96e3585ca 100644 --- a/aws-lc-sys/README.md +++ b/aws-lc-sys/README.md @@ -1,36 +1,85 @@ # aws-lc-sys [![crates.io](https://img.shields.io/crates/v/aws-lc-sys.svg)](https://crates.io/crates/aws-lc-sys) -[![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) -**Autogenerated** Low-level AWS-LC bindings for the Rust programming language. We do not recommend directly relying on these bindings. +**Autogenerated** Low-level bindings to the AWS-LC library for the Rust programming language. The versioning for this +crate will be unstable. +New releases of AWS-LC will correspond to a new `0.x.0` version of this crate. Features and/or fixes from AWS-LC +will not be backported to older versions of this crate. We do not recommend taking a direct dependency on this crate. + +See our [User Guide](https://aws.github.io/aws-lc-rs/) for guidance on installing build requirements. [Documentation](https://github.com/aws/aws-lc). -## Release Support +## Build Support -This crate pulls in the source code of AWS-LC to build with it. Bindings for platforms we officially support are pre-generated. To generate bindings for any platforms where pre-generated bindings aren't available, you can use the `generate_bindings` feature to do so. +This crate pulls in the source code of AWS-LC to build with it. Bindings for popular platforms are pre-generated. +To generate bindings for platforms where pre-generated bindings aren't available, you can either specify our `bindgen` +feature or install the [bindgen-cli](https://crates.io/crates/bindgen-cli). ### Pregenerated Bindings Availability -CPU|OS --------------|------------- -x86|Linux -x86-64|Linux -arm-64|Linux -x86-64|MacOS +Targets +------------- +aarch64_apple_darwin +aarch64_pc_windows_msvc +aarch64_unknown_linux_gnu +aarch64_unknown_linux_musl +i686_pc_windows_msvc +i686_unknown_linux_gnu +x86_64_apple_darwin +x86_64_pc_windows_gnu +x86_64_pc_windows_msvc +x86_64_unknown_linux_gnu +x86_64_unknown_linux_musl + +### 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. ## Build Prerequisites -Since this crate builds AWS-LC as a native library, most build tools needed to build AWS-LC are applicable to `aws-lc-sys` as well. Go and Perl aren't absolutely necessary for `aws-lc-sys`, as AWS-LC provides generated build files. +Since this crate builds AWS-LC as a native library, most build tools needed to build AWS-LC are applicable +to `aws-lc-sys` as well. Go and Perl aren't absolutely necessary for `aws-lc-sys`, as AWS-LC provides generated build +files. -[Building AWS-LC](https://github.com/awslabs/aws-lc/blob/main/BUILDING.md) +[Building AWS-LC](https://github.com/aws/aws-lc/blob/main/BUILDING.md) -AWS-LC is tested on a variety of C/C++ compiler, OS, and CPU combinations. For a complete list of tested combinations see [tests/ci/Readme.md](https://github.com/awslabs/aws-lc/tree/main/tests/ci#unit-tests). If you use a different build combination and would like us to support it, please open an issue to us at [AWS-LC](https://github.com/awslabs/aws-lc/issues/new?assignees=&labels=&template=build-issue.md&title=). +AWS-LC is tested on a variety of C/C++ compiler, OS, and CPU combinations. For a complete list of tested combinations +see [tests/ci/Readme.md](https://github.com/aws/aws-lc/tree/main/tests/ci#unit-tests). If you use a different build +combination and would like us to support it, please open an issue to us +at [AWS-LC](https://github.com/aws/aws-lc/issues/new?assignees=&labels=&template=build-issue.md&title=). ## Building with a FIPS-validated module -This crate does not offer the AWS-LC FIPS build. To use AWS-LC FIPS, please use the FIPS version of this crate, available at [aws-lc-fips-sys](https://crates.io/crates/aws-lc-fips-sys). +This crate does not offer the AWS-LC FIPS build. To use AWS-LC FIPS, please use the FIPS version of this crate, +available at [aws-lc-fips-sys](https://crates.io/crates/aws-lc-fips-sys). ## Security Notification Process @@ -45,8 +94,8 @@ Please contact aws-lc-pre-notifications@amazon.com. ## Contribution -See contributing file at [AWS-LC](https://github.com/awslabs/aws-lc/blob/main/CONTRIBUTING.md) +See contributing file at [AWS-LC](https://github.com/aws/aws-lc/blob/main/CONTRIBUTING.md) ## Licensing -See license at [AWS-LC](https://github.com/awslabs/aws-lc/blob/main/LICENSE) +See license at [AWS-LC](https://github.com/aws/aws-lc/blob/main/LICENSE) diff --git a/aws-lc-sys/builder/cmake_builder.rs b/aws-lc-sys/builder/cmake_builder.rs index d377c20515c..0707f7d2d92 100644 --- a/aws-lc-sys/builder/cmake_builder.rs +++ b/aws-lc-sys/builder/cmake_builder.rs @@ -5,7 +5,8 @@ use crate::OutputLib::{Crypto, RustWrapper, Ssl}; use crate::{ allow_prebuilt_nasm, cargo_env, emit_warning, execute_command, get_cflags, is_crt_static, is_no_asm, option_env, requested_c_std, target, target_arch, target_env, target_family, - target_os, target_underscored, target_vendor, test_nasm_command, CStdRequested, OutputLibType, + target_os, target_underscored, target_vendor, test_nasm_command, use_prebuilt_nasm, + CStdRequested, OutputLibType, }; use std::env; use std::ffi::OsString; @@ -256,8 +257,7 @@ impl CmakeBuilder { } _ => {} } - if target_arch() == "x86_64" && !test_nasm_command() && Some(true) == allow_prebuilt_nasm() - { + if use_prebuilt_nasm() { emit_warning("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"); emit_warning("!!! Using pre-built NASM binaries !!!"); emit_warning("!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"); @@ -271,7 +271,6 @@ impl CmakeBuilder { let script_path = script_path.replace('\\', "/"); cmake_cfg.define("CMAKE_ASM_NASM_COMPILER", script_path.as_str()); - cmake_cfg.define("CMAKE_VERBOSE_MAKEFILE", "1"); } } @@ -327,12 +326,15 @@ impl crate::Builder for CmakeBuilder { fn check_dependencies(&self) -> Result<(), String> { let mut missing_dependency = false; - if target_os() == "windows" { - if target_arch() == "x86_64" - && !is_no_asm() - && !test_nasm_command() - && Some(true) != allow_prebuilt_nasm() - { + if target_os() == "windows" && target_arch() == "x86-64" { + if is_no_asm() && Some(true) == allow_prebuilt_nasm() { + eprintln!( + "Build environment has both `AWS_LC_SYS_PREBUILT_NASM` and `AWS_LC_SYS_NO_ASM` set.\ + Please remove one of these environment variables. + See User Guide: https://aws.github.io/aws-lc-rs/index.html" + ); + } + if !is_no_asm() && !test_nasm_command() && !use_prebuilt_nasm() { eprintln!( "Consider setting `AWS_LC_SYS_PREBUILT_NASM` in the build environment.\ See User Guide: https://aws.github.io/aws-lc-rs/index.html" diff --git a/aws-lc-sys/builder/main.rs b/aws-lc-sys/builder/main.rs index c12110c83f5..3fae1e4448b 100644 --- a/aws-lc-sys/builder/main.rs +++ b/aws-lc-sys/builder/main.rs @@ -77,21 +77,28 @@ fn option_env>(name: N) -> Option { fn env_var_to_bool(name: &str) -> Option { let build_type_result = option_env(name); if let Some(env_var_value) = build_type_result { - eprintln!("{name}={env_var_value}"); - // If the environment variable is set, we ignore every other factor. + eprintln!("Evaluating: {name}='{env_var_value}'"); + let env_var_value = env_var_value.to_lowercase(); if env_var_value.starts_with('0') || env_var_value.starts_with('n') || env_var_value.starts_with("off") + || env_var_value.starts_with('f') { - Some(false) - } else { - // Otherwise, if the variable is set, assume true - Some(true) + eprintln!("Parsed: {name}=false"); + return Some(false); } - } else { - None + if env_var_value.starts_with(|c: char| c.is_ascii_digit()) + || env_var_value.starts_with('y') + || env_var_value.starts_with("on") + || env_var_value.starts_with('t') + { + eprintln!("Parsed: {name}=true"); + return Some(true); + } + eprintln!("Parsed: {name}=unknown"); } + None } impl Default for OutputLibType { @@ -421,6 +428,15 @@ fn get_cflags() -> &'static str { unsafe { AWS_LC_SYS_CFLAGS.as_str() } } +fn use_prebuilt_nasm() -> bool { + target_os() == "windows" + && target_arch() == "x86_64" + && !is_no_asm() + && !test_nasm_command() + && (Some(true) == allow_prebuilt_nasm() + || (allow_prebuilt_nasm().is_none() && cfg!(feature = "prebuilt-nasm"))) +} + fn allow_prebuilt_nasm() -> Option { unsafe { AWS_LC_SYS_PREBUILT_NASM } } diff --git a/book/src/requirements/apple.md b/book/src/requirements/apple.md index d0584161d61..8d1e4921e5a 100644 --- a/book/src/requirements/apple.md +++ b/book/src/requirements/apple.md @@ -54,6 +54,12 @@ brew install llvm cargo install --force --locked bindgen-cli ``` +## FIPS build + +Building with the "fips" feature on this platform will result in the creation of shared libraries (named like +`libaws_lc_fips_0_xx_yy_crypto.dylib` and `libaws_lc_fips_0_xx_yy_rust_wrapper.dylib`). These shared libraries will +likely need to be distributed alongside any executable that depends on **aws-lc-rs**. + ## Troubleshooting See our [troubleshooting section](../resources.md#troubleshooting). diff --git a/book/src/requirements/windows.md b/book/src/requirements/windows.md index 5cab5e27e15..fe52787465d 100644 --- a/book/src/requirements/windows.md +++ b/book/src/requirements/windows.md @@ -2,11 +2,15 @@ | Platform | *default* | **fips** | bindgen required? | |---------------------------|--------------------------------------------|-----------------------------------------|-------------------| -| `x86_64-pc-windows-msvc` | C/C++ Compiler, CMake & NASM | C/C++ Compiler, CMake, NASM, Go & Ninja | **_Yes_** | -| `x86_64-pc-windows-gnu` | C/C++ Compiler, CMake & NASM | **Not Supported** | **_Yes_** | -| `aarch64-pc-windows-msvc` | C/C++ Compiler (MSVC's `clang-cl`) & CMake | **Not Supported** | **_Yes_** | +| `x86_64-pc-windows-msvc` | C/C++ Compiler, CMake & \*NASM | C/C++ Compiler, CMake, NASM, Go & Ninja | No | +| `x86_64-pc-windows-gnu` | C/C++ Compiler, CMake & \*NASM | **Not Supported** | No | +| `i686-pc-windows-msvc` | C/C++ Compiler, CMake & NASM | **Not Supported** | No | +| `aarch64-pc-windows-msvc` | C/C++ Compiler (MSVC's `clang-cl`) & CMake | **Not Supported** | No | | _Other_ | **Not Supported** | **Not Supported** | N/A | +* The NASM assembler is recommended on `x86-64` platforms. NASM is required for `x86` and for "fips" builds. See the + [Prebuilt NASM objects](#prebuilt-nasm-objects) section below. + ## C/C++ Compiler Use the following instructions to download **Visual Studio Build Tools 2017** or later. @@ -36,6 +40,35 @@ Use the following instructions to download **Visual Studio Build Tools 2017** or 2. Add the NASM installation directory to your PATH * `set PATH="C:\Program Files\NASM;%PATH%"` +### 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. + ### No-assembly build It is possible to avoid the NASM requirement by setting the `AWS_LC_SYS_NO_ASM`/`AWS_LC_FIPS_SYS_NO_ASM` environment @@ -50,7 +83,8 @@ notes in our [troubleshooting section](../resources.md#troubleshooting). ## Bindgen -On most platforms, `bindgen` requires `libclang` or `llvm` package to be installed. +Bindgen is not required for most Windows targets, but it can still be used if needed. +Using `bindgen` requires a `libclang` or `llvm` package to be installed. See the [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html) page in [The bindgen User Guide] for instructions. @@ -67,6 +101,12 @@ See the [requirements](https://rust-lang.github.io/rust-bindgen/requirements.htm cargo install --force --locked bindgen-cli ``` +## FIPS build + +Building with the "fips" feature on this platform will result in the creation of shared libraries (named like +`aws_lc_fips_0_xx_yy_crypto.dll` and `aws_lc_fips_0_xx_yy_rust_wrapper.dll`). These shared libraries will likely need to +be distributed alongside any executable that depends on **aws-lc-rs**. + ## Troubleshooting See our [troubleshooting section](../resources.md#troubleshooting). diff --git a/book/src/resources.md b/book/src/resources.md index c1eefc3ddb8..e0c485a673b 100644 --- a/book/src/resources.md +++ b/book/src/resources.md @@ -20,6 +20,13 @@ future release. Please [contact us] about any bugs you find in our build process be used. This option is only available for unoptimized (i.e., `OPT_LEVEL = "0"` or "debug") builds. **WARNING**: Performance on most platforms is extremely limited by this option. Certain security properties, such as resistance to timing attacks, can only be provided when assembly code is used. +* `AWS_LC_SYS_PREBUILT_NASM` -- value can be set to `1` to *allow* the build to use our prebuilt NASM objects. + The value can be set to `0` to *prevent* our prebuilt NASM objects from being used. See the section on + [Prebuilt NASM objects](requirements/windows.md#prebuilt-nasm-objects) for more information. +* `AWS_LC_SYS_CFLAGS` -- if value is set, it will be used as the value of `CFLAGS` in the environment when the AWS-LC + build is performed. +* `AWS_LC_SYS_C_STD` -- value can be set to determine the C standard used by the C compiler. It may be set to + either `99` for C99 or `11` for C11. On most platforms, C11 will be used by default. ## Links