Struct rustls::ConfigBuilder

source ·
pub struct ConfigBuilder<Side: ConfigSide, State> { /* private fields */ }
Expand description

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:

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

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:

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

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:

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§

source§

impl<S: ConfigSide> ConfigBuilder<S, WantsVersions>

source

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.

source

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

Use a specific set of protocol versions.

source§

impl ConfigBuilder<ClientConfig, WantsVersions>

source

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.

source§

impl ConfigBuilder<ClientConfig, WantsVerifier>

source

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()?
+ )
source

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.

source

pub fn dangerous(self) -> DangerousClientConfigBuilder

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

source§

impl ConfigBuilder<ClientConfig, WantsClientCert>

source

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 CryptoProviders support all three encodings, but other CryptoProviders may not.

This function fails if key_der is invalid.

source

pub fn with_no_client_auth(self) -> ClientConfig

Do not support client auth.

source

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

Sets a custom ResolvesClientCert.

source§

impl ConfigBuilder<ServerConfig, WantsVerifier>

source

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

Choose how to verify client certificates.

source

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

Disable client authentication.

source§

impl ConfigBuilder<ServerConfig, WantsServerCert>

source

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

source

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

source

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

Sets a custom ResolvesServerCert.

Trait Implementations§

source§

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<Side, State> Freeze for ConfigBuilder<Side, State>
where State: Freeze,

§

impl<Side, State> RefUnwindSafe for ConfigBuilder<Side, State>
where State: RefUnwindSafe, Side: RefUnwindSafe,

§

impl<Side, State> Send for ConfigBuilder<Side, State>
where State: Send, Side: Send,

§

impl<Side, State> Sync for ConfigBuilder<Side, State>
where State: Sync, Side: Sync,

§

impl<Side, State> Unpin for ConfigBuilder<Side, State>
where State: Unpin, Side: Unpin,

§

impl<Side, State> UnwindSafe for ConfigBuilder<Side, State>
where State: UnwindSafe, Side: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.