logo
pub struct Permission(_);
Expand description

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() contructor 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

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]);

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);

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 supercedes 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]);

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

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

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

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]);

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

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.

Converts to this type from the input type.

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

This method tests for !=.

The actual name of the HTTP header. Read more

Returns the Header to attach to all outgoing responses. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Converts self into a collection.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more