snet

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Mar 30, 2020 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package snet implements interfaces net.Conn and net.PacketConn for SCION connections.

New networking contexts can be created using NewNetwork. Calling the Dial or Listen methods on the networking context yields connections that run in that context.

A connection can be created by calling Dial or Listen; both functions register an address-port pair with the local dispatcher. For Dial, the remote address is fixed, meaning only Read and Write can be used. Attempting to ReadFrom or WriteTo a connection created by Dial is an invalid operation. For Listen, the remote address cannot be fixed. ReadFrom can be used to read from the connection and find out the sender's address; and WriteTo can be used to send a message to a chosen destination.

Multiple networking contexts can share the same SCIOND and/or dispatcher.

Write calls never return SCMP errors directly. If a write call caused an SCMP message to be received by the Conn, it can be inspected by calling Read. In this case, the error value is non-nil and can be type asserted to *OpError. Method SCMP() can be called on the error to extract the SCMP header.

Important: not draining SCMP errors via Read calls can cause the dispatcher to shutdown the socket (see https://github.com/scionproto/scion/pull/1356). To prevent this on a Conn object with only Write calls, run a separate goroutine that continuously calls Read on the Conn.

Index

Constants

View Source 
const (
	// BufSize is the receive and send buffer sizes
	BufSize = 1<<16 - 1
)

Variables

This section is empty.

Functions

func CopyUDPAddr added in v0.5.0 

func CopyUDPAddr(a *net.UDPAddr) *net.UDPAddr

CopyUDPAddr creates a deep copy of the net.UDPAddr.

func StableSortExtensions added in v0.4.0 

func StableSortExtensions(data []common.Extension)

StableSortExtensions sorts the extensions in data in place. The sort is stable.

SCMP extensions are moved to the start of the slice, followed by HBH extensions and finally E2E extensions.

StableSortExtensions performs no validations on the number and/or types of extensions.

The function panics if data is nil.

Types

type BaseRouter added in v0.4.0 

type BaseRouter struct {
	Querier PathQuerier
}

func (*BaseRouter) AllRoutes added in v0.4.0 

func (r *BaseRouter) AllRoutes(ctx context.Context, dst addr.IA) ([]Path, error)

AllRoutes is the same as Route except that it returns multiple paths.

func (*BaseRouter) Route added in v0.4.0 

func (r *BaseRouter) Route(ctx context.Context, dst addr.IA) (Path, error)

Route uses the specified path resolver (if one exists) to obtain a path from the local AS to dst.

type Bytes added in v0.4.0 

type Bytes common.RawBytes

Bytes contains the raw slices of data related to a packet. Most callers can safely ignore it. For performance-critical applications, callers should manually allocate/recycle the Bytes.

Prior to serialization/decoding, the internal slice is reset to its full capacity, so be careful about passing in slices that have runoff data after their length.

After a packet has been serialized/decoded, the length of Contents will be equal to the size of the entire packet data. The capacity remains unchanged.

If Bytes is not initialized, space will be allocated during serialization/decoding.

func (*Bytes) Prepare added in v0.4.0 

func (b *Bytes) Prepare()

Prepare readies a layer's storage for use.

If the layer is not allocated, a backing buffer of maximum packet size is allocated.

If the layer is already allocated, its length is reset to its capacity.

type Conn 

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

func (*Conn) Close 

func (c *Conn) Close() error

func (*Conn) LocalAddr 

func (c *Conn) LocalAddr() net.Addr

func (*Conn) Read 

func (c *Conn) Read(b []byte) (int, error)

Read reads data into b from a connection with a fixed remote address. If the remote address for the connection is unknown, Read returns an error.

func (*Conn) ReadFrom 

func (c *Conn) ReadFrom(b []byte) (int, net.Addr, error)

ReadFrom reads data into b, returning the length of copied data and the address of the sender.

func (*Conn) RemoteAddr 

func (c *Conn) RemoteAddr() net.Addr

func (*Conn) SVC 

func (c *Conn) SVC() addr.HostSVC

func (*Conn) SetDeadline 

func (c *Conn) SetDeadline(t time.Time) error

func (*Conn) SetReadDeadline 

func (c *Conn) SetReadDeadline(t time.Time) error

func (*Conn) SetWriteDeadline 

func (c *Conn) SetWriteDeadline(t time.Time) error

func (*Conn) Write 

func (c *Conn) Write(b []byte) (int, error)

Write sends b through a connection with fixed remote address. If the remote address for the connection is unknown, Write returns an error.

func (*Conn) WriteTo 

func (c *Conn) WriteTo(b []byte, raddr net.Addr) (int, error)

WriteTo sends b to raddr.

type DefaultPacketDispatcherService added in v0.4.0 

type DefaultPacketDispatcherService struct {
	// Dispatcher is used to get packets from the local SCION Dispatcher process.
	Dispatcher reliable.Dispatcher
	// SCMPHandler is invoked for packets that contain an SCMP L4. If the
	// handler is nil, errors are returned back to applications every time an
	// SCMP message is received.
	SCMPHandler SCMPHandler
}

DefaultPacketDispatcherService parses/serializes packets received from / sent to the dispatcher.

func (*DefaultPacketDispatcherService) Register added in v0.5.0 

func (s *DefaultPacketDispatcherService) Register(ctx context.Context, ia addr.IA,
	registration *net.UDPAddr, svc addr.HostSVC) (PacketConn, uint16, error)

type Error 

type Error interface {
	error
	SCMP() *scmp.Hdr
}

type IntraASPathQuerier added in v0.5.0 

type IntraASPathQuerier struct {
	IA addr.IA
}

IntraASPathQuerier implements the PathQuerier interface. It will only provide AS internal paths, i.e., empty paths with only the IA as destination. This should only be used in places where you know that you only need to communicate inside the AS.

func (IntraASPathQuerier) Query added in v0.5.0 

func (q IntraASPathQuerier) Query(_ context.Context, _ addr.IA) ([]Path, error)

Query implements PathQuerier.

type Network 

type Network interface {
	Listen(ctx context.Context, network string, listen *net.UDPAddr,
		svc addr.HostSVC) (*Conn, error)
	Dial(ctx context.Context, network string, listen *net.UDPAddr, remote *UDPAddr,
		svc addr.HostSVC) (*Conn, error)
}

type OpError 

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

func (*OpError) Error 

func (e *OpError) Error() string

func (*OpError) RevInfo added in v0.4.0 

func (e *OpError) RevInfo() *path_mgmt.RevInfo

func (*OpError) SCMP 

func (e *OpError) SCMP() *scmp.Hdr

type Packet added in v0.5.0 

type Packet struct {
	Bytes
	PacketInfo
}

type PacketConn added in v0.4.0 

type PacketConn interface {
	ReadFrom(pkt *Packet, ov *net.UDPAddr) error
	WriteTo(pkt *Packet, ov *net.UDPAddr) error
	SetReadDeadline(t time.Time) error
	SetWriteDeadline(t time.Time) error
	SetDeadline(t time.Time) error
	Close() error
}

PacketConn gives applications easy access to writing and reading custom SCION packets.

type PacketDispatcherService added in v0.4.0 

type PacketDispatcherService interface {
	Register(ctx context.Context, ia addr.IA, registration *net.UDPAddr,
		svc addr.HostSVC) (PacketConn, uint16, error)
}

PacketDispatcherService constructs SCION sockets where applications have fine-grained control over header fields.

type PacketInfo added in v0.5.0 

type PacketInfo struct {
	// Destination contains the destination address.
	Destination SCIONAddress
	// Source contains the source address. If it is an SVC address, packet
	// serialization will return an error.
	Source SCIONAddress
	// Path contains a SCION forwarding path. The field must be nil or an empty
	// path if the source and destination are inside the same AS.
	//
	// If the source and destination are in different ASes but the path is
	// nil or empty, an error is returned during serialization.
	Path *spath.Path
	// Extensions contains SCION HBH and E2E extensions. When received from a
	// RawSCIONConn, extensions are present in the order they were found in the packet.
	//
	// When writing to a RawSCIONConn, the serializer will attempt
	// to reorder the extensions, depending on their type, in the correct
	// order. If the number of extensions is over the limit allowed by SCION,
	// serialization will fail. Whenever multiple orders are valid, the stable
	// sorting is preferred. The extensions are sorted in place, so callers
	// should expect the order to change after a write.
	//
	// The SCMP HBH extension needs to be manually included by calling code,
	// even when the L4Header and Payload demand one (as is the case, for
	// example, for a SCMP::General::RecordPathRequest packet).
	Extensions []common.Extension
	// L4Header contains L4 header information.
	L4Header l4.L4Header
	Payload  common.Payload
}

PacketInfo contains the data needed to construct a SCION packet.

This is a high-level structure, and can only be used to create valid packets. The documentation for each field specifies cases where serialization might fail due to some violation of SCION protocol rules.

type Path added in v0.4.0 

type Path interface {
	// Fingerprint uniquely identifies the path based on the sequence of
	// ASes and BRs. Other metadata, such as MTU or NextHop have no effect
	// on the fingerprint. Empty string means unknown fingerprint.
	Fingerprint() PathFingerprint
	// OverlayNextHop returns the address:port pair of a local-AS overlay
	// speaker. Usually, this is a border router that will forward the traffic.
	OverlayNextHop() *net.UDPAddr
	// Path returns a raw (data-plane compatible) representation of the path.
	// The returned path is initialized and ready for use in snet calls that
	// deal with raw paths.
	Path() *spath.Path
	// Interfaces returns a list of interfaces on the path. If the list is not
	// available the result is nil.
	Interfaces() []PathInterface
	// Destination is the AS the path points to. Empty paths return the local
	// AS of the router that created them.
	Destination() addr.IA
	// MTU returns the MTU of the path. If the result is zero, MTU is unknown.
	MTU() uint16
	// Expiry returns the expiration time of the path. If the result is a zero
	// value expiration time is unknown.
	Expiry() time.Time
	// Copy create a copy of the path.
	Copy() Path
}

Path is an abstract representation of a path. Most applications do not need access to the raw internals.

An empty path is a special kind of path that can be used for intra-AS traffic. Empty paths are valid return values for certain route calls (e.g., if the source and destination ASes match, or if a router was configured without a source of paths). An empty path only contains a Destination value, all other values are zero values.

type PathFingerprint added in v0.5.0 

type PathFingerprint string

func (PathFingerprint) String added in v0.5.0 

func (pf PathFingerprint) String() string

type PathInterface added in v0.5.0 

type PathInterface interface {
	// ID is the ID of the interface.
	ID() common.IFIDType
	// IA is the ISD AS identifier of the interface.
	IA() addr.IA
}

PathInterface is an interface of the path. This is currently an interface so that packages which can not depend on snet can still implement the snet.Path interface.

type PathQuerier added in v0.5.0 

type PathQuerier interface {
	Query(context.Context, addr.IA) ([]Path, error)
}

type RevocationHandler added in v0.4.0 

type RevocationHandler interface {
	// RevokeRaw handles a revocation received as raw bytes.
	RevokeRaw(ctx context.Context, rawSRevInfo common.RawBytes)
}

RevocationHandler is called by the default SCMP Handler whenever revocations are encountered.

type Router added in v0.4.0 

type Router interface {
	// Route returns a path from the local AS to dst. If dst matches the local
	// AS, an empty path is returned.
	Route(ctx context.Context, dst addr.IA) (Path, error)
	// AllRoutes is similar to Route except that it returns multiple paths.
	AllRoutes(ctx context.Context, dst addr.IA) ([]Path, error)
}

Router performs path resolution for SCION-speaking applications.

Most applications backed by SCIOND can use the default router implementation in this package. Applications that run SCIOND-less (PS, SD, BS) might be interested in spinning their own implementations.

type SCIONAddress added in v0.4.0 

type SCIONAddress struct {
	IA   addr.IA
	Host addr.HostAddr
}

SCIONAddress is the fully-specified address of a host.

type SCIONNetwork added in v0.3.0 

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

SCIONNetwork is the SCION networking context, containing local ISD-AS, SCIOND, Dispatcher and Path resolver.

func NewCustomNetworkWithPR added in v0.4.0 

func NewCustomNetworkWithPR(ia addr.IA, pktDispatcher PacketDispatcherService) *SCIONNetwork

NewCustomNetworkWithPR is similar to NewNetworkWithPR, while giving control over packet processing via pktDispatcher.

func NewNetworkWithPR 

func NewNetworkWithPR(ia addr.IA, dispatcher reliable.Dispatcher,
	querier PathQuerier, revHandler RevocationHandler) *SCIONNetwork

NewNetworkWithPR creates a new networking context with path resolver pr. A nil path resolver means the Network will run without SCIOND.

func (*SCIONNetwork) Dial added in v0.5.0 

func (n *SCIONNetwork) Dial(ctx context.Context, network string, listen *net.UDPAddr,
	remote *UDPAddr, svc addr.HostSVC) (*Conn, error)

Dial returns a SCION connection to remote. Nil values for listen are not supported yet. Parameter network must be "udp". The returned connection's Read and Write methods can be used to receive and send SCION packets. Remote address requires a path and the underlay net hop to be set if the destination is in a remote AS.

The context is used for connection setup, it doesn't affect the returned connection.

func (*SCIONNetwork) Listen added in v0.5.0 

func (n *SCIONNetwork) Listen(ctx context.Context, network string, listen *net.UDPAddr,
	svc addr.HostSVC) (*Conn, error)

Listen registers listen with the dispatcher. Nil values for listen are not supported yet. The returned connection's ReadFrom and WriteTo methods can be used to receive and send SCION packets with per-packet addressing. Parameter network must be "udp".

The context is used for connection setup, it doesn't affect the returned connection.

type SCIONPacketConn added in v0.4.0 

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

SCIONPacketConn gives applications full control over the content of valid SCION packets.

func NewSCIONPacketConn added in v0.4.0 

func NewSCIONPacketConn(conn net.PacketConn, scmpHandler SCMPHandler) *SCIONPacketConn

NewSCIONPacketConn creates a new conn with packet serialization/decoding support that transfers data over conn.

func (*SCIONPacketConn) Close added in v0.4.0 

func (c *SCIONPacketConn) Close() error

func (*SCIONPacketConn) ReadFrom added in v0.4.0 

func (c *SCIONPacketConn) ReadFrom(pkt *Packet, ov *net.UDPAddr) error

func (*SCIONPacketConn) SetDeadline added in v0.4.0 

func (c *SCIONPacketConn) SetDeadline(d time.Time) error

func (*SCIONPacketConn) SetReadDeadline added in v0.4.0 

func (c *SCIONPacketConn) SetReadDeadline(d time.Time) error

func (*SCIONPacketConn) SetWriteDeadline added in v0.4.0 

func (c *SCIONPacketConn) SetWriteDeadline(d time.Time) error

func (*SCIONPacketConn) WriteTo added in v0.4.0 

func (c *SCIONPacketConn) WriteTo(pkt *Packet, ov *net.UDPAddr) error

type SCMPHandler added in v0.4.0 

type SCMPHandler interface {
	// Handle processes the packet as an SCMP packet. If packet is not SCMP, it
	// returns an error.
	//
	// If the handler returns an error value, snet will propagate the error
	// back to the caller. If the return value is nil, snet will reattempt to
	// read a data packet from the underlying dispatcher connection.
	//
	// Handlers that wish to ignore SCMP can just return nil.
	//
	// If the handler mutates the packet, the changes are seen by snet
	// connection method callers.
	Handle(pkt *Packet) error
}

SCMPHandler customizes the way snet connections deal with SCMP.

func NewSCMPHandler added in v0.4.0 

func NewSCMPHandler(rh RevocationHandler) SCMPHandler

NewSCMPHandler creates a default SCMP handler that forwards revocations to the revocation handler. SCMP packets are also forwarded to snet callers via errors returned by Read calls.

If the revocation handler is nil, revocations are not forwarded. However, they are still sent back to the caller during read operations.

type SVCAddr added in v0.5.0 

type SVCAddr struct {
	IA      addr.IA
	Path    *spath.Path
	NextHop *net.UDPAddr
	SVC     addr.HostSVC
}

SVCAddr is the address type for SVC destinations.

func (*SVCAddr) Copy added in v0.5.0 

func (a *SVCAddr) Copy() *SVCAddr

Copy creates a deep copy of the address.

func (*SVCAddr) GetPath added in v0.5.0 

func (a *SVCAddr) GetPath() (Path, error)

GetPath returns a path with attached metadata.

func (*SVCAddr) Network added in v0.5.0 

func (a *SVCAddr) Network() string

Network implements net.Addr interface.

func (*SVCAddr) String added in v0.5.0 

func (a *SVCAddr) String() string

String implements net.Addr interface.

type SerializationOptions added in v0.4.0 

type SerializationOptions struct {
	// If ComputeChecksums is true, the checksums in sent Packets are
	// recomputed. Otherwise, the checksum value is left intact.
	ComputeChecksums bool
	// If FixLengths is true, any lengths in sent Packets are recomputed
	// to match the data contained in payloads/inner layers. This currently
	// concerns extension headers and the L4 header.
	FixLengths bool
	// If InitializePaths is set to true, then forwarding paths are reset to
	// their starting InfoField/HopField during serialization, irrespective of
	// previous offsets. If it is set to false, then the fields are left
	// unchanged.
	InitializePaths bool
}

type UDPAddr added in v0.5.0 

type UDPAddr struct {
	IA      addr.IA
	Path    *spath.Path
	NextHop *net.UDPAddr
	Host    *net.UDPAddr
}

UDPAddr to be used when UDP host.

func ParseUDPAddr added in v0.5.0 

func ParseUDPAddr(s string) (*UDPAddr, error)

ParseUDPAddr converts an address string to a SCION address. The supported formats are:

Recommended:

  • isd-as,ipv4:port (e.g., 1-ff00:0:300,192.168.1.1:8080)
  • isd-as,[ipv6]:port (e.g., 1-ff00:0:300,[f00d::1337]:808)

Others:

  • isd-as,[ipv4]:port (e.g., 1-ff00:0:300,[192.168.1.1]:80)
  • isd-as,[ipv4] (e.g., 1-ff00:0:300,[192.168.1.1])
  • isd-as,[ipv6] (e.g., 1-ff00:0:300,[f00d::1337])
  • isd-as,ipv4 (e.g., 1-ff00:0:300,192.168.1.1)
  • isd-as,ipv6 (e.g., 1-ff00:0:300,f00d::1337)

Not supported:

  • isd-as,ipv6:port (caveat if ipv6:port builds a valid ipv6 address, it will successfully parse as ipv6 without error)

func (*UDPAddr) Copy added in v0.5.0 

func (a *UDPAddr) Copy() *UDPAddr

Copy creates a deep copy of the address.

func (*UDPAddr) GetPath added in v0.5.0 

func (a *UDPAddr) GetPath() (Path, error)

GetPath returns a path with attached metadata.

func (*UDPAddr) Network added in v0.5.0 

func (a *UDPAddr) Network() string

Network implements net.Addr interface.

func (*UDPAddr) Set added in v0.5.0 

func (a *UDPAddr) Set(s string) error

Set implements the flag.Value interface

func (*UDPAddr) String added in v0.5.0 

func (a *UDPAddr) String() string

String implements net.Addr interface.

Source Files

View all Source files

Directories

Path Synopsis
internal
metrics
Package mock_snet is a generated GoMock package.
 Package mock_snet is a generated GoMock package.
QUIC/SCION implementation.
 QUIC/SCION implementation.

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.