RFC 6797
HTTP Strict Transport Security (HSTS)
6. Syntax
This section defines the syntax of the Strict-Transport-Security HTTP response header field and its directives, and presents some examples. Section 7 ("Server Processing Model") then details how hosts employ this header field to declare their HSTS Policy, and Section 8 ("User Agent Processing Model") details how user agents process the header field and apply the HSTS Policy.
6.1. Strict-Transport-Security HTTP Response Header Field
The Strict-Transport-Security HTTP response header field (STS header field) indicates to a UA that it MUST enforce the HSTS Policy in regards to the host emitting the response message containing this header field. The ABNF (Augmented Backus-Naur Form) syntax for the STS header field is given below. It is based on the Generic Grammar defined in Section 2 of [RFC2616] (which includes a notion of "implied linear whitespace", also known as "implied *LWS"). Strict-Transport-Security = "Strict-Transport-Security" ":" [ directive ] *( ";" [ directive ] ) directive = directive-name [ "=" directive-value ] directive-name = token directive-value = token | quoted-string where: token = <token, defined in [RFC2616], Section 2.2> quoted-string = <quoted-string, defined in [RFC2616], Section 2.2> The two directives defined in this specification are described below. The overall requirements for directives are: 1. The order of appearance of directives is not significant. 2. All directives MUST appear only once in an STS header field. Directives are either optional or required, as stipulated in their definitions. 3. Directive names are case-insensitive. 4. UAs MUST ignore any STS header field containing directives, or other header field value data, that does not conform to the syntax defined in this specification. 5. If an STS header field contains directive(s) not recognized by the UA, the UA MUST ignore the unrecognized directives, and if the STS header field otherwise satisfies the above requirements (1 through 4), the UA MUST process the recognized directives. Additional directives extending the semantic functionality of the STS header field can be defined in other specifications, with a registry (having an IANA policy definition of IETF Review [RFC5226]) defined for them at such time.
NOTE: Such future directives will be ignored by UAs implementing
only this specification, as well as by generally
non-conforming UAs. See Section 14.2 ("Non-Conformant User
Agent Implications") for further discussion.
6.1.1. The max-age Directive
The REQUIRED "max-age" directive specifies the number of seconds,
after the reception of the STS header field, during which the UA
regards the host (from whom the message was received) as a Known HSTS
Host. See also Section 8.1.1 ("Noting an HSTS Host - Storage
Model"). The delta-seconds production is specified in [RFC2616].
The syntax of the max-age directive's REQUIRED value (after
quoted-string unescaping, if necessary) is defined as:
max-age-value = delta-seconds
delta-seconds = <1*DIGIT, defined in [RFC2616], Section 3.3.2>
NOTE: A max-age value of zero (i.e., "max-age=0") signals the UA to
cease regarding the host as a Known HSTS Host, including the
includeSubDomains directive (if asserted for that HSTS Host).
See also Section 8.1 ("Strict-Transport-Security Response
Header Field Processing").
6.1.2. The includeSubDomains Directive
The OPTIONAL "includeSubDomains" directive is a valueless directive
which, if present (i.e., it is "asserted"), signals the UA that the
HSTS Policy applies to this HSTS Host as well as any subdomains of
the host's domain name.
6.2. Examples
The HSTS header field below stipulates that the HSTS Policy is to
remain in effect for one year (there are approximately 31536000
seconds in a year), and the policy applies only to the domain of the
HSTS Host issuing it:
Strict-Transport-Security: max-age=31536000
The HSTS header field below stipulates that the HSTS Policy is to
remain in effect for approximately six months and that the policy
applies to the domain of the issuing HSTS Host and all of its
subdomains:
Strict-Transport-Security: max-age=15768000 ; includeSubDomains
The max-age directive value can optionally be quoted:
Strict-Transport-Security: max-age="31536000"
The HSTS header field below indicates that the UA must delete the
entire HSTS Policy associated with the HSTS Host that sent the header
field:
Strict-Transport-Security: max-age=0
The HSTS header field below has exactly the same effect as the one
immediately above because the includeSubDomains directive's presence
in the HSTS header field is ignored when max-age is zero:
Strict-Transport-Security: max-age=0; includeSubDomains
7. Server Processing Model
This section describes the processing model that HSTS Hosts
implement. The model comprises two facets: the first being the
processing rules for HTTP request messages received over a secure
transport (TLS [RFC5246] or SSL [RFC6101]; see also Section 14.1
("Underlying Secure Transport Considerations")), and the second being
the processing rules for HTTP request messages received over
non-secure transports, such as TCP.
7.1. HTTP-over-Secure-Transport Request Type
When replying to an HTTP request that was conveyed over a secure
transport, an HSTS Host SHOULD include in its response message an STS
header field that MUST satisfy the grammar specified above in
Section 6.1 ("Strict-Transport-Security HTTP Response Header Field").
If an STS header field is included, the HSTS Host MUST include only
one such header field.
Establishing a given host as a Known HSTS Host, in the context of a
given UA, MAY be accomplished over HTTP, which is in turn running
over secure transport, by correctly returning (per this
specification) at least one valid STS header field to the UA. Other
mechanisms, such as a client-side pre-loaded Known HSTS Host list,
MAY also be used; e.g., see Section 12 ("User Agent Implementation
Advice").
NOTE: Including the STS header field is stipulated as a "SHOULD" in
order to accommodate various server- and network-side caches
and load-balancing configurations where it may be difficult to
uniformly emit STS header fields on behalf of a given HSTS
Host.
7.2. HTTP Request Type
If an HSTS Host receives an HTTP request message over a non-secure transport, it SHOULD send an HTTP response message containing a status code indicating a permanent redirect, such as status code 301 (Section 10.3.2 of [RFC2616]), and a Location header field value containing either the HTTP request's original Effective Request URI (see Section 9 ("Constructing an Effective Request URI")) altered as necessary to have a URI scheme of "https", or a URI generated according to local policy with a URI scheme of "https". NOTE: The above behavior is a "SHOULD" rather than a "MUST" due to: * Risks in server-side non-secure-to-secure redirects [OWASP-TLSGuide]. * Site deployment characteristics. For example, a site that incorporates third-party components may not behave correctly when doing server-side non-secure-to-secure redirects in the case of being accessed over non-secure transport but does behave correctly when accessed uniformly over secure transport. The latter is the case given an HSTS-capable UA that has already noted the site as a Known HSTS Host (by whatever means, e.g., prior interaction or UA configuration). An HSTS Host MUST NOT include the STS header field in HTTP responses conveyed over non-secure transport.8. User Agent Processing Model
This section describes the HTTP Strict Transport Security processing model for UAs. There are several facets to the model, enumerated by the following subsections. This processing model assumes that the UA implements IDNA2008 [RFC5890], or possibly IDNA2003 [RFC3490], as noted in Section 13 ("Internationalized Domain Names for Applications (IDNA): Dependency and Migration"). It also assumes that all domain names manipulated in this specification's context are already IDNA-canonicalized as outlined in Section 10 ("Domain Name IDNA-Canonicalization") prior to the processing specified in this section. NOTE: [RFC3490] is referenced due to its ongoing relevance to actual deployments for the foreseeable future. The above assumptions mean that this processing model also specifically assumes that appropriate IDNA and Unicode validations and character list testing have occurred on the domain names, in
conjunction with their IDNA-canonicalization, prior to the processing specified in this section. See the IDNA-specific security considerations in Section 14.10 ("Internationalized Domain Names") for rationale and further details.8.1. Strict-Transport-Security Response Header Field Processing
If an HTTP response, received over a secure transport, includes an STS header field, conforming to the grammar specified in Section 6.1 ("Strict-Transport-Security HTTP Response Header Field"), and there are no underlying secure transport errors or warnings (see Section 8.4), the UA MUST either: o Note the host as a Known HSTS Host if it is not already so noted (see Section 8.1.1 ("Noting an HSTS Host - Storage Model")), or o Update the UA's cached information for the Known HSTS Host if either or both of the max-age and includeSubDomains header field value tokens are conveying information different than that already maintained by the UA. The max-age value is essentially a "time to live" value relative to the reception time of the STS header field. If the max-age header field value token has a value of zero, the UA MUST remove its cached HSTS Policy information (including the includeSubDomains directive, if asserted) if the HSTS Host is known, or the UA MUST NOT note this HSTS Host if it is not yet known. If a UA receives more than one STS header field in an HTTP response message over secure transport, then the UA MUST process only the first such header field. Otherwise: o If an HTTP response is received over insecure transport, the UA MUST ignore any present STS header field(s). o The UA MUST ignore any STS header fields not conforming to the grammar specified in Section 6.1 ("Strict-Transport-Security HTTP Response Header Field").
8.1.1. Noting an HSTS Host - Storage Model
If the substring matching the host production from the Request-URI (of the message to which the host responded) syntactically matches the IP-literal or IPv4address productions from Section 3.2.2 of [RFC3986], then the UA MUST NOT note this host as a Known HSTS Host. Otherwise, if the substring does not congruently match a Known HSTS Host's domain name, per the matching procedure specified in Section 8.2 ("Known HSTS Host Domain Name Matching"), then the UA MUST note this host as a Known HSTS Host, caching the HSTS Host's domain name and noting along with it the expiry time of this information, as effectively stipulated per the given max-age value, as well as whether the includeSubDomains directive is asserted or not. See also Section 11.2 ("HSTS Policy Expiration Time Considerations"). The UA MUST NOT modify the expiry time or the includeSubDomains directive of any superdomain matched Known HSTS Host. A Known HSTS Host is "expired" if its cache entry has an expiry date in the past. The UA MUST evict all expired Known HSTS Hosts from its cache if, at any time, an expired Known HSTS Host exists in the cache.8.2. Known HSTS Host Domain Name Matching
A given domain name may match a Known HSTS Host's domain name in one or both of two fashions: a congruent match, or a superdomain match. Alternatively, there may be no match. The steps below determine whether there are any matches, and if so, of which fashion: Compare the given domain name with the domain name of each of the UA's unexpired Known HSTS Hosts. For each Known HSTS Host's domain name, the comparison is done with the given domain name label-by-label (comparing only labels) using an ASCII case- insensitive comparison beginning with the rightmost label, and continuing right-to-left. See also Section 2.3.2.4 of [RFC5890]. * Superdomain Match If a label-for-label match between an entire Known HSTS Host's domain name and a right-hand portion of the given domain name is found, then this Known HSTS Host's domain name is a superdomain match for the given domain name. There could be multiple superdomain matches for a given domain name.
For example:
Given domain name (DN): qaz.bar.foo.example.com
Superdomain matched
Known HSTS Host DN: bar.foo.example.com
Superdomain matched
Known HSTS Host DN: foo.example.com
* Congruent Match
If a label-for-label match between a Known HSTS Host's domain
name and the given domain name is found -- i.e., there are no
further labels to compare -- then the given domain name
congruently matches this Known HSTS Host.
For example:
Given domain name: foo.example.com
Congruently matched
Known HSTS Host DN: foo.example.com
* Otherwise, if no matches are found, the given domain name does
not represent a Known HSTS Host.
8.3. URI Loading and Port Mapping
Whenever the UA prepares to "load" (also known as "dereference") any
"http" URI [RFC3986] (including when following HTTP redirects
[RFC2616]), the UA MUST first determine whether a domain name is
given in the URI and whether it matches a Known HSTS Host, using
these steps:
1. Extract from the URI any substring described by the host
component of the authority component of the URI.
2. If the substring is null, then there is no match with any Known
HSTS Host.
3. Else, if the substring is non-null and syntactically matches the
IP-literal or IPv4address productions from Section 3.2.2 of
[RFC3986], then there is no match with any Known HSTS Host.
4. Otherwise, the substring is a given domain name, which MUST be
matched against the UA's Known HSTS Hosts using the procedure in
Section 8.2 ("Known HSTS Host Domain Name Matching").
5. If, when performing domain name matching any superdomain match
with an asserted includeSubDomains directive is found, or, if no
superdomain matches with asserted includeSubDomains directives
are found and a congruent match is found (with or without an
asserted includeSubDomains directive), then before proceeding
with the load:
The UA MUST replace the URI scheme with "https" [RFC2818], and
if the URI contains an explicit port component of "80", then
the UA MUST convert the port component to be "443", or
if the URI contains an explicit port component that is not
equal to "80", the port component value MUST be preserved;
otherwise,
if the URI does not contain an explicit port component, the UA
MUST NOT add one.
NOTE: These steps ensure that the HSTS Policy applies to HTTP
over any TCP port of an HSTS Host.
NOTE: In the case where an explicit port is provided (and to a
lesser extent with subdomains), it is reasonably likely that
there is actually an HTTP (i.e., non-secure) server running on
the specified port and that an HTTPS request will thus fail
(see item 6 in Appendix A ("Design Decision Notes")).
8.4. Errors in Secure Transport Establishment
When connecting to a Known HSTS Host, the UA MUST terminate the
connection (see also Section 12 ("User Agent Implementation Advice"))
if there are any errors, whether "warning" or "fatal" or any other
error level, with the underlying secure transport. For example, this
includes any errors found in certificate validity checking that UAs
employ, such as via Certificate Revocation Lists (CRLs) [RFC5280], or
via the Online Certificate Status Protocol (OCSP) [RFC2560], as well
as via TLS server identity checking [RFC6125].
8.5. HTTP-Equiv <Meta> Element Attribute
UAs MUST NOT heed http-equiv="Strict-Transport-Security" attribute
settings on <meta> elements [W3C.REC-html401-19991224] in received
content.
8.6. Missing Strict-Transport-Security Response Header Field
If a UA receives HTTP responses from a Known HSTS Host over a secure channel but the responses are missing the STS header field, the UA MUST continue to treat the host as a Known HSTS Host until the max-age value for the knowledge of that Known HSTS Host is reached. Note that the max-age value could be effectively infinite for a given Known HSTS Host. For example, this would be the case if the Known HSTS Host is part of a pre-configured list that is implemented such that the list entries never "age out".9. Constructing an Effective Request URI
This section specifies how an HSTS Host must construct the Effective Request URI for a received HTTP request. HTTP requests often do not carry an absoluteURI for the target resource; instead, the URI needs to be inferred from the Request-URI, Host header field, and connection context ([RFC2616], Sections 3.2.1, 5.1.2, and 5.2). The result of this process is called the "effective request URI (ERU)". The "target resource" is the resource identified by the effective request URI.9.1. ERU Fundamental Definitions
The first line of an HTTP request message, Request-Line, is specified by the following ABNF from [RFC2616], Section 5.1: Request-Line = Method SP Request-URI SP HTTP-Version CRLF The Request-URI, within the Request-Line, is specified by the following ABNF from [RFC2616], Section 5.1.2: Request-URI = "*" | absoluteURI | abs_path | authority The Host request header field is specified by the following ABNF from [RFC2616], Section 14.23: Host = "Host" ":" host [ ":" port ]
9.2. Determining the Effective Request URI
If the Request-URI is an absoluteURI, then the effective request URI is the Request-URI. If the Request-URI uses the abs_path form or the asterisk form, and the Host header field is present, then the effective request URI is constructed by concatenating: o the scheme name: "http" if the request was received over an insecure TCP connection, or "https" when received over a TLS/ SSL-secured TCP connection, and o the octet sequence "://", and o the host, and the port (if present), from the Host header field, and o the Request-URI obtained from the Request-Line, unless the Request-URI is just the asterisk "*". If the Request-URI uses the abs_path form or the asterisk form, and the Host header field is not present, then the effective request URI is undefined. Otherwise, when Request-URI uses the authority form, the effective request URI is undefined. Effective request URIs are compared using the rules described in [RFC2616] Section 3.2.3, except that empty path components MUST NOT be treated as equivalent to an absolute path of "/".9.2.1. Effective Request URI Examples
Example 1: the effective request URI for the message GET /pub/WWW/TheProject.html HTTP/1.1 Host: www.example.org:8080 (received over an insecure TCP connection) is "http", plus "://", plus the authority component "www.example.org:8080", plus the request-target "/pub/WWW/TheProject.html". Thus, it is "http://www.example.org:8080/pub/WWW/TheProject.html".
Example 2: the effective request URI for the message
OPTIONS * HTTP/1.1
Host: www.example.org
(received over an SSL/TLS secured TCP connection) is "https", plus
"://", plus the authority component "www.example.org". Thus, it is
"https://www.example.org".
10. Domain Name IDNA-Canonicalization
An IDNA-canonicalized domain name is the output string generated by
the following steps. The input is a putative domain name string
ostensibly composed of any combination of "A-labels", "U-labels", and
"NR-LDH labels" (see Section 2 of [RFC5890]) concatenated using some
separator character (typically ".").
1. Convert the input putative domain name string to an order-
preserving sequence of individual label strings.
2. When implementing IDNA2008, convert, validate, and test each
A-label and U-label found among the sequence of individual label
strings, using the procedures defined in Sections 5.3 through 5.5
of [RFC5891].
Otherwise, when implementing IDNA2003, convert each label using
the "ToASCII" conversion in Section 4 of [RFC3490] (see also the
definition of "equivalence of labels" in Section 2 of [RFC3490]).
3. If no errors occurred during the foregoing step, concatenate all
the labels in the sequence, in order, into a string, separating
each label from the next with a %x2E (".") character. The
resulting string, known as an IDNA-canonicalized domain name, is
appropriate for use in the context of Section 8 ("User Agent
Processing Model").
Otherwise, errors occurred. The input putative domain name
string was not successfully IDNA-canonicalized. Invokers of this
procedure should attempt appropriate error recovery.
See also Sections 13 ("Internationalized Domain Names for
Applications (IDNA): Dependency and Migration") and 14.10
("Internationalized Domain Names") of this specification for further
details and considerations.
11. Server Implementation and Deployment Advice
This section is non-normative.11.1. Non-Conformant User Agent Considerations
Non-conformant UAs ignore the Strict-Transport-Security header field; thus, non-conformant user agents do not address the threats described in Section 2.3.1 ("Threats Addressed"). Please refer to Section 14.2 ("Non-Conformant User Agent Implications") for further discussion.11.2. HSTS Policy Expiration Time Considerations
Server implementations and deploying web sites need to consider whether they are setting an expiry time that is a constant value into the future, or whether they are setting an expiry time that is a fixed point in time. The "constant value into the future" approach can be accomplished by constantly sending the same max-age value to UAs. For example, a max-age value of 7776000 seconds is 90 days: Strict-Transport-Security: max-age=7776000 Note that each receipt of this header by a UA will require the UA to update its notion of when it must delete its knowledge of this Known HSTS Host. The "fixed point in time" approach can be accomplished by sending max-age values that represent the remaining time until the desired expiry time. This would require the HSTS Host to send a newly calculated max-age value in each HTTP response. A consideration here is whether a deployer wishes to have the signaled HSTS Policy expiry time match that for the web site's domain certificate. Additionally, server implementers should consider employing a default max-age value of zero in their deployment configuration systems. This will require deployers to willfully set max-age in order to have UAs enforce the HSTS Policy for their host and will protect them from inadvertently enabling HSTS with some arbitrary non-zero duration.
11.3. Using HSTS in Conjunction with Self-Signed Public-Key Certificates
If all four of the following conditions are true... o a web site/organization/enterprise is generating its own secure transport public-key certificates for web sites, and o that organization's root certification authority (CA) certificate is not typically embedded by default in browser and/or operating system CA certificate stores, and o HSTS Policy is enabled on a host identifying itself using a certificate signed by the organization's CA (i.e., a "self-signed certificate"), and o this certificate does not match a usable TLS certificate association (as defined by Section 4 of the TLSA protocol specification [RFC6698]), ...then secure connections to that site will fail, per the HSTS design. This is to protect against various active attacks, as discussed above. However, if said organization wishes to employ its own CA, and self- signed certificates, in concert with HSTS, it can do so by deploying its root CA certificate to its users' browsers or operating system CA root certificate stores. It can also, in addition or instead, distribute to its users' browsers the end-entity certificate(s) for specific hosts. There are various ways in which this can be accomplished (details are out of scope for this specification). Once its root CA certificate is installed in the browsers, it may employ HSTS Policy on its site(s). Alternatively, that organization can deploy the TLSA protocol; all browsers that also use TLSA will then be able to trust the certificates identified by usable TLS certificate associations as denoted via TLSA. NOTE: Interactively distributing root CA certificates to users, e.g., via email, and having the users install them, is arguably training the users to be susceptible to a possible form of phishing attack. See Section 14.8 ("Bogus Root CA Certificate Phish plus DNS Cache Poisoning Attack"). Thus, care should be taken in the manner in which such certificates are distributed and installed on users' systems and browsers.
11.4. Implications of includeSubDomains
The includeSubDomains directive has practical implications meriting careful consideration; two example scenarios are: o An HSTS Host offers unsecured HTTP-based services on alternate ports or at various subdomains of its HSTS Host domain name. o Distinct web applications are offered at distinct subdomains of an HSTS Host, such that UAs often interact directly with these subdomain web applications without having necessarily interacted with a web application offered at the HSTS Host's domain name (if any). The sections below discuss each of these scenarios in turn.11.4.1. Considerations for Offering Unsecured HTTP Services at Alternate Ports or Subdomains of an HSTS Host
For example, certification authorities often offer their CRL distribution and OCSP services [RFC2560] over plain HTTP, and sometimes at a subdomain of a publicly available web application that may be secured by TLS/SSL. For example, <https://ca.example.com/> is a publicly available web application for "Example CA", a certification authority. Customers use this web application to register their public keys and obtain certificates. "Example CA" generates certificates for customers containing <http://crl-and-ocsp.ca.example.com/> as the value for the "CRL Distribution Points" and "Authority Information Access:OCSP" certificate fields. If ca.example.com were to issue an HSTS Policy with the includeSubDomains directive, then HTTP-based user agents implementing HSTS that have interacted with the ca.example.com web application would fail to retrieve CRLs and fail to check OCSP for certificates, because these services are offered over plain HTTP. In this case, Example CA can either: o not use the includeSubDomains directive, or o ensure that HTTP-based services offered at subdomains of ca.example.com are also uniformly offered over TLS/SSL, or
o offer plain HTTP-based services at a different domain name, e.g.,
crl-and-ocsp.ca.example.NET, or
o utilize an alternative approach to distributing certificate status
information, obviating the need to offer CRL distribution and OCSP
services over plain HTTP (e.g., the "Certificate Status Request"
TLS extension [RFC6066], often colloquially referred to as "OCSP
Stapling").
NOTE: The above points are expressly only an example and do not
purport to address all the involved complexities. For
instance, there are many considerations -- on the part of CAs,
certificate deployers, and applications (e.g., browsers) --
involved in deploying an approach such as "OCSP Stapling".
Such issues are out of scope for this specification.
11.4.2. Considerations for Offering Web Applications at Subdomains of
an HSTS Host
In this scenario, an HSTS Host declares an HSTS Policy with an
includeSubDomains directive, and there also exist distinct web
applications offered at distinct subdomains of the HSTS Host such
that UAs often interact directly with these subdomain web
applications without having necessarily interacted with the HSTS
Host. In such a case, the UAs will not receive or enforce the HSTS
Policy.
For example, the HSTS Host is "example.com", and it is configured to
emit the STS header field with the includeSubDomains directive.
However, example.com's actual web application is addressed at
"www.example.com", and example.com simply redirects user agents to
"https://www.example.com/".
If the STS header field is only emitted by "example.com" but UAs
typically bookmark -- and links (from anywhere on the web) are
typically established to -- "www.example.com", and "example.com" is
not contacted directly by all user agents in some non-zero percentage
of interactions, then some number of UAs will not note "example.com"
as an HSTS Host, and some number of users of "www.example.com" will
be unprotected by HSTS Policy.
To address this, HSTS Hosts should be configured such that the STS
header field is emitted directly at each HSTS Host domain or
subdomain name that constitutes a well-known "entry point" to one's
web application(s), whether or not the includeSubDomains directive is
employed.
Thus, in our example, if the STS header field is emitted from both "example.com" and "www.example.com", this issue will be addressed. Also, if there are any other well-known entry points to web applications offered by "example.com", such as "foo.example.com", they should also be configured to emit the STS header field.
(page 30 continued on part 3)
