ndn

README

ndn package

ndn provides basic interfaces of NDN packet, specification abstraction, and low-level engine. Most high level packages will only depend on ndn, instead of specific implementations. To simplify implementation, Data and Interest are immutable. ndn.spec_2022 has a default implementation of these interfaces based on current NDN Spec.

Documentation

Index

• Constants
• Variables
• type Client
• type ConsumeExtArgs
• type ConsumeState
• type ContentType
• type Data
• type DataConfig
• type EncodedData
• type EncodedInterest
• type Engine
• type ErrInvalidValue
  • func (e ErrInvalidValue) Error() string
• type ErrNotSupported
  • func (e ErrNotSupported) Error() string
• type ExpressCallbackArgs
• type ExpressCallbackFunc
• type ExpressRArgs
• type Interest
• type InterestConfig
• type InterestHandler
• type InterestHandlerArgs
• type InterestResult
  • func (r InterestResult) String() string
• type KeyChain
• type KeyChainIdentity
• type KeyChainKey
• type ProduceArgs
• type SigChecker
• type SigType
  • func (t SigType) String() string
• type Signature
• type Signer
• type Spec
• type Store
• type Timer
• type TrustSchema
• type ValidateExtArgs
• type WireReplyFunc

Constants

const MaxNDNPacketSize = 8800

MaxNDNPacketSize is the maximum allowed NDN packet size

Variables

var ErrCancelled = errors.New("operation cancelled")

var ErrDeadlineExceed = errors.New("interest deadline exceeded")

ErrDeadlineExceed is returned when the deadline of the Interest passed.

var ErrFaceDown = errors.New("face is down. Unable to send packet")

ErrFaceDown is returned when the face is closed.

var ErrFailedToEncode = errors.New("failed to encode an NDN packet")

ErrFailedToEncode is returned when encoding fails but the input arguments are valid.

var ErrMultipleHandlers = errors.New("multiple handlers attached to the same prefix")

ErrMultipleHandlers is returned when multiple handlers are attached to the same prefix.

var ErrNetwork = errors.New("network error")

var ErrNoPubKey = errors.New("public key does not exist")

ErrNoPubKey is returned when the public key does not exist.

var ErrProtocol = errors.New("protocol error")

var ErrSecurity = errors.New("security error")

var ErrWrongType = errors.New("packet to parse is not of desired type")

ErrWrongType is returned when the type of the packet to parse is not expected.

Types

type Client

type Client interface {
	// String is the instance log identifier.
	String() string
	// Start starts the client. The engine must be running.
	Start() error
	// Stop stops the client.
	Stop() error
	// Engine gives the underlying API engine.
	Engine() Engine
	// Store gives the underlying data store.
	Store() Store

	// Produce generates and signs data, and inserts into the client's store.
	// The input data will be freed as the object is segmented.
	// Returns the final versioned name of the object.
	Produce(args ProduceArgs) (enc.Name, error)
	// Remove removes an object from the client's store by name.
	Remove(name enc.Name) error

	// Consume fetches an object with a given name.
	// By default, Consume will attemt to discover the latest version of the object.
	// To specify a particular version, use Name.WithVersion()
	Consume(name enc.Name, callback func(status ConsumeState))
	// ConsumeExt is a more advanced consume API that allows for
	// more control over the fetching process.
	ConsumeExt(args ConsumeExtArgs)

	// LatestLocal returns the latest version name of an object in the store.
	LatestLocal(name enc.Name) (enc.Name, error)
	// GetLocal returns the object data from the store.
	GetLocal(name enc.Name) (enc.Wire, error)

	// ExpressR sends a single interest with reliability.
	// Since this is a low-level API, the result is NOT validated.
	ExpressR(args ExpressRArgs)
	// IsCongested returns true if the client is congested.
	IsCongested() bool

	// Suggest suggests a signer for a given name.
	// nil is returned if no signer is found.
	SuggestSigner(name enc.Name) Signer
	// Validate validates a single data packet.
	Validate(data Data, sigCov enc.Wire, callback func(bool, error))
	// ValidateExt validates a single data packet (advanced API).
	ValidateExt(args ValidateExtArgs)
}

Client is the interface for the Object Client API

type ConsumeExtArgs

type ConsumeExtArgs struct {
	// Name is the name of the object to consume.
	Name enc.Name
	// Callback is called when data is available.
	// True should be returned to continue fetching the object.
	Callback func(status ConsumeState)
	// OnProgress is called when progress is made (advanced usage).
	// [Caution] Any data returned by Content() may not be validated.
	OnProgress func(status ConsumeState)
	// NoMetadata disables fetching RDR metadata (advanced usage).
	NoMetadata bool
}

ConsumeExtArgs are arguments for the ConsumeExt API.

type ConsumeState

type ConsumeState interface {
	// Name of the object being consumed including version.
	Name() enc.Name
	// Version of the object being consumed.
	Version() uint64

	// IsComplete returns true if the content has been completely fetched.
	IsComplete() bool
	// Progress counter
	Progress() int
	// ProgressMax is the max value for the progress counter (-1 for unknown).
	ProgressMax() int
	// Error that occurred during fetching.
	Error() error

	// Content is the currently available buffer in the content.
	// any subsequent calls to Content() will return data after the previous call.
	Content() enc.Wire

	// Cancel the consume operation.
	Cancel()
}

ConsumeState is the state of the consume operation

type ContentType

type ContentType uint64

ContentType represents the type of Data content in MetaInfo.

const (
	ContentTypeBlob               ContentType = 0
	ContentTypeLink               ContentType = 1
	ContentTypeKey                ContentType = 2
	ContentTypeNack               ContentType = 3
	ContentTypeManifest           ContentType = 4
	ContentTypePrefixAnnouncement ContentType = 5
	ContentTypeEncapsulatedData   ContentType = 6
	ContentTypeSigningKey         ContentType = 9
)

type Data

type Data interface {
	Name() enc.Name
	ContentType() optional.Optional[ContentType]
	Freshness() optional.Optional[time.Duration]
	FinalBlockID() optional.Optional[enc.Component]
	Content() enc.Wire
	Signature() Signature
}

Data is the abstract of a received Data packet.

type DataConfig

type DataConfig struct {
	// Standard Data parameters
	ContentType  optional.Optional[ContentType]
	Freshness    optional.Optional[time.Duration]
	FinalBlockID optional.Optional[enc.Component]

	// Certificate parameters
	SigNotBefore optional.Optional[time.Time]
	SigNotAfter  optional.Optional[time.Time]
}

DataConfig is used to create a Data.

type EncodedData

type EncodedData struct {
	// Encoded Data packet
	Wire enc.Wire
	// Signed part of the Data
	SigCovered enc.Wire
	// Parameter configuration of the Data
	Config *DataConfig
}

Container for an encoded Data packet

type EncodedInterest

type EncodedInterest struct {
	// Encoded Interest packet
	Wire enc.Wire
	// Signed part of the Interest
	SigCovered enc.Wire
	// Final name of the Interest
	FinalName enc.Name
	// Parameter configuration of the Interest
	Config *InterestConfig
}

Container for an encoded Interest packet

type Engine

type Engine interface {
	// EngineTrait is the type trait of the NDN engine.
	EngineTrait() Engine
	// Spec returns an NDN packet specification.
	Spec() Spec
	// Timer returns a Timer managed by the engine.
	Timer() Timer

	// Start processing packets.
	// If the engine is attached to a face, this will attempt
	// to open the face, and may block until the face is up.
	Start() error
	// Stops processing packets.
	Stop() error
	// Checks if the engine is running.
	IsRunning() bool

	// AttachHandler attaches an Interest handler to the namespace of prefix.
	AttachHandler(prefix enc.Name, handler InterestHandler) error
	// DetachHandler detaches an Interest handler from the namespace of prefix.
	DetachHandler(prefix enc.Name) error

	// Express expresses an Interest, with callback called when there is result.
	// To simplify the implementation, finalName needs to be the final Interest name given by MakeInterest.
	// The callback should create go routine or channel back to another routine to avoid blocking the main thread.
	Express(interest *EncodedInterest, callback ExpressCallbackFunc) error

	// ExecMgmtCmd executes a management command.
	//   args are the control arguments (*mgmt.ControlArgs)
	//   returns response and error if any (*mgmt.ControlResponse, error)
	ExecMgmtCmd(module string, cmd string, args any) (any, error)
	// SetCmdSec sets the interest signing parameters for management commands.
	SetCmdSec(signer Signer, validator func(enc.Name, enc.Wire, Signature) bool)
	// RegisterRoute registers a route of prefix to the local forwarder.
	RegisterRoute(prefix enc.Name) error
	// UnregisterRoute unregisters a route of prefix to the local forwarder.
	UnregisterRoute(prefix enc.Name) error
}

Engine represents a running NDN App low-level engine. Used by NTSchema.

type ErrInvalidValue

type ErrInvalidValue struct {
	Item  string
	Value any
}

func (ErrInvalidValue) Error

func (e ErrInvalidValue) Error() string

type ErrNotSupported

type ErrNotSupported struct {
	Item string
}

func (ErrNotSupported) Error

func (e ErrNotSupported) Error() string

type ExpressCallbackArgs

type ExpressCallbackArgs struct {
	// Result of the Interest expression.
	// If the result is not InterestResultData, Data fields are invalid.
	Result InterestResult
	// Data fetched.
	Data Data
	// Raw Data wire.
	RawData enc.Wire
	// Signature covered part of the Data.
	SigCovered enc.Wire
	// NACK reason code, if the result is InterestResultNack.
	NackReason uint64
	// Error, if the result is InterestResultError.
	Error error
}

ExpressCallbackArgs represents the arguments passed to the ExpressCallbackFunc.

type ExpressCallbackFunc

type ExpressCallbackFunc func(args ExpressCallbackArgs)

ExpressCallbackFunc represents the callback function for Interest expression.

type ExpressRArgs

type ExpressRArgs struct {
	// Name of the data to fetch.
	Name enc.Name
	// Interest configuration.
	Config *InterestConfig
	// AppParam for the interest.
	AppParam enc.Wire
	// Signer for signed interests.
	Signer Signer
	// Number of retries.
	Retries int
	// Callback for the result. This will be called on the engine's
	// main thread, so make sure it is either non-blocking and very fast,
	// or use a goroutine to handle the result.
	Callback ExpressCallbackFunc
}

ExpressRArgs are the arguments for the express retry API.

type Interest

type Interest interface {
	// Name of the Interest packet
	Name() enc.Name
	// Indicates whether a Data with a longer name can match
	CanBePrefix() bool
	// Indicates whether the Data must be fresh
	MustBeFresh() bool
	// ForwardingHint is the list of names to guide the Interest forwarding
	ForwardingHint() []enc.Name
	// Number to identify the Interest uniquely
	Nonce() optional.Optional[uint32]
	// Lifetime of the Interest
	Lifetime() optional.Optional[time.Duration]
	// Max number of hops the Interest can traverse
	HopLimit() *uint
	// Application parameters of the Interest (optional)
	AppParam() enc.Wire
	// Signature on the Interest (optional)
	Signature() Signature
}

Interest is the abstract of a received Interest packet

type InterestConfig

type InterestConfig struct {
	// Standard Interest parameters
	CanBePrefix    bool
	MustBeFresh    bool
	ForwardingHint []enc.Name
	Nonce          optional.Optional[uint32]
	Lifetime       optional.Optional[time.Duration]
	HopLimit       *byte

	// Signed Interest parameters.
	// The use of signed interests is strongly discouraged, and will
	// be gradually phased out, which is why these parameters are
	// not directly provided by the signer.
	SigNonce []byte
	SigTime  optional.Optional[time.Duration]
	SigSeqNo optional.Optional[uint64]

	// NDNLPv2 parameters
	NextHopId optional.Optional[uint64]
}

InterestConfig is used to create a Interest.

type InterestHandler

type InterestHandler func(args InterestHandlerArgs)

InterestHandler represents the callback function for an Interest handler. It should create a go routine to avoid blocking the main thread, if either 1) Data is not ready to send; or 2) Validation is required.

type InterestHandlerArgs

type InterestHandlerArgs struct {
	// Decoded interest packet
	Interest Interest
	// Function to reply to the Interest
	Reply WireReplyFunc
	// Raw Interest packet wire
	RawInterest enc.Wire
	// Signature covered part of the Interest
	SigCovered enc.Wire
	// Deadline of the Interest
	Deadline time.Time
	// PIT token
	PitToken []byte
	// Incoming face ID (if available)
	IncomingFaceId optional.Optional[uint64]
}

Extra information passed to the InterestHandler

type InterestResult

type InterestResult int

InterestResult represents the result of Interest expression. Can be Data fetched (succeeded), NetworkNack received, or Timeout. Note that AppNack is considered as Data.

const (
	// Empty result. Not used by the engine.
	// Used by high-level part if the setting to construct an Interest is incorrect.
	InterestResultNone InterestResult = iota
	// Data is fetched
	InterestResultData
	// NetworkNack is received
	InterestResultNack
	// Timeout
	InterestResultTimeout
	// Cancelled due to disconnection
	InterestCancelled
	// Failed of validation. Not used by the engine itself.
	InterestResultUnverified
	// Other error happens during handling the fetched data. Not used by the engine itself.
	InterestResultError
)

func (InterestResult) String

func (r InterestResult) String() string

type KeyChain

type KeyChain interface {
	// String provides the log identifier of the keychain.
	String() string
	// Store provides the public storage of the keychain.
	Store() Store
	// Identities returns all identities in the keychain.
	Identities() []KeyChainIdentity
	// IdentityByName returns the identity by full name.
	IdentityByName(enc.Name) KeyChainIdentity
	// InsertKey inserts a key to the keychain.
	InsertKey(Signer) error
	// InsertCert inserts a certificate to the keychain.
	InsertCert([]byte) error
}

KeyChain is the interface of a keychain. Note that Keychains are not thread-safe, and the owner should provide a lock.

type KeyChainIdentity

type KeyChainIdentity interface {
	// Name returns the full name of the identity.
	Name() enc.Name
	// Keys returns all keys of the identity.
	Keys() []KeyChainKey
}

KeyChainIdentity is the interface of a signing identity.

type KeyChainKey

type KeyChainKey interface {
	// KeyName returns the key name of the key.
	KeyName() enc.Name
	// Signer returns the signer of the key.
	Signer() Signer
	// UniqueCerts returns a list of unique cert names in the key.
	// The version number is always set to zero.
	UniqueCerts() []enc.Name
}

KeyChainKey is the interface of a key in the keychain.

type ProduceArgs

type ProduceArgs struct {
	// Name is the name of the object to produce.
	// The version of the object MUST be set using WithVersion.
	Name enc.Name
	// Content is the raw data wire.
	// Content can be larger than a single packet and will be segmented.
	Content enc.Wire
	// Time for which the object version can be cached (default 4s).
	FreshnessPeriod time.Duration
	// NoMetadata disables RDR metadata (advanced usage).
	NoMetadata bool
}

ProduceArgs are the arguments for the produce API.

type SigChecker

type SigChecker func(name enc.Name, sigCovered enc.Wire, sig Signature) bool

SigChecker is a basic function to check the signature of a packet. In NTSchema, policies&sub-trees are supposed to be used for validation; SigChecker is only designed for low-level engine. Create a go routine for time consuming jobs.

type SigType

type SigType int

SigType represents the type of signature.

const (
	SignatureNone            SigType = -1
	SignatureDigestSha256    SigType = 0
	SignatureSha256WithRsa   SigType = 1
	SignatureSha256WithEcdsa SigType = 3
	SignatureHmacWithSha256  SigType = 4
	SignatureEd25519         SigType = 5
	SignatureEmptyTest       SigType = 200
)

func (SigType) String

func (t SigType) String() string

type Signature

type Signature interface {
	// SigType returns the type of the signature.
	SigType() SigType
	// KeyName returns the key locator in the signature.
	// Note that this may not be the actual key name.
	KeyName() enc.Name
	// Validity returns the validity period of the signature.
	// This field is generally only present in NDN certificates.
	Validity() (notBefore, notAfter *time.Time)
	// SigValue returns the signature value.
	SigValue() []byte

	// SigNonce returns the nonce in the Interest signature.
	SigNonce() []byte
	// SigTime returns the time in the Interest signature.
	SigTime() *time.Time
	// SigSeqNum returns the sequence number in the Interest signature.
	SigSeqNum() *uint64
}

Signature is the abstract of the signature of a packet. Some of the fields are invalid for Data or Interest.

type Signer

type Signer interface {
	// SigInfo returns the configuration of the signature.
	Type() SigType
	// KeyName returns the key name of the signer.
	KeyName() enc.Name
	// KeyLocator returns the key locator name of the signer.
	KeyLocator() enc.Name
	// EstimateSize gives the approximate size of the signature in bytes.
	EstimateSize() uint
	// Sign computes the signature value of a wire.
	Sign(enc.Wire) ([]byte, error)
	// Public returns the public key of the signer or nil.
	Public() ([]byte, error)
}

Signer is the interface of a NDN packet signer.

type Spec

type Spec interface {
	// MakeData creates a Data packet, returns the encoded DataContainer
	MakeData(name enc.Name, config *DataConfig, content enc.Wire, signer Signer) (*EncodedData, error)
	// MakeData creates an Interest packet, returns an encoded InterestContainer
	MakeInterest(name enc.Name, config *InterestConfig, appParam enc.Wire, signer Signer) (*EncodedInterest, error)
	// ReadData reads and parses a Data from the reader, returns the Data, signature covered parts, and error.
	ReadData(reader enc.WireView) (Data, enc.Wire, error)
	// ReadData reads and parses an Interest from the reader, returns the Data, signature covered parts, and error.
	ReadInterest(reader enc.WireView) (Interest, enc.Wire, error)
}

Spec represents an NDN packet specification.

type Store

type Store interface {
	// returns a Data wire matching the given name
	// prefix = return the newest Data wire with the given prefix
	Get(name enc.Name, prefix bool) ([]byte, error)

	// inserts a Data wire into the store
	Put(name enc.Name, version uint64, wire []byte) error

	// removes a Data wire from the store
	// if prefix is set, all names with the given prefix are removed
	Remove(name enc.Name, prefix bool) error

	// begin a write transaction (for put only)
	// we support these primarily for performance rather than correctness
	// do not rely on atomicity of transactions as far as possible
	Begin() (Store, error)
	// commit a write transaction
	Commit() error
	// rollback a write transaction
	Rollback() error
}

type Timer

type Timer interface {
	// Now returns current time.
	Now() time.Time
	// Sleep sleeps for the duration.
	Sleep(time.Duration)
	// Schedule schedules the callback function to be called after the duration,
	// and returns a cancel callback to cancel the scheduled function.
	Schedule(time.Duration, func()) func() error
	// Nonce generates a random nonce.
	Nonce() []byte
}

type TrustSchema

type TrustSchema interface {
	// Check checks if a packet can be signed with the provided certificate.
	Check(pkt enc.Name, cert enc.Name) bool
	// Suggest suggests a signer for a packet.
	Suggest(enc.Name, KeyChain) Signer
}

TrustSchema is the interface for a trust schema.

type ValidateExtArgs

type ValidateExtArgs struct {
	// Data packet to validate.
	Data Data
	// Signature covered wire.
	SigCovered enc.Wire
	// Callback for the result.
	Callback func(bool, error)
	// Override data name during first validation.
	OverrideName enc.Name
	// Next Hop ID to use for fetching certificates.
	CertNextHop optional.Optional[uint64]
}

ValidateExtArgs are the arguments for the advanced validate API.

type WireReplyFunc

type WireReplyFunc func(wire enc.Wire) error

ReplyFunc represents the callback function to reply for an Interest.