Introduction
aws-lc-rs is a cryptographic library using AWS Libcrypto (AWS-LC) for its cryptographic operations. This library strives to be API-compatible with the popular Rust library named ring (v0.16). It uses one of our auto-generated Foreign Function Interface (FFI) crates (either aws-lc-sys or aws-lc-fips-sys) for binding to AWS-LC for the cryptographic implementations.
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 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 (v0.16) API. Rust developers with prescribed cryptographic requirements can seamlessly integrate aws-lc-rs into their applications and deploy them into AWS Regions.
Questions, Feedback and Contributing
We use GitHub Issues 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.
Security Notification Process
If you discover a potential security issue in AWS-LC or aws-lc-rs, we ask that you notify AWS Security via our vulnerability reporting page. Please do not create a public GitHub issue.
If you package or distribute aws-lc-rs, or use aws-lc-rs as part of a large multi-user service, you may be eligible for pre-notification of future aws-lc-rs releases. Please contact aws-lc-pre-notifications@amazon.com.
License
aws-lc-rs is licensed under the Apache-2.0 or the ISC License. The aws-lc-sys and aws-lc-fips-sys libraries contain code from AWS-LC and are licensed under the ISC AND ( Apache-2.0 OR ISC ) AND OpenSSL licenses.
Requirements
This page outlines the requirements for using aws-lc-rs
on each target platform.
aws-lc-rs
uses aws-lc-sys or aws-lc-fips-sys to provide raw FFI bindings to AWS-LC. Thus,
there are additional build tools required for building these crates into your Rust application.
Linux Requirements
Unless the "fips" feature is enabled, building aws-lc-rs v1.7.0 (or later) for the following targets should only require a C/C++ compiler.
Platform | default | fips | bindgen required? |
---|---|---|---|
aarch64-unknown-linux-gnu | C/C++ Compiler | C/C++ Compiler, CMake & Go | No |
aarch64-unknown-linux-musl | C/C++ Compiler | C/C++ Compiler, CMake & Go | No |
x86_64-unknown-linux-gnu | C/C++ Compiler | C/C++ Compiler, CMake & Go | No |
x86_64-unknown-linux-musl | C/C++ Compiler | C/C++ Compiler, CMake & Go | No |
i686-unknown-linux-gnu | C/C++ Compiler | Not Supported | No |
Other | C/C++ Compiler & CMake | Not Supported | Yes |
C/C++ Compiler
Amazon Linux (AL2023)
sudo dnf groupinstall -y "Development Tools"
Ubuntu (22.04 LTS)
sudo apt-get install -y build-essential
CMake & Go
Amazon Linux (AL2023)
sudo dnf install -y cmake golang
Ubuntu (22.04 LTS)
sudo apt-get install -y cmake golang
Bindgen
On most platforms, bindgen
requires libclang
or llvm
package to be installed.
See the requirements page in
The bindgen User Guide for instructions.
libclang / LLVM
Amazon Linux (AL2023)
sudo dnf install -y clang-libs
Ubuntu (22.04 LTS)
sudo apt-get install -y libclang1
bindgen-cli
cargo install --force --locked bindgen-cli
Troubleshooting
See our troubleshooting section.
macOS & iOS Requirements
Unless the "fips" feature is enabled, building aws-lc-rs v1.7.0 (or later) for macOS targets should only require a C/C++ compiler. Builds for iOS will also require CMake.
Platform | default | fips | bindgen required? |
---|---|---|---|
aarch64-apple-darwin | C/C++ Compiler | C/C++ Compiler, CMake & Go | No |
x86_64-apple-darwin | C/C++ Compiler | C/C++ Compiler, CMake & Go | No |
aarch64-apple-ios | C/C++ Compiler & CMake | Not Supported | Yes |
x86_64-apple-ios | C/C++ Compiler & CMake | Not Supported | Yes |
C/C++ Compiler
Install Command Line Tools for Xcode which a provides a C/C++ compiler environment (LLVM).
CMake
MacPorts
sudo port install cmake
Homebrew
brew install cmake
Bindgen
On most platforms, bindgen
requires libclang
or llvm
package to be installed.
See the requirements page in
The bindgen User Guide for instructions.
MacPorts
sudo port install clang
Homebrew
brew install llvm
bindgen-cli
cargo install --force --locked bindgen-cli
FIPS build
Building with the "fips" feature on this platform will result in the creation of shared libraries (named like
libaws_lc_fips_0_xx_yy_crypto.dylib
and libaws_lc_fips_0_xx_yy_rust_wrapper.dylib
). These shared libraries will
likely need to be distributed alongside any executable that depends on aws-lc-rs.
Troubleshooting
See our troubleshooting section.
Windows Requirements
Platform | default | fips | bindgen required? |
---|---|---|---|
x86_64-pc-windows-msvc | C/C++ Compiler, CMake & *NASM | C/C++ Compiler, CMake, NASM, Go & Ninja | No |
x86_64-pc-windows-gnu | C/C++ Compiler, CMake & *NASM | Not Supported | No |
i686-pc-windows-msvc | C/C++ Compiler, CMake & NASM | Not Supported | No |
aarch64-pc-windows-msvc | C/C++ Compiler (MSVC's clang-cl ) & CMake | Not Supported | No |
Other | Not Supported | Not Supported | N/A |
- The NASM assembler is recommended on
x86-64
platforms. NASM is required forx86
and for "fips" builds. See the Prebuilt NASM objects section below.
C/C++ Compiler
Use the following instructions to download Visual Studio Build Tools 2017 or later.
- Download the Build Tools for Visual Studio installer.
- Execute the installer.
- If you have an existing installation chose
Modify
on the existing installation. - Under
Workloads
selectVisual C++ build tools
- Under
Individual componenets
selectC++/CLI support
C++ CMake tools for Windows
- For ARM64/aarch64 support, also select:
C++ Clang Compiler for Windows
MSBuild support for LLVM (clang-cl) toolset
- Confirm selections and click
Install
CMake
- Download Windows CMake Installer
- Execute the installer
- Add the CMake installation binary directory to your PATH.
set PATH="C:\Program Files\CMake\bin;%PATH%"
NASM
- Download and install the Netwide Assembler (NASM)
- Add the NASM installation directory to your PATH
set PATH="C:\Program Files\NASM;%PATH%"
Use of prebuilt NASM objects
For Windows x86 and x86-64, NASM is required for assembly code compilation. On these platforms, we recommend that you install the NASM assembler. If NASM is detected in the build environment it is used to compile the assembly files. However, if a NASM assembler is not available, and the "fips" feature is not enabled, then the build fails unless one of the following conditions are true:
- 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 AWS_LC_SYS_PREBUILT_NASM
is not found in the environment AND the "prebuilt-nasm" feature has been enabled.
- The
If the above cases apply, then the crate provided prebuilt NASM objects will be used for the build. To prevent usage of
prebuilt NASM
objects, install NASM in the build environment and/or set the variable AWS_LC_SYS_PREBUILT_NASM
to 0
in the build
environment to prevent their use.
About prebuilt NASM objects
Prebuilt NASM objects are generated using automation similar to the crate provided pregenerated bindings. See the repositories GitHub workflow configuration for more information. The prebuilt NASM objects are checked into the repository and are available for inspection. For each PR submitted, CI verifies that the NASM objects newly built from source match the NASM objects currently in the repository.
No-assembly build
It is possible to avoid the NASM requirement by setting the AWS_LC_SYS_NO_ASM
/AWS_LC_FIPS_SYS_NO_ASM
environment
variables. However, this severely impacts performance and can only be used for un-optimized/debug builds. See the
notes in our troubleshooting section.
Ninja
- Download and install Ninja
- Add the Ninja installation directory to your PATH
set PATH="C:\ninja\ninja_build;%PATH%"
Bindgen
Bindgen is not required for most Windows targets, but it can still be used if needed.
Using bindgen
requires a libclang
or llvm
package to be installed.
See the requirements page in
[The bindgen User Guide] for instructions.
libclang / LLVM
- Download LLVM Installer
- Execute the installer
- Update your environment to set
LIBCLANG_PATH
to the bin directory inside LLVM install directory.set LIBCLANG_PATH="C:\Program Files\LLVM\bin"
bindgen-cli
cargo install --force --locked bindgen-cli
FIPS build
Building with the "fips" feature on this platform will result in the creation of shared libraries (named like
aws_lc_fips_0_xx_yy_crypto.dll
and aws_lc_fips_0_xx_yy_rust_wrapper.dll
). These shared libraries will likely need to
be distributed alongside any executable that depends on aws-lc-rs.
Troubleshooting
See our troubleshooting section.
Platform Support
Pre-generated bindings
aws-lc-rs
can utilize pre-generated bindings when operating on the following
build targets.
Platform | aws-lc-sys | aws-lc-fips-sys |
---|---|---|
aarch64-apple-darwin | X | X |
aarch64-pc-windows-msvc | X | Not Supported |
aarch64-unknown-linux-gnu | X | X |
aarch64-unknown-linux-musl | X | X |
i686-pc-windows-msvc | X | Not Supported |
i686-unknown-linux-gnu | X | Not Supported |
x86_64-apple-darwin | X | X |
x86_64-pc-windows-gnu | X | Not Supported |
x86_64-pc-windows-msvc | X | |
x86_64-unknown-linux-gnu | X | X |
x86_64-unknown-linux-musl | X | X |
Tested platforms
In addition to the ones listed above, the aws-lc-rs
CI builds and/or tests with the following platforms.
All platforms listed below require CMake
to be available in the build environment.
They also require bindings to be generated during the build process.
bindgen
One of the following options must be used for bindings generation. See requirements page for more information.
- Enable
bindgen
feature in yourCargo.toml
:
[dependencies]
aws-lc-rs = { version = "1", features = ["bindgen"] }
-- OR --
- Install
bindgen-cli
in the build envionment:
cargo install --force --locked bindgen-cli
Platforms
Platform | Build | Tests |
---|---|---|
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 |
powerpc64le-unknown-linux-gnu | X | X |
powerpc64-unknown-linux-gnu | X | X |
powerpc-unknown-linux-gnu | X | X |
riscv64gc-unknown-linux-gnu | X | X |
s390x-unknown-linux-gnu | X | X |
x86_64-apple-ios | X | |
x86_64-pc-windows-gnu | X | X |
x86_64-pc-windows-msvc | X | X |
Frequently Asked Questions
What are the differences between aws-lc-rs
and ring
?
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?
The answer to this question is dependent on several factors based on the target environment:
- Must be a platform and CPU architecture supported by AWS-LC.
- Must be a platform supported by the Rust compiler with support for the full standard library. See the Rust compiler's platform support documentation.
- If the underlying
aws-lc-sys
oraws-lc-fips-sys
crates don't have pre-generated bindings for the desired platform then you must use thebindgen
crate feature ofaws-lc-rs
, or have the bindgen-cli installed, to enable generation of the FFI bindings for the desired platform and architecture. - See Requirements and Platform Support 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.
Resources
Troubleshooting
There are a few environment variables that may help in diagnosing/remdiating build problem. These affect the way that
aws-lc-sys
or aws-lc-fips-sys
build the underlying AWS-LC library.
None of the environment variables below are officially supported, and any one of them might be removed or changed on a future release. Please contact us about any bugs you find in our build process.
AWS_LC_SYS_STATIC
|AWS_LC_FIPS_SYS_STATIC
-- value can be set to0
or1
to force the resulting build artifact to be shared library (e.g.,*.so
) or static library (e.g.,*.a
).AWS_LC_SYS_CMAKE_BUILDER
-- value can be set to1
or0
to force the build to use (1
) or not use (0
) CMake.AWS_LC_SYS_EXTERNAL_BINDGEN | ``AWS_LC_FIPS_SYS_EXTERNAL_BINDGEN
-- value can be set to1
or0
to force the build to use (1
) or not use (0
) thebindgen-cli
instead of the pre-generated or internally generated bindings.AWS_LC_SYS_NO_PREFIX
|AWS_LC_FIPS_SYS_NO_PREFIX
-- value can be set to1
to force the build to not prefix the library nor the symbols it contains.AWS_LC_SYS_NO_ASM
|AWS_LC_FIPS_SYS_NO_ASM
-- value can be set to1
to force the build to use C-language implementations for all cryptographic operations. Our optimized hardware-specific assembly implementations will not be used. This option is only available for unoptimized (i.e.,OPT_LEVEL = "0"
or "debug") builds. WARNING: Performance on most platforms is extremely limited by this option. Certain security properties, such as resistance to timing attacks, can only be provided when assembly code is used.AWS_LC_SYS_PREBUILT_NASM
-- value can be set to1
to allow the build to use our prebuilt NASM objects. The value can be set to0
to prevent our prebuilt NASM objects from being used. See the section on Prebuilt NASM objects for more information.AWS_LC_SYS_CFLAGS
-- if value is set, it will be used as the value ofCFLAGS
in the environment when the AWS-LC build is performed.AWS_LC_SYS_C_STD
-- value can be set to determine the C standard used by the C compiler. It may be set to either99
for C99 or11
for C11. On most platforms, C11 will be used by default.