rocket/shield/mod.rs
1//! Security and privacy headers for all outgoing responses.
2//!
3//! The [`Shield`] fairing provides a typed interface for injecting HTTP
4//! security and privacy headers into all outgoing responses. It takes some
5//! inspiration from [helmetjs], a similar piece of middleware for [express].
6//!
7//! [fairing]: https://rocket.rs/v0.5/guide/fairings/
8//! [helmetjs]: https://helmetjs.github.io/
9//! [express]: https://expressjs.com
10//!
11//! # Supported Headers
12//!
13//! | HTTP Header | Description | Policy | Default? |
14//! | --------------------------- | -------------------------------------- | -------------- | -------- |
15//! | [X-XSS-Protection] | Prevents some reflected XSS attacks. | [`XssFilter`] | ✗ |
16//! | [X-Content-Type-Options] | Prevents client sniffing of MIME type. | [`NoSniff`] | ✔ |
17//! | [X-Frame-Options] | Prevents [clickjacking]. | [`Frame`] | ✔ |
18//! | [Strict-Transport-Security] | Enforces strict use of HTTPS. | [`Hsts`] | ? |
19//! | [Expect-CT] | Enables certificate transparency. | [`ExpectCt`] | ✗ |
20//! | [Referrer-Policy] | Enables referrer policy. | [`Referrer`] | ✗ |
21//! | [X-DNS-Prefetch-Control] | Controls browser DNS prefetching. | [`Prefetch`] | ✗ |
22//! | [Permissions-Policy] | Allows or block browser features. | [`Permission`] | ✔ |
23//!
24//! <small>? If TLS is enabled in a non-debug profile, HSTS is automatically
25//! enabled with its default policy and a warning is logged at liftoff.</small>
26//!
27//! [X-XSS-Protection]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection
28//! [X-Content-Type-Options]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
29//! [X-Frame-Options]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
30//! [Strict-Transport-Security]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
31//! [Expect-CT]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expect-CT
32//! [Referrer-Policy]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
33//! [X-DNS-Prefetch-Control]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-DNS-Prefetch-Control
34//! [clickjacking]: https://en.wikipedia.org/wiki/Clickjacking
35//! [Permissions-Policy]: https://github.com/w3c/webappsec-permissions-policy/blob/a45df7b237e2a85e1909d7f226ca4eb4ce5095ba/permissions-policy-explainer.md
36//!
37//! [`XssFilter`]: self::XssFilter
38//! [`NoSniff`]: self::NoSniff
39//! [`Frame`]: self::Frame
40//! [`Hsts`]: self::Hsts
41//! [`ExpectCt`]: self::ExpectCt
42//! [`Referrer`]: self::Referrer
43//! [`Prefetch`]: self::Prefetch
44//!
45//! # Usage
46//!
47//! By default, [`Shield::default()`] is attached to all instances Rocket. To
48//! change the default, including removing all `Shield` headers, attach a
49//! configured instance of [`Shield`]:
50//!
51//! ```rust
52//! # #[macro_use] extern crate rocket;
53//! use rocket::shield::Shield;
54//!
55//! #[launch]
56//! fn rocket() -> _ {
57//! // Remove all `Shield` headers.
58//! rocket::build().attach(Shield::new())
59//! }
60//! ```
61//!
62//! Each header can be configured individually. To enable a particular header,
63//! call the chainable [`enable()`](shield::Shield::enable()) method
64//! on an instance of `Shield`, passing in the configured policy type.
65//! Similarly, to disable a header, call the chainable
66//! [`disable()`](shield::Shield::disable()) method on an instance of
67//! `Shield`:
68//!
69//! ```rust
70//! # #[macro_use] extern crate rocket;
71//! use time::Duration;
72//!
73//! use rocket::http::uri::Uri;
74//! use rocket::shield::{Shield, Referrer, Prefetch, ExpectCt, NoSniff};
75//!
76//! let report_uri = uri!("https://report.rocket.rs");
77//! let shield = Shield::default()
78//! .enable(Referrer::NoReferrer)
79//! .enable(Prefetch::Off)
80//! .enable(ExpectCt::ReportAndEnforce(Duration::days(30), report_uri))
81//! .disable::<NoSniff>();
82//! ```
83//!
84//! # FAQ
85//!
86//! * **Which policies should I choose?**
87//!
88//! See the links in the table above for individual header documentation. The
89//! [helmetjs] docs are also a good resource, and [OWASP] has a collection of
90//! references on these headers.
91//!
92//! * **Do I need any headers beyond what `Shield` enables by default?**
93//!
94//! Maybe! The other headers may protect against many important
95//! vulnerabilities. Please consult their documentation and other resources to
96//! determine if they are needed for your project.
97//!
98//! [OWASP]: https://www.owasp.org/index.php/OWASP_Secure_Headers_Project#tab=Headers
99
100mod shield;
101mod policy;
102
103pub use self::shield::Shield;
104pub use self::policy::*;