IPNS Signed Records Response Format on HTTP Gateways

Summary

Add IPNS Signed Records response format to the HTTP Gateway.

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

The reference implementation in Kubo 0.19 provides reusable assertions.

:::issue 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>
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.