Struct SecretKey

pub struct SecretKey { /* private fields */ }

A cryptographically secure secret key.

A SecretKey is primarily used by private cookies. See the configuration guide for further details. It can be configured from 256-bit random material or a 512-bit master key, each as either a base64-encoded string or raw bytes.

use rocket::config::Config;

// NOTE: Don't (!) use this key! Generate your own and keep it private!
//       e.g. via `head -c64 /dev/urandom | base64`
let figment = Config::figment()
    .merge(("secret_key", "hPrYyЭRiMyµ5sBB1π+CMæ1køFsåqKvBiQJxBVHQk="));

let config = Config::from(figment);
assert!(!config.secret_key.is_zero());

When configured in the debug profile with the secrets feature enabled, a key set as 0 is automatically regenerated at launch time from the OS’s random source if available.

use rocket::config::Config;
use rocket::local::blocking::Client;

let figment = Config::figment()
    .merge(("secret_key", vec![0u8; 64]))
    .select("debug");

let rocket = rocket::custom(figment);
let client = Client::tracked(rocket).expect("okay in debug");
assert!(!client.rocket().config().secret_key.is_zero());

When running in any other profile with the secrets feature enabled, providing a key of 0 or not provided a key at all results in an error at launch-time:

use rocket::config::Config;
use rocket::figment::Profile;
use rocket::local::blocking::Client;
use rocket::error::ErrorKind;

let profile = Profile::const_new("staging");
let figment = Config::figment()
    .merge(("secret_key", vec![0u8; 64]))
    .select(profile.clone());

let rocket = rocket::custom(figment);
let error = Client::tracked(rocket).expect_err("error in non-debug");
assert!(matches!(error.kind(), ErrorKind::InsecureSecretKey(profile)));

Implementations

impl SecretKey

pub fn from(master: &[u8]) -> SecretKey

Creates a SecretKey from a 512-bit master key. For security, master must be cryptographically random.

Panics

Panics if master < 64 bytes.

Example

use rocket::config::SecretKey;

let key = SecretKey::from(&master);

pub fn derive_from(material: &[u8]) -> SecretKey

Derives a SecretKey from 256 bits of cryptographically random material. For security, material must be cryptographically random.

Panics

Panics if material < 32 bytes.

Example

use rocket::config::SecretKey;

let key = SecretKey::derive_from(&material);

pub fn generate() -> Option<SecretKey>

Attempts to generate a SecretKey from randomness retrieved from the OS. If randomness from the OS isn’t available, returns None.

Example

use rocket::config::SecretKey;

let key = SecretKey::generate();

pub fn is_zero(&self) -> bool

Returns true if self is the 0-key.

Example

use rocket::config::SecretKey;

let master = vec![0u8; 64];
let key = SecretKey::from(&master);
assert!(key.is_zero());

pub fn is_provided(&self) -> bool

Returns true if self was not automatically generated and is not zero.

Example

use rocket::config::SecretKey;

let master = vec![0u8; 64];
let key = SecretKey::generate().unwrap();
assert!(!key.is_provided());

let master = vec![0u8; 64];
let key = SecretKey::from(&master);
assert!(!key.is_provided());

Trait Implementations

impl Clone for SecretKey

fn clone(&self) -> SecretKey

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for SecretKey

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SecretKey

fn deserialize<D: Deserializer<'de>>(de: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for SecretKey

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

Formats the value using the given formatter.

impl<'r> FromRequest<'r> for &'r SecretKey

type Error = Infallible

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( req: &'r Request<'life0>, ) -> Pin<Box<dyn Future<Output = Outcome<Self, Self::Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.

impl PartialEq for SecretKey

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