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 or Visual Studio Build Tools 2017)
- Cmake (>= v3.12)
- Linux or macOS or Windows
Platform- and Feature-specific Requirements
- Linux - required for
fips
- Go - required for
fips
- libclang - required for
bindgen
and for any platform lacking pre-generated bindings (like Windows or M1 Macs)
See our User Guide for guidance on installing these 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 crate for the cryptographic implementations. The aws-lc-fips-sys crate provides bindings to AWS-LC-FIPS 2.x, 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 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 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 requires libclang
to be installed. See the
requirements
for rust-bindgen
§ring-compatibility
Although this library attempts to be fully compatible with ring (v0.16.x), 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
. See the list of supported platforms above. Ed25519KeyPair::from_pkcs8
andEd25519KeyPair::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§
- Authenticated Encryption with Associated Data (AEAD).
- Key Agreement: ECDH, including X25519.
- Block and Stream Ciphers for Encryption and Decryption.
- Constant-time operations.
- SHA-2 and the legacy SHA-1 digest algorithm.
- Serialization formats
- Error reporting.
- HMAC-based Extract-and-Expand Key Derivation Function.
- HMAC is specified in RFC 2104.
- io
ring-io
Serialization and deserialization. - Initialization Vector (IV) cryptographic primitives
- Key-Encapsulation Mechanisms (KEMs), including support for Kyber Round 3 Submission.
- Key Wrap Algorithms.
- PBKDF2 derivation and verification.
- PKCS#8 is specified in RFC 5208.
- Cryptographic pseudo-random number generation.
- RSA Signature and Encryption Support.
- Public key signatures: signing and verification.
- unstable
unstable
Unstable aws-lc-rs features.
Macros§
- References a test input file.
Functions§
- Initialize the AWS-LC library. (This should generally not be needed.)
- Indicates whether the underlying implementation is FIPS.