Struct rustls::client::ClientConfig
source · pub struct ClientConfig {Show 13 fields
pub alpn_protocols: Vec<Vec<u8>>,
pub resumption: Resumption,
pub max_fragment_size: Option<usize>,
pub client_auth_cert_resolver: Arc<dyn ResolvesClientCert>,
pub enable_sni: bool,
pub key_log: Arc<dyn KeyLog>,
pub enable_secret_extraction: bool,
pub enable_early_data: bool,
pub require_ems: bool,
pub time_provider: Arc<dyn TimeProvider>,
pub cert_decompressors: Vec<&'static dyn CertDecompressor>,
pub cert_compressors: Vec<&'static dyn CertCompressor>,
pub cert_compression_cache: Arc<CompressionCache>,
/* private fields */
}
Expand description
Common configuration for (typically) all connections made by a program.
Making one of these is cheap, though one of the inputs may be expensive: gathering trust roots
from the operating system to add to the RootCertStore
passed to with_root_certificates()
(the rustls-native-certs crate is often used for this) may take on the order of a few hundred
milliseconds.
These must be created via the ClientConfig::builder()
or ClientConfig::builder_with_provider()
function.
Note that using ConfigBuilder<ClientConfig, WantsVersions>::with_ech()
will produce a common
configuration specific to the provided crate::client::EchConfig
that 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.
§Defaults
ClientConfig::max_fragment_size
: the default isNone
(meaning 16kB).ClientConfig::resumption
: supports resumption with up to 256 server names, using session ids or tickets, with a max of eight tickets per server.ClientConfig::alpn_protocols
: the default is empty – no ALPN protocol is negotiated.ClientConfig::key_log
: key material is not logged.ClientConfig::cert_decompressors
: depends on the crate features, seecompress::default_cert_decompressors()
.ClientConfig::cert_compressors
: depends on the crate features, seecompress::default_cert_compressors()
.ClientConfig::cert_compression_cache
: caches the most recently used 4 compressions
Fields§
§alpn_protocols: Vec<Vec<u8>>
Which ALPN protocols we include in our client hello. If empty, no ALPN extension is sent.
resumption: Resumption
How and when the client can resume a previous session.
max_fragment_size: Option<usize>
The maximum size of plaintext input to be emitted in a single TLS record. A value of None is equivalent to the TLS maximum of 16 kB.
rustls enforces an arbitrary minimum of 32 bytes for this field. Out of range values are reported as errors from ClientConnection::new.
Setting this value to a little less than the TCP MSS may improve latency for stream-y workloads.
client_auth_cert_resolver: Arc<dyn ResolvesClientCert>
How to decide what client auth certificate/keys to use.
enable_sni: bool
Whether to send the Server Name Indication (SNI) extension during the client handshake.
The default is true.
key_log: Arc<dyn KeyLog>
How to output key material for debugging. The default does nothing.
enable_secret_extraction: bool
Allows traffic secrets to be extracted after the handshake, e.g. for kTLS setup.
enable_early_data: bool
Whether to send data on the first flight (“early data”) in TLS 1.3 handshakes.
The default is false.
require_ems: bool
If set to true
, requires the server to support the extended
master secret extraction method defined in RFC 7627.
The default is true
if the fips
crate feature is enabled,
false
otherwise.
It must be set to true
to meet FIPS requirement mentioned in section
D.Q Transition of the TLS 1.2 KDF to Support the Extended Master
Secret from FIPS 140-3 IG.pdf.
time_provider: Arc<dyn TimeProvider>
Provides the current system time
cert_decompressors: Vec<&'static dyn CertDecompressor>
How to decompress the server’s certificate chain.
If this is non-empty, the RFC8779 certificate compression extension is offered, and any compressed certificates are transparently decompressed during the handshake.
This only applies to TLS1.3 connections. It is ignored for TLS1.2 connections.
cert_compressors: Vec<&'static dyn CertCompressor>
How to compress the client’s certificate chain.
If a server supports this extension, and advertises support for one of the compression algorithms included here, the client certificate will be compressed according to RFC8779.
This only applies to TLS1.3 connections. It is ignored for TLS1.2 connections.
cert_compression_cache: Arc<CompressionCache>
Caching for compressed certificates.
This is optional: compress::CompressionCache::Disabled
gives
a cache that does no caching.
Implementations§
source§impl ClientConfig
impl ClientConfig
sourcepub fn builder() -> ConfigBuilder<Self, WantsVerifier>
pub fn builder() -> ConfigBuilder<Self, WantsVerifier>
Create a builder for a client configuration with
the process-default CryptoProvider
and safe protocol version defaults.
For more information, see the ConfigBuilder
documentation.
sourcepub fn builder_with_protocol_versions(
versions: &[&'static SupportedProtocolVersion],
) -> ConfigBuilder<Self, WantsVerifier>
pub fn builder_with_protocol_versions( versions: &[&'static SupportedProtocolVersion], ) -> ConfigBuilder<Self, WantsVerifier>
Create a builder for a client configuration with
the process-default CryptoProvider
and the provided protocol versions.
Panics if
- the supported versions are not compatible with the provider (eg. the combination of ciphersuites supported by the provider and supported versions lead to zero cipher suites being usable),
- if a
CryptoProvider
cannot be resolved using a combination of the crate features and process default.
For more information, see the ConfigBuilder
documentation.
sourcepub fn builder_with_provider(
provider: Arc<CryptoProvider>,
) -> ConfigBuilder<Self, WantsVersions>
pub fn builder_with_provider( provider: Arc<CryptoProvider>, ) -> ConfigBuilder<Self, WantsVersions>
Create a builder for a client configuration with a specific CryptoProvider
.
This will use the provider’s configured ciphersuites. You must additionally choose
which protocol versions to enable, using with_protocol_versions
or
with_safe_default_protocol_versions
and handling the Result
in case a protocol
version is not supported by the provider’s ciphersuites.
For more information, see the ConfigBuilder
documentation.
sourcepub fn builder_with_details(
provider: Arc<CryptoProvider>,
time_provider: Arc<dyn TimeProvider>,
) -> ConfigBuilder<Self, WantsVersions>
pub fn builder_with_details( provider: Arc<CryptoProvider>, time_provider: Arc<dyn TimeProvider>, ) -> ConfigBuilder<Self, WantsVersions>
Create a builder for a client configuration with no default implementation details.
This API must be used by no_std
users.
You must provide a specific TimeProvider
.
You must provide a specific CryptoProvider
.
This will use the provider’s configured ciphersuites. You must additionally choose
which protocol versions to enable, using with_protocol_versions
or
with_safe_default_protocol_versions
and handling the Result
in case a protocol
version is not supported by the provider’s ciphersuites.
For more information, see the ConfigBuilder
documentation.
sourcepub fn fips(&self) -> bool
pub fn fips(&self) -> bool
Return true if connections made with this ClientConfig
will
operate in FIPS mode.
This is different from CryptoProvider::fips()
: CryptoProvider::fips()
is concerned only with cryptography, whereas this also covers TLS-level
configuration that NIST recommends, as well as ECH HPKE suites if applicable.
sourcepub fn crypto_provider(&self) -> &Arc<CryptoProvider>
pub fn crypto_provider(&self) -> &Arc<CryptoProvider>
Return the crypto provider used to construct this client configuration.
sourcepub fn dangerous(&mut self) -> DangerousClientConfig<'_>
pub fn dangerous(&mut self) -> DangerousClientConfig<'_>
Access configuration options whose use is dangerous and requires extra care.
Trait Implementations§
source§impl Clone for ClientConfig
impl Clone for ClientConfig
source§fn clone(&self) -> ClientConfig
fn clone(&self) -> ClientConfig
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for ClientConfig
impl Debug for ClientConfig
impl ConfigSide for ClientConfig
Auto Trait Implementations§
impl Freeze for ClientConfig
impl !RefUnwindSafe for ClientConfig
impl Send for ClientConfig
impl Sync for ClientConfig
impl Unpin for ClientConfig
impl !UnwindSafe for ClientConfig
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
)