|
1 | | -# AWS Libcrypto for Rust (aws-lc-rs) |
| 1 | +# wolfcrypt-ring-compat |
2 | 2 |
|
3 | | -[](https://crates.io/crates/aws-lc-rs) |
4 | | -[](https://github.com/aws/aws-lc-rs) |
| 3 | +API-compatible replacement for the [`ring`](https://crates.io/crates/ring) crate, backed by wolfCrypt instead of BoringSSL. |
5 | 4 |
|
6 | | -A [*ring*](https://github.com/briansmith/ring)-compatible crypto library using the cryptographic |
7 | | -operations provided by [*AWS-LC*](https://github.com/aws/aws-lc). It uses either the |
8 | | -auto-generated [*aws-lc-sys*](https://crates.io/crates/aws-lc-sys) or |
9 | | -[*aws-lc-fips-sys*](https://crates.io/crates/aws-lc-fips-sys) |
10 | | -Foreign Function Interface (FFI) crates found in this repository for invoking *AWS-LC*. |
11 | | - |
12 | | -## Build |
13 | | - |
14 | | -`aws-lc-rs` is available through [crates.io](https://crates.io/crates/aws-lc-rs). It can |
15 | | -be added to your project in the [standard way](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) |
16 | | -using `Cargo.toml`: |
| 5 | +## Usage |
17 | 6 |
|
18 | 7 | ```toml |
19 | | -[dependencies] |
20 | | -aws-lc-rs = "1" |
21 | | -``` |
22 | | -Consuming projects will need a C/C++ compiler to build. |
23 | | - |
24 | | -**Non-FIPS builds (default):** |
25 | | -* CMake is **never** required |
26 | | -* Bindgen is **never** required (pre-generated bindings are provided) |
27 | | -* Go is **never** required |
28 | | - |
29 | | -**FIPS builds:** Require **CMake**, **Go**, and potentially **bindgen** depending on the target platform. |
30 | | - |
31 | | -See our [User Guide](https://aws.github.io/aws-lc-rs/) for guidance on installing build requirements. |
32 | | - |
33 | | -## Feature Flags |
34 | | - |
35 | | -##### alloc (default) |
36 | | - |
37 | | -Allows implementation to allocate values of arbitrary size. (The meaning of this feature differs |
38 | | -from the "alloc" feature of *ring*.) Currently, this is required by the `io::writer` module. |
39 | | - |
40 | | -##### ring-io (default) |
41 | | - |
42 | | -Enable feature to access the `io` module. |
43 | | - |
44 | | -##### ring-sig-verify (default) |
45 | | - |
46 | | -Enable feature to preserve compatibility with ring's `signature::VerificationAlgorithm::verify` |
47 | | -function. This adds a requirement on `untrusted = "0.7.1"`. |
48 | | - |
49 | | -##### fips |
50 | | - |
51 | | -Enable this feature to have aws-lc-rs use the [*aws-lc-fips-sys*](https://crates.io/crates/aws-lc-fips-sys) |
52 | | -crate for the cryptographic implementations. The aws-lc-fips-sys crate provides bindings to the |
53 | | -latest version of the AWS-LC-FIPS module that has completed FIPS validation testing by an |
54 | | -accredited lab and has been submitted to NIST for certification. This will continue to be the |
55 | | -case as we periodically submit new versions of the AWS-LC-FIPS module to NIST for certification. |
56 | | -Currently, aws-lc-fips-sys binds to |
57 | | -[AWS-LC-FIPS 3.0.x](https://github.com/aws/aws-lc/tree/fips-2024-09-27). |
58 | | - |
59 | | -Consult with your local FIPS compliance team to determine the version of AWS-LC-FIPS module that you require. Consumers |
60 | | -needing to remain on a previous version of the AWS-LC-FIPS module should pin to specific versions of aws-lc-rs to avoid |
61 | | -automatically being upgraded to a newer module version. |
62 | | -(See [cargo's documentation](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) |
63 | | -on how to specify dependency versions.) |
64 | | - |
65 | | -| AWS-LC-FIPS module | aws-lc-rs | |
66 | | -|--------------------|-----------| |
67 | | -| 2.0.x | \<1.12.0 | |
68 | | -| 3.0.x | *latest* | |
69 | | - |
70 | | -Refer to the |
71 | | -[NIST Cryptographic Module Validation Program's Modules In Progress List](https://csrc.nist.gov/Projects/cryptographic-module-validation-program/modules-in-process/Modules-In-Process-List) |
72 | | -for the latest status of the static or dynamic AWS-LC Cryptographic Module. Please see the |
73 | | -[FIPS.md in the aws-lc repository](https://github.com/aws/aws-lc/blob/main/crypto/fipsmodule/FIPS.md) |
74 | | -for relevant security policies and information on supported operating environments. |
75 | | -We will also update our release notes and documentation to reflect any changes in FIPS certification status. |
76 | | - |
77 | | -##### non-fips |
78 | | - |
79 | | -Enable this feature to guarantee that the non-FIPS [*aws-lc-sys*](https://crates.io/crates/aws-lc-sys) |
80 | | -crate is used for cryptographic implementations. This feature is mutually exclusive with the `fips` |
81 | | -feature - enabling both will result in a compile-time error. Use this feature when you need a |
82 | | -compile-time guarantee that your build is using the non-FIPS cryptographic module. |
83 | | - |
84 | | -##### asan |
85 | | - |
86 | | -Performs an "address sanitizer" build. This can be used to help detect memory leaks. See the |
87 | | -["Address Sanitizer" section](https://doc.rust-lang.org/beta/unstable-book/compiler-flags/sanitizer.html#addresssanitizer) |
88 | | -of the [Rust Unstable Book](https://doc.rust-lang.org/beta/unstable-book/). |
89 | | - |
90 | | -##### bindgen |
91 | | - |
92 | | -Causes `aws-lc-sys` or `aws-lc-fips-sys` to generates fresh bindings for AWS-LC instead of using |
93 | | -the pre-generated bindings. This feature requires `libclang` to be installed. See the |
94 | | -[requirements](https://rust-lang.github.io/rust-bindgen/requirements.html) |
95 | | -for [rust-bindgen](https://github.com/rust-lang/rust-bindgen) |
96 | | - |
97 | | -##### prebuilt-nasm |
98 | | - |
99 | | -Enables the use of crate provided prebuilt NASM objects under certain conditions. This only affects builds for |
100 | | -Windows x86-64 platforms. This feature is ignored if the "fips" feature is also enabled. |
101 | | - |
102 | | -Use of prebuilt NASM objects is prevented if either of the following conditions are true: |
103 | | -* The NASM assembler is detected in the build environment |
104 | | -* `AWS_LC_SYS_PREBUILT_NASM` environment variable is set with a value of `0` |
105 | | - |
106 | | -Be aware that [features are additive](https://doc.rust-lang.org/cargo/reference/features.html#feature-unification); |
107 | | -by enabling this feature, it is enabled for all crates within the same build. |
108 | | - |
109 | | -##### dev-tests-only |
110 | | - |
111 | | -Enables the `rand::unsealed` module, which re-exports the normally sealed `SecureRandom` trait. |
112 | | -This allows consumers to provide their own implementations of `SecureRandom` (e.g., a |
113 | | -deterministic RNG) for testing purposes. When enabled, a `mut_fill` method is also available on |
114 | | -`SecureRandom`. |
115 | | - |
116 | | -This feature is restricted to **dev/debug profile builds only** — attempting to use it in a |
117 | | -release build will result in a compile-time error. |
118 | | - |
119 | | -It can be enabled in two ways: |
120 | | -* **Feature flag:** `cargo test --features dev-tests-only` |
121 | | -* **Environment variable:** `AWS_LC_RS_DEV_TESTS_ONLY=1 cargo test` |
122 | | - |
123 | | -**⚠️ Warning:** This feature is intended **only** for development and testing. It must not be |
124 | | -used in production builds. The `rand::unsealed` module and `mut_fill` method are not part of the |
125 | | -stable public API and may change without notice. |
126 | | - |
127 | | -## Use of prebuilt NASM objects |
128 | | - |
129 | | -Prebuilt NASM objects are **only** applicable to Windows x86-64 platforms. They are **never** used on any other platform (Linux, macOS, etc.). |
130 | | - |
131 | | -For Windows x86 and x86-64, NASM is required for assembly code compilation. On these platforms, |
132 | | -we recommend that you install [the NASM assembler](https://www.nasm.us/). **If NASM is |
133 | | -detected in the build environment, it is always used** to compile the assembly files. Prebuilt NASM objects are only used as a fallback. |
134 | | - |
135 | | -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: |
136 | | - |
137 | | -* You are building for `x86-64` and either: |
138 | | - * The `AWS_LC_SYS_PREBUILT_NASM` environment variable is found and has a value of "1"; OR |
139 | | - * `AWS_LC_SYS_PREBUILT_NASM` is *not found* in the environment AND the "prebuilt-nasm" feature has been enabled. |
140 | | - |
141 | | -If the above cases apply, then the crate provided prebuilt NASM objects will be used for the build. To prevent usage of prebuilt NASM |
142 | | -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. |
143 | | - |
144 | | -### About prebuilt NASM objects |
145 | | - |
146 | | -Prebuilt NASM objects are generated using automation similar to the crate provided pregenerated bindings. See the repository's |
147 | | -[GitHub workflow configuration](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/sys-bindings-generator.yml) for more information. |
148 | | -The prebuilt NASM objects are checked into the repository |
149 | | -and are [available for inspection](https://github.com/aws/aws-lc-rs/tree/main/aws-lc-sys/builder/prebuilt-nasm). |
150 | | -For each PR submitted, |
151 | | -[CI verifies](https://github.com/aws/aws-lc-rs/blob/main/.github/workflows/tests.yml) |
152 | | -that the NASM objects newly built from source match the NASM objects currently in the repository. |
153 | | - |
154 | | -## *ring*-compatibility |
155 | | - |
156 | | -Although this library attempts to be fully compatible with *ring* (v0.16.x), there are a few places where our |
157 | | -behavior is observably different. |
158 | | - |
159 | | -* Our implementation requires the `std` library. We currently do not support a |
160 | | - [`#![no_std]`](https://docs.rust-embedded.org/book/intro/no-std.html) build. |
161 | | -* `aws-lc-rs` supports the platforms supported by `aws-lc-sys` and AWS-LC. See the |
162 | | - [Platform Support](https://aws.github.io/aws-lc-rs/platform_support.html) page in our User Guide. |
163 | | -* `Ed25519KeyPair::from_pkcs8` and `Ed25519KeyPair::from_pkcs8_maybe_unchecked` both support |
164 | | - parsing of v1 or v2 PKCS#8 documents. If a v2 encoded key is provided to either function, |
165 | | - public key component, if present, will be verified to match the one derived from the encoded |
166 | | - private key. |
167 | | - |
168 | | -## Post-Quantum Cryptography |
169 | | - |
170 | | -Details on the post-quantum algorithms supported by aws-lc-rs can be found at |
171 | | -[PQREADME](https://github.com/aws/aws-lc/tree/main/crypto/fipsmodule/PQREADME.md). |
172 | | - |
173 | | -## Motivation |
174 | | - |
175 | | -Rust developers increasingly need to deploy applications that meet US and Canadian government |
176 | | -cryptographic requirements. We evaluated how to deliver FIPS validated cryptography in idiomatic |
177 | | -and performant Rust, built around our AWS-LC offering. We found that the popular ring (v0.16) |
178 | | -library fulfilled much of the cryptographic needs in the Rust community, but it did not meet the |
179 | | -needs of developers with FIPS requirements. Our intention is to contribute a drop-in replacement |
180 | | -for ring that provides FIPS support and is compatible with the ring API. Rust developers with |
181 | | -prescribed cryptographic requirements can seamlessly integrate aws-lc-rs into their applications |
182 | | -and deploy them into AWS Regions. |
183 | | - |
184 | | -### Contributor Quickstart for Amazon Linux 2023 |
185 | | - |
186 | | -For those who would like to contribute to our project or build it directly from our repository, |
187 | | -a few more packages may be needed. The listing below shows the steps needed for you to begin |
188 | | -building and testing our project locally. |
189 | | - |
190 | | -```shell |
191 | | -# Install dependencies needed for build and testing |
192 | | -sudo yum install -y cmake3 clang git clang-libs golang openssl-devel perl-FindBin |
193 | | - |
194 | | -# Install Rust |
195 | | -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh |
196 | | -source "$HOME/.cargo/env" |
197 | | - |
198 | | -# Clone and initialize a local repository |
199 | | -git clone https://github.com/aws/aws-lc-rs.git |
200 | | -cd aws-lc-rs |
201 | | -git submodule update --init --recursive |
202 | | - |
203 | | -# Build and test the project |
204 | | -cargo test |
| 8 | +# Before |
| 9 | +ring = "0.17" |
205 | 10 |
|
| 11 | +# After |
| 12 | +wolfcrypt-ring-compat = { version = "1.16", features = ["ring-sig-verify"] } |
206 | 13 | ``` |
207 | 14 |
|
208 | | -## Questions, Feedback and Contributing |
| 15 | +Same API. No application code changes required. |
209 | 16 |
|
210 | | -* [Submit an non-security Bug/Issue/Request](https://github.com/aws/aws-lc-rs/issues/new/choose) |
211 | | -* [API documentation](https://docs.rs/aws-lc-rs/) |
212 | | -* [Fork our repo](https://github.com/aws/aws-lc-rs/fork) |
| 17 | +## Coverage |
213 | 18 |
|
214 | | -We use [GitHub Issues](https://github.com/aws/aws-lc-rs/issues/new/choose) for managing feature requests, bug |
215 | | -reports, or questions about aws-lc-rs API usage. |
| 19 | +AES-GCM, ChaCha20-Poly1305, ECDH (P-256, P-384, X25519), SHA-{1,256,384,512}, HMAC, HKDF, PBKDF2, ECDSA, Ed25519, RSA PKCS#1v1.5 and PSS, SystemRandom. Targets API parity with ring 0.17. |
216 | 20 |
|
217 | | -Otherwise, if you think you might have found a security impacting issue, please instead |
218 | | -follow our *Security Notification Process* below. |
| 21 | +## FIPS |
219 | 22 |
|
220 | | -## Security Notification Process |
| 23 | +```toml |
| 24 | +wolfcrypt-ring-compat = { version = "1.16", features = ["fips"] } |
| 25 | +``` |
221 | 26 |
|
222 | | -If you discover a potential security issue in *AWS-LC* or *aws-lc-rs*, we ask that you notify AWS |
223 | | -Security via our |
224 | | -[vulnerability reporting page](https://aws.amazon.com/security/vulnerability-reporting/). |
225 | | -Please do **not** create a public GitHub issue. |
| 27 | +ring is not FIPS 140-3 certifiable. wolfCrypt is. This is the migration path if you need ring's API with a FIPS-certifiable backend. |
226 | 28 |
|
227 | | -If you package or distribute *aws-lc-rs*, or use *aws-lc-rs* as part of a large multi-user service, |
228 | | -you may be eligible for pre-notification of future *aws-lc-rs* releases. |
229 | | -Please contact aws-lc-pre-notifications@amazon.com. |
| 29 | +Requires a wolfSSL commercial FIPS license and the validated source tree. See the [workspace README](https://github.com/wolfSSL/wolfssl-rs). |
230 | 30 |
|
231 | 31 | ## License |
232 | 32 |
|
233 | | -This library is licensed under the Apache-2.0 or the ISC License. |
| 33 | +MIT |
0 commit comments