1. Introduction
This section is not normative.
Requests
made
from
a
document,
and
for
navigations
away
from
that
document
are
associated
with
a
Referer
header.
While
the
header
can
be
suppressed
for
links
with
the
noreferrer
link
type,
authors
might
wish
to
control
the
Referer
header
more
directly
for
a
number
of
reasons:
1.1. Privacy
A social networking site has a profile page for each of its users, and users add hyperlinks from their profile page to their favorite bands. The social networking site might not wish to leak the user’s profile URL to the band web sites when other users follow those hyperlinks (because the profile URLs might reveal the identity of the owner of the profile).
Some social networking sites, however, might wish to inform the band web sites that the links originated from the social networking site but not reveal which specific user’s profile contained the links.
1.2. Security
A web application uses HTTPS and a URL-based session identifier. The web application might wish to link to HTTPS resources on other web sites without leaking the user’s session identifier in the URL.
Alternatively, a web application may use URLs which themselves grant some capability. Controlling the referrer can help prevent these capability URLs from leaking via referrer headers. [CAPABILITY-URLS]
Note that there are other ways for capability URLs to leak, and controlling the referrer is not enough to control all those potential leaks.
1.3. Trackback
A blog hosted over HTTPS might wish to link to a blog hosted over HTTP and receive trackback links.
2. Key Concepts and Terminology
- referrer policy
-
A
referrer
policy
modifies
the
algorithm
used
to
populate
the
Referer
header when fetching subresources, prefetching, or performing navigations. This document defines the various behaviors for each referrer policy .Every environment settings object has an algorithm for obtaining a referrer policy , which is used by default for all requests with that environment settings object as their client .
- same-origin request
-
A
Request
request is a same-origin request if request ’s origin and the origin of request ’s current url are the same . - cross-origin request
-
A
Request
is a cross-origin request if it is not same-origin .
3. Referrer Policies
A
referrer
policy
is
the
empty
string,
"
no-referrer
",
"
no-referrer-when-downgrade
",
"
same-origin
",
"
origin
",
"
strict-origin
",
"
origin-when-cross-origin
",
"
strict-origin-when-cross-origin
",
or
"
unsafe-url
".
enum {
ReferrerPolicy ,
"" ,
"no-referrer" ,
"no-referrer-when-downgrade" ,
"same-origin" ,
"origin" ,
"strict-origin" ,
"origin-when-cross-origin" ,
"strict-origin-when-cross-origin" };
"unsafe-url"
Each possible referrer policy is explained below. A detailed algorithm for evaluating their effect is given in the §5 Integration with Fetch and §8 Algorithms sections.
Note:
The
referrer
policy
for
an
environment
settings
object
provides
a
default
baseline
policy
for
requests
when
that
environment
settings
object
is
used
as
a
request
client
.
This
policy
may
be
tightened
for
specific
requests
via
mechanisms
like
the
noreferrer
link
type.
3.1.
"
no-referrer
"
The
simplest
policy
is
"
no-referrer
"
,
which
specifies
that
no
referrer
information
is
to
be
sent
along
with
requests
made
from
a
particular
request
client
to
any
origin
.
The
header
will
be
omitted
entirely.
https://example.com/page.html
sets
a
policy
of
"
no-referrer
"
,
then
navigations
to
https://example.com/
(or
any
other
URL)
would
send
no
Referer
header.
3.2.
"
no-referrer-when-downgrade
"
The
"
no-referrer-when-downgrade
"
policy
sends
a
full
URL
along
with
requests
from
environment
settings
objects
whose
HTTPS
state
is
"`modern`"
to
a
potentially
trustworthy
URL
,
and
requests
from
clients
whose
HTTPS
state
is
not
"`modern`"
to
any
origin
.
Requests
from
clients
whose
HTTPS
state
is
"`modern`"
to
non-
potentially
trustworthy
URL
s,
on
the
other
hand,
will
contain
no
referrer
information.
A
Referer
HTTP
header
will
not
be
sent.
https://example.com/page.html
sets
a
policy
of
"
no-referrer-when-downgrade
"
,
then
navigations
to
https://not.example.com/
would
send
a
Referer
HTTP
header
with
a
value
of
https://example.com/page.html
,
as
neither
resource’s
origin
is
a
non-
potentially
trustworthy
URL
.
Navigations
from
that
same
page
to
http
://not.example.com/
would
send
no
Referer
header.
This is a user agent’s default behavior, if no policy is otherwise specified.
3.3.
"
same-origin
"
The
"
same-origin
"
policy
specifies
that
a
full
URL,
stripped
for
use
as
a
referrer
,
is
sent
as
referrer
information
when
making
same-origin
requests
from
a
particular
client
.
Cross-origin
requests
,
on
the
other
hand,
will
contain
no
referrer
information.
A
Referer
HTTP
header
will
not
be
sent.
https://example.com/page.html
sets
a
policy
of
"
same-origin
"
,
then
navigations
to
https://example.com/not-page.html
would
send
a
Referer
header
with
a
value
of
https://example.com/page.html
.
Navigations
from
that
same
page
to
https://
not
.example.com/
would
send
no
Referer
header.
3.4.
"
origin
"
The
"
origin
"
policy
specifies
that
only
the
ASCII
serialization
of
the
origin
of
the
request
client
is
sent
as
referrer
information
when
making
both
same-origin
requests
and
cross-origin
requests
from
a
particular
client
.
Note:
The
serialization
of
an
origin
looks
like
https://example.com
.
To
ensure
that
a
valid
URL
is
sent
in
the
`
Referer
`
header,
user
agents
will
append
a
U+002F
SOLIDUS
("
/
")
character
to
the
origin
(e.g.
https://example.com/
).
Note:
The
"
origin
"
policy
causes
the
origin
of
HTTPS
referrers
to
be
sent
over
the
network
as
part
of
unencrypted
HTTP
requests.
The
"
strict-origin
"
policy
addresses
this
concern.
https://example.com/page.html
sets
a
policy
of
"
origin
"
,
then
navigations
to
any
origin
would
send
a
Referer
header
with
a
value
of
https://example.com/
,
even
to
URLs
that
are
not
potentially
trustworthy
URL
.
3.5.
"
strict-origin
"
The
"
strict-origin
"
policy
sends
the
ASCII
serialization
of
the
origin
of
the
request
client
when
making
requests:
- from an environment settings object whose HTTPS state is "`modern`" to a potentially trustworthy URL , and
- from environment settings objects whose HTTPS state is not "`modern`" to any origin .
Requests
from
request
clients
whose
HTTPS
state
is
"`modern`"
to
non-
potentially
trustworthy
URL
s,
on
the
other
hand,
will
contain
no
referrer
information.
A
Referer
HTTP
header
will
not
be
sent.
https://example.com/page.html
sets
a
policy
of
"
strict-origin
"
,
then
navigations
to
https://
not
.example.com
would
send
a
Referer
header
with
a
value
of
https://example.com/
.
Navigations
from
that
same
page
to
http://
not.example.com
would
send
no
Referer
header.
http://example.com/page.html
sets
a
policy
of
"
strict-origin
"
,
then
navigations
to
http://
not
.example.com
or
https
://example.com
would
send
a
Referer
header
with
a
value
of
http://example.com/
.
3.6.
"
origin-when-cross-origin
"
The
"
origin-when-cross-origin
"
policy
specifies
that
a
full
URL,
stripped
for
use
as
a
referrer
,
is
sent
as
referrer
information
when
making
same-origin
requests
from
a
particular
request
client
,
and
only
the
ASCII
serialization
of
the
origin
of
the
request
client
is
sent
as
referrer
information
when
making
cross-origin
requests
from
a
particular
client
.
Note:
For
the
"
origin-when-cross-origin
"
policy,
we
also
consider
protocol
upgrades,
e.g.
requests
from
http://example.com/
to
https://example.com/
,
to
be
cross-origin
requests
.
Note:
The
"
origin-when-cross-origin
"
policy
causes
the
origin
of
HTTPS
referrers
to
be
sent
over
the
network
as
part
of
unencrypted
HTTP
requests.
The
"
strict-origin-when-cross-origin
"
policy
addresses
this
concern.
https://example.com/page.html
sets
a
policy
of
"
origin-when-cross-origin
"
,
then
navigations
to
https://example.com/not-page.html
would
send
a
Referer
header
with
a
value
of
https://example.com/page.html
.
Navigations
from
that
same
page
to
https://not.example.com/
would
send
a
Referer
header
with
a
value
of
https://example.com/
,
even
to
URLs
that
are
not
potentially
trustworthy
URL
s.
3.7.
"
strict-origin-when-cross-origin
"
The
"
strict-origin-when-cross-origin
"
policy
specifies
that
a
full
URL,
stripped
for
use
as
a
referrer
,
is
sent
as
referrer
information
when
making
same-origin
requests
from
a
particular
request
client
,
and
only
the
ASCII
serialization
of
the
origin
of
the
request
client
when
making
cross-origin
requests
:
- from a environment settings object whose HTTPS state is "`modern`" to a potentially trustworthy URL , and
- from environment settings objects whose HTTPS state is not "`modern`" to any origin .
Requests
from
clients
whose
HTTPS
state
is
"`modern`"
to
non-
potentially
trustworthy
URL
s,
on
the
other
hand,
will
contain
no
referrer
information.
A
Referer
HTTP
header
will
not
be
sent.
https://example.com/page.html
sets
a
policy
of
"
strict-origin-when-cross-origin
"
,
then
navigations
to
https://example.com/not-page.html
would
send
a
Referer
header
with
a
value
of
https://example.com/page.html
.
Navigations
from
that
same
page
to
https://not.example.com/
would
send
a
Referer
header
with
a
value
of
https://example.com/
.
Navigations
from
that
same
page
to
http://
not.example.com/
would
send
no
Referer
header.
3.8.
"
unsafe-url
"
The
"
unsafe-url
"
policy
specifies
that
a
full
URL,
stripped
for
use
as
a
referrer
,
is
sent
along
with
both
cross-origin
requests
and
same-origin
requests
made
from
a
particular
client
.
https://example.com/sekrit.html
sets
a
policy
of
"
unsafe-url
"
,
then
navigations
to
http://not.example.com/
(and
every
other
origin)
would
send
a
Referer
HTTP
header
with
a
value
of
https://example.com/sekrit.html
.
Note: The policy’s name doesn’t lie; it is unsafe. This policy will leak origins and paths from secure resources to insecure origins. Carefully consider the impact of setting such a policy for potentially sensitive documents.
3.9. The empty string
The
empty
string
""
corresponds
to
no
referrer
policy
,
causing
a
fallback
to
a
referrer
policy
defined
elsewhere,
or
in
the
case
where
no
such
higher-level
policy
is
available,
defaulting
to
"
no-referrer-when-downgrade
"
.
This
defaulting
happens
in
the
§8.3
Determine
request’s
Referrer
algorithm.
a
element
without
any
declared
referrerpolicy
attribute,
its
referrer
policy
is
the
empty
string.
Thus,
navigation
requests
initiated
by
clicking
on
that
a
element
will
be
sent
with
the
referrer
policy
of
the
a
element’s
node
document
.
If
that
Document
has
the
empty
string
as
its
referrer
policy,
the
§8.3
Determine
request’s
Referrer
algorithm
will
treat
the
empty
string
the
same
as
"
no-referrer-when-downgrade
"
.
4. Referrer Policy Delivery
A request ’s referrer policy is delivered in one of five ways:
-
Via
the
Referrer-Policy
HTTP header (defined in §4.1 Delivery via Referrer-Policy header ). -
Via
a
meta
element with aname
ofreferrer
. -
Via
a
referrerpolicy
content attribute on ana
,area
,img
,iframe
, orlink
element. -
Via
the
noreferrer
link relation on ana
, orarea
element. - Implicitly, via inheritance.
4.1. Delivery via Referrer-Policy header
The
Referrer-Policy
HTTP
header
specifies
the
referrer
policy
that
the
user
agent
applies
when
determining
what
referrer
information
should
be
included
with
requests
made,
and
with
browsing
contexts
created
from
the
context
of
the
protected
resource.
The
syntax
for
the
name
and
value
of
the
header
are
described
by
the
following
ABNF
grammar.
ABNF
is
defined
in
[RFC5234]
,
and
the
#rule
ABNF
extension
used
below
is
defined
in
Section
7
of
[RFC7230]
.
"Referrer-Policy:" 1#(policy-token / extension-token)
policy-token = "no-referrer" / "no-referrer-when-downgrade" / "strict-origin" / "strict-origin-when-cross-origin" / "same-origin" / "origin" / "origin-when-cross-origin" / "unsafe-url" extension-token = 1*( ALPHA / "-" )
Note: The header name does not share the HTTP Referer header’s misspelling.
Note: The purpose of extension-token is so that browsers do not fail to parse the entire header field if it includes an unknown policy value. §11.1 Unknown Policy Values describes in greater detail how new policy values can be deployed.
Note: The quotes in the ABNF above are used to indicate literal strings. Referrer-Policy header values should not be quoted.
§5
Integration
with
Fetch
and
§6
Integration
with
HTML
describe
how
the
Referrer-Policy
header
is
processed.
4.1.1. Usage
This section is not normative.
A
protected
resource
can
prevent
referrer
leakage
by
specifying
no-referrer
as
the
value
of
its
Referrer-Policy
header:
Referrer-Policy: no-referrer
This
will
cause
all
requests
made
from
the
protected
resource’s
context
to
have
an
empty
Referer
[sic]
header.
4.2.
Delivery
via
meta
This section is not normative.
The
HTML
Standard
defines
the
referrer
keyword
for
the
meta
element,
which
allows
setting
the
referrer
policy
via
markup.
4.3.
Delivery
via
a
referrerpolicy
content
attribute
This section is not normative.
The HTML Standard defines the concept of referrer policy attributes which applies to several of its elements, for example:
< a href = "http://example.com" referrerpolicy = "origin" >
4.4. Nested browsing contexts
This section is not normative.
The
HTML
Standard
and
Fetch
Standard
define
how
nested
browsing
contexts
that
are
not
created
from
responses
,
such
as
iframe
elements
with
their
srcdoc
attribute
set,
or
created
from
a
blob
URL,
inherit
their
referrer
policy
from
the
creator
browsing
context
or
blob
URL.
5. Integration with Fetch
This section is not normative.
The Fetch specification calls out to §8.2 Set request’s referrer policy on redirect before Step 13 of the HTTP-redirect fetch , so that a request’s referrer policy can be updated before following a redirect.
The
Fetch
specification
calls
out
to
§8.3
Determine
request’s
Referrer
as
Step
8
of
the
Main
fetch
algorithm
,
and
uses
the
result
to
set
the
request
’s
referrer
property.
Fetch
is
responsible
for
serializing
the
URL
provided,
and
setting
the
`
Referer
`
header
on
request
.
6. Integration with HTML
This section is not normative.
The
HTML
Standard
determines
the
referrer
policy
of
any
response
received
during
navigation
or
while
running
a
worker
,
and
uses
the
result
to
set
the
resulting
Document
or
WorkerGlobalScope
's
referrer
policy.
This
is
later
used
by
the
corresponding
environment
settings
object
,
which
serves
as
a
request
client
for
fetches
it
initiates.
Note:
W3C
HTML5
does
not
define
the
referrerpolicy
content
attributes,
or
referrerPolicy
IDL
attributes,
or
the
referrer
keyword
for
meta
,
or
the
integration
with
navigation
or
running
a
worker.
For
this
spec
to
make
sense
with
W3C
HTML5,
those
would
need
to
be
copied
from
[HTML]
.
7. Integration with CSS
The CSS Standard does not specify how it fetches resources referenced from stylesheets. However, implementations should be sure to set the referrer-related properties of any requests initiated by stylesheets as follows:
-
If
a
CSS
style
sheet
is
responsible
for
the
request,
and
its
location
is
non-null,
set
the
referrer
to
its
location
,
and
the
referrer
policy
to
its
referrer
policy
.
This requires that CSS style sheets process `Referrer-Policy` headers, and store a referrer policy in the same way that Documents do .
- If a CSS style sheet with a null location is responsible for the request, set the referrer to its owner node ’s node document ’s URL , and the referrer policy to its owner node ’s node document ’s referrer policy .
- Otherwise, a CSS declaration block that was created by the embedder is responsible for the request - either from parsing of an element’s style attribute , or to implement an presentational hint for an element. We assume that in this case the CSS declaration block ’s owner node points to that element, and set the referrer to the block’s owner node ’s node document ’s URL , and the referrer policy to the block’s owner node ’s node document ’s referrer policy .
Note: Both the value of the request ’s referrer and referrer policy are set based on the values at the time a given request is created. If a document’s referrer policy changes during its lifetime, the policy associated with inline stylesheet requests will also change.
8. Algorithms
8.1.
Parse
a
referrer
policy
from
a
Referrer-Policy
header
Given
a
response
response
,
the
following
steps
return
a
referrer
policy
according
to
response
’s
`
Referrer-Policy
`
header:
-
Let
policy-tokens
be
the
result
of
extracting
header
list
values
given
`
Referrer-Policy
` and response ’s header list . - Let policy be the empty string.
-
For
each
token
in
policy-tokens
,
if
token
is
a
referrer
policy
and
token
is
not
the
empty
string,
then
set
policy
to
token
.
Note: This algorithm loops over multiple policy values to allow deployment of new policy values with fallbacks for older user agents, as described in §11.1 Unknown Policy Values .
- Return policy .
8.2. Set request ’s referrer policy on redirect
Given a request request and a response actualResponse , this algorithm updates request ’s associated referrer policy according to the Referrer-Policy header (if any) in actualResponse .
- Let policy be the result of executing §8.1 Parse a referrer policy from a Referrer-Policy header on actualResponse .
- If policy is not the empty string, then set request ’s associated referrer policy to policy .
8.3. Determine request ’s Referrer
Given
a
request
request
,
we
can
determine
the
correct
referrer
information
to
send
by
examining
the
referrer
policy
associated
with
it,
as
detailed
in
the
following
steps,
which
return
either
no
referrer
or
a
URL:
- Let policy be request ’s associated referrer policy .
- Let environment be request ’s client .
-
Switch
on
request
’s
referrer
:
-
"
client
" -
-
If
environment
’s
global
object
is
a
Window
object, then-
Let
document
be
the
associated
Document
of environment ’s global object . -
If
document
’s
origin
is
an
opaque
origin
,
return
no referrer
. -
While
document
is
an
iframe srcdoc
document , let document be document ’s browsing context ’s browsing context container ’s node document . - Let referrerSource be document ’s URL .
-
Let
document
be
the
associated
- Otherwise, let referrerSource be environment ’s creation URL .
-
If
environment
’s
global
object
is
a
- a URL
- Let referrerSource be request ’s referrer .
Note: If request ’s referrer is "
no-referrer
", Fetch will not call into this algorithm. -
"
- Let referrerURL be the result of stripping referrerSource for use as a referrer.
- If the result of serializing referrerURL is a string whose length is greater than 4096, set referrerURL to referrerOrigin .
-
Let
referrerOrigin
be
the
result
of
stripping
referrerSource
for
use
as
a
referrer
,
with
the
origin-only flag
set totrue
. -
Execute
the
statements
corresponding
to
the
value
of
policy
:
-
"
no-referrer
" -
Return
no referrer
-
"
origin
" - Return referrerOrigin
-
"
unsafe-url
" - Return referrerURL .
-
"
strict-origin
" -
-
If
environment
is
not
null:
-
If
environment
’s
HTTPS
state
is
"`modern`"
and
request
’s
current
URL
is
not
a
potentially
trustworthy
URL
,
then
return
no referrer
.
-
If
environment
’s
HTTPS
state
is
"`modern`"
and
request
’s
current
URL
is
not
a
potentially
trustworthy
URL
,
then
return
- Return referrerOrigin .
-
If
environment
is
not
null:
-
"
strict-origin-when-cross-origin
" -
- If request is a same-origin request , then return referrerURL .
-
If
environment
is
not
null:
-
If
environment
’s
HTTPS
state
is
"`modern`"
and
request
’s
current
URL
is
not
a
potentially
trustworthy
URL
-
Return
no referrer
.
-
Return
-
If
environment
’s
HTTPS
state
is
"`modern`"
and
request
’s
current
URL
is
not
a
potentially
trustworthy
URL
- Return referrerOrigin .
-
"
same-origin
" -
- If request is a same-origin request , then return referrerURL .
-
Otherwise,
return
no referrer
.
-
"
origin-when-cross-origin
" -
- If request is a cross-origin request , then return referrerOrigin .
- Otherwise, return referrerURL .
-
"
no-referrer-when-downgrade
" -
-
If
environment
is
not
null:
-
If
environment
’s
HTTPS
state
is
"`modern`"
and
request
’s
current
URL
is
not
a
potentially
trustworthy
URL
,
then
return
no referrer
.
-
If
environment
’s
HTTPS
state
is
"`modern`"
and
request
’s
current
URL
is
not
a
potentially
trustworthy
URL
,
then
return
- Return referrerURL .
-
If
environment
is
not
null:
Note: Fetch will ensure request ’s referrer policy is not the empty string before calling this algorithm.
-
"
8.4. Strip url for use as a referrer
Certain
portions
of
URLs
must
not
be
included
when
sending
a
URL
as
the
value
of
a
`
Referer
`
header:
a
URLs
fragment,
username,
and
password
components
must
be
stripped
from
the
URL
before
it’s
sent
out.
This
algorithm
accepts
a
origin-only
flag
,
which
defaults
to
false
.
If
set
to
true
,
the
algorithm
will
additionally
remove
the
URL’s
path
and
query
components,
leaving
only
the
scheme,
host,
and
port.
-
If
url
is
null
, returnno referrer
. -
If
url
’s
scheme
is
a
local
scheme
,
then
return
no referrer
. - Set url ’s username to the empty string.
-
Set
url
’s
password
to
null
. -
Set
url
’s
fragment
to
null
. -
If
the
origin-only flag
istrue
, then: - Return url .
9. Privacy Considerations
9.1. User Controls
Nothing
in
this
specification
should
be
interpreted
as
preventing
user
agents
from
offering
options
to
users
which
would
change
the
information
sent
out
via
a
`
Referer
`
header.
For
instance,
user
agents
MAY
allow
users
to
suppress
the
referrer
header
entirely,
regardless
of
the
active
referrer
policy
on
a
page.
10. Security Considerations
10.1. Information Leakage
The
referrer
policies
"
origin
"
,
"
origin-when-cross-origin
"
and
"
unsafe-url
"
might
leak
the
origin
and
the
URL
of
a
secure
site
respectively
via
insecure
transport.
Those three policies are included in the spec nevertheless to lower the friction of sites adopting secure transport.
Authors
wanting
to
ensure
that
they
do
not
leak
any
more
information
than
the
default
policy
should
instead
use
the
policy
states
"
same-origin
"
,
"
strict-origin
"
,
"
strict-origin-when-cross-origin
"
or
"
no-referrer
"
.
10.2. Downgrade to less strict policies
The
spec
does
not
forbid
downgrading
to
less
strict
policies,
e.g.,
from
"
no-referrer
"
to
"
unsafe-url
"
.
On
the
one
hand,
it
is
not
clear
which
policy
is
more
strict
for
all
possible
pairs
of
policies:
While
"
no-referrer-when-downgrade
"
will
not
leak
any
information
over
insecure
transport,
and
"
origin
"
will,
the
latter
reveals
less
information
across
cross-origin
navigations.
On the other hand, allowing for setting less strict policies enables authors to define safe fallbacks as described in §11.1 Unknown Policy Values .
11. Authoring Considerations
11.1. Unknown Policy Values
As
described
in
§8.1
Parse
a
referrer
policy
from
a
Referrer-Policy
header
and
in
the
meta
referrer
algorithm,
unknown
policy
values
will
be
ignored,
and
when
multiple
sources
specify
a
referrer
policy,
the
value
of
the
latest
one
will
be
used.
This
makes
it
possible
to
deploy
new
policy
values.
unsafe-url
"
policy.
A
site
can
specify
an
"
origin
"
policy
followed
by
an
"
unsafe-url
"
policy:
older
user
agents
will
ignore
the
unknown
"
unsafe-url
"
value
and
use
"
origin
"
,
while
newer
user
agents
will
use
"
unsafe-url
"
because
it
is
the
last
to
be
processed.
Referrer-Policy: no-referrer Referrer-Policy: unsafe-url
or, equivalently, multiple comma-separated header values:
Referrer-Policy: no-referrer,unsafe-url
This
behavior
does
not,
however,
apply
to
the
referrerpolicy
attribute.
Authors
may
dynamically
set
and
get
the
referrerpolicy
attribute
to
detect
whether
a
particular
policy
value
is
supported.
12. Acknowledgements
This specification is based in large part on Adam Barth and Jochen Eisinger’s Meta referrer document.