36 stable releases (3 major)
4.11.0 | Oct 17, 2024 |
---|---|
4.9.1 | Aug 4, 2024 |
4.8.0 | Jul 5, 2024 |
4.5.0 | Feb 8, 2024 |
1.0.2 | Nov 12, 2020 |
#52 in Cryptography
61,190 downloads per month
Used in 50 crates
(26 directly)
27MB
742K
SLoC
boring
BoringSSL bindings for the Rust programming language and TLS adapters for tokio and hyper built on top of it.
Documentation
- Boring API: https://docs.rs/boring
- tokio TLS adapters: https://docs.rs/tokio-boring
- hyper HTTPS connector: https://docs.rs/hyper-boring
- FFI bindings: https://docs.rs/boring-sys
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed under the terms of both the Apache License, Version 2.0 and the MIT license without any additional terms or conditions.
Accolades
The project is based on a fork of rust-openssl.
lib.rs
:
Bindings to BoringSSL
This crate provides a safe interface to the BoringSSL cryptography library.
Versioning
Crate versioning
The crate and all the related crates (FFI bindings, etc.) are released simultaneously and all bumped to the same version disregard whether particular crate has any API changes or not. However, semantic versioning guarantees still hold, as all the crate versions will be updated based on the crate with most significant changes.
BoringSSL version
By default, the crate aims to statically link with the latest BoringSSL master branch. Note: any BoringSSL revision bumps will be released as a major version update of all crates.
Compilation and linking options
Environment variables
This crate uses various environment variables to tweak how boring is built. The variables
are all prefixed by BORING_BSSL_
for non-FIPS builds, and by BORING_BSSL_FIPS_
for FIPS builds.
Support for pre-built binaries or custom source
While this crate can build BoringSSL on its own, you may want to provide pre-built binaries instead.
To do so, specify the environment variable BORING_BSSL{,_FIPS}_PATH
with the path to the binaries.
You can also provide specific headers by setting BORING_BSSL{,_FIPS}_INCLUDE_PATH
.
Notes: The crate will look for headers in the$BORING_BSSL{,_FIPS}_INCLUDE_PATH/openssl/
folder, make sure to place your headers there.
In alternative a different path for the BoringSSL source code directory can be specified by setting
BORING_BSSL{,_FIPS}_SOURCE_PATH
which will automatically be compiled during the build process.
Warning: When providing a different version of BoringSSL make sure to use a compatible one, the crate relies on the presence of certain functions.
Building with a FIPS-validated module
Only BoringCrypto module version 853ca1ea1168dff08011e5d42d94609cc0ca2e27
, as certified with
FIPS 140-2 certificate 4407
is supported by this crate. Support is enabled by this crate's fips
feature.
boring-sys
comes with a test that FIPS is enabled/disabled depending on the feature flag. You can run it as follows:
$ cargo test --features fips fips::is_enabled
Linking current BoringSSL version with precompiled FIPS-validated module (bcm.o
)
It's possible to link latest supported version of BoringSSL with FIPS-validated crypto module
(bcm.o
). To enable this compilation option one should enable fips-link-precompiled
compilation feature and provide a BORING_BSSL_FIPS_PRECOMPILED_BCM_O
env variable with a path to the
precompiled FIPS-validated bcm.o
module.
Note that BORING_BSSL_PRECOMPILED_BCM_O
is never used, as linking BoringSSL with precompiled non-FIPS
module is not supported.
Optional patches
Raw Public Key
The crate can be compiled with RawPublicKey
support by turning on rpk
compilation feature.
Experimental post-quantum cryptography
The crate can be compiled with post-quantum cryptography
support by turning on post-quantum
compilation feature.
Upstream BoringSSL support the post-quantum hybrid key agreement X25519Kyber768Draft00
. Most
users should stick to that one for now. Enabling this feature, adds a few other post-quantum key
agreements:
X25519MLKEM768
is the successor ofX25519Kyber768Draft00
. We expect servers to switch before the end of 2024.X25519Kyber768Draft00Old
is the same asX25519Kyber768Draft00
, but under its old codepoint.X25519Kyber512Draft00
. Similar toX25519Kyber768Draft00
, but uses level 1 parameter set for Kyber. Not recommended. It's useful to test whether the shorter ClientHello upsets fewer middle boxes.P256Kyber768Draft00
. Similar again toX25519Kyber768Draft00
, but uses P256 as classical part. It uses a non-standard codepoint. Not recommended.
Presently all these key agreements are deployed by Cloudflare, but we do not guarantee continued support for them.