README

NDNgo: Named Data Networking in Go

NDNgo is a minimal Named Data Networking library compatible with the NDN-DPDK forwarder. This library does not depend on Cgo, and can be used in external projects via Go Modules. However, NDNgo has no API stability guarantees: breaking changes may happen at any time.

NDNgo logo

Features

Packet encoding and decoding

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

Transports

KeyChain

Application layer services

  • Endpoint: yes
  • Segmented object producer and consumer: no

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.

Expand ▾ Collapse ▴

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

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

	MinHopLimit = 1
	MaxHopLimit = math.MaxUint8
)

Defaults and limits.


const (
	// CanBePrefixFlag enables CanBePrefix in NewInterest.
	CanBePrefixFlag = tCanBePrefix(true)

	// MustBeFreshFlag enables MustBeFresh in NewInterest.
	MustBeFreshFlag = tMustBeFresh(true)
)

Variables

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")
	ErrSigType       = errors.New("bad SigType")
	ErrKeyLocator    = errors.New("bad KeyLocator")
	ErrSigNonce      = errors.New("bad SigNonce")
	ErrSigValue      = errors.New("bad SigValue")
)

Simple error conditions.


Functions

func PitTokenFromUint

func PitTokenFromUint(n uint64) []byte

PitTokenFromUint creates a PIT token from uint64, interpreted as big endian.

func PitTokenToUint

func PitTokenToUint(token []byte) uint64

PitTokenToUint reads a 8-octet PIT token as uint64, interpreted as big endian. Returns 0 if the input token is not 8 octets.

func RegisterSigInfoExtension

func RegisterSigInfoExtension(typ uint32)

RegisterSigInfoExtension registers an extension TLV-TYPE in SigInfo.

Types

type ContentType

type ContentType uint

ContentType represents a ContentType field.

func (ContentType) MarshalTlv

func (ct ContentType) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this ContentType.

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
	Content     []byte
	SigInfo     *SigInfo
	SigValue    []byte
	// contains filtered or unexported fields
}

Data represents a Data packet.

func MakeData

func MakeData(args ...interface{}) (data Data)

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

- string or Name: set Name
- ContentType
- time.Duration: set Freshness
- []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) 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) FullName

func (data Data) FullName() Name

FullName returns full name of this Data.

func (Data) MarshalTlv

func (data Data) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this Data.

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

ToPacket wraps Data as Packet.

func (*Data) UnmarshalBinary

func (data *Data) UnmarshalBinary(wire []byte) 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 FHDelegation

type FHDelegation struct {
	Preference int
	Name       Name
}

FHDelegation represents a delegation of forwarding hint.

func MakeFHDelegation

func MakeFHDelegation(preference int, name interface{}) (del FHDelegation)

MakeFHDelegation creates a delegation. name should be either Name or string.

func (FHDelegation) MarshalTlv

func (del FHDelegation) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this delegation.

func (*FHDelegation) UnmarshalBinary

func (del *FHDelegation) UnmarshalBinary(wire []byte) error

UnmarshalBinary decodes from TLV-VALUE.

type ForwardingHint

type ForwardingHint []FHDelegation

ForwardingHint represents a forwarding hint.

func (*ForwardingHint) Append

func (fh *ForwardingHint) Append(preference int, name interface{})

Append adds a delegation. name should be either Name or string.

func (ForwardingHint) MarshalTlv

func (fh ForwardingHint) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this forwarding hint.

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) MarshalTlv

func (hl HopLimit) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this HopLimit.

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 ...interface{}) (interest Interest)

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

- string or Name: set Name
- CanBePrefixFlag: set CanBePrefix
- MustBeFreshFlag: set MustBeFresh
- FHDelegation: append forwarding hint delegation
- 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) MarshalTlv

func (interest Interest) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this Interest.

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

ToPacket wraps Interest as Packet.

func (*Interest) UnmarshalBinary

func (interest *Interest) UnmarshalBinary(wire []byte) 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) MarshalTlv

func (kl KeyLocator) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this KeyLocator.

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
	// contains filtered or unexported fields
}

LpFragment represents an NDNLPv2 fragmented frame.

func (LpFragment) MarshalTlv

func (frag LpFragment) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this fragment.

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   int
}

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 Nack

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

Nack represents a Nack packet.

func MakeNack

func MakeNack(args ...interface{}) (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

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 URI representation of name. It uses best effort and can accept any input.

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) 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 TLV-VALUE of this name.

func (Name) MarshalText

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

MarshalText implements encoding.TextMarshaler interface.

func (Name) MarshalTlv

func (name Name) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this name.

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. The zero NameComponent is invalid.

func MakeNameComponent

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

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

func ParseNameComponent

func ParseNameComponent(input string) (comp NameComponent)

ParseNameComponent parses 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) MarshalTlv

func (comp NameComponent) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this component.

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) IsZero

func (nonce Nonce) IsZero() bool

IsZero returns true if the nonce is zero.

func (Nonce) MarshalTlv

func (nonce Nonce) MarshalTlv() (typ uint32, value []byte, e error)

MarshalTlv encodes this Nonce.

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) MarshalTlv

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

MarshalTlv encodes this packet.

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

EncodeAs creates an encodable object for either ISigInfo or DSigInfo TLV-TYPE. If si is nil, the encoding result contains SigType=SigNull.

func (SigInfo) String

func (si SigInfo) String() string

func (*SigInfo) UnmarshalBinary

func (si *SigInfo) UnmarshalBinary(wire []byte) 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.

Directories

Path Synopsis
an Package an contains Assigned Numbers in Named Data Networking (NDN).
endpoint Package endpoint implements basic consumer and producer functionality.
keychain Package keychain implements signing and verification on NDN packets.
keychain/eckey Package eckey implements SigSha256WithEcdsa signature type.
keychain/rsakey Package rsakey implements SigSha256WithRsa signature type.
l3 Package l3 defines a network layer face abstraction.
memiftransport Package memiftransport implements a transport over a shared memory packet interface (memif).
mgmt Package mgmt defines interface of forwarder management features.
mgmt/gqlmgmt Package gqlmgmt provides access to NDN-DPDK GraphQL API.
ndntestenv
ndntestvector
packettransport Package packettransport implements a transport based on gopacket library.
packettransport/afpacket Package afpacket implements a transport that communicates over AF_PACKET sockets.
sockettransport Package sockettransport implements a transport based on stream or datagram sockets.
tlv Package tlv implements Type-Length-Value (TLV) encoding in Named Data Networking (NDN).