IPNS Record and Protocol

2.1 Key Types

Implementations MUST support Ed25519 with signatures defined in [rfc8032]. Ed25519 is the current default key type.

Implementations SHOULD support RSA if they wish to interoperate with legacy IPNS names (RSA was used before Ed25519).

Implementations MAY support Secp256k1 and ECDSA for private use, but peers from the public IPFS swarm and DHT may not be able to resolve IPNS records signed by these optional key types.

When implementing support for key types, follow signature implementation notes from PeerID specs.

In all cases, the IPNS implementation MAY allow the user to enable/disable specific key types via configuration. Note that disabling support for compulsory key type will hinder IPNS interop.

2.2 Key Serialization Format

IPNS encodes keys in protobuf containing a KeyType and the encoded key in a Data field:

syntax = "proto2";

enum KeyType {
 RSA = 0;
 Ed25519 = 1;
 Secp256k1 = 2;
 ECDSA = 3;
}

// PublicKey
message PublicKey {
 required KeyType Type = 1;
 required bytes Data = 2;
}

// PrivateKey
message PrivateKey {
 required KeyType Type = 1;
 required bytes Data = 2;
}

Note:

• Data encoding depends on KeyType (see Key Types)

• Although private keys are not transmitted over the wire, the PrivateKey serialization format used to store keys on disk is also included as a reference for IPNS implementers who would like to import existing IPNS key pairs.

• PublicKey and PrivateKey structures were originally defined in PeerID specification, and are currently the same in both libp2p and IPNS. If the PeerID specification ever changes in the future, definition from this file takes the precedence.

3.1 String Representation

IPNS Name should be represented as a CIDv1 with libp2p-key multicodec (code 0x72), and encoded using case-insensitive Multibase such as Base36.

A good practice is to prefix IPNS Name with /ipns/ namespace, and refer to IPNS addresses as /ipns/{ipns-name} (or /ipns/{libp2p-key}).

4.1 Record Fields

A logical IPNS Record is a data structure containing the following fields:

4.2 Record Serialization Format

For storing this structured data at rest and on the wire, we use IpnsEntry encoded as protobuf, which is a language-neutral, platform neutral extensible mechanism for serializing structured data. The extensible part of IPNS Record is placed in IpnsEntry.data field, which itself is encoded using a strict and deterministic subset of CBOR named DAG-CBOR.

This canonical serialization format uses the application/vnd.ipfs.ipns-record content type.

message IpnsEntry {
 enum ValidityType {
  // setting an EOL says "this record is valid until..."
  EOL = 0;
 }

 // legacy V1 copy of data[Value]
 optional bytes value = 1;

 // legacy V1 field, verify 'signatureV2' instead
 optional bytes signatureV1 = 2;

 // legacy V1 copies of data[ValidityType] and data[Validity]
 optional ValidityType validityType = 3;
 optional bytes validity = 4;

 // legacy V1 copy of data[Sequence]
 optional uint64 sequence = 5;

 // legacy V1 copy copy of data[TTL]
 optional uint64 ttl = 6;

 // Optional Public Key to be used for signature verification.
 // Used for big keys such as old RSA keys. Including the public key as part of
 // the record itself makes it verifiable in offline mode, without any additional lookup.
 // For newer Ed25519 keys, the public key is small enough that it can be embedded in the
 // IPNS Name itself, making this field unnecessary.
 optional bytes pubKey = 7;

 // (mandatory V2) signature of the IPNS record
 optional bytes signatureV2 = 8;

 // (mandatory V2) extensible record data in DAG-CBOR format
 optional bytes data = 9;
}

4.3 Backward Compatibility

Implementations that want to interop with the public IPFS swarm MUST maintain backward compatibility for legacy consumers of IPNS records:

• A legacy publisher MUST always be able to update to the latest implementation of this specification without breaking record resolution for legacy consumers.
• A legacy consumer MUST always be able to resolve IPNS name, even when publisher updated to the latest implementation of this specification.

This means, for example, that changes made to the IpnsEntry protobuf, or validation logic should always be additive.

Future changes to this spec should include design decisions that allow legacy nodes to gracefully ignore new fields and verify compatible records using legacy logic.

5.1 Overview

Taking into consideration a p2p network, each peer should be able to publish IPNS records to the network, as well as to resolve the IPNS records published by other peers.

When a node intends to publish a record to the network, an IPNS record needs to be created first. The node needs to have a previously generated asymmetric key pair to create the record according to the data structure previously specified. It is important pointing out that the record needs to be uniquely identified in the network. As a result, the record identifier should be a hash of the public key used to sign the record.

As an IPNS record may be updated during its lifetime, a versioning related logic is needed during the publish process. As a consequence, the record must be stored locally, in order to enable the publisher to understand which is the most recent record published. Accordingly, before creating the record, the node must verify if a previous version of the record exists, and update the sequence value for the new record being created.

Once the record is created, it is ready to be spread through the network. This way, a peer can use whatever routing system it supports to make the record accessible to the remaining peers of the network.

The means of distribution are left unspecified. Implementations MAY choose to publish signed record using multiple routing systems, such as libp2p Kademlia DHT or [ipns-pubsub-router] (see Routing record).

On the other side, each peer must be able to get a record published by another node. It only needs to have the unique identifier used to publish the record to the network. Taking into account the routing system being used, we may obtain a set of occurrences of the record from the network. In this case, records can be compared using the sequence number, in order to obtain the most recent one.

As soon as the node has the most recent record, the signature and the validity must be verified, in order to conclude that the record is still valid and not compromised.

Finally, the network nodes may also republish their records, so that the records in the network continue to be valid to the other nodes.

5.2 Record Creation

IPNS record MUST be serialized as IpnsEntry protobuf, and IpnsEntry.data MUST be signed (IpnsEntry.signatureV2) using the private key.

Creating a new IPNS record MUST follow the below steps:

1. Create IpnsEntry protobuf

2. Create a DAG-CBOR document with values for Value, Validity, ValidityType, Sequence, and TTL

   • Following DAG-CBOR specification is paramount. The CBOR bytes will be used for signing and the serialized form must be deterministic.

   • If you are updating an existing record, remember to increase values in sequence and validity

3. Store DAG-CBOR in IpnsEntry.data.

   • If you want to store additional metadata in the record, add it under unique keys at IpnsEntry.data.

   • The order of fields impacts signature verification. If you are using an alternative CBOR implementation, make sure the CBOR field order follows [rfc7049] sorting rules: length and then bytewise. The order of fields impacts signature verification.

4. If your public key can't be inlined inside the IPNS Name, include a serialized copy in IpnsEntry.pubKey

   • This step SHOULD be skipped for Ed25519, and any other key types that are small enough (32 bytes) to be inlined inside IPNS Name itself.

5. Create IpnsEntry.signatureV2

   • Create bytes for signing by concatenating ipns-signature: prefix (bytes in hex: 69706e732d7369676e61747572653a) with raw CBOR bytes from IpnsEntry.data

   • Sign concatenated bytes from the previous step using the private key, and store the signature in IpnsEntry.signatureV2

6. Confirm that the serialized IpnsEntry bytes sum to less than or equal to the size limit.

Created IpnsEntry protobuf includes signed data CBOR and optional public key:

message IpnsEntry {
 optional bytes pubKey = 7;
 optional bytes signatureV2 = 8;
 optional bytes data = 9;
}

The IpnsEntry.data CBOR document includes key-value pairs for Value, Validity, ValidityType, Sequence and TTL. Keys are sorted and serialized in order that follows the DAG-CBOR specification:

// IpnsEntry.data
{
  Sequence: …
  TTL: …
  Validity: …
  ValidityType: …
  Value: …
}

5.3 Record Verification

Implementations MUST resolve IPNS Names only using verified records. Record's data and signature verification MUST be implemented as outlined below, and fail on the first error.

1. Before parsing the protobuf, confirm that the serialized IpnsEntry bytes sum to less than or equal to the size limit.
2. Confirm IpnsEntry.signatureV2 and IpnsEntry.data are present and are not empty
3. Extract public key
   • Use IpnsEntry.pubKey or a cached entry in the local key store, if present.
   • If public key is missing
     • Assume the public key is inlined in the IPNS Name itself (e.g., Ed25519 inlined using identity multihash)
     • Confirm Multihash type is identity
     • Unmarshall public key from Multihash digest
4. Deserialize IpnsEntry.data as a DAG-CBOR document
5. Create bytes for signature verification by concatenating ipns-signature: prefix (bytes in hex: 69706e732d7369676e61747572653a) with raw CBOR bytes from IpnsEntry.data
6. Verify the signature in IpnsEntry.signatureV2 against the concatenated result from the previous step.
7. If IpnsEntry.signatureV1 or IpnsEntry.value is present, confirm the values in IpnsEntry protobuf match deserialized ones from IpnsEntry.data:
   • IpnsEntry.value must match IpnsEntry.data[Value]
   • IpnsEntry.validity must match IpnsEntry.data[Validity]
   • IpnsEntry.validityType must match IpnsEntry.data[ValidityType]
   • IpnsEntry.sequence must match IpnsEntry.data[Sequence]
   • IpnsEntry.ttl must match IpnsEntry.data[TTL]
8. Check Validity
   • If ValidityType is 0 (EOL) parse the Validity as an ASCII string that follows notation from [rfc3339] (1970-01-01T00:00:00.000000001Z) and confirm it is bigger than the current time.

Value from IpnsEntry.signatureV1 MUST never be used for signature verification. Implementations MUST ensure IpnsEntry.signatureV2 is used instead.

Value from IpnsEntry.value MUST never be used unless it is the same as signed IpnsEntry.data[Value].

6.1 Test Vectors

Below are test vectors in Record Serialization Format, along with the expected verification results. The 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

6.2 Integration with IPFS

Below are additional notes for implementers, documenting how IPNS is integrated within IPFS ecosystem.