Struct rustls::ConfigBuilder
source · [−]pub struct ConfigBuilder<Side: ConfigSide, State> { /* private fields */ }
Expand description
Building a ServerConfig
or ClientConfig
in a linker-friendly and
complete way.
Linker-friendly: meaning unused cipher suites, protocol versions, key exchange mechanisms, etc. can be discarded by the linker as they’ll be unreferenced.
Complete: the type system ensures all decisions required to run a server or client have been made by the time the process finishes.
Example, to make a ServerConfig
:
ServerConfig::builder()
.with_safe_default_cipher_suites()
.with_safe_default_kx_groups()
.with_safe_default_protocol_versions()
.unwrap()
.with_no_client_auth()
.with_single_cert(certs, private_key)
.expect("bad certificate/key");
This may be shortened to:
ServerConfig::builder()
.with_safe_defaults()
.with_no_client_auth()
.with_single_cert(certs, private_key)
.expect("bad certificate/key");
To make a ClientConfig
:
ClientConfig::builder()
.with_safe_default_cipher_suites()
.with_safe_default_kx_groups()
.with_safe_default_protocol_versions()
.unwrap()
.with_root_certificates(root_certs)
.with_single_cert(certs, private_key)
.expect("bad certificate/key");
This may be shortened to:
ClientConfig::builder()
.with_safe_defaults()
.with_root_certificates(root_certs)
.with_no_client_auth();
The types used here fit together like this:
- Call
ClientConfig::builder()
orServerConfig::builder()
to initialize a builder. - You must make a decision on which cipher suites to use, typically
by calling
ConfigBuilder<S, WantsCipherSuites>::with_safe_default_cipher_suites()
. - Now you must make a decision
on key exchange groups: typically by calling
ConfigBuilder<S, WantsKxGroups>::with_safe_default_kx_groups()
. - Now you must make
a decision on which protocol versions to support, typically by calling
ConfigBuilder<S, WantsVersions>::with_safe_default_protocol_versions()
. - Now see
ConfigBuilder<ClientConfig, WantsVerifier>
orConfigBuilder<ServerConfig, WantsVerifier>
for further steps.
Implementations
sourceimpl<S: ConfigSide> ConfigBuilder<S, WantsCipherSuites>
impl<S: ConfigSide> ConfigBuilder<S, WantsCipherSuites>
sourcepub fn with_safe_defaults(self) -> ConfigBuilder<S, WantsVerifier>
pub fn with_safe_defaults(self) -> ConfigBuilder<S, WantsVerifier>
Start side-specific config with defaults for underlying cryptography.
If used, this will enable all safe supported cipher suites (DEFAULT_CIPHER_SUITES
), all
safe supported key exchange groups (ALL_KX_GROUPS
) and all safe supported protocol
versions (DEFAULT_VERSIONS
).
These are safe defaults, useful for 99% of applications.
sourcepub fn with_cipher_suites(
self,
cipher_suites: &[SupportedCipherSuite]
) -> ConfigBuilder<S, WantsKxGroups>
pub fn with_cipher_suites(
self,
cipher_suites: &[SupportedCipherSuite]
) -> ConfigBuilder<S, WantsKxGroups>
Choose a specific set of cipher suites.
sourcepub fn with_safe_default_cipher_suites(self) -> ConfigBuilder<S, WantsKxGroups>
pub fn with_safe_default_cipher_suites(self) -> ConfigBuilder<S, WantsKxGroups>
Choose the default set of cipher suites (DEFAULT_CIPHER_SUITES
).
Note that this default provides only high-quality suites: there is no need to filter out low-, export- or NULL-strength cipher suites: rustls does not implement these.
sourceimpl<S: ConfigSide> ConfigBuilder<S, WantsKxGroups>
impl<S: ConfigSide> ConfigBuilder<S, WantsKxGroups>
sourcepub fn with_kx_groups(
self,
kx_groups: &[&'static SupportedKxGroup]
) -> ConfigBuilder<S, WantsVersions>
pub fn with_kx_groups(
self,
kx_groups: &[&'static SupportedKxGroup]
) -> ConfigBuilder<S, WantsVersions>
Choose a specific set of key exchange groups.
sourcepub fn with_safe_default_kx_groups(self) -> ConfigBuilder<S, WantsVersions>
pub fn with_safe_default_kx_groups(self) -> ConfigBuilder<S, WantsVersions>
Choose the default set of key exchange groups (ALL_KX_GROUPS
).
This is a safe default: rustls doesn’t implement any poor-quality groups.
sourceimpl<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.
sourceimpl ConfigBuilder<ClientConfig, WantsVerifier>
impl ConfigBuilder<ClientConfig, WantsVerifier>
sourcepub fn with_root_certificates(
self,
root_store: RootCertStore
) -> ConfigBuilder<ClientConfig, WantsTransparencyPolicyOrClientCert>
pub fn with_root_certificates(
self,
root_store: RootCertStore
) -> ConfigBuilder<ClientConfig, WantsTransparencyPolicyOrClientCert>
Choose how to verify client certificates.
sourcepub fn with_custom_certificate_verifier(
self,
verifier: Arc<dyn ServerCertVerifier>
) -> ConfigBuilder<ClientConfig, WantsClientCert>
pub fn with_custom_certificate_verifier(
self,
verifier: Arc<dyn ServerCertVerifier>
) -> ConfigBuilder<ClientConfig, WantsClientCert>
Set a custom certificate verifier.
sourceimpl ConfigBuilder<ClientConfig, WantsTransparencyPolicyOrClientCert>
impl ConfigBuilder<ClientConfig, WantsTransparencyPolicyOrClientCert>
sourcepub fn with_certificate_transparency_logs(
self,
logs: &'static [&'static Log<'_>],
validation_deadline: SystemTime
) -> ConfigBuilder<ClientConfig, WantsClientCert>
pub fn with_certificate_transparency_logs(
self,
logs: &'static [&'static Log<'_>],
validation_deadline: SystemTime
) -> ConfigBuilder<ClientConfig, WantsClientCert>
Set Certificate Transparency logs to use for server certificate validation.
Because Certificate Transparency logs are sharded on a per-year basis and can be trusted or distrusted relatively quickly, rustls stores a validation deadline. Server certificates will be validated against the configured CT logs until the deadline expires. After the deadline, certificates will no longer be validated, and a warning message will be logged. The deadline may vary depending on how often you deploy builds with updated dependencies.
sourcepub fn with_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey
) -> Result<ClientConfig, Error>
pub fn with_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey
) -> 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 RSA, ECDSA, or Ed25519 private key.
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
.
sourceimpl ConfigBuilder<ClientConfig, WantsClientCert>
impl ConfigBuilder<ClientConfig, WantsClientCert>
sourcepub fn with_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey
) -> Result<ClientConfig, Error>
pub fn with_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey
) -> 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 RSA, ECDSA, or Ed25519 private key.
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
.
sourceimpl 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.
sourceimpl ConfigBuilder<ServerConfig, WantsServerCert>
impl ConfigBuilder<ServerConfig, WantsServerCert>
sourcepub fn with_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey
) -> Result<ServerConfig, Error>
pub fn with_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey
) -> 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 RSA, ECDSA, or Ed25519 private key.
This function fails if key_der
is invalid.
sourcepub fn with_single_cert_with_ocsp_and_sct(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey,
ocsp: Vec<u8>,
scts: Vec<u8>
) -> Result<ServerConfig, Error>
pub fn with_single_cert_with_ocsp_and_sct(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey,
ocsp: Vec<u8>,
scts: Vec<u8>
) -> Result<ServerConfig, Error>
Sets a single certificate chain, matching private key, OCSP response and SCTs. 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 RSA, ECDSA, or Ed25519 private key.
ocsp
is a DER-encoded OCSP response. Ignored if zero length.
scts
is an SignedCertificateTimestampList
encoding (see RFC6962)
and is ignored if empty.
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
sourceimpl<Side: Clone + ConfigSide, State: Clone> Clone for ConfigBuilder<Side, State>
impl<Side: Clone + ConfigSide, State: Clone> Clone for ConfigBuilder<Side, State>
sourcefn clone(&self) -> ConfigBuilder<Side, State>
fn clone(&self) -> ConfigBuilder<Side, State>
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl<Side: ConfigSide, State: Debug> Debug for ConfigBuilder<Side, State>
impl<Side: ConfigSide, State: Debug> Debug for ConfigBuilder<Side, State>
Auto Trait Implementations
impl<Side, State> RefUnwindSafe for ConfigBuilder<Side, State> where
Side: RefUnwindSafe,
State: RefUnwindSafe,
impl<Side, State> Send for ConfigBuilder<Side, State> where
Side: Send,
State: Send,
impl<Side, State> Sync for ConfigBuilder<Side, State> where
Side: Sync,
State: Sync,
impl<Side, State> Unpin for ConfigBuilder<Side, State> where
Side: Unpin,
State: Unpin,
impl<Side, State> UnwindSafe for ConfigBuilder<Side, State> where
Side: UnwindSafe,
State: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more