-
Notifications
You must be signed in to change notification settings - Fork 233
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #351 from ipfs/ipns-records-gateway
- Loading branch information
Showing
3 changed files
with
121 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,100 @@ | ||
| --- | ||
| title: "IPIP-0351: IPNS Signed Records Response Format on HTTP Gateways" | ||
| date: 2022-11-29 | ||
| ipip: ratified | ||
| editors: | ||
| - name: Henrique Dias | ||
| github: hacdias | ||
| url: https://hacdias.com/ | ||
| - name: Marcin Rataj | ||
| github: lidel | ||
| url: https://lidel.org/ | ||
| relatedIssues: | ||
| - https://github.com/ipfs/specs/issues/320 | ||
| - https://github.com/ipfs/specs/pull/351 | ||
| - https://github.com/ipfs/kubo/pull/9399 | ||
| order: 351 | ||
| tags: ['ipips'] | ||
| --- | ||
|
|
||
| ## Summary | ||
|
|
||
| Add IPNS Signed Records response format to the [HTTP Gateway](/http-gateways/). | ||
|
|
||
| ## Motivation | ||
|
|
||
| Currently, the gateway allows for trustless retrieval of data under the `/ipfs` | ||
| namespace, but fetching the data as a CAR, or Block, and then verifying it locally. | ||
| This is especially important for light IPFS clients, so that they can retrieve | ||
| data from other gateways without delegating any of the trust to them. Unfortunately, | ||
| this is not possible under the `/ipns` namespace. | ||
|
|
||
| In contrary to DNSLink, IPNS provides cryptographically-verifiable records that | ||
| can be verified by the client. This means that, if a gateway is able to provide | ||
| the IPNS signed record to an HTTP client, trustless retrieval would also be available | ||
| under the `/ipns` namespace. | ||
|
|
||
| In this IPIP, we propose adding :cite[ipns-record] as a response | ||
| format to the gateway under the `/ipns` namespace, allowing for trustless | ||
| retrieval of IPNS records over HTTP as [application/vnd.ipfs.ipns-record](https://www.iana.org/assignments/media-types/application/vnd.ipfs.ipns-record) content type (multicodec `0x0300`). | ||
|
|
||
| ## Detailed design | ||
|
|
||
| - :cite[trustless-gateway] can now provide a signed IPNS record upon request for `/ipns/{ipns-name}` path. | ||
| - To request the IPNS record, use one of the following methods: | ||
| - Include the `Accept: application/vnd.ipfs.ipns-record` HTTP header in the request. | ||
| - Include the `format=ipns-record` query parameter in the request URL. | ||
| - The HTTP response containing the verifiable IPNS record will have the following format: | ||
| - Header: `Content-Type: application/vnd.ipfs.ipns-record` | ||
| - Body: :cite[ipns-record] serialized as the `IpnsEntry` protobuf. | ||
|
|
||
| ## Test fixtures | ||
|
|
||
| This IPIP got ratified before | ||
| [gateway-conformance](https://github.com/ipfs/gateway-conformance) existed. | ||
|
|
||
|
|
||
| The [reference implementation in Kubo 0.19](https://github.com/ipfs/kubo/blob/master/docs/changelogs/v0.19.md#signed-ipns-record-response-format) | ||
| provides reusable [assertions](https://github.com/ipfs/kubo/blob/v0.19.2/test/sharness/t0124-gateway-ipns-record.sh). | ||
|
|
||
| :::issue | ||
| Until vendor-agnostic fixtures are added to the conformance test suite ([tracking issue](https://github.com/ipfs/gateway-conformance/issues/3)), | ||
| IPNS records for testing can be generated in Kubo by creating an IPNS record: | ||
|
|
||
| ```bash | ||
| $ ipfs key gen <key-name> | ||
| k51Key | ||
|
|
||
| $ ipfs name publish /ipfs/bafyHash --key=<key-name> --ttl=<record-ttl> | ||
| Published to k51Key: /ipfs/bafyHash | ||
|
|
||
| $ ipfs routing get /ipns/k51Key > key.pb | ||
| ``` | ||
| ::: | ||
|
|
||
| ## Design rationale | ||
|
|
||
| The current gateway already supports different response formats via the | ||
| `Accept` HTTP header and the `format` URL query. This IPIP proposes adding | ||
| one more supported format to that list. | ||
|
|
||
| ### User benefit | ||
|
|
||
| By providing IPNS records through the gateway, IPFS light clients are able | ||
| to race multiple gateways in search for an IPNS record for a certain IPNS key. | ||
| This way, IPFS light clients do not necessarily need to implement the required | ||
| machinery to fetch IPNS records from other IPFS nodes through the DHT or PubSub. | ||
|
|
||
| In addition, the retrieval of IPNS records is trustless in the sense that they can | ||
| be verified by the client since the IPNS record includes a cryptographic signature | ||
| provided by its creator. | ||
|
|
||
| ### Compatibility | ||
|
|
||
| This IPIP proposes a new format to be added to the gateway, but does not change | ||
| any prior format. Therefore, this IPIP is backwards compatible. Please note | ||
| that IPNS records are also added to the :cite[trustless-gateway] specification. | ||
|
|
||
| ### Copyright | ||
|
|
||
| Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). |