larlet-fr-david-cache/cache/7fb7e8f5fb68a4ddc308b112a7f8d09f/index.md

title: Web Packaging Format Explainer
url: https://github.com/WICG/webpackage/blob/master/explainer.md
hash_url: 7fb7e8f5fb68a4ddc308b112a7f8d09f

<p>This document describes use cases for a new package format for web sites and
applications and outlines such a format. It replaces the
<del><a href="https://w3ctag.github.io/packaging-on-the-web/" rel="nofollow">W3C TAG's Web Packaging Draft</a></del>.
It serves similar role as typical "Introduction" or "Using" and other
non-normative sections of specs.</p>
<h2><a href="#background" aria-hidden="true" class="anchor" id="user-content-background"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Background</h2>
<p>Some new use cases for Web technology have motivated thinking about a multi-resource packaging format. Those new opportunities include:</p>
<h3><a href="#local-sharing" aria-hidden="true" class="anchor" id="user-content-local-sharing"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Local Sharing</h3>
<p>Local sharing is quite popular, especially in Emerging Markets countries, due to
cost and limitations on cellular data and relatively spotty WiFi availability.
It is typically done over local Bluetooth/WiFi, by either built-in OS features
like <a href="https://en.wikipedia.org/wiki/Android_Beam" rel="nofollow">Android Beam</a> or with popular
3-rd party apps, such as
<a href="https://play.google.com/store/apps/details?id=com.lenovo.anyshare.gps" rel="nofollow">ShareIt</a>
or <a href="https://play.google.com/store/apps/details?id=cn.xender" rel="nofollow">Xender</a>).
Typically, the locally stored media files and apps (APK files for Android for
example) are shared this way. Extending sharing to bundles of content and web
apps (Progressive Web Apps in particular) opens up new possibilities:</p>
<h4><a href="#unsigned-snapshots" aria-hidden="true" class="anchor" id="user-content-unsigned-snapshots"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Unsigned snapshots</h4>
<p>Any client can snapshot the page they're currently reading. This is currently
done mostly by capturing a screenshot or saving into a browser-specific format
like <a href="https://tools.ietf.org/html/rfc2557" rel="nofollow">MHTML</a>
or <a href="https://en.wikipedia.org/wiki/Webarchive" rel="nofollow">Web Archive</a>, but these only
support at most a single page per archive, and the second
set <a href="https://xkcd.com/927/" rel="nofollow">aren't supported by other browsers</a>.</p>
<h4><a href="#signed-applications" aria-hidden="true" class="anchor" id="user-content-signed-applications"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Signed applications</h4>
<p>If the original origin signs a package, the contents can get full access to
browser state and network requests for that origin. This lets people share full
PWAs peer-to-peer.</p>
<p>Local sharing tends to be popular where connectivity to the web is expensive:
each byte costs money. This means the client may be stuck with an outdated
version of a package for a significant amount of time, including that package's
vulnerabilities. It may be feasible to periodically check for OCSP notification
that a package's certificate has been revoked. We also need to design a cheap
notification that the package is critically vulnerable and needs to be disabled
until it can be updated.</p>
<h3><a href="#physical-web" aria-hidden="true" class="anchor" id="user-content-physical-web"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Physical Web</h3>
<p><a href="https://google.github.io/physical-web/" rel="nofollow">Beacons</a> and other physical web devices often want to 'broadcast' various content locally. Today, they broadcast a URL and make the user's device go to a web site. This delivers the trusted content to the user's browser (user can observe the address bar to verify) and allow web apps to talk back to their services. It can be useful to be able to broadcast a package containing several pages or even a simple web app, even without a need to immediately have a Web connection - for example, via Bluetooth. If combined with signature from the publisher, the loaded pages may be treated as if they were loaded via TLS connection with a valid certificate, in terms of the <a href="https://tools.ietf.org/html/rfc6454" rel="nofollow">origin-based security model</a>. For example, they can use <a href="https://fetch.spec.whatwg.org/#fetch-api" rel="nofollow"><code>fetch()</code></a> against its service or use "Add To Homescreen" for the convenience of the user.</p>
<p>Physical web beacons may be located in a place that has no connectivity, and
their owner may only visit to update them as often as their battery needs
replacement: annually or less often. This leaves a large window during which a
certificate could be compromised or a package could get out of date. We think
there's no way to prevent a client from trusting its initial download of a
package signed by a compromised certificate. When the client gets back to a
public network, it should attempt to validate both the certificate and the
package using the mechanisms alluded to under <a href="#local-sharing">Local Sharing</a>.</p>
<h3><a href="#content-distributors-and-web-caches" aria-hidden="true" class="anchor" id="user-content-content-distributors-and-web-caches"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Content Distributors and Web caches.</h3>
<p>Content distributors can provide the service of hosting web content that should
be delivered at scale. This includes both hosting subresources (JS libraries,
images) as well as entire content (<a href="https://developers.google.com/amp/cache/overview" rel="nofollow">Google
AMP</a>) on a network of servers,
often provided as a service by 3rd party. Unfortunately, the origin-based
security model of the Web limits the ways 3rd-party caches/servers can be used.
For example in the case of hosting JS subresources, the original document must
explicitly trust the distributor's origin to serve the trusted script. The user
agent must use protocol-based means to verify the subresource is coming from the
trusted distributor. Another example is a content distributor that caches the
whole content. Because the origin of the distributor is different from the
origin of the site, the browser normally can't afford the origin treatment of
the site to the loaded content. Look at how an article from USA Today is
represented:</p>
<p><a href="/WICG/webpackage/blob/master/buick.png" target="_blank"><img align="center" src="/WICG/webpackage/raw/master/buick.png"/></a></p>
<p>Note the address bar indicating google.com. Also, since the content of USA Today is hosted in an iframe, it can't use all the functionality typically afforded to a top-level document:</p>
<ul>
<li>Can't request permissions</li>
<li>Can't be added to homescreen</li>
</ul>
<p>Packages served to content distributors can staple an OCSP response and have a
short expiration time, avoiding the problems with outdated packages under "Local
Sharing".</p>
<h2><a href="#goals-and-non-goals" aria-hidden="true" class="anchor" id="user-content-goals-and-non-goals"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Goals and non-goals</h2>
<p>See
<a href="https://wicg.github.io/webpackage/draft-yasskin-webpackage-use-cases.html#requirements" rel="nofollow">https://wicg.github.io/webpackage/draft-yasskin-webpackage-use-cases.html#requirements</a></p>
<h2><a href="#proposal" aria-hidden="true" class="anchor" id="user-content-proposal"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Proposal</h2>
<p>We propose to introduce a packaging format for the Web that would be able to contain multiple resources (HTML, CSS, Images, Media files, JS files etc) in a "bundle". That bundle can be distributed as regular Web resource (over HTTP[S]) and also by non-Web means, which includes local storage, local sharing, non-HTTP protocols like Bluetooth, etc. Being a single "bundle", it facilitates various modes of transfer. The <strong>packages may be nested</strong>, providing natural way to represent the bundles of resources corresponding to different origins and sites.</p>
<p>In addition, that format would include optional <strong>signing</strong> of the resources, which can be used to verify authenticity and integrity of the content. Once and if verified (this may or may not require network connection), the content can be afforded the treatment of the claimed origin - for example showing a "green lock" with URL in a browser, or being able to send network request to the origin's server. This disconnects the verification of the origin from actual network connection and enables many new scenarios for the web content to be consumed, including time-shifted delivery (when content is delivered by an opportunistic restartable download for example), peer-to-peer sharing or caching on local file servers.</p>
<p>Since the packaged "bundle" can be quite large (a game with a lot of resources or content of multiple web sites), efficient access to that content becomes important. For example, it would be often prohibitively expensive to "unpack" or somehow else pre-process such a large resource on the client device. Unpacking, for example, may require twice the space to be occupied in device's storage, which can be a problem, especially on low-end devices. We propose a optional <strong>Content Index</strong> structure that allows the bundle to be consumed (browsed) efficiently as is, without unpacking - by adding an index-like structure which provides direct offsets into the package.</p>
<p>This is roughly based on the existing <a href="https://w3ctag.github.io/packaging-on-the-web/" rel="nofollow">Packaging on the Web</a> W3C TAG proposal, but we've made significant changes:</p>
<ol>
<li>Index of content to facilitate local resource fetching from the package.</li>
<li>Package manifests that can refer to sub-package manifests to allow resources
from multiple origins.</li>
<li>Signature block, to cryptographically sign the content of the package.</li>
<li>Removed the
<a href="https://w3ctag.github.io/packaging-on-the-web/#fragment-identifiers" rel="nofollow">fragment-based URL schema</a>
from the spec as it's complex with limited use cases.</li>
</ol>
<p>Note that this is just an explainer, <strong>not a specification</strong>. We'll add more
precision when we translate it to a spec.</p>
<h3><a href="#overall-format" aria-hidden="true" class="anchor" id="user-content-overall-format"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Overall format</h3>
<p>The package is a <a href="https://tools.ietf.org/html/rfc7049" rel="nofollow">CBOR-encoded data item</a>
with MIME type <code>application/package+cbor</code>. It logically contains a flat sequence
of resources represented as HTTP responses. The package also includes metadata
such as a manifest and an index to let consumers validate the resources and
access them directly.</p>
<p>The overall structure of the item is described by the following
<a href="https://tools.ietf.org/html/draft-greevenbosch-appsawg-cbor-cddl" rel="nofollow">CDDL</a>:</p>
<pre lang="cddl"><code>webpackage = [
  magic1: h'F0 9F 8C 90 F0 9F 93 A6',  ; 🌐📦 in UTF-8.
  section-offsets: { * (($section-name .within tstr) =&gt; offset) },
  sections: ({ * $$section }) .within ({ * $section-name =&gt; any }),
  length: uint,                        ; Total number of bytes in the package.
  magic2: h'F0 9F 8C 90 F0 9F 93 A6',  ; 🌐📦 in UTF-8.
]

; Offsets are measured from the first byte of the webpackage item to the first
; byte of the target item.
offset = uint
</code></pre>
<p>Each section-offset points to a section with the same key, by holding the byte
offset from the start of the webpackage item to the start of the section's name
item.</p>
<p>The length holds the total length in bytes of the <code>webpackage</code> item and must be
encoded in the uint64_t format, which makes it possible to build self-extracting
executables by appending a normal web package to the extractor executable.</p>
<p>The defined section types are:</p>
<ul>
<li><a href="#main-content"><code>"indexed-content"</code></a>: The only required section.
Maps resource keys (URLs possibly extended with HTTP headers) to
HTTP2 responses. The mapping uses byte offsets to allow random
access to any resource.</li>
<li><a href="#manifest"><code>"manifest"</code></a>: Validates that resources came from the expected
source. May refer to other manifests among the responses. If this section
isn't provided, the resources are un-signed and can be loaded as untrusted
data.</li>
</ul>
<p>More sections may be defined later. If an unexpected section is encountered, it
is ignored.</p>
<p>Note that this top-level information is <em>not signed</em>, and so can't be trusted.
Only information in the manifest and below can be trusted.</p>
<h3><a href="#main-content" aria-hidden="true" class="anchor" id="user-content-main-content"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Main content</h3>
<p>The main content of a package is an index of HTTP requests pointing to HTTP
responses. These request/response pairs hold the manifests of sub-packages and
the resources in the package and all of its sub-packages. Both the requests and
responses can appear in any order, usually chosen to optimize loading while the
package is streamed.</p>
<pre lang="cddl"><code>$section-name /= "indexed-content"
$$section //= ("indexed-content" =&gt; [
  index: [* [resource-key, offset, ? length: uint] ],
  responses: [* [response-headers: http-headers, body: bstr]],
])

resource-key = uri / http-headers

; http-headers is a byte string in HPACK format (RFC7541).
; The dynamic table begins empty for each instance of http-headers.
http-headers = bstr
</code></pre>
<p>A <code>uri</code> <code>resource-key</code> is equivalent to an <code>http-headers</code> block with ":method"
set to "GET" and with ":scheme", ":authority", and ":path" headers set from the
URI as described in
<a href="https://tools.ietf.org/html/rfc7540#section-8.1.2.3" rel="nofollow">RFC7540 section 8.1.2.3</a>.</p>
<p>As an optimization, the <code>resource-key</code>s in the index store relative instead of
absolute URLs. Each entry is resolved relative to the resolved version of the
previous entry.</p>
<p>TODO: Consider random access into large indices.</p>
<p>In addition to the CDDL constraints:</p>
<ul>
<li>All byte strings must use a definite-length encoding so that package consumers
can parse the content directly instead of concatenating the indefinite-length
chunks first. The definite lengths here may also help a package consumer to
quickly send resources to other threads for parsing.</li>
<li>The index must not contain two resolved <code>resource-key</code>s with the
same <a href="http://httpwg.org/specs/rfc7541.html#rfc.section.1.3" rel="nofollow">header list</a> after
HPACK decoding.</li>
<li>The <code>resource-key</code> must not contain any headers that aren't either ":method",
":scheme", ":authority", ":path", or listed in the
<code>response-headers</code>'
<a href="https://tools.ietf.org/html/rfc7231#section-7.1.4" rel="nofollow">"Vary" header</a>.</li>
<li>The <code>resource-key</code> must contain at most one of each ":method", ":scheme",
":authority", ":path" header, in that order, before any other headers.
Resolving the <code>resource-key</code> fills in any missing pseudo-headers from that
set, ensuring that all resolved keys have exactly one of each.</li>
</ul>
<p>The optional <code>length</code> field in the index entries is redundant with the length
prefixes on the <code>response-headers</code> and <code>body</code> in the content, but it can be used
to issue <a href="https://tools.ietf.org/html/rfc7233" rel="nofollow">Range requests</a> for responses
that appear late in the <code>content</code>.</p>
<h3><a href="#manifest" aria-hidden="true" class="anchor" id="user-content-manifest"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Manifest</h3>
<p>TODO: Now that this no longer contains
a <a href="https://www.merriam-webster.com/dictionary/manifest#h3" rel="nofollow">manifest</a>,
consider renaming it to something like "authenticity".</p>
<p>A package's manifest contains some metadata for the
package, <a href="#validating-resources">hashes</a> for all resources included in that
package, and validity information for any <a href="#sub-packages">sub-packages</a> the
package depends on. The manifest is signed, so that UAs can trust that it comes
from its claimed origin.</p>
<pre lang="cddl"><code>$section-name /= "manifest"
$$section //= ("manifest" =&gt; signed-manifest)

signed-manifest = {
  manifest: manifest,
  certificates: [+ certificate],
  signatures: [+ signature]
}

manifest = {
  metadata: manifest-metadata,
  resource-hashes: {* hash-algorithm =&gt; [hash-value]},
  ? subpackages: [* subpackage],
}

manifest-metadata = {
  date: time,
  origin: uri,
  * tstr =&gt; any,
}

; From https://www.w3.org/TR/CSP3/#grammardef-hash-algorithm.
hash-algorithm /= "sha256" / "sha384" / "sha512"
; Note that a hash value is not base64-encoded, unlike in CSP.
hash-value = bstr

; X.509 format; see https://tools.ietf.org/html/rfc5280
certificate = bstr

signature = {
  ; RFC5280 says certificates can be identified by either the
  ; issuer-name-and-serial-number or by the subject key identifier. However,
  ; issuer names are complicated, and the subject key identifier only identifies
  ; the public key, not the certificate, so we identify certificates by their
  ; index in the certificates array instead.
  keyIndex: uint,
  ; Encoded as described in TLS 1.3,
  ; https://tlswg.github.io/tls13-spec/#signature-algorithms.
  signature: bstr,
}
</code></pre>
<p>The metadata must include an absolute URL identifying
the
<a href="https://html.spec.whatwg.org/multipage/browsers.html#concept-origin" rel="nofollow">origin</a>
vouching for the package and the date the package was created. It may contain
more keys defined in <a href="https://www.w3.org/TR/appmanifest/" rel="nofollow">https://www.w3.org/TR/appmanifest/</a>.</p>
<h4><a href="#manifest-signatures" aria-hidden="true" class="anchor" id="user-content-manifest-signatures"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Manifest signatures</h4>
<p>The manifest is signed by a set of certificates, including at least one that is
trusted to sign content from the
manifest's
<a href="https://html.spec.whatwg.org/multipage/browsers.html#concept-origin" rel="nofollow">origin</a>.
Other certificates can sign to vouch for the package along other dimensions, for
example that it was checked for malicious behavior by some authority.</p>
<p>The signed sequence of bytes is the concatenation of the following byte strings.
This matches the TLS1.3 format to avoid cross-protocol attacks when TLS
certificates are used to sign manifests.</p>
<ol>
<li>A string that consists of octet 32 (0x20) repeated 64 times.</li>
<li>A context string: the ASCII encoding of "Web Package Manifest".</li>
<li>A single 0 byte which serves as a separator.</li>
<li>The bytes of the <code>manifest</code> CBOR item.</li>
</ol>
<p>Each signature uses the <code>keyIndex</code> field to identify the certificate used to
generate it.
The <a href="https://tlswg.github.io/tls13-spec/#rfc.section.4.2.3" rel="nofollow">TLS 1.3 signing algorithm</a>
is determined from the certificate's public key type:</p>
<ul>
<li>RSA, 2048 bits: rsa_pss_sha256</li>
<li>secp256r1: ecdsa_secp256r1_sha256</li>
<li>secp384r1: ecdsa_secp384r1_sha384</li>
</ul>
<p>The following key types are not supported, for the mentioned reason:</p>
<ul>
<li>secp521r1: <a href="https://crbug.com/477623" rel="nofollow">Chrome doesn't support this curve</a>, so
certificates aren't using it on the web.</li>
<li>ed25519 and ed448:
The <a href="https://tools.ietf.org/html/draft-josefsson-tls-ed25519" rel="nofollow">RFC</a> for using
these in certificates isn't yet final.</li>
<li>RSA != 2048: Only 4096 has measurable usage, and it's very low.</li>
</ul>
<p>As a special case, if the package is being transferred from the manifest's
origin under TLS, the UA may load it without checking that its own resources match
the manifest. The UA still needs to validate resources provided by sub-manifests.</p>
<h4><a href="#certificates" aria-hidden="true" class="anchor" id="user-content-certificates"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Certificates</h4>
<p>The <code>signed-manifest.certificates</code> array should contain enough
X.509 certificates to chain from the signing certificates, using the rules
in <a href="https://tools.ietf.org/html/rfc5280" rel="nofollow">RFC5280</a>, to roots trusted by all
expected consumers of the package.</p>
<p><a href="#sub-packages'">Sub-packages</a> manifests can contain their own certificates or
can rely on certificates in their parent packages.</p>
<p>Requirements on the
certificates' <a href="https://tools.ietf.org/html/rfc5280#section-4.2.1.3" rel="nofollow">Key Usage</a>
and <a href="https://tools.ietf.org/html/rfc5280#section-4.2.1.12" rel="nofollow">Extended Key Usage</a>
are TBD. It may or may not be important to prevent TLS serving certificates from
being used to sign packages, in order to prevent cross-protocol attacks.</p>
<h4><a href="#validating-resources" aria-hidden="true" class="anchor" id="user-content-validating-resources"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Validating resources</h4>
<p>For a resource to be valid, then for each <code>hash-algorithm =&gt; [hash-value]</code> in
<code>resource-hashes</code>, the resource's hash using that algorithm needs to appear in
that list of <code>hash-value</code>s. Like
in <a href="https://www.w3.org/TR/SRI/#agility" rel="nofollow">Subresource Integrity</a>, the UA will only
check one of these, but it's up to the UA which one.</p>
<p>The hash of a resource is the hash of its Canonical CBOR encoding using the
following CDDL. Headers are decompressed before being encoded and hashed.</p>
<pre lang="cddl"><code>resource = [
  request: [
    ':method', bstr,
    ':scheme', bstr,
    ':authority', bstr,
    ':path', bstr,
    * (header-name, header-value: bstr)
  ],
  response-headers: [
    ':status', bstr,
    * (header-name, header-value: bstr)
  ],
  response-body: bstr
]

# Headers must be lower-case ascii per
# http://httpwg.org/specs/rfc7540.html#rfc.section.8.1.2, and only
# pseudo-headers can include ":".
header-name = bstr .regexp "[\x21-\x39\x3b-\x40\x5b-\x7e]+"
</code></pre>
<p>This differs from <a href="https://w3c.github.io/webappsec-subresource-integrity" rel="nofollow">SRI</a>,
which only hashes the body. Note: This will usually prevent a package from
relying on some of its contents being transferred as normal network responses,
unless its author can guarantee the network won't change or reorder the headers.</p>
<h4><a href="#sub-packages" aria-hidden="true" class="anchor" id="user-content-sub-packages"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Sub-packages</h4>
<p>A sub-package is represented by a <a href="#manifest">manifest</a> file in
the <a href="#main-content"><code>"content"</code></a> section, which contains hashes of resources
from another origin. The sub-package's resources are not otherwise distinguished
from the rest of the resources in the package. Sub-packages can form an
arbitrarily-deep tree.</p>
<p>There are three possible forms of dependencies on sub-packages, of which we
allow two. Because a sub-package is protected by its
own <a href="#signatures">signature</a>, if the main package trusts the sub-package's
server, it could avoid specifying a version of the sub-package at all. However,
this opens the main package up to downgrade attacks, where the sub-package is
replaced by an older, vulnerable version, so we don't allow this option.</p>
<pre lang="cddl"><code>subpackage = [
  resource: resource-key,
  validation: {
    ? hash: hashes,
    ? notbefore: time,
  }
]
</code></pre>
<p>If the main package wants to load either the sub-package it was built with or
any upgrade, it can specify the date of the original sub-package:</p>
<pre lang="cbor-diag"><code>[32("https://example.com/loginsdk.package"), {"notbefore": 1(1486429554)}]
</code></pre>
<p>Constraining packages with their date makes it possible to link together
sub-packages with common dependencies, even if the sub-packages were built at
different times.</p>
<p>If the main package wants to be certain it's loading the exact version of a
sub-package that it was built with, it can constrain sub-package with a hash of its manifest:</p>
<pre lang="cbor-diag"><code>[32("https://example.com/loginsdk.package"),
 {"hash": {"sha256": 22(b64'9qg0NGDuhsjeGwrcbaxMKZAvfzAHJ2d8L7NkDzXhgHk=')}}]
</code></pre>
<p>Note that because the sub-package may include sub-sub-packages by date, the top
package may need to explicitly list those sub-sub-packages' hashes in order to
be completely constrained.</p>
<h2><a href="#examples" aria-hidden="true" class="anchor" id="user-content-examples"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Examples</h2>
<p>Following are some example usages that correspond to these additions.
The packages are written in
<a href="https://tools.ietf.org/html/draft-greevenbosch-appsawg-cbor-cddl-10#appendix-G" rel="nofollow">CBOR's extended diagnostic notation</a>,
with the extensions that:</p>
<ol>
<li><code>hpack({key:value,...})</code> is an <a href="https://tools.ietf.org/html/rfc7541" rel="nofollow">hpack</a>
encoding of the described headers.</li>
<li><code>DER(...)</code> is the DER encoding of a certificate described partially by the
contents of the <code>...</code>.</li>
</ol>
<p>All examples are available in the <a href="/WICG/webpackage/blob/master/examples">examples</a> directory.</p>
<h3><a href="#single-site-a-couple-of-web-pages-with-resources-in-a-package" aria-hidden="true" class="anchor" id="user-content-single-site-a-couple-of-web-pages-with-resources-in-a-package"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Single site: a couple of web pages with resources in a package.</h3>
<p>The example web site contains two HTML pages and an image. This is straightforward case, demonstrating the following:</p>
<ol>
<li>The <code>section-offsets</code> section declares one main section starting 1 byte into
the <code>sections</code> item. (The 1 byte is the map header for the <code>sections</code> item.)</li>
<li>The <code>index</code> maps <a href="http://httpwg.org/specs/rfc7541.html" rel="nofollow">hpack</a>-encoded
headers for each resource to the start of that resource, measured relative to
the start of the <code>responses</code> item.</li>
<li>Each resource contains <code>date</code>/<code>expires</code> headers that specify when the
resource can be used by UA, similar to HTTP 1.1
<a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.2" rel="nofollow">Expiration Model</a>.
The actual expiration model is TBD and to be reflected in the spec. Note that
we haven't yet described a way to set an <code>expires</code> value for the whole
package at once.</li>
<li>The length of the whole package always appears from the 10th to 18th bytes
before the end of the package, in big-endian format.</li>
</ol>
<pre lang="cbor-diag"><code>['🌐📦',
    {"indexed-content": 1},
    {"indexed-content":
        [
            [ # Index.
                [hpack({
                    :method: GET,
                    :scheme: https
                    :authority: example.com
                    :path: /index.html
                }), 1],
                [hpack({
                    :method: GET
                    :scheme: https
                    :authority: example.com
                    :path: /otherPage.html
                }), 121],
                [hpack({
                    :method: GET
                    :scheme: https
                    :authority: example.com
                    :path: /images/world.png
                }), 243]
            ],
            [ # Resources.
                [
                    hpack({
                        :status: 200
                        content-type: text/html
                        date: Wed, 15 Nov 2016 06:25:24 GMT
                        expires: Thu, 01 Jan 2017 16:00:00 GMT
                    }),
                    '&lt;body&gt;\n  &lt;a href=\"otherPage.html\"&gt;Other page&lt;/a&gt;\n&lt;/body&gt;\n'
                ],
                [
                    hpack({
                        :status: 200
                        content-type: text/html
                        date: Wed, 15 Nov 2016 06:25:24 GMT
                        expires: Thu, 01 Jan 2017 16:00:00 GMT
                    }),
                    '&lt;body&gt;\n  Hello World! &lt;img src=\"images/world.png\"&gt;\n&lt;/body&gt;\n'
                ], [
                    hpack({
                        :status: 200
                        content-type: image/png
                        date: Wed, 15 Nov 2016 06:25:24 GMT
                        expires: Thu, 01 Jan 2017 16:00:00 GMT
                    }),
                    '... binary png image ...'
                ]
            ]
        ]
    },
    473,  # Always 8 bytes long.
    '🌐📦'
]
</code></pre>
<h3><a href="#multiple-origins-a-web-page-with-a-resources-from-the-other-origin" aria-hidden="true" class="anchor" id="user-content-multiple-origins-a-web-page-with-a-resources-from-the-other-origin"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Multiple Origins: a web page with a resources from the other origin.</h3>
<p>The example web site contains an HTML page and pulls a script from the
well-known location (different origin). Note that there's no need to distinguish
the resources from other origins vs the ones from the main origin. Since none of
them are signed, the browser won't treat any as
<a href="https://html.spec.whatwg.org/multipage/browsers.html#same-origin" rel="nofollow">same-origin</a>
with their claimed origin.</p>
<pre lang="cbor-diag"><code>['🌐📦',
    {"indexed-content": 1},
    {"indexed-content":
        [
            [
                [hpack({
                    :method: GET
                    :scheme: https
                    :authority: example.com
                    :path: /index.html
                }), 1],
                [hpack({
                    :method: GET
                    :scheme: https
                    :authority: ajax.googleapis.com
                    :path: /ajax/libs/jquery/3.1.0/jquery.min.js
                }), 179]
            ],
            [
                [
                    hpack({
                        :status: 200
                        content-type: text/html
                        date: Wed, 15 Nov 2016 06:25:24 GMT
                        expires: Thu, 01 Jan 2017 16:00:00 GMT
                    }),
                    '&lt;head&gt;\n&lt;script src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js\"&gt;&lt;/script&gt;\n&lt;body&gt;\n...\n&lt;/body&gt;\n'
                ],
                [
                    hpack({
                        :status: 200
                        content-type: text/html
                        date: Wed, 15 Nov 2016 06:25:24 GMT
                        expires: Thu, 01 Jan 2017 16:00:00 GMT
                    }),
                    '... some JS code ...\n'
                ]
            ]
        ]
    },
    396,
    '🌐📦'
]
</code></pre>
<h3><a href="#use-case-signed-package-one-origin" aria-hidden="true" class="anchor" id="user-content-use-case-signed-package-one-origin"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Use Case: Signed package, one origin.</h3>
<p>The example contains example.com/index.html. The package is signed by the
example.com publisher, using the same private key that example.com uses for
HTTPS. The signed package ensures the verification of the origin even if the
package is stored in a local file or obtained via other insecure ways like HTTP,
or hosted on another origin's server.</p>
<p>Some interesting things to notice in this package:</p>
<ol>
<li>The <code>"manifest"</code> map contains <code>"certificates"</code> and <code>"signatures"</code> arrays
describing how the manifest is signed.</li>
<li>The signature identifies the first element of <code>"certificates"</code> as the signing
certificate.</li>
<li>The elements of <code>"certificates"</code> are
DER-encoded <a href="https://tools.ietf.org/html/rfc5280" rel="nofollow">X.509 certificates</a>.
The <a href="/WICG/webpackage/blob/master/go/webpack/testdata/pki/example.com.cert">signing certificate</a> is
trusted for <code>example.com</code>, and that certificate chains,
using <a href="/WICG/webpackage/blob/master/go/webpack/testdata/pki/intermediate1.cert">other elements</a> of
<code>"certificates"</code>, to
a <a href="/WICG/webpackage/blob/master/go/webpack/testdata/pki/root1.cert">trusted root certificate</a>. The chain
is built and trusted in the same way as TLS chains during normal web
browsing.</li>
<li>The signature algorithm is determined by the signing certificate's public key
type, <code>prime256v1</code>, and isn't encoded separately in the signature block.</li>
<li>The manifest contains a <code>"resource-hashes"</code> block, which contains the hashes,
using the SHA384 algorithm in this case, of all resources in the package.
Unlike in
<a href="https://w3c.github.io/webappsec-subresource-integrity/" rel="nofollow">Subresource Integrity</a>,
the hashes include the request and response headers.</li>
<li>The inclusion of a certificate chain makes it possible to validate the
package offline. Browsers detect revoked certificates and packages with known
vulnerabilities by looking for separately signed files containing OCSP and
recency information, but this package does not demonstrate how to attach
those.</li>
</ol>
<pre lang="cbor-diag"><code>[
  '🌐📦',
  {
    "manifest": 1,
    "indexed-content": 2057
  },
  {
    "manifest": {
      "manifest": {
        "metadata": {
          "date": 1(1494583200),
          "origin": 32("https://example.com")
        },
        "resource-hashes": {
          "sha384": [
            h'3C3A03F7C3FC99494F6AAA25C3D11DA3C0D7097ABBF5A9476FB64741A769984E8B6801E71BB085E25D7134287B99BAAB',
            h'5AA8B83EE331F5F7D1EF2DF9B5AFC8B3A36AEC953F2715CE33ECCECD58627664D53241759778A8DC27BCAAE20F542F9F',
            h'D5B2A3EA8FE401F214DA8E3794BE97DE9666BAF012A4B515B8B67C85AAB141F8349C4CD4EE788C2B7A6D66177BC68171'
          ]
        }
      },
      "signatures": [
        {
          "keyIndex": 0,
          "signature": h'3044022015B1C8D46E4C6588F73D9D894D05377F382C4BC56E7CDE41ACEC1D81BF1EBF7E02204B812DACD001E0FD4AF968CF28EC6152299483D6D14D5DBE23FC1284ABB7A359'
        }
      ],
      "certificates": [
        DER(
          Certificate:
              ...
              Signature Algorithm: ecdsa-with-SHA256
                  Issuer: C=US, O=Honest Achmed's, CN=Honest Achmed's Test Intermediate CA
                  Validity
                      Not Before: May 10 00:00:00 2017 GMT
                      Not After : May 18 00:10:36 2018 GMT
                  Subject: C=US, O=Test Example, CN=example.com
                  Subject Public Key Info:
                      Public Key Algorithm: id-ecPublicKey
                          Public-Key: (256 bit)
                          pub:
                              ...
                          ASN1 OID: prime256v1
                  ...
        ),
        DER(
          Certificate:
              ...
              Signature Algorithm: sha256WithRSAEncryption
                  Issuer: C=US, O=Honest Achmed's, CN=Honest Achmed's Test Root CA
                  Validity
                      Not Before: May 10 00:00:00 2017 GMT
                      Not After : May 18 00:10:36 2018 GMT
                  Subject: C=US, O=Honest Achmed's, CN=Honest Achmed's Test Intermediate CA
                  Subject Public Key Info:
                      Public Key Algorithm: id-ecPublicKey
                          Public-Key: (521 bit)
                          pub:
                              ...
                          ASN1 OID: secp521r1
                  ...
        )
      ]
    },
    "indexed-content": [
      [
        [ hpack({
            :method: GET
            :scheme: https
            :authority: example.com
            :path: /index.html
          }), 1]
        [ hpack({
            :method: GET
            :scheme: https
            :authority: example.com
            :path: /otherPage.html
          }), 121],
        [ hpack({
            :method: GET
            :scheme: https
            :authority: example.com
            :path: /images/world.png
          }), 243]
        ],
      ],
      [
        [ hpack({
            :status: 200
            content-type: text/html
            date: Wed, 15 Nov 2016 06:25:24 GMT
            expires: Thu, 01 Jan 2017 16:00:00 GMT
          }),
          '&lt;body&gt;\n  &lt;a href=\"otherPage.html\"&gt;Other page&lt;/a&gt;\n&lt;/body&gt;\n'
        ]
        [ hpack({
            :status: 200
            content-type: text/html
            date: Wed, 15 Nov 2016 06:25:24 GMT
            expires: Thu, 01 Jan 2017 16:00:00 GMT
          }),
          '&lt;body&gt;\n  Hello World! &lt;img src=\"images/world.png\"&gt;\n&lt;/body&gt;\n'
        ],
        [ hpack({
            :status: 200
            content-type: image/png
            date: Wed, 15 Nov 2016 06:25:24 GMT
            expires: Thu, 01 Jan 2017 16:00:00 GMT
          }),
          '... binary png image ...'
        ]
      ]
    ]
  },
  2541,
  '🌐📦'
]
</code></pre>
<p>The process of validation:</p>
<ol>
<li>Verify that certificates identified by signature elements chain to trusted roots.</li>
<li>Find the subset of the signatures that correctly sign the manifest's bytes
using their identified certificates' public keys.</li>
<li>Parse the manifest and find its claimed origin.</li>
<li>Verify that at least one correct signature identifies a certificate that's
trusted for use by that origin.</li>
<li>When loading a resource, pick the strongest hash function in the
<code>"resource-hashes"</code> map, and use that to hash the Canonical CBOR
representation of its request headers, response headers, and body. Verify
that the resulting digest appears in that array in the <code>"resource-hashes"</code>
map.</li>
</ol>
<p><strong><em>Examples below here are out of date</em></strong></p>
<h3><a href="#use-case-signed-package-2-origins" aria-hidden="true" class="anchor" id="user-content-use-case-signed-package-2-origins"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Use Case: Signed package, 2 origins</h3>
<p>Lets add signing to the example mentioned above where a page uses a cross-origin JS library, hosted on <a href="https://ajax.googleapis.com" rel="nofollow">https://ajax.googleapis.com</a>. Since this package includes resources from 2 origins, this means there are 2 packages, one of them nested. Both of them should be signed by their respective publisher, since for the main page to be validated as secure (green lock, origin access) all resources that comprise it must be signed/validated - equivalent of them being loaded via HTTPS.</p>
<p>Important notes:</p>
<ol>
<li>Nested package with the JS library, obtained from googleapis.com, is separately signed by googleapis.com</li>
<li>Nested packages may have their own signatures and Content Index.  They can be included verbatim as a <a href="https://w3ctag.github.io/packaging-on-the-web/#parts" rel="nofollow">part</a> of the outer package. Therefore, their index entries will be relative to the inner package.  This does mean that accessing a part of a nested package will require multiple index lookups depending on how deeply nested a package is, as it will be necessary to locate the inner package using the outer package's Content Index.</li>
<li>Alternative for example.com would be to include the JS library into its own package and sign it as part of example.com, but this is useful example on how the nested signed package looks like.</li>
<li>The nested package has been indented for illustration purposes but would not be in an actual package.</li>
</ol>
<div class="highlight highlight-text-html-basic"><pre>Package-Signature: NNejtdEjGnea4VTvO7A/x+5ucZm+pGPkQ1TD32oT3oKGhPWeF0hASWjxQOXvfX5+; algorithm=sha384; certificate=urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479
Content-Type: application/package
Content-Location: https://example.org/examplePack.pack
Link: &lt;/<span class="pl-ent">index</span>.<span class="pl-e">html</span>&gt;; rel=describedby
Link: &lt;<span class="pl-ent">https:</span>//<span class="pl-e">ajax</span>.<span class="pl-e">googleapis</span>.<span class="pl-e">com</span>/<span class="pl-e">packs</span>/<span class="pl-e">jquery</span>_3.<span class="pl-e">1</span>.<span class="pl-e">0</span>.<span class="pl-e">pack</span>&gt;; rel=package; scope=/ajax/libs/jquery/3.1.0
Link: &lt;<span class="pl-ent">urn:uuid:d479c10b-58cc-4243-97a5-0e02b2c3f47a</span>&gt;; rel=index; offset=12014/2048

--j38n02qryf9n0eqny8cq0
Content-Location: /index.html
Content-Type: text/html
&lt;<span class="pl-ent">head</span>&gt;
&lt;<span class="pl-ent">script</span> <span class="pl-e">src</span>=<span class="pl-s"><span class="pl-pds">"</span>https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js<span class="pl-pds">"</span></span>&gt;&lt;/<span class="pl-ent">script</span>&gt;
&lt;<span class="pl-ent">body</span>&gt;
...
&lt;/<span class="pl-ent">body</span>&gt;
--j38n02qryf9n0eqny8cq0
	Package-Signature: A/xtdEjGnea4VTvNNejO7+5ucZm+pGPkQ1TD32oT3oKGhPWeF0hASWjx5+QOXvfX; algorithm=sha384; certificate=urn:uuid:7af4c10b-58cc-4372-8567-0e02b2c3dabc
	Content-Location: https://ajax.googleapis.com/packs/jquery_3.1.0.pack
	Content-Type: application/package
	Link: &lt;<span class="pl-ent">urn:uuid:aaf4c10b-58cc-4372-8567-0e02b2c3daaa</span>&gt;; rel=index; offset=12014/2048

	--klhfdlifhhiorefioeri1
	Content-Location: /ajax/libs/jquery/3.1.0/jquery.min.js
	Content-Type: application/javascript

	... some JS code ...
	--klhfdlifhhiorefioeri1   (This is Content Index for ajax.googleapis.com subpackage)
	Content-Location: urn:uuid:aaf4c10b-58cc-4372-8567-0e02b2c3daaa
	Content-Type: application/package.index

	/ajax/libs/jquery/3.1.0/jquery.min.js sha384-3dEjGnea4A/xtGPkQ1TDVTvNNejO7+5ucZm+pASWjx5+QOXvfX2oT3oKGhPWeF0h 102 3876
	... other entries ...
	--klhfdlifhhiorefioeri1
	Content-Location: urn:uuid:7af4c10b-58cc-4372-8567-0e02b2c3dabc
	Content-Type: application/pkix-cert

	... certificate for ajax.googleapi.com ...
	--klhfdlifhhiorefioeri1--
--j38n02qryf9n0eqny8cq0   (This is Content Index for example.com package)
Content-Location: urn:uuid:d479c10b-58cc-4243-97a5-0e02b2c3f47a
Content-Type: application/package.index

/index.html sha384-WeF0h3dEjGnea4ANejO7+5/xtGPkQ1TDVTvNucZm+pASWjx5+QOXvfX2oT3oKGhP 153 215
--j38n02qryf9n0eqny8cq0
Content-Location: urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479
Content-Type: application/pkcs7-mime

... certificate for example.com ...
--j38n02qryf9n0eqny8cq0--
</pre></div>
<h2><a href="#faq" aria-hidden="true" class="anchor" id="user-content-faq"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>FAQ</h2>
<h3><a href="#why-signing-but-not-encryption-https-provides-both" aria-hidden="true" class="anchor" id="user-content-why-signing-but-not-encryption-https-provides-both"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Why signing but not encryption? HTTPS provides both...</h3>
<p>The signing part of the proposal addresses <em>integrity</em> and <em>authenticity</em> aspects of the security. It is enough for the resource to be signed to validate it belongs to the origin corresponding to the certificate used. This, in turn allows the browsers and other user agents to afford the 'origin treatment' to the resources in the package, because there is a guarantee that those resources were not tampered with.</p>
<h3><a href="#what-about-certificate-revocation-many-use-cases-assume-package-is-validated-while-offline" aria-hidden="true" class="anchor" id="user-content-what-about-certificate-revocation-many-use-cases-assume-package-is-validated-while-offline"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>What about certificate revocation? Many use cases assume package is validated while offline.</h3>
<p>Indeed, as is the case with web browsers as well, certificate revocation is not instant on the web. In case of packages that are consumed while device is offline (maybe for a long period of time), the revocation of the certificate may not reach device promptly. But then again, if the web resources were stored in a browser cache, or if pages were Saved As, and used when device is offline, there would be no way to receive the CRL or use OCSP for real-time certificate validation as well. Once the device is online, the certificate should be validated using best practices of the user agent and access revoked if needed.</p>
<h3><a href="#is-that-package-signature-a-mac-or-hmac-of-the-package" aria-hidden="true" class="anchor" id="user-content-is-that-package-signature-a-mac-or-hmac-of-the-package"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Is that Package-Signature a MAC or HMAC of the package?</h3>
<p>No, we don't use what commonly is called <a href="https://en.wikipedia.org/wiki/Message_authentication_code" rel="nofollow">MAC</a> here because the packages are not encrypted (and there is no strong use case motivating such encryption) so there is no symmetrical key and therefore the traditional concept of MAC is not applicable. However, the Package-Signature contains a <a href="https://en.wikipedia.org/wiki/Digital_signature" rel="nofollow">Digital Signature</a> which is a hash of the (Content Index + Package Header) signed with a private key of the publisher. The Content Index contains hashes for each resource part included in the package, so the Package-Signature validates each resource part as well.</p>
<h3><a href="#does-the-package-signature-cover-all-the-bits-of-the-package" aria-hidden="true" class="anchor" id="user-content-does-the-package-signature-cover-all-the-bits-of-the-package"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Does the Package-Signature cover all the bits of the package?</h3>
<p>Yes, the Package Header and Content Index are hashed and this hash, signed, is provided in the Package-Signature header. The Content Index, in turn, has hashes for all resources (Header+Body) so all bits of package are covered.</p>
<h3><a href="#are-subpackages-signed-as-well" aria-hidden="true" class="anchor" id="user-content-are-subpackages-signed-as-well"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Are subpackages signed as well?</h3>
<p>No. If a package contains subpackages, those subpackages are not covered by the package's signature or hashes and have to have their own Package-Signature header if they need to be signed. This reflects the fact that subpackages typically group resources from a different origin, with their own certificate. The [sub]packages are the units that are typically package resources from their respective origins and are therefore separately signed.</p>
<h3><a href="#what-happens-if-urnuuid-urls-collide" aria-hidden="true" class="anchor" id="user-content-what-happens-if-urnuuid-urls-collide"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>What happens if urn:uuid: URLs collide?</h3>
<p>Since they are Version 4 UUIDs, the chances of them colliding are vanishingly small.</p>
<h3><a href="#what-if-a-publisher-signed-a-package-with-a-js-library-and-later-discovered-a-vulnerability-in-it-on-the-web-they-would-just-replace-the-js-file-with-an-updated-one-what-is-the-story-in-case-of-packages" aria-hidden="true" class="anchor" id="user-content-what-if-a-publisher-signed-a-package-with-a-js-library-and-later-discovered-a-vulnerability-in-it-on-the-web-they-would-just-replace-the-js-file-with-an-updated-one-what-is-the-story-in-case-of-packages"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>What if a publisher signed a package with a JS library, and later discovered a vulnerability in it. On the Web, they would just replace the JS file with an updated one. What is the story in case of packages?</h3>
<p>The expiration headers in Package Headers section prescribe the 'useful lifetime' of the package, with UA optionally indicating the 'stale' state to the user and asking to upgrade, or automatically fetching a new one. While offline, the expiration may be ignored (not unlike Cache-Control: no-cache) but once user is online, the UA should verify both the certificate and if the package Content-Location contains an updated package (per Package Headers section) - and replace the package if necessary. In general, if the device is online and the package is expired, and the original location has updated package, the UA should obtain a new one (details TBD).</p>
<h3><a href="#why-is-there-a-content-index-that-specifies-where-each-part-is-and-also-mime-like-boundaries-that-separate-parts-in-the-package" aria-hidden="true" class="anchor" id="user-content-why-is-there-a-content-index-that-specifies-where-each-part-is-and-also-mime-like-boundaries-that-separate-parts-in-the-package"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Why is there a Content Index that specifies where each part is, and also MIME-like 'boundaries' that separate parts in the package?</h3>
<p>This is due to two main use cases of package loading:</p>
<ol>
<li>Loading the package from Web as part of the page or some other resource. In this case, the package is streamed from the server and <strong>boundaries</strong> allow to parse the package as it comes in and start using subresources as fast as possible. If the package has to be signed though, the package in its entirety has to be loaded first.</li>
<li>Loading a (potentially large) package offline. In that case, it is important to provide a fast access to subresources as they are requested, w/o unpacking the package (it takes double the storage at least to unpack and significant time). Using direct byte-offset Content Index allows to directly access resources in a potentially large package.</li>
</ol>
<h3><a href="#does-the-package-supply-a-full-chain-of-certificates-to-a-known-ca-root" aria-hidden="true" class="anchor" id="user-content-does-the-package-supply-a-full-chain-of-certificates-to-a-known-ca-root"><svg aria-hidden="true" class="octicon octicon-link" version="1.1" viewbox="0 0 16 16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"/></svg></a>Does the package supply a full chain of certificates to a known CA root?</h3>
<p>Not necessarily. Different devices have different sets of roots in their trust
stores, so there is not a single "correct" set of certificates to send that will
work best for all clients. Instead, for compatibility, packages may need to
include a set of certificates from which chains can be built to multiple roots,
or rely on clients to dynamically fetch additional intermediates when needed.</p>
<p>This becomes a tradeoff between the package size vs the set of clients that can
validate the signature offline. We expect that packaging tools will allow their
users to configure this tradeoff in appropriate ways.</p>