结构体 ConfigBuilder 

pub struct ConfigBuilder<Side: ConfigSide, State> { /* private fields */ }

A builder 用于 ServerConfig 或 ClientConfig values.

To get one of these, call ServerConfig::builder() 或 ClientConfig::builder()。

To build 一个 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 并 ClientConfig。

此 usual choice 用于 protocol primitives is 到 call ClientConfig::builder/ServerConfig::builder which will use rustls’ default cryptographic provider 并 safe defaults 用于 ciphersuites 并 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. 此 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 or
• ConfigBuilder::dangerous() and DangerousClientConfigBuilder::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 certificate
• ConfigBuilder::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 certificate
• ConfigBuilder::with_single_cert_with_ocsp - to send a specific certificate, plus stapled OCSP
• ConfigBuilder::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:

• WantsVersions
• WantsVerifier
• WantsClientCert
• WantsServerCert

此 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 从 the compiler mentioning some of these types.

Additionally, ServerConfig and ClientConfig carry a private field containing a CryptoProvider, 从 ClientConfig::builder_with_provider() or ServerConfig::builder_with_provider()。 This determines which cryptographic backend is used. 此 default is the process-default provider。

实现

impl<Side: ConfigSide, State> ConfigBuilder<Side, State>

pub fn crypto_provider(&self) -> &Arc<CryptoProvider>

返回用于构造此 builder 的密码提供者。

impl<S: ConfigSide> ConfigBuilder<S, WantsVersions>

pub fn with_safe_default_protocol_versions( self, ) -> Result<ConfigBuilder<S, WantsVerifier>, Error>

接受默认的协议版本：同时启用 TLS1.2 和 TLS 1.3。

pub fn with_protocol_versions( self, versions: &[&'static SupportedProtocolVersion], ) -> Result<ConfigBuilder<S, WantsVerifier>, Error>

使用特定的协议版本集合。

impl ConfigBuilder<ClientConfig, WantsVersions>

pub fn with_ech( self, mode: EchMode, ) -> Result<ConfigBuilder<ClientConfig, WantsVerifier>, Error>

启用 Encrypted Client Hello (ECH) in the given mode.

This implicitly selects TLS 1.3 as the only supported protocol version 到 meet the requirement 到 support ECH.

此 ClientConfig that ， produced by this builder ， specific 到 the provided crate::client::EchConfig 并 may not be appropriate 用于 all connections made by the program. In this case the configuration should only be shared by connections intended 用于 domains that offer the provided crate::client::EchConfig in their DNS zone.

impl ConfigBuilder<ClientConfig, WantsVerifier>

pub fn with_root_certificates( self, root_store: impl Into<Arc<RootCertStore>>, ) -> ConfigBuilder<ClientConfig, WantsClientCert>

选择如何验证服务器证书。

使用此函数不会配置吊销。 If you wish 到 configure revocation, instead use:

- .with_root_certificates(root_store)
+ .with_webpki_verifier(
+   WebPkiServerVerifier::builder_with_provider(root_store, crypto_provider)
+   .with_crls(...)
+   .build()?
+ )

pub fn with_webpki_verifier( self, verifier: Arc<WebPkiServerVerifier>, ) -> ConfigBuilder<ClientConfig, WantsClientCert>

使用 webpki 验证器选择如何验证服务器证书。

，请参见webpki::WebPkiServerVerifier::builder 并 webpki::WebPkiServerVerifier::builder_with_provider 以获取更多信息。

pub fn dangerous(self) -> DangerousClientConfigBuilder

访问配置选项，其使用危险且需要 extra care.

impl ConfigBuilder<ClientConfig, WantsClientCert>

pub fn with_client_auth_cert( self, cert_chain: Vec<CertificateDer<'static>>, key_der: PrivateKeyDer<'static>, ) -> Result<ClientConfig, Error>

Sets 一个 single certificate chain 并 matching 私钥 用于 use in client authentication.

cert_chain 是 vector of DER-encoded 证书 key_der 是 DER-encoded 私钥 as PKCS#1, PKCS#8, 或 SEC1. 此 aws-lc-rs 并 ring CryptoProviders support all three encodings, but other CryptoProviders may not.

This function fails if key_der is invalid.

pub fn with_no_client_auth(self) -> ClientConfig

不支持客户端身份验证。

pub fn with_client_cert_resolver( self, client_auth_cert_resolver: Arc<dyn ResolvesClientCert>, ) -> ClientConfig

设置一个自定义 ResolvesClientCert。

impl ConfigBuilder<ServerConfig, WantsVerifier>

pub fn with_client_cert_verifier( self, client_cert_verifier: Arc<dyn ClientCertVerifier>, ) -> ConfigBuilder<ServerConfig, WantsServerCert>

选择如何验证客户端证书。

pub fn with_no_client_auth(self) -> ConfigBuilder<ServerConfig, WantsServerCert>

禁用客户端身份验证。

impl ConfigBuilder<ServerConfig, WantsServerCert>

pub fn with_single_cert( self, cert_chain: Vec<CertificateDer<'static>>, key_der: PrivateKeyDer<'static>, ) -> Result<ServerConfig, Error>

Sets 一个 single certificate chain 并 matching 私钥. This certificate 并 key is 用 用于 all subsequent connections, irrespective of things like SNI hostname.

Note that the end-entity certificate must have the Subject Alternative Name extension 到 describe, e.g., the valid DNS name. 此 commonName field is disregarded.

cert_chain 是 vector of DER-encoded 证书 key_der 是 DER-encoded 私钥 as PKCS#1, PKCS#8, 或 SEC1. 此 aws-lc-rs 并 ring CryptoProviders support all three encodings, but other CryptoProviders may not.

This function fails if key_der is invalid, 或 if the SubjectPublicKeyInfo 从 the 私钥 does not match the public key 用于 the end-entity certificate 从 the cert_chain。

pub fn with_single_cert_with_ocsp( self, cert_chain: Vec<CertificateDer<'static>>, key_der: PrivateKeyDer<'static>, ocsp: Vec<u8>, ) -> Result<ServerConfig, Error>

Sets 一个 single certificate chain, matching 私钥 并 optional OCSP response. This certificate 并 key is 用 用于 all subsequent connections, irrespective of things like SNI hostname.

cert_chain 是 vector of DER-encoded 证书 key_der 是 DER-encoded 私钥 as PKCS#1, PKCS#8, 或 SEC1. 此 aws-lc-rs 并 ring CryptoProviders support all three encodings, but other CryptoProviders may not. ocsp 是 DER-encoded OCSP response. Ignored if zero length.

This function fails if key_der is invalid, 或 if the SubjectPublicKeyInfo 从 the 私钥 does not match the public key 用于 the end-entity certificate 从 the cert_chain。

pub fn with_cert_resolver( self, cert_resolver: Arc<dyn ResolvesServerCert>, ) -> ServerConfig

设置一个自定义 ResolvesServerCert。

Trait 实现

impl<Side: Clone + ConfigSide, State: Clone> Clone for ConfigBuilder<Side, State>

fn clone(&self) -> ConfigBuilder<Side, State>

返回值的副本。 更多信息

fn clone_from(&mut self, source: &Self)

Performs copy-assignment 从 source. 更多信息

impl<Side: ConfigSide, State: Debug> Debug for ConfigBuilder<Side, State>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

使用给定的格式化器格式化此值。 更多信息