A place to cache linked articles (think custom and personal wayback machine)
您最多选择25个主题 主题必须以字母或数字开头,可以包含连字符 (-),并且长度不得超过35个字符

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747
  1. title: Web Packaging Format Explainer
  2. url: https://github.com/WICG/webpackage/blob/master/explainer.md
  3. hash_url: 7fb7e8f5fb68a4ddc308b112a7f8d09f
  4. <p>This document describes use cases for a new package format for web sites and
  5. applications and outlines such a format. It replaces the
  6. <del><a href="https://w3ctag.github.io/packaging-on-the-web/" rel="nofollow">W3C TAG's Web Packaging Draft</a></del>.
  7. It serves similar role as typical "Introduction" or "Using" and other
  8. non-normative sections of specs.</p>
  9. <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>
  10. <p>Some new use cases for Web technology have motivated thinking about a multi-resource packaging format. Those new opportunities include:</p>
  11. <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>
  12. <p>Local sharing is quite popular, especially in Emerging Markets countries, due to
  13. cost and limitations on cellular data and relatively spotty WiFi availability.
  14. It is typically done over local Bluetooth/WiFi, by either built-in OS features
  15. like <a href="https://en.wikipedia.org/wiki/Android_Beam" rel="nofollow">Android Beam</a> or with popular
  16. 3-rd party apps, such as
  17. <a href="https://play.google.com/store/apps/details?id=com.lenovo.anyshare.gps" rel="nofollow">ShareIt</a>
  18. or <a href="https://play.google.com/store/apps/details?id=cn.xender" rel="nofollow">Xender</a>).
  19. Typically, the locally stored media files and apps (APK files for Android for
  20. example) are shared this way. Extending sharing to bundles of content and web
  21. apps (Progressive Web Apps in particular) opens up new possibilities:</p>
  22. <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>
  23. <p>Any client can snapshot the page they're currently reading. This is currently
  24. done mostly by capturing a screenshot or saving into a browser-specific format
  25. like <a href="https://tools.ietf.org/html/rfc2557" rel="nofollow">MHTML</a>
  26. or <a href="https://en.wikipedia.org/wiki/Webarchive" rel="nofollow">Web Archive</a>, but these only
  27. support at most a single page per archive, and the second
  28. set <a href="https://xkcd.com/927/" rel="nofollow">aren't supported by other browsers</a>.</p>
  29. <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>
  30. <p>If the original origin signs a package, the contents can get full access to
  31. browser state and network requests for that origin. This lets people share full
  32. PWAs peer-to-peer.</p>
  33. <p>Local sharing tends to be popular where connectivity to the web is expensive:
  34. each byte costs money. This means the client may be stuck with an outdated
  35. version of a package for a significant amount of time, including that package's
  36. vulnerabilities. It may be feasible to periodically check for OCSP notification
  37. that a package's certificate has been revoked. We also need to design a cheap
  38. notification that the package is critically vulnerable and needs to be disabled
  39. until it can be updated.</p>
  40. <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>
  41. <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>
  42. <p>Physical web beacons may be located in a place that has no connectivity, and
  43. their owner may only visit to update them as often as their battery needs
  44. replacement: annually or less often. This leaves a large window during which a
  45. certificate could be compromised or a package could get out of date. We think
  46. there's no way to prevent a client from trusting its initial download of a
  47. package signed by a compromised certificate. When the client gets back to a
  48. public network, it should attempt to validate both the certificate and the
  49. package using the mechanisms alluded to under <a href="#local-sharing">Local Sharing</a>.</p>
  50. <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>
  51. <p>Content distributors can provide the service of hosting web content that should
  52. be delivered at scale. This includes both hosting subresources (JS libraries,
  53. images) as well as entire content (<a href="https://developers.google.com/amp/cache/overview" rel="nofollow">Google
  54. AMP</a>) on a network of servers,
  55. often provided as a service by 3rd party. Unfortunately, the origin-based
  56. security model of the Web limits the ways 3rd-party caches/servers can be used.
  57. For example in the case of hosting JS subresources, the original document must
  58. explicitly trust the distributor's origin to serve the trusted script. The user
  59. agent must use protocol-based means to verify the subresource is coming from the
  60. trusted distributor. Another example is a content distributor that caches the
  61. whole content. Because the origin of the distributor is different from the
  62. origin of the site, the browser normally can't afford the origin treatment of
  63. the site to the loaded content. Look at how an article from USA Today is
  64. represented:</p>
  65. <p><a href="/WICG/webpackage/blob/master/buick.png" target="_blank"><img align="center" src="/WICG/webpackage/raw/master/buick.png"/></a></p>
  66. <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>
  67. <ul>
  68. <li>Can't request permissions</li>
  69. <li>Can't be added to homescreen</li>
  70. </ul>
  71. <p>Packages served to content distributors can staple an OCSP response and have a
  72. short expiration time, avoiding the problems with outdated packages under "Local
  73. Sharing".</p>
  74. <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>
  75. <p>See
  76. <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>
  77. <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>
  78. <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>
  79. <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>
  80. <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>
  81. <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>
  82. <ol>
  83. <li>Index of content to facilitate local resource fetching from the package.</li>
  84. <li>Package manifests that can refer to sub-package manifests to allow resources
  85. from multiple origins.</li>
  86. <li>Signature block, to cryptographically sign the content of the package.</li>
  87. <li>Removed the
  88. <a href="https://w3ctag.github.io/packaging-on-the-web/#fragment-identifiers" rel="nofollow">fragment-based URL schema</a>
  89. from the spec as it's complex with limited use cases.</li>
  90. </ol>
  91. <p>Note that this is just an explainer, <strong>not a specification</strong>. We'll add more
  92. precision when we translate it to a spec.</p>
  93. <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>
  94. <p>The package is a <a href="https://tools.ietf.org/html/rfc7049" rel="nofollow">CBOR-encoded data item</a>
  95. with MIME type <code>application/package+cbor</code>. It logically contains a flat sequence
  96. of resources represented as HTTP responses. The package also includes metadata
  97. such as a manifest and an index to let consumers validate the resources and
  98. access them directly.</p>
  99. <p>The overall structure of the item is described by the following
  100. <a href="https://tools.ietf.org/html/draft-greevenbosch-appsawg-cbor-cddl" rel="nofollow">CDDL</a>:</p>
  101. <pre lang="cddl"><code>webpackage = [
  102. magic1: h'F0 9F 8C 90 F0 9F 93 A6', ; 🌐📦 in UTF-8.
  103. section-offsets: { * (($section-name .within tstr) =&gt; offset) },
  104. sections: ({ * $$section }) .within ({ * $section-name =&gt; any }),
  105. length: uint, ; Total number of bytes in the package.
  106. magic2: h'F0 9F 8C 90 F0 9F 93 A6', ; 🌐📦 in UTF-8.
  107. ]
  108. ; Offsets are measured from the first byte of the webpackage item to the first
  109. ; byte of the target item.
  110. offset = uint
  111. </code></pre>
  112. <p>Each section-offset points to a section with the same key, by holding the byte
  113. offset from the start of the webpackage item to the start of the section's name
  114. item.</p>
  115. <p>The length holds the total length in bytes of the <code>webpackage</code> item and must be
  116. encoded in the uint64_t format, which makes it possible to build self-extracting
  117. executables by appending a normal web package to the extractor executable.</p>
  118. <p>The defined section types are:</p>
  119. <ul>
  120. <li><a href="#main-content"><code>"indexed-content"</code></a>: The only required section.
  121. Maps resource keys (URLs possibly extended with HTTP headers) to
  122. HTTP2 responses. The mapping uses byte offsets to allow random
  123. access to any resource.</li>
  124. <li><a href="#manifest"><code>"manifest"</code></a>: Validates that resources came from the expected
  125. source. May refer to other manifests among the responses. If this section
  126. isn't provided, the resources are un-signed and can be loaded as untrusted
  127. data.</li>
  128. </ul>
  129. <p>More sections may be defined later. If an unexpected section is encountered, it
  130. is ignored.</p>
  131. <p>Note that this top-level information is <em>not signed</em>, and so can't be trusted.
  132. Only information in the manifest and below can be trusted.</p>
  133. <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>
  134. <p>The main content of a package is an index of HTTP requests pointing to HTTP
  135. responses. These request/response pairs hold the manifests of sub-packages and
  136. the resources in the package and all of its sub-packages. Both the requests and
  137. responses can appear in any order, usually chosen to optimize loading while the
  138. package is streamed.</p>
  139. <pre lang="cddl"><code>$section-name /= "indexed-content"
  140. $$section //= ("indexed-content" =&gt; [
  141. index: [* [resource-key, offset, ? length: uint] ],
  142. responses: [* [response-headers: http-headers, body: bstr]],
  143. ])
  144. resource-key = uri / http-headers
  145. ; http-headers is a byte string in HPACK format (RFC7541).
  146. ; The dynamic table begins empty for each instance of http-headers.
  147. http-headers = bstr
  148. </code></pre>
  149. <p>A <code>uri</code> <code>resource-key</code> is equivalent to an <code>http-headers</code> block with ":method"
  150. set to "GET" and with ":scheme", ":authority", and ":path" headers set from the
  151. URI as described in
  152. <a href="https://tools.ietf.org/html/rfc7540#section-8.1.2.3" rel="nofollow">RFC7540 section 8.1.2.3</a>.</p>
  153. <p>As an optimization, the <code>resource-key</code>s in the index store relative instead of
  154. absolute URLs. Each entry is resolved relative to the resolved version of the
  155. previous entry.</p>
  156. <p>TODO: Consider random access into large indices.</p>
  157. <p>In addition to the CDDL constraints:</p>
  158. <ul>
  159. <li>All byte strings must use a definite-length encoding so that package consumers
  160. can parse the content directly instead of concatenating the indefinite-length
  161. chunks first. The definite lengths here may also help a package consumer to
  162. quickly send resources to other threads for parsing.</li>
  163. <li>The index must not contain two resolved <code>resource-key</code>s with the
  164. same <a href="http://httpwg.org/specs/rfc7541.html#rfc.section.1.3" rel="nofollow">header list</a> after
  165. HPACK decoding.</li>
  166. <li>The <code>resource-key</code> must not contain any headers that aren't either ":method",
  167. ":scheme", ":authority", ":path", or listed in the
  168. <code>response-headers</code>'
  169. <a href="https://tools.ietf.org/html/rfc7231#section-7.1.4" rel="nofollow">"Vary" header</a>.</li>
  170. <li>The <code>resource-key</code> must contain at most one of each ":method", ":scheme",
  171. ":authority", ":path" header, in that order, before any other headers.
  172. Resolving the <code>resource-key</code> fills in any missing pseudo-headers from that
  173. set, ensuring that all resolved keys have exactly one of each.</li>
  174. </ul>
  175. <p>The optional <code>length</code> field in the index entries is redundant with the length
  176. prefixes on the <code>response-headers</code> and <code>body</code> in the content, but it can be used
  177. to issue <a href="https://tools.ietf.org/html/rfc7233" rel="nofollow">Range requests</a> for responses
  178. that appear late in the <code>content</code>.</p>
  179. <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>
  180. <p>TODO: Now that this no longer contains
  181. a <a href="https://www.merriam-webster.com/dictionary/manifest#h3" rel="nofollow">manifest</a>,
  182. consider renaming it to something like "authenticity".</p>
  183. <p>A package's manifest contains some metadata for the
  184. package, <a href="#validating-resources">hashes</a> for all resources included in that
  185. package, and validity information for any <a href="#sub-packages">sub-packages</a> the
  186. package depends on. The manifest is signed, so that UAs can trust that it comes
  187. from its claimed origin.</p>
  188. <pre lang="cddl"><code>$section-name /= "manifest"
  189. $$section //= ("manifest" =&gt; signed-manifest)
  190. signed-manifest = {
  191. manifest: manifest,
  192. certificates: [+ certificate],
  193. signatures: [+ signature]
  194. }
  195. manifest = {
  196. metadata: manifest-metadata,
  197. resource-hashes: {* hash-algorithm =&gt; [hash-value]},
  198. ? subpackages: [* subpackage],
  199. }
  200. manifest-metadata = {
  201. date: time,
  202. origin: uri,
  203. * tstr =&gt; any,
  204. }
  205. ; From https://www.w3.org/TR/CSP3/#grammardef-hash-algorithm.
  206. hash-algorithm /= "sha256" / "sha384" / "sha512"
  207. ; Note that a hash value is not base64-encoded, unlike in CSP.
  208. hash-value = bstr
  209. ; X.509 format; see https://tools.ietf.org/html/rfc5280
  210. certificate = bstr
  211. signature = {
  212. ; RFC5280 says certificates can be identified by either the
  213. ; issuer-name-and-serial-number or by the subject key identifier. However,
  214. ; issuer names are complicated, and the subject key identifier only identifies
  215. ; the public key, not the certificate, so we identify certificates by their
  216. ; index in the certificates array instead.
  217. keyIndex: uint,
  218. ; Encoded as described in TLS 1.3,
  219. ; https://tlswg.github.io/tls13-spec/#signature-algorithms.
  220. signature: bstr,
  221. }
  222. </code></pre>
  223. <p>The metadata must include an absolute URL identifying
  224. the
  225. <a href="https://html.spec.whatwg.org/multipage/browsers.html#concept-origin" rel="nofollow">origin</a>
  226. vouching for the package and the date the package was created. It may contain
  227. more keys defined in <a href="https://www.w3.org/TR/appmanifest/" rel="nofollow">https://www.w3.org/TR/appmanifest/</a>.</p>
  228. <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>
  229. <p>The manifest is signed by a set of certificates, including at least one that is
  230. trusted to sign content from the
  231. manifest's
  232. <a href="https://html.spec.whatwg.org/multipage/browsers.html#concept-origin" rel="nofollow">origin</a>.
  233. Other certificates can sign to vouch for the package along other dimensions, for
  234. example that it was checked for malicious behavior by some authority.</p>
  235. <p>The signed sequence of bytes is the concatenation of the following byte strings.
  236. This matches the TLS1.3 format to avoid cross-protocol attacks when TLS
  237. certificates are used to sign manifests.</p>
  238. <ol>
  239. <li>A string that consists of octet 32 (0x20) repeated 64 times.</li>
  240. <li>A context string: the ASCII encoding of "Web Package Manifest".</li>
  241. <li>A single 0 byte which serves as a separator.</li>
  242. <li>The bytes of the <code>manifest</code> CBOR item.</li>
  243. </ol>
  244. <p>Each signature uses the <code>keyIndex</code> field to identify the certificate used to
  245. generate it.
  246. The <a href="https://tlswg.github.io/tls13-spec/#rfc.section.4.2.3" rel="nofollow">TLS 1.3 signing algorithm</a>
  247. is determined from the certificate's public key type:</p>
  248. <ul>
  249. <li>RSA, 2048 bits: rsa_pss_sha256</li>
  250. <li>secp256r1: ecdsa_secp256r1_sha256</li>
  251. <li>secp384r1: ecdsa_secp384r1_sha384</li>
  252. </ul>
  253. <p>The following key types are not supported, for the mentioned reason:</p>
  254. <ul>
  255. <li>secp521r1: <a href="https://crbug.com/477623" rel="nofollow">Chrome doesn't support this curve</a>, so
  256. certificates aren't using it on the web.</li>
  257. <li>ed25519 and ed448:
  258. The <a href="https://tools.ietf.org/html/draft-josefsson-tls-ed25519" rel="nofollow">RFC</a> for using
  259. these in certificates isn't yet final.</li>
  260. <li>RSA != 2048: Only 4096 has measurable usage, and it's very low.</li>
  261. </ul>
  262. <p>As a special case, if the package is being transferred from the manifest's
  263. origin under TLS, the UA may load it without checking that its own resources match
  264. the manifest. The UA still needs to validate resources provided by sub-manifests.</p>
  265. <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>
  266. <p>The <code>signed-manifest.certificates</code> array should contain enough
  267. X.509 certificates to chain from the signing certificates, using the rules
  268. in <a href="https://tools.ietf.org/html/rfc5280" rel="nofollow">RFC5280</a>, to roots trusted by all
  269. expected consumers of the package.</p>
  270. <p><a href="#sub-packages'">Sub-packages</a> manifests can contain their own certificates or
  271. can rely on certificates in their parent packages.</p>
  272. <p>Requirements on the
  273. certificates' <a href="https://tools.ietf.org/html/rfc5280#section-4.2.1.3" rel="nofollow">Key Usage</a>
  274. and <a href="https://tools.ietf.org/html/rfc5280#section-4.2.1.12" rel="nofollow">Extended Key Usage</a>
  275. are TBD. It may or may not be important to prevent TLS serving certificates from
  276. being used to sign packages, in order to prevent cross-protocol attacks.</p>
  277. <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>
  278. <p>For a resource to be valid, then for each <code>hash-algorithm =&gt; [hash-value]</code> in
  279. <code>resource-hashes</code>, the resource's hash using that algorithm needs to appear in
  280. that list of <code>hash-value</code>s. Like
  281. in <a href="https://www.w3.org/TR/SRI/#agility" rel="nofollow">Subresource Integrity</a>, the UA will only
  282. check one of these, but it's up to the UA which one.</p>
  283. <p>The hash of a resource is the hash of its Canonical CBOR encoding using the
  284. following CDDL. Headers are decompressed before being encoded and hashed.</p>
  285. <pre lang="cddl"><code>resource = [
  286. request: [
  287. ':method', bstr,
  288. ':scheme', bstr,
  289. ':authority', bstr,
  290. ':path', bstr,
  291. * (header-name, header-value: bstr)
  292. ],
  293. response-headers: [
  294. ':status', bstr,
  295. * (header-name, header-value: bstr)
  296. ],
  297. response-body: bstr
  298. ]
  299. # Headers must be lower-case ascii per
  300. # http://httpwg.org/specs/rfc7540.html#rfc.section.8.1.2, and only
  301. # pseudo-headers can include ":".
  302. header-name = bstr .regexp "[\x21-\x39\x3b-\x40\x5b-\x7e]+"
  303. </code></pre>
  304. <p>This differs from <a href="https://w3c.github.io/webappsec-subresource-integrity" rel="nofollow">SRI</a>,
  305. which only hashes the body. Note: This will usually prevent a package from
  306. relying on some of its contents being transferred as normal network responses,
  307. unless its author can guarantee the network won't change or reorder the headers.</p>
  308. <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>
  309. <p>A sub-package is represented by a <a href="#manifest">manifest</a> file in
  310. the <a href="#main-content"><code>"content"</code></a> section, which contains hashes of resources
  311. from another origin. The sub-package's resources are not otherwise distinguished
  312. from the rest of the resources in the package. Sub-packages can form an
  313. arbitrarily-deep tree.</p>
  314. <p>There are three possible forms of dependencies on sub-packages, of which we
  315. allow two. Because a sub-package is protected by its
  316. own <a href="#signatures">signature</a>, if the main package trusts the sub-package's
  317. server, it could avoid specifying a version of the sub-package at all. However,
  318. this opens the main package up to downgrade attacks, where the sub-package is
  319. replaced by an older, vulnerable version, so we don't allow this option.</p>
  320. <pre lang="cddl"><code>subpackage = [
  321. resource: resource-key,
  322. validation: {
  323. ? hash: hashes,
  324. ? notbefore: time,
  325. }
  326. ]
  327. </code></pre>
  328. <p>If the main package wants to load either the sub-package it was built with or
  329. any upgrade, it can specify the date of the original sub-package:</p>
  330. <pre lang="cbor-diag"><code>[32("https://example.com/loginsdk.package"), {"notbefore": 1(1486429554)}]
  331. </code></pre>
  332. <p>Constraining packages with their date makes it possible to link together
  333. sub-packages with common dependencies, even if the sub-packages were built at
  334. different times.</p>
  335. <p>If the main package wants to be certain it's loading the exact version of a
  336. sub-package that it was built with, it can constrain sub-package with a hash of its manifest:</p>
  337. <pre lang="cbor-diag"><code>[32("https://example.com/loginsdk.package"),
  338. {"hash": {"sha256": 22(b64'9qg0NGDuhsjeGwrcbaxMKZAvfzAHJ2d8L7NkDzXhgHk=')}}]
  339. </code></pre>
  340. <p>Note that because the sub-package may include sub-sub-packages by date, the top
  341. package may need to explicitly list those sub-sub-packages' hashes in order to
  342. be completely constrained.</p>
  343. <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>
  344. <p>Following are some example usages that correspond to these additions.
  345. The packages are written in
  346. <a href="https://tools.ietf.org/html/draft-greevenbosch-appsawg-cbor-cddl-10#appendix-G" rel="nofollow">CBOR's extended diagnostic notation</a>,
  347. with the extensions that:</p>
  348. <ol>
  349. <li><code>hpack({key:value,...})</code> is an <a href="https://tools.ietf.org/html/rfc7541" rel="nofollow">hpack</a>
  350. encoding of the described headers.</li>
  351. <li><code>DER(...)</code> is the DER encoding of a certificate described partially by the
  352. contents of the <code>...</code>.</li>
  353. </ol>
  354. <p>All examples are available in the <a href="/WICG/webpackage/blob/master/examples">examples</a> directory.</p>
  355. <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>
  356. <p>The example web site contains two HTML pages and an image. This is straightforward case, demonstrating the following:</p>
  357. <ol>
  358. <li>The <code>section-offsets</code> section declares one main section starting 1 byte into
  359. the <code>sections</code> item. (The 1 byte is the map header for the <code>sections</code> item.)</li>
  360. <li>The <code>index</code> maps <a href="http://httpwg.org/specs/rfc7541.html" rel="nofollow">hpack</a>-encoded
  361. headers for each resource to the start of that resource, measured relative to
  362. the start of the <code>responses</code> item.</li>
  363. <li>Each resource contains <code>date</code>/<code>expires</code> headers that specify when the
  364. resource can be used by UA, similar to HTTP 1.1
  365. <a href="https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.2" rel="nofollow">Expiration Model</a>.
  366. The actual expiration model is TBD and to be reflected in the spec. Note that
  367. we haven't yet described a way to set an <code>expires</code> value for the whole
  368. package at once.</li>
  369. <li>The length of the whole package always appears from the 10th to 18th bytes
  370. before the end of the package, in big-endian format.</li>
  371. </ol>
  372. <pre lang="cbor-diag"><code>['🌐📦',
  373. {"indexed-content": 1},
  374. {"indexed-content":
  375. [
  376. [ # Index.
  377. [hpack({
  378. :method: GET,
  379. :scheme: https
  380. :authority: example.com
  381. :path: /index.html
  382. }), 1],
  383. [hpack({
  384. :method: GET
  385. :scheme: https
  386. :authority: example.com
  387. :path: /otherPage.html
  388. }), 121],
  389. [hpack({
  390. :method: GET
  391. :scheme: https
  392. :authority: example.com
  393. :path: /images/world.png
  394. }), 243]
  395. ],
  396. [ # Resources.
  397. [
  398. hpack({
  399. :status: 200
  400. content-type: text/html
  401. date: Wed, 15 Nov 2016 06:25:24 GMT
  402. expires: Thu, 01 Jan 2017 16:00:00 GMT
  403. }),
  404. '&lt;body&gt;\n &lt;a href=\"otherPage.html\"&gt;Other page&lt;/a&gt;\n&lt;/body&gt;\n'
  405. ],
  406. [
  407. hpack({
  408. :status: 200
  409. content-type: text/html
  410. date: Wed, 15 Nov 2016 06:25:24 GMT
  411. expires: Thu, 01 Jan 2017 16:00:00 GMT
  412. }),
  413. '&lt;body&gt;\n Hello World! &lt;img src=\"images/world.png\"&gt;\n&lt;/body&gt;\n'
  414. ], [
  415. hpack({
  416. :status: 200
  417. content-type: image/png
  418. date: Wed, 15 Nov 2016 06:25:24 GMT
  419. expires: Thu, 01 Jan 2017 16:00:00 GMT
  420. }),
  421. '... binary png image ...'
  422. ]
  423. ]
  424. ]
  425. },
  426. 473, # Always 8 bytes long.
  427. '🌐📦'
  428. ]
  429. </code></pre>
  430. <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>
  431. <p>The example web site contains an HTML page and pulls a script from the
  432. well-known location (different origin). Note that there's no need to distinguish
  433. the resources from other origins vs the ones from the main origin. Since none of
  434. them are signed, the browser won't treat any as
  435. <a href="https://html.spec.whatwg.org/multipage/browsers.html#same-origin" rel="nofollow">same-origin</a>
  436. with their claimed origin.</p>
  437. <pre lang="cbor-diag"><code>['🌐📦',
  438. {"indexed-content": 1},
  439. {"indexed-content":
  440. [
  441. [
  442. [hpack({
  443. :method: GET
  444. :scheme: https
  445. :authority: example.com
  446. :path: /index.html
  447. }), 1],
  448. [hpack({
  449. :method: GET
  450. :scheme: https
  451. :authority: ajax.googleapis.com
  452. :path: /ajax/libs/jquery/3.1.0/jquery.min.js
  453. }), 179]
  454. ],
  455. [
  456. [
  457. hpack({
  458. :status: 200
  459. content-type: text/html
  460. date: Wed, 15 Nov 2016 06:25:24 GMT
  461. expires: Thu, 01 Jan 2017 16:00:00 GMT
  462. }),
  463. '&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'
  464. ],
  465. [
  466. hpack({
  467. :status: 200
  468. content-type: text/html
  469. date: Wed, 15 Nov 2016 06:25:24 GMT
  470. expires: Thu, 01 Jan 2017 16:00:00 GMT
  471. }),
  472. '... some JS code ...\n'
  473. ]
  474. ]
  475. ]
  476. },
  477. 396,
  478. '🌐📦'
  479. ]
  480. </code></pre>
  481. <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>
  482. <p>The example contains example.com/index.html. The package is signed by the
  483. example.com publisher, using the same private key that example.com uses for
  484. HTTPS. The signed package ensures the verification of the origin even if the
  485. package is stored in a local file or obtained via other insecure ways like HTTP,
  486. or hosted on another origin's server.</p>
  487. <p>Some interesting things to notice in this package:</p>
  488. <ol>
  489. <li>The <code>"manifest"</code> map contains <code>"certificates"</code> and <code>"signatures"</code> arrays
  490. describing how the manifest is signed.</li>
  491. <li>The signature identifies the first element of <code>"certificates"</code> as the signing
  492. certificate.</li>
  493. <li>The elements of <code>"certificates"</code> are
  494. DER-encoded <a href="https://tools.ietf.org/html/rfc5280" rel="nofollow">X.509 certificates</a>.
  495. The <a href="/WICG/webpackage/blob/master/go/webpack/testdata/pki/example.com.cert">signing certificate</a> is
  496. trusted for <code>example.com</code>, and that certificate chains,
  497. using <a href="/WICG/webpackage/blob/master/go/webpack/testdata/pki/intermediate1.cert">other elements</a> of
  498. <code>"certificates"</code>, to
  499. a <a href="/WICG/webpackage/blob/master/go/webpack/testdata/pki/root1.cert">trusted root certificate</a>. The chain
  500. is built and trusted in the same way as TLS chains during normal web
  501. browsing.</li>
  502. <li>The signature algorithm is determined by the signing certificate's public key
  503. type, <code>prime256v1</code>, and isn't encoded separately in the signature block.</li>
  504. <li>The manifest contains a <code>"resource-hashes"</code> block, which contains the hashes,
  505. using the SHA384 algorithm in this case, of all resources in the package.
  506. Unlike in
  507. <a href="https://w3c.github.io/webappsec-subresource-integrity/" rel="nofollow">Subresource Integrity</a>,
  508. the hashes include the request and response headers.</li>
  509. <li>The inclusion of a certificate chain makes it possible to validate the
  510. package offline. Browsers detect revoked certificates and packages with known
  511. vulnerabilities by looking for separately signed files containing OCSP and
  512. recency information, but this package does not demonstrate how to attach
  513. those.</li>
  514. </ol>
  515. <pre lang="cbor-diag"><code>[
  516. '🌐📦',
  517. {
  518. "manifest": 1,
  519. "indexed-content": 2057
  520. },
  521. {
  522. "manifest": {
  523. "manifest": {
  524. "metadata": {
  525. "date": 1(1494583200),
  526. "origin": 32("https://example.com")
  527. },
  528. "resource-hashes": {
  529. "sha384": [
  530. h'3C3A03F7C3FC99494F6AAA25C3D11DA3C0D7097ABBF5A9476FB64741A769984E8B6801E71BB085E25D7134287B99BAAB',
  531. h'5AA8B83EE331F5F7D1EF2DF9B5AFC8B3A36AEC953F2715CE33ECCECD58627664D53241759778A8DC27BCAAE20F542F9F',
  532. h'D5B2A3EA8FE401F214DA8E3794BE97DE9666BAF012A4B515B8B67C85AAB141F8349C4CD4EE788C2B7A6D66177BC68171'
  533. ]
  534. }
  535. },
  536. "signatures": [
  537. {
  538. "keyIndex": 0,
  539. "signature": h'3044022015B1C8D46E4C6588F73D9D894D05377F382C4BC56E7CDE41ACEC1D81BF1EBF7E02204B812DACD001E0FD4AF968CF28EC6152299483D6D14D5DBE23FC1284ABB7A359'
  540. }
  541. ],
  542. "certificates": [
  543. DER(
  544. Certificate:
  545. ...
  546. Signature Algorithm: ecdsa-with-SHA256
  547. Issuer: C=US, O=Honest Achmed's, CN=Honest Achmed's Test Intermediate CA
  548. Validity
  549. Not Before: May 10 00:00:00 2017 GMT
  550. Not After : May 18 00:10:36 2018 GMT
  551. Subject: C=US, O=Test Example, CN=example.com
  552. Subject Public Key Info:
  553. Public Key Algorithm: id-ecPublicKey
  554. Public-Key: (256 bit)
  555. pub:
  556. ...
  557. ASN1 OID: prime256v1
  558. ...
  559. ),
  560. DER(
  561. Certificate:
  562. ...
  563. Signature Algorithm: sha256WithRSAEncryption
  564. Issuer: C=US, O=Honest Achmed's, CN=Honest Achmed's Test Root CA
  565. Validity
  566. Not Before: May 10 00:00:00 2017 GMT
  567. Not After : May 18 00:10:36 2018 GMT
  568. Subject: C=US, O=Honest Achmed's, CN=Honest Achmed's Test Intermediate CA
  569. Subject Public Key Info:
  570. Public Key Algorithm: id-ecPublicKey
  571. Public-Key: (521 bit)
  572. pub:
  573. ...
  574. ASN1 OID: secp521r1
  575. ...
  576. )
  577. ]
  578. },
  579. "indexed-content": [
  580. [
  581. [ hpack({
  582. :method: GET
  583. :scheme: https
  584. :authority: example.com
  585. :path: /index.html
  586. }), 1]
  587. [ hpack({
  588. :method: GET
  589. :scheme: https
  590. :authority: example.com
  591. :path: /otherPage.html
  592. }), 121],
  593. [ hpack({
  594. :method: GET
  595. :scheme: https
  596. :authority: example.com
  597. :path: /images/world.png
  598. }), 243]
  599. ],
  600. ],
  601. [
  602. [ hpack({
  603. :status: 200
  604. content-type: text/html
  605. date: Wed, 15 Nov 2016 06:25:24 GMT
  606. expires: Thu, 01 Jan 2017 16:00:00 GMT
  607. }),
  608. '&lt;body&gt;\n &lt;a href=\"otherPage.html\"&gt;Other page&lt;/a&gt;\n&lt;/body&gt;\n'
  609. ]
  610. [ hpack({
  611. :status: 200
  612. content-type: text/html
  613. date: Wed, 15 Nov 2016 06:25:24 GMT
  614. expires: Thu, 01 Jan 2017 16:00:00 GMT
  615. }),
  616. '&lt;body&gt;\n Hello World! &lt;img src=\"images/world.png\"&gt;\n&lt;/body&gt;\n'
  617. ],
  618. [ hpack({
  619. :status: 200
  620. content-type: image/png
  621. date: Wed, 15 Nov 2016 06:25:24 GMT
  622. expires: Thu, 01 Jan 2017 16:00:00 GMT
  623. }),
  624. '... binary png image ...'
  625. ]
  626. ]
  627. ]
  628. },
  629. 2541,
  630. '🌐📦'
  631. ]
  632. </code></pre>
  633. <p>The process of validation:</p>
  634. <ol>
  635. <li>Verify that certificates identified by signature elements chain to trusted roots.</li>
  636. <li>Find the subset of the signatures that correctly sign the manifest's bytes
  637. using their identified certificates' public keys.</li>
  638. <li>Parse the manifest and find its claimed origin.</li>
  639. <li>Verify that at least one correct signature identifies a certificate that's
  640. trusted for use by that origin.</li>
  641. <li>When loading a resource, pick the strongest hash function in the
  642. <code>"resource-hashes"</code> map, and use that to hash the Canonical CBOR
  643. representation of its request headers, response headers, and body. Verify
  644. that the resulting digest appears in that array in the <code>"resource-hashes"</code>
  645. map.</li>
  646. </ol>
  647. <p><strong><em>Examples below here are out of date</em></strong></p>
  648. <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>
  649. <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>
  650. <p>Important notes:</p>
  651. <ol>
  652. <li>Nested package with the JS library, obtained from googleapis.com, is separately signed by googleapis.com</li>
  653. <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>
  654. <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>
  655. <li>The nested package has been indented for illustration purposes but would not be in an actual package.</li>
  656. </ol>
  657. <div class="highlight highlight-text-html-basic"><pre>Package-Signature: NNejtdEjGnea4VTvO7A/x+5ucZm+pGPkQ1TD32oT3oKGhPWeF0hASWjxQOXvfX5+; algorithm=sha384; certificate=urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479
  658. Content-Type: application/package
  659. Content-Location: https://example.org/examplePack.pack
  660. Link: &lt;/<span class="pl-ent">index</span>.<span class="pl-e">html</span>&gt;; rel=describedby
  661. 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
  662. Link: &lt;<span class="pl-ent">urn:uuid:d479c10b-58cc-4243-97a5-0e02b2c3f47a</span>&gt;; rel=index; offset=12014/2048
  663. --j38n02qryf9n0eqny8cq0
  664. Content-Location: /index.html
  665. Content-Type: text/html
  666. &lt;<span class="pl-ent">head</span>&gt;
  667. &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;
  668. &lt;<span class="pl-ent">body</span>&gt;
  669. ...
  670. &lt;/<span class="pl-ent">body</span>&gt;
  671. --j38n02qryf9n0eqny8cq0
  672. Package-Signature: A/xtdEjGnea4VTvNNejO7+5ucZm+pGPkQ1TD32oT3oKGhPWeF0hASWjx5+QOXvfX; algorithm=sha384; certificate=urn:uuid:7af4c10b-58cc-4372-8567-0e02b2c3dabc
  673. Content-Location: https://ajax.googleapis.com/packs/jquery_3.1.0.pack
  674. Content-Type: application/package
  675. Link: &lt;<span class="pl-ent">urn:uuid:aaf4c10b-58cc-4372-8567-0e02b2c3daaa</span>&gt;; rel=index; offset=12014/2048
  676. --klhfdlifhhiorefioeri1
  677. Content-Location: /ajax/libs/jquery/3.1.0/jquery.min.js
  678. Content-Type: application/javascript
  679. ... some JS code ...
  680. --klhfdlifhhiorefioeri1 (This is Content Index for ajax.googleapis.com subpackage)
  681. Content-Location: urn:uuid:aaf4c10b-58cc-4372-8567-0e02b2c3daaa
  682. Content-Type: application/package.index
  683. /ajax/libs/jquery/3.1.0/jquery.min.js sha384-3dEjGnea4A/xtGPkQ1TDVTvNNejO7+5ucZm+pASWjx5+QOXvfX2oT3oKGhPWeF0h 102 3876
  684. ... other entries ...
  685. --klhfdlifhhiorefioeri1
  686. Content-Location: urn:uuid:7af4c10b-58cc-4372-8567-0e02b2c3dabc
  687. Content-Type: application/pkix-cert
  688. ... certificate for ajax.googleapi.com ...
  689. --klhfdlifhhiorefioeri1--
  690. --j38n02qryf9n0eqny8cq0 (This is Content Index for example.com package)
  691. Content-Location: urn:uuid:d479c10b-58cc-4243-97a5-0e02b2c3f47a
  692. Content-Type: application/package.index
  693. /index.html sha384-WeF0h3dEjGnea4ANejO7+5/xtGPkQ1TDVTvNucZm+pASWjx5+QOXvfX2oT3oKGhP 153 215
  694. --j38n02qryf9n0eqny8cq0
  695. Content-Location: urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479
  696. Content-Type: application/pkcs7-mime
  697. ... certificate for example.com ...
  698. --j38n02qryf9n0eqny8cq0--
  699. </pre></div>
  700. <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>
  701. <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>
  702. <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>
  703. <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>
  704. <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>
  705. <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>
  706. <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>
  707. <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>
  708. <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>
  709. <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>
  710. <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>
  711. <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>
  712. <p>Since they are Version 4 UUIDs, the chances of them colliding are vanishingly small.</p>
  713. <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>
  714. <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>
  715. <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>
  716. <p>This is due to two main use cases of package loading:</p>
  717. <ol>
  718. <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>
  719. <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>
  720. </ol>
  721. <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>
  722. <p>Not necessarily. Different devices have different sets of roots in their trust
  723. stores, so there is not a single "correct" set of certificates to send that will
  724. work best for all clients. Instead, for compatibility, packages may need to
  725. include a set of certificates from which chains can be built to multiple roots,
  726. or rely on clients to dynamically fetch additional intermediates when needed.</p>
  727. <p>This becomes a tradeoff between the package size vs the set of clients that can
  728. validate the signature offline. We expect that packaging tools will allow their
  729. users to configure this tradeoff in appropriate ways.</p>