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 ¶
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 ¶
ExtractPublicKey extracts a crypto.PubKey matching the given Name from the IPNS Record, if possible.
func MarshalRecord ¶ added in v0.11.0
MarshalRecord encodes the given IPNS Record into its Protobuf serialization format.
func Validate ¶
Validates validates the given IPNS Record against the given crypto.PubKey, following the Record Verification specification.
Types ¶
type Name ¶ added in v0.11.0
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 ¶ added in v0.11.0
func NameFromPeer ¶ added in v0.11.0
func NameFromRoutingKey ¶ added in v0.11.0
NameFromRoutingKey creates a Name from the given IPNS Name in its routing key representation. See Name.RoutingKey for more information.
func NameFromString ¶ added in v0.11.0
NameFromString creates a Name from the given IPNS Name in its string representation.
func (Name) AsPath ¶ added in v0.14.0
AsPath returns the IPNS Name as a path.Path prefixed by path.IPNSNamespace.
func (Name) Cid ¶ added in v0.11.0
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) MarshalJSON ¶ added in v0.11.0
MarshalJSON implements json.Marshaler interface. IPNS Name will marshal as a string using Name.String.
func (Name) RoutingKey ¶ added in v0.11.0
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 ¶ added in v0.11.0
String returns the human-readable IPNS Name, encoded as a CIDv1 with libp2p-key multicodec (0x72) with case-insensitive Base36.
func (*Name) UnmarshalJSON ¶ added in v0.11.0
UnmarshalJSON implements json.Unmarshaler interface. IPNS Name will unmarshal from a string via NameFromString.
type Option ¶ added in v0.11.0
type Option func(*options)
func WithPublicKey ¶ added in v0.11.0
func WithV1Compatibility ¶ added in v0.11.0
type Record ¶ added in v0.11.0
type Record struct {
// contains filtered or unexported fields
}
Record represents an IPNS Record.
func NewRecord ¶ added in v0.11.0
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 ¶ added in v0.11.0
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) Validity ¶ added in v0.11.0
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 ¶ added in v0.11.0
func (rec *Record) ValidityType() (ValidityType, error)
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 ¶
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.
type ValidityType ¶ added in v0.11.0
type ValidityType int64
const ValidityEOL ValidityType = 0
ValidityEOL means "this record is valid until {Validity}". This is currently the only supported Validity type.
Source Files
Directories