Struct rocket::mtls::MtlsConfig

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

Available on crate feature mtls only.

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::mtls::MtlsConfig;
use rocket::figment::providers::Serialized;

#[launch]
fn rocket() -> _ {
    let mtls = MtlsConfig::from_path("/ssl/ca_cert.pem");
    rocket::custom(rocket::Config::figment().merge(("tls.mutual", mtls)))
}

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 MtlsConfig

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

Constructs a MtlsConfig 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 an MtlsConfig for later use.

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

Example

use rocket::mtls::MtlsConfig;

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

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

Constructs a MtlsConfig 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 an MtlsConfig for later use.

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

Example

use rocket::mtls::MtlsConfig;

let mtls_config = MtlsConfig::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::mtls::MtlsConfig;

let mtls_config = MtlsConfig::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::mtls::MtlsConfig;

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

pub fn ca_certs_reader(&self) -> Result<Box<dyn BufRead + Sync + Send>>

Trait Implementations

impl Clone for MtlsConfig

fn clone(&self) -> MtlsConfig

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for MtlsConfig

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MtlsConfig

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for MtlsConfig

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

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

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

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

impl Serialize for MtlsConfig

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 MtlsConfig