path

Documentation

Index

• Constants
• func ExpTimeFromDuration(d time.Duration) (uint8, error)
• func ExpTimeToDuration(expTime uint8) time.Duration
• func FullMAC(h hash.Hash, info InfoField, hf HopField, buffer []byte) []byte
• func MAC(h hash.Hash, info InfoField, hf HopField, buffer []byte) [MacLen]byte
• func MACInput(segID uint16, timestamp uint32, expTime uint8, consIngress, consEgress uint16, ...)
• func RegisterPath(pathMeta Metadata)
• func StrictDecoding(strict bool)
• type HopField
  • func (h *HopField) DecodeFromBytes(raw []byte) (err error)
  • func (h *HopField) SerializeTo(b []byte) (err error)
• type InfoField
  • func (inf *InfoField) DecodeFromBytes(raw []byte) (err error)
  • func (inf *InfoField) SerializeTo(b []byte) (err error)
  • func (inf InfoField) String() string
  • func (inf *InfoField) UpdateSegID(hfMac [MacLen]byte)
• type Metadata
• type Path
  • func NewPath(pathType Type) (Path, error)
  • func NewRawPath() Path
• type Type
  • func (t Type) String() string

Constants

const (
	// HopLen is the size of a HopField in bytes.
	HopLen = 12
	// MacLen is the size of the MAC of each HopField.
	MacLen = 6
)

const InfoLen = 8

InfoLen is the size of an InfoField in bytes.

const MACBufferSize = 16

const MaxTTL = 24 * time.Hour

MaxTTL is the maximum age of a HopField.

Functions

func ExpTimeFromDuration

func ExpTimeFromDuration(d time.Duration) (uint8, error)

ExpTimeFromDuration calculates the largest relative expiration time that represents a duration <= the provided duration, that is: d <= ExpTimeToDuration(ExpTimeFromDuration(d)). The returned value is the ExpTime that can be used in a HopField. For durations that are out of range, an error is returned.

func ExpTimeToDuration

func ExpTimeToDuration(expTime uint8) time.Duration

ExpTimeToDuration calculates the relative expiration time in seconds. Note that for a 0 value ExpTime, the minimal duration is expTimeUnit. ExpTimeToDuration is pure: it does not modify any memory locations and does not produce any side effects. @ pure Calls to ExpTimeToDuration are guaranteed to always terminate. @ decreases

func FullMAC

func FullMAC(h hash.Hash, info InfoField, hf HopField, buffer []byte) []byte

FullMAC calculates the HopField MAC according to https://docs.scion.org/en/latest/protocols/scion-header.html#hop-field-mac-computation this method does not modify info or hf. Modifying the provided buffer after calling this function may change the returned HopField MAC. In contrast to MAC(), FullMAC returns all the 16 bytes instead of only 6 bytes of the MAC.

func MAC

func MAC(h hash.Hash, info InfoField, hf HopField, buffer []byte) [MacLen]byte

MAC calculates the HopField MAC according to https://docs.scion.org/en/latest/protocols/scion-header.html#hop-field-mac-computation this method does not modify info or hf. Modifying the provided buffer after calling this function may change the returned HopField MAC.

func MACInput

func MACInput(segID uint16, timestamp uint32, expTime uint8,
	consIngress, consEgress uint16, buffer []byte)

MACInput returns the MAC input data block with the following layout:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               0               |             SegID             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           Timestamp                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|       0       |    ExpTime    |          ConsIngress          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          ConsEgress           |               0               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func RegisterPath

func RegisterPath(pathMeta Metadata)

RegisterPath registers a new SCION path type globally. The PathType passed in must be unique, or a runtime panic will occur.

func StrictDecoding

func StrictDecoding(strict bool)

StrictDecoding enables or disables strict path decoding. If enabled, unknown path types fail to decode. If disabled, unknown path types are decoded into a raw path that keeps the encoded path around for re-serialization.

Strict parsing is enabled by default.

Experimental: This function is experimental and might be subject to change.

Types

type HopField

type HopField struct {
	// IngressRouterAlert flag. If the IngressRouterAlert is set, the ingress router (in
	// construction direction) will process the L4 payload in the packet.
	IngressRouterAlert bool
	// EgressRouterAlert flag. If the EgressRouterAlert is set, the egress router (in
	// construction direction) will process the L4 payload in the packet.
	EgressRouterAlert bool
	// Exptime is the expiry time of a HopField. The field is 1-byte long, thus there are 256
	// different values available to express an expiration time. The expiration time expressed by
	// the value of this field is relative, and an absolute expiration time in seconds is computed
	// in combination with the timestamp field (from the corresponding info field) as follows
	//
	// Timestamp + (1 + ExpTime) * (24*60*60)/256
	ExpTime uint8
	// ConsIngress is the ingress interface ID in construction direction.
	ConsIngress uint16
	// ConsEgress is the egress interface ID in construction direction.
	ConsEgress uint16
	// Mac is the 6-byte Message Authentication Code to authenticate the HopField.
	Mac [MacLen]byte
}

HopField is the HopField used in the SCION and OneHop path types.

The Hop Field has the following format:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|r r r r r r I E|    ExpTime    |           ConsIngress         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|        ConsEgress             |                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               +
|                              MAC                              |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func (*HopField) DecodeFromBytes

func (h *HopField) DecodeFromBytes(raw []byte) (err error)

DecodeFromBytes populates the fields from a raw buffer. The buffer must be of length >= path.HopLen. @ requires len(raw) >= HopLen DecodeFromBytes modifies the fields of *h and reads (but does not modify) the contents of raw. @ preserves acc(h) && acc(raw, 1/2) When a call that satisfies the precondition (len(raw) >= HopLen) is made, the return value is guaranteed to be nil. @ ensures err == nil Calls to DecodeFromBytes are always guaranteed to terminate. @ decreases

func (*HopField) SerializeTo

func (h *HopField) SerializeTo(b []byte) (err error)

SerializeTo writes the fields into the provided buffer. The buffer must be of length >= path.HopLen. @ requires len(b) >= HopLen SerializeTo reads (but does not modify) the fields of *h and writes to the contents of b. @ preserves acc(h, 1/2) && acc(b) When a call that satisfies the precondition (len(b) >= HopLen) is made, the return value is guaranteed to be nil. @ ensures err == nil Calls to SerializeTo are guaranteed to terminate. @ decreases

type InfoField

type InfoField struct {
	// Peer is the peering flag. If set to true, then the forwarding path is built as a peering
	// path, which requires special processing on the dataplane.
	Peer bool
	// ConsDir is the construction direction flag. If set to true then the hop fields are arranged
	// in the direction they have been constructed during beaconing.
	ConsDir bool
	// SegID is a updatable field that is required for the MAC-chaining mechanism.
	SegID uint16
	// Timestamp created by the initiator of the corresponding beacon. The timestamp is expressed in
	// Unix time, and is encoded as an unsigned integer within 4 bytes with 1-second time
	// granularity.  This timestamp enables validation of the hop field by verification of the
	// expiration time and MAC.
	Timestamp uint32
}

InfoField is the InfoField used in the SCION and OneHop path types.

InfoField has the following format:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|r r r r r r P C|      RSV      |             SegID             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           Timestamp                           |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

func (*InfoField) DecodeFromBytes

func (inf *InfoField) DecodeFromBytes(raw []byte) (err error)

DecodeFromBytes populates the fields from a raw buffer. The buffer must be of length >= path.InfoLen. @ requires len(raw) >= InfoLen DecodeFromBytes modifies *inf and reads (but does not modify) the contents of raw. @ preserves acc(inf) && acc(raw, 1/2) When a call that satisfies the precondition (len(raw) >= InfoLen) is made, the return value is guaranteed to be nil. @ ensures err == nil DecodeFromBytes always terminates. @ decreases

func (*InfoField) SerializeTo

func (inf *InfoField) SerializeTo(b []byte) (err error)

SerializeTo writes the fields into the provided buffer. The buffer must be of length >= path.InfoLen. @ requires len(b) >= InfoLen SerializeTo modifies the contents of b and reads (but does not modify) the fields of inf. @ preserves acc(b) && acc(inf, 1/2) When a call that satisfies the precondition (len(b) >= InfoLen) is made, the return value is guaranteed to be nil. @ ensures err == nil SerializeTo always terminates. @ decreases

func (InfoField) String

func (inf InfoField) String() string

String is not verified because Gobra does not yet support the fmt package. @ trusted String always terminates. @ decreases

func (*InfoField) UpdateSegID

func (inf *InfoField) UpdateSegID(hfMac [MacLen]byte)

UpdateSegID updates the SegID field by XORing the SegID field with the 2 first bytes of the MAC. It is the beta calculation according to https://docs.scion.org/en/latest/protocols/scion-header.html#hop-field-mac-computation

UpdateSegID only accesses and modifies the contents of inf.SegID.

@ preserves acc(&inf.SegID) UpdateSegID always terminates. @ decreases

type Metadata

type Metadata struct {
	// Type is a unique value for the path.
	Type Type
	// Desc is the description/name of the path.
	Desc string
	// New is a path constructor function.
	New func() Path
}

Metadata defines a new SCION path type, used for dynamic SICON path type registration.

type Path

type Path interface {
	// SerializeTo serializes the path into the provided buffer.
	SerializeTo(b []byte) error
	// DecodesFromBytes decodes the path from the provided buffer.
	DecodeFromBytes(b []byte) error
	// Reverse reverses a path such that it can be used in the reversed direction.
	//
	// XXX(shitz): This method should possibly be moved to a higher-level path manipulation package.
	Reverse() (Path, error)
	// Len returns the length of a path in bytes.
	Len() int
	// Type returns the type of a path.
	Type() Type
}

Path is the path contained in the SCION header.

func NewPath

func NewPath(pathType Type) (Path, error)

NewPath returns a new path object of pathType.

func NewRawPath

func NewRawPath() Path

NewRawPath returns a new raw path that can hold any path type.

type Type

type Type uint8

Type indicates the type of the path contained in the SCION header.

func (Type) String

func (t Type) String() string