diff --git a/README.md b/README.md index 8f2532e2..28498df7 100644 --- a/README.md +++ b/README.md @@ -93,10 +93,10 @@ x86, x86-64, LoongArch64, 32-bit & 64-bit Little Endian MIPS, 32-bit PowerPC (Bi support WebAssembly. For more information, see [the supported `ring` target platforms][ring-target-platforms]. -By providing a custom instance of the [`crate::crypto::CryptoProvider`] struct, you +By providing a custom instance of the [`crypto::CryptoProvider`] struct, you can replace all cryptography dependencies of rustls. This is a route to being portable to a wider set of architectures and environments, or compliance requirements. See the -[`crate::crypto::CryptoProvider`] documentation for more details. +[`crypto::CryptoProvider`] documentation for more details. Specifying `default-features = false` when depending on rustls will remove the dependency on *ring*. @@ -104,6 +104,7 @@ dependency on *ring*. Rustls requires Rust 1.61 or later. [ring-target-platforms]: https://github.com/briansmith/ring/blob/2e8363b433fa3b3962c877d9ed2e9145612f3160/include/ring-core/target.h#L18-L64 +[crypto::CryptoProvider]: https://docs.rs/rustls/latest/rustls/crypto/trait.CryptoProvider.html # Example code There are two example programs which use diff --git a/rustls/src/builder.rs b/rustls/src/builder.rs index 26de3adb..a3acb23c 100644 --- a/rustls/src/builder.rs +++ b/rustls/src/builder.rs @@ -7,6 +7,9 @@ use core::fmt; use core::marker::PhantomData; use std::sync::Arc; +#[cfg(doc)] +use crate::{ClientConfig, ServerConfig}; + /// A [builder] for [`ServerConfig`] or [`ClientConfig`] values. /// /// To get one of these, call [`ServerConfig::builder()`] or [`ClientConfig::builder()`]. @@ -19,7 +22,7 @@ use std::sync::Arc; /// For settings besides these, see the fields of [`ServerConfig`] and [`ClientConfig`]. /// /// The usual choice for protocol primitives is to call -/// [`crate::ClientConfig::builder`]/[`ServerConfig::builder`] +/// [`ClientConfig::builder`]/[`ServerConfig::builder`] /// which will use rustls' default cryptographic provider and safe defaults for ciphersuites and /// supported protocol versions. /// diff --git a/rustls/src/client/client_conn.rs b/rustls/src/client/client_conn.rs index 40213e13..dd11959f 100644 --- a/rustls/src/client/client_conn.rs +++ b/rustls/src/client/client_conn.rs @@ -30,6 +30,9 @@ use core::mem; use core::ops::{Deref, DerefMut}; use std::io; +#[cfg(doc)] +use crate::{crypto, DistinguishedName}; + /// A trait for the ability to store client session data, so that sessions /// can be resumed in future connections. /// @@ -103,7 +106,7 @@ pub trait ResolvesClientCert: fmt::Debug + Send + Sync { /// decide on a client certificate the server is likely to accept. If /// the list is empty, the client should send whatever certificate it /// has. The hints are expected to be DER-encoded X.500 distinguished names, - /// per [RFC 5280 A.1]. See [`crate::DistinguishedName`] for more information + /// per [RFC 5280 A.1]. See [`DistinguishedName`] for more information /// on decoding with external crates like `x509-parser`. /// /// `sigschemes` is the list of the [`SignatureScheme`]s the server @@ -235,7 +238,7 @@ impl Clone for ClientConfig { impl ClientConfig { /// Create a builder for a client configuration with the default - /// [`CryptoProvider`]: [`crate::crypto::ring::default_provider`] and safe ciphersuite and + /// [`CryptoProvider`]: [`crypto::ring::default_provider`] and safe ciphersuite and /// protocol defaults. /// /// For more information, see the [`ConfigBuilder`] documentation. @@ -248,7 +251,7 @@ impl ClientConfig { } /// Create a builder for a client configuration with the default - /// [`CryptoProvider`]: [`crate::crypto::ring::default_provider`], safe ciphersuite defaults and + /// [`CryptoProvider`]: [`crypto::ring::default_provider`], safe ciphersuite defaults and /// the provided protocol versions. /// /// Panics if provided an empty slice of supported versions. diff --git a/rustls/src/crypto/mod.rs b/rustls/src/crypto/mod.rs index be08a4ec..563005e5 100644 --- a/rustls/src/crypto/mod.rs +++ b/rustls/src/crypto/mod.rs @@ -10,6 +10,14 @@ use core::fmt::Debug; use pki_types::PrivateKeyDer; use zeroize::Zeroize; +#[cfg(all(doc, feature = "tls12"))] +use crate::Tls12CipherSuite; +#[cfg(doc)] +use crate::{ + client, crypto, server, sign, ClientConfig, ConfigBuilder, ServerConfig, SupportedCipherSuite, + Tls13CipherSuite, +}; + pub use crate::webpki::{ verify_tls12_signature, verify_tls13_signature, WebPkiSupportedAlgorithms, }; @@ -56,10 +64,10 @@ pub use crate::msgs::handshake::KeyExchangeAlgorithm; /// This crate comes with two built-in options, provided as /// `CryptoProvider` structures: /// -/// - [`crate::crypto::ring::default_provider`]: (behind the `ring` crate feature, which +/// - [`crypto::ring::default_provider`]: (behind the `ring` crate feature, which /// is enabled by default). This provider uses the [*ring*](https://github.com/briansmith/ring) /// crate. -/// - [`crate::crypto::aws_lc_rs::default_provider`]: (behind the `aws_lc_rs` feature, +/// - [`crypto::aws_lc_rs::default_provider`]: (behind the `aws_lc_rs` feature, /// which is optional). This provider uses the [aws-lc-rs](https://github.com/aws/aws-lc-rs) /// crate. /// @@ -68,20 +76,20 @@ pub use crate::msgs::handshake::KeyExchangeAlgorithm; /// /// # Using a specific `CryptoProvider` /// -/// Supply the provider when constructing your [`crate::ClientConfig`] or [`crate::ServerConfig`]: +/// Supply the provider when constructing your [`ClientConfig`] or [`ServerConfig`]: /// -/// - [`crate::ClientConfig::builder_with_provider()`] -/// - [`crate::ServerConfig::builder_with_provider()`] +/// - [`ClientConfig::builder_with_provider()`] +/// - [`ServerConfig::builder_with_provider()`] /// /// When creating and configuring a webpki-backed client or server certificate verifier, a choice of /// provider is also needed to start the configuration process: /// -/// - [`crate::client::WebPkiServerVerifier::builder_with_provider()`] -/// - [`crate::server::WebPkiClientVerifier::builder_with_provider()`] +/// - [`client::WebPkiServerVerifier::builder_with_provider()`] +/// - [`server::WebPkiClientVerifier::builder_with_provider()`] /// /// # Making a custom `CryptoProvider` /// -/// Your goal will be to populate a [`crate::crypto::CryptoProvider`] struct instance. +/// Your goal will be to populate a [`crypto::CryptoProvider`] struct instance. /// /// ## Which elements are required? /// @@ -91,7 +99,7 @@ pub use crate::msgs::handshake::KeyExchangeAlgorithm; /// provider (dynamically). /// /// For example, if we want to make a provider that just overrides key loading in the config builder -/// API ([`crate::ConfigBuilder::with_single_cert`] etc.), it might look like this: +/// API ([`ConfigBuilder::with_single_cert`] etc.), it might look like this: /// /// ``` /// # #[cfg(feature = "ring")] { @@ -121,13 +129,13 @@ pub use crate::msgs::handshake::KeyExchangeAlgorithm; /// /// The elements are documented separately: /// -/// - **Random** - see [`crate::crypto::SecureRandom::fill()`]. -/// - **Cipher suites** - see [`crate::SupportedCipherSuite`], [`crate::Tls12CipherSuite`], and -/// [`crate::Tls13CipherSuite`]. -/// - **Key exchange groups** - see [`crate::crypto::SupportedKxGroup`]. -/// - **Signature verification algorithms** - see [`crate::crypto::WebPkiSupportedAlgorithms`]. -/// - **Authentication key loading** - see [`crate::crypto::KeyProvider::load_private_key()`] and -/// [`crate::sign::SigningKey`]. +/// - **Random** - see [`crypto::SecureRandom::fill()`]. +/// - **Cipher suites** - see [`SupportedCipherSuite`], [`Tls12CipherSuite`], and +/// [`Tls13CipherSuite`]. +/// - **Key exchange groups** - see [`crypto::SupportedKxGroup`]. +/// - **Signature verification algorithms** - see [`crypto::WebPkiSupportedAlgorithms`]. +/// - **Authentication key loading** - see [`crypto::KeyProvider::load_private_key()`] and +/// [`sign::SigningKey`]. /// /// # Example code /// @@ -166,9 +174,9 @@ pub struct CryptoProvider { /// /// These are used for both certificate chain verification and handshake signature verification. /// - /// This is called by [`crate::ConfigBuilder::with_root_certificates()`], - /// [`crate::server::WebPkiClientVerifier::builder_with_provider()`] and - /// [`crate::client::WebPkiServerVerifier::builder_with_provider()`]. + /// This is called by [`ConfigBuilder::with_root_certificates()`], + /// [`server::WebPkiClientVerifier::builder_with_provider()`] and + /// [`client::WebPkiServerVerifier::builder_with_provider()`]. pub signature_verification_algorithms: WebPkiSupportedAlgorithms, /// Source of cryptographically secure random numbers. @@ -197,8 +205,8 @@ pub trait SecureRandom: Send + Sync + Debug { pub trait KeyProvider: Send + Sync + Debug { /// Decode and validate a private signing key from `key_der`. /// - /// This is used by [`crate::ConfigBuilder::with_client_auth_cert()`], [`crate::ConfigBuilder::with_single_cert()`], - /// and [`crate::ConfigBuilder::with_single_cert_with_ocsp()`]. The key types and formats supported by this + /// This is used by [`ConfigBuilder::with_client_auth_cert()`], [`ConfigBuilder::with_single_cert()`], + /// and [`ConfigBuilder::with_single_cert_with_ocsp()`]. The key types and formats supported by this /// function directly defines the key types and formats supported in those APIs. /// /// Return an error if the key type encoding is not supported, or if the key fails validation. diff --git a/rustls/src/key_log.rs b/rustls/src/key_log.rs index 677d206d..bca28b66 100644 --- a/rustls/src/key_log.rs +++ b/rustls/src/key_log.rs @@ -1,5 +1,8 @@ use core::fmt::Debug; +#[cfg(doc)] +use crate::KeyLogFile; + /// This trait represents the ability to do something useful /// with key material, such as logging it to a file for debugging. /// @@ -10,7 +13,7 @@ use core::fmt::Debug; /// You'll likely want some interior mutability in your /// implementation to make this useful. /// -/// See [`KeyLogFile`](crate::KeyLogFile) that implements the standard +/// See [`KeyLogFile`] that implements the standard /// `SSLKEYLOGFILE` environment variable behaviour. pub trait KeyLog: Debug + Send + Sync { /// Log the given `secret`. `client_random` is provided for diff --git a/rustls/src/lib.rs b/rustls/src/lib.rs index 0c03a438..957d3abb 100644 --- a/rustls/src/lib.rs +++ b/rustls/src/lib.rs @@ -63,10 +63,10 @@ //! support WebAssembly. //! For more information, see [the supported `ring` target platforms][ring-target-platforms]. //! -//! By providing a custom instance of the [`crate::crypto::CryptoProvider`] struct, you +//! By providing a custom instance of the [`crypto::CryptoProvider`] struct, you //! can replace all cryptography dependencies of rustls. This is a route to being portable //! to a wider set of architectures and environments, or compliance requirements. See the -//! [`crate::crypto::CryptoProvider`] documentation for more details. +//! [`crypto::CryptoProvider`] documentation for more details. //! //! Specifying `default-features = false` when depending on rustls will remove the //! dependency on *ring*. @@ -74,6 +74,7 @@ //! Rustls requires Rust 1.61 or later. //! //! [ring-target-platforms]: https://github.com/briansmith/ring/blob/2e8363b433fa3b3962c877d9ed2e9145612f3160/include/ring-core/target.h#L18-L64 +//! [crypto::CryptoProvider]: https://docs.rs/rustls/latest/rustls/crypto/trait.CryptoProvider.html //! //! ## Design Overview //! ### Rustls does not take care of network IO @@ -244,7 +245,7 @@ //! //! - `ring` (enabled by default): makes the rustls crate depend on the *ring* crate, which is //! used for cryptography by default. Without this feature, these items must be provided -//! externally to the core rustls crate: see [`crate::crypto::CryptoProvider`]. +//! externally to the core rustls crate: see [`CryptoProvider`]. //! //! - `aws_lc_rs`: makes the rustls crate depend on the aws-lc-rs crate, //! which can be used for cryptography as an alternative to *ring*. @@ -333,6 +334,9 @@ extern crate std; #[allow(unused_extern_crates)] extern crate test; +#[cfg(doc)] +use crate::crypto::CryptoProvider; + // log for logging (optional). #[cfg(feature = "logging")] use log; diff --git a/rustls/src/server/server_conn.rs b/rustls/src/server/server_conn.rs index 898e5c77..4c6e9f5e 100644 --- a/rustls/src/server/server_conn.rs +++ b/rustls/src/server/server_conn.rs @@ -32,6 +32,9 @@ use core::marker::PhantomData; use core::ops::{Deref, DerefMut}; use std::io; +#[cfg(doc)] +use crate::crypto; + /// A trait for the ability to store server session data. /// /// The keys and values are opaque. @@ -338,7 +341,7 @@ impl Clone for ServerConfig { impl ServerConfig { /// Create a builder for a server configuration with the default - /// [`CryptoProvider`]: [`crate::crypto::ring::default_provider`] and safe ciphersuite and protocol + /// [`CryptoProvider`]: [`crypto::ring::default_provider`] and safe ciphersuite and protocol /// defaults. /// /// For more information, see the [`ConfigBuilder`] documentation. @@ -351,7 +354,7 @@ impl ServerConfig { } /// Create a builder for a server configuration with the default - /// [`CryptoProvider`]: [`crate::crypto::ring::default_provider`], safe ciphersuite defaults and + /// [`CryptoProvider`]: [`crypto::ring::default_provider`], safe ciphersuite defaults and /// the provided protocol versions. /// /// Panics if provided an empty slice of supported versions. diff --git a/rustls/src/webpki/client_verifier.rs b/rustls/src/webpki/client_verifier.rs index 0e6cf8b7..1264e598 100644 --- a/rustls/src/webpki/client_verifier.rs +++ b/rustls/src/webpki/client_verifier.rs @@ -14,6 +14,13 @@ use crate::webpki::parse_crls; use crate::webpki::verify::{verify_tls12_signature, verify_tls13_signature, ParsedCertificate}; use crate::{DistinguishedName, Error, RootCertStore, SignatureScheme}; +#[cfg(doc)] +use crate::crypto; +#[cfg(doc)] +use crate::server::ServerConfig; +#[cfg(doc)] +use crate::ConfigBuilder; + /// A builder for configuring a `webpki` client certificate verifier. /// /// For more information, see the [`WebPkiClientVerifier`] documentation. @@ -138,11 +145,11 @@ impl ClientCertVerifierBuilder { /// certificate authentication offer with a client certificate. /// /// If `with_signature_verification_algorithms` was not called on the builder, a default set of - /// signature verification algorithms is used, controlled by the selected [`crate::crypto::CryptoProvider`]. + /// signature verification algorithms is used, controlled by the selected [`CryptoProvider`]. /// /// Once built, the provided `Arc` can be used with a Rustls - /// [crate::server::ServerConfig] to configure client certificate validation using - /// [`with_client_cert_verifier`][crate::ConfigBuilder::with_client_cert_verifier]. + /// [`ServerConfig`] to configure client certificate validation using + /// [`with_client_cert_verifier`][ConfigBuilder::with_client_cert_verifier]. /// /// # Errors /// This function will return a `ClientCertVerifierBuilderError` if: @@ -168,8 +175,8 @@ impl ClientCertVerifierBuilder { /// A client certificate verifier that uses the `webpki` crate[^1] to perform client certificate /// validation. It must be created via the [WebPkiClientVerifier::builder()] function. /// -/// Once built, the provided `Arc` can be used with a Rustls [crate::server::ServerConfig] -/// to configure client certificate validation using [`with_client_cert_verifier`][crate::ConfigBuilder::with_client_cert_verifier]. +/// Once built, the provided `Arc` can be used with a Rustls [`ServerConfig`] +/// to configure client certificate validation using [`with_client_cert_verifier`][ConfigBuilder::with_client_cert_verifier]. /// /// Example: /// @@ -242,7 +249,7 @@ impl WebPkiClientVerifier { /// will be verified using the trust anchors found in the provided `roots`. If you /// wish to disable client authentication use [WebPkiClientVerifier::no_client_auth()] instead. /// - /// The cryptography used comes from the default [`CryptoProvider`]: [`crate::crypto::ring::default_provider`]. + /// The cryptography used comes from the default [`CryptoProvider`]: [`crypto::ring::default_provider`]. /// Use [`Self::builder_with_provider`] if you wish to customize this. /// /// For more information, see the [`ClientCertVerifierBuilder`] documentation. diff --git a/rustls/src/webpki/server_verifier.rs b/rustls/src/webpki/server_verifier.rs index 3e9319cc..dd17531a 100644 --- a/rustls/src/webpki/server_verifier.rs +++ b/rustls/src/webpki/server_verifier.rs @@ -17,6 +17,9 @@ use crate::webpki::verify::{ use crate::webpki::{parse_crls, verify_server_name, VerifierBuilderError}; use crate::{Error, RootCertStore, SignatureScheme}; +#[cfg(doc)] +use crate::{crypto, ConfigBuilder, ServerConfig}; + /// A builder for configuring a `webpki` server certificate verifier. /// /// For more information, see the [`WebPkiServerVerifier`] documentation. @@ -85,11 +88,11 @@ impl ServerCertVerifierBuilder { /// trust anchors, and to control how server certificate revocation checking is performed. /// /// If `with_signature_verification_algorithms` was not called on the builder, a default set of - /// signature verification algorithms is used, controlled by the selected [`crate::crypto::CryptoProvider`]. + /// signature verification algorithms is used, controlled by the selected [`crypto::CryptoProvider`]. /// /// Once built, the provided `Arc` can be used with a Rustls - /// [crate::server::ServerConfig] to configure client certificate validation using - /// [`with_client_cert_verifier`][crate::ConfigBuilder::with_client_cert_verifier]. + /// [`ServerConfig`] to configure client certificate validation using + /// [`with_client_cert_verifier`][ConfigBuilder::with_client_cert_verifier]. /// /// # Errors /// This function will return a `CertVerifierBuilderError` if: @@ -129,7 +132,7 @@ impl WebPkiServerVerifier { /// /// Server certificates will be verified using the trust anchors found in the provided `roots`. /// - /// The cryptography used comes from the default [`CryptoProvider`]: [`crate::crypto::ring::default_provider`]. + /// The cryptography used comes from the default [`CryptoProvider`]: [`crypto::ring::default_provider`]. /// Use [`Self::builder_with_provider`] if you wish to customize this. /// /// For more information, see the [`ServerCertVerifierBuilder`] documentation.