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 ring::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, 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.
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.
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§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)