pub struct TlsConfig { /* private fields */ }
tls
only.Expand description
TLS configuration: certificate chain, key, and ciphersuites.
Four parameters control tls
configuration:
-
certs
,key
Both
certs
andkey
can be configured as a path or as raw bytes.certs
must be a DER-encoded X.509 TLS certificate chain, whilekey
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 asRocket.toml
, relative paths are interpreted as relative to the source file’s directory. -
ciphers
A list of supported
CipherSuite
s in server-preferred order, from most to least. It is not required and defaults toCipherSuite::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
impl TlsConfig
sourcepub fn from_bytes(certs: &[u8], key: &[u8]) -> Self
pub fn from_bytes(certs: &[u8], key: &[u8]) -> Self
sourcepub fn with_ciphers<I>(self, ciphers: I) -> Selfwhere
I: IntoIterator<Item = CipherSuite>,
pub fn with_ciphers<I>(self, ciphers: I) -> Selfwhere 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,
]);
sourcepub fn with_preferred_server_cipher_order(
self,
prefer_server_order: bool
) -> Self
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);
sourcepub fn with_mutual(self, config: MutualTls) -> Self
Available on crate feature mtls
only.
pub fn with_mutual(self, config: MutualTls) -> Self
mtls
only.sourcepub fn certs(&self) -> Either<PathBuf, &[u8]> ⓘ
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));
sourcepub fn key(&self) -> Either<PathBuf, &[u8]> ⓘ
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"));
sourcepub fn ciphers(&self) -> impl Iterator<Item = CipherSuite> + '_
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()));
sourcepub fn prefer_server_cipher_order(&self) -> bool
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());
sourcepub fn mutual(&self) -> Option<&MutualTls>
Available on crate feature mtls
only.
pub fn mutual(&self) -> Option<&MutualTls>
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);