Struct ConfigBuilder

pub struct ConfigBuilder<Side, State>
where
    Side: ConfigSide,
{ /* private fields */ }

A builder for ServerConfig or ClientConfig values.

To get one of these, call ServerConfig::builder() or ClientConfig::builder().

To build a config, you must make at least two decisions (in order):

• How should this client or server verify certificates provided by its peer?
• What certificates should this client or server present to its peer?

For settings besides these, see the fields of ServerConfig and ClientConfig.

The usual choice for protocol primitives is to call [ClientConfig::builder]/ServerConfig::builder which will use rustls’ default cryptographic provider and safe defaults for ciphersuites and supported protocol versions.

use rustls::{ClientConfig, ServerConfig};
ClientConfig::builder()
//  ...

ServerConfig::builder()
//  ...

You may also override the choice of protocol versions:

ServerConfig::builder_with_protocol_versions(&[&rustls::version::TLS13])
//  ...

Overriding the default cryptographic provider introduces a Result that must be unwrapped, because the config builder checks for consistency of the choices made. For instance, it’s an error to configure only TLS 1.2 cipher suites while specifying that TLS 1.3 should be the only supported protocol version.

If you configure a smaller set of protocol primitives than the default, you may get a smaller binary, since the code for the unused ones can be optimized away at link time.

After choosing protocol primitives, you must choose (a) how to verify certificates and (b) what certificates (if any) to send to the peer. The methods to do this are specific to whether you’re building a ClientConfig or a ServerConfig, as tracked by the ConfigSide type parameter on the various impls of ConfigBuilder.

ClientConfig certificate configuration

For a client, certificate verification must be configured either by calling one of:

• ConfigBuilder::with_root_certificates or
• ConfigBuilder::dangerous() and DangerousClientConfigBuilder::with_custom_certificate_verifier

Next, certificate sending (also known as “client authentication”, “mutual TLS”, or “mTLS”) must be configured or disabled using one of:

• ConfigBuilder::with_no_client_auth - to not send client authentication (most common)
• ConfigBuilder::with_client_auth_cert - to always send a specific certificate
• ConfigBuilder::with_client_cert_resolver - to send a certificate chosen dynamically

For example:

ClientConfig::builder()
    .with_root_certificates(root_certs)
    .with_no_client_auth();

ServerConfig certificate configuration

For a server, certificate verification must be configured by calling one of:

• ConfigBuilder::with_no_client_auth - to not require client authentication (most common)
• ConfigBuilder::with_client_cert_verifier - to use a custom verifier

Next, certificate sending must be configured by calling one of:

• ConfigBuilder::with_single_cert - to send a specific certificate
• ConfigBuilder::with_single_cert_with_ocsp - to send a specific certificate, plus stapled OCSP
• ConfigBuilder::with_cert_resolver - to send a certificate chosen dynamically

For example:

ServerConfig::builder()
    .with_no_client_auth()
    .with_single_cert(certs, private_key)
    .expect("bad certificate/key");

Types

ConfigBuilder uses the typestate pattern to ensure at compile time that each required configuration item is provided exactly once. This is tracked in the State type parameter, which can have these values:

• WantsVersions
• WantsVerifier
• WantsClientCert
• WantsServerCert

The other type parameter is Side, which is either ServerConfig or ClientConfig depending on whether the ConfigBuilder was built with ServerConfig::builder() or ClientConfig::builder().

You won’t need to write out either of these type parameters explicitly. If you write a correct chain of configuration calls they will be used automatically. If you write an incorrect chain of configuration calls you will get an error message from the compiler mentioning some of these types.

Additionally, ServerConfig and ClientConfig carry a private field containing a CryptoProvider, from ClientConfig::builder_with_provider() or ServerConfig::builder_with_provider(). This determines which cryptographic backend is used. The default is the process-default provider.

Implementations

impl<Side, State> ConfigBuilder<Side, State>

where Side: ConfigSide,

pub fn crypto_provider(&self) -> &Arc<CryptoProvider>

Return the crypto provider used to construct this builder.

impl<S> ConfigBuilder<S, WantsVersions>

where S: ConfigSide,

pub fn with_safe_default_protocol_versions( self, ) -> Result<ConfigBuilder<S, WantsVerifier>, Error>

Accept the default protocol versions: both TLS1.2 and TLS1.3 are enabled.

pub fn with_protocol_versions( self, versions: &[&'static SupportedProtocolVersion], ) -> Result<ConfigBuilder<S, WantsVerifier>, Error>

Use a specific set of protocol versions.

impl ConfigBuilder<ClientConfig, WantsVersions>

pub fn with_ech( self, mode: EchMode, ) -> Result<ConfigBuilder<ClientConfig, WantsVerifier>, Error>

Enable Encrypted Client Hello (ECH) in the given mode.

This implicitly selects TLS 1.3 as the only supported protocol version to meet the requirement to support ECH.

The ClientConfig that will be produced by this builder will be specific to the provided crate::client::EchConfig and may not be appropriate for all connections made by the program. In this case the configuration should only be shared by connections intended for domains that offer the provided crate::client::EchConfig in their DNS zone.

impl ConfigBuilder<ClientConfig, WantsVerifier>

pub fn with_root_certificates( self, root_store: impl Into<Arc<RootCertStore>>, ) -> ConfigBuilder<ClientConfig, WantsClientCert>

Choose how to verify server certificates.

Using this function does not configure revocation. If you wish to configure revocation, instead use:

- .with_root_certificates(root_store)
+ .with_webpki_verifier(
+   WebPkiServerVerifier::builder_with_provider(root_store, crypto_provider)
+   .with_crls(...)
+   .build()?
+ )

pub fn with_webpki_verifier( self, verifier: Arc<WebPkiServerVerifier>, ) -> ConfigBuilder<ClientConfig, WantsClientCert>

Choose how to verify server certificates using a webpki verifier.

See webpki::WebPkiServerVerifier::builder and webpki::WebPkiServerVerifier::builder_with_provider for more information.

pub fn dangerous(self) -> DangerousClientConfigBuilder

Access configuration options whose use is dangerous and requires extra care.

impl ConfigBuilder<ClientConfig, WantsClientCert>

pub fn with_client_auth_cert( self, cert_chain: Vec<CertificateDer<'static>>, key_der: PrivateKeyDer<'static>, ) -> Result<ClientConfig, Error>

Sets a single certificate chain and matching private key for use in client authentication.

cert_chain is a vector of DER-encoded certificates. key_der is a DER-encoded private key as PKCS#1, PKCS#8, or SEC1. The aws-lc-rs and ring [CryptoProvider][crate::CryptoProvider]s support all three encodings, but other CryptoProviders may not.

This function fails if key_der is invalid.

pub fn with_no_client_auth(self) -> ClientConfig

Do not support client auth.

pub fn with_client_cert_resolver( self, client_auth_cert_resolver: Arc<dyn ResolvesClientCert>, ) -> ClientConfig

Sets a custom ResolvesClientCert.

impl ConfigBuilder<ServerConfig, WantsVerifier>

pub fn with_client_cert_verifier( self, client_cert_verifier: Arc<dyn ClientCertVerifier>, ) -> ConfigBuilder<ServerConfig, WantsServerCert>

Choose how to verify client certificates.

pub fn with_no_client_auth(self) -> ConfigBuilder<ServerConfig, WantsServerCert>

Disable client authentication.

impl ConfigBuilder<ServerConfig, WantsServerCert>

pub fn with_single_cert( self, cert_chain: Vec<CertificateDer<'static>>, key_der: PrivateKeyDer<'static>, ) -> Result<ServerConfig, Error>

Sets a single certificate chain and matching private key. This certificate and key is used for all subsequent connections, irrespective of things like SNI hostname.

Note that the end-entity certificate must have the Subject Alternative Name extension to describe, e.g., the valid DNS name. The commonName field is disregarded.

cert_chain is a vector of DER-encoded certificates. key_der is a DER-encoded private key as PKCS#1, PKCS#8, or SEC1. The aws-lc-rs and ring [CryptoProvider][crate::CryptoProvider]s support all three encodings, but other CryptoProviders may not.

This function fails if key_der is invalid, or if the SubjectPublicKeyInfo from the private key does not match the public key for the end-entity certificate from the cert_chain.

pub fn with_single_cert_with_ocsp( self, cert_chain: Vec<CertificateDer<'static>>, key_der: PrivateKeyDer<'static>, ocsp: Vec<u8>, ) -> Result<ServerConfig, Error>

Sets a single certificate chain, matching private key and optional OCSP response. This certificate and key is used for all subsequent connections, irrespective of things like SNI hostname.

cert_chain is a vector of DER-encoded certificates. key_der is a DER-encoded private key as PKCS#1, PKCS#8, or SEC1. The aws-lc-rs and ring [CryptoProvider][crate::CryptoProvider]s support all three encodings, but other CryptoProviders may not. ocsp is a DER-encoded OCSP response. Ignored if zero length.

This function fails if key_der is invalid, or if the SubjectPublicKeyInfo from the private key does not match the public key for the end-entity certificate from the cert_chain.

pub fn with_cert_resolver( self, cert_resolver: Arc<dyn ResolvesServerCert>, ) -> ServerConfig

Sets a custom ResolvesServerCert.

Trait Implementations

impl<Side, State> Clone for ConfigBuilder<Side, State>

where Side: Clone + ConfigSide, State: Clone,

fn clone(&self) -> ConfigBuilder<Side, State>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Side, State> Debug for ConfigBuilder<Side, State>

where Side: ConfigSide, State: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.