rust/rustls
rust
/
rustls
mirror of https://github.com/ctz/rustls
1
0
Fork 0
Code Issues Releases Wiki Activity

doc: remove `crate::` prefix for links 

Instead, use `#[cfg(doc)]` to conditionally import names that we want to
use in the docs. This provides a user-friendlier link name.
This commit is contained in:
Jacob Hoffman-Andrews 2023-12-01 12:02:29 -08:00 committed by Joe Birr-Pixton
parent 74321cfbb1
commit 6845c013cb
9 changed files with 78 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@ -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

5
rustls/src/builder.rs
View File

@ -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.
///

9
rustls/src/client/client_conn.rs
View File

@ -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.

50
rustls/src/crypto/mod.rs
View File

@ -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.

5
rustls/src/key_log.rs
View File

@ -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

10
rustls/src/lib.rs
View File

@ -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;

7
rustls/src/server/server_conn.rs
View File

@ -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.

19
rustls/src/webpki/client_verifier.rs
View File

@ -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<dyn ClientCertVerifier>` can be used with a Rustls
/// [crate::server::ServerConfig] to configure client certificate validation using
/// [`with_client_cert_verifier`][crate::ConfigBuilder<ClientConfig, WantsVerifier>::with_client_cert_verifier].
/// [`ServerConfig`] to configure client certificate validation using
/// [`with_client_cert_verifier`][ConfigBuilder<ClientConfig, WantsVerifier>::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<dyn ClientCertVerifier>` can be used with a Rustls [crate::server::ServerConfig]
/// to configure client certificate validation using [`with_client_cert_verifier`][crate::ConfigBuilder<ClientConfig, WantsVerifier>::with_client_cert_verifier].
/// Once built, the provided `Arc<dyn ClientCertVerifier>` can be used with a Rustls [`ServerConfig`]
/// to configure client certificate validation using [`with_client_cert_verifier`][ConfigBuilder<ClientConfig, WantsVerifier>::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.

11
rustls/src/webpki/server_verifier.rs
View File

@ -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<dyn ServerCertVerifier>` can be used with a Rustls
/// [crate::server::ServerConfig] to configure client certificate validation using
/// [`with_client_cert_verifier`][crate::ConfigBuilder<ClientConfig, WantsVerifier>::with_client_cert_verifier].
/// [`ServerConfig`] to configure client certificate validation using
/// [`with_client_cert_verifier`][ConfigBuilder<ClientConfig, WantsVerifier>::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.