Struct Permission

pub struct Permission(/* private fields */);

The Permissions-Policy header: allow or block the use of browser features.

Tells the browser to allow or block the use of a browser feature in the top-level page as well as allow or block requesting access to (via the allow iframe attribute) features in embedded iframes.

By default, the top-level page may access ~all features and any embedded iframes may request access to ~any feature. This header allows the server to control exactly which (if any) origins may access or request access to browser features.

Features are enabled via the Permission::allowed() constructor and chainable allow() build method. Features can be blocked via the Permission::blocked() and chainable block() builder method.

use rocket::shield::{Shield, Permission, Feature, Allow};

// In addition to defaults, block access to geolocation and USB features.
// Enable camera and microphone features only for the serving origin. Enable
// payment request access for the current origin and `https://rocket.rs`.
let permission = Permission::default()
    .block(Feature::Geolocation)
    .block(Feature::Usb)
    .allow(Feature::Camera, Allow::This)
    .allow(Feature::Microphone, Allow::This)
    .allow(Feature::Payment, [Allow::This, Allow::Origin(uri!("https://rocket.rs"))]);

rocket::build().attach(Shield::default().enable(permission));

Default

The default returned via Permission::default() blocks access to the interest-cohort feature, otherwise known as FLoC, which disables using the current site in ad targeting tracking computations.

Implementations

impl Permission

pub fn allowed<L>(feature: Feature, allow: L) -> Self

where L: IntoCollection<Allow>,

Constructs a new Permission policy with only feature allowed for the set of origins in allow which may be a single Allow, a slice ([Allow] or &[Allow]), or a vector (Vec<Allow>).

If allow is empty, the use of the feature is blocked unless another call to allow() allows it. If allow contains Allow::Any, the feature is allowable for all origins. Otherwise, the feature is allowable only for the origin specified in allow.

Panics

Panics if an Absolute URI in an Allow::Origin does not contain a host part.

Example

use rocket::shield::{Permission, Feature, Allow};

let rocket = Allow::Origin(uri!("https://rocket.rs"));

let perm = Permission::allowed(Feature::Usb, Allow::This);
let perm = Permission::allowed(Feature::Usb, Allow::Any);
let perm = Permission::allowed(Feature::Usb, [Allow::This, rocket]);

pub fn blocked(feature: Feature) -> Self

Constructs a new Permission policy with only feature blocked.

Example

use rocket::shield::{Permission, Feature};

let perm = Permission::blocked(Feature::Usb);
let perm = Permission::blocked(Feature::Payment);

pub fn allow<L>(self, feature: Feature, allow: L) -> Self

where L: IntoCollection<Allow>,

Adds feature as allowable for the set of origins in allow which may be a single Allow, a slice ([Allow] or &[Allow]), or a vector (Vec<Allow>).

This policy supersedes any previous policy set for feature.

If allow is empty, the use of the feature is blocked unless another call to allow() allows it. If allow contains Allow::Any, the feature is allowable for all origins. Otherwise, the feature is allowable only for the origin specified in allow.

Panics

Panics if an Absolute URI in an Allow::Origin does not contain a host part.

Example

use rocket::shield::{Permission, Feature, Allow};

let rocket = Allow::Origin(uri!("https://rocket.rs"));
let perm = Permission::allowed(Feature::Usb, Allow::This)
    .allow(Feature::Payment, [rocket, Allow::This]);

pub fn block(self, feature: Feature) -> Self

Blocks feature. This policy supersedes any previous policy set for feature.

Example

use rocket::shield::{Permission, Feature};

let perm = Permission::default()
    .block(Feature::Usb)
    .block(Feature::Payment);

pub fn get(&self, feature: Feature) -> Option<&[Allow]>

Returns the allow list (so far) for feature if feature is allowed.

Example

use rocket::shield::{Permission, Feature, Allow};

let perm = Permission::default();
assert!(perm.get(Feature::Usb).is_none());

let perm = perm.allow(Feature::Usb, Allow::Any);
assert_eq!(perm.get(Feature::Usb).unwrap(), &[Allow::Any]);

pub fn iter(&self) -> impl Iterator<Item = (Feature, Option<&[Allow]>)>

Returns an iterator over the pairs of features and their allow lists, None if the feature is blocked.

Features are returned in the order in which they were first added.

Example

use rocket::shield::{Permission, Feature, Allow};

let foo = uri!("https://foo.com:1234");
let perm = Permission::blocked(Feature::Camera)
    .allow(Feature::Gyroscope, [Allow::This, Allow::Origin(foo.clone())])
    .block(Feature::Payment)
    .allow(Feature::Camera, Allow::Any);

let perms: Vec<_> = perm.iter().collect();
assert_eq!(perms.len(), 3);
assert_eq!(perms, vec![
    (Feature::Camera, Some(&[Allow::Any][..])),
    (Feature::Gyroscope, Some(&[Allow::This, Allow::Origin(foo)][..])),
    (Feature::Payment, None),
]);

Trait Implementations

impl Clone for Permission

fn clone(&self) -> Permission

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for Permission

fn default() -> Self

The default Permission policy blocks access to the interest-cohort feature, otherwise known as FLoC, which disables using the current site in ad targeting tracking computations.

impl From<&Permission> for Header<'static>

fn from(perm: &Permission) -> Self

Converts to this type from the input type.

impl PartialEq for Permission

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

impl Policy for Permission

const NAME: &'static str = "Permissions-Policy"

The actual name of the HTTP header.

fn header(&self) -> Header<'static>

Returns the Header to attach to all outgoing responses.

impl StructuralPartialEq for Permission