logo
pub struct MutualTls {
    pub mandatory: bool,
    /* private fields */
}
Available on crate feature mtls only.
Expand description

Mutual TLS configuration.

Configuration works in concert with the mtls module, which provides a request guard to validate, verify, and retrieve client certificates in routes.

By default, mutual TLS is disabled and client certificates are not required, validated or verified. To enable mutual TLS, the mtls feature must be enabled and support configured via two tls.mutual parameters:

  • ca_certs

    A required path to a PEM file or raw bytes to a DER-encoded X.509 TLS certificate chain for the certificate authority to verify client certificates against. When a path is configured in a file, such as Rocket.toml, relative paths are interpreted as relative to the source file’s directory.

  • mandatory

    An optional boolean that control whether client authentication is required.

    When true, client authentication is required. TLS connections where the client does not present a certificate are immediately terminated. When false, the client is not required to present a certificate. In either case, if a certificate is presented, it must be valid or the connection is terminated.

In a Rocket.toml, configuration might look like:

[default.tls.mutual]
ca_certs = "/ssl/ca_cert.pem"
mandatory = true                # when absent, defaults to false

Programmatically, configuration might look like:

use rocket::config::{Config, TlsConfig, MutualTls};

#[launch]
fn rocket() -> _ {
    let tls_config = TlsConfig::from_paths("/ssl/certs.pem", "/ssl/key.pem")
        .with_mutual(MutualTls::from_path("/ssl/ca_cert.pem"));

    let config = Config {
        tls: Some(tls_config),
        ..Default::default()
    };

    rocket::custom(config)
}

Once mTLS is configured, the mtls::Certificate request guard can be used to retrieve client certificates in routes.

Fields

mandatory: bool

Whether the client is required to present a certificate.

When true, the client is required to present a valid certificate to proceed with TLS. When false, the client is not required to present a certificate. In either case, if a certificate is presented, it must be valid or the connection is terminated.

Implementations

Constructs a MutualTls from a path to a PEM file with a certificate authority ca_certs DER-encoded X.509 TLS certificate chain. This method does no validation; it simply creates a structure suitable for passing into a TlsConfig.

These certificates will be used to verify client-presented certificates in TLS connections.

Example
use rocket::config::MutualTls;

let tls_config = MutualTls::from_path("/ssl/ca_certs.pem");

Constructs a MutualTls from a byte buffer to a certificate authority ca_certs DER-encoded X.509 TLS certificate chain. This method does no validation; it simply creates a structure suitable for passing into a TlsConfig.

These certificates will be used to verify client-presented certificates in TLS connections.

Example
use rocket::config::MutualTls;

let mtls_config = MutualTls::from_bytes(ca_certs_buf);

Sets whether client authentication is required. Disabled by default.

When true, client authentication will be required. TLS connections where the client does not present a certificate will be immediately terminated. When false, the client is not required to present a certificate. In either case, if a certificate is presented, it must be valid or the connection is terminated.

Example
use rocket::config::MutualTls;

let mtls_config = MutualTls::from_bytes(ca_certs_buf).mandatory(true);

Returns the value of the ca_certs parameter.

Example
use rocket::config::MutualTls;

let mtls_config = MutualTls::from_bytes(ca_certs_buf).mandatory(true);
assert_eq!(mtls_config.ca_certs().unwrap_right(), ca_certs_buf);

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

Deserialize this value from the given Serde deserializer. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

Serialize this value into the given Serde serializer. 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.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

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

Converts self into a collection.

Should always be Self

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.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more