Update docs; add aarch64-pc-windows-msvc (#422)

README.md

@@ -3,40 +3,48 @@
 [![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 Libcrypto for Rust
+
 [*aws-lc-rs*](aws-lc-rs/README.md) is a cryptographic library using [AWS-LC](https://github.com/aws/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). It uses either the auto-generated [*aws-lc-sys*](aws-lc-sys/README.md) or [
-*aws-lc-fips-sys*](aws-lc-fips-sys/README.md) Foreign Function Interface (FFI) crates found in this
+[ring](https://github.com/briansmith/ring) (v0.16). It uses either the auto-generated
+[*aws-lc-sys*](aws-lc-sys/README.md) or
+[*aws-lc-fips-sys*](aws-lc-fips-sys/README.md) Foreign Function Interface (FFI) crates found in this
 repository for invoking *AWS-LC*.
 
 ## Crates
 
 ### [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-sys](aws-lc-sys/README.md)
+
 **Autogenerated** Low-level AWS-LC bindings for the Rust programming language.
 We do not recommend directly relying on these bindings.
 
 ### [aws-lc-fips-sys](aws-lc-fips-sys/README.md)
+
 **Autogenerated** Low-level AWS-LC bindings for the Rust programming language, providing FIPS support.
 We do not recommend directly relying on these bindings. This crate provides bindings to
 [AWS-LC-FIPS 2.x](https://github.com/aws/aws-lc/tree/fips-2022-11-02), which has completed
-FIPS validation testing by an accredited lab and has been submitted to NIST for certification. The static build of AWS-LC-FIPS
-is used. (See [README](./aws-lc-fips-sys/README.md)).  
+FIPS validation testing by an accredited lab and has been submitted to NIST for certification. The static build of
+AWS-LC-FIPS
+is used. (See [README](./aws-lc-fips-sys/README.md)).
 
-Refer to the [NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List)
-for the latest status of the static or dynamic AWS-LC Cryptographic Module. A complete list of supported operating environments will be
-made available in the vendor security policy once the validation certificate has been issued. We will also update our release notes
-and documentation to reflect any changes in FIPS certification status.
+Refer to the
+[NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List)
+for the latest status of the static or dynamic AWS-LC Cryptographic Module. A complete list of supported operating
+environments will be made available in the vendor security policy once the validation certificate has been issued. We
+will also update our release notes and documentation to reflect any changes in FIPS certification status.
 
 ## Build
 
 Please see the [build instructions](aws-lc-rs/README.md#Build) in the aws-lc-rs crate.
 
 # 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
@@ -50,7 +58,8 @@ cryptographic requirements can seamlessly integrate aws-lc-rs into their applica
 * [API documentation](https://docs.rs/aws-lc-rs/)
 * [Fork our repo](https://github.com/awslabs/aws-lc-rs/fork)
 
-We use [GitHub Issues](https://github.com/awslabs/aws-lc-rs/issues/new/choose) for managing feature requests, bug reports, or questions about aws-lc-rs API usage.
+We use [GitHub Issues](https://github.com/awslabs/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
 follow our *Security Notification Process* below.

aws-lc-rs/README.md

@@ -5,69 +5,66 @@
 
 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
-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)
+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*.
 
 ## Build
 
 `aws-lc-rs` is available through [crates.io](https://crates.io/crates/aws-lc-rs). It can
 be added to your project in the [standard way](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html)
 using `Cargo.toml`:
+
 ```toml
 [dependencies]
 aws-lc-rs = "1.0.0"
 ```
-Consuming projects will need a C Compiler (Clang or GCC) and Cmake to build.
-
-**Requirements**:
-* C compiler (Clang or GCC or Visual Studio Build Tools 2017)
-* Cmake (>= v3.12)
-* Linux or [macOS](https://www.apple.com/macos) or Windows
-
-**Platform- and Feature-specific Requirements**
-  * Linux - required for `fips`
-  * [Go](https://go.dev/) - required for `fips`
-  * [libclang](https://llvm.org/) - required for `bindgen` and for any platform lacking pre-generated bindings (like Windows or M1 Macs)
+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 these requirements.
+See our [User Guide](https://awslabs.github.io/aws-lc-rs/) for guidance on installing build requirements.
 
 
 ## Feature Flags
 
 ##### alloc (default)
+
 Allows implementation to allocate values of arbitrary size. (The meaning of this feature differs
 from the "alloc" feature of *ring*.) Currently, this is required by the `io::writer` module.
 
 ##### ring-io (default)
+
 Enable feature to access the  `io`  module.
 
 ##### ring-sig-verify (default)
+
 Enable feature to preserve compatibility with ring's `signature::VerificationAlgorithm::verify`
 function. This adds a requirement on `untrusted = "0.7.1"`.
 
 ##### fips
+
 Enable this feature to have aws-lc-rs use the [*aws-lc-fips-sys*](https://crates.io/crates/aws-lc-fips-sys)
 crate for the cryptographic implementations. The *aws-lc-fips-sys* crate provides bindings to
 [AWS-LC-FIPS 2.x](https://github.com/aws/aws-lc/tree/fips-2022-11-02), which has completed
 FIPS validation testing by an accredited lab and has been submitted to NIST for certification.
 The static build of AWS-LC-FIPS is used.
 
-| Supported Targets |
-| --- |
-| x86_64-unknown-linux-gnu |
-| aarch64-unknown-linux-gnu |
-
-Refer to the [NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List)
-for the latest status of the static or dynamic AWS-LC Cryptographic Module. A complete list of supported operating environments will be
-made available in the vendor security policy once the validation certificate has been issued. We will also update our release notes
+Refer to the
+[NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List)
+for the latest status of the static or dynamic AWS-LC Cryptographic Module. A complete list of supported operating
+environments will be made available in the vendor security policy once the validation certificate has been issued. We
+will also update our release notes
 and documentation to reflect any changes in FIPS certification status.
 
 ##### asan
+
 Performs an "address sanitizer" build. This can be used to help detect memory leaks. See the
 ["Address Sanitizer" section](https://doc.rust-lang.org/beta/unstable-book/compiler-flags/sanitizer.html#addresssanitizer)
 of the [Rust Unstable Book](https://doc.rust-lang.org/beta/unstable-book/).
 
 ##### bindgen
+
 Causes `aws-lc-sys` or `aws-lc-fips-sys` to generates fresh bindings for AWS-LC instead of using
 the pre-generated bindings. This feature requires `libclang` to be installed. See the
 [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html)
@@ -79,13 +76,13 @@ Although this library attempts to be fully compatible with *ring* (v0.16.x), the
 behavior is observably different.
 
 * Our implementation requires the `std` library. We currently do not support a
-[`#![no_std]`](https://docs.rust-embedded.org/book/intro/no-std.html) build.
+  [`#![no_std]`](https://docs.rust-embedded.org/book/intro/no-std.html) build.
 * We can only support a subset of the platforms supported by `aws-lc-sys`. See the list of
-supported platforms above.
+  supported platforms above.
 * `Ed25519KeyPair::from_pkcs8` and `Ed25519KeyPair::from_pkcs8_maybe_unchecked` both support
-parsing of v1 or v2 PKCS#8 documents. If a v2 encoded key is provided to either function,
-public key component, if present, will be verified to match the one derived from the encoded
-private key.
+  parsing of v1 or v2 PKCS#8 documents. If a v2 encoded key is provided to either function,
+  public key component, if present, will be verified to match the one derived from the encoded
+  private key.
 
 ## Motivation
 
@@ -127,7 +124,8 @@ cargo test
 * [API documentation](https://docs.rs/aws-lc-rs/)
 * [Fork our repo](https://github.com/awslabs/aws-lc-rs/fork)
 
-We use [GitHub Issues](https://github.com/awslabs/aws-lc-rs/issues/new/choose) for managing feature requests, bug reports, or questions about aws-lc-rs API usage.
+We use [GitHub Issues](https://github.com/awslabs/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
 follow our *Security Notification Process* below.

aws-lc-rs/README.tpl

@@ -34,7 +34,8 @@ cargo test
 * [API documentation](https://docs.rs/aws-lc-rs/)
 * [Fork our repo](https://github.com/awslabs/aws-lc-rs/fork)
 
-We use [GitHub Issues](https://github.com/awslabs/aws-lc-rs/issues/new/choose) for managing feature requests, bug reports, or questions about aws-lc-rs API usage.
+We use [GitHub Issues](https://github.com/awslabs/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
 follow our *Security Notification Process* below.

aws-lc-rs/src/lib.rs

@@ -3,71 +3,69 @@
 // Modifications copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0 OR ISC
 
+#![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
-//! 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)
+//! 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*.
 //!
 //! # Build
 //!
 //! `aws-lc-rs` is available through [crates.io](https://crates.io/crates/aws-lc-rs). It can
 //! be added to your project in the [standard way](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html)
 //! using `Cargo.toml`:
+//!
 //! ```toml
 //! [dependencies]
 //! aws-lc-rs = "1.0.0"
 //! ```
-//! Consuming projects will need a C Compiler (Clang or GCC) and Cmake to build.
-//!
-//! **Requirements**:
-//! * C compiler (Clang or GCC or Visual Studio Build Tools 2017)
-//! * Cmake (>= v3.12)
-//! * Linux or [macOS](https://www.apple.com/macos) or Windows
-//!
-//! **Platform- and Feature-specific Requirements**
-//!   * Linux - required for `fips`
-//!   * [Go](https://go.dev/) - required for `fips`
-//!   * [libclang](https://llvm.org/) - required for `bindgen` and for any platform lacking pre-generated bindings (like Windows or M1 Macs)
+//! 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 these requirements.
+//! See our [User Guide](https://awslabs.github.io/aws-lc-rs/) for guidance on installing build requirements.
 //!
 //!
 //! # Feature Flags
 //!
 //! #### alloc (default)
+//!
 //! Allows implementation to allocate values of arbitrary size. (The meaning of this feature differs
 //! from the "alloc" feature of *ring*.) Currently, this is required by the `io::writer` module.
 //!
 //! #### ring-io (default)
+//!
 //! Enable feature to access the  `io`  module.
 //!
 //! #### ring-sig-verify (default)
+//!
 //! Enable feature to preserve compatibility with ring's `signature::VerificationAlgorithm::verify`
 //! function. This adds a requirement on `untrusted = "0.7.1"`.
 //!
 //! #### fips
+//!
 //! Enable this feature to have aws-lc-rs use the [*aws-lc-fips-sys*](https://crates.io/crates/aws-lc-fips-sys)
 //! crate for the cryptographic implementations. The *aws-lc-fips-sys* crate provides bindings to
 //! [AWS-LC-FIPS 2.x](https://github.com/aws/aws-lc/tree/fips-2022-11-02), which has completed
 //! FIPS validation testing by an accredited lab and has been submitted to NIST for certification.
 //! The static build of AWS-LC-FIPS is used.
 //!
-//! | Supported Targets |
-//! | --- |
-//! | x86_64-unknown-linux-gnu |
-//! | aarch64-unknown-linux-gnu |
-//!
-//! Refer to the [NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List)
-//! for the latest status of the static or dynamic AWS-LC Cryptographic Module. A complete list of supported operating environments will be
-//! made available in the vendor security policy once the validation certificate has been issued. We will also update our release notes
+//! Refer to the
+//! [NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List)
+//! for the latest status of the static or dynamic AWS-LC Cryptographic Module. A complete list of supported operating
+//! environments will be made available in the vendor security policy once the validation certificate has been issued. We
+//! will also update our release notes
 //! and documentation to reflect any changes in FIPS certification status.
 //!
 //! #### asan
+//!
 //! Performs an "address sanitizer" build. This can be used to help detect memory leaks. See the
 //! ["Address Sanitizer" section](https://doc.rust-lang.org/beta/unstable-book/compiler-flags/sanitizer.html#addresssanitizer)
 //! of the [Rust Unstable Book](https://doc.rust-lang.org/beta/unstable-book/).
 //!
 //! #### bindgen
+//!
 //! Causes `aws-lc-sys` or `aws-lc-fips-sys` to generates fresh bindings for AWS-LC instead of using
 //! the pre-generated bindings. This feature requires `libclang` to be installed. See the
 //! [requirements](https://rust-lang.github.io/rust-bindgen/requirements.html)
@@ -79,13 +77,13 @@
 //! behavior is observably different.
 //!
 //! * Our implementation requires the `std` library. We currently do not support a
-//! [`#![no_std]`](https://docs.rust-embedded.org/book/intro/no-std.html) build.
+//!   [`#![no_std]`](https://docs.rust-embedded.org/book/intro/no-std.html) build.
 //! * We can only support a subset of the platforms supported by `aws-lc-sys`. See the list of
-//! supported platforms above.
+//!   supported platforms above.
 //! * `Ed25519KeyPair::from_pkcs8` and `Ed25519KeyPair::from_pkcs8_maybe_unchecked` both support
-//! parsing of v1 or v2 PKCS#8 documents. If a v2 encoded key is provided to either function,
-//! public key component, if present, will be verified to match the one derived from the encoded
-//! private key.
+//!   parsing of v1 or v2 PKCS#8 documents. If a v2 encoded key is provided to either function,
+//!   public key component, if present, will be verified to match the one derived from the encoded
+//!   private key.
 //!
 //! # Motivation
 //!

book/src/faq.md

@@ -5,7 +5,7 @@
 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?
+## 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:
 
@@ -15,8 +15,8 @@ The answer to this question is dependent on several factors based on the target
 * 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`, 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.
+* See [Requirements](requirements/README.md) and [Platform Support](./platform_suppport.md) for more details on
+  build requirements for various platforms.
 
 If there is a platform or architecture you are interested in seeing support for, please create a GitHub [issue].
 

book/src/platform_support.md

@@ -47,6 +47,7 @@ cargo install --force --locked bindgen-cli
 |---------------------------------|-------|-------|
 | `aarch64-apple-ios`             | X     | X     |
 | `aarch64-linux-android`         | X     | X     |
+| `aarch64-pc-windows-msvc`       | X     |       | 
 | `armv7-linux-androideabi`       | X     | X     | 
 | `arm-linux-androideabi`         | X     | X     |
 | `arm-unknown-linux-gnueabihf`   | X     | X     |