Skip to content

Commit

Permalink
Update READMEs
Browse files Browse the repository at this point in the history
  • Loading branch information
@justsmth
justsmth committed Aug 30, 2024
1 parent c181926 commit 4ae23a8
Show file tree
Hide file tree
Showing 8 changed files with 170 additions and 42 deletions.
8 changes: 4 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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
Expand Down
16 changes: 12 additions & 4 deletions aws-lc-fips-sys/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions aws-lc-rs/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/*",
Expand Down
3 changes: 3 additions & 0 deletions aws-lc-rs/Makefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
52 changes: 44 additions & 8 deletions aws-lc-rs/README.md
View file
Original file line number Diff line number Diff line change
@@ -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*.
Expand All @@ -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

Expand Down Expand Up @@ -70,6 +70,41 @@ 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 our prebuilt NASM objects in certain situations. This only affect builds for
the Windows/x86-64 platforms. This feature is ignored if the "fips" feature is also enabled.
Use of prebuilt NASM objects will be prevented if either:
a NASM assembler is installed in the build environment
and/or `AWS_LC_SYS_PREBUILT_NASM` 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, the AWS-LC assembly code requires NASM to build. On these platforms,
we recommend that you install [the NASM assembler](https://www.nasm.us/). If a NASM assembler is
found during the build process, then it *will* be used to compile the assembly files. However,
if a NASM assembler is not found, then the (non-"fips") build may fail except in the following case:

* 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 the value is empty); 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 our prebuilt NASM objects may be used for the build. To prevent our prebuilt NASM
objects from being used, please install NASM and/or set `AWS_LC_SYS_PREBUILT_NASM=0` in your build environment to prevent their use.

### About prebuilt NASM objects

Our prebuilt NASM objects are generated using the same automation that produces our pregenerated bindings. See our
[GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml).
The prebuilt NASM objects are checked into our 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,
[our 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
Expand Down Expand Up @@ -100,6 +135,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
Expand All @@ -109,7 +145,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

Expand All @@ -120,11 +156,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
Expand Down
11 changes: 6 additions & 5 deletions aws-lc-rs/README.tpl
View file
Original file line number Diff line number Diff line change
@@ -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}}

Expand All @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down
41 changes: 38 additions & 3 deletions aws-lc-rs/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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*.
Expand All @@ -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
//!
Expand Down Expand Up @@ -71,6 +71,41 @@
//! [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 our prebuilt NASM objects in certain situations. This only affect builds for
//! the Windows/x86-64 platforms. This feature is ignored if the "fips" feature is also enabled.
//! Use of prebuilt NASM objects will be prevented if either:
//! a NASM assembler is installed in the build environment
//! and/or `AWS_LC_SYS_PREBUILT_NASM` 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, the AWS-LC assembly code requires NASM to build. On these platforms,
//! we recommend that you install [the NASM assembler](https://www.nasm.us/). If a NASM assembler is
//! found during the build process, then it *will* be used to compile the assembly files. However,
//! if a NASM assembler is not found, then the (non-"fips") build may fail except in the following case:
//!
//! * 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 the value is empty); 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 our prebuilt NASM objects may be used for the build. To prevent our prebuilt NASM
//! objects from being used, please install NASM and/or set `AWS_LC_SYS_PREBUILT_NASM=0` in your build environment to prevent their use.
//!
//! ## About prebuilt NASM objects
//!
//! Our prebuilt NASM objects are generated using the same automation that produces our pregenerated bindings. See our
//! [GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml).
//! The prebuilt NASM objects are checked into our 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,
//! [our 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
Expand Down
77 changes: 61 additions & 16 deletions aws-lc-sys/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,81 @@
# 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, the AWS-LC assembly code requires NASM to build. On these platforms,
we recommend that you install [the NASM assembler](https://www.nasm.us/). If a NASM assembler is
found during the build process, then it *will* be used to compile the assembly files. However,
if a NASM assembler is not found, then the build may fail except in the following case:

* 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 the value is empty); 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 our prebuilt NASM objects may be used for the build. To prevent our prebuilt NASM
objects from being used, please install NASM and/or set `AWS_LC_SYS_PREBUILT_NASM=0` in your build environment to
prevent their use.

#### About prebuilt NASM objects

Our prebuilt NASM objects are generated using the same automation that produces our pregenerated bindings. See our
[GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml).
The prebuilt NASM objects are checked into our 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,
[our 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

Expand All @@ -45,8 +90,8 @@ Please contact [email protected].

## 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)

0 comments on commit 4ae23a8

Please sign in to comment.