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:

  1. Call ClientConfig::builder() or ServerConfig::builder() to initialize a builder.
  2. You must make a decision on which cipher suites to use, typically by calling ConfigBuilder<S, WantsCipherSuites>::with_safe_default_cipher_suites().
  3. Now you must make a decision on key exchange groups: typically by calling ConfigBuilder<S, WantsKxGroups>::with_safe_default_kx_groups().
  4. Now you must make a decision on which protocol versions to support, typically by calling ConfigBuilder<S, WantsVersions>::with_safe_default_protocol_versions().
  5. Now see ConfigBuilder<ClientConfig, WantsVerifier> or ConfigBuilder<ServerConfig, WantsVerifier> for further steps.

Implementations

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.

Choose a specific set of cipher suites.

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.

Choose a specific set of key exchange groups.

Choose the default set of key exchange groups (ALL_KX_GROUPS).

This is a safe default: rustls doesn’t implement any poor-quality groups.

Accept the default protocol versions: both TLS1.2 and TLS1.3 are enabled.

Use a specific set of protocol versions.

Choose how to verify client certificates.

Set a custom certificate verifier.

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.

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.

Do not support client auth.

Sets a custom ResolvesClientCert.

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.

Do not support client auth.

Sets a custom ResolvesClientCert.

Choose how to verify client certificates.

Disable client authentication.

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.

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.

Sets a custom ResolvesServerCert.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.