IPIP-0428: Allowing V2-Only Records in IPNS

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

1. Summary

Introduce support for creation and validation of compact, V2-only IPNS Records.

2. Motivation

IPNS record creation and validation is overly complex due to the legacy of decisions made in 2021.

The "V1+V2" record creation and validation was reverse-engineered and documented the current state in ipfs/specs#319, which created a base for specifications to improve upon.

A quick refresher on how IPNS Record lifecycle works today (2023 Q2):

We've been producing and expecting these hybrid V1+V2 records since 2021.

An unfortunate result is that all mandatory values MUST be duplicated, even when both ends use a modern client that only cares about signatureV2 that guards CBOR field, otherwise the record will not be valid.

What this IPIP aims to improve is allow implementations to produce lean, V2-only IPNS records and ensure clients will interpret them as valid IPNS.

3. Detailed design

Finish V2 story by making V2-Only records possible, namely:

For details, see the updated [ipns-record] specification.

4. Design rationale

For modern IPNS, the outer IpnsEntry protobuf should effectively only have two required fields: data and its signatureV2, and such record, as long signature is valid, should be accepted as valid.

At the same time, we don't want to break existig software, especially software and hardware devices which use IPNS for pulling updates.

We can get to that future in two steps:

  1. Reference implementations (boxo/ipns, js-ipns) will keep producing V1+V2 records as backward-compatible default, but we adjust validation algorithm to allow V2-only records, and support creation of such records as opt-in in modern implementations of IPFS+IPNS, like Kubo (GO) and Helia (JS).

    • Namely, only check/require fields to be duplicated in top level protobuf IF signatureV1 is present in the IpnsEntry protobuf.
      • IF there is no signatureV1, the V1 record would be invalid anyway.
      • IF there is no signatureV1 but signatureV2 and data fields are present and valid, the V2-only record should be considered valid.
        • This will allow people to build V2-only systems that produce records that are considered valid.
  2. At some point in the future, e.g. when we see the majority of the public swarm supports V2-Only records, libraries like boxo/ipns, js-ipns and implementations like Kubo will stop producing V1+V2 and switch to publishing V2-only records that are protobuf with only two fields: Data CBOR+signatureV2.

4.1 User benefit

4.2 Compatibility

4.3 Security

It is highly advised to implement validation conformance tests using the fixtures included at the end of this IPIP.

4.4 Alternatives

Describe alternate designs that were considered and related work.

  1. Just switch to V2-only as the new default!

    • No, this would be a breaking change. We have to do this in two steps, because we've rushed the way V2 was introduced in 2021, and STILL require field copying, even when signatureV1 is missing. So technically there was never "V2", it was more like "V1.5". Only with this IPIP, we finally adjust validation to only care about CBOR values when there is no signatureV1.
  2. Why keeping the outer protobuf envelope? Could we make IPNS DAG-CBOR-only?

    • Due to how long it takes for decentralized network nodes to upgrade, we prefer evolution rather than revolution.
    • Protobuf is a useful envelope for two reasons:
      1. Ensures the opaque V2-only record can be passed and stored in existing infrastructure.
      2. Allows us to evolve IPNS record ("V3") in the future without impacting existing infrastructure.

5. Test fixtures

To make testing easier below are test vectors in form of IPNS records along with the expected verification results. These test records are valid for 100 years, making them safe for use in CI tests.

  1. V1-only → record invalid
  2. V1+V2 (both signatures valid) → record valid, value points at /ipfs/bafkqaddwgevxmmraojswg33smq
  3. V1+V2 (both signatures valid, but 'value' is different in V1 pb vs V2 CBOR) → record invalid
  4. V1+V2 (only signatureV1 valid) → record invalid
  5. V1+V2 (only signatureV2 valid) → record valid, value points at /ipfs/bafkqahtwgevxmmrao5uxi2bamjzg623fnyqhg2lhnzqxi5lsmuqhmmi
  6. V2-only (no V1 fields) → record valid

Implementers can either write own tests against the above test vectors, or run gateway-conformance test suite, which includes tests for these vectors since gateway-conformance/pull/157.

A. References

IPNS Record and Protocol. Vasco Santos; Steve Allen; Marcin Rataj; Henrique Dias; Gus Eggert. 2023-07-24. URL: https://specs.ipfs.tech/ipns/ipns-record/
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119