Struct Shield

pub struct Shield { /* private fields */ }

A Fairing that injects browser security and privacy headers into all outgoing responses.

Usage

To use Shield, first construct an instance of it. To use the default set of headers, construct with Shield::default(). For an instance with no preset headers, use Shield::new(). To enable an additional header, use enable(), and to disable a header, use disable():

use rocket::shield::Shield;
use rocket::shield::{XssFilter, ExpectCt};

// A `Shield` with the default headers:
let shield = Shield::default();

// A `Shield` with the default headers minus `XssFilter`:
let shield = Shield::default().disable::<XssFilter>();

// A `Shield` with the default headers plus `ExpectCt`.
let shield = Shield::default().enable(ExpectCt::default());

// A `Shield` with only `XssFilter` and `ExpectCt`.
let shield = Shield::default()
    .enable(XssFilter::default())
    .enable(ExpectCt::default());

Then, attach the instance of Shield to your application’s instance of Rocket:

rocket::build()
    // ...
    .attach(shield)

The fairing will inject all enabled headers into all outgoing responses unless the response already contains a header with the same name. If it does contain the header, a warning is emitted, and the header is not overwritten.

TLS and HSTS

If TLS is configured and enabled when the application is launched in a non-debug profile, HSTS is automatically enabled with its default policy and a warning is logged. To get rid of this warning, explicitly Shield::enable() an Hsts policy.

Implementations

impl Shield

pub fn new() -> Self

Returns an instance of Shield with no headers enabled.

Example

use rocket::shield::Shield;

let shield = Shield::new();

pub fn enable<P: Policy>(self, policy: P) -> Self

Enables the policy header policy.

If the policy was previously enabled, the configuration is replaced with that of policy.

Example

use rocket::shield::Shield;
use rocket::shield::NoSniff;

let shield = Shield::new().enable(NoSniff::default());

pub fn disable<P: Policy>(self) -> Self

Disables the policy header policy.

Example

use rocket::shield::Shield;
use rocket::shield::NoSniff;

let shield = Shield::default().disable::<NoSniff>();

pub fn is_enabled<P: Policy>(&self) -> bool

Returns true if the policy P is enabled.

Example

use rocket::shield::Shield;
use rocket::shield::{Permission, NoSniff, Frame};
use rocket::shield::{Prefetch, ExpectCt, Referrer};

let shield = Shield::default();

assert!(shield.is_enabled::<NoSniff>());
assert!(shield.is_enabled::<Frame>());
assert!(shield.is_enabled::<Permission>());

assert!(!shield.is_enabled::<Prefetch>());
assert!(!shield.is_enabled::<ExpectCt>());
assert!(!shield.is_enabled::<Referrer>());

Trait Implementations

impl Clone for Shield

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Shield

fn default() -> Self

Returns a new Shield instance. See the table for a description of the policies used by default.

Example

use rocket::shield::Shield;

let shield = Shield::default();

impl Fairing for Shield

fn info(&self) -> Info

Returns an Info structure containing the name and Kind of this fairing. The name can be any arbitrary string. Kind must be an ord set of Kind variants.

fn on_liftoff<'life0, 'life1, 'async_trait>( &'life0 self, rocket: &'life1 Rocket<Orbit>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The liftoff callback.

fn on_response<'r, 'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _: &'r Request<'life1>, response: &'life2 mut Response<'r>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

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

The response callback.

fn on_ignite<'life0, 'async_trait>( &'life0 self, rocket: Rocket<Build>, ) -> Pin<Box<dyn Future<Output = Result> + Send + 'async_trait>>

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

The ignite callback. Returns Ok if ignition should proceed and Err if ignition and launch should be aborted.

fn on_request<'life0, 'life1, 'life2, 'life3, 'life4, 'async_trait>( &'life0 self, _req: &'life1 mut Request<'life2>, _data: &'life3 mut Data<'life4>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait, 'life4: 'async_trait,

The request callback.

fn on_shutdown<'life0, 'life1, 'async_trait>( &'life0 self, _rocket: &'life1 Rocket<Orbit>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

The shutdown callback.