Struct rocket::config::SecretKey

pub struct SecretKey { /* fields omitted */ }

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;

let figment = Config::figment()
    .merge(("secret_key", "hPRYyVRiMyxpw5sBB1XeCMN1kFsDCqKvBi2QJxBVHQk="));

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 a failure 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("failure 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<'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
    'r: 'async_trait,
    'life0: 'async_trait,
    Self: 'async_trait, 

Derives an instance of Self from the incoming request metadata.

impl PartialEq<SecretKey> for SecretKey

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

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

#[must_use]

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

This method tests for !=.