ipns

README

IPNS

A reference implementation of the IPNS Record and Verification specification.

Documentation

• Go Documentation: https://pkg.go.dev/github.com/ipfs/boxo/ipns
• IPNS Record Specification: https://specs.ipfs.tech/ipns/ipns-record/

Example

Here's an example on how to create an IPNS Record:

import (
	"crypto/rand"
	"time"

	"github.com/ipfs/boxo/ipns"
	"github.com/ipfs/boxo/path"
	ic "github.com/libp2p/go-libp2p/core/crypto"
)

func main() {
	// Create a private key to sign your IPNS record. Most of the time, you
	// will want to retrieve an already-existing key from Kubo, for example.
	sk, _, err := ic.GenerateEd25519Key(rand.Reader)
	if err != nil {
		panic(err)
	}

	// Define the path this record will point to.
	path, err := path.NewPath("/ipfs/bafkqac3jobxhgidsn5rww4yk")
	if err != nil {
		panic(err)
	}

	// Until when the record is valid.
	eol := time.Now().Add(time.Hour)

	// For how long should caches cache the record.
	ttl := time.Second * 20

	record, err := ipns.NewRecord(sk, path, 1, eol, ttl)
	if err != nil {
		panic(err)
	}

	// Now you have an IPNS Record.
}

Documentation

Index

• Constants
• Variables
• func ExtractPublicKey(rec *Record, name Name) (ic.PubKey, error)
• func MarshalRecord(rec *Record) ([]byte, error)
• func Validate(rec *Record, pk ic.PubKey) error
• func ValidateWithName(rec *Record, name Name) error
• type Name
  • func NameFromCid(c cid.Cid) (Name, error)
  • func NameFromPeer(pid peer.ID) Name
  • func NameFromRoutingKey(data []byte) (Name, error)
  • func NameFromString(str string) (Name, error)
  • func (n Name) AsPath() path.Path
  • func (n Name) Cid() cid.Cid
  • func (n Name) Equal(other Name) bool
  • func (n Name) MarshalJSON() ([]byte, error)
  • func (n Name) Peer() peer.ID
  • func (n Name) RoutingKey() []byte
  • func (n Name) String() string
  • func (n *Name) UnmarshalJSON(b []byte) error
• type Option
  • func WithPublicKey(embedded bool) Option
  • func WithV1Compatibility(compatible bool) Option
• type Record
  • func NewRecord(sk ic.PrivKey, value path.Path, seq uint64, eol time.Time, ttl time.Duration, ...) (*Record, error)
  • func UnmarshalRecord(data []byte) (*Record, error)
  • func (rec *Record) PubKey() (ic.PubKey, error)
  • func (rec *Record) Sequence() (uint64, error)
  • func (rec *Record) TTL() (time.Duration, error)
  • func (rec *Record) Validity() (time.Time, error)
  • func (rec *Record) ValidityType() (ValidityType, error)
  • func (rec *Record) Value() (path.Path, error)
• type Validator
  • func (v Validator) Select(k string, vals [][]byte) (int, error)
  • func (v Validator) Validate(key string, value []byte) error
• type ValidityType

Constants

const (

	// DefaultRecordLifetime defines for how long IPNS record should be valid
	// when ValidityType is 0. The default here aims to match the record
	// expiration window of Amino DHT.
	DefaultRecordLifetime = 48 * time.Hour

	// DefaultRecordTTL specifies how long the record can be returned from
	// cache before checking for update again. The function of this TTL is
	// similar to TTL of DNS record, and the default here is a trade-off
	// between faster updates and benefiting from various types of caching.
	DefaultRecordTTL = 1 * time.Hour
)

const MaxRecordSize int = 10 << (10 * 1)

MaxRecordSize is the IPNS Record size limit.

const (
	// NamespacePrefix is the prefix of the IPNS namespace.
	NamespacePrefix = "/ipns/"
)

Variables

var ErrDataMissing = errors.New("record is missing the dag-cbor data field")

ErrDataMissing is returned when an IPNS Record is missing the data field.

var ErrExpiredRecord = errors.New("record is expired")

ErrExpiredRecord is returned when an IPNS Record is invalid due to being expired.

var ErrInvalidName = errors.New("name is invalid")

ErrInvalidName is returned when an IPNS Name is invalid.

var ErrInvalidPath = errors.New("value is not a valid content path")

ErrInvalidPath is returned when an IPNS Record has an invalid path.

var ErrInvalidPublicKey = errors.New("public key invalid")

ErrInvalidPublicKey is returned when an IPNS Record has an invalid public key,

var ErrInvalidRecord = errors.New("record is malformed")

ErrInvalidRecord is returned when an IPNS Record is malformed.

var ErrInvalidValidity = errors.New("record contains an invalid validity")

ErrInvalidValidity is returned when an IPNS Record has a known validity type, but the validity value is invalid.

var ErrPublicKeyMismatch = errors.New("record public key does not match the expected public key")

ErrPublicKeyMismatch is return when the public key embedded in an IPNS Record does not match the expected public key.

var ErrPublicKeyNotFound = errors.New("public key not found")

ErrPublicKeyNotFound is returned when the public key is not found.

var ErrRecordSize = errors.New("record exceeds allowed size limit")

ErrRecordSize is returned when an IPNS Record exceeds the maximum size.

var ErrSignature = errors.New("signature verification failed")

ErrSignature is returned when an IPNS Record fails signature verification.

var ErrUnrecognizedValidity = errors.New("record contains an unrecognized validity type")

ErrUnrecognizedValidity is returned when an IPNS Record has an unknown validity type.

Functions

func ExtractPublicKey

func ExtractPublicKey(rec *Record, name Name) (ic.PubKey, error)

ExtractPublicKey extracts a crypto.PubKey matching the given Name from the IPNS Record, if possible.

func MarshalRecord

func MarshalRecord(rec *Record) ([]byte, error)

MarshalRecord encodes the given IPNS Record into its Protobuf serialization format.

func Validate

func Validate(rec *Record, pk ic.PubKey) error

Validates validates the given IPNS Record against the given crypto.PubKey, following the Record Verification specification.

func ValidateWithName

func ValidateWithName(rec *Record, name Name) error

ValidateWithName validates the given IPNS Record against the given Name.

Types

type Name

type Name struct {
	// contains filtered or unexported fields
}

Name represents a Multihash of a serialized public key according to the IPNS Name specifications.

func NameFromCid

func NameFromCid(c cid.Cid) (Name, error)

NameFromCid creates a Name from the given cid.Cid.

func NameFromPeer

func NameFromPeer(pid peer.ID) Name

NameFromPeer creates a Name from the given peer.ID.

func NameFromRoutingKey

func NameFromRoutingKey(data []byte) (Name, error)

NameFromRoutingKey creates a Name from the given IPNS Name in its routing key representation. See Name.RoutingKey for more information.

func NameFromString

func NameFromString(str string) (Name, error)

NameFromString creates a Name from the given IPNS Name in its string representation.

func (Name) AsPath

func (n Name) AsPath() path.Path

AsPath returns the IPNS Name as a path.Path prefixed by path.IPNSNamespace.

func (Name) Cid

func (n Name) Cid() cid.Cid

Cid returns Name encoded as a cid.Cid of the public key. If the IPNS Name is invalid (e.g., empty), this will return the empty Cid.

func (Name) Equal

func (n Name) Equal(other Name) bool

Equal returns whether the records are equal.

func (Name) MarshalJSON

func (n Name) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface. IPNS Name will marshal as a string using Name.String.

func (Name) Peer

func (n Name) Peer() peer.ID

Peer returns Name as a peer.ID.

func (Name) RoutingKey

func (n Name) RoutingKey() []byte

RoutingKey returns the binary IPNS Routing Key for the given Name. Note that the intended use of this function is for routing purposes only. The output of this function is binary, not human readable. For a human-readable string, see [Name.Key].

func (Name) String

func (n Name) String() string

String returns the human-readable IPNS Name, encoded as a CIDv1 with libp2p-key multicodec (0x72) with case-insensitive Base36.

func (*Name) UnmarshalJSON

func (n *Name) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler interface. IPNS Name will unmarshal from a string via NameFromString.

type Option

type Option func(*options)

func WithPublicKey

func WithPublicKey(embedded bool) Option

func WithV1Compatibility

func WithV1Compatibility(compatible bool) Option

type Record

type Record struct {
	// contains filtered or unexported fields
}

Record represents an IPNS Record.

func NewRecord

func NewRecord(sk ic.PrivKey, value path.Path, seq uint64, eol time.Time, ttl time.Duration, opts ...Option) (*Record, error)

NewRecord creates a new IPNS Record and signs it with the given private key. By default, we embed the public key for key types whose peer IDs do not encode the public key, such as RSA and ECDSA key types. This can be changed with the option WithPublicKey. In addition, records are, by default created with V1 compatibility.

func UnmarshalRecord

func UnmarshalRecord(data []byte) (*Record, error)

UnmarshalRecord parses the Protobuf-serialized IPNS Record into a usable Record struct. Please note that this function does not perform a full validation of the record. For that use Validate.

func (*Record) PubKey

func (rec *Record) PubKey() (ic.PubKey, error)

func (*Record) Sequence

func (rec *Record) Sequence() (uint64, error)

func (*Record) TTL

func (rec *Record) TTL() (time.Duration, error)

func (*Record) Validity

func (rec *Record) Validity() (time.Time, error)

Validity returns the validity of the IPNS Record. This function returns ErrUnrecognizedValidity if the validity type of the record isn't EOL. Otherwise, it returns an error if it can't parse the EOL.

func (*Record) ValidityType

func (rec *Record) ValidityType() (ValidityType, error)

func (*Record) Value

func (rec *Record) Value() (path.Path, error)

Value returns the path.Path that is embedded in this IPNS Record. If the path is invalid, an ErrInvalidPath is returned.

type Validator

type Validator struct {
	// KeyBook, if non-nil, is used to lookup keys for validating IPNS Records.
	KeyBook peerstore.KeyBook
}

Validator is an IPNS Record validator that satisfies the record.Validator interface from Libp2p.

func (Validator) Select

func (v Validator) Select(k string, vals [][]byte) (int, error)

Select selects the best record by checking which has the highest sequence number and latest validity. This function returns an error if any of the records fail to parse.

This function does not validate the records. The caller is responsible for ensuring that the Records are valid by using Validate.

func (Validator) Validate

func (v Validator) Validate(key string, value []byte) error

Validate validates an IPNS record.

type ValidityType

type ValidityType int64

const ValidityEOL ValidityType = 0

ValidityEOL means "this record is valid until {Validity}". This is currently the only supported Validity type.