Updates for User Guide (#400)

* Updates for User Guide * Note about AWS_LC_SYS_NO_ASM * Satisfy clippy * Per PR feedback
aws · May 2, 2024 · beaf5e2 · beaf5e2
1 parent a9bc038
commit beaf5e2
Show file tree

Hide file tree

Showing 15 changed files with 306 additions and 101 deletions.
diff --git 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 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.");
             missing_dependency = true;
         }

diff --git 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<String>,
     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/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 for development builds.\
+            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/aws-lc-sys/builder/main.rs b/aws-lc-sys/builder/main.rs
@@ -511,8 +511,18 @@ fn invoke_external_bindgen(
     prefix: &Option<String>,
     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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,63 @@
+# macOS & iOS Requirements
+
+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? |
+|------------------------|------------------------|----------------------------|-------------------|
+| `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_**         |
+
+## 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/