Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyDomain = errors.New("envelope domain must not be empty")
var ErrEmptyPayloadType = errors.New("payloadType must not be empty")
var ErrInvalidSignature = errors.New("invalid signature or incorrect domain")
var ( // ErrPayloadTypeNotRegistered is returned from ConsumeEnvelope when the Envelope's // PayloadType does not match any registered Record types. ErrPayloadTypeNotRegistered = errors.New("payload type is not registered") )
Functions ¶
func ConsumeEnvelope ¶
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)
}
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.
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.
func RegisterType ¶
func RegisterType(prototype Record)
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..
Types ¶
type Envelope ¶
type Envelope struct {
// The public key that can be used to verify the signature and derive the peer id of the signer.
PublicKey crypto.PubKey
// A binary identifier that indicates what kind of data is contained in the payload.
// TODO(yusef): enforce multicodec prefix
PayloadType []byte
// The envelope payload.
RawPayload []byte
// contains filtered or unexported fields
}
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.
func ConsumeTypedEnvelope ¶
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.
func Seal ¶
Seal marshals the given Record, places the marshaled bytes inside an Envelope, and signs with the given private key.
func UnmarshalEnvelope ¶
UnmarshalEnvelope unmarshals a serialized Envelope protobuf message, without validating its contents. Most users should use ConsumeEnvelope.
func (*Envelope) Equal ¶
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.
func (*Envelope) Marshal ¶
Marshal returns a byte slice containing a serialized protobuf representation of a Envelope.
func (*Envelope) Record ¶
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.
func (*Envelope) TypedRecord ¶
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.
type Record ¶
type Record interface {
// 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.
Domain() string
// 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 lookup the correct Record type to unmarshal the Envelope payload into.
Codec() []byte
// MarshalRecord converts a Record instance to a []byte, so that it can be used as an
// Envelope payload.
MarshalRecord() ([]byte, error)
// UnmarshalRecord unmarshals a []byte payload into an instance of a particular Record type.
UnmarshalRecord([]byte) 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.
Source Files
Directories