aws-lc-rs

What is aws-lc-rs?

aws-lc-rs is a cryptographic library for Rust that uses AWS Libcrypto (AWS-LC) for its cryptographic operations.

Key Features

• API Compatibility: It is designed to be API-compatible with the ring library (specifically v0.16), allowing it to serve as a drop-in replacement.
• FIPS Support: It is intended for developers who need to meet US and Canadian government cryptographic requirements (FIPS) while maintaining idiomatic and performant Rust code.
• FFI Bindings: The library uses auto-generated Foreign Function Interface (FFI) crates—either aws-lc-sys or aws-lc-fips-sys—to bind to the underlying AWS-LC implementations.

When to use it

Use aws-lc-rs if you are currently using ring but need to deploy applications into AWS Regions that require FIPS-validated cryptography.

AWS Libcrypto for Rust is a cryptographic library that uses AWS-LC for its cryptographic operations. It is designed to be an API-compatible, drop-in replacement for the ring (v0.16) library, specifically aimed at providing FIPS-validated cryptography for Rust developers who need to meet US and Canadian government requirements.

It achieves this by using either the aws-lc-sys or aws-lc-fips-sys FFI crates to invoke the underlying AWS-LC implementation.

The aws-lc-fips-sys crate provides autogenerated low-level AWS-LC FIPS bindings for the Rust programming language. It is designed to link against the AWS-LC-FIPS module that has completed FIPS validation testing and has been submitted to NIST for certification.

Warning: This crate provides low-level bindings. Direct reliance on these bindings is not recommended for most users; instead, use higher-level crates like aws-lc-rs.

When AWS_LC_SYS_SYSTEM_DIR is unset, the build script attempts to discover a usable AWS-LC using the following precedence:

1. AWS_LC_SYS_SYSTEM_DIR: Explicit install prefix.
2. OPENSSL_DIR: Install prefix.
3. OPENSSL_INCLUDE_DIR and OPENSSL_LIB_DIR: Independent header and library directories.
4. pkg-config (Unix only): Probes openssl, aws-lc, libcrypto, then libcrypto-awslc.

Each OPENSSL_* variable also supports a target-suffixed form (e.g., OPENSSL_DIR_x86_64_unknown_linux_gnu).

Requirements for a discovered install:

• Must contain include/openssl/base.h (used to verify the OPENSSL_IS_AWSLC marker and version).
• Must contain lib/ or lib64/ containing libcrypto (and libssl if the ssl feature is enabled).
• Must satisfy the minimum version requirement (defined by MINIMUM_AWS_LC_VERSION).
• Must provide usable bindings.

While aws-lc-rs aims for full compatibility with ring (v0.16.x), there are key differences to note:

• Standard Library Requirement: aws-lc-rs requires the std library and does not support #[no_std] builds.
• Platform Support: It supports platforms compatible with aws-lc-sys and AWS-LC.
• PKCS#8 Parsing: Ed25519KeyPair::from_pkcs8 and Ed25519KeyPair::from_pkcs8_maybe_unchecked support both v1 and v2 PKCS#8 documents. For v2 documents, the public key component (if present) is verified against the derived private key.

The crate requires a minimum AWS-LC FIPS module version (an integer identifying a validation submission). Currently, the minimum supported version is 3.

To ensure you are using the correct version of the FIPS module, refer to the following compatibility mapping:

If you need to remain on a specific version of the AWS-LC-FIPS module for compliance, you should pin your aws-lc-rs dependency to a compatible version in your Cargo.toml.

To bypass the version check (not recommended), set the environment variable AWS_LC_FIPS_SYS_SYSTEM_SKIP_VERSION_CHECK=1.

Whether you need bindgen installed depends on which crate you are using and whether pre-generated bindings are available for your platform.

• For aws-lc-rs users (Non-FIPS): You do not need bindgen. aws-lc-rs uses pre-generated "universal" bindings that work across all supported platforms.
• For aws-lc-sys direct users: If you depend on aws-lc-sys directly rather than through aws-lc-rs, it defaults to target-specific bindings, which may require bindgen.
• For FIPS (aws-lc-fips-sys) users: bindgen is required for most targets. It is only unnecessary if your specific target platform is included in the limited set of targets with pre-generated FIPS bindings.

The project is composed of several crates with different levels of abstraction:

• aws-lc-rs: The primary high-level crate. It is a ring-compatible crypto library that uses AWS-LC. This is the crate most end-users should use.
• aws-lc-sys: Low-level, autogenerated FFI bindings for AWS-LC. Direct use is not recommended.
• aws-lc-fips-sys: Low-level, autogenerated FFI bindings providing FIPS support (specifically AWS-LC-FIPS 3.x). This crate is used for FIPS-compliant requirements. Direct use is not recommended.