From fd3d128ce582b1efbadaed234365b478a71eb915 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 23 Jul 2018 01:28:19 +0200 Subject: [PATCH 1/3] Create ADDRESSING.md Initial draft of IPFS Addressing in Web Browsers memo. The goal is to highlight near-term use cases as a base for discussions during DWEB 2018. --- ADDRESSING.md | 148 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 ADDRESSING.md diff --git a/ADDRESSING.md b/ADDRESSING.md new file mode 100644 index 0000000..3e2b7c1 --- /dev/null +++ b/ADDRESSING.md @@ -0,0 +1,148 @@ +# IPFS Addressing in Web Browsers + + + +> ### Status of This Memo +> +> This living document specifies current set of conventions for the IPFS community, +> and requests discussion and suggestions for improvements via PR. + +## Table of Contents + +- [Summary](#tldr) +- [References](#references) +- [Appendices](#appendices) + - Notes on addressing with [http://](#notes-on-addressing-with-http) + - Notes on addressing with [ipfs://](#notes-on-addressing-with-ipfs) + +## TL;DR + +### Addressing with HTTP + + +When site isolation does not matter gateway can expose IPFS namespaces as regular URL paths: + + https://.tld/ipfs//path/to/resource + https://.tld/ipns//path/to/resource + +When origin-based security perimeter is needed, [CIDv1](https://github.com/ipld/cid#cidv1) in Base32 ([RFC4648](https://tools.ietf.org/html/rfc4648#section-6), no padding) should be used in subdomain: + + https://.ipfs..tld/path/to/resource + https://.ipns..tld/path/to/resource + + +For more context see [notes on addressing with HTTP](#notes-on-addressing-with-http) below. + +### Addressing with Native URL + +In future, subdomain convention will be replaced with native handler that provides the same origin-based guarantees: + + ipfs://{cidv1b32}/path/to/resource + +## References +- [The four stages of the upgrade path for path addressing](https://github.com/ipfs/specs/pull/152#issuecomment-284628862) +- [CID as a Subdomain](https://github.com/ipfs/in-web-browsers/issues/89) +- [IPFS: Migration to CIDv1 (default base32)](https://github.com/ipfs/ipfs/issues/337) +- [Support Custom Protocols in WebExtension](https://github.com/lidel/ipfs-firefox-addon/issues/164) +- [mozilla/libdweb experiment: ipfs:// protocol handler](https://github.com/ipfs-shipyard/ipfs-companion/pull/533) + +## Appendices + +### Notes on addressing with `http://` + +The first stage on the upgrade path are HTTP gateways. + +Gateways are provided strictly for convenience to help tools that speak HTTP +but do not speak distributed protocols such as IPFS. This approach has been +working well since 2015 but comes with a significant set of limitations related +to the centralized nature of HTTP and some of its semantics. Location-based +addressing of a gateway depends on both DNS and HTTPS/TLS, which relies on the trust in +Certificate Authorities and PKI. In the long term these issues SHOULD be +mitigated by use of opportunistic protocol upgrade schemes. + +#### Opportunistic Protocol Upgrade + +Tools and [browser extensions](https://github.com/ipfs-shipyard/ipfs-companion) SHOULD detect valid IPFS paths and resolve them +directly over IPFS protocol and use HTTP gateway ONLY as a fallback when no +native implementation is available to ensure a smooth, backward-compatible +transition. + + +#### Gateway Semantics + + +In the most basic scheme an URL path used for content addressing is effectively a +resource name without a canonical location. HTTP Gateway provides the location +part, which makes it possible for browsers to interpret content path as +relative to the current server and just work without a need for any conversion. + +HTTP gateway SHOULD: +- Take advantage of existing caching primitives, namely: + - Set `Etag` HTTP header to the canonical CID of returned payload + - Set `Cache-Control: public,max-age=29030400,immutable` if resource + belongs to immutable namespace (eg. `/ipfs/*`) +- set `Suborigin` header based on the hash of the root of current content tree +- provide a meaningful directory index for root resources representing file + system trees + +HTTP gateway MAY: +- Customize style of directory index. +- Return a custom payload along with error responses (HTTP 400 etc). +- Provide a writable (`POST`, `PUT`) access to exposed namespaces. + + +##### Origin Workaround #1: Subdomains + +Gateway operator MAY work around single Origin limitation by creating artificial +subdomains based on URL-safe version of root content identifier (eg. +`.ipfs.foo.tld`). Each subdomain provides separate Origin and creates an +isolated security context at a cost of obfuscating path-based addressing. + +Benefits of this approach: + +- The ability to do proper security origins without introducing any changes to + preeexisting HTTP stack. +- Root path of content-addressed namespace becomes the root of URL path, which + makes asset adressing compatible with existing web browsers: `` +- Opens up the ability for [HTTP Host + header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host) and + [TLS SNI](https://en.wikipedia.org/wiki/Server_Name_Indication) parsing, + which is a prerequisite for fully automated deployment of TLS via Let's Encrypt. + +According to [RFC 1035](http://tools.ietf.org/html/rfc1035) subdomains (aka +"labels", hostnames) are case-insensitive, which severly constraints the number +of content addressing identifier types that can be used without need for an +additional conversion step. + +Due to this IPFS community [decided](https://github.com/ipfs/ipfs/issues/337) to use lowercased base32 +([RFC4648](https://tools.ietf.org/html/rfc4648#section-6) - no padding - highest letter) +as the default base encoding of [CIDv1](https://github.com/ipld/cid#cidv1) (our binary identifiers). + + +##### Origin Workaround #2: Suborigin + +Suborigins are a +[work-in-progress](https://w3c.github.io/webappsec-suborigins/) standard to +provide a new mechanism for allowing sites to separate their content by +creating synthetic origins while serving content from a single physical origin. + +A [`suborigin` header](https://w3c.github.io/webappsec-suborigins/#the-suborigin-header) +SHOULD be returned by HTTP gateway and contain a value +unique to the current content addressing root. + +Unfortunately due to limited adoption suborigin have no practical use. + + +### Notes on addressing with `ipfs://` + +The `ipfs://` protocol scheme follows the same requirement of CIDv1 in Base32 as [subdomains](#origin-workaround-1-subdomains). +It does not retain original path, but instead requires a conversion step to/from URI: +> `ipfs://{immutable-root}/path/to/resourceA` → `/ipfs/{immutable-root}/path/to/resourceA` +> `ipns://{mutable-root}/path/to/resourceB` → `/ipns/{mutable-root}/path/to/resourceB` + +The first element after double slash is an opaque identifier representing +the content root. It is interpreted as an authority component used for Origin +calculation, which provides necessary isolation between security contexts of diferent content trees. + + From 826328ec1491829e660d7fbec8972524f8ccccc2 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Thu, 26 Jul 2018 22:40:45 +0200 Subject: [PATCH 2/3] docs: removed IPNS in subdomain Missed the fact IPNS does not work in case-insensitive contexts right now. More: https://github.com/ipfs/go-ipfs/issues/5287 --- ADDRESSING.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/ADDRESSING.md b/ADDRESSING.md index 3e2b7c1..ecda00f 100644 --- a/ADDRESSING.md +++ b/ADDRESSING.md @@ -23,13 +23,11 @@ When site isolation does not matter gateway can expose IPFS namespaces as regular URL paths: https://.tld/ipfs//path/to/resource - https://.tld/ipns//path/to/resource + https://.tld/ipns//path/to/resource When origin-based security perimeter is needed, [CIDv1](https://github.com/ipld/cid#cidv1) in Base32 ([RFC4648](https://tools.ietf.org/html/rfc4648#section-6), no padding) should be used in subdomain: https://.ipfs..tld/path/to/resource - https://.ipns..tld/path/to/resource - For more context see [notes on addressing with HTTP](#notes-on-addressing-with-http) below. From 6c70696cd925b78d1fbf40b88fd1c2ac19167cc8 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Tue, 31 Jul 2018 20:33:20 -0700 Subject: [PATCH 3/3] Update README.md Added link to ADDRESSING.md --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c3944bd..5539ed1 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,11 @@ Latest Beta experimentally exposes IPFS API under [`window.ipfs`](https://github Currently in order to run IPFS in a web browser, you have to either bundle [`js-ipfs`](https://github.com/ipfs/js-ipfs) (full IPFS node in JS) with your client-side application or use [`js-ipfs-api`](https://github.com/ipfs/js-ipfs-api) (HTTP API client library) to connect to external daemon running on local or remote machine. +### IPFS Addressing in Web Browsers + +See [this memo](ADDRESSING.md). It specifies current set of conventions for the IPFS community. +We invite everyone to submit questions and suggestions for improvements via issues/PR. + ## PM'ing - [![Waffle.io - Columns and their card count](https://badge.waffle.io/ipfs/in-web-browsers.svg?columns=all)](https://waffle.io/ipfs/in-web-browsers) @@ -28,5 +33,4 @@ or use [`js-ipfs-api`](https://github.com/ipfs/js-ipfs-api) (HTTP API client lib - [IPFS WebUI](https://github.com/ipfs-shipyard/ipfs-webui) - The IPFS Dashboard - [IPFS GUI](https://github.com/ipfs-shipyard/pm-ipfs-gui) - Unifying and leveling up IPFS interfaces and the user journey into the Distributed Web - [IPFS Styleguide and UI language](https://github.com/ipfs-shipyard/ipfs-ui-style-guide) -- `dweb:` specification & roadmap - The upgrade and integration path for Browsers to support the Distributed Web.