Struct rocket::tls::TlsConfig

pub struct TlsConfig { /* private fields */ }

Available on crate feature tls only.

TLS configuration: certificate chain, key, and ciphersuites.

Four parameters control tls configuration:

• certs, key

  Both certs and key can be configured as a path or as raw bytes. certs must be a DER-encoded X.509 TLS certificate chain, while key must be a DER-encoded ASN.1 key in either PKCS#8, PKCS#1, or SEC1 format. When a path is configured in a file, such as Rocket.toml, relative paths are interpreted as relative to the source file’s directory.

• ciphers

  A list of supported CipherSuites in server-preferred order, from most to least. It is not required and defaults to CipherSuite::DEFAULT_SET, the recommended setting.

• prefer_server_cipher_order

  A boolean that indicates whether the server should regard its own ciphersuite preferences over the client’s. The default and recommended value is false.

Additionally, the mutual parameter controls if and how the server authenticates clients via mutual TLS. It works in concert with the mtls module. See MtlsConfig for configuration details.

In Rocket.toml, configuration might look like:

[default.tls]
certs = "private/rsa_sha256_cert.pem"
key = "private/rsa_sha256_key.pem"

With a custom programmatic configuration, this might look like:

use rocket::tls::{TlsConfig, CipherSuite};
use rocket::figment::providers::Serialized;

#[launch]
fn rocket() -> _ {
    let tls = TlsConfig::from_paths("/ssl/certs.pem", "/ssl/key.pem")
        .with_ciphers(CipherSuite::TLS_V13_SET)
        .with_preferred_server_cipher_order(true);

    rocket::custom(rocket::Config::figment().merge(("tls", tls)))
}

Or by creating a custom figment:

use rocket::figment::Figment;
use rocket::tls::TlsConfig;

let figment = Figment::new()
    .merge(("certs", "path/to/certs.pem"))
    .merge(("key", vec![0; 32]));

Implementations

impl TlsConfig

pub fn from_paths<C, K>(certs: C, key: K) -> Self

where C: AsRef<Path>, K: AsRef<Path>,

Constructs a TlsConfig from paths to a certs certificate chain a key private-key. This method does no validation; it simply creates a structure suitable for passing into a Config.

Example

use rocket::tls::TlsConfig;

let tls_config = TlsConfig::from_paths("/ssl/certs.pem", "/ssl/key.pem");

pub fn from_bytes(certs: &[u8], key: &[u8]) -> Self

Constructs a TlsConfig from byte buffers to a certs certificate chain a key private-key. This method does no validation; it simply creates a structure suitable for passing into a Config.

Example

use rocket::tls::TlsConfig;

let tls_config = TlsConfig::from_bytes(certs_buf, key_buf);

pub fn with_ciphers<C>(self, ciphers: C) -> Self

where C: IntoIterator<Item = CipherSuite>,

Sets the cipher suites supported by the server and their order of preference from most to least preferred.

If a suite appears more than once in ciphers, only the first suite (and its relative order) is considered. If all cipher suites for a version oF TLS are disabled, the respective protocol itself is disabled entirely.

Example

Disable TLS v1.2 by selecting only TLS v1.3 cipher suites:

use rocket::tls::{TlsConfig, CipherSuite};

let tls_config = TlsConfig::from_bytes(certs_buf, key_buf)
    .with_ciphers(CipherSuite::TLS_V13_SET);

Enable only ChaCha20-Poly1305 based TLS v1.2 and TLS v1.3 cipher suites:

use rocket::tls::{TlsConfig, CipherSuite};

let tls_config = TlsConfig::from_bytes(certs_buf, key_buf)
    .with_ciphers([
        CipherSuite::TLS_CHACHA20_POLY1305_SHA256,
        CipherSuite::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
        CipherSuite::TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
    ]);

Later duplicates are ignored.

use rocket::tls::{TlsConfig, CipherSuite};

let tls_config = TlsConfig::from_bytes(certs_buf, key_buf)
    .with_ciphers([
        CipherSuite::TLS_CHACHA20_POLY1305_SHA256,
        CipherSuite::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
        CipherSuite::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
        CipherSuite::TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
        CipherSuite::TLS_CHACHA20_POLY1305_SHA256,
    ]);

let ciphers: Vec<_> = tls_config.ciphers().collect();
assert_eq!(ciphers, &[
    CipherSuite::TLS_CHACHA20_POLY1305_SHA256,
    CipherSuite::TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,
    CipherSuite::TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,
]);

pub fn with_preferred_server_cipher_order( self, prefer_server_order: bool, ) -> Self

Whether to prefer the server’s cipher suite order and ignore the client’s preferences (true) or choose the first supported ciphersuite in the client’s preference list (false). The default prefer’s the client’s order (false).

During TLS cipher suite negotiation, the client presents a set of supported ciphers in its preferred order. From this list, the server chooses one cipher suite. By default, the server chooses the first cipher it supports from the list.

By setting prefer_server_order to true, the server instead chooses the first ciphersuite in it prefers that the client also supports, ignoring the client’s preferences.

Example

use rocket::tls::{TlsConfig, CipherSuite};

let tls_config = TlsConfig::from_bytes(certs_buf, key_buf)
    .with_ciphers(CipherSuite::TLS_V13_SET)
    .with_preferred_server_cipher_order(true);

pub fn with_mutual(self, config: MtlsConfig) -> Self

Available on crate feature mtls only.

Set mutual TLS configuration. See MtlsConfig for details.

Example

use rocket::tls::TlsConfig;
use rocket::mtls::MtlsConfig;

let mtls_config = MtlsConfig::from_path("path/to/cert.pem").mandatory(true);
let tls_config = TlsConfig::from_bytes(certs, key).with_mutual(mtls_config);
assert!(tls_config.mutual().is_some());

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

Returns the value of the certs parameter.

Example

use rocket::tls::TlsConfig;
use rocket::figment::Figment;

let figment = Figment::new()
    .merge(("certs", "/path/to/certs.pem"))
    .merge(("key", vec![0; 32]));

let tls_config: TlsConfig = figment.extract().unwrap();
let cert_path = tls_config.certs().left().unwrap();
assert_eq!(cert_path, Path::new("/path/to/certs.pem"));

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

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

Returns the value of the key parameter.

Example

use rocket::tls::TlsConfig;
use rocket::figment::Figment;

let figment = Figment::new()
    .merge(("certs", vec![0; 32]))
    .merge(("key", "/etc/ssl/key.pem"));

let tls_config: TlsConfig = figment.extract().unwrap();
let key_path = tls_config.key().left().unwrap();
assert_eq!(key_path, Path::new("/etc/ssl/key.pem"));

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

pub fn ciphers(&self) -> impl Iterator<Item = CipherSuite> + '_

Returns an iterator over the enabled cipher suites in their order of preference from most to least preferred.

Example

use rocket::tls::{TlsConfig, CipherSuite};

// The default set is CipherSuite::DEFAULT_SET.
let tls_config = TlsConfig::from_bytes(certs_buf, key_buf);
assert_eq!(tls_config.ciphers().count(), 9);
assert!(tls_config.ciphers().eq(CipherSuite::DEFAULT_SET.iter().copied()));

// Enable only the TLS v1.3 ciphers.
let tls_v13_config = TlsConfig::from_bytes(certs_buf, key_buf)
    .with_ciphers(CipherSuite::TLS_V13_SET);

assert_eq!(tls_v13_config.ciphers().count(), 3);
assert!(tls_v13_config.ciphers().eq(CipherSuite::TLS_V13_SET.iter().copied()));

pub fn prefer_server_cipher_order(&self) -> bool

Whether the server’s cipher suite ordering is preferred or not.

Example

use rocket::tls::TlsConfig;

// The default prefers the server's order.
let tls_config = TlsConfig::from_bytes(certs_buf, key_buf);
assert!(!tls_config.prefer_server_cipher_order());

// Which can be overridden with the eponymous builder method.
let tls_config = TlsConfig::from_bytes(certs_buf, key_buf)
    .with_preferred_server_cipher_order(true);

assert!(tls_config.prefer_server_cipher_order());

pub fn mutual(&self) -> Option<&MtlsConfig>

Available on crate feature mtls only.

Returns the value of the mutual parameter.

Example

use std::path::Path;

use rocket::tls::TlsConfig;
use rocket::mtls::MtlsConfig;

let mtls_config = MtlsConfig::from_path("path/to/cert.pem").mandatory(true);
let tls_config = TlsConfig::from_bytes(certs, key).with_mutual(mtls_config);

let mtls = tls_config.mutual().unwrap();
assert_eq!(mtls.ca_certs().unwrap_left(), Path::new("path/to/cert.pem"));
assert!(mtls.mandatory);

pub async fn server_config(&self) -> Result<ServerConfig>

Try to convert self into a rustls ServerConfig.

pub fn validate(&self) -> Result<()>

NOTE: This is a blocking function.

Trait Implementations

impl Clone for TlsConfig

fn clone(&self) -> TlsConfig

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for TlsConfig

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

Formats the value using the given formatter.

impl Default for TlsConfig

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for TlsConfig

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for TlsConfig

fn eq(&self, other: &TlsConfig) -> 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 TlsConfig

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 TlsConfig