From 66d20a24d7b6d361c001188b7e5f54c2fb8871fa Mon Sep 17 00:00:00 2001 From: Justin Smith Date: Thu, 18 Apr 2024 12:42:28 -0400 Subject: [PATCH 1/4] Updates for User Guide --- aws-lc-fips-sys/builder/main.rs | 14 ++++++- aws-lc-sys/builder/main.rs | 14 ++++++- book/book.toml | 2 +- book/src/README.md | 43 ++++++++++++++------- book/src/SUMMARY.md | 2 +- book/src/faq.md | 27 +++++++++----- book/src/platform_support.md | 63 +++++++++++++++++++++++-------- book/src/requirements/README.md | 12 +++--- book/src/requirements/apple.md | 64 ++++++++++++++++++++++++++++++++ book/src/requirements/linux.md | 48 ++++++++++++++++++++---- book/src/requirements/macos.md | 34 ----------------- book/src/requirements/windows.md | 46 ++++++++++++++++++----- book/src/resources.md | 20 ++++++++++ 13 files changed, 288 insertions(+), 101 deletions(-) create mode 100644 book/src/requirements/apple.md delete mode 100644 book/src/requirements/macos.md diff --git a/aws-lc-fips-sys/builder/main.rs b/aws-lc-fips-sys/builder/main.rs index e5ebedb60c2..4f316cb2aac 100644 --- a/aws-lc-fips-sys/builder/main.rs +++ b/aws-lc-fips-sys/builder/main.rs @@ -474,8 +474,18 @@ fn invoke_external_bindgen( prefix: &Option, gen_bindings_path: &Path, ) -> Result<(), String> { - if !execute_command("bindgen".as_ref(), &["--version".as_ref()]).status { - return Err("External bindgen command not found.".to_string()); + let result = execute_command("bindgen".as_ref(), &["--version".as_ref()]); + if !result.status { + if !result.executed { + eprintln!( + "Consider installing the bindgen-cli: \ + `cargo install --force --locked bindgen-cli`\ + \n\ + See our User Guide for more information about bindgen:\ + https://aws.github.io/aws-lc-rs/index.html" + ) + } + return Err("External bindgen command failed.".to_string()); } let options = BindingOptions { // We collect the symbols w/o the prefix added diff --git a/aws-lc-sys/builder/main.rs b/aws-lc-sys/builder/main.rs index 1f6b6f571f5..8ab5d52cb30 100644 --- a/aws-lc-sys/builder/main.rs +++ b/aws-lc-sys/builder/main.rs @@ -511,8 +511,18 @@ fn invoke_external_bindgen( prefix: &Option, gen_bindings_path: &Path, ) -> Result<(), String> { - if !execute_command("bindgen".as_ref(), &["--version".as_ref()]).status { - return Err("External bindgen command not found.".to_string()); + let result = execute_command("bindgen".as_ref(), &["--version".as_ref()]); + if !result.status { + if !result.executed { + eprintln!( + "Consider installing the bindgen-cli: \ + `cargo install --force --locked bindgen-cli`\ + \n\ + See our User Guide for more information about bindgen:\ + https://aws.github.io/aws-lc-rs/index.html" + ) + } + return Err("External bindgen command failed.".to_string()); } let options = BindingOptions { build_prefix: None, diff --git a/book/book.toml b/book/book.toml index c2655b88d17..f9a6d7adf1d 100644 --- a/book/book.toml +++ b/book/book.toml @@ -1,5 +1,5 @@ [book] -authors = ["Sean McGrail"] +authors = ["Sean McGrail", "Justin W. Smith"] language = "en" multilingual = false src = "src" diff --git a/book/src/README.md b/book/src/README.md index bdc1e0ae061..4761ebdb451 100644 --- a/book/src/README.md +++ b/book/src/README.md @@ -1,21 +1,24 @@ # Introduction -[![aws-lc-rs](https://img.shields.io/badge/aws--lc--rs-crates.io-important)](https://crates.io/crates/aws-lc-rs) -[![aws-lc-sys](https://img.shields.io/badge/aws--lc--sys-crates.io-important)](https://crates.io/crates/aws-lc-sys) -[![aws-lc-fips-sys](https://img.shields.io/badge/aws--lc--fips--sys-crates.io-important)](https://crates.io/crates/aws-lc-fips-sys) +[![aws-lc-rs](https://img.shields.io/crates/v/aws-lc-rs?label=aws-lc-rs)](https://crates.io/crates/aws-lc-rs) +[![aws-lc-sys](https://img.shields.io/crates/v/aws-lc-sys?label=aws-lc-sys)](https://crates.io/crates/aws-lc-sys) +[![aws-lc-fips-sys](https://img.shields.io/crates/v/aws-lc-fips-sys?label=aws-lc-fips-sys)](https://crates.io/crates/aws-lc-fips-sys) -`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. -It uses either the auto-generated `aws-lc-sys` or `aws-lc-fips-sys` Foreign Function Interface (FFI) crates -for binding to AWS Libcrypto (AWS-LC) for the cryptographic implementations. +**[aws-lc-rs]** is a cryptographic library using AWS Libcrypto ([AWS-LC]) +for its cryptographic operations. This library strives to be API-compatible with the popular Rust library +named [ring](https://github.com/briansmith/ring) ([v0.16](https://docs.rs/ring/0.16.20/ring/index.html)). +It uses one of our auto-generated Foreign Function Interface (FFI) crates +(either **[aws-lc-sys]** or **[aws-lc-fips-sys]**) for binding to AWS-LC for the cryptographic implementations. ## Motivation + Rust developers increasingly need to deploy applications that meet US and Canadian government cryptographic requirements. We evaluated how to deliver FIPS validated cryptography in idiomatic and performant Rust, built around our -AWS-LC offering. We found that the popular ring (v0.16) library fulfilled much of the cryptographic needs in the Rust +AWS-LC offering. We found that the popular ring library fulfilled much of the cryptographic needs in the Rust community, but it did not meet the needs of developers with FIPS requirements. Our intention is to contribute a drop-in -replacement for ring that provides FIPS support and is compatible with the ring API. Rust developers with prescribed -cryptographic requirements can seamlessly integrate aws-lc-rs into their applications and deploy them into AWS Regions. +replacement for ring that provides FIPS support and is compatible with the ring (v0.16) API. Rust developers with +prescribed cryptographic requirements can seamlessly integrate aws-lc-rs into their applications and deploy them into +AWS Regions. ## Questions, Feedback and Contributing @@ -31,8 +34,7 @@ follow our *Security Notification Process* below. ## Security Notification Process If you discover a potential security issue in *AWS-LC* or *aws-lc-rs*, we ask that you notify AWS -Security via our -[vulnerability reporting page][VULN_REPORT]. +Security via our [vulnerability reporting page]. Please do **not** create a public GitHub issue. If you package or distribute *aws-lc-rs*, or use *aws-lc-rs* as part of a large multi-user service, @@ -41,9 +43,22 @@ Please contact aws-lc-pre-notifications@amazon.com. ## License -This library is licensed under the Apache-2.0 or the ISC License. +[aws-lc-rs] is licensed under the Apache-2.0 or the ISC License. +The [aws-lc-sys] and [aws-lc-fips-sys] libraries contain code from [AWS-LC] and are licensed under +the ISC AND ( Apache-2.0 OR ISC ) AND OpenSSL licenses. [ISSUES]: https://github.com/awslabs/aws-lc-rs/issues/new/choose + [API_DOC]: https://docs.rs/aws-lc-rs/ + [FORK]: https://github.com/awslabs/aws-lc-rs/fork -[VULN_REPORT]: https://aws.amazon.com/security/vulnerability-reporting/ + +[vulnerability reporting page]: https://aws.amazon.com/security/vulnerability-reporting/ + +[AWS-LC]: https://github.com/aws/aws-lc + +[aws-lc-rs]: https://crates.io/crates/aws-lc-rs + +[aws-lc-sys]: https://crates.io/crates/aws-lc-sys + +[aws-lc-fips-sys]: https://crates.io/crates/aws-lc-fips-sys diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index b121c16add5..fed907470ec 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -6,7 +6,7 @@ - [Requirements](requirements/README.md) - [Linux](requirements/linux.md) - - [macOS](requirements/macos.md) + - [macOS/iOS](requirements/apple.md) - [Windows](requirements/windows.md) - [Platform Support](platform_support.md) - [FAQ](faq.md) diff --git a/book/src/faq.md b/book/src/faq.md index 02dea2a9803..728544bcfd8 100644 --- a/book/src/faq.md +++ b/book/src/faq.md @@ -1,24 +1,33 @@ # Frequently Asked Questions ## What are the differences between `aws-lc-rs` and `ring`? -While we aim to be API-compatible with `ring` there are some differences in our implementation. Please review the -[ring-compatibility](https://docs.rs/aws-lc-rs/1.0.1/aws_lc_rs/#ring-compatibility) section of our -[API reference guide][COMPAT]. + +While we aim to be API-compatible with `ring` v0.16 there are some differences in our implementation. Please review the +[ring-compatibility] section of our [API reference guide]. ## Can I run `aws-lc-rs` on X platform or architecture? The answer to this question is dependent on several factors based on the target environment: -* Must be a platform and CPU architecture supported by [AWS-LC][AWS-LC]. + +* Must be a platform and CPU architecture supported by [AWS-LC]. * Must be a platform supported by the Rust compiler with support for the full standard library. - See the Rust compiler's [platform support][rustc] documentation. + See the [Rust compiler's platform support] documentation. * If the underlying `aws-lc-sys` or `aws-lc-fips-sys` crates don't have pre-generated bindings for the desired platform - then you must use the `bindgen` crate feature of `aws-lc-rs` to enable generation of the FFI bindings for the desired - platform and architecture. See [Requirements](requirements/README.md) for more details on what build dependencies are + then you must use the `bindgen` crate feature of `aws-lc-rs`, or have the [bindgen-cli] installed, to enable + generation of the FFI bindings for the desired platform and architecture. +* See [Requirements](requirements/README.md) for more details on what build dependencies are required for target platforms. If there is a platform or architecture you are interested in seeing support for, please create a GitHub [issue]. -[COMPAT]: https://docs.rs/aws-lc-rs/1.0.1/aws_lc_rs/#ring-compatibility +[ring-compatibility]: https://docs.rs/aws-lc-rs/latest/aws_lc_rs/#ring-compatibility + +[API reference guide]: https://docs.rs/aws-lc-rs/latest/aws_lc_rs + [AWS-LC]: https://github.com/aws/aws-lc -[rustc]: https://doc.rust-lang.org/rustc/platform-support.html + +[Rust compiler's platform support]: https://doc.rust-lang.org/rustc/platform-support.html + [issue]: https://github.com/awslabs/aws-lc-rs/issues/new/choose + +[bindgen-cli]: https://crates.io/crates/bindgen-cli diff --git a/book/src/platform_support.md b/book/src/platform_support.md index 2f24f178ff0..baae774de68 100644 --- a/book/src/platform_support.md +++ b/book/src/platform_support.md @@ -1,29 +1,60 @@ # Platform Support -## Platforms with pre-generated bindings +## Pre-generated bindings `aws-lc-rs` can utilize pre-generated bindings when operating on the following -operating systems and CPU architecture combinations. +build targets. -| OS | Architecture | -|-------|--------------| -| macOS | x86-64 | -| Linux | x86-64 | -| Linux | x86 | -| Linux | aarch64 | +| Platform | `aws-lc-sys` | `aws-lc-fips-sys` | +|------------------------------|--------------|-------------------| +| `aarch64-unknown-linux-gnu` | X | X | +| `aarch64-unknown-linux-musl` | X | X | +| `x86_64-unknown-linux-gnu` | X | X | +| `x86_64-unknown-linux-musl` | X | X | +| `i686-unknown-linux-gnu` | X | | +| `aarch64-apple-darwin` | X | X | +| `x86_64-apple-darwin` | X | X | -## Supported via `bindgen` feature. +## Tested platforms -`aws-lc-rs` can be utilized on the following platforms when built with the `bindgen` crate feature. +In addition to the ones listed above, the `aws-lc-rs` CI builds and/or tests with the following platforms. +All platforms listed below require `CMake` to be available in the build environment. +They also require bindings to be generated during the build process. -In addition to requiring a C/C++ compiler and CMake, LLVM is required to be installed. +### bindgen + +One of the following options must be used for bindings generation. +See [requirements](requirements/README.md) page for more information. + +* Enable `bindgen` feature in your `Cargo.toml`: ```toml [dependencies] -aws-lc-rs = { version = "1", features = ["bindgen"]} +aws-lc-rs = { version = "1", features = ["bindgen"] } +``` + +_**-- OR --**_ + +* Install `bindgen-cli` in the build envionment: + +```shell +cargo install --force --locked bindgen-cli ``` -| OS | Architecture | -|---------|--------------| -| Windows | x86-64 | -| macOS | aarch64 | +### Platforms + +| Platform | Build | Tests | +|---------------------------------|-------|-------| +| `aarch64-apple-ios` | X | X | +| `aarch64-linux-android` | X | X | +| `armv7-linux-androideabi` | X | X | +| `arm-linux-androideabi` | X | X | +| `arm-unknown-linux-gnueabihf` | X | X | +| `powerpc64le-unknown-linux-gnu` | X | X | +| `powerpc64-unknown-linux-gnu` | X | X | +| `powerpc-unknown-linux-gnu` | X | X | +| `riscv64gc-unknown-linux-gnu` | X | X | +| `s390x-unknown-linux-gnu` | X | X | +| `x86_64-apple-ios` | X | | +| `x86_64-pc-windows-gnu` | X | X | +| `x86_64-pc-windows-msvc` | X | X | diff --git a/book/src/requirements/README.md b/book/src/requirements/README.md index 9f4c36d75a1..78875e6b1aa 100644 --- a/book/src/requirements/README.md +++ b/book/src/requirements/README.md @@ -2,13 +2,15 @@ This page outlines the requirements for using `aws-lc-rs` on each target platform. -`aws-lc-rs` uses [aws-lc-sys] or [aws-lc-fips-sys] raw FFI bindings to [AWS-LC], and thus -a minimal set of additional build environments in order to compile your Rust application. +`aws-lc-rs` uses [aws-lc-sys] or [aws-lc-fips-sys] to provide raw FFI bindings to [AWS-LC]. Thus, +there are additional build tools required for building these crates into your Rust application. -- [Linux](linux.md) -- [macOS](macos.md) -- [Windows](windows.md) +- [Linux](linux) +- [macOS & iOS](apple) +- [Windows](windows) [aws-lc-sys]: https://crates.io/crates/aws-lc-sys + [aws-lc-fips-sys]: https://crates.io/crates/aws-lc-fips-sys + [AWS-LC]: https://github.com/aws/aws-lc diff --git a/book/src/requirements/apple.md b/book/src/requirements/apple.md new file mode 100644 index 00000000000..13db16f6bef --- /dev/null +++ b/book/src/requirements/apple.md @@ -0,0 +1,64 @@ +# macOS & iOS Requirements + +Unless the "fips" feature is enabled, building aws-lc-rs v1.7.0 (or later) for the following targets should only require +a C/C++ compiler. + +| Platform | *default* | **fips** | bindgen required? | +|------------------------|------------------------|----------------------------|-------------------| +| `aarch64-apple-darwin` | C/C++ Compiler | C/C++ Compiler, CMake & Go | No | +| `x86_64-apple-darwin` | C/C++ Compiler | C/C++ Compiler, CMake & Go | No | +| `aarch64-apple-ios` | C/C++ Compiler & CMake | **Not Supported** | **_Yes_** | +| `x86_64-apple-ios` | C/C++ Compiler & CMake | **Not Supported** | **_Yes_** | +| _Other_ | C/C++ Compiler & CMake | **Not Supported** | **_Yes_** | + +## C/C++ Compiler + +Install [Command Line Tools for Xcode][XCODE] which a provides a C/C++ compiler environment (LLVM). + +## CMake + +### MacPorts + +```shell +sudo port install cmake +``` + +### Homebrew + +```shell +brew install cmake +``` + +## Bindgen + +On most platforms, `bindgen` requires `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. + +#### + +### MacPorts + +```shell +sudo port install clang +``` + +### Homebrew + +```shell +brew install llvm +``` + +### bindgen-cli + +```shell +cargo install --force --locked bindgen-cli +``` + +## Troubleshooting + +See our [troubleshooting section](../resources.md#troubleshooting). + +[The bindgen User Guide]: https://rust-lang.github.io/rust-bindgen/ + +[XCODE]: https://developer.apple.com/xcode/resources/ diff --git a/book/src/requirements/linux.md b/book/src/requirements/linux.md index ec3d366dd9b..090910b6124 100644 --- a/book/src/requirements/linux.md +++ b/book/src/requirements/linux.md @@ -1,41 +1,73 @@ # Linux Requirements +Unless the "fips" feature is enabled, building aws-lc-rs v1.7.0 (or later) for the following targets should only require +a C/C++ compiler. + +| Platform | *default* | **fips** | bindgen required? | +|------------------------------|------------------------|----------------------------|-------------------| +| `aarch64-unknown-linux-gnu` | C/C++ Compiler | C/C++ Compiler, CMake & Go | No | +| `aarch64-unknown-linux-musl` | C/C++ Compiler | C/C++ Compiler, CMake & Go | No | +| `x86_64-unknown-linux-gnu` | C/C++ Compiler | C/C++ Compiler, CMake & Go | No | +| `x86_64-unknown-linux-musl` | C/C++ Compiler | C/C++ Compiler, CMake & Go | No | +| `i686-unknown-linux-gnu` | C/C++ Compiler | **Not Supported** | No | +| _Other_ | C/C++ Compiler & CMake | **Not Supported** | **_Yes_** | + ## C/C++ Compiler ### Amazon Linux (AL2023) ```shell -sudo dnf install -y gcc gcc-c++ +sudo dnf groupinstall -y "Development Tools" ``` #### Ubuntu (22.04 LTS) ```shell -sudo apt-get install -y gcc g++ +sudo apt-get install -y build-essential ``` -## CMake +## CMake & Go #### Amazon Linux (AL2023) ```shell -sudo dnf install -y cmake +sudo dnf install -y cmake golang ``` #### Ubuntu (22.04 LTS) ```shell -sudo apt-get install -y cmake +sudo apt-get install -y cmake golang ``` -## LLVM (When building with `bindgen` feature) +## Bindgen + +On most platforms, `bindgen` requires `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. + +### libclang / LLVM + +#### Amazon Linux (AL2023) -### Amazon Linux (AL2023) ```shell sudo dnf install -y clang-libs ``` #### Ubuntu (22.04 LTS) + ```shell sudo apt-get install -y libclang1 -``` \ No newline at end of file +``` + +### bindgen-cli + +```shell +cargo install --force --locked bindgen-cli +``` + +## Troubleshooting + +See our [troubleshooting section](../resources.md#troubleshooting). + +[The bindgen User Guide]: https://rust-lang.github.io/rust-bindgen/ diff --git a/book/src/requirements/macos.md b/book/src/requirements/macos.md deleted file mode 100644 index 8f9320e030b..00000000000 --- a/book/src/requirements/macos.md +++ /dev/null @@ -1,34 +0,0 @@ -# macOS Requirements - -## C/C++ Compiler - -Install [Command Line Tools for Xcode][XCODE] which a provides a C/C++ compiler environment (LLVM). - -## CMake - -### MacPorts - -```shell -sudo port install cmake -``` - -### Homebrew - -```shell -brew install cmake -``` - -## LLVM (When building with `bindgen` feature) - -### MacPorts - -```shell -sudo port install clang -``` - -### Homebrew -```shell -brew install llvm -``` - -[XCODE]: https://developer.apple.com/xcode/resources/ diff --git a/book/src/requirements/windows.md b/book/src/requirements/windows.md index ab3dd1ca404..70aca4ff762 100644 --- a/book/src/requirements/windows.md +++ b/book/src/requirements/windows.md @@ -1,18 +1,23 @@ # Windows Requirements +| 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` | **Not Yet Supported** | **Not Supported** | N/A | +| _Other_ | **Not Supported** | **Not Supported** | N/A | + ## C/C++ Compiler Use the following instructions to download **Visual Studio Build Tools 2017**. -**NOTE**: Visual Studio Build Tools 2022 is **NOT** supported at this time. - 1. Download the [Build Tools for Visual Studio][WIN_TOOLS] installer. 2. Execute the installer. 3. If you have an existing installation chose `Modify` on the existing installation. 4. Under `Workloads` select `Visual C++ build tools` 5. Under `Individual componenets` select - * `C++/CLI support` - * `C++ CMake tools for Windows` + * `C++/CLI support` + * `C++ CMake tools for Windows` 6. Confirm selections and click `Install` ## CMake @@ -20,18 +25,41 @@ Use the following instructions to download **Visual Studio Build Tools 2017**. 1. [Download](https://cmake.org/download/) Windows CMake Installer 2. Execute the installer 3. Add the CMake installation binary directory to your PATH. - * `set PATH="C:\Program Files\CMake\bin;%PATH%"` + * `set PATH="C:\Program Files\CMake\bin;%PATH%"` ## NASM + 1. [Download](https://nasm.us/) and install the Netwide Assembler (NASM) 2. Add the NASM installation directory to your PATH - * `set PATH="C:\Program Files\NASM;%PATH%"` + * `set PATH="C:\Program Files\NASM;%PATH%"` + +## Ninja + +1. [Download](https://github.com/ninja-build/ninja/releases) and install Ninja +2. Add the Ninja installation directory to your PATH + * `set PATH="C:\ninja\ninja_build;%PATH%"` + +## Bindgen -## LLVM (When building with `bindgen` feature) +On most platforms, `bindgen` requires `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. + +### libclang / LLVM 1. Download [LLVM Installer](https://github.com/llvm/llvm-project/releases/tag/llvmorg-15.0.6) 2. Execute the installer 3. Update your environment to set `LIBCLANG_PATH` to the bin directory inside LLVM install directory. - * `set LIBCLANG_PATH="C:\Program Files\LLVM\bin"` + * `set LIBCLANG_PATH="C:\Program Files\LLVM\bin"` + +### bindgen-cli + +```shell +cargo install --force --locked bindgen-cli +``` + +## Troubleshooting + +See our [troubleshooting section](../resources.md#troubleshooting). -[WIN_TOOLS]: https://aka.ms/vs/15/release/vs_BuildTools.exe +[WIN_TOOLS]: https://aka.ms/vs/17/release/vs_BuildTools.exe diff --git a/book/src/resources.md b/book/src/resources.md index 5da15064b58..7087bfef598 100644 --- a/book/src/resources.md +++ b/book/src/resources.md @@ -1,4 +1,24 @@ # Resources +## Troubleshooting + +There are a few environment variables that may help in diagnosing/remdiating build problem. These affect the way that +`aws-lc-sys` or `aws-lc-fips-sys` build the underlying AWS-LC library. + +None of the environment variables below are officially supported, and any one of them might be removed or changed on a +future release. Please [contact us] about any bugs you find in our build process. + +* `AWS_LC_SYS_STATIC` | `AWS_LC_FIPS_SYS_STATIC` -- value can be set to `0` or `1` to force the resulting build + artifact to be shared library (e.g., `*.so`) or static library (e.g., `*.a`). +* `AWS_LC_SYS_CMAKE_BUILDER` -- value can be set to `1` or `0` to force the build to use (`1`) or not use (`0`) CMake. +* `AWS_LC_SYS_EXTERNAL_BINDGEN | ``AWS_LC_FIPS_SYS_EXTERNAL_BINDGEN` -- value can be set to `1` or `0` to force the + build to use (`1`) or not use (`0`) the `bindgen-cli` instead of the pre-generated or internally generated bindings. +* `AWS_LC_SYS_NO_PREFIX` | `AWS_LC_FIPS_SYS_NO_PREFIX` -- value can be set to `1` to force the build to not prefix the + library nor the symbols it contains. + +## Links + - [API Reference Guide](https://docs.rs/aws-lc-rs/latest) - [GitHub Repository](https://github.com/awslabs/aws-lc-rs) + +[contact us]: https://github.com/awslabs/aws-lc-rs/issues/new/choose From 72bb6b521887f201426c4b80d8c5ee82294dd115 Mon Sep 17 00:00:00 2001 From: Justin Smith Date: Fri, 26 Apr 2024 10:40:50 -0400 Subject: [PATCH 2/4] Note about AWS_LC_SYS_NO_ASM --- aws-lc-fips-sys/builder/cmake_builder.rs | 4 ++++ aws-lc-sys/builder/cmake_builder.rs | 4 ++++ book/src/requirements/windows.md | 6 ++++++ book/src/resources.md | 5 +++++ 4 files changed, 19 insertions(+) diff --git a/aws-lc-fips-sys/builder/cmake_builder.rs b/aws-lc-fips-sys/builder/cmake_builder.rs index 8fa1859f26e..5835724b871 100644 --- a/aws-lc-fips-sys/builder/cmake_builder.rs +++ b/aws-lc-fips-sys/builder/cmake_builder.rs @@ -208,6 +208,10 @@ impl crate::Builder for CmakeBuilder { && !test_nasm_command() && !is_no_asm() { + eprintln!( + "Consider setting `AWS_LC_FIPS_SYS_NO_ASM` in the environment.\ + See User Guide about the limitations: https://aws.github.io/aws-lc-rs/index.html" + ); eprintln!("Missing dependency: nasm is required for FIPS."); missing_dependency = true; } diff --git a/aws-lc-sys/builder/cmake_builder.rs b/aws-lc-sys/builder/cmake_builder.rs index a66315e30a1..a843780e9fb 100644 --- a/aws-lc-sys/builder/cmake_builder.rs +++ b/aws-lc-sys/builder/cmake_builder.rs @@ -166,6 +166,10 @@ impl crate::Builder for CmakeBuilder { && !test_nasm_command() && !is_no_asm() { + eprintln!( + "Consider setting `AWS_LC_SYS_NO_ASM` in the environment.\ + See User Guide about the limitations: https://aws.github.io/aws-lc-rs/index.html" + ); eprintln!("Missing dependency: nasm"); missing_dependency = true; } diff --git a/book/src/requirements/windows.md b/book/src/requirements/windows.md index 70aca4ff762..1459550be65 100644 --- a/book/src/requirements/windows.md +++ b/book/src/requirements/windows.md @@ -33,6 +33,12 @@ Use the following instructions to download **Visual Studio Build Tools 2017**. 2. Add the NASM installation directory to your PATH * `set PATH="C:\Program Files\NASM;%PATH%"` +### 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 +variables. However, this severely impacts performance and can only be used for un-optimized/debug builds. See the +notes in our [troubleshooting section](../resources.md#troubleshooting). + ## Ninja 1. [Download](https://github.com/ninja-build/ninja/releases) and install Ninja diff --git a/book/src/resources.md b/book/src/resources.md index 7087bfef598..c1eefc3ddb8 100644 --- a/book/src/resources.md +++ b/book/src/resources.md @@ -15,6 +15,11 @@ future release. Please [contact us] about any bugs you find in our build process build to use (`1`) or not use (`0`) the `bindgen-cli` instead of the pre-generated or internally generated bindings. * `AWS_LC_SYS_NO_PREFIX` | `AWS_LC_FIPS_SYS_NO_PREFIX` -- value can be set to `1` to force the build to not prefix the library nor the symbols it contains. +* `AWS_LC_SYS_NO_ASM` | `AWS_LC_FIPS_SYS_NO_ASM` -- value can be set to `1` to force the build to use C-language + implementations for all cryptographic operations. Our optimized hardware-specific assembly implementations will not + 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. ## Links From 556ebb7245d3e55becd6ca1424f89cfebcc2f78f Mon Sep 17 00:00:00 2001 From: Justin Smith Date: Tue, 30 Apr 2024 08:54:45 -0400 Subject: [PATCH 3/4] Satisfy clippy --- aws-lc-fips-sys/builder/main.rs | 2 +- aws-lc-sys/builder/main.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/aws-lc-fips-sys/builder/main.rs b/aws-lc-fips-sys/builder/main.rs index 4f316cb2aac..3b51715cd2f 100644 --- a/aws-lc-fips-sys/builder/main.rs +++ b/aws-lc-fips-sys/builder/main.rs @@ -483,7 +483,7 @@ fn invoke_external_bindgen( \n\ See our User Guide for more information about bindgen:\ https://aws.github.io/aws-lc-rs/index.html" - ) + ); } return Err("External bindgen command failed.".to_string()); } diff --git a/aws-lc-sys/builder/main.rs b/aws-lc-sys/builder/main.rs index 8ab5d52cb30..a113b26bc5b 100644 --- a/aws-lc-sys/builder/main.rs +++ b/aws-lc-sys/builder/main.rs @@ -520,7 +520,7 @@ fn invoke_external_bindgen( \n\ See our User Guide for more information about bindgen:\ https://aws.github.io/aws-lc-rs/index.html" - ) + ); } return Err("External bindgen command failed.".to_string()); } From df7b637258a88f1340475b93d7e4c281d99b09e8 Mon Sep 17 00:00:00 2001 From: Justin Smith Date: Thu, 2 May 2024 17:10:03 -0400 Subject: [PATCH 4/4] Per PR feedback --- aws-lc-fips-sys/builder/cmake_builder.rs | 2 +- aws-lc-sys/builder/cmake_builder.rs | 2 +- book/src/requirements/apple.md | 5 ++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/aws-lc-fips-sys/builder/cmake_builder.rs b/aws-lc-fips-sys/builder/cmake_builder.rs index 5835724b871..b2dab2500cd 100644 --- a/aws-lc-fips-sys/builder/cmake_builder.rs +++ b/aws-lc-fips-sys/builder/cmake_builder.rs @@ -209,7 +209,7 @@ impl crate::Builder for CmakeBuilder { && !is_no_asm() { eprintln!( - "Consider setting `AWS_LC_FIPS_SYS_NO_ASM` in the environment.\ + "Consider setting `AWS_LC_FIPS_SYS_NO_ASM` in the environment for development builds.\ See User Guide about the limitations: https://aws.github.io/aws-lc-rs/index.html" ); eprintln!("Missing dependency: nasm is required for FIPS."); diff --git a/aws-lc-sys/builder/cmake_builder.rs b/aws-lc-sys/builder/cmake_builder.rs index a843780e9fb..4b3e4739a35 100644 --- a/aws-lc-sys/builder/cmake_builder.rs +++ b/aws-lc-sys/builder/cmake_builder.rs @@ -167,7 +167,7 @@ impl crate::Builder for CmakeBuilder { && !is_no_asm() { eprintln!( - "Consider setting `AWS_LC_SYS_NO_ASM` in the environment.\ + "Consider setting `AWS_LC_SYS_NO_ASM` in the environment for development builds.\ See User Guide about the limitations: https://aws.github.io/aws-lc-rs/index.html" ); eprintln!("Missing dependency: nasm"); diff --git a/book/src/requirements/apple.md b/book/src/requirements/apple.md index 13db16f6bef..d0584161d61 100644 --- a/book/src/requirements/apple.md +++ b/book/src/requirements/apple.md @@ -1,7 +1,7 @@ # macOS & iOS Requirements -Unless the "fips" feature is enabled, building aws-lc-rs v1.7.0 (or later) for the following targets should only require -a C/C++ compiler. +Unless the "fips" feature is enabled, building aws-lc-rs v1.7.0 (or later) for macOS targets should only require +a C/C++ compiler. Builds for iOS will also require CMake. | Platform | *default* | **fips** | bindgen required? | |------------------------|------------------------|----------------------------|-------------------| @@ -9,7 +9,6 @@ a C/C++ compiler. | `x86_64-apple-darwin` | C/C++ Compiler | C/C++ Compiler, CMake & Go | No | | `aarch64-apple-ios` | C/C++ Compiler & CMake | **Not Supported** | **_Yes_** | | `x86_64-apple-ios` | C/C++ Compiler & CMake | **Not Supported** | **_Yes_** | -| _Other_ | C/C++ Compiler & CMake | **Not Supported** | **_Yes_** | ## C/C++ Compiler