Struct rocket::config::TlsConfig

source ·
pub struct TlsConfig { /* private fields */ }
Expand description

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 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§

source§

impl TlsConfig

source

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

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

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,
]);
source

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

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

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

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

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

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

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§

source§

impl Clone for TlsConfig

source§

fn clone(&self) -> TlsConfig

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for TlsConfig

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
source§

impl PartialEq for TlsConfig

source§

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

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

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.
source§

impl Serialize for TlsConfig

source§

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

Serialize this value into the given Serde serializer. Read more
source§

impl StructuralPartialEq for TlsConfig

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<'a, T> AsTaggedExplicit<'a> for T
where T: 'a,

source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self>

source§

impl<'a, T> AsTaggedImplicit<'a> for T
where T: 'a,

source§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoCollection<T> for T

§

fn into_collection<A>(self) -> SmallVec<A>
where A: Array<Item = T>,

Converts self into a collection.
§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>
where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Paint for T
where T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

§Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

§Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

§Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

§Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

§Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

§Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

§Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

§Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

§Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

§Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

§Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

§Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

§Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

§Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

§Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

§Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

§Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

§Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

§Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

§Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

§Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

§Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

§Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

§Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

§Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

§Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

§Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

§Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

§Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

§Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

§Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

§Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

§Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

§Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

§Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

§Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

§Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

§Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

§Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

§Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

§Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

§Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

§Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

§Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

§Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

§Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

§Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

§Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

§Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

§Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear(). The clear() method will be removed in a future release.

Returns self with the quirk() set to Quirk::Clear.

§Example
println!("{}", value.clear());
source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Resetting.

§Example
println!("{}", value.resetting());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

§Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

§Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,