Struct rustls::ConfigBuilder
source · pub struct ConfigBuilder<Side: ConfigSide, State> {
pub(crate) state: State,
pub(crate) side: PhantomData<Side>,
}
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_client_auth_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.
Fields§
§state: State
§side: PhantomData<Side>
Implementations§
source§impl<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.
source§impl<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.
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, WantsTransparencyPolicyOrClientCert>
pub fn with_root_certificates( self, root_store: impl Into<Arc<RootCertStore>>, ) -> ConfigBuilder<ClientConfig, WantsTransparencyPolicyOrClientCert>
Choose how to verify server 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.
source§impl 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_client_auth_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey,
) -> Result<ClientConfig, Error>
pub fn with_client_auth_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_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey,
) -> Result<ClientConfig, Error>
👎Deprecated since 0.21.4: Use with_client_auth_cert
instead
pub fn with_single_cert( self, cert_chain: Vec<Certificate>, key_der: PrivateKey, ) -> Result<ClientConfig, Error>
with_client_auth_cert
insteadSets 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
.
fn with_logs( self, ct_policy: Option<CertificateTransparencyPolicy>, ) -> ConfigBuilder<ClientConfig, WantsClientCert>
source§impl ConfigBuilder<ClientConfig, WantsClientCert>
impl ConfigBuilder<ClientConfig, WantsClientCert>
sourcepub fn with_client_auth_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey,
) -> Result<ClientConfig, Error>
pub fn with_client_auth_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_single_cert(
self,
cert_chain: Vec<Certificate>,
key_der: PrivateKey,
) -> Result<ClientConfig, Error>
👎Deprecated since 0.21.4: Use with_client_auth_cert
instead
pub fn with_single_cert( self, cert_chain: Vec<Certificate>, key_der: PrivateKey, ) -> Result<ClientConfig, Error>
with_client_auth_cert
insteadSets 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
.
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<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§
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 more