1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112

//! Security and privacy headers for all outgoing responses.
//!
//! [`SpaceHelmet`] provides a typed interface for HTTP security headers. It
//! takes some inspiration from [helmetjs], a similar piece of middleware for
//! [express].
//!
//! [fairing]: https://rocket.rs/v0.4/guide/fairings/
//! [helmetjs]: https://helmetjs.github.io/
//! [express]: https://expressjs.com
//! [`SpaceHelmet`]: helmet::SpaceHelmet
//!
//! # Enabling
//!
//! This module is only available when the `helmet` feature is enabled. Enable
//! it in `Cargo.toml` as follows:
//!
//! ```toml
//! [dependencies.rocket_contrib]
//! version = "0.4.10"
//! default-features = false
//! features = ["helmet"]
//! ```
//!
//! # Supported Headers
//!
//! | HTTP Header                 | Description                            | Policy        | Default? |
//! | --------------------------- | -------------------------------------- | ------------- | -------- |
//! | [X-XSS-Protection]          | Prevents some reflected XSS attacks.   | [`XssFilter`] | ✔        |
//! | [X-Content-Type-Options]    | Prevents client sniffing of MIME type. | [`NoSniff`]   | ✔        |
//! | [X-Frame-Options]           | Prevents [clickjacking].               | [`Frame`]     | ✔        |
//! | [Strict-Transport-Security] | Enforces strict use of HTTPS.          | [`Hsts`]      | ?        |
//! | [Expect-CT]                 | Enables certificate transparency.      | [`ExpectCt`]  | ✗        |
//! | [Referrer-Policy]           | Enables referrer policy.               | [`Referrer`]  | ✗        |
//!
//! <small>? If TLS is enabled when the application is launched, in a
//! non-development environment (e.g., staging or production), HSTS is
//! automatically enabled with its default policy and a warning is
//! issued.</small>
//!
//! [X-XSS-Protection]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection
//! [X-Content-Type-Options]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
//! [X-Frame-Options]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
//! [Strict-Transport-Security]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
//! [Expect-CT]:  https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expect-CT
//! [Referrer-Policy]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
//! [clickjacking]: https://en.wikipedia.org/wiki/Clickjacking
//!
//! [`XssFilter`]: self::XssFilter
//! [`NoSniff`]: self::NoSniff
//! [`Frame`]: self::Frame
//! [`Hsts`]: self::Hsts
//! [`ExpectCt`]: self::ExpectCt
//! [`Referrer`]: self::Referrer
//!
//! # Usage
//!
//! To apply default headers, simply attach an instance of [`SpaceHelmet`]
//! before launching:
//!
//! ```rust
//! # extern crate rocket;
//! # extern crate rocket_contrib;
//! use rocket_contrib::helmet::SpaceHelmet;
//!
//! let rocket = rocket::ignite().attach(SpaceHelmet::default());
//! ```
//!
//! Each header can be configured individually. To enable a particular header,
//! call the chainable [`enable()`](helmet::SpaceHelmet::enable()) method
//! on an instance of `SpaceHelmet`, passing in the configured policy type.
//! Similarly, to disable a header, call the chainable
//! [`disable()`](helmet::SpaceHelmet::disable()) method on an instance of
//! `SpaceHelmet`:
//!
//! ```rust
//! # extern crate rocket;
//! # extern crate rocket_contrib;
//! use rocket::http::uri::Uri;
//! use rocket_contrib::helmet::{SpaceHelmet, Frame, XssFilter, Hsts, NoSniff};
//!
//! let site_uri = Uri::parse("https://mysite.example.com").unwrap();
//! let report_uri = Uri::parse("https://report.example.com").unwrap();
//! let helmet = SpaceHelmet::default()
//!     .enable(Hsts::default())
//!     .enable(Frame::AllowFrom(site_uri))
//!     .enable(XssFilter::EnableReport(report_uri))
//!     .disable::<NoSniff>();
//! ```
//!
//! # FAQ
//!
//! * **Which policies should I choose?**
//!
//!   See the links in the table above for individual header documentation. The
//!   [helmetjs] docs are also a good resource, and [OWASP] has a collection of
//!   references on these headers.
//!
//! * **Do I need any headers beyond what `SpaceHelmet` enables by default?**
//!
//!   Maybe! The other headers can protect against many important
//!   vulnerabilities. Please consult their documentation and other resources to
//!   determine if they are needed for your project.
//!
//! [OWASP]: https://www.owasp.org/index.php/OWASP_Secure_Headers_Project#tab=Headers

extern crate time;

mod helmet;
mod policy;

pub use self::helmet::SpaceHelmet;
pub use self::policy::*;