Crate aws_lc_rs

source ·
Expand description

A ring-compatible crypto library using the cryptographic operations provided by AWS-LC. It uses either the auto-generated aws-lc-sys or 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. It can be added to your project in the standard way using Cargo.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)
  • Cmake (> v3.12) is required to build.

Feature-specific Requirements

Contributor Quickstart for Amazon Linux 2023

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.

# Install CMake, Clang, Git, Libclang and Golang
sudo yum install -y cmake3 clang git clang-libs golang openssl-devel

# Install Rust
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
cd aws-lc-rs
git submodule update --init --recursive

# Build and test the project
cargo test

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

EXPERIMENTAL Enable this feature to have aws-lc-rs use the aws-lc-fips-sys crate for the cryptographic implementations. The aws-lc-fips-sys crate provides bindings to the FIPS variant of AWS-LC. AWS-LC has been submitted to an accredited lab for FIPS validation testing, and upon completion will be submitted to NIST for certification. Once NIST grants a validation certificate to AWS-LC, we will make an announcement to Rust developers on how to leverage the FIPS mode. This feature is currently only available on Linux.

- asan

Performs an “address sanitizer” build. This can be used to help detect memory leaks. See the “Address Sanitizer” section of the Rust 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 require libclang to be installed. See the requirements for rust-bindgen

ring-compatibility

Although this library attempts to be fully compatible with ring, there are a few places where our behavior is observably different.

  • Our implementation requires the std library. We currently do not support a #![no_std] build.
  • We can only support a subset of the platforms supported by aws-lc-sys. We currently support Mac and Linux, both x86-64 and aarch64.
  • 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.

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 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.

Modules

  • aead
    Authenticated Encryption with Associated Data (AEAD).
  • agreement
    Key Agreement: ECDH, including X25519.
  • constant_time
    Constant-time operations.
  • digest
    SHA-2 and the legacy SHA-1 digest algorithm.
  • error
    Error reporting.
  • hkdf
    HMAC-based Extract-and-Expand Key Derivation Function.
  • hmac
    HMAC is specified in RFC 2104.
  • io
    Serialization and deserialization.
  • pbkdf2
    PBKDF2 derivation and verification.
  • pkcs8
    PKCS#8 is specified in RFC 5208.
  • rand
    Cryptographic pseudo-random number generation.
  • signature
    Public key signatures: signing and verification.
  • test
    Testing framework.

Macros

Functions

  • init
    Initialize the AWS-LC library. (This should generally not be needed.)
  • try_fips_mode
    Indicates whether the underlying implementation is FIPS.