From 2efc29e6d8664e62835f151460f5d08ea2e98fa4 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 10 Jun 2019 20:01:15 +0200 Subject: [PATCH 1/2] Add examples to ADDRESSING.md --- ADDRESSING.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/ADDRESSING.md b/ADDRESSING.md index 43c435c..2d4bd1c 100644 --- a/ADDRESSING.md +++ b/ADDRESSING.md @@ -20,15 +20,28 @@ ### Addressing with HTTP +#### Paths 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 + +Examples: + + https://gateway.ipfs.io/ipfs/bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html + https://gateway.ipfs.io/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Mars.html + https://gateway.ipfs.io/ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html + +#### Subdomains -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: +When [origin-based security](https://en.wikipedia.org/wiki/Same-origin_policy) 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 + +Example: + + https://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq.ipfs.dweb.link/wiki/ Read more: [notes on addressing with HTTP](#notes-on-addressing-with-http). @@ -37,6 +50,10 @@ Read more: [notes on addressing with HTTP](#notes-on-addressing-with-http). In future, subdomain convention will be replaced with native handler that provides the same origin-based guarantees: ipfs://{cidv1b32}/path/to/resource + +Example: + + ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html Read more: [notes on addressing with ipfs://](#notes-on-addressing-with-ipfs). @@ -47,6 +64,11 @@ We argue that paths are the better canonical address and that all kinds of thing dweb:/ipfs/{cidv1b32}/path/to/resource +Example: + + dweb://ipfs/bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html + dweb://ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html + Read more: [notes on addressing with dweb:](#notes-on-addressing-with-dweb). ## References From c4723df2cd4225f4950b57bc22754a391f2e60b6 Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Mon, 10 Jun 2019 22:04:22 +0200 Subject: [PATCH 2/2] ADDRESSING.md: add microspec as TL;DR --- ADDRESSING.md | 76 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 23 deletions(-) diff --git a/ADDRESSING.md b/ADDRESSING.md index 2d4bd1c..827e2e9 100644 --- a/ADDRESSING.md +++ b/ADDRESSING.md @@ -3,13 +3,15 @@ > ### 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) +- [**TL;DR**](#tldr) +- [With HTTP](#addressing-with-http) +- [With New URIs](#addressing-with-native-url) - [References](#references) - [Appendices](#appendices) - Notes on addressing with [http://](#notes-on-addressing-with-http) @@ -18,56 +20,87 @@ ## TL;DR -### Addressing with HTTP +If no native protocol handler is available, redirect to a gateway: -#### Paths +```bash +ipfs://{cid} → https://{gateway}/ipfs/{cid} +ipns://{libp2p-key} → https://{gateway}/ipns/{libp2p-key} +ipns://{fqdn-with-dnslink} → https://{gateway}/ipns/{fqdn-with-dnslink} +``` + +With native protocol handlers, follow below: + +```bash +ipfs://{cidv1base32} +ipfs://{cidv0} → redirect → ipfs://{cidv1base32} # CIDv0 is case-sensitive Base58, does not work as Origin authority + +ipns://{libp2p-key-in-cidv1base32} +ipns://{libp2p-key-in-base58} → redirect → ipns://{libp2p-key-in-cidv1} # Base58, does not work as Origin authority + +ipns://{fqdn-with-dnslink} +ipfs://{fqdn-with-dnslink} → redirect → ipns://{fqdn-with-dnslink} # just to improve UX :-) + +dweb:/ipfs/{root}/{resource} → redirect → ipfs://{root}/{resource} # ensures {root} is the authority component +dweb:/ipns/{root}/{resource} → redirect → ipns://{root}/{resource} # ensures {root} is the authority component +``` + +## Addressing with HTTP + +### Paths 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 - -Examples: + +Examples: https://gateway.ipfs.io/ipfs/bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html https://gateway.ipfs.io/ipfs/QmT5NvUtoM5nWFfrQdVrFtvGfKFmG7AHE8P34isapyhCxX/wiki/Mars.html https://gateway.ipfs.io/ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html -#### Subdomains +### Subdomains When [origin-based security](https://en.wikipedia.org/wiki/Same-origin_policy) 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 - + Example: https://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq.ipfs.dweb.link/wiki/ Read more: [notes on addressing with HTTP](#notes-on-addressing-with-http). -### Addressing with Native URL +## 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 - + Example: ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html Read more: [notes on addressing with ipfs://](#notes-on-addressing-with-ipfs). -### Addressing with URI +## Addressing with URI + +> **Implementation Warning:** +> web browsers often implement custom URIs in a way that enforces Origin to be either equal `null` or based on the first label after `:`. +> This makes proper security isolation of content loaded via `dweb:/ipfs/{root}/` difficult to get right, and it may be easier to redirect to `ipfs://{root}`. In contexts that do not require origin-based security a simple URI can be used for addressing both IPFS and IPNS resources. + We argue that paths are the better canonical address and that all kinds of things with different semantics can live in a shared universal namespace. To provide a first step towards that goal, the dweb: URI is proposed: dweb:/ipfs/{cidv1b32}/path/to/resource + dweb:/ipns/{libp2p-key-in-cidv1base32}/path/to/resource + dweb:/ipns/{fqdn-with-dnslink}/path/to/resource Example: - dweb://ipfs/bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html - dweb://ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html + dweb:/ipfs/bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/wiki/Vincent_van_Gogh.html + dweb:/ipns/tr.wikipedia-on-ipfs.org/wiki/Anasayfa.html Read more: [notes on addressing with dweb:](#notes-on-addressing-with-dweb). @@ -77,9 +110,9 @@ Read more: [notes on addressing with dweb:](#notes-on-addressing-with-dweb). - [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. @@ -147,7 +180,7 @@ According to [RFC 1035](http://tools.ietf.org/html/rfc1035) subdomains (aka 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 +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). @@ -159,9 +192,9 @@ Suborigins are a 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) +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. +unique to the current content addressing root. Unfortunately due to limited adoption suborigin have no practical use. @@ -179,14 +212,11 @@ calculation, which provides necessary isolation between security contexts of dif ### Notes on addressing with `dweb:` -We're not trying to bring in all the possible sources of data, or interfaces into this namespace. -We only work on content-addressed stuff here. +We're not trying to bring in all the possible sources of data, or interfaces into this namespace. +We only work on content-addressed stuff here. Why not just only `ipfs://` and `ipns://`? - These URLs satisfy the content-addressing requirement - They don't satisfy the universal-data-namespace requirement - [We want to leave room for others in this new addressing scheme](https://github.com/arewedistributedyet/arewedistributedyet/issues/28) - - -