Struct ConfigBuilder 

pub struct ConfigBuilder<Side: ConfigSide, State> { /* 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 three decisions (in order):

• What crypto provider do you want to use?
• 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 rustls project recommends the crypto provider based on aws-lc-rs for production use. This can be selected by passing in crate::crypto::aws_lc_rs::DEFAULT_PROVIDER, which includes safe defaults for cipher suites and protocol versions.

use rustls::{ClientConfig, ServerConfig};
use rustls::crypto::aws_lc_rs::DEFAULT_PROVIDER;
ClientConfig::builder(Arc::new(DEFAULT_PROVIDER))
//  ...

ServerConfig::builder(Arc::new(DEFAULT_PROVIDER))
//  ...

After choosing the CryptoProvider, 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.

A Result<ClientConfig, Error> or Result<ServerConfig, Error>is the outcome of the builder process. The error is used to report consistency problems with the configuration. For example, it’s an error to have a CryptoProvider that has no cipher suites.

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_server_credential_resolver - to send a certificate chosen dynamically

For example:

ClientConfig::builder(Arc::new(DEFAULT_PROVIDER))
    .with_root_certificates(root_certs)
    .with_no_client_auth()
    .unwrap();

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_server_credential_resolver - to send a certificate chosen dynamically

For example:

ServerConfig::builder(Arc::new(DEFAULT_PROVIDER))
    .with_no_client_auth()
    .with_single_cert(Arc::new(Identity::from_cert_chain(certs).unwrap()), private_key)
    .expect("bad certificate/key/provider");

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:

• 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() or ServerConfig::builder(). This determines which cryptographic backend is used.

Implementations

impl<Side: ConfigSide, State> ConfigBuilder<Side, State>

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

Return the crypto provider used to construct this builder.

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(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 for more information.

pub fn with_ech(self, mode: EchMode) -> Self

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

This requires TLS 1.3 as the only supported protocol version to meet the requirement to support ECH. At the end, the config building process will return an error if either TLS1.3 is not supported by the provider, or TLS1.2 is supported.

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.

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, identity: Arc<Identity<'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 CryptoProviders support all three encodings, but other CryptoProviders may not.

This function fails if key_der is invalid.

pub fn with_no_client_auth(self) -> Result<ClientConfig, Error>

Do not support client auth.

pub fn with_client_credential_resolver( self, client_auth_cert_resolver: Arc<dyn ClientCredentialResolver>, ) -> Result<ClientConfig, Error>

Sets a custom ClientCredentialResolver.

impl ConfigBuilder<ServerConfig, WantsVerifier>

pub fn with_client_cert_verifier( self, client_cert_verifier: Arc<dyn ClientVerifier>, ) -> 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, identity: Arc<Identity<'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 CryptoProviders 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, identity: Arc<Identity<'static>>, key_der: PrivateKeyDer<'static>, ocsp: Arc<[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 CryptoProviders 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_server_credential_resolver( self, cert_resolver: Arc<dyn ServerCredentialResolver>, ) -> Result<ServerConfig, Error>

Sets a custom ServerCredentialResolver.

Trait Implementations

impl<Side: Clone + ConfigSide, State: Clone> Clone for ConfigBuilder<Side, State>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.