IPIP-0351: IPNS Signed Records Response Format on HTTP Gateways

Henrique Dias GitHub
Marcin Rataj GitHub
Related Issues
Commit History
GitHub ipfs/specs (pull requests, new issue, open issues)

1. Summary

Add IPNS Signed Records response format to the HTTP Gateway.

2. 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 [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 content type (multicodec 0x0300).

3. Detailed design

4. Test fixtures

This IPIP got ratified before gateway-conformance existed.

The reference implementation in Kubo 0.19 provides reusable assertions.

Until vendor-agnostic fixtures are added to the conformance test suite (tracking issue), IPNS records for testing can be generated in Kubo by creating an IPNS record:

$ ipfs key gen <key-name>

$ ipfs name publish /ipfs/bafyHash --key=<key-name> --ttl=<record-ttl>
Published to k51Key: /ipfs/bafyHash

$ ipfs routing get /ipns/k51Key > key.pb

5. 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.

5.1 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.

5.2 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 [trustless-gateway] specification.

A. References

IPNS Record and Protocol. Vasco Santos; Steve Allen; Marcin Rataj; Henrique Dias; Gus Eggert. 2023-10-03. URL: https://specs.ipfs.tech/ipns/ipns-record/
Trustless Gateway Specification. Marcin Rataj; Henrique Dias. 2024-04-17. URL: https://specs.ipfs.tech/http-gateways/trustless-gateway/