ndn

package
v0.0.0-...-1e60831 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 23, 2024 License: NIST-PD-fallback Imports: 20 Imported by: 9

README

NDNgo: Named Data Networking in Go

NDNgo is a minimal Named Data Networking library compatible with the NDN-DPDK forwarder. The main purpose of this library is for implementing unit tests and management functionality of NDN-DPDK. It also serves as a demonstration on how to create a library compatible with NDN-DPDK.

NDNgo does not depend on Cgo, and can be used in external projects via Go Modules. It is intended to be cross-platform, and part of the library can be compiled for WebAssembly via TinyGo compiler. However, this is not a high performance library, and there is no API stability guarantees.

NDNgo logo

Features

Packet encoding and decoding

  • General purpose TLV codec (in package tlv)
  • Interest and Data: v0.3 format only
    • TLV evolvability: yes
    • Forwarding hint: yes
    • Signed Interest: basic support
  • NDNLPv2
    • Fragmentation and reassembly: partial
    • Nack: yes
    • PIT token: yes
    • Congestion mark: yes
    • Link layer reliability: no
  • Naming Convention: rev3 format (TLV-TYPE numbers)

Transports

KeyChain

  • Encryption: no
  • Signing algorithms
    • SHA256: yes
    • ECDSA: yes
    • RSA: yes
    • HMAC-SHA256: no
    • Ed25519: proof of concept only
    • Null: yes
  • NDN certificates: basic support
  • Persistent key and certificate storage: no
  • Trust schema: no

Application layer services

Management integration:

Getting Started

The best places to get started are:

  • Consume function in package endpoint: express an Interest and wait for response, with automatic retransmissions and Data verification.
  • Produce function in package endpoint: start a producer, with automatic Data signing.
  • l3.Face type in package l3: network layer face abstraction, for low-level programming.

Examples are in command ndndpdk-godemo.

Documentation

Overview

Package ndn implements Named Data Networking (NDN) packet semantics. This is the top-level package of NDNgo, a minimal NDN library in pure Go.

This package contains the following important types: 

Packet representation:
- Interest
- Data
- Nack
- Packet

Security abstraction:
- Signer
- Verifier

Index

Constants

View Source 
const (
	DefaultInterestLifetime time.Duration = 4000 * time.Millisecond
	MinInterestLifetime     time.Duration = 1 * time.Millisecond

	MinHopLimit = 1
	MaxHopLimit = math.MaxUint8
)

Defaults and limits.

View Source 
const (
	// CanBePrefixFlag enables CanBePrefix in MakeInterest.
	CanBePrefixFlag = tCanBePrefix(true)

	// MustBeFreshFlag enables MustBeFresh in MakeInterest.
	MustBeFreshFlag = tMustBeFresh(true)
)
View Source 
const (
	CanSatisfyInCache = 1 << iota
)
View Source 
const FinalBlockFlag = tFinalBlockFlag(true)

FinalBlockFlag enables MakeData to set FinalBlock to the last name component.

Variables

View Source 
var (
	ErrFragment      = errors.New("bad fragment")
	ErrL3Type        = errors.New("unknown L3 packet type")
	ErrComponentType = errors.New("NameComponent TLV-TYPE out of range")
	ErrNonceLen      = errors.New("Nonce wrong length")
	ErrLifetime      = errors.New("InterestLifetime out of range")
	ErrHopLimit      = errors.New("HopLimit out of range")
	ErrParamsDigest  = errors.New("bad ParamsDigest")
	ErrContentType   = errors.New("bad ContentType")
	ErrSigType       = errors.New("bad SigType")
	ErrKeyLocator    = errors.New("bad KeyLocator")
	ErrSigNonce      = errors.New("bad SigNonce")
	ErrSigValue      = errors.New("bad SigValue")
)

Error conditions.

Functions

func RegisterSigInfoExtension 

func RegisterSigInfoExtension(typ uint32)

RegisterSigInfoExtension registers an extension TLV-TYPE in SigInfo.

Types

type CanSatisfyFlag 

type CanSatisfyFlag int

Data.CanSatisfy flags.

type ContentType 

type ContentType uint64

ContentType represents a ContentType field.

func (ContentType) Field 

func (ct ContentType) Field() tlv.Field

func (*ContentType) UnmarshalBinary 

func (ct *ContentType) UnmarshalBinary(wire []byte) error

UnmarshalBinary decodes from wire encoding.

type Data 

type Data struct {
	Name        Name
	ContentType ContentType
	Freshness   time.Duration
	FinalBlock  NameComponent
	Content     []byte
	SigInfo     *SigInfo
	SigValue    []byte
	// contains filtered or unexported fields
}

Data represents a Data packet.

func MakeData 

func MakeData(args ...any) (data Data)

MakeData creates a Data from flexible arguments. Arguments can contain:

  • string or Name: set Name
  • ContentType
  • time.Duration: set Freshness
  • FinalBlock: set FinalBlock
  • FinalBlockFlag: set FinalBlock to the last name component, ignored if name is empty
  • []byte: set Content
  • LpL3: copy PitToken and CongMark
  • Interest or *Interest: copy Name, set FreshnessPeriod if Interest has MustBeFresh, inherit LpL3

func (Data) CanSatisfy 

func (data Data) CanSatisfy(interest Interest, optionalFlag ...CanSatisfyFlag) bool

CanSatisfy determines whether this Data can satisfy the given Interest.

func (Data) ComputeDigest 

func (data Data) ComputeDigest() []byte

ComputeDigest computes implicit digest of this Data.

If data was decoded from Packet (data.packet is assigned), the digest is of the origin packet. Computed digest is cached on data.packet. Modifying a decoded Data will cause this function to return incorrect digest.

If data was constructed (data.packet is unassigned), the digest is of the encoding of the current packet, and is not cached.

func (Data) Field 

func (data Data) Field() tlv.Field

Field implements tlv.Fielder interface.

func (Data) FullName 

func (data Data) FullName() Name

FullName returns full name of this Data.

func (Data) IsFinalBlock 

func (data Data) IsFinalBlock() bool

IsFinalBlock determines whether FinalBlock field equals the last name component.

func (*Data) SignWith 

func (data *Data) SignWith(signer func(name Name, si *SigInfo) (LLSign, error)) error

SignWith implements Signable interface. Caller should use signer.Sign(data).

func (Data) String 

func (data Data) String() string

func (Data) ToPacket 

func (data Data) ToPacket() (packet *Packet)

ToPacket wraps Data as Packet.

func (*Data) UnmarshalBinary 

func (data *Data) UnmarshalBinary(value []byte) (e error)

UnmarshalBinary decodes from TLV-VALUE.

func (Data) VerifyWith 

func (data Data) VerifyWith(verifier func(name Name, si SigInfo) (LLVerify, error)) error

VerifyWith implements Verifiable interface. Caller should use verifier.Verify(data).

If data was decoded from Packet (data.packet is assigned), verification is on the origin packet. Modifying a decoded Data will cause this function to return incorrect result.

If data was constructed (data.packet is unassigned), verification is on the encoding of the current packet.

type FinalBlock 

type FinalBlock NameComponent

FinalBlock is passed to MakeData to set FinalBlock field.

type ForwardingHint 

type ForwardingHint []Name

ForwardingHint represents a forwarding hint.

func (ForwardingHint) Field 

func (fh ForwardingHint) Field() tlv.Field

Field implements tlv.Fielder interface.

func (*ForwardingHint) UnmarshalBinary 

func (fh *ForwardingHint) UnmarshalBinary(wire []byte) error

UnmarshalBinary decodes from TLV-VALUE.

type HopLimit 

type HopLimit uint8

HopLimit represents a HopLimit field.

func (HopLimit) Field 

func (hl HopLimit) Field() tlv.Field

Field implements tlv.Fielder interface.

func (*HopLimit) UnmarshalBinary 

func (hl *HopLimit) UnmarshalBinary(wire []byte) error

UnmarshalBinary decodes from wire encoding.

type Interest 

type Interest struct {
	Name           Name
	CanBePrefix    bool
	MustBeFresh    bool
	ForwardingHint ForwardingHint
	Nonce          Nonce
	Lifetime       time.Duration
	HopLimit       HopLimit
	AppParameters  []byte
	SigInfo        *SigInfo
	SigValue       []byte
	// contains filtered or unexported fields
}

Interest represents an Interest packet.

func MakeInterest 

func MakeInterest(args ...any) (interest Interest)

MakeInterest creates an Interest from flexible arguments. Arguments can contain:

  • string or Name: set Name
  • CanBePrefixFlag: set CanBePrefix
  • MustBeFreshFlag: set MustBeFresh
  • ForwardingHint: set forwarding hint
  • Nonce: set Nonce
  • time.Duration: set Lifetime
  • HopLimit: set HopLimit
  • []byte: set AppParameters
  • LpL3: copy PitToken and CongMark

func (*Interest) ApplyDefaultLifetime 

func (interest *Interest) ApplyDefaultLifetime() time.Duration

ApplyDefaultLifetime updates Lifetime to the default if it is not set.

func (Interest) Field 

func (interest Interest) Field() tlv.Field

Field implements tlv.Fielder interface.

func (*Interest) SignWith 

func (interest *Interest) SignWith(signer func(name Name, si *SigInfo) (LLSign, error)) error

SignWith implements Signable interface. Caller should use signer.Sign(interest).

func (Interest) String 

func (interest Interest) String() string

func (Interest) ToPacket 

func (interest Interest) ToPacket() (packet *Packet)

ToPacket wraps Interest as Packet.

func (*Interest) UnmarshalBinary 

func (interest *Interest) UnmarshalBinary(wire []byte) (e error)

UnmarshalBinary decodes from TLV-VALUE.

func (*Interest) UpdateParamsDigest 

func (interest *Interest) UpdateParamsDigest()

UpdateParamsDigest appends or updates ParametersSha256DigestComponent. It will not remove erroneously present or duplicate ParametersSha256DigestComponent.

func (Interest) VerifyWith 

func (interest Interest) VerifyWith(verifier func(name Name, si SigInfo) (LLVerify, error)) error

VerifyWith implements Verifiable interface. Caller should use verifier.Verify(interest).

This function cannot verify an Interest that contains unrecognized TLV elements.

type KeyLocator 

type KeyLocator struct {
	Name   Name
	Digest []byte
}

KeyLocator represents KeyLocator in SignatureInfo.

func (KeyLocator) Empty 

func (kl KeyLocator) Empty() bool

Empty returns true if KeyLocator has zero fields.

func (KeyLocator) Field 

func (kl KeyLocator) Field() tlv.Field

Field implements tlv.Fielder interface.

func (KeyLocator) String 

func (kl KeyLocator) String() string

func (*KeyLocator) UnmarshalBinary 

func (kl *KeyLocator) UnmarshalBinary(wire []byte) error

UnmarshalBinary decodes from TLV-VALUE.

type L3Packet 

type L3Packet interface {
	ToPacket() *Packet
}

L3Packet represents any NDN layer 3 packet.

type LLSign 

type LLSign func(input []byte) (sig []byte, e error)

LLSign is a low-level signing function.

type LLVerify 

type LLVerify func(input, sig []byte) error

LLVerify is a low-level verification function.

type LpFragment 

type LpFragment struct {
	SeqNum    uint64
	FragIndex int
	FragCount int
	Header    []byte // encoded NDNLPv2 L3 header fields
	Payload   []byte // LpPayload TLV-VALUE
}

LpFragment represents an NDNLPv2 fragmented frame.

func (LpFragment) Field 

func (frag LpFragment) Field() tlv.Field

Field implements tlv.Fielder interface.

func (LpFragment) String 

func (frag LpFragment) String() string

type LpFragmenter 

type LpFragmenter struct {
	// contains filtered or unexported fields
}

LpFragmenter splits Packet into fragments.

func NewLpFragmenter 

func NewLpFragmenter(mtu int) *LpFragmenter

NewLpFragmenter creates a LpFragmenter.

func (*LpFragmenter) Fragment 

func (fragmenter *LpFragmenter) Fragment(full *Packet) (frags []*Packet, e error)

Fragment fragments a packet.

type LpL3 

type LpL3 struct {
	PitToken   []byte
	NackReason uint8
	CongMark   uint8
}

LpL3 contains layer 3 fields in NDNLPv2 header.

func (LpL3) Empty 

func (lph LpL3) Empty() bool

Empty returns true if LpL3 has zero fields.

type LpReassembler 

type LpReassembler struct {
	// contains filtered or unexported fields
}

LpReassembler reassembles fragments.

func NewLpReassembler 

func NewLpReassembler(capacity int) *LpReassembler

NewLpReassembler creates a LpReassembler.

func (*LpReassembler) Accept 

func (reass *LpReassembler) Accept(pkt *Packet) (full *Packet, e error)

Accept processes a fragment. pkt.Fragment must not be nil.

type Nack 

type Nack struct {
	Reason   uint8
	Interest Interest
	// contains filtered or unexported fields
}

Nack represents a Nack packet.

Nack struct does not support encoding or decoding. Instead, you can encode nack.ToPacket(), or decode as Packet then access the Nack.

func MakeNack 

func MakeNack(args ...any) (nack Nack)

MakeNack creates a Nack from flexible arguments. Arguments can contain:

  • uint8 or int: set Reason
  • Interest or *Interest: set Interest, copy PitToken and CongMark
  • LpL3: copy PitToken and CongMark

func (Nack) Name 

func (nack Nack) Name() Name

Name returns the name of the enclosed Interest.

func (Nack) String 

func (nack Nack) String() string

func (Nack) ToPacket 

func (nack Nack) ToPacket() (packet *Packet)

ToPacket wraps Nack as Packet.

type Name 

type Name []NameComponent

Name represents a name. The zero Name has zero components.

func ParseName 

func ParseName(input string) (name Name)

ParseName parses canonical URI representation of name. It uses best effort and can accept any input.

func (Name) Append 

func (name Name) Append(comps ...NameComponent) (ret Name)

Append appends zero or more components to a copy of this name.

func (Name) Compare 

func (name Name) Compare(other Name) int

Compare returns negative when name<other, zero when name==other, positive when name>other.

func (Name) Equal 

func (name Name) Equal(other Name) bool

Equal determines whether two names are the same.

func (Name) Field 

func (name Name) Field() tlv.Field

Field implements tlv.Fielder interface.

func (Name) Get 

func (name Name) Get(i int) NameComponent

Get returns i-th component. If negative, count from the end. If out-of-range, return invalid NameComponent.

func (Name) GetPrefix 

func (name Name) GetPrefix(i int) Name

GetPrefix returns a prefix of i components. If negative, count from the end.

func (Name) IsPrefixOf 

func (name Name) IsPrefixOf(other Name) bool

IsPrefixOf returns true if this name is a prefix of other name.

func (Name) Length 

func (name Name) Length() int

Length returns TLV-LENGTH. Use len(name) to get number of components.

func (Name) MarshalBinary 

func (name Name) MarshalBinary() (value []byte, e error)

MarshalBinary encodes to TLV-VALUE.

func (Name) MarshalText 

func (name Name) MarshalText() (text []byte, e error)

MarshalText implements encoding.TextMarshaler interface.

func (Name) Slice 

func (name Name) Slice(i int, j ...int) Name

Slice returns a sub name between i-th (inclusive) and j-th (exclusive) components. j is optional; the default is toward the end. If negative, count from the end. If out-of-range, return empty name.

func (Name) String 

func (name Name) String() string

String returns URI representation of this name.

func (*Name) UnmarshalBinary 

func (name *Name) UnmarshalBinary(wire []byte) error

UnmarshalBinary decodes TLV-VALUE from wire format.

func (*Name) UnmarshalText 

func (name *Name) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler interface.

type NameComponent 

type NameComponent struct {
	tlv.Element
}

NameComponent represents a name component. Zero value is invalid.

func DecodeFinalBlock 

func DecodeFinalBlock(de tlv.DecodingElement) (finalBlock NameComponent, e error)

DecodeFinalBlock decodes FinalBlock name component from FinalBlock TLV element.

func MakeNameComponent 

func MakeNameComponent(typ uint32, value []byte) (comp NameComponent)

MakeNameComponent constructs a NameComponent from TLV-TYPE and TLV-VALUE.

func NameComponentFrom 

func NameComponentFrom(typ uint32, value tlv.Fielder) NameComponent

NameComponentFrom constructs a NameComponent from TLV-TYPE and tlv.Fielder as TLV-VALUE. If value encodes to an error, returns an invalid NameComponent.

To create a name component with NonNegativeInteger as commonly used in naming conventions: 

NameComponentFrom(an.VersionNameComponent, tlv.NNI(1))

func ParseNameComponent 

func ParseNameComponent(input string) (comp NameComponent)

ParseNameComponent parses canonical URI representation of name component. It uses best effort and can accept any input.

func (NameComponent) Compare 

func (comp NameComponent) Compare(other NameComponent) int

Compare returns negative when comp<other, zero when comp==other, positive when comp>other.

func (NameComponent) Equal 

func (comp NameComponent) Equal(other NameComponent) bool

Equal determines whether two components are the same.

func (NameComponent) Field 

func (comp NameComponent) Field() tlv.Field

Field implements tlv.Fielder interface.

func (NameComponent) String 

func (comp NameComponent) String() string

String returns URI representation of this component.

func (*NameComponent) UnmarshalTLV 

func (comp *NameComponent) UnmarshalTLV(typ uint32, value []byte) error

UnmarshalTLV decodes from wire format.

func (NameComponent) Valid 

func (comp NameComponent) Valid() bool

Valid checks whether this component has a valid TLV-TYPE.

type Nonce 

type Nonce [4]byte

Nonce represents an Interest Nonce.

func NewNonce 

func NewNonce() (nonce Nonce)

NewNonce generates a random Nonce.

func NonceFromUint 

func NonceFromUint(n uint32) (nonce Nonce)

NonceFromUint converts uint32 to Nonce, interpreted as big endian.

func (Nonce) Field 

func (nonce Nonce) Field() tlv.Field

Field implements tlv.Fielder interface.

func (Nonce) IsZero 

func (nonce Nonce) IsZero() bool

IsZero returns true if the nonce is zero.

func (Nonce) ToUint 

func (nonce Nonce) ToUint() uint32

ToUint converts Nonce to uint32, interpreted as big endian.

func (*Nonce) UnmarshalBinary 

func (nonce *Nonce) UnmarshalBinary(wire []byte) error

UnmarshalBinary decodes from wire encoding.

type Packet 

type Packet struct {
	Lp LpL3

	Fragment *LpFragment
	Interest *Interest
	Data     *Data
	Nack     *Nack
	// contains filtered or unexported fields
}

Packet represents an NDN layer 3 packet with associated LpL3.

func (*Packet) Field 

func (pkt *Packet) Field() tlv.Field

Field implements tlv.Fielder interface.

func (*Packet) String 

func (pkt *Packet) String() string

func (*Packet) ToPacket 

func (pkt *Packet) ToPacket() *Packet

ToPacket returns self.

func (*Packet) UnmarshalTLV 

func (pkt *Packet) UnmarshalTLV(typ uint32, value []byte) (e error)

UnmarshalTLV decodes from wire format.

type SigInfo 

type SigInfo struct {
	Type       uint32
	KeyLocator KeyLocator
	Nonce      []byte
	Time       uint64
	SeqNum     uint64
	Extensions []tlv.Element
}

SigInfo represents SignatureInfo on Interest or Data.

func (*SigInfo) EncodeAs 

func (si *SigInfo) EncodeAs(typ uint32) tlv.Fielder

EncodeAs creates a tlv.Fielder for either ISigInfo or DSigInfo TLV-TYPE. If si is nil, the encoding result contains SigType=SigNull.

func (*SigInfo) FindExtension 

func (si *SigInfo) FindExtension(typ uint32) *tlv.Element

FindExtension retrieves extension field by TLV-TYPE number.

func (SigInfo) String 

func (si SigInfo) String() string

func (*SigInfo) UnmarshalBinary 

func (si *SigInfo) UnmarshalBinary(wire []byte) (e error)

UnmarshalBinary decodes from TLV-VALUE.

type Signable 

type Signable interface {
	SignWith(signer func(name Name, si *SigInfo) (LLSign, error)) error
}

Signable is a packet that can be signed.

type SignableVerifiable 

type SignableVerifiable interface {
	Signable
	Verifiable
}

SignableVerifiable is both Signable and Verifiable.

type Signer 

type Signer interface {
	Sign(packet Signable) error
}

Signer is high-level signer, such as a private key. 

var NullSigner Signer = nullSigner{}

NullSigner implements Signer for SigNull signature type.

type SignerVerifier 

type SignerVerifier interface {
	Signer
	Verifier
}

SignerVerifier is both Signer and Verifier. 

var DigestSigning SignerVerifier = digestSigning{}

DigestSigning implements Signer and Verifier for SigSha256 signature type.

type Verifiable 

type Verifiable interface {
	VerifyWith(verifier func(name Name, si SigInfo) (LLVerify, error)) error
}

Verifiable is a packet that can be verified.

type Verifier 

type Verifier interface {
	Verify(packet Verifiable) error
}

Verifier is high-level verifier, such as a public key. 

var NopVerifier Verifier = nopVerifier{}

NopVerifier is a Verifier that performs no verification.

Source Files

View all Source files

Directories

Path Synopsis
Package an exports Assigned Numbers in NDN.
 Package an exports Assigned Numbers in NDN.
Package endpoint implements basic consumer and producer functionality.
 Package endpoint implements basic consumer and producer functionality.
Package fch provides a simple NDN-FCH client.
 Package fch provides a simple NDN-FCH client.
Package keychain implements signing and verification on NDN packets.
 Package keychain implements signing and verification on NDN packets.
Package l3 defines a network layer face abstraction.
 Package l3 defines a network layer face abstraction.
Package memiftransport implements a transport over a shared memory packet interface (memif).
 Package memiftransport implements a transport over a shared memory packet interface (memif).
Package mgmt defines interface of forwarder management features.
 Package mgmt defines interface of forwarder management features.
gqlmgmt
Package gqlmgmt provides access to NDN-DPDK GraphQL API.
 Package gqlmgmt provides access to NDN-DPDK GraphQL API.
nfdmgmt
Package nfdmgmt provides access to NFD Management API.
 Package nfdmgmt provides access to NFD Management API.
Package ndnlayer provides a GoPacket layer for NDN.
 Package ndnlayer provides a GoPacket layer for NDN.
Package ndntestenv contains helper functions to validate NDN packets in test code.
 Package ndntestenv contains helper functions to validate NDN packets in test code.
tiny
Command tiny verifies that part of NDNgo library is compatible with TinyGo compiler.
 Command tiny verifies that part of NDNgo library is compatible with TinyGo compiler.
Package ndntestvector contains test vectors of NDN packets.
 Package ndntestvector contains test vectors of NDN packets.
Package packettransport implements a transport based on GoPacket library.
 Package packettransport implements a transport based on GoPacket library.
afpacket
Package afpacket implements a transport that communicates over AF_PACKET sockets.
 Package afpacket implements a transport that communicates over AF_PACKET sockets.
rdr
Package rdr implements Realtime Data Retrieval (RDR) protocol.
 Package rdr implements Realtime Data Retrieval (RDR) protocol.
ndn6file
Package ndn6file implements ndn6-file-server protocol.
 Package ndn6file implements ndn6-file-server protocol.
Package segmented publishes and retrieves segmented objects.
 Package segmented publishes and retrieves segmented objects.
Package sockettransport implements a transport based on stream or datagram sockets.
 Package sockettransport implements a transport based on stream or datagram sockets.
Package tlv implements NDN Type-Length-Value (TLV) encoding.
 Package tlv implements NDN Type-Length-Value (TLV) encoding.
Package wasmtransport implements l3.Transport for WebAssembly.
 Package wasmtransport implements l3.Transport for WebAssembly.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.