Envelope contains an arbitrary []byte payload, signed by a libp2p peer.
Envelopes are signed in the context of a particular "domain", which is a
string specified when creating and verifying the envelope. You must know the
domain string used to produce the envelope in order to verify the signature
and access the payload. A binary identifier that indicates what kind of data is contained in the payload.
TODO(yusef): enforce multicodec prefix The public key that can be used to verify the signature and derive the peer id of the signer. The envelope payload. Equal returns true if the other Envelope has the same public key,
payload, payload type, and signature. This implies that they were also
created with the same domain string. Marshal returns a byte slice containing a serialized protobuf representation
of an Envelope. Record returns the Envelope's payload unmarshalled as a Record.
The concrete type of the returned Record depends on which Record
type was registered for the Envelope's PayloadType - see record.RegisterType.
Once unmarshalled, the Record is cached for future access. TypedRecord unmarshals the Envelope's payload to the given Record instance.
It is the caller's responsibility to ensure that the Record type is capable
of unmarshalling the Envelope payload. Callers can inspect the Envelope's
PayloadType field to determine the correct type of Record to use.
This method will always unmarshal the Envelope payload even if a cached record
exists.
*Envelope : github.com/gogo/protobuf/proto.Marshaler
*Envelope : github.com/golang/protobuf/proto.Marshaler
func ConsumeEnvelope(data []byte, domain string) (envelope *Envelope, rec Record, err error)
func ConsumeTypedEnvelope(data []byte, destRecord Record) (envelope *Envelope, err error)
func Seal(rec Record, privateKey crypto.PrivKey) (*Envelope, error)
func UnmarshalEnvelope(data []byte) (*Envelope, error)
func github.com/libp2p/go-libp2p/core/peerstore.CertifiedAddrBook.GetPeerRecord(p peer.ID) *Envelope
func (*Envelope).Equal(other *Envelope) bool
func github.com/libp2p/go-libp2p/core/peerstore.CertifiedAddrBook.ConsumePeerRecord(s *Envelope, ttl time.Duration) (accepted bool, err error)
Record represents a data type that can be used as the payload of an Envelope.
The Record interface defines the methods used to marshal and unmarshal a Record
type to a byte slice.
Record types may be "registered" as the default for a given Envelope.PayloadType
using the RegisterType function. Once a Record type has been registered,
an instance of that type will be created and used to unmarshal the payload of
any Envelope with the registered PayloadType when the Envelope is opened using
the ConsumeEnvelope function.
To use an unregistered Record type instead, use ConsumeTypedEnvelope and pass in
an instance of the Record type that you'd like the Envelope's payload to be
unmarshaled into. Codec is a binary identifier for this type of record, ideally a registered multicodec
(see https://github.com/multiformats/multicodec).
When a Record is put into an Envelope (see record.Seal), the Codec value will be used
as the Envelope's PayloadType. When the Envelope is later unsealed, the PayloadType
will be used to look up the correct Record type to unmarshal the Envelope payload into. Domain is the "signature domain" used when signing and verifying a particular
Record type. The Domain string should be unique to your Record type, and all
instances of the Record type must have the same Domain string. MarshalRecord converts a Record instance to a []byte, so that it can be used as an
Envelope payload. UnmarshalRecord unmarshals a []byte payload into an instance of a particular Record type.
*github.com/libp2p/go-libp2p/core/peer.PeerRecord
*github.com/libp2p/go-libp2p/p2p/protocol/circuitv2/proto.ReservationVoucher
func ConsumeEnvelope(data []byte, domain string) (envelope *Envelope, rec Record, err error)
func (*Envelope).Record() (Record, error)
func ConsumeTypedEnvelope(data []byte, destRecord Record) (envelope *Envelope, err error)
func RegisterType(prototype Record)
func Seal(rec Record, privateKey crypto.PrivKey) (*Envelope, error)
func (*Envelope).TypedRecord(dest Record) error
Package-Level Functions (total 5)
ConsumeEnvelope unmarshals a serialized Envelope and validates its
signature using the provided 'domain' string. If validation fails, an error
is returned, along with the unmarshalled envelope, so it can be inspected.
On success, ConsumeEnvelope returns the Envelope itself, as well as the inner payload,
unmarshalled into a concrete Record type. The actual type of the returned Record depends
on what has been registered for the Envelope's PayloadType (see RegisterType for details).
You can type assert on the returned Record to convert it to an instance of the concrete
Record type:
envelope, rec, err := ConsumeEnvelope(envelopeBytes, peer.PeerRecordEnvelopeDomain)
if err != nil {
handleError(envelope, err) // envelope may be non-nil, even if errors occur!
return
}
peerRec, ok := rec.(*peer.PeerRecord)
if ok {
doSomethingWithPeerRecord(peerRec)
}
If the Envelope signature is valid, but no Record type is registered for the Envelope's
PayloadType, ErrPayloadTypeNotRegistered will be returned, along with the Envelope and
a nil Record.
ConsumeTypedEnvelope unmarshals a serialized Envelope and validates its
signature. If validation fails, an error is returned, along with the unmarshalled
envelope, so it can be inspected.
Unlike ConsumeEnvelope, ConsumeTypedEnvelope does not try to automatically determine
the type of Record to unmarshal the Envelope's payload into. Instead, the caller provides
a destination Record instance, which will unmarshal the Envelope payload. It is the caller's
responsibility to determine whether the given Record type is able to unmarshal the payload
correctly.
rec := &MyRecordType{}
envelope, err := ConsumeTypedEnvelope(envelopeBytes, rec)
if err != nil {
handleError(envelope, err)
}
doSomethingWithRecord(rec)
Important: you MUST check the error value before using the returned Envelope. In some error
cases, including when the envelope signature is invalid, both the Envelope and an error will
be returned. This allows you to inspect the unmarshalled but invalid Envelope. As a result,
you must not assume that any non-nil Envelope returned from this function is valid.
RegisterType associates a binary payload type identifier with a concrete
Record type. This is used to automatically unmarshal Record payloads from Envelopes
when using ConsumeEnvelope, and to automatically marshal Records and determine the
correct PayloadType when calling Seal.
Callers must provide an instance of the record type to be registered, which must be
a pointer type. Registration should be done in the init function of the package
where the Record type is defined:
package hello_record
import record "github.com/libp2p/go-libp2p/core/record"
func init() {
record.RegisterType(&HelloRecord{})
}
type HelloRecord struct { } // etc..
Seal marshals the given Record, places the marshaled bytes inside an Envelope,
and signs with the given private key.
UnmarshalEnvelope unmarshals a serialized Envelope protobuf message,
without validating its contents. Most users should use ConsumeEnvelope.
ErrPayloadTypeNotRegistered is returned from ConsumeEnvelope when the Envelope's
PayloadType does not match any registered Record types.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
