ipns

README

go-ipns

ipns record definitions

❗ This repo is no longer maintained.

👉 We highly recommend switching to the maintained version at https://github.com/ipfs/boxo/tree/main/ipns. 🏎️ Good news! There is tooling and documentation to expedite a switch in your repo.

⚠️ If you continue using this repo, please note that security fixes will not be provided (unless someone steps in to maintain it).

📚 Learn more, including how to take the maintainership mantle or ask questions, here.

This package contains all of the components necessary to create, understand, and validate IPNS records. It does not publish or resolve those records. Kubo uses this package internally to manipulate records.

Usage

To create a new IPNS record:

import (
	"time"

	ipns "github.com/ipfs/go-ipns"
	crypto "github.com/libp2p/go-libp2p-crypto"
)

// Generate a private key to sign the IPNS record with. Most of the time, 
// however, you'll want to retrieve an already-existing key from IPFS using the
// go-ipfs/core/coreapi CoreAPI.KeyAPI() interface.
privateKey, publicKey, err := crypto.GenerateKeyPair(crypto.RSA, 2048)
if err != nil {
  panic(err)
}

// Create an IPNS record that expires in one hour and points to the IPFS address
// /ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5
ipnsRecord, err := ipns.Create(privateKey, []byte("/ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5"), 0, time.Now().Add(1*time.Hour))
if err != nil {
	panic(err)
}

Once you have the record, you’ll need to use IPFS to publish it.

There are several other major operations you can do with go-ipns. Check out the API docs or look at the tests in this repo for examples.

Documentation

https://godoc.org/github.com/ipfs/go-ipns

Want to hack on IPFS?

License

Copyright (c) Protocol Labs, Inc. under the MIT license. See LICENSE file for details.

Documentation

Index

• Constants
• Variables
• func Compare(a, b *pb.IpnsEntry) (int, error)
• func Create(sk ic.PrivKey, val []byte, seq uint64, eol time.Time, ttl time.Duration) (*pb.IpnsEntry, error)
• func EmbedPublicKey(pk ic.PubKey, entry *pb.IpnsEntry) error
• func ExtractPublicKey(pid peer.ID, entry *pb.IpnsEntry) (ic.PubKey, error)
• func GetEOL(entry *pb.IpnsEntry) (time.Time, error)
• func RecordKey(pid peer.ID) string
• func Validate(pk ic.PubKey, entry *pb.IpnsEntry) error
• type Validator
  • func (v Validator) Select(k string, vals [][]byte) (int, error)
  • func (v Validator) Validate(key string, value []byte) error

Examples

• Create

Constants

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

10 KiB limit defined in https://github.com/ipfs/specs/pull/319

Deprecated: use github.com/ipfs/boxo/ipns.MaxRecordSize

Variables

var ErrBadRecord = errors.New("record could not be unmarshalled")

ErrBadRecord should be returned when an ipns record cannot be unmarshalled

Deprecated: use github.com/ipfs/boxo/ipns.ErrBadRecord

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

ErrExpiredRecord should be returned when an ipns record is invalid due to being too old

Deprecated: use github.com/ipfs/boxo/ipns.ErrExpiredRecord

var ErrInvalidPath = errors.New("record path invalid")

ErrInvalidPath should be returned when an ipns record path is not in a valid format

Deprecated: use github.com/ipfs/boxo/ipns.ErrInvalidPath

var ErrKeyFormat = errors.New("record key could not be parsed into peer ID")

ErrKeyFormat should be returned when an ipns record key is incorrectly formatted (not a peer ID)

Deprecated: use github.com/ipfs/boxo/ipns.ErrKeyFormat

var ErrPublicKeyMismatch = errors.New("public key in record did not match expected pubkey")

ErrPublicKeyMismatch should be returned when the public key embedded in the record doesn't match the expected public key.

Deprecated: use github.com/ipfs/boxo/ipns.ErrPublicKeyMismatch

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

ErrPublicKeyNotFound should be returned when the public key corresponding to the ipns record path cannot be retrieved from the peer store

Deprecated: use github.com/ipfs/boxo/ipns.ErrPublicKeyNotFound

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

ErrRecordSize should be returned when an ipns record is invalid due to being too big

Deprecated: use github.com/ipfs/boxo/ipns.ErrRecordSize

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

ErrSignature should be returned when an ipns record fails signature verification

Deprecated: use github.com/ipfs/boxo/ipns.ErrSignature

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

ErrUnrecognizedValidity is returned when an IpnsRecord has an unknown validity type.

Deprecated: use github.com/ipfs/boxo/ipns.ErrUnrecognizedValidity

Functions

func Compare

func Compare(a, b *pb.IpnsEntry) (int, error)

Compare compares two IPNS entries. It returns:

* -1 if a is older than b * 0 if a and b cannot be ordered (this doesn't mean that they are equal) * +1 if a is newer than b

It returns an error when either a or b are malformed.

NOTE: It *does not* validate the records, the caller is responsible for calling `Validate` first.

NOTE: If a and b cannot be ordered by this function, you can determine their order by comparing their serialized byte representations (using `bytes.Compare`). You must do this if you are implementing a libp2p record validator (or you can just use the one provided for you by this package).

Deprecated: use github.com/ipfs/boxo/ipns.Compare

func Create

func Create(sk ic.PrivKey, val []byte, seq uint64, eol time.Time, ttl time.Duration) (*pb.IpnsEntry, error)

Create creates a new IPNS entry and signs it with the given private key.

This function does not embed the public key. If you want to do that, use `EmbedPublicKey`.

Deprecated: use github.com/ipfs/boxo/ipns.Create

Example

// Generate a private key to sign the IPNS record with. Most of the time,
// however, you'll want to retrieve an already-existing key from IPFS using
// go-ipfs/core/coreapi CoreAPI.KeyAPI() interface.
privateKey, _, err := ci.GenerateKeyPair(ci.RSA, 2048)
if err != nil {
	panic(err)
}

// Create an IPNS record that expires in one hour and points to the IPFS address
// /ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5
ipnsRecord, err := Create(privateKey, []byte("/ipfs/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5"), 0, time.Now().Add(1*time.Hour), 0)
if err != nil {
	panic(err)
}

fmt.Println(ipnsRecord)

func EmbedPublicKey

func EmbedPublicKey(pk ic.PubKey, entry *pb.IpnsEntry) error

EmbedPublicKey embeds the given public key in the given ipns entry. While not strictly required, some nodes (e.g., DHT servers) may reject IPNS entries that don't embed their public keys as they may not be able to validate them efficiently.

Deprecated: use github.com/ipfs/boxo/ipns.EmbedPublicKey

func ExtractPublicKey

func ExtractPublicKey(pid peer.ID, entry *pb.IpnsEntry) (ic.PubKey, error)

ExtractPublicKey extracts a public key matching `pid` from the IPNS record, if possible.

This function returns (nil, nil) when no public key can be extracted and nothing is malformed.

Deprecated: use github.com/ipfs/boxo/ipns.ExtractPublicKey

func GetEOL

func GetEOL(entry *pb.IpnsEntry) (time.Time, error)

GetEOL returns the EOL of this IPNS entry

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.

Deprecated: use github.com/ipfs/boxo/ipns.GetEOL

func RecordKey

func RecordKey(pid peer.ID) string

RecordKey returns the libp2p record key for a given peer ID.

Deprecated: use github.com/ipfs/boxo/ipns.RecordKey

func Validate

func Validate(pk ic.PubKey, entry *pb.IpnsEntry) error

Validates validates the given IPNS entry against the given public key.

Deprecated: use github.com/ipfs/boxo/ipns.Validate

Types

type Validator

type Validator struct {
	// KeyBook, if non-nil, will be used to lookup keys for validating IPNS
	// records.
	KeyBook pstore.KeyBook
}

Validator is an IPNS record validator that satisfies the libp2p record validator interface.

Deprecated: use github.com/ipfs/boxo/ipns.Validator

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

This function returns an error if any of the records fail to parse. Validate your records first!

func (Validator) Validate

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

Validate validates an IPNS record.