idnits 2.17.1 draft-soilandreyes-app-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 22, 2018) is 2257 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 611 ** Obsolete normative reference: RFC 2279 (Obsoleted by RFC 3629) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) == Outdated reference: A later version (-17) exists of draft-kunze-bagit-14 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Soiland-Reyes 3 Internet-Draft The University of Manchester 4 Intended status: Informational M. Caceres 5 Expires: July 26, 2018 Mozilla Corporation 6 January 22, 2018 8 Application and Packaging Pointer (app) URI scheme 9 draft-soilandreyes-app-04 11 Abstract 13 This specification proposes the Application and Packaging Pointer URI 14 scheme "app". 16 app URIs can be used to consume or reference hypermedia resources 17 bundled inside a file archive or an application package, as well as 18 to resolve URIs for archive resources within a programmatic 19 framework. 21 This URI scheme provides mechanisms to generate a unique base URI to 22 represent the root of the archive, so that relative URI references in 23 a bundled resource can be resolved within the archive without having 24 to extract the archive content on the local file system. 26 An app URI can be used for purposes of isolation (e.g. when consuming 27 multiple archives), security constraints (avoiding "climb out" from 28 the archive), or for externally identiyfing sub-resources referenced 29 by hypermedia formats. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on July 26, 2018. 48 Copyright Notice 50 Copyright (c) 2018 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents 55 (https://trustee.ietf.org/license-info) in effect on the date of 56 publication of this document. Please review these documents 57 carefully, as they describe your rights and restrictions with respect 58 to this document. Code Components extracted from this document must 59 include Simplified BSD License text as described in Section 4.e of 60 the Trust Legal Provisions and are provided without warranty as 61 described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Background . . . . . . . . . . . . . . . . . . . . . . . . . 3 67 3. Scheme syntax . . . . . . . . . . . . . . . . . . . . . . . . 4 68 3.1. Authority . . . . . . . . . . . . . . . . . . . . . . . . 4 69 3.2. Path . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 4. Scheme semantics . . . . . . . . . . . . . . . . . . . . . . 5 71 4.1. Authority semantics . . . . . . . . . . . . . . . . . . . 5 72 4.2. Path semantics . . . . . . . . . . . . . . . . . . . . . 7 73 4.3. Resolution protocol . . . . . . . . . . . . . . . . . . . 7 74 4.4. Resolving from a .well-known endpoint . . . . . . . . . . 8 75 5. Encoding considerations . . . . . . . . . . . . . . . . . . . 8 76 6. Interoperability considerations . . . . . . . . . . . . . . . 9 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 78 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 79 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 80 9.1. Normative References . . . . . . . . . . . . . . . . . . 11 81 9.2. Informative References . . . . . . . . . . . . . . . . . 12 82 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 13 83 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 84 A.1. Sharing using app names . . . . . . . . . . . . . . . . . 14 85 A.2. Sandboxing . . . . . . . . . . . . . . . . . . . . . . . 15 86 A.3. Origin-based . . . . . . . . . . . . . . . . . . . . . . 16 87 A.4. Hash-based . . . . . . . . . . . . . . . . . . . . . . . 17 88 A.5. Archives that are not files . . . . . . . . . . . . . . . 17 89 A.6. Linked Data containers which are not on the web . . . . . 18 90 A.7. Resolution of packaged resources . . . . . . . . . . . . 19 91 Appendix B. History . . . . . . . . . . . . . . . . . . . . . . 19 92 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 94 1. Introduction 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 98 document are to be interpreted as described in [RFC2119]. 100 For the purpose of this specification, an *archive* is a collection 101 of sub-resources addressable by name or path. This definition covers 102 typical archive file formats like ".zip" or "tar.gz" and derived 103 "+zip" media types [RFC6839], but also non-file resource packages 104 like an LDP Container [W3C.REC-ldp-20150226], an installed Web App 105 [W3C.WD-appmanifest-20180118], or a BagIt folder structure 106 [I-D.draft-kunze-bagit-14]. 108 For brevity, the term _archive_ is used throughout this 109 specification, although from the above it can also mean a 110 _container_, _application_ or _package_. 112 2. Background 114 Mobile and Web Applications ("apps") may bundle resources such as 115 stylesheets with relative URI references to scripts, images and 116 fonts. Resolving such resources within URI handling frameworks may 117 require generating absolute URIs and applying Same-Origin [RFC6454] 118 security policies separately for each app. 120 Applications that are accessing resources bundled inside an archive 121 (e.g. "zip" or "tar.gz" file) can struggle to consume hypermedia 122 content types that use relative URI references [RFC3986] such as 123 "../css/", as it is challenging to determine the base URI in a 124 consistent fashion. 126 Frequently the archive must be unpacked locally to synthesize base 127 URIs like "file:///tmp/a1b27ae03865/" to represent the root of the 128 archive. Such URIs are temporary, might not be globally unique, and 129 could be vulnerable to attacks such as "climbing out" of the root 130 directory. 132 An archive containing multiple HTML or Linked Data resources, such as 133 in a BagIt archive [I-D.draft-kunze-bagit-14], may be using relative 134 URIs to cross-reference constituent files. 136 Consumptions of archives might be performed in memory or through a 137 common framework, abstracting away any local file location. 139 Consumption of an archive with a consistent base URL should be 140 possible no matter from which location it was retrieved, or on which 141 device it is inspected. 143 When consuming multiple archives from untrusted sources it would be 144 beneficial to have a Same Origin policy [RFC6454] so that relative 145 hyperlinks can't escape the particular archive. 147 The "file:" URI scheme [RFC8089] can be ill-suited for purposes such 148 as above, where a location-independent URI scheme is more flexible, 149 secure and globally unique. 151 3. Scheme syntax 153 The "app" URI scheme follows the [RFC3986] syntax for hierarchical 154 URIs according to the following productions: 156 URI = scheme ":" app-specific [ "#" fragment ] 158 scheme = "app" 160 app-specific = "//" app-authority [ path-absolute ] [ "?" query ] 162 The "app-authority" component provides a unique identifier for the 163 opened archive. See Section 3.1 for details. 165 The "path-absolute" component provides the absolute path of a 166 resource (e.g. a file or directory) within the archive. See 167 Section 3.2 for details. 169 The "query" component MAY be used, but its semantics is undefined by 170 this specification. 172 The "fragment" component MAY be used by implementations according to 173 [RFC3986] and the implied media type [RFC2046] of the resource at the 174 path. This specification does not specify how to determine the media 175 type. 177 3.1. Authority 179 The purpose of the "authority" component in an app URI is to build a 180 unique base URI for a particular archive. The authority is NOT 181 intended to be resolvable without former knowledge of the archive. 183 The authority of an app URI MUST be valid according to these 184 productions: 186 app-authority = uuid | ni | name | authority 187 uuid = "uuid," UUID 188 ni = "ni," alg-val 189 name = "name," reg-name 190 1. The prefix "uuid," combines with the "UUID" production as defined 191 in [RFC4122], e.g. "uuid,2a47c495-ac70-4ed1-850b-8800a57618cf" 193 2. The prefix "ni," combines with the "alg-val" production as 194 defined in [RFC6920], e.g. "ni,sha- 195 256;JCS7yveugE3UaZiHCs1XpRVfSHaewxAKka0o5q2osg8" 197 3. The prefix "name," combines with the "reg-name" production as 198 defined in [RFC3986], e.g. "name,app.example.com". 200 4. The production "authority" matches its definition in [RFC3986]. 201 As this necessarily also match the above prefixed productions, 202 those should be considered first before falling back to this 203 production. 205 3.2. Path 207 The "path-absolute" component, if present, MUST match the production 208 in [RFC3986] and provide the absolute path of a resource (e.g. a file 209 or directory) within the archive. 211 Archive media types vary in constraints and possibilities on how to 212 express paths, however implementations SHOULD use "/" as path 213 separator for nested folders and files. 215 It is RECOMMENDED to include the trailing "/" if it is known the path 216 represents a directory. 218 4. Scheme semantics 220 This specification does not constrain what format might constitute an 221 _archive_, and neither does it require that the archive is 222 retrievable as a single bytestream or file. 224 Examples of retrievable archive media types include "application/ 225 zip", "application/vnd.android.package-archive", "application/x-tar", 226 "application/x-gtar" and "application/x-7z-compressed". 228 Examples of non-file archives include an LDP Container 229 [W3C.REC-ldp-20150226], an installed Web App 230 [W3C.WD-appmanifest-20180118], or a BagIt folder structure 231 [I-D.draft-kunze-bagit-14]. 233 4.1. Authority semantics 235 The _authority_ component identifies the archive itself. 237 Implementations MAY assume that two app URIs with the same authority 238 component relate to resources within the same archive, subject to 239 limitations explained in this section. 241 The authority prefix, if present, helps to inform consumers what 242 uniqueness constraints have been used when identifying the archive, 243 without necessarily providing access to the archive. 245 1. If the prefix is "uuid," followed by a UUID [RFC4122], this 246 indicates a unique archive identity. 248 2. If the prefix is "uuid," followed by a v4 UUID [RFC4122], this 249 indicate uniqueness based on a random number generator. 250 Implementations creating random-based authorities SHOULD generate 251 the v4 random UUID using a suitable random number generator 252 [RFC4086]. 254 3. If the prefix is "uuid," followed by a v5 name-based UUID 255 [RFC4122], this indicates uniqueness based on an existing archive 256 location, typically an URL. Implementations creating location- 257 based authorities from an archive's URL SHOULD generate the v5 258 UUID using the URL namespace "6ba7b811-9dad- 259 11d1-80b4-00c04fd430c8" and the particular URL (see [RFC4122] 260 section 4.3). Note that while implementations cannot resolve 261 which location was used, they can confirm the name-based UUID if 262 the location is otherwise known. 264 4. If the prefix is "ni," this indicates a unique archive identity 265 based on a hashing of the archive's bytestream or content. 266 Implementations can assume that resources within an "ni" app URIs 267 remains static, although the implementation may use content 268 negotiation or similar transformations. The checksum MUST be 269 expressed according to [RFC6920]'s "alg-val" production. 270 Implementations creating hash-based authorities from an archive's 271 bytestream SHOULD use the "sha-256" without truncation. 273 5. If the prefix is "name," this indicates that the authority is an 274 application or package name, typically as installed on a device 275 or system. Implementations SHOULD assume that an unrecognized 276 "name" authority is only unique within a particular installation, 277 but MAY assume further uniqueness guarantees for names under 278 their control. It is RECOMMENDED that implementations creating 279 name-based authorities use DNS names under their control, for 280 instance an app installed as "app.example.com" can make an 281 authority "name,app.example.com" to refer to its packaged 282 resources, or "name,foo.app.example.com" to refer to a "foo" 283 container distributed across all installations. 285 The uniqueness properties are unspecified for app URIs which 286 authority do not match any of the prefixes defined in this 287 specification. 289 4.2. Path semantics 291 The _path_ component of an app URI identify individual resources 292 within a particular archive, typically a _directory_ or _file_. 294 o If the _path_ is "/" - e.g. "app://uuid,833ebda2-f9a8-4462-b74a- 295 4fcdc1a02d22/" - then the app URI represent the archive itself, 296 typically represented as a root directory or collection. 298 o If the path ends with "/" then the path represents a directory or 299 collection. 301 The app URIs can be used for uniquely identifying the resources 302 independent of the location of the archive, such as within an 303 information system. 305 Assuming an appropriate resolution mechanism which have knowledge of 306 the corresponding archive, an app URI can also be used for 307 resolution. 309 Some archive formats might permit resources with the same (duplicate) 310 path, in which case it is undefined from this specification which 311 particular entry is described. 313 4.3. Resolution protocol 315 This specification do not define the protocol to resolve resources 316 according to the app URI scheme. For instance, one implementation 317 might rewrite app URIs to localized paths in a temporary directory, 318 while another implementation might use an embedded HTTP server. 320 It is envisioned that an implementation will have extracted or opened 321 an archive in advance, and assigned it an appropriate authority 322 according to Section 3.1. Such an implementation can then resolve 323 app URIs programmatically, e.g. by using in-memory access or mapping 324 paths to the extracted archive on the local file system. 326 Implementations that support resolving app URIs SHOULD: 328 1. Fail with the equivalent of _Not Found_ if the authority is 329 unknown. 331 2. Fail with the equivalent of _Gone_ if the authority is known, but 332 the content of the archive is no longer available. 334 3. Fail with the equivalent of _Not Found_ if the path does not map 335 to a file or directory within the archive. 337 4. Return the corresponding (potentially uncompressed) bytestream if 338 the path maps to a file within the archive. 340 5. Return an appropriate directory listing if the path maps to a 341 directory within the archive. 343 6. Return an appropriate directory listing of the archive's root 344 directory if the path is "/". 346 Not all archive formats or implementations will have the concept of a 347 directory listing, in which case the implementation MAY fail such 348 resolutions with the equivalent of "Not Implemented". 350 It is not undefined by this specification how an implementation can 351 determine the media type of a file within an archive. This could be 352 expressed in secondary resources (such as a manifest), be determined 353 by file extensions or magic bytes. 355 The media type "text/uri-list" [RFC2483] MAY be used to represent a 356 directory listing, in which case it SHOULD contain only URIs that 357 start with the app URI of the directory. 359 Some archive formats might support resources which are neither 360 directories nor regular files (e.g. device files, symbolic links). 361 This specification does not define the semantics of attempting to 362 resolve such resources. 364 This specification does not define how to change an archive or its 365 content using app URIs. 367 4.4. Resolving from a .well-known endpoint 369 If the "authority" component of an app URI matches the "alg-val" 370 production, an application MAY attempt to resolve the authority from 371 any ".well-known/ni/" endpoint [RFC5785] as specified in [RFC6920] 372 section 4, in order to retrieve the complete archive. Applications 373 SHOULD verify the checksum of the retrieved archive before resolving 374 the individual path. 376 5. Encoding considerations 378 The productions for "UUID" and "alg-val" are restricted to URI safe 379 ASCII and should not require any encoding considerations. 381 Care should be taken to %-encode the directory and file segments of 382 "path-absolute" according to [RFC3986] (for URIs) or [RFC3987] (for 383 IRIs). 385 When used as part an IRI, paths SHOULD be expressed using 386 international Unicode characters instead of %-encoding as ASCII. 388 Not all archive formats have an explicit character encoding specified 389 for their paths. If no such information is available for the archive 390 format, implementations MAY assume that the path component is encoded 391 with UTF-8 [RFC2279]. 393 Some archive formats have case-insensitive paths, in which cases it 394 is RECOMMENDED to preserve the casing as expressed in the archive. 396 6. Interoperability considerations 398 As multiple authorities are possible for the same archive 399 (Section 3.1), and path interpretation might vary, there can be 400 interoperability challenges when exchanging app URIs between 401 implementations. Some considerations: 403 1. Two implementations describe the same archive (e.g. stored in the 404 same local file path), but using different random-based UUID 405 authorities. The implementations may need to detect equality of 406 the two UUIDs out of band. 408 2. Two implementations describe an archive retrieved from the same 409 URL, with the same location-based UUID authority, but retrieved 410 at different times. The implementations might disagree about the 411 content of the archive. 413 3. Two implementations describe an archive retrieved from the same 414 URL, with the same location-based UUID authority, but retrieved 415 using different content negotiation resulting in different 416 archive representations. The implementations may disagree about 417 path encoding, file name casing or hierarchy. 419 4. Two implementations describe the same archive bytestream using 420 the hash-based authority, but they have used two different hash 421 algorithms. The implementations may need to negotiate to a 422 common hash algorithm. 424 5. Two implementations access the same archive, which contain file 425 paths with Unicode characters, but extracted to two different 426 file systems. Limitations and conventions for file names in the 427 local file system (such as Unicode normalization, case 428 insensitivity, total path length) may result in the 429 implementations having inconsistent or inaccessible paths. 431 7. Security Considerations 433 As when handling any content, extra care should be taken when 434 consuming archives and app URIs from unknown sources. 436 An archive could contain compressed files that expand to fill all 437 available disk space. 439 A maliciously crafted archive could contain paths with characters 440 (e.g. backspace) which could make an app URI invalid or misleading if 441 used unescaped. 443 A maliciously crafted archive could contain paths (e.g. combined 444 Unicode sequences) that cause the app URI to be very long, causing 445 issues in information systems propagating said URI. 447 An archive might contain symbolic links that, if extracted to a local 448 file system, might address files outside the archive's directory 449 structure. Implementations SHOULD detect such links and prevent 450 outside access. 452 An maliciously crafted app URI might contain "../" path segments, 453 which if naively converted to a "file:///" URI might address files 454 outside the archive's directory structure. Implementations SHOULD 455 perform Path Segment Normalization [RFC3986] before converting app 456 URIs. 458 In particular for IRIs, an archive might contain multiple paths with 459 similar-looking characters or with different Unicode combine 460 sequences, which could be used to mislead users. 462 An URI hyperlink might use or guess an app URI authority to attempt 463 to climb into a different archive for malicious purposes. 464 Applications SHOULD employ Same Orgin policy [RFC6454] checks if 465 resolving cross-references is not desired. 467 While a UUID or hash-based authority provide some level of 468 information hiding of an archive's origin, this should not be relied 469 upon for access control or anonymisation. Implementors should keep 470 in mind that such authority components in many cases can be 471 predictably generated by third-parties, for instance using dictionary 472 attacks. 474 8. IANA Considerations 476 This specification requests that IANA registers the following URI 477 scheme according to the provisions of [RFC7595]. 479 Scheme name: app 481 Status: provisional 483 Applications/protocols that use this protocol: Hypermedia-consuming 484 application that handle archives or packages. 486 Contact: Stian Soiland-Reyes stain@apache.org [1] 488 Change controller: Stian Soiland-Reyes 490 9. References 492 9.1. Normative References 494 [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail 495 Extensions (MIME) Part Two: Media Types", RFC 2046, 496 DOI 10.17487/RFC2046, November 1996, 497 . 499 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 500 Requirement Levels", BCP 14, RFC 2119, 501 DOI 10.17487/RFC2119, March 1997, 502 . 504 [RFC2279] Yergeau, F., "UTF-8, a transformation format of ISO 505 10646", RFC 2279, DOI 10.17487/RFC2279, January 1998, 506 . 508 [RFC2483] Mealling, M. and R. Daniel, "URI Resolution Services 509 Necessary for URN Resolution", RFC 2483, 510 DOI 10.17487/RFC2483, January 1999, 511 . 513 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 514 Resource Identifier (URI): Generic Syntax", STD 66, 515 RFC 3986, DOI 10.17487/RFC3986, January 2005, 516 . 518 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 519 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 520 January 2005, . 522 [RFC4086] Eastlake 3rd, D., Schiller, J., and S. Crocker, 523 "Randomness Requirements for Security", BCP 106, RFC 4086, 524 DOI 10.17487/RFC4086, June 2005, 525 . 527 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 528 Unique IDentifier (UUID) URN Namespace", RFC 4122, 529 DOI 10.17487/RFC4122, July 2005, 530 . 532 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 533 Uniform Resource Identifiers (URIs)", RFC 5785, 534 DOI 10.17487/RFC5785, April 2010, 535 . 537 [RFC6454] Barth, A., "The Web Origin Concept", RFC 6454, 538 DOI 10.17487/RFC6454, December 2011, 539 . 541 [RFC6839] Hansen, T. and A. Melnikov, "Additional Media Type 542 Structured Syntax Suffixes", RFC 6839, 543 DOI 10.17487/RFC6839, January 2013, 544 . 546 [RFC6920] Farrell, S., Kutscher, D., Dannewitz, C., Ohlman, B., 547 Keranen, A., and P. Hallam-Baker, "Naming Things with 548 Hashes", RFC 6920, DOI 10.17487/RFC6920, April 2013, 549 . 551 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 552 and Registration Procedures for URI Schemes", BCP 35, 553 RFC 7595, DOI 10.17487/RFC7595, June 2015, 554 . 556 [RFC8089] Kerwin, M., "The "file" URI Scheme", RFC 8089, 557 DOI 10.17487/RFC8089, February 2017, 558 . 560 9.2. Informative References 562 [ApacheTaverna] 563 "Apache Taverna (incubating)", January 2018, 564 . 566 [I-D.draft-kunze-bagit-14] 567 Kunze, J., Littman, J., Madden, L., Summers, E., Boyko, 568 A., and B. Vargas, "The BagIt File Packaging Format 569 (V0.97)", draft-kunze-bagit-14 (work in progress), October 570 2016. 572 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 573 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 574 . 576 [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., 577 and D. Orchard, "URI Template", RFC 6570, 578 DOI 10.17487/RFC6570, March 2012, 579 . 581 [ROBundle] 582 Soiland-Reyes, S., Gamble, M., and R. Haines, "Research 583 Object Bundle 1.0", Zenodo report, 584 DOI 10.5281/zenodo.12586, November 2014, 585 . 587 [W3C.NOTE-app-uri-20150723] 588 Caceres, M., "The app: URL Scheme", World Wide Web 589 Consortium NOTE NOTE-app-uri-20150723, July 2015, 590 . 592 [W3C.NOTE-widgets-uri-20120313] 593 Caceres, M., "Widget URI scheme", World Wide Web 594 Consortium NOTE NOTE-widgets-uri-20120313, March 2012, 595 . 597 [W3C.REC-ldp-20150226] 598 Speicher, S., Arwe, J., and A. Malhotra, "Linked Data 599 Platform 1.0", World Wide Web Consortium Recommendation 600 REC-ldp-20150226, February 2015, 601 . 603 [W3C.WD-appmanifest-20180118] 604 Caceres, M., Christiansen, K., Lamouri, M., Kostiainen, 605 A., and R. Dolin, "Web App Manifest", World Wide Web 606 Consortium WD WD-appmanifest-20180118, January 2018, 607 . 609 9.3. URIs 611 [1] mailto:stain@apache.org 613 Appendix A. Examples 615 A.1. Sharing using app names 617 A photo gallery application on a mobile device uses app URIs for 618 navigation between its UI states. The gallery is secured so that 619 other applications can't normally access its photos. 621 The application is installed as the package name 622 "gallery.example.org", making the corresponding name-based app URI: 624 app://name,gallery.example.org/ 626 A user is at the application state which shows the newest photos as 627 thumbnails: 629 app://name,gallery.example.org/photos/?New 631 The user selects a photo, rendered with metadata overlaid: 633 app://name,gallery.example.org/photos/137 635 The user requests to "share" the photo, selecting 636 "messaging.example.com" which uses the common URI framework on the 637 device. 639 The photo gallery registers with the device's app framework that the 640 chosen "messaging.example.com" gets read permission to its 641 "/photos/137" resource. 643 The sharing function returns a URI Template [RFC6570]: 645 app://name,messaging.example.com/share{;uri}{;redirect} 647 Filling in the template, the gallery requests to pop up: 649 app://name,messaging.example.com/share 650 ;uri=app://gallery.example.org/photos/137 651 ;redirect=app://gallery.example.org/photos/%3fNew 653 The app framework checks its registration for "messaging.example.com" 654 and finds the installed messaging application. It performs 655 permission checks that other apps are allowed to navigate to its 656 "/share" state. 658 The messaging app is launched and navigates to its "sharing" UI, 659 asking the user for a caption. 661 The messaging app requests the app framework to retrieve 662 "app://name,gallery.example.org/photos/137" using content negotiation 663 for an "image/jpeg" representation. 665 The app framework finds the installed photo gallery 666 "gallery.example.org", and confirms the read permission. 668 The photo gallery application returns a JPEG representation after 669 retrieving the photo from its internal store. 671 After the messaging app has completed sharing the picture bytestream, 672 it request the UI framework to navigate to: 674 app://name,gallery.example.org/photos/?New 676 The UI returns to the original view in the photo gallery. 678 If the messaging app had attempted to _retrieve_ the app URI 680 app://name,gallery.example.org/photos/?New 682 then it would be rejected by the app framework as permission was not 683 granted. 685 However, if such access had been granted, the gallery could return a 686 "text/uri-list" of the newest photos: 688 app://name,gallery.example.org/photos/137 689 app://name,gallery.example.org/photos/138 690 app://name,gallery.example.org/photos/139 692 This examples show that although an app URI represents a resource, it 693 can have different representations or UI states for different apps. 695 A.2. Sandboxing 697 An document store application has received a file "document.tar.gz" 698 which content will be checked for consistency. 700 For sandboxing purposes it generates a UUID v4 "32a423d6-52ab-47e3- 701 a9cd-54f418a48571" using a pseudo-random generator. The app base URI 702 is thus "app://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/" 704 The archive contains the files: 706 o "./doc.html" which links to "css/base.css" 708 o "./css/base.css" which links to "../fonts/Coolie.woff" 709 o "./fonts/Coolie.woff" 711 The application generates the corresponding app URIs and uses those 712 for URI resolutions to list resources and their hyperlinks: 714 app://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/doc.html 715 -> app://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/css/base.css 716 app://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/css/base.css 717 -> app://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/fonts/Coolie.woff 718 app://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/fonts/Coolie.woff 720 The application is now confident that all hyperlinked files are 721 indeed present in the archive. In its database it notes which 722 "tar.gz" file corresponds to UUID "32a423d6-52ab-47e3-a9cd- 723 54f418a48571". 725 If the application had encountered a malicious hyperlink 726 "../../../outside.txt" it would first resolve it to the absolute URI 727 "app://uuid,32a423d6-52ab-47e3-a9cd-54f418a48571/outside.txt" and 728 conclude from the "Not Found" error that the path "/outside.txt" was 729 not present in the archive. 731 A.3. Origin-based 733 A web crawler is about to index the content of the URL 734 "http://example.com/data.zip" and need to generate absolute URIs as 735 it continues crawling inside the individual resources of the archive. 737 The application generates a UUID v5 based on the URL namespace 738 "6ba7b811-9dad-11d1-80b4-00c04fd430c8" and the URL to the zip file: 740 >>> uuid.uuid5(uuid.NAMESPACE_URL, "http://example.com/data.zip") 741 UUID('b7749d0b-0e47-5fc4-999d-f154abe68065') 743 Thus the location-based app URI for indexing the ZIP content is 745 app://uuid,b7749d0b-0e47-5fc4-999d-f154abe68065/ 747 Listing all directories and files in the ZIP, the crawler finds the 748 URIs: 750 app://uuid,b7749d0b-0e47-5fc4-999d-f154abe68065/ 751 app://uuid,b7749d0b-0e47-5fc4-999d-f154abe68065/pics/ 752 app://uuid,b7749d0b-0e47-5fc4-999d-f154abe68065/pics/flower.jpeg 754 When the application encounters "http://example.com/data.zip" some 755 time later it can recalculate the same base app URI. This time the 756 ZIP file has been modified upstream and the crawler finds 757 additionally: 759 app://uuid,b7749d0b-0e47-5fc4-999d-f154abe68065/pics/cloud.jpeg 761 If files had been removed from the updated ZIP file the crawler can 762 simply remove those from its database, as it used the same app base 763 URI as in last crawl. 765 A.4. Hash-based 767 An application where users can upload software distributions for 768 virus checking needs to avoid duplication as users tend to upload 769 "foo-1.2.tar" multiple times. 771 The application calculates the "sha-256" checksum of the uploaded 772 file to be in hexadecimal: 774 17edf80f84d478e7c6d2c7a5cfb4442910e8e1778f91ec0f79062d8cbdef42cd 776 The "base64url" encoding [RFC4648] of the binary version of the 777 checksum is: 779 F-34D4TUeOfG0selz7REKRDo4XePkewPeQYtjL3vQs0 781 The corresponding "alg-val" authority is thus: 783 sha-256;F-34D4TUeOfG0selz7REKRDo4XePkewPeQYtjL3vQs0 785 From this the hash base app URL is: 787 app://ni,sha-256;F-34D4TUeOfG0selz7REKRDo4XePkewPeQYtjL3vQs0/ 789 The crawler finds that its virus database already contain entries 790 for: 792 app://ni,sha-256;F-34D4TUeOfG0selz7REKRDo4XePkewPeQYtjL3vQs0/bin/evil 794 and flags the upload as malicious without having to scan it again. 796 A.5. Archives that are not files 798 An application is relating BagIt archives [I-D.draft-kunze-bagit-14] 799 on a shared file system, using structured folders and manifests 800 rather than individual archive files. 802 The BagIt payload manifest "/gfs/bags/scan15/manifest-md5.txt" lists 803 the files: 805 49afbd86a1ca9f34b677a3f09655eae9 data/27613-h/q172.png 806 408ad21d50cef31da4df6d9ed81b01a7 data/27613-h/q172.txt 808 The application generates a random UUID v4 "ff2d5a82-7142-4d3f-b8cc- 809 3e662d6de756" which it adds to the bag metadata file 810 "/gfs/bags/scan15/bag-info.txt" 812 External-Identifier: ff2d5a82-7142-4d3f-b8cc-3e662d6de756 814 It then generates app URIs for the files listed in the manifest: 816 app://uuid,ff2d5a82-7142-4d3f-b8cc-3e662d6de756/data/27613-h/q172.png 817 app://uuid,ff2d5a82-7142-4d3f-b8cc-3e662d6de756/data/27613-h/q172.txt 819 When a different application on the same shared file system encounter 820 these app URIs, it can match them to the correct bag folder by 821 inspecting the "External-Identifier" metadata. 823 A.6. Linked Data containers which are not on the web 825 An application exposes in-memory objects of an Address Book as a 826 Linked Data Platform container [W3C.REC-ldp-20150226], but addressing 827 the container using app URIs instead of http to avoid network 828 exposure. 830 The app URIs are used in conjuction with a generic LDP client library 831 (developed for http), but connected to the application's URI 832 resolution mechanism. 834 The application generates a new random UUID v4 "12f89f9c-e6ca- 835 4032-ae73-46b68c2b415a" for the address book, and provides the 836 corresponding app URI to the LDP client: 838 app://uuid,12f89f9c-e6ca-4032-ae73-46b68c2b415a/ 840 The LDP client resolves the container with content negotiation for 841 the "text/turtle" media type, and receives: 843 @base . 844 @prefix ldp: . 845 @prefix dcterms: . 847 848 a ldp:BasicContainer; 849 dcterms:title "Address book"; 850 ldp:contains , . 852 The LDP client resolves the relative URIs to retrieve each of the 853 contacts: 855 app://uuid,12f89f9c-e6ca-4032-ae73-46b68c2b415a/contact1 856 app://uuid,12f89f9c-e6ca-4032-ae73-46b68c2b415a/contact2 858 A.7. Resolution of packaged resources 860 A virtual file system driver on a mobile operating system has mounted 861 several packaged applications for resolving common resources. An 862 application requests the rendering framework to resolve a picture 863 from "app://uuid,eb1edec9-d2eb-4736-a875-eb97b37c690e/img/logo.png" 864 to show it within a user interface. 866 The framework first checks that the authority "uuid,eb1edec9-d2eb- 867 4736-a875-eb97b37c690e" is valid to access according to the Same 868 Origin policies or permissions of the running application. It then 869 matches the authority to the corresponding application package. 871 The framework resolves "/img/logo.png" from within that package, and 872 returns an image buffer it already had cached in memory. 874 Appendix B. History 876 This specification proposes the URI scheme "app", which was 877 originally proposed by [W3C.NOTE-app-uri-20150723] but never 878 registered with IANA. That W3C Note evolved from 879 [W3C.NOTE-widgets-uri-20120313] which proposed the URI scheme 880 "widget". 882 Neither W3C Notes progressed further as Recommendation track 883 documents. 885 While the focus of those W3C Notes was to specify how to resolve 886 resources from within a packaged application, this specification 887 generalize the "app" URI scheme to support referencing and 888 identifying resources within any archive, and de-emphasize the 889 retrieval mechanism. 891 For compatibility with existing adaptations of the "app" URI scheme, 892 e.g. [ROBundle] and [ApacheTaverna], this specification reuse the 893 same scheme name and remains compatible with the intentions of 894 [W3C.NOTE-app-uri-20150723], but renames "app" to mean "Application 895 and Packaging Pointer" instead of "Application". 897 Authors' Addresses 899 Stian Soiland-Reyes 900 The University of Manchester 901 Oxford Road 902 Manchester 903 United Kingdom 905 Email: stain@apache.org 907 Marcos Caceres 908 Mozilla Corporation 910 Email: marcos@marcosc.com