record

Documentation

Overview

Deprecated: This package has moved into go-libp2p as a sub-package: github.com/libp2p/go-libp2p/core/record.

Index

• Variables
• func ConsumeEnvelope(data []byte, domain string) (envelope *Envelope, rec Record, err error)
• func RegisterType(prototype Record)
• type Envelope
  • 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)
• type Record

Variables

var ErrEmptyDomain = record.ErrEmptyDomain

Deprecated: use github.com/libp2p/go-libp2p/core/record.ErrEmptyDomain instead

var ErrEmptyPayloadType = record.ErrEmptyPayloadType

Deprecated: use github.com/libp2p/go-libp2p/core/record.ErrEmptyPayloadType instead

var ErrInvalidSignature = record.ErrInvalidSignature

Deprecated: use github.com/libp2p/go-libp2p/core/record.ErrInvalidSignature instead

var (
	// ErrPayloadTypeNotRegistered is returned from ConsumeEnvelope when the Envelope's
	// PayloadType does not match any registered Record types.
	// Deprecated: use github.com/libp2p/go-libp2p/core/record.ErrPayloadTypeNotRegistered instead
	ErrPayloadTypeNotRegistered = record.ErrPayloadTypeNotRegistered
)

Functions

func ConsumeEnvelope

func ConsumeEnvelope(data []byte, domain string) (envelope *Envelope, rec Record, err error)

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. Deprecated: use github.com/libp2p/go-libp2p/core/record.ConsumeEnvelope instead

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

Deprecated: use github.com/libp2p/go-libp2p/core/record.RegisterType instead

Types

type Envelope

type Envelope = record.Envelope

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. Deprecated: use github.com/libp2p/go-libp2p/core/record.Envelope instead

func ConsumeTypedEnvelope

func ConsumeTypedEnvelope(data []byte, destRecord Record) (envelope *Envelope, err error)

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. Deprecated: use github.com/libp2p/go-libp2p/core/record.ConsumeTypedEnvelope instead

func Seal

func Seal(rec Record, privateKey crypto.PrivKey) (*Envelope, error)

Seal marshals the given Record, places the marshaled bytes inside an Envelope, and signs with the given private key. Deprecated: use github.com/libp2p/go-libp2p/core/record.Seal instead

func UnmarshalEnvelope

func UnmarshalEnvelope(data []byte) (*Envelope, error)

UnmarshalEnvelope unmarshals a serialized Envelope protobuf message, without validating its contents. Most users should use ConsumeEnvelope. Deprecated: use github.com/libp2p/go-libp2p/core/record.UnmarshalEnvelope instead

type Record

type Record = record.Record

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. Deprecated: use github.com/libp2p/go-libp2p/core/record.Record instead