Struct rocket::config::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 or PKCS#1 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 MutualTls 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::config::{Config, TlsConfig, CipherSuite};

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

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

    rocket::custom(config)
}

Or by creating a custom figment:

use rocket::config::Config;

let figment = Config::figment()
    .merge(("tls.certs", "path/to/certs.pem"))
    .merge(("tls.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::config::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::config::TlsConfig;

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

pub fn with_ciphers<I>(self, ciphers: I) -> Self where
    I: 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::config::{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::config::{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::config::{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::config::{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: MutualTls) -> Self

Available on crate feature mtls only.

Configures mutual TLS. See MutualTls for details.

Example

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

let mtls_config = MutualTls::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::Config;

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

let config = rocket::Config::from(figment);
let tls_config = config.tls.as_ref().unwrap();
let cert_bytes = tls_config.certs().right().unwrap();
assert!(cert_bytes.iter().all(|&b| b == 0));

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

Returns the value of the key parameter.

Example

use std::path::Path;
use rocket::Config;

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

let config = rocket::Config::from(figment);
let tls_config = config.tls.as_ref().unwrap();
let key_path = tls_config.key().left().unwrap();
assert_eq!(key_path, Path::new("/etc/ssl/key.pem"));

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::config::{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::config::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 overriden 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<&MutualTls>

Available on crate feature mtls only.

Returns the value of the mutual parameter.

Example

use std::path::Path;
use rocket::config::{TlsConfig, MutualTls};

let mtls_config = MutualTls::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);

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<'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<TlsConfig> for TlsConfig

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

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

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

This method tests for !=.

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