From 63ce28e4eca516b3e23c691cec4e8519ac541e8a Mon Sep 17 00:00:00 2001 From: Ivan Nikulin Date: Mon, 10 Jul 2023 12:10:18 +0100 Subject: [PATCH] Update docs --- README.md | 33 +++++------------------------- boring/src/lib.rs | 51 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index d023c509..37ebcc63 100644 --- a/README.md +++ b/README.md @@ -5,34 +5,11 @@ BoringSSL bindings for the Rust programming language and TLS adapters for [tokio](https://github.com/tokio-rs/tokio) and [hyper](https://github.com/hyperium/hyper) built on top of it. -[Documentation](https://docs.rs/boring). - -## Release Support - -By default, the crate statically links with the latest BoringSSL master branch. - -## Support for pre-built binaries - -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_PATH` with the path to the binaries. - -You can also provide specific headers by setting `BORING_BSSL_INCLUDE_PATH`. - -_Notes_: The crate will look for headers in the `$BORING_BSSL_INCLUDE_PATH/openssl/` folder, make sure to place your headers there. - -_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](https://csrc.nist.gov/projects/cryptographic-module-validation-program/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: - -```bash -$ cargo test --features fips fips::is_enabled -``` +## Documentation + - Boring API: + - tokio TLS adapters: + - hyper HTTPS connector: + - FFI bindings: ## Contribution diff --git a/boring/src/lib.rs b/boring/src/lib.rs index 261f57c5..9e794064 100644 --- a/boring/src/lib.rs +++ b/boring/src/lib.rs @@ -1,6 +1,57 @@ //! 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 +//! +//! ## Support for pre-built binaries +//! +//! 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_PATH` with the path to the binaries. +//! +//! You can also provide specific headers by setting `BORING_BSSL_INCLUDE_PATH`. +//! +//! _Notes_: The crate will look for headers in the `$BORING_BSSL_INCLUDE_PATH/openssl/` folder, make sure to place your headers there. +//! +//! _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](https://csrc.nist.gov/projects/cryptographic-module-validation-program/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: +//! +//! ```bash +//! $ cargo test --features fips fips::is_enabled +//! ``` +//! +//! # Optional patches +//! +//! ## Raw Public Key +//! +//! The crate can be compiled with [RawPublicKey](https://datatracker.ietf.org/doc/html/rfc7250) +//! support by turning on `rpk` compilation feature. +//! +//! ## Post-quantum cryptography +//! +//! The crate can be compiled with [post-quantum cryptography](https://blog.cloudflare.com/post-quantum-for-all/) +//! support by turning on `post-quantum` compilation feature. #![cfg_attr(docsrs, feature(doc_auto_cfg))]