rustls/manual/fips.rs
1/*! # Using rustls with FIPS-approved cryptography
2
3To use FIPS-approved cryptography with rustls, you should
4utilize a FIPS-approved `CryptoProvider`.
5rustls ships with one using `aws-lc-rs`, take these actions to make use of it:
6
7## 1. Enable the `fips` crate feature for rustls.
8
9Use:
10
11```toml
12rustls = { version = "0.23", features = [ "fips" ] }
13```
14
15## 2. Use the FIPS `CryptoProvider`
16
17This is [`default_fips_provider()`]:
18
19```rust,ignore
20rustls::crypto::default_fips_provider()
21 .install_default()
22 .expect("default provider already set elsewhere");
23```
24
25This snippet makes use of the process-default provider,
26and that assumes all your uses of rustls use that.
27See [`CryptoProvider`] documentation for other ways to
28specify which `CryptoProvider` to use.
29
30## 3. Validate the FIPS status of your `ClientConfig`/`ServerConfig` at run-time
31
32See [`ClientConfig::fips()`] or [`ServerConfig::fips()`].
33
34You could, for example:
35
36```rust,ignore
37# let client_config = unreachable!();
38assert!(client_config.fips());
39```
40
41But maybe your application has an error handling
42or health-check strategy better than panicking.
43
44# aws-lc-rs FIPS approval status
45
46This is covered by [FIPS 140-3 certificate #4816][cert-4816].
47See [the security policy][policy-4816] for precisely which
48environments and functions this certificate covers.
49
50Later releases of aws-lc-rs may be covered by later certificates,
51or be pending certification.
52
53For the most up-to-date details see the latest documentation
54for the [`aws-lc-fips-sys`] crate.
55
56[`aws-lc-fips-sys`]: https://crates.io/crates/aws-lc-fips-sys
57[`default_fips_provider()`]: crate::crypto::default_fips_provider
58[`CryptoProvider`]: crate::crypto::CryptoProvider
59[`ClientConfig::fips()`]: crate::client::ClientConfig::fips
60[`ServerConfig::fips()`]: crate::server::ServerConfig::fips
61[cert-4816]: https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4816
62[policy-4816]: https://csrc.nist.gov/CSRC/media/projects/cryptographic-module-validation-program/documents/security-policies/140sp4816.pdf
63*/