Crate boring 

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 statically links against a pinned BoringSSL revision, vendored as a submodule at boring-sys/deps/boringssl. The current pin is upstream tag 0.20260929.0. 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.

Linking with a C++ standard library

Recent versions of boringssl require some C++ standard library features, so boring needs to link with a STL implementation. This can be controlled using the BORING_BSSL_RUST_CPPLIB variable. If no library is specified, libc++ is used on macOS and iOS whereas libstdc++ is used on other Unix systems.

Optional patches

Raw Public Key

The crate can be compiled with RawPublicKey support by turning on rpk compilation feature.

Post-quantum cryptography

Upstream BoringSSL now supports and enables X25519MLKEM768, the recommended post-quantum key agreement from RFC 10024, by default. The pq-experimental feature is a no-op kept only for backwards compatibility.

We patch BpringSSL to additionally support

• X25519Kyber768Draft00, under codepoint 0x6399. This is the pre-standard predecessor of X25519MLKEM768. Not recommended; it’s being phased out.
• P256Kyber768Draft00, under codepoint 0xfe32, which uses P-256 as the classical part. In the past we needed this for compliance reasons. Not recommended; it’s being phased out.

Presently all these key agreements are deployed by Cloudflare. We only support X25519MLKEM768 long term.

Modules

aead

Authenticated encryption with detached authentication tags.

aes

Low level AES IGE and key wrapping functionality

asn1

Defines the format of certificiates

base64

Base64 encoding support.

bn

BigNum implementation

conf

Interface for processing OpenSSL configuration files.

derive

Shared secret derivation.

dh

dsa

Digital Signatures

ec

Elliptic Curve

ecdsa

Low level Elliptic Curve Digital Signature Algorithm (ECDSA) functions.

error

Errors returned by OpenSSL library.

ex_data

fips

FIPS 140-2 support.

hash

hkdf

HMAC-based Extract-and-Expand Key Derivation Function (HKDF) as specified by RFC 5869.

hmac

hpke

memcmp

Utilities to safely compare cryptographic values.

mldsa

ML-DSA (FIPS 204) post-quantum digital signature.

mlkem

ML-KEM (FIPS 203) post-quantum key encapsulation.

nid

A collection of numerical identifiers for OpenSSL objects.

pkcs5

pkcs12

PKCS #12 archives.

pkey

Public/private key processing.

rand

Utilities for secure random number generation.

rsa

Rivest–Shamir–Adleman cryptosystem

sha

The SHA family of hashes.

sign

Message signatures.

srtp

ssl

SSL/TLS support.

stack

string

symm

High level interface to certain symmetric ciphers.

version

x509

The standard defining the format of public key certificates.

Functions

init