README
¶
go-ipns
ipns record definitions
This package contains all of the components necessary to create, understand, and validate IPNS records. It does not publish or resolve those records. go-ipfs uses this package internally to manipulate records.
Lead Maintainer
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
Contribute
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.
Want to hack on IPFS?
License
Copyright (c) Protocol Labs, Inc. under the MIT license. See LICENSE file for details.
Documentation
¶
Index ¶
- Variables
- func Compare(a, b *pb.Dms3NsEntry) (int, error)
- func Create(sk ic.PrivKey, val []byte, seq uint64, eol time.Time) (*pb.Dms3NsEntry, error)
- func EmbedPublicKey(pk ic.PubKey, entry *pb.Dms3NsEntry) error
- func ExtractPublicKey(pid peer.ID, entry *pb.Dms3NsEntry) (ic.PubKey, error)
- func GetEOL(entry *pb.Dms3NsEntry) (time.Time, error)
- func RecordKey(pid peer.ID) string
- func Validate(pk ic.PubKey, entry *pb.Dms3NsEntry) error
- type Validator
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrBadRecord = errors.New("record could not be unmarshalled")
ErrBadRecord should be returned when an dms3ns record cannot be unmarshalled
var ErrExpiredRecord = errors.New("expired record")
ErrExpiredRecord should be returned when an dms3ns record is invalid due to being too old
var ErrInvalidPath = errors.New("record path invalid")
ErrInvalidPath should be returned when an dms3ns record path is not in a valid format
var ErrKeyFormat = errors.New("record key could not be parsed into peer ID")
ErrKeyFormat should be returned when an dms3ns record key is incorrectly formatted (not a peer ID)
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.
var ErrPublicKeyNotFound = errors.New("public key not found in peer store")
ErrPublicKeyNotFound should be returned when the public key corresponding to the dms3ns record path cannot be retrieved from the peer store
var ErrSignature = errors.New("record signature verification failed")
ErrSignature should be returned when an dms3ns record fails signature verification
var ErrUnrecognizedValidity = errors.New("unrecognized validity type")
ErrUnrecognizedValidity is returned when an IpnsRecord has an unknown validity type.
Functions ¶
func Compare ¶
func Compare(a, b *pb.Dms3NsEntry) (int, error)
Compare compares two DMS3NS 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).
func Create ¶
Create creates a new DMS3NS 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`.
Example ¶
// Generate a private key to sign the DMS3NS record with. Most of the time,
// however, you'll want to retrieve an already-existing key from DMS3 using
// go-dms3/core/coreapi CoreAPI.KeyAPI() interface.
privateKey, _, err := ci.GenerateKeyPair(ci.RSA, 2048)
if err != nil {
panic(err)
}
// Create an DMS3NS record that expires in one hour and points to the DMS3 address
// /dms3/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5
dms3nsRecord, err := Create(privateKey, []byte("/dms3/Qme1knMqwt1hKZbc1BmQFmnm9f36nyQGwXxPGVpVJ9rMK5"), 0, time.Now().Add(1*time.Hour))
if err != nil {
panic(err)
}
fmt.Println(dms3nsRecord)
Output:
func EmbedPublicKey ¶
func EmbedPublicKey(pk ic.PubKey, entry *pb.Dms3NsEntry) error
EmbedPublicKey embeds the given public key in the given dms3ns entry. While not strictly required, some nodes (e.g., DHT servers) may reject DMS3NS entries that don't embed their public keys as they may not be able to validate them efficiently.
func ExtractPublicKey ¶
ExtractPublicKey extracts a public key matching `pid` from the DMS3NS record, if possible.
This function returns (nil, nil) when no public key can be extracted and nothing is malformed.
func GetEOL ¶
func GetEOL(entry *pb.Dms3NsEntry) (time.Time, error)
GetEOL returns the EOL of this DMS3NS 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.
Types ¶
type Validator ¶
type Validator struct {
// KeyBook, if non-nil, will be used to lookup keys for validating DMS3NS
// records.
KeyBook pstore.KeyBook
}
Validator is an DMS3NS record validator that satisfies the libp2p record validator interface.
Source Files
Directories