pub struct MutualTls {
pub mandatory: bool,
/* private fields */
}
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. Whenfalse
, 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§
source§impl MutualTls
impl MutualTls
sourcepub fn from_path<C: AsRef<Path>>(ca_certs: C) -> Self
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");
sourcepub fn from_bytes(ca_certs: &[u8]) -> Self
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);
sourcepub fn mandatory(self, mandatory: bool) -> Self
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);