Network Working Group J. Yasskin
Internet-Draft Google
Intended status: Standards Track June 13, 2018
Expires: December 15, 2018
Bundled HTTP Exchanges
draft-yasskin-wpack-bundled-exchanges-00
Abstract
Bundled exchanges provide a way to bundle up groups of HTTP
request+response pairs to transmit or store them together. They can
include multiple top-level resources with one identified as the
default by a manifest, provide random access to their component
exchanges, and efficiently store 8-bit resources.
Note to Readers
Discussion of this draft takes place on the ART area mailing list
(art@ietf.org), which is archived at
https://mailarchive.ietf.org/arch/search/?email_list=art [1].
The source code and issues list for this draft can be found in
https://github.com/WICG/webpackage [2].
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 https://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 December 15, 2018.
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved.
Yasskin Expires December 15, 2018 [Page 1]
Internet-Draft Bundled HTTP Exchanges June 2018
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Mode of specification . . . . . . . . . . . . . . . . . . 3
2. Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Stream attributes and operations . . . . . . . . . . . . 4
2.2. Load a bundle's metadata . . . . . . . . . . . . . . . . 4
2.2.1. Load a bundle's metadata from the end . . . . . . . . 5
2.3. Load a response from a bundle . . . . . . . . . . . . . . 5
3. Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Top-level structure . . . . . . . . . . . . . . . . . . . 5
3.2. Load a bundle's metadata . . . . . . . . . . . . . . . . 6
3.2.1. Parsing the index section . . . . . . . . . . . . . . 8
3.2.2. Parsing the manifest section . . . . . . . . . . . . 9
3.2.3. Parsing the critical section . . . . . . . . . . . . 10
3.2.4. The responses section . . . . . . . . . . . . . . . . 10
3.2.5. Starting from the end . . . . . . . . . . . . . . . . 10
3.3. Load a response from a bundle . . . . . . . . . . . . . . 11
3.4. Parsing CBOR items . . . . . . . . . . . . . . . . . . . 13
3.4.1. Parse a known-length item . . . . . . . . . . . . . . 13
3.4.2. Parsing variable-length data from a bytestring . . . 13
3.5. Interpreting CBOR HTTP headers . . . . . . . . . . . . . 14
4. Guidelines for bundle authors . . . . . . . . . . . . . . . . 15
5. Security Considerations . . . . . . . . . . . . . . . . . . . 15
6. IANA considerations . . . . . . . . . . . . . . . . . . . . . 16
6.1. Internet Media Type Registration . . . . . . . . . . . . 16
6.2. Web Bundle Section Name Registry . . . . . . . . . . . . 17
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.1. Normative References . . . . . . . . . . . . . . . . . . 17
7.2. Informative References . . . . . . . . . . . . . . . . . 19
7.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 19
Yasskin Expires December 15, 2018 [Page 2]
Internet-Draft Bundled HTTP Exchanges June 2018
1. Introduction
To satisfy the use cases in [I-D.yasskin-webpackage-use-cases], this
document proposes a new bundling format to group HTTP resources.
Several of the use cases require the resources to be signed: that's
provided by bundling signed exchanges
([I-D.yasskin-http-origin-signed-responses]) rather than natively in
this format.
1.1. Terminology
Exchange (noun) An HTTP request+response pair. This can either be a
request from a client and the matching response from a server or
the request in a PUSH_PROMISE and its matching response stream.
Defined by Section 8 of [RFC7540].
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
1.2. Mode of specification
This specification defines how conformant bundle parsers work. It
does not constrain how encoders produce a bundle: although there are
some guidelines in Section 4, encoders MAY produce any sequence of
bytes that a conformant parser would parse into the intended
semantics.
This specification uses the conventions and terminology defined in
the Infra Standard ([INFRA]).
2. Semantics
A bundle is logically a set of HTTP exchanges, with a URL identifying
the manifest(s) of the bundle itself.
While the order of the exchanges is not semantically meaningful, it
can significantly affect performance when the bundle is loaded from a
network stream.
A bundle is parsed from a stream of bytes, which is assumed to have
the attributes and operations described in Section 2.1.
Bundle parsers support two operations, Load a bundle's metadata
(Section 2.2) and Load a response from a bundle (Section 2.3) each of
which can return an error instead of their normal result.
Yasskin Expires December 15, 2018 [Page 3]
Internet-Draft Bundled HTTP Exchanges June 2018
A client is expected to load the metadata for a bundle as soon as it
start downloading it or otherwise discovers it. Then, when fetching
([FETCH]) a request, the cliend is expected to match it against the
requests in the metadata, and if one matches, load that request's
response.
2.1. Stream attributes and operations
o A sequence of *available bytes*. As the stream delivers bytes,
these are appended to the available bytes.
o An *EOF* flag that's true if the available bytes include the
entire stream.
o A *current offset* within the available bytes.
o A *seek to offset N* operation to set the current offset to N
bytes past the beginning of the available bytes. A seek past the
end of the available bytes blocks until N bytes are available. If
the stream ends before enough bytes are received, either due to a
network error or because the stream has a finite length, the seek
fails.
o A *read N bytes* operation, which blocks until N bytes are
available past the current offset, and then returns them and seeks
forward by N bytes. If the stream ends before enough bytes are
received, either due to a network error or because the stream has
a finite length, the read operation returns an error instead.
2.2. Load a bundle's metadata
This takes the bundle's stream and returns a map ([INFRA]) of
metadata containing at least keys named:
requests A map ([INFRA]) whose keys are [FETCH] requests for the
HTTP exchanges in the bundle, and whose values are opaque metadata
that Load a response from a bundle can use to find the matching
response.
manifest The URL of the bundle's manifest(s). This is a URL to
support bundles with multiple different manifests, where the
client uses content negotiation to select the most appropriate
one.
The map may include other items added by sections defined in the
Web Bundle Section Name Registry.
Yasskin Expires December 15, 2018 [Page 4]
Internet-Draft Bundled HTTP Exchanges June 2018
This operation only waits for a prefix of the stream that, if the
bundle is encoded with the "responses" section last, ends before the
first response.
This operation's implementation is in Section 3.2.
2.2.1. Load a bundle's metadata from the end
If a bundle's bytes are embedded in a longer sequence rather than
being streamed, a parser can also load them starting from a pointer
to the last byte of the bundle. This returns the same data as
Section 2.2.
This operation's implementation is in Section 3.2.5.
2.3. Load a response from a bundle
This takes the sequence of bytes representing the bundle and one
request returned from Section 2.2 with its metadata, and returns the
response ([FETCH]) matching that request.
This operation can be completed without inspecting bytes other than
those that make up the loaded response, although higher-level
operations like proving that an exchange is correctly signed
([I-D.yasskin-http-origin-signed-responses]) may need to load other
responses.
Note that this operation uses the metadata for a particular request
returned by Section 2.2, while a client will generally want to load
the response for a request that the client generated. TODO: Specify
how a client determines the best available bundled response, if any,
for that client-generated request, in this or another document.
This operation's implementation is in Section 3.3.
3. Format
3.1. Top-level structure
_This section is non-normative._
A bundle holds a series of named sections. The beginning of the
bundle maps section names to the range of bytes holding that section.
The most important section is the "index" (Section 3.2.1), which
similarly maps serialized HTTP requests to the range of bytes holding
that request's serialized response. Byte ranges are represented
using an offset from some point in the bundle _after_ the encoding of
Yasskin Expires December 15, 2018 [Page 5]
Internet-Draft Bundled HTTP Exchanges June 2018
the range itself, to reduce the amount of work needed to use the
shortest possible encoding of the range.
Future specifications can define new sections with extra data, and if
necessary, these sections can be marked "critical" (Section 3.2.3) to
prevent older parsers from using the rest of the bundle incorrectly.
The bundle is roughly a CBOR item ([I-D.ietf-cbor-7049bis]) with the
following CDDL ([I-D.ietf-cbor-cddl]) schema, but bundle parsers are
required to successfully parse some byte strings that aren't valid
CBOR. For example, sections might have padding between them, or even
overlap, as long as the embedded relative offsets cause the parsing
algorithms in this specification to return data.
webbundle = [
; 🌐📦 in UTF-8.
magic: h'F0 9F 8C 90 F0 9F 93 A6',
section-offsets: bytes .cbor {* ($section-name .within tstr) =>
[ offset: uint, length: uint] },
sections: [* $section ],
length: bytes .size 8, ; Big-endian number of bytes in the bundle.
]
$section-name /= "index" / "manifest" / "critical" / "responses"
$section /= index / manifest / critical / responses
responses = [*response]
3.2. Load a bundle's metadata
A bundle holds a series of sections, which can be accessed randomly
using the information in the "section-offset" CBOR item:
section-offsets = {* tstr => [ offset: uint, length: uint] },
Offsets in this item are relative to the _end_ of the section-offset
item.
To implement Section 2.2, the parser MUST run the following steps,
taking the "stream" as input.
1. Seek to offset 0 in "stream". Assert: this operation doesn't
fail.
2. If reading 10 bytes from "stream" returns an error or doesn't
return the bytes with hex encoding "84 48 F0 9F 8C 90 F0 9F 93
Yasskin Expires December 15, 2018 [Page 6]
Internet-Draft Bundled HTTP Exchanges June 2018
A6" (the CBOR encoding of the 4-item array initial byte and
8-byte bytestring initial byte, followed by 🌐📦
in UTF-8), return an error.
3. Let "sectionOffsetsLength" be the result of getting the length
of the CBOR bytestring header from "stream" (Section 3.4.2). If
this is an error, return that error.
4. If "sectionOffsetsLength" is TBD or greater, return an error.
5. Let "sectionOffsetsBytes" be the result of reading
"sectionOffsetsLength" bytes from "stream". If
"sectionOffsetsBytes" is an error, return that error.
6. Let "sectionOffsets" be the result of parsing one CBOR item
(Section 3.4) from "sectionOffsetsBytes", matching the section-
offsets rule in the CDDL ([I-D.ietf-cbor-cddl]) above. If
"sectionOffsets" is an error, return an error.
7. Let "sectionsStart" be the current offset within "stream". For
example, if "sectionOffsetsLength" were 52, "sectionsStart"
would be 64.
8. Let "knownSections" be the subset of the Section 6.2 that this
client has implemented.
9. Let "ignoredSections" be an empty set.
10. For each ""name"" key in "sectionOffsets", if ""name""'s
specification in "knownSections" says not to process other
sections, add those sections' names to "ignoredSections".
11. Let "metadata" be an empty map ([INFRA]).
12. For each ""name""/["offset", "length"] triple in
"sectionOffsets":
1. If ""name"" isn't in "knownSections", continue to the next
triple.
2. If ""name""'s Metadata field is "No", continue to the next
triple.
3. If ""name"" is in "ignoredSections", continue to the next
triple.
4. Seek to offset "sectionsStart + offset" in "stream". If
this fails, return an error.
Yasskin Expires December 15, 2018 [Page 7]
Internet-Draft Bundled HTTP Exchanges June 2018
5. Let "sectionContents" be the result of reading "length"
bytes from "stream". If "sectionContents" is an error,
return that error.
6. Follow ""name""'s specification from "knownSections" to
process the section, passing "sectionContents", "stream",
"sectionOffsets", "sectionsStart", and "metadata". If this
returns an error, return it.
13. If "metadata" doesn't have entries with keys "requests" and
"manifest", return an error.
14. Return "metadata".
3.2.1. Parsing the index section
The "index" section defines the set of HTTP requests in the bundle
and identifies their locations in the "responses" section.
index = {* headers => [ offset: uint,
length: uint] }
To parse the index section, given its "sectionContents", the
"sectionsStart" offset, the "sectionOffsets" CBOR item, and the
"metadata" map to fill in, the parser MUST do the following:
1. Let "index" be the result of parsing "sectionContents" as a CBOR
item matching the "index" rule in the above CDDL (Section 3.4).
If "index" is an error, return an error.
2. Let "requests" be an initially-empty map ([INFRA]) from HTTP
requests ([FETCH]) to structs ([INFRA]) with items named "offset"
and "length".
3. For each "cbor-http-request"/["offset", "length"] triple in
"index":
1. Let "headers"/"pseudos" be the result of converting "cbor-
http-request" to a header list and pseudoheaders using the
algorithm in Section 3.5. If this returns an error, return
that error.
2. If "pseudos" does not have keys named ':method' and ':url',
or its size isn't 2, return an error.
3. If "pseudos[':method']" is not 'GET', return an error.
Yasskin Expires December 15, 2018 [Page 8]
Internet-Draft Bundled HTTP Exchanges June 2018
Note: This could probably support any cacheable
(Section 4.2.3) of [RFC7231]) and safe (Section 4.2.1 of
[RFC7231]) method, matching PUSH_PROMISE (Section 8.2 of
[RFC7540]), but today that's only HEAD and GET, and HEAD can
be served as a transformation of GET, so this version of the
specification keeps the method simple.
4. Let "parsedUrl" be the result of parsing ([URL])
"pseudos[':url']" with no base URL.
5. If "parsedUrl" is a failure, its fragment is not null, or it
includes credentials, return an error.
6. Let "http-request" be a new request ([FETCH]) whose:
+ method is "pseudos[':method']",
+ url is "parsedUrl",
+ header list is "headers", and
+ client is null.
7. Let "streamOffset" be "sectionsStart + section-
offsets["responses"].offset + offset". That is, offsets in
the index are relative to the start of the "responses"
section.
8. If "offset + length" is greater than
"sectionOffsets["responses"].length", return an error.
9. Set "requests"["http-request"] to a struct whose "offset"
item is "streamOffset" and whose "length" item is "length".
4. Set "metadata["requests"]" to "requests".
3.2.2. Parsing the manifest section
The "manifest" section records a single URL identifying the manifest
of the bundle. The bundle can contain multiple resources at this
URL, and the client is expected to content-negotiate for the best
one. For example, a client might select the one with an "accept"
header of "application/manifest+json" ([appmanifest]) and an "accept-
language" header of "es-419".
manifest = text
Yasskin Expires December 15, 2018 [Page 9]
Internet-Draft Bundled HTTP Exchanges June 2018
To parse the manifest section, given its "sectionContents" and the
"metadata" map to fill in, the parser MUST do the following:
1. Let "urlString" be the result of parsing "sectionContents" as a
CBOR item matching the above "manifest" rule (Section 3.4. If
"urlString" is an error, return that error.
2. Let "url" be the result of parsing ([URL]) "urlString" with no
base URL.
3. If "url" is a failure, its fragment is not null, or it includes
credentials, return an error.
4. Set "metadata["manifest"]" to "url".
3.2.3. Parsing the critical section
The "critical" section lists sections of the bundle that the client
needs to understand in order to load the bundle correctly. Other
sections are assumed to be optional.
critical = [*tstr]
To parse the critical section, given its "sectionContents" and the
"metadata" map to fill in, the parser MUST do the following:
1. Let "critical" be the result of parsing "sectionContents" as a
CBOR item matching the above "critical" rule (Section 3.4). If
"critical" is an error, return that error.
2. For each value "sectionName" in the "critical" list, if the
client has not implemented sections named "sectionName", return
an error.
This section does not modify the returned metadata.
3.2.4. The responses section
The responses section does not add any items to the bundle metadata
map. Instead, its offset and length are used in processing the index
section (Section 3.2.1).
3.2.5. Starting from the end
The length of a bundle is encoded as a big-endian integer inside a
CBOR byte string at the end of the bundle.
Yasskin Expires December 15, 2018 [Page 10]
Internet-Draft Bundled HTTP Exchanges June 2018
+------------+-----+----+----+----+----+----+----+----+----+----+
| first byte | ... | 48 | 00 | 00 | 00 | 00 | 00 | BC | 61 | 4E |
+------------+-----+----+----+----+----+----+----+----+----+----+
/ \
0xBC614E-10=12345668 omitted bytes
Figure 1: Example trailing bytes
Parsing from the end allows the bundle to be appended to another
format such as a self-extracting executable.
To implement Section 2.2.1, taking a sequence of bytes "bytes", the
client MUST:
1. Let "byteStringHeader" be "bytes[bytes.length - 9]". If
"byteStringHeader is not "0x48` (the CBOR
([I-D.ietf-cbor-7049bis]) initial byte for an 8-byte byte
string), return an error.
2. Let "bundleLength" be "[bytes[bytes.length - 8],
bytes[bytes.length])" (the last 8 bytes) interpreted as a big-
endian integer.
3. If "bundleLength > bytes.length", return an error.
4. Let "stream" be a new stream whose:
* Available bytes are "[bytes[bytes.length - bundleLength],
bytes[bytes.length])".
* EOF flag is set.
* Current offset is initially 0.
* The seek to offset N and read N bytes operations succeed
immediately if "currentOffset + N <= bundleLength" and fail
otherwise.
5. Return the result of running Section 3.2 with "stream" as input.
3.3. Load a response from a bundle
The result of Load a bundle's metadata maps each request to a
response, which consists of headers and a payload. The headers can
be loaded from the bundle's stream before waiting for the payload,
and similarly the payload can be streamed to downstream consumers.
response = [headers: bstr .cbor headers, payload: bstr]
Yasskin Expires December 15, 2018 [Page 11]
Internet-Draft Bundled HTTP Exchanges June 2018
To implement Section 2.3, the parser MUST run the following steps,
taking the bundle's "stream" and one "request" and its
"requestMetadata" as returned by Section 2.2.
1. Seek to offset "requestMetadata.offset" in "stream". If this
fails, return an error.
2. Read 1 byte from "stream". If this is an error or isn't "0x82",
return an error.
3. Let "headerLength" be the result of getting the length of a CBOR
bytestring header from "stream" (Section 3.4.2). If
"headerLength" is an error, return that error.
4. If "headerLength" is TBD or greater, return an error.
5. Let "headerCbor" be the result of reading "headerLength" bytes
from "stream" and parsing a CBOR item from them matching the
"headers" CDDL rule. If either the read or parse returns an
error, return that error.
6. Let "headers"/"pseudos" be the result of converting "cbor-http-
request" to a header list and pseudoheaders using the algorithm
in Section 3.5. If this returns an error, return that error.
7. If "pseudos" does not have a key named ':status' or its size
isn't 1, return an error.
8. If "pseudos[':status']" isn't exactly 3 ASCII decimal digits,
return an error.
9. Let "payloadLength" be the result of getting the length of a
CBOR bytestring header from "stream" (Section 3.4.2). If
"payloadLength" is an error, return that error.
10. If "stream.currentOffset + payloadLength !=
requestMetadata.offset + requestMetadata.length", return an
error.
11. Let "body" be a new body ([FETCH]) whose stream is a tee'd copy
of "stream" starting at the current offset and ending after
"payloadLength" bytes.
TODO: Add the rest of the details of creating a "ReadableStream"
object.
12. Let "response" be a new response ([FETCH]) whose:
Yasskin Expires December 15, 2018 [Page 12]
Internet-Draft Bundled HTTP Exchanges June 2018
* Url list is "request"'s url list,
* status is "pseudos[':status']",
* header list is "headers", and
* body is "body".
13. Return "response".
3.4. Parsing CBOR items
Parsing a bundle involves parsing many CBOR items. All of these
items need to be canonically encoded.
3.4.1. Parse a known-length item
To parse a CBOR item ([I-D.ietf-cbor-7049bis]), optionally matching a
CDDL rule ([I-D.ietf-cbor-cddl]), from a sequence of bytes, "bytes",
the parser MUST do the following:
1. If "bytes" are not a well-formed CBOR item, return an error.
2. If "bytes" does not satisfy the core canonicalization
requirements from Section 4.9 of [I-D.ietf-cbor-7049bis], return
an error. This format does not use floating point values or
tags, so this specification does not add any canonicalization
rules for them.
3. If "bytes" includes extra bytes after the encoding of a CBOR
item, return an error.
4. Let "item" be the result of decoding "bytes" as a CBOR item.
5. If a CDDL rule was specified, but "item" does not match it,
return an error.
6. Return "item".
3.4.2. Parsing variable-length data from a bytestring
Bundles encode variable-length data in CBOR bytestrings, which are
prefixed with their length. This algorithm returns the number of
bytes in the variable-length item and sets the stream's current
offset to the first byte of the contents.
To get the length of a CBOR bytestring header from a bundle's stream,
the parser MUST do the following:
Yasskin Expires December 15, 2018 [Page 13]
Internet-Draft Bundled HTTP Exchanges June 2018
1. Let "firstByte" be the result of reading 1 byte from the stream.
If "firstByte" is an error, return that error.
2. If "firstByte & 0xE0" is not "0x40", the item is not a
bytestring. Return an error.
3. If "firstByte & 0x1F" is:
0..23, inclusive Return "firstByte".
24 Let "content" be the result of reading 1 byte from the stream.
If "content" is an error or is less than 24, return an error.
25 Let "content" be the result of reading 2 bytes from the
stream. If "content" is an error or its first byte is 0,
return an error.
26 Let "content" be the result of reading 4 bytes from the
stream. If "content" is an error or its first two bytes are
0, return an error.
27 Let "content" be the result of reading 8 bytes from the
stream. If "content" is an error or its first four bytes are
0, return an error.
28..31, inclusive Return an error.
4. Return the big-endian integer encoded in "content".
3.5. Interpreting CBOR HTTP headers
Bundles represent HTTP requests and responses as a list of headers,
matching the following CDDL ([I-D.ietf-cbor-cddl]):
headers = {* bstr => bstr}
Pseudo-headers starting with a ":" provide the non-header information
needed to create a request or response as appropriate
To convert a CBOR item "item" into a [FETCH] header list and
pseudoheaders, parsers MUST do the following:
1. If "item" doesn't match the "headers" rule in the above CDDL,
return an error.
2. Let "headers" be a new header list ([FETCH]).
3. Let "pseudos" be an empty map ([INFRA]).
Yasskin Expires December 15, 2018 [Page 14]
Internet-Draft Bundled HTTP Exchanges June 2018
4. For each pair "name"/"value" in "item":
1. If "name" contains any upper-case or non-ASCII characters,
return an error. This matches the requirement in
Section 8.1.2 of [RFC7540].
2. If "name" starts with a ':':
1. Assert: "pseudos[name]" does not exist, because CBOR maps
cannot contain duplicate keys.
2. Set "pseudos[name]" to "value".
3. Continue.
3. If "name" or "value" doesn't satisfy the requirements for a
header in [FETCH], return an error.
4. Assert: "headers" does not contain ([FETCH]) "name", because
CBOR maps cannot contain duplicate keys and an earlier step
rejected upper-case bytes.
Note: This means that a response cannot set more than one
cookie, because the "Set-Cookie" header ([RFC6265]) has to
appear multiple times to set multiple cookies.
5. Append "name"/"value" to "headers".
5. Return "headers"/"pseudos".
4. Guidelines for bundle authors
Bundles SHOULD consist of a single CBOR item satisfying the core
canonicalization requirements (Section 3.4) and matching the
"webbundle" CDDL rule in Section 3.1.
5. Security Considerations
Bundles currently have no mechanism for ensuring that the signed
exchanges they contain constitute a consistent version of those
resources. Even if a website never has a security vulnerability when
resources are fetched at a single time, an attacker might be able to
combine a set of resources pulled from different versions of the
website to build a vulnerable site. While the vulnerable site could
have occurred by chance on a client's machine due to normal HTTP
caching, bundling allows an attacker to guarantee that it happens.
Future work in this specification might allow a bundle to constrain
its resources to come from a consistent version.
Yasskin Expires December 15, 2018 [Page 15]
Internet-Draft Bundled HTTP Exchanges June 2018
6. IANA considerations
6.1. Internet Media Type Registration
IANA maintains the registry of Internet Media Types [RFC6838] at
https://www.iana.org/assignments/media-types [3].
o Type name: application
o Subtype name: webbundle
o Required parameters: N/A
o Optional parameters: N/A
o Encoding considerations: binary
o Security considerations: See Section 5 of this document.
o Interoperability considerations: N/A
o Published specification: This document
o Applications that use this media type: None yet, but it is
expected that web browsers will use this format.
o Fragment identifier considerations: N/A
o Additional information:
* Deprecated alias names for this type: N/A
* Magic number(s): 84 48 F0 9F 8C 90 F0 9F 93 A6
* File extension(s): .wbn
* Macintosh file type code(s): N/A
o Person & email address to contact for further information: See the
Author's Address section of this specification.
o Intended usage: COMMON
o Restrictions on usage: N/A
o Author: See the Author's Address section of this specification.
o Change controller: The IESG iesg@ietf.org [4]
Yasskin Expires December 15, 2018 [Page 16]
Internet-Draft Bundled HTTP Exchanges June 2018
o Provisional registration? (standards tree only): Not yet.
6.2. Web Bundle Section Name Registry
IANA is directed to create a new registry with the following
attributes:
Name: Web Bundle Section Names
Review Process: Specification Required
Initial Assignments:
+--------------+---------------+----------+
| Section Name | Specification | Metadata |
+--------------+---------------+----------+
| "index" | Section 3.2.1 | Yes |
| | | |
| "manifest | Section 3.2.2 | Yes |
| | | |
| "critical | Section 3.2.3 | Yes |
| | | |
| "responses" | Section 3.2.4 | No |
+--------------+---------------+----------+
Requirements on new assignments:
Section Names MUST be encoded in UTF-8.
Assignments must specify whether the section is parsed during
Load a bundle's metadata (Metadata=Yes) or not (Metadata=No).
The section's specification can use the bytes making up the section,
the bundle's stream (Section 2.1), the "sectionOffsets" CBOR item
(Section 3.2), and the offset within the stream where sections start,
as input, and MUST say if an error is returned, and otherwise what
items, if any, are added to the map that Section 3.2 returns. A
section's specification MAY say that, if it is present, another
section is not processed.
7. References
7.1. Normative References
Yasskin Expires December 15, 2018 [Page 17]
Internet-Draft Bundled HTTP Exchanges June 2018
[appmanifest]
Caceres, M., Christiansen, K., Lamouri, M., Kostiainen,
A., Dolin, R., and M. Giuca, "Web App Manifest", World
Wide Web Consortium WD WD-appmanifest-20180523, May 2018,
<https://www.w3.org/TR/2018/WD-appmanifest-20180523>.
[FETCH] WHATWG, "Fetch", June 2018,
<https://fetch.spec.whatwg.org/>.
[I-D.ietf-cbor-7049bis]
Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", draft-ietf-cbor-7049bis-02 (work
in progress), March 2018.
[I-D.ietf-cbor-cddl]
Birkholz, H., Vigano, C., and C. Bormann, "Concise data
definition language (CDDL): a notational convention to
express CBOR data structures", draft-ietf-cbor-cddl-02
(work in progress), February 2018.
[INFRA] WHATWG, "Infra", June 2018,
<https://infra.spec.whatwg.org/>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
DOI 10.17487/RFC7231, June 2014,
<https://www.rfc-editor.org/info/rfc7231>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[SRI] Akhawe, D., Braun, F., Marier, F., and J. Weinberger,
"Subresource Integrity", World Wide Web Consortium
Recommendation REC-SRI-20160623, June 2016,
<http://www.w3.org/TR/2016/REC-SRI-20160623>.
[URL] WHATWG, "URL", June 2018, <https://url.spec.whatwg.org/>.
Yasskin Expires December 15, 2018 [Page 18]
Internet-Draft Bundled HTTP Exchanges June 2018
7.2. Informative References
[I-D.yasskin-http-origin-signed-responses]
Yasskin, J., "Signed HTTP Exchanges", draft-yasskin-http-
origin-signed-responses-03 (work in progress), March 2018.
[I-D.yasskin-webpackage-use-cases]
Yasskin, J., "Use Cases and Requirements for Web
Packages", draft-yasskin-webpackage-use-cases-01 (work in
progress), March 2018.
[RFC6265] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011,
<https://www.rfc-editor.org/info/rfc6265>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.
7.3. URIs
[1] https://mailarchive.ietf.org/arch/search/?email_list=art
[2] https://github.com/WICG/webpackage
[3] https://www.iana.org/assignments/media-types
[4] mailto:iesg@ietf.org
Appendix A. Acknowledgements
Author's Address
Jeffrey Yasskin
Google
Email: jyasskin@chromium.org
Yasskin Expires December 15, 2018 [Page 19]
