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:
ConfigBuilder::with_root_certificates
orConfigBuilder::dangerous()
andDangerousClientConfigBuilder::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 certificateConfigBuilder::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 certificateConfigBuilder::with_single_cert_with_ocsp
- to send a specific certificate, plus stapled OCSPConfigBuilder::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:
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>
impl<S: ConfigSide> ConfigBuilder<S, WantsVersions>
sourcepub fn with_safe_default_protocol_versions(
self,
) -> Result<ConfigBuilder<S, WantsVerifier>, Error>
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.
sourcepub fn with_protocol_versions(
self,
versions: &[&'static SupportedProtocolVersion],
) -> Result<ConfigBuilder<S, WantsVerifier>, Error>
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>
impl ConfigBuilder<ClientConfig, WantsVersions>
sourcepub fn with_ech(
self,
mode: EchMode,
) -> Result<ConfigBuilder<ClientConfig, WantsVerifier>, Error>
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>
impl ConfigBuilder<ClientConfig, WantsVerifier>
sourcepub fn with_root_certificates(
self,
root_store: impl Into<Arc<RootCertStore>>,
) -> ConfigBuilder<ClientConfig, WantsClientCert>
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()?
+ )
sourcepub fn with_webpki_verifier(
self,
verifier: Arc<WebPkiServerVerifier>,
) -> ConfigBuilder<ClientConfig, WantsClientCert>
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.
sourcepub fn dangerous(self) -> DangerousClientConfigBuilder
pub fn dangerous(self) -> DangerousClientConfigBuilder
Access configuration options whose use is dangerous and requires extra care.
source§impl ConfigBuilder<ClientConfig, WantsClientCert>
impl ConfigBuilder<ClientConfig, WantsClientCert>
sourcepub fn with_client_auth_cert(
self,
cert_chain: Vec<CertificateDer<'static>>,
key_der: PrivateKeyDer<'static>,
) -> Result<ClientConfig, Error>
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
s support all three encodings,
but other CryptoProviders
may not.
This function fails if key_der
is invalid.
sourcepub fn with_no_client_auth(self) -> ClientConfig
pub fn with_no_client_auth(self) -> ClientConfig
Do not support client auth.
sourcepub fn with_client_cert_resolver(
self,
client_auth_cert_resolver: Arc<dyn ResolvesClientCert>,
) -> ClientConfig
pub fn with_client_cert_resolver( self, client_auth_cert_resolver: Arc<dyn ResolvesClientCert>, ) -> ClientConfig
Sets a custom ResolvesClientCert
.
source§impl ConfigBuilder<ServerConfig, WantsVerifier>
impl ConfigBuilder<ServerConfig, WantsVerifier>
sourcepub fn with_client_cert_verifier(
self,
client_cert_verifier: Arc<dyn ClientCertVerifier>,
) -> ConfigBuilder<ServerConfig, WantsServerCert>
pub fn with_client_cert_verifier( self, client_cert_verifier: Arc<dyn ClientCertVerifier>, ) -> ConfigBuilder<ServerConfig, WantsServerCert>
Choose how to verify client certificates.
sourcepub fn with_no_client_auth(self) -> ConfigBuilder<ServerConfig, WantsServerCert>
pub fn with_no_client_auth(self) -> ConfigBuilder<ServerConfig, WantsServerCert>
Disable client authentication.
source§impl ConfigBuilder<ServerConfig, WantsServerCert>
impl ConfigBuilder<ServerConfig, WantsServerCert>
sourcepub fn with_single_cert(
self,
cert_chain: Vec<CertificateDer<'static>>,
key_der: PrivateKeyDer<'static>,
) -> Result<ServerConfig, Error>
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
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
.
sourcepub fn with_single_cert_with_ocsp(
self,
cert_chain: Vec<CertificateDer<'static>>,
key_der: PrivateKeyDer<'static>,
ocsp: Vec<u8>,
) -> Result<ServerConfig, Error>
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
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
.
sourcepub fn with_cert_resolver(
self,
cert_resolver: Arc<dyn ResolvesServerCert>,
) -> ServerConfig
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>
impl<Side: Clone + ConfigSide, State: Clone> Clone for ConfigBuilder<Side, State>
source§fn clone(&self) -> ConfigBuilder<Side, State>
fn clone(&self) -> ConfigBuilder<Side, State>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreAuto 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>
impl<Side, State> Sync for ConfigBuilder<Side, State>
impl<Side, State> Unpin for ConfigBuilder<Side, State>
impl<Side, State> UnwindSafe for ConfigBuilder<Side, State>where
State: UnwindSafe,
Side: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)