Struct MutualTls

pub struct MutualTls {
    pub mandatory: bool,
    /* private fields */
}

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

impl MutualTls

pub fn from_path<C: AsRef<Path>>(ca_certs: C) -> Self

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");

pub fn from_bytes(ca_certs: &[u8]) -> Self

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);

pub fn mandatory(self, mandatory: bool) -> Self

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);

pub fn ca_certs(&self) -> Either<PathBuf, &[u8]>

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

impl Clone for MutualTls

fn clone(&self) -> MutualTls

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MutualTls

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MutualTls

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for MutualTls

fn eq(&self, other: &MutualTls) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for MutualTls

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for MutualTls