HTTP Alternative Services
draft-ietf-httpbis-alt-svc-13
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 7838.
|
|
|---|---|---|---|
| Authors | Mark Nottingham , Patrick McManus , Julian Reschke | ||
| Last updated | 2016-03-08 (Latest revision 2016-03-01) | ||
| Replaces | draft-nottingham-httpbis-alt-svc | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews | |||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | Submitted to IESG for Publication | |
| Document shepherd | Mike Bishop | ||
| Shepherd write-up | Show Last changed 2015-12-29 | ||
| IESG | IESG state | Became RFC 7838 (Proposed Standard) | |
| Consensus boilerplate | Yes | ||
| Telechat date | (None) | ||
| Responsible AD | Barry Leiba | ||
| Send notices to | "Mike Bishop" <michael.bishop@microsoft.com> | ||
| IANA | IANA review state | IANA OK - Actions Needed |
draft-ietf-httpbis-alt-svc-13
HTTP Working Group M. Nottingham
Internet-Draft Akamai
Intended status: Standards Track P. McManus
Expires: September 2, 2016 Mozilla
J. Reschke
greenbytes
March 1, 2016
HTTP Alternative Services
draft-ietf-httpbis-alt-svc-13
Abstract
This document specifies "Alternative Services" for HTTP, which allow
an origin's resources to be authoritatively available at a separate
network location, possibly accessed with a different protocol
configuration.
Editorial Note (To be removed by RFC Editor)
Discussion of this draft takes place on the HTTPBIS working group
mailing list (ietf-http-wg@w3.org), which is archived at
<https://lists.w3.org/Archives/Public/ietf-http-wg/>.
Working Group information can be found at <http://httpwg.github.io/>;
source code and issues list for this draft can be found at
<https://github.com/httpwg/http-extensions>.
The changes in this draft are summarized in Appendix A.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 2, 2016.
Nottingham, et al. Expires September 2, 2016 [Page 1]
Internet-Draft HTTP Alternative Services March 2016
Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Nottingham, et al. Expires September 2, 2016 [Page 2]
Internet-Draft HTTP Alternative Services March 2016
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4
2. Alternative Services Concepts . . . . . . . . . . . . . . . . 5
2.1. Host Authentication . . . . . . . . . . . . . . . . . . . 7
2.2. Alternative Service Caching . . . . . . . . . . . . . . . 7
2.3. Requiring Server Name Indication . . . . . . . . . . . . . 8
2.4. Using Alternative Services . . . . . . . . . . . . . . . . 8
3. The Alt-Svc HTTP Header Field . . . . . . . . . . . . . . . . 9
3.1. Caching Alt-Svc Header Field Values . . . . . . . . . . . 11
4. The ALTSVC HTTP/2 Frame . . . . . . . . . . . . . . . . . . . 12
5. The Alt-Used HTTP Header Field . . . . . . . . . . . . . . . . 14
6. The 421 Misdirected Request HTTP Status Code . . . . . . . . . 14
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
7.1. Header Field Registrations . . . . . . . . . . . . . . . . 15
7.2. The ALTSVC HTTP/2 Frame Type . . . . . . . . . . . . . . . 15
7.3. Alt-Svc Parameter Registry . . . . . . . . . . . . . . . . 15
7.3.1. Procedure . . . . . . . . . . . . . . . . . . . . . . 15
7.3.2. Registrations . . . . . . . . . . . . . . . . . . . . 16
8. Internationalization Considerations . . . . . . . . . . . . . 16
9. Security Considerations . . . . . . . . . . . . . . . . . . . 16
9.1. Changing Ports . . . . . . . . . . . . . . . . . . . . . . 16
9.2. Changing Hosts . . . . . . . . . . . . . . . . . . . . . . 17
9.3. Changing Protocols . . . . . . . . . . . . . . . . . . . . 17
9.4. Tracking Clients Using Alternative Services . . . . . . . 18
9.5. Confusion Regarding Request Scheme . . . . . . . . . . . . 18
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
10.1. Normative References . . . . . . . . . . . . . . . . . . . 19
10.2. Informative References . . . . . . . . . . . . . . . . . . 20
Appendix A. Change Log (to be removed by RFC Editor before
publication) . . . . . . . . . . . . . . . . . . . . 20
A.1. Since draft-nottingham-httpbis-alt-svc-05 . . . . . . . . 20
A.2. Since draft-ietf-httpbis-alt-svc-00 . . . . . . . . . . . 21
A.3. Since draft-ietf-httpbis-alt-svc-01 . . . . . . . . . . . 21
A.4. Since draft-ietf-httpbis-alt-svc-02 . . . . . . . . . . . 21
A.5. Since draft-ietf-httpbis-alt-svc-03 . . . . . . . . . . . 21
A.6. Since draft-ietf-httpbis-alt-svc-04 . . . . . . . . . . . 21
A.7. Since draft-ietf-httpbis-alt-svc-05 . . . . . . . . . . . 22
A.8. Since draft-ietf-httpbis-alt-svc-06 . . . . . . . . . . . 22
A.9. Since draft-ietf-httpbis-alt-svc-07 . . . . . . . . . . . 22
A.10. Since draft-ietf-httpbis-alt-svc-08 . . . . . . . . . . . 23
A.11. Since draft-ietf-httpbis-alt-svc-09 . . . . . . . . . . . 24
A.12. Since draft-ietf-httpbis-alt-svc-10 . . . . . . . . . . . 24
A.13. Since draft-ietf-httpbis-alt-svc-11 . . . . . . . . . . . 24
A.14. Since draft-ietf-httpbis-alt-svc-12 . . . . . . . . . . . 24
Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 24
Nottingham, et al. Expires September 2, 2016 [Page 3]
Internet-Draft HTTP Alternative Services March 2016
1. Introduction
HTTP [RFC7230] conflates the identification of resources with their
location. In other words, "http://" and "https://" URIs are used to
both name and find things to interact with.
In some cases, it is desirable to separate identification and
location in HTTP; keeping the same identifier for a resource, but
interacting with it at a different location on the network.
For example:
o An origin server might wish to redirect a client to a different
server when it is under load, or it has found a server in a
location that is more local to the client.
o An origin server might wish to offer access to its resources using
a new protocol, such as HTTP/2 [RFC7540], or one using improved
security, such as Transport Layer Security (TLS) [RFC5246].
o An origin server might wish to segment its clients into groups of
capabilities, such as those supporting Server Name Indication
(SNI) (Section 3 of [RFC6066]), for operational purposes.
This specification defines a new concept in HTTP, "Alternative
Services", that allows an origin server to nominate additional means
of interacting with it on the network. It defines a general
framework for this in Section 2, along with specific mechanisms for
advertising their existence using HTTP header fields (Section 3) or
HTTP/2 frames (Section 4), plus a way to indicate that an alternative
service was used (Section 5).
It also endorses the status code 421 (Misdirected Request)
(Section 6) that origin servers or their nominated alternatives can
use to indicate that they are not authoritative for a given origin,
in cases where the wrong location is used.
1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
This document uses the Augmented BNF defined in [RFC5234] and updated
by [RFC7405] along with the "#rule" extension defined in Section 7 of
[RFC7230]. The rules below are defined in [RFC5234], [RFC7230], and
[RFC7234]:
Nottingham, et al. Expires September 2, 2016 [Page 4]
Internet-Draft HTTP Alternative Services March 2016
OWS = <OWS, see [RFC7230], Section 3.2.3>
delta-seconds = <delta-seconds; see [RFC7234], Section 1.2.1>
port = <port, see [RFC7230], Section 2.7>
quoted-string = <quoted-string, see [RFC7230], Section 3.2.6>
token = <token, see [RFC7230], Section 3.2.6>
uri-host = <uri-host, see [RFC7230], Section 2.7>
2. Alternative Services Concepts
This specification defines a new concept in HTTP, the "Alternative
Service". When an origin [RFC6454] has resources that are accessible
through a different protocol / host / port combination, it is said to
have an alternative service available.
An alternative service can be used to interact with the resources on
an origin server at a separate location on the network, possibly
using a different protocol configuration. Alternative services are
considered authoritative for an origin's resources, in the sense of
[RFC7230], Section 9.1.
For example, an origin:
("http", "www.example.com", "80")
might declare that its resources are also accessible at the
alternative service:
("h2", "new.example.com", "81")
By their nature, alternative services are explicitly at the
granularity of an origin; they cannot be selectively applied to
resources within an origin.
Alternative services do not replace or change the origin for any
given resource; in general, they are not visible to the software
"above" the access mechanism. The alternative service is essentially
alternative routing information that can also be used to reach the
origin in the same way that DNS CNAME or SRV records define routing
information at the name resolution level. Each origin maps to a set
of these routes -- the default route is derived from the origin
itself and the other routes are introduced based on alternative-
service information.
Furthermore, it is important to note that the first member of an
alternative service tuple is different from the "scheme" component of
an origin; it is more specific, identifying not only the major
version of the protocol being used, but potentially communication
options for that protocol.
Nottingham, et al. Expires September 2, 2016 [Page 5]
Internet-Draft HTTP Alternative Services March 2016
This means that clients using an alternative service can change the
host, port and protocol that they are using to fetch resources, but
these changes MUST NOT be propagated to the application that is using
HTTP; from that standpoint, the URI being accessed and all
information derived from it (scheme, host, port) are the same as
before.
Importantly, this includes its security context; in particular, when
TLS [RFC5246] is used to authenticate, the alternative service will
need to present a certificate for the origin's host name, not that of
the alternative. Likewise, the Host header field ([RFC7230], Section
5.4) is still derived from the origin, not the alternative service
(just as it would if a CNAME were being used).
The changes MAY, however, be made visible in debugging tools,
consoles, etc.
Formally, an alternative service is identified by the combination of:
o An Application Layer Protocol Negotiation (ALPN) protocol name, as
per [RFC7301]
o A host, as per [RFC3986], Section 3.2.2
o A port, as per [RFC3986], Section 3.2.3
The ALPN protocol name is used to identify the application protocol
or suite of protocols used by the alternative service. Note that for
the purpose of this specification, an ALPN protocol name implicitly
includes TLS in the suite of protocols it identifies, unless
specified otherwise in its definition. In particular, the ALPN name
"http/1.1", registered by Section 6 of [RFC7301], identifies HTTP/1.1
over TLS.
Additionally, each alternative service MUST have:
o A freshness lifetime, expressed in seconds; see Section 2.2
There are many ways that a client could discover the alternative
service(s) associated with an origin. This document describes two
such mechanisms: the "Alt-Svc" HTTP header field (Section 3) and the
"ALTSVC" HTTP/2 frame type (Section 4).
The remainder of this section describes requirements that are common
to alternative services, regardless of how they are discovered.
Nottingham, et al. Expires September 2, 2016 [Page 6]
Internet-Draft HTTP Alternative Services March 2016
2.1. Host Authentication
Clients MUST have reasonable assurances that the alternative service
is under control of and valid for the whole origin. This mitigates
the attack described in Section 9.2.
For the purposes of this document, "reasonable assurances" can be
established through use of a TLS-based protocol with the certificate
checks defined in [RFC2818]. Other means of establishing them MUST
be documented in an RFC that updates this specification. Clients MAY
impose additional criteria for establishing reasonable assurances.
For example, if the origin's host is "www.example.com" and an
alternative is offered on "other.example.com" with the "h2" protocol,
and the certificate offered is valid for "www.example.com", the
client can use the alternative. However, if either is offered with
the "h2c" protocol, the client cannot use it, because there is no
mechanism (at the time of the publication of this specification) in
that protocol to establish the relationship between the origin and
the alternative.
2.2. Alternative Service Caching
Mechanisms for discovering alternative services also associate a
freshness lifetime with them; for example, the Alt-Svc header field
uses the "ma" parameter.
Clients can choose to use an alternative service instead of the
origin at any time when it is considered fresh; see Section 2.4 for
specific recommendations.
Clients with existing connections to an alternative service do not
need to stop using it when its freshness lifetime ends; the caching
mechanism is intended for limiting how long an alternative service
can be used for establishing new connections, not limiting the use of
existing ones.
Alternative services are fully authoritative for the origin in
question, including the ability to clear or update cached alternative
service entries, extend freshness lifetimes, and any other authority
the origin server would have.
When alternative services are used to send a client to the most
optimal server, a change in network configuration can result in
cached values becoming suboptimal. Therefore, clients SHOULD remove
from cache all alternative services that lack the "persist" flag with
the value "1" when they detect such a change, when information about
network state is available.
Nottingham, et al. Expires September 2, 2016 [Page 7]
Internet-Draft HTTP Alternative Services March 2016
2.3. Requiring Server Name Indication
A client MUST only use a TLS-based alternative service if the client
also supports TLS Server Name Indication (SNI). This supports the
conservation of IP addresses on the alternative service host.
Note that the SNI information provided in TLS by the client will be
that of the origin, not the alternative (as will the Host HTTP header
field value).
2.4. Using Alternative Services
By their nature, alternative services are OPTIONAL: clients do not
need to use them. However, it is advantageous for clients to behave
in a predictable way when alternative services are used by servers,
to aid purposes like load balancing.
Therefore, if a client becomes aware of an alternative service, the
client SHOULD use that alternative service for all requests to the
associated origin as soon as it is available, provided the
alternative service information is fresh (Section 2.2) and the
security properties of the alternative service protocol are
desirable, as compared to the existing connection. A viable
alternative service is then treated in every way as the origin; this
includes the ability to advertise alternative services.
If a client becomes aware of multiple alternative services, it
chooses the most suitable according to its own criteria, keeping
security properties in mind. For example, an origin might advertise
multiple alternative services to notify clients of support for
multiple versions of HTTP.
A client configured to use a proxy for a given request SHOULD NOT
directly connect to an alternative service for this request, but
instead route it through that proxy.
When a client uses an alternative service for a request, it can
indicate this to the server using the Alt-Used header field
(Section 5).
The client does not need to block requests on any existing
connection; it can be used until the alternative connection is
established. However, if the security properties of the existing
connection are weak (for example, cleartext HTTP/1.1) then it might
make sense to block until the new connection is fully available in
order to avoid information leakage.
Furthermore, if the connection to the alternative service fails or is
Nottingham, et al. Expires September 2, 2016 [Page 8]
Internet-Draft HTTP Alternative Services March 2016
unresponsive, the client MAY fall back to using the origin or another
alternative service. Note, however, that this could be the basis of
a downgrade attack, thus losing any enhanced security properties of
the alternative service. If the connection to the alternative
service does not negotiate the expected protocol (for example, ALPN
fails to negotiate h2, or an Upgrade request to h2c is not accepted),
the connection to the alternative service MUST be considered to have
failed.
3. The Alt-Svc HTTP Header Field
An HTTP(S) origin server can advertise the availability of
alternative services to clients by adding an Alt-Svc header field to
responses.
Alt-Svc = clear / 1#alt-value
clear = %s"clear"; "clear", case-sensitive
alt-value = alternative *( OWS ";" OWS parameter )
alternative = protocol-id "=" alt-authority
protocol-id = token ; percent-encoded ALPN protocol name
alt-authority = quoted-string ; containing [ uri-host ] ":" port
parameter = token "=" ( token / quoted-string )
The field value consists either of a list of values, each of which
indicates one alternative service, or the keyword "clear".
A field value containing the special value "clear" indicates that the
origin requests all alternatives for that origin to be invalidated
(including those specified in the same response, in case of an
invalid reply containing both "clear" and alternative services).
ALPN protocol names are octet sequences with no additional
constraints on format. Octets not allowed in tokens ([RFC7230],
Section 3.2.6) MUST be percent-encoded as per Section 2.1 of
[RFC3986]. Consequently, the octet representing the percent
character "%" (hex 25) MUST be percent-encoded as well.
In order to have precisely one way to represent any ALPN protocol
name, the following additional constraints apply:
1. Octets in the ALPN protocol name MUST NOT be percent-encoded if
they are valid token characters except "%", and
2. When using percent-encoding, uppercase hex digits MUST be used.
With these constraints, recipients can apply simple string comparison
to match protocol identifiers.
Nottingham, et al. Expires September 2, 2016 [Page 9]
Internet-Draft HTTP Alternative Services March 2016
The "alt-authority" component consists of an OPTIONAL uri-host
("host" in Section 3.2.2 of [RFC3986]), a colon (":"), and a port
number.
For example:
Alt-Svc: h2=":8000"
This indicates the "h2" protocol ([RFC7540]) on the same host using
the indicated port 8000.
An example involving a change of host:
Alt-Svc: h2="new.example.org:80"
This indicates the "h2" protocol on the host "new.example.org",
running on port 80. Note that the "quoted-string" syntax needs to be
used because ":" is not an allowed character in "token".
Examples for protocol name escaping:
+--------------------+-------------+---------------------+
| ALPN protocol name | protocol-id | Note |
+--------------------+-------------+---------------------+
| h2 | h2 | No escaping needed |
+--------------------+-------------+---------------------+
| w=x:y#z | w%3Dx%3Ay#z | "=" and ":" escaped |
+--------------------+-------------+---------------------+
| x%y | x%25y | "%" needs escaping |
+--------------------+-------------+---------------------+
Alt-Svc MAY occur in any HTTP response message, regardless of the
status code. Note that recipients of Alt-Svc can ignore the header
field (and are required to in some situations; see Sections 2.1 and
6).
The Alt-Svc field value can have multiple values:
Alt-Svc: h2="alt.example.com:8000", h2=":443"
When multiple values are present, the order of the values reflects
the server's preference (with the first value being the most
preferred alternative).
The value(s) advertised by Alt-Svc can be used by clients to open a
new connection to an alternative service. Subsequent requests can
start using this new connection immediately, or can continue using
the existing connection while the new connection is created.
Nottingham, et al. Expires September 2, 2016 [Page 10]
Internet-Draft HTTP Alternative Services March 2016
When using HTTP/2 ([RFC7540]), servers SHOULD instead send an ALTSVC
frame (Section 4). A single ALTSVC frame can be sent for a
connection; a new frame is not needed for every request. Note that,
despite this recommendation, Alt-Svc header fields remain valid in
responses delivered over HTTP/2.
Each "alt-value" is followed by an OPTIONAL semicolon-separated list
of additional parameters, each such "parameter" comprising a name and
a value.
This specification defines two parameters: "ma" and "persist",
defined in Section 3.1. Unknown parameters MUST be ignored. That
is, the values (alt-value) they appear in MUST be processed as if the
unknown parameter was not present.
New parameters can be defined in extension specifications (see
Section 7.3 for registration details).
Note that all field elements that allow "quoted-string" syntax MUST
be processed as per Section 3.2.6 of [RFC7230].
3.1. Caching Alt-Svc Header Field Values
When an alternative service is advertised using Alt-Svc, it is
considered fresh for 24 hours from generation of the message. This
can be modified with the 'ma' (max-age) parameter.
Syntax:
ma = delta-seconds; see [RFC7234], Section 1.2.1
The delta-seconds value indicates the number of seconds since the
response was generated the alternative service is considered fresh
for.
Alt-Svc: h2=":443"; ma=3600
See Section 4.2.3 of [RFC7234] for details of determining response
age.
Nottingham, et al. Expires September 2, 2016 [Page 11]
Internet-Draft HTTP Alternative Services March 2016
For example, a response:
HTTP/1.1 200 OK
Content-Type: text/html
Cache-Control: max-age=600
Age: 30
Alt-Svc: h2=":8000"; ma=60
indicates that an alternative service is available and usable for the
next 60 seconds. However, the response has already been cached for
30 seconds (as per the Age header field value), so therefore the
alternative service is only fresh for the 30 seconds from when this
response was received, minus estimated transit time.
Note that the freshness lifetime for HTTP caching (here, 600 seconds)
does not affect caching of Alt-Svc values.
When an Alt-Svc response header field is received from an origin, its
value invalidates and replaces all cached alternative services for
that origin.
By default, cached alternative services will be cleared when the
client detects a network change. Alternative services that are
intended to be longer-lived (such as those that are not specific to
the client access network) can carry the "persist" parameter with a
value "1" as a hint that the service is potentially useful beyond a
network configuration change.
Syntax:
persist = "1"
For example:
Alt-Svc: h2=":443"; ma=2592000; persist=1
This specification only defines a single value for "persist".
Clients MUST ignore "persist" parameters with values other than "1".
See Section 2.2 for general requirements on caching alternative
services.
4. The ALTSVC HTTP/2 Frame
The ALTSVC HTTP/2 frame ([RFC7540], Section 4) advertises the
availability of an alternative service to an HTTP/2 client.
The ALTSVC frame is a non-critical extension to HTTP/2. Endpoints
Nottingham, et al. Expires September 2, 2016 [Page 12]
Internet-Draft HTTP Alternative Services March 2016
that do not support this frame will ignore it (as per the
extensibility rules defined in Section 4.1 of [RFC7540]).
An ALTSVC frame from a server to a client on a stream other than
stream 0 indicates that the conveyed alternative service is
associated with the origin of that stream.
An ALTSVC frame from a server to a client on stream 0 indicates that
the conveyed alternative service is associated with the origin
contained in the Origin field of the frame. An association with an
origin that the client does not consider authoritative for the
current connection MUST be ignored.
The ALTSVC frame type is 0xa (decimal 10).
+-------------------------------+-------------------------------+
| Origin-Len (16) | Origin? (*) ...
+-------------------------------+-------------------------------+
| Alt-Svc-Field-Value (*) ...
+---------------------------------------------------------------+
ALTSVC Frame Payload
The ALTSVC frame contains the following fields:
Origin-Len: An unsigned, 16-bit integer indicating the length, in
octets, of the Origin field.
Origin: An OPTIONAL sequence of characters containing the ASCII
serialization of an origin ([RFC6454], Section 6.2) that the
alternative service is applicable to.
Alt-Svc-Field-Value: A sequence of octets (length determined by
subtracting the length of all preceding fields from the frame
length) containing a value identical to the Alt-Svc field value
defined in Section 3 (ABNF production "Alt-Svc").
The ALTSVC frame does not define any flags.
The ALTSVC frame is intended for receipt by clients. A device acting
as a server MUST ignore it.
An ALTSVC frame on stream 0 with empty (length 0) "Origin"
information is invalid and MUST be ignored. An ALTSVC frame on a
stream other than stream 0 containing non-empty "Origin" information
is invalid and MUST be ignored.
The ALTSVC frame is processed hop-by-hop. An intermediary MUST NOT
Nottingham, et al. Expires September 2, 2016 [Page 13]
Internet-Draft HTTP Alternative Services March 2016
",
"typ": "gnap-binding+jwsd",
"created": 1618884475
}
The request body, used as the JWS Payload, is the following JSON
object:
Richer & Imbault Expires 27 April 2023 [Page 116]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
NOTE: '\' line wrapping per RFC 8792
{
"access_token": {
"access": [
"dolphin-metadata"
]
},
"interact": {
"start": ["redirect"],
"finish": {
"method": "redirect",
"uri": "https://client.foo/callback",
"nonce": "VJLO6A4CAYLBXHTR0KRO"
}
},
"client": {
"key": {
"proof": "jws",
"jwk": {
"kid": "gnap-rsa",
"kty": "RSA",
"e": "AQAB",
"alg": "RS256",
"n": "hYOJ-XOKISdMMShn_G4W9m20mT0VWtQBsmBBkI2cmRt4Ai8Bf\
YdHsFzAtYKOjpBR1RpKpJmVKxIGNy0g6Z3ad2XYsh8KowlyVy8IkZ8NMwSrcUIBZG\
YXjHpwjzvfGvXH_5KJlnR3_uRUp4Z4Ujk2bCaKegDn11V2vxE41hqaPUnhRZxe0jR\
ETddzsE3mu1SK8dTCROjwUl14mUNo8iTrTm4n0qDadz8BkPo-uv4BC0bunS0K3bA_\
3UgVp7zBlQFoFnLTO2uWp_muLEWGl67gBq9MO3brKXfGhi3kOzywzwPTuq-cVQDyE\
N7aL0SxCb3Hc4IdqDaMg8qHUyObpPitDQ"
}
}
"display": {
"name": "My Client Display Name",
"uri": "https://client.foo/"
},
},
"subject": {
"formats": ["iss_sub", "opaque"]
}
}
This leads to the following full HTTP request message:
Richer & Imbault Expires 27 April 2023 [Page 117]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
NOTE: '\' line wrapping per RFC 8792
POST /gnap HTTP/1.1
Host: server.example.com
Content-Type: application/jose
Content-Length: 1047
eyJhbGciOiJSUzI1NiIsImNyZWF0ZWQiOjE2MTg4ODQ0NzUsImh0bSI6IlBPU1QiLCJ\
raWQiOiJnbmFwLXJzYSIsInR5cCI6ImduYXAtYmluZGluZytqd3NkIiwidXJpIjoiaH\
R0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20vZ25hcCJ9.CnsKICAgICJhY2Nlc3NfdG9r\
ZW4iOiB7CiAgICAgICAgImFjY2VzcyI6IFsKICAgICAgICAgICAgImRvbHBoaW4tbWV\
0YWRhdGEiCiAgICAgICAgXQogICAgfSwKICAgICJpbnRlcmFjdCI6IHsKICAgICAgIC\
Aic3RhcnQiOiBbInJlZGlyZWN0Il0sCiAgICAgICAgImZpbmlzaCI6IHsKICAgICAgI\
CAgICAgIm1ldGhvZCI6ICJyZWRpcmVjdCIsCiAgICAgICAgICAgICJ1cmkiOiAiaHR0\
cHM6Ly9jbGllbnQuZm9vL2NhbGxiYWNrIiwKICAgICAgICAgICAgIm5vbmNlIjogIlZ\
KTE82QTRDQVlMQlhIVFIwS1JPIgogICAgICAgIH0KICAgIH0sCiAgICAiY2xpZW50Ij\
ogewogICAgICAicHJvb2YiOiAiandzIiwKICAgICAgImtleSI6IHsKICAgICAgICAia\
ndrIjogewogICAgICAgICAgICAia2lkIjogImduYXAtcnNhIiwKICAgICAgICAgICAg\
Imt0eSI6ICJSU0EiLAogICAgICAgICAgICAiZSI6ICJBUUFCIiwKICAgICAgICAgICA\
gImFsZyI6ICJSUzI1NiIsCiAgICAgICAgICAgICJuIjogImhZT0otWE9LSVNkTU1TaG\
5fRzRXOW0yMG1UMFZXdFFCc21CQmtJMmNtUnQ0QWk4QmZZZEhzRnpBdFlLT2pwQlIxU\
nBLcEptVkt4SUdOeTBnNlozYWQyWFlzaDhLb3dseVZ5OElrWjhOTXdTcmNVSUJaR1lY\
akhwd2p6dmZHdlhIXzVLSmxuUjNfdVJVcDRaNFVqazJiQ2FLZWdEbjExVjJ2eEU0MWh\
xYVBVbmhSWnhlMGpSRVRkZHpzRTNtdTFTSzhkVENST2p3VWwxNG1VTm84aVRyVG00bj\
BxRGFkejhCa1BvLXV2NEJDMGJ1blMwSzNiQV8zVWdWcDd6QmxRRm9GbkxUTzJ1V3Bfb\
XVMRVdHbDY3Z0JxOU1PM2JyS1hmR2hpM2tPenl3endQVHVxLWNWUUR5RU43YUwwU3hD\
YjNIYzRJZHFEYU1nOHFIVXlPYnBQaXREUSIKICAgICAgICB9CiAgICAgIH0KICAgICA\
gImRpc3BsYXkiOiB7CiAgICAgICAgIm5hbWUiOiAiTXkgQ2xpZW50IERpc3BsYXkgTm\
FtZSIsCiAgICAgICAgInVyaSI6ICJodHRwczovL2NsaWVudC5mb28vIgogICAgICB9L\
AogICAgfSwKICAgICJzdWJqZWN0IjogewogICAgICAgICJmb3JtYXRzIjogWyJpc3Nf\
c3ViIiwgIm9wYXF1ZSJdCiAgICB9Cn0K.MwNoVMQp5hVxI0mCs9LlOUdFtkDXaA1_eT\
vOXq7DOGrtDKH7q4vP2xUq3fH2jRAZqnobo0WdPP3eM3NH5QUjW8pa6_QpwdIWkK7r-\
u_52puE0lPBp7J4U2w4l9gIbg8iknsmWmXeY5F6wiGT8ptfuEYGgmloAJd9LIeNvD3U\
LW2h2dz1Pn2eDnbyvgB0Ugae0BoZB4f69fKWj8Z9wvTIjk1LZJN1PcL7_zT8Lrlic9a\
PyzT7Q9ovkd1s-4whE7TrnGUzFc5mgWUn_gsOpsP5mIIljoEEv-FqOW2RyNYulOZl0Q\
8EnnDHV_vPzrHlUarbGg4YffgtwkQhdK72-JOxYQ
When the verifier receives an attached JWS request, it MUST parse and
validate the JWS object. The signature MUST be validated against the
expected key of the signer. All required fields MUST be present and
their values MUST be valid. If the HTTP message request contains a
body, the verifier MUST decode the payload of the JWS object and
treat this as the HTTP message body.
Note that this proof method depends on a specific cryptographic
algorithm, SHA-256, in two ways: the ath hash algorithm is hardcoded,
and computing the payload of the detached/attached signature also
uses a hardcoded hash. A future version of this document may address
Richer & Imbault Expires 27 April 2023 [Page 118]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
crypto-agility for both these uses by replacing ath with a new header
that upgrades the algorithm, and possibly defining a new header that
indicates the HTTP content's hash method.
7.3.4.1. Key Rotation using Attached JWS
When rotating a key using Attached JWS, the message, which includes
the new public key value or reference, is first signed with the old
key using a JWS object with typ header value "gnap-binding-
rotation+jwsd". The value of the JWS object is then taken as the
payload of a new JWS object, to be signed by the new key.
8. Resource Access Rights
GNAP provides a rich structure for describing the protected resources
hosted by RSs and accessed by client software. This structure is
used when the client instance requests an access token (Section 2.1)
and when an access token is returned (Section 3.2).
The root of this structure is a JSON array. The elements of the JSON
array represent rights of access that are associated with the the
access token. The resulting access is the union of all elements
within the array.
The access associated with the access token is described using
objects that each contain multiple dimensions of access. Each object
contains a REQUIRED type property that determines the type of API
that the token is used for.
type (string): The type of resource request as a string. This field
MAY define which other fields are allowed in the request object.
REQUIRED.
The value of the type field is under the control of the AS. This
field MUST be compared using an exact byte match of the string value
against known types by the AS. The AS MUST ensure that there is no
collision between different authorization data types that it
supports. The AS MUST NOT do any collation or normalization of data
types during comparison. It is RECOMMENDED that designers of
general-purpose APIs use a URI for this field to avoid collisions
between multiple API types protected by a single AS.
While it is expected that many APIs will have their own properties, a
set of common properties are defined here. Specific API
implementations SHOULD NOT re-use these fields with different
semantics or syntax. The available values for these properties are
determined by the API being protected at the RS. All values are
OPTIONAL at the discretion of the API definition.
Richer & Imbault Expires 27 April 2023 [Page 119]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
actions (array of strings): The types of actions the client instance
will take at the RS as an array of strings. For example, a client
instance asking for a combination of "read" and "write" access.
locations (array of strings): The location of the RS as an array of
strings. These strings are typically URIs identifying the
location of the RS.
datatypes (array of strings): The kinds of data available to the
client instance at the RS's API as an array of strings. For
example, a client instance asking for access to raw "image" data
and "metadata" at a photograph API.
identifier (string): A string identifier indicating a specific
resource at the RS. For example, a patient identifier for a
medical API or a bank account number for a financial API.
privileges (array of strings): The types or levels of privilege
being requested at the resource. For example, a client instance
asking for administrative level access, or access when the
resource owner is no longer online.
The following non-normative example is describing three kinds of
access (read, write, delete) to each of two different locations and
two different data types (metadata, images) for a single access token
using the fictitious photo-api type definition.
"access": [
{
"type": "photo-api",
"actions": [
"read",
"write",
"delete"
],
"locations": [
"https://server.example.net/",
"https://resource.local/other"
],
"datatypes": [
"metadata",
"images"
]
}
]
Richer & Imbault Expires 27 April 2023 [Page 120]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
The access requested for a given object when using these fields is
the cross-product of all fields of the object. That is to say, the
object represents a request for all actions listed to be used at all
locations listed for all possible datatypes listed within the object.
Assuming the request above was granted, the client instance could
assume that it would be able to do a read action against the images
on the first server as well as a delete action on the metadata of the
second server, or any other combination of these fields, using the
same access token.
To request a different combination of access, such as requesting one
of the possible actions against one of the possible locations and a
different choice of possible actions against a different one of the
possible locations, the client instance can include multiple separate
objects in the resources array. The following non-normative example
uses the same fictitious photo-api type definition to request a
single access token with more specifically targeted access rights by
using two discrete objects within the request.
"access": [
{
"type": "photo-api",
"actions": [
"read"
],
"locations": [
"https://server.example.net/"
],
"datatypes": [
"images"
]
},
{
"type": "photo-api",
"actions": [
"write",
"delete"
],
"locations": [
"https://resource.local/other"
],
"datatypes": [
"metadata"
]
}
]
Richer & Imbault Expires 27 April 2023 [Page 121]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
The access requested here is for read access to images on one server
while simultaneously requesting write and delete access for metadata
on a different server, but importantly without requesting write or
delete access to images on the first server.
It is anticipated that API designers will use a combination of common
fields defined in this specification as well as fields specific to
the API itself. The following non-normative example shows the use of
both common and API-specific fields as part of two different
fictitious API type values. The first access request includes the
actions, locations, and datatypes fields specified here as well as
the API-specific geolocation field. The second access request
includes the actions and identifier fields specified here as well as
the API-specific currency field.
"access": [
{
"type": "photo-api",
"actions": [
"read",
"write"
],
"locations": [
"https://server.example.net/",
"https://resource.local/other"
],
"datatypes": [
"metadata",
"images"
],
"geolocation": [
{ lat: -32.364, lng: 153.207 },
{ lat: -35.364, lng: 158.207 }
]
},
{
"type": "financial-transaction",
"actions": [
"withdraw"
],
"identifier": "account-14-32-32-3",
"currency": "USD"
}
]
If this request is approved, the resulting access token
(Section 3.2.1)'s access rights will be the union of the requested
types of access for each of the two APIs, just as above.
Richer & Imbault Expires 27 April 2023 [Page 122]forward ALTSVC frames, though it can use the information contained in
ALTSVC frames in forming new ALTSVC frames to send to its own
clients.
Receiving an ALTSVC frame is semantically equivalent to receiving an
Alt-Svc header field. As a result, the ALTSVC frame causes
alternative services for the corresponding origin to be replaced.
Note that it would be unwise to mix the use of Alt-Svc header fields
with the use of ALTSVC frames, as the sequence of receipt might be
hard to predict.
5. The Alt-Used HTTP Header Field
The Alt-Used header field is used in requests to indicate the
identity of the alternative service in use, just as the Host header
field (Section 5.4 of [RFC7230]) identifies the host and port of the
origin.
Alt-Used = uri-host [ ":" port ]
Alt-Used is intended to allow alternative services to detect loops,
differentiate traffic for purposes of load balancing, and generally
to ensure that it is possible to identify the intended destination of
traffic, since introducing this information after a protocol is in
use has proven to be problematic.
When using an alternative service, clients SHOULD include an Alt-Used
header field in all requests.
For example:
GET /thing HTTP/1.1
Host: origin.example.com
Alt-Used: alternate.example.net
6. The 421 Misdirected Request HTTP Status Code
The 421 (Misdirected Request) status code is defined in Section 9.1.2
of [RFC7540] to indicate that the current server instance is not
authoritative for the requested resource. This can be used to
indicate that an alternative service is not authoritative; see
Section 2).
Clients receiving 421 (Misdirected Request) from an alternative
service MUST remove the corresponding entry from its alternative
service cache (see Section 2.2) for that origin. Regardless of the
idempotency of the request method, they MAY retry the request, either
at another alternative server, or at the origin.
Nottingham, et al. Expires September 2, 2016 [Page 14]
Internet-Draft HTTP Alternative Services March 2016
An Alt-Svc header field in a 421 (Misdirected Request) response MUST
be ignored.
7. IANA Considerations
7.1. Header Field Registrations
HTTP header fields are registered within the "Message Headers"
registry maintained at
<https://www.iana.org/assignments/message-headers/>.
This document defines the following HTTP header fields, so their
associated registry entries shall be added according to the permanent
registrations below (see [BCP90]):
+-------------------+----------+----------+-----------+
| Header Field Name | Protocol | Status | Reference |
+-------------------+----------+----------+-----------+
| Alt-Svc | http | standard | Section 3 |
| Alt-Used | http | standard | Section 5 |
+-------------------+----------+----------+-----------+
The change controller is: "IETF (iesg@ietf.org) - Internet
Engineering Task Force".
7.2. The ALTSVC HTTP/2 Frame Type
This document registers the ALTSVC frame type in the HTTP/2 Frame
Types registry ([RFC7540], Section 11.2).
Frame Type: ALTSVC
Code: 0xa
Specification: Section 4 of this document
7.3. Alt-Svc Parameter Registry
The HTTP Alt-Svc Parameter Registry defines the name space for
parameters. It will be created and maintained at (the suggested URI)
<http://www.iana.org/assignments/http-alt-svc-parameters>.
7.3.1. Procedure
A registration MUST include the following fields:
o Parameter Name
Nottingham, et al. Expires September 2, 2016 [Page 15]
Internet-Draft HTTP Alternative Services March 2016
o Pointer to specification text
Values to be added to this name space require Expert Review (see
[RFC5226], Section 4.1).
7.3.2. Registrations
The HTTP Alt-Svc Parameter Registry is to be populated with the
registrations below:
+-------------------+-------------+
| Alt-Svc Parameter | Reference |
+-------------------+-------------+
| ma | Section 3.1 |
| persist | Section 3.1 |
+-------------------+-------------+
8. Internationalization Considerations
An internationalized domain name that appears in either the header
field (Section 3) or the HTTP/2 frame (Section 4) MUST be expressed
using A-labels ([RFC5890], Section 2.3.2.1).
9. Security Considerations
9.1. Changing Ports
Using an alternative service implies accessing an origin's resources
on an alternative port, at a minimum. An attacker that can inject
alternative services and listen at the advertised port is therefore
able to hijack an origin. On certain servers, it is normal for users
to be able to control some personal pages available on a shared port,
and also to accept to requests on less-privileged ports.
For example, an attacker that can add HTTP response header fields to
some pages can redirect traffic for an entire origin to a different
port on the same host using the Alt-Svc header field; if that port is
under the attacker's control, they can thus masquerade as the HTTP
server.
This risk is mitigated by the requirements in Section 2.1.
On servers, this risk can also be reduced by restricting the ability
to advertise alternative services, and restricting who can open a
port for listening on that host.
Nottingham, et al. Expires September 2, 2016 [Page 16]
Internet-Draft HTTP Alternative Services March 2016
9.2. Changing Hosts
When the host is changed due to the use of an alternative service, it
presents an opportunity for attackers to hijack communication to an
origin.
For example, if an attacker can convince a user agent to send all
traffic for "innocent.example.org" to "evil.example.com" by
successfully associating it as an alternative service, they can
masquerade as that origin. This can be done locally (see mitigations
in Section 9.1) or remotely (e.g., by an intermediary as a man-in-
the-middle attack).
This is the reason for the requirement in Section 2.1 that clients
have reasonable assurances that the alternative service is under
control of and valid for the whole origin; presenting a certificate
for the origin proves that the alternative service is authorized to
serve traffic for the origin.
Note that this assurance is only as strong as the method used to
authenticate the alternative service. In particular, when TLS
authentication is used to do so, there are well-known exploits to
make an attacker's certificate appear as legitimate.
Alternative services could be used to persist such an attack. For
example, an intermediary could man-in-the-middle TLS-protected
communication to a target, and then direct all traffic to an
alternative service with a large freshness lifetime, so that the user
agent still directs traffic to the attacker even when not using the
intermediary.
Implementations MUST perform any certificate-pinning validation (such
as [RFC7469]) on alternative services just as they would on direct
connections to the origin. Implementations might also choose to add
other requirements around which certificates are acceptable for
alternative services.
9.3. Changing Protocols
When the ALPN protocol is changed due to the use of an alternative
service, the security properties of the new connection to the origin
can be different from that of the "normal" connection to the origin,
because the protocol identifier itself implies this.
For example, if an "https://" URI has a protocol advertised that does
not use some form of end-to-end encryption (most likely, TLS), it
violates the expectations for security that the URI scheme implies.
Therefore, clients cannot blindly use alternative services, but
Nottingham, et al. Expires September 2, 2016 [Page 17]
Internet-Draft HTTP Alternative Services March 2016
instead evaluate the option(s) presented to assure that security
requirements and expectations of specifications, implementations and
end users are met.
9.4. Tracking Clients Using Alternative Services
Choosing an alternative service implies connecting to a new, server-
supplied host name. By using unique names, servers could conceivably
track client requests. Such tracking could follow users across
multiple networks, when the "persist" flag is used.
Clients that wish to prevent requests from being correlated can
decide not to use alternative services for multiple requests that
would not otherwise be allowed to be correlated.
In a user agent, any alternative service information MUST be removed
when origin-specific data is cleared (typically, when cookies
[RFC6265] are cleared).
9.5. Confusion Regarding Request Scheme
Some server-side HTTP applications make assumptions about security
based upon connection context; for example, equating being served
upon port 443 with the use of an "https://" URI and the various
security properties that implies.
This affects not only the security properties of the connection
itself, but also the state of the client at the other end of it; for
example, a Web browser treats "https://" URIs differently than
"http://" URIs in many ways, not just for purposes of protocol
handling.
Since one of the uses of Alternative Services is to allow a
connection to be migrated to a different protocol and port, these
applications can become confused about the security properties of a
given connection, sending information (for example, cookies and
content) that is intended for a secure context (such as an "https://"
URI) to a client that is not treating it as one.
This risk can be mitigated in servers by using the URI scheme
explicitly carried by the protocol (such as ":scheme" in HTTP/2 or
the "absolute form" of the request target in HTTP/1.1) as an
indication of security context, instead of other connection
properties ([RFC7540], Section 8.1.2.3 and [RFC7230], Section 5.3.2).
When the protocol does not explicitly carry the scheme (as is usually
the case for HTTP/1.1 over TLS), servers can mitigate this risk by
either assuming that all requests have an insecure context, or by
Nottingham, et al. Expires September 2, 2016 [Page 18]
Internet-Draft HTTP Alternative Services March 2016
refraining from advertising alternative services for insecure
schemes, for example HTTP.
10. References
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/
RFC2818, May 2000,
<http://www.rfc-editor.org/info/rfc2818>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
DOI 10.17487/RFC5226, May 2008,
Internet-Draft Grant Negotiation and Authorization Prot October 2022
8.1. Requesting Resources By Reference
Instead of sending an object describing the requested resource
(Section 8), access rights MAY be communicated as a string known to
the AS representing the access being requested. Just like access
rights communicated as an object, access rights communicated as
reference strings indicate a specific access at a protected resource.
In the following non-normative example, three distinct resource
access rights are being requested.
"access": [
"read", "dolphin-metadata", "some other thing"
]
This value is opaque to the client instance and MAY be any valid JSON
string, and therefore could include spaces, unicode characters, and
properly escaped string sequences. However, in some situations the
value is intended to be seen and understood by the client software's
developer. In such cases, the API designer choosing any such human-
readable strings SHOULD take steps to ensure the string values are
not easily confused by a developer, such as by limiting the strings
to easily disambiguated characters.
In order to facilitate the use of both object and reference strings
to access the same kind of APIs, the API designer can define a clear
mapping between these forms. One possible approach for choosing
reference string values is to use the same value as the type
parameter from the fully-specified object, with the API defining a
set of default behaviors in this case. For example, an API
definition could declare the following string:
"access": [
"photo-api"
]
As being equivalent to the following fully-defined object:
"access": [
{
"type": "photo-api",
"actions": [ "read", "write", "delete" ],
"datatypes": [ "metadata", "image" ]
}
]
The exact mechanisms for relating reference strings is up to the API
designer. These are enforced by the AS, and the details are out of
scope for this specification.
Richer & Imbault Expires 27 April 2023 [Page 123]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
This functionality is similar in practice to OAuth 2.0's scope
parameter [RFC6749], where a single string represents the set of
access rights requested by the client instance. As such, the
reference string could contain any valid OAuth 2.0 scope value as in
Appendix C.5. Note that the reference string here is not bound to
the same character restrictions as in OAuth 2.0's scope definition.
A single access array MAY include both object-type and string-type
resource items. In this non-normative example, the client instance
is requesting access to a photo-api and financial-transaction API
type as well as the reference values of read, dolphin-metadata, and
some other thing.
"access": [
{
"type": "photo-api",
"actions": [
"read",
"write",
"delete"
],
"locations": [
"https://server.example.net/",
"https://resource.local/other"
],
"datatypes": [
"metadata",
"images"
]
},
"read",
"dolphin-metadata",
{
"type": "financial-transaction",
"actions": [
"withdraw"
],
"identifier": "account-14-32-32-3",
"currency": "USD"
},
"some other thing"
]
The requested access is the union of all elements of the array,
including both objects and reference strings.
Richer & Imbault Expires 27 April 2023 [Page 124]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
9. Discovery
By design, the protocol minimizes the need for any pre-flight
discovery. To begin a request, the client instance only needs to
know the endpoint of the AS and which keys it will use to sign the
request. Everything else can be negotiated dynamically in the course
of the protocol.
However, the AS can have limits on its allowed functionality. If the
client instance wants to optimize its calls to the AS before making a
request, it MAY send an HTTP OPTIONS request to the grant request
endpoint to retrieve the server's discovery information. The AS MUST
respond with a JSON document with Content-Type application/json
containing a single object with the following information:
grant_request_endpoint (string): The location of the AS's grant
request endpoint. The location MUST be an absolute URL [RFC3986]
with a scheme component (which MUST be "https"), a host component,
and optionally, port, path and query components and no fragment
components. This URL MUST match the URL the client instance used
to make the discovery request. REQUIRED.
interaction_start_modes_supported (array of strings): A list of the
AS's interaction start methods. The values of this list
correspond to the possible values for the interaction start
section (Section 2.5.1) of the request and MUST be values from the
Interaction Start Modes Registry (Section 11.7). OPTIONAL.
interaction_finish_methods_supported (array of strings): A list of
the AS's interaction finish methods. The values of this list
correspond to the possible values for the method element of the
interaction finish section (Section 2.5.2) of the request and MUST
be values from the Interaction Finish Methods Registry
(Section 11.8). OPTIONAL.
key_proofs_supported (array of strings): A list of the AS's
supported key proofing mechanisms. The values of this list
correspond to possible values of the proof field of the key
section (Section 7.1) of the request and MUST be values from the
Key Proofing Methods Registry (Section 11.14). OPTIONAL.
sub_id_formats_supported (array of strings): A list of the AS's
supported subject identifier formats. The values of this list
correspond to possible values of the subject identifier section
(Section 2.2) of the request and MUST be values from the Subject
Identifier Formats Registry established by
[I-D.ietf-secevent-subject-identifiers]. OPTIONAL.
Richer & Imbault Expires 27 April 2023 [Page 125]
Internet-Draft Grant Negotiation and Authorization Prot October 2022<http://www.rfc-editor.org/info/rfc5226>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/
RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>.
[RFC5890] Klensin, J., "Internationalized Domain Names for
Applications (IDNA): Definitions and Document Framework",
RFC 5890, DOI 10.17487/RFC5890, August 2010,
<http://www.rfc-editor.org/info/rfc5890>.
[RFC6066] Eastlake, D., "Transport Layer Security (TLS) Extensions:
Extension Definitions", RFC 6066, DOI 10.17487/RFC6066,
January 2011, <http://www.rfc-editor.org/info/rfc6066>.
[RFC6454] Barth, A., "The Web Origin Concept", RFC 6454,
DOI 10.17487/RFC6454, December 2011,
<http://www.rfc-editor.org/info/rfc6454>.
[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Message Syntax and Routing",
RFC 7230, DOI 10.17487/RFC7230, June 2014,
<http://www.rfc-editor.org/info/rfc7230>.
Nottingham, et al. Expires September 2, 2016 [Page 19]
Internet-Draft HTTP Alternative Services March 2016
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014,
<http://www.rfc-editor.org/info/rfc7234>.
[RFC7301] Friedl, S., Popov, A., Langley, A., and S. Emile,
"Transport Layer Security (TLS) Application-Layer Protocol
Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301,
July 2014, <http://www.rfc-editor.org/info/rfc7301>.
[RFC7405] Kyzivat, P., "Case-Sensitive String Support in ABNF",
RFC 7405, DOI 10.17487/RFC7405, December 2014,
<http://www.rfc-editor.org/info/rfc7405>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol version 2", RFC 7540, DOI 10.17487/
RFC7540, May 2015,
<http://www.rfc-editor.org/info/rfc7540>.
10.2. Informative References
[BCP90] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", BCP 90, RFC 3864,
September 2004, <http://www.rfc-editor.org/info/bcp90>.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/
RFC5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011,
<http://www.rfc-editor.org/info/rfc6265>.
[RFC7469] Evans, C., Palmer, C., and R. Sleevi, "Public Key Pinning
Extension for HTTP", RFC 7469, DOI 10.17487/RFC7469,
April 2015, <http://www.rfc-editor.org/info/rfc7469>.
Appendix A. Change Log (to be removed by RFC Editor before publication)
A.1. Since draft-nottingham-httpbis-alt-svc-05
This is the first version after adoption of
draft-nottingham-httpbis-alt-svc-05 as Working Group work item. It
only contains editorial changes.
Nottingham, et al. Expires September 2, 2016 [Page 20]
Internet-Draft HTTP Alternative Services March 2016
A.2. Since draft-ietf-httpbis-alt-svc-00
Selected 421 as proposed status code for "Not Authoritative".
Changed header field syntax to use percent-encoding of ALPN protocol
names (<https://github.com/http2/http2-spec/issues/446>).
A.3. Since draft-ietf-httpbis-alt-svc-01
Updated HTTP/1.1 references.
Renamed "Service" to "Alt-Svc-Used" and reduced information to a flag
to address fingerprinting concerns
(<https://github.com/http2/http2-spec/issues/502>).
Note that ALTSVC frame is preferred to Alt-Svc header field
(<https://github.com/http2/http2-spec/pull/503>).
Incorporate ALTSRV frame
(<https://github.com/http2/http2-spec/pull/507>).
Moved definition of status code 421 to HTTP/2.
Partly resolved <https://github.com/httpwg/http-extensions/issues/5>.
A.4. Since draft-ietf-httpbis-alt-svc-02
Updated ALPN reference.
Resolved <https://github.com/httpwg/http-extensions/issues/2>.
A.5. Since draft-ietf-httpbis-alt-svc-03
Renamed "Alt-Svc-Used" to "Alt-Used"
(<https://github.com/httpwg/http-extensions/issues/17>).
Clarify ALTSVC Origin information requirements
(<https://github.com/httpwg/http-extensions/issues/19>).
Remove/tune language with respect to tracking risks (see
<https://github.com/httpwg/http-extensions/issues/34>).
A.6. Since draft-ietf-httpbis-alt-svc-04
Mention tracking by alt-svc host name in Security Considerations
(<https://github.com/httpwg/http-extensions/issues/36>).
"421 (Not Authoritative)" -> "421 (Misdirected Request)".
Nottingham, et al. Expires September 2, 2016 [Page 21]
Internet-Draft HTTP Alternative Services March 2016
Allow the frame to carry multiple indicator and use the same payload
formats for both
(<https://github.com/httpwg/http-extensions/issues/37>).
A.7. Since draft-ietf-httpbis-alt-svc-05
Go back to specifying the origin in Alt-Used, but make it a "SHOULD"
(<https://github.com/httpwg/http-extensions/issues/34>).
Restore Origin field in ALT-SVC frame
(<https://github.com/httpwg/http-extensions/issues/38>).
A.8. Since draft-ietf-httpbis-alt-svc-06
Disallow use of alternative services when the protocol might not
carry the scheme
(<https://github.com/httpwg/http-extensions/issues/12>).
Align opp-sec and alt-svc
(<https://github.com/httpwg/http-extensions/issues/33>).
alt svc frame on pushed (even and non-0) frame
(<https://github.com/httpwg/http-extensions/issues/44>).
"browser" -> "user agent"
(<https://github.com/httpwg/http-extensions/pull/61>).
ABNF for "parameter"
(<https://github.com/httpwg/http-extensions/issues/65>).
Updated HTTP/2 reference.
A.9. Since draft-ietf-httpbis-alt-svc-07
Alt-Svc alternative cache invalidation
(<https://github.com/httpwg/http-extensions/issues/16>).
Unexpected Alt-Svc frames
(<https://github.com/httpwg/http-extensions/issues/18>).
Associating Alt-Svc header with an origin
(<https://github.com/httpwg/http-extensions/issues/21>).
ALPN identifiers in Alt-Svc
(<https://github.com/httpwg/http-extensions/issues/43>).
Number of alternate services used
(<https://github.com/httpwg/http-extensions/issues/58>).
Nottingham, et al. Expires September 2, 2016 [Page 22]
Internet-Draft HTTP Alternative Services March 2016
Proxy and .pac interaction
(<https://github.com/httpwg/http-extensions/issues/62>).
Need to define extensibility for alt-svc parameters
(<https://github.com/httpwg/http-extensions/issues/69>).
Persistence of alternates across network changes
(<https://github.com/httpwg/http-extensions/issues/71>).
Alt-Svc header with 421 status
(<https://github.com/httpwg/http-extensions/issues/75>).
Incorporate several editorial improvements suggested by Mike Bishop
(<https://github.com/httpwg/http-extensions/pull/77>,
<https://github.com/httpwg/http-extensions/pull/78>).
Alt-Svc response header field in HTTP/2 frame
(<https://github.com/httpwg/http-extensions/issues/87>).
A.10. Since draft-ietf-httpbis-alt-svc-08
Remove left over text about ext-params, applying to an earlier
version of Alt-Used (see
<https://github.com/httpwg/http-extensions/issues/34>).
Conflicts between Alt-Svc and ALPN
(<https://github.com/httpwg/http-extensions/issues/72>).
Elevation of privilege
(<https://github.com/httpwg/http-extensions/issues/73>).
Alternates of alternates
(<https://github.com/httpwg/http-extensions/issues/74
assertion_formats_supported (array of strings): A list of the AS's
supported assertion formats. The values of this list correspond
to possible values of the subject assertion section (Section 2.2)
of the request and MUST be values from the Assertion Formats
Registry (Section 11.4). OPTIONAL.
The information returned from this method is for optimization
purposes only. The AS MAY deny any request, or any portion of a
request, even if it lists a capability as supported. For example, a
given client instance can be registered with the mtls key proofing
mechanism, but the AS also returns other proofing methods from the
discovery document, then the AS will still deny a request from that
client instance using a different proofing mechanism.
Additional fields can be defined the Authorization Server Discovery
Fields Registry (Section 11.16).
9.1. RS-first Method of AS Discovery
If the client instance calls an RS without an access token, or with
an invalid access token, the RS SHOULD be explicit about the fact
that GNAP needs to be used to access the resource, by responding with
the WWW-Authenticate header field and a GNAP challenge.
In some situations, the client instance might want to know with which
specific AS it needs to negotiate for access to that RS. The RS MAY
additionally return the address of the GNAP endpoint in the as_uri
parameter, a referrer parameter to indicate which RS initiated the
discovery process, and an opaque access reference. The client
instance SHOULD then use both the referrer and access parameters in
its access token request. The referrer parameter MUST be the URI of
the RS, and the client instance MUST check its value to protect
itself. The opaque access reference MUST be sufficient for at least
the action the client instance was attempting to take at the RS and
MAY be more powerful.
The means for the RS to determine the value for the access reference
are out of scope of this specification, but some dynamic methods are
discussed in [I-D.ietf-gnap-resource-servers].
When receiving the following response from the RS:
NOTE: '\' line wrapping per RFC 8792
WWW-Authenticate: \
GNAP as_uri=https://as.example/tx\
;access=FWWIKYBQ6U56NL1\
;referrer=https://rs.example
Richer & Imbault Expires 27 April 2023 [Page 126]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
The client instance then makes a request to the as_uri as described
in Section 2, with the value of referrer passed as an HTTP Referer
header field and the access reference passed unchanged into the
access array in the access_token portion of the request. The client
instance MAY request additional resources and other information.
In this non-normative example, the client instance is requesting a
single access token using the opaque access reference FWWIKYBQ6U56NL1
received from the RS in addition to the dolphin-metadata that the
client instance has been configured with out of band.
POST /tx HTTP/1.1
Host: as.example
Referer: https://rs.example/resource
Content-Type: application/json
Signature-Input: sig1=...
Signature: sig1=...
Content-Digest: sha-256=...
{
"access_token": {
"access": [
"FWWIKYBQ6U56NL1",
"dolphin-metadata"
]
},
"client": "KHRS6X63AJ7C7C4AZ9AO"
}
The client instance includes the Referer header field as a way for
the AS to know that the process is initiated through a discovery
process at the RS.
If issued, the resulting access token would contain sufficient access
to be used at both referenced resources.
Security considerations, especially related to the potential of a
[compromised RS]{#security-compromised-rs} redirecting the requests
of an otherwise properly authenticated client, need to be carefully
considered when allowing such a discovery process. This risk can be
mitigated by an alternative pre-registration process so that the
client knows which AS protects which RS.
Richer & Imbault Expires 27 April 2023 [Page 127]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
9.2. Dynamic grant endpoint discovery
Additional methods of discovering the appropriate grant endpoint for
a given application are outside the scope of this specification.
This limitation is intentional, as many applications rely on static
configuration between the client instance and AS, as is common in
OAuth 2.0. However, the dynamic nature of GNAP makes it a prime
candidate for other extensions defining methods for discovery of the
appropriate AS grant endpoint at runtime. Advanced use cases could
define contextual methods for contextually providing this endpoint to
the client instance securely. Furthermore, GNAP's design
intentionally requires the client instance to only know the grant
endpoint and not additional parameters, since other functions and
values can be disclosed and negotiated during the grant process.
10. Acknowledgements
The editors would like to thank the feedback of the following
individuals for their reviews, implementations, and contributions:
Åke Axeland, Aaron Parecki, Adam Omar Oueidat, Andrii Deinega,
Annabelle Backman, Dick Hardt, Dmitri Zagidulin, Dmitry Barinov,
Fabien Imbault, Florian Helmschmidt, Francis Pouatcha, George
Fletcher, Haardik Haardik, Hamid Massaoud, Jacky Yuan, Joseph Heenan,
Justin Richer, Kathleen Moriarty, Mike Jones, Mike Varley, Nat
Sakimura, Takahiko Kawasaki, Takahiro Tsuchiya.
The editors would also like to thank the GNAP working group design
team of Kathleen Moriarty, Fabien Imbault, Dick Hardt, Mike Jones,
and Justin Richer, who incorporated elements from the XAuth and XYZ
proposals to create the first version of this document.
In addition, the editors would like to thank Aaron Parecki and Mike
Jones for insights into how to integrate identity and authentication
systems into the core protocol, and Justin Richer and Dick Hardt for
the use cases, diagrams, and insights provided in the XYZ and XAuth
proposals that have been incorporated here. The editors would like
to especially thank Mike Varley and the team at SecureKey for
feedback and development of early versions of the XYZ protocol that
fed into this standards work.
Finally, the editors want to acknowledge the immense contributions of
Aaron Parecki to the content of this document. We thank him for his
insight, input, and hard work, without which GNAP would not have
grown to what it is.
Richer & Imbault Expires 27 April 2023 [Page 128]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
11. IANA Considerations
IANA is requested to create XX registries for the Grant Negotiation
and Authorization Protocol and to populate those registries with
initial values as described in this section.
All use of value typing is based on [RFC8259] data types and MUST be
one of the following: number, object, string, boolean, or array.
When the type is array, the contents of the array MUST be specified,
as in "array of objects". If a parameter is available in different
types, each type SHOULD be registered separately.
General guidance for extension parameters is found in Appendix E.
11.1. Grant Request Parameters
This document defines a GNAP grant request, for which IANA is asked
to create and maintain a new registry titled "Grant Request
Parameters". Initial values for this registry are given in
Section 11.1.2. Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy [RFC8126] and shall follow the template presented in
Section 11.1.1.
Each grant request parameter's definition MUST specify the expected
behavior of the AS for each potential state of the grant request.
11.1.1. Registration Template
Name:
An identifier for the parameter.
Type:
The JSON type allowed for the value.
Specification document(s):
Reference to the document(s) that specify the value, preferably
including a URI that can be used to retrieve a copy of the
document(s). An indication of the relevant sections may also be
included but is not required.
Richer & Imbault Expires 27 April 2023 [Page 129]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
11.1.2. Initial Contents
+==============+==================+===========================+
| Name | Type | Specification document(s) |
+==============+==================+===========================+
| access_token | object | Section 2.1.1 of RFC nnnn |
+--------------+------------------+---------------------------+
| access_token | array of objects | Section 2.1.2 of RFC nnnn |
+--------------+------------------+---------------------------+
| subject | object | Section 2.2 of RFC nnnn |
+--------------+------------------+---------------------------+
| client | object | Section 2.3 of RFC nnnn |
+--------------+------------------+---------------------------+
| client | string | Section 2.3.1 of RFC nnnn |
+--------------+------------------+---------------------------+
| user | object | Section 2.4 of RFC nnnn |
+--------------+------------------+---------------------------+
| user | string | Section 2.4.1 of RFC nnnn |
+--------------+------------------+---------------------------+
| interact | object | Section 2.5 of RFC nnnn |
+--------------+------------------+---------------------------+
| interact_ref | string | Section 5.1 of RFC nnnn |
+--------------+------------------+---------------------------+
Table 1
11.2. Access Token Flags
This document defines a GNAP access token flags, for which IANA is
asked to create and maintain a new registry titled "Access Token
Flags". Initial values for this registry are given in
Section 11.2.2. Future assignments and modifications to existing
assignment are to be made through the Expert Review registration
policy [RFC8126] and shall follow the template presented in
Section 11.2.1.
Each flag MUST specify whether it can be requested by clients
instances or is only allowed in responses from the AS.
11.2.1. Registration Template
Name:
An identifier for the parameter.
Specification document(s):
Richer & Imbault Expires 27 April 2023 [Page 130]
Internet-Draft Grant Negotiation and Authorization Prot October 2022
Reference to the document(s) that specify the value, preferably
including a URI that can be used to retrieve a copy of the
document(s). An indication of the relevant sections may also be
included but is not required.
11.2.2. Initial Contents
+=========+=============================================+
| Name | Specification document(s) |
+=========+=============================================+
| bearer | Section 2.1.1 and Section 3.2.1 of RFC nnnn |
+---------+---------------------------------------------+
| durable | Section 3.2.1 of RFC nnnn |
+---------+---------------------------------------------+
Table 2
11.3. Subject Information Request Fields
This document defines a means to request subject information from the
AS to the client instance, for which IANA is asked to create and
maintain a new registry titled "Subject Information Request Fields&>).
Alt-Svc and Cert Pinning
(<https://github.com/httpwg/http-extensions/issues/76>).
Using alt-svc on localhost (no change to spec, see
<https://github.com/httpwg/http-extensions/issues/89>).
IANA procedure for alt-svc parameters
(<https://github.com/httpwg/http-extensions/issues/96>).
Alt-svc from https (1.1) to https (1.1)
(<https://github.com/httpwg/http-extensions/issues/91>).
Alt-svc vs the ability to convey the scheme inside the protocol
(<https://github.com/httpwg/http-extensions/issues/92>).
Nottingham, et al. Expires September 2, 2016 [Page 23]
Internet-Draft HTTP Alternative Services March 2016
Reconciling MAY/can vs. SHOULD
(<https://github.com/httpwg/http-extensions/issues/101>).
Typo in alt-svc caching example
(<https://github.com/httpwg/http-extensions/issues/117>).
A.11. Since draft-ietf-httpbis-alt-svc-09
Editorial improvements
(<https://github.com/httpwg/http-extensions/issues/118>,
<https://github.com/httpwg/http-extensions/issues/119>,
<https://github.com/httpwg/http-extensions/issues/120>,
<https://github.com/httpwg/http-extensions/issues/121>,
<https://github.com/httpwg/http-extensions/issues/122>,
<https://github.com/httpwg/http-extensions/issues/123>,
<https://github.com/httpwg/http-extensions/issues/125>,
<https://github.com/httpwg/http-extensions/issues/126>).
A.12. Since draft-ietf-httpbis-alt-svc-10
Editorial improvements
(<https://github.com/httpwg/http-extensions/issues/130>).
Use RFC 7405 ABNF extension
(<https://github.com/httpwg/http-extensions/issues/131>).
A.13. Since draft-ietf-httpbis-alt-svc-11
Security considerations wrt system ports
(<https://github.com/httpwg/http-extensions/issues/139>).
A.14. Since draft-ietf-httpbis-alt-svc-12
Editorial changes triggered by <https://lists.w3.org/Archives/Public/
ietf-http-wg/2016JanMar/0243.html>.
Reasonable Assurances and H2C
(<https://github.com/httpwg/http-extensions/issues/148>).
Appendix B. Acknowledgements
Thanks to Adam Langley, Bence Beky, Chris Lonvick, Eliot Lear, Erik
Nygren, Guy Podjarny, Herve Ruellan, Lucas Pardue, Martin Thomson,
Matthew Kerwin, Mike Bishop, Paul Hoffman, Richard Barnes, Richard
Bradbury, Stephen Farrell, Stephen Ludin, and Will Chan for their
feedback and suggestions.
The Alt-Svc header field was influenced by the design of the
Nottingham, et al. Expires September 2, 2016 [Page 24]
Internet-Draft HTTP Alternative Services March 2016
Alternate-Protocol header field in SPDY.
Authors' Addresses
Mark Nottingham
Akamai
EMail: mnot@mnot.net
URI: https://www.mnot.net/
Patrick McManus
Mozilla
EMail: mcmanus@ducksong.com
URI: https://mozillians.org/u/pmcmanus/
Julian F. Reschke
greenbytes GmbH
EMail: julian.reschke@greenbytes.de
URI: https://greenbytes.de/tech/webdav/
Nottingham, et al. Expires September 2, 2016 [Page 25]