reliable

Documentation

Overview

Package reliable implements the SCION ReliableSocket protocol

Servers should first call Listen on a UNIX socket address, and then call Accept on the received Listener.

Clients should either call:

Dial, if they do not want to register a receiving address with the remote end
  (e.g., when connecting to SCIOND);
Register, to register the address argument with the remote end
  (e.g., when connecting to a dispatcher).

ReliableSocket common header message format:

8-bytes: COOKIE (0xde00ad01be02ef03)
1-byte: ADDR TYPE (NONE=0, IPv4=1, IPv6=2, SVC=3)
4-byte: data length
var-byte: Destination address (0 bytes for SCIOND API)
  +2-byte: If destination address not NONE, destination port
var-byte: Payload

ReliableSocket registration message format:

13-bytes: [Common header with address type NONE]
 1-byte: Command (bit mask with 0x04=Bind address, 0x02=SCMP enable, 0x01 always set)
 1-byte: L4 Proto (IANA number)
 8-bytes: ISD-AS
 2-bytes: L4 port
 1-byte: Address type
 var-byte: Address
+2-bytes: L4 bind port  \
+1-byte: Address type    ) (optional bind address)
+var-byte: Bind Address /
+2-bytes: SVC (optional SVC type)

To communicate with SCIOND, clients must first connect to SCIOND's UNIX socket. Messages for SCIOND must set the ADDR TYPE field in the common header to NONE. The payload contains the query for SCIOND (e.g., a request for paths to a SCION destination). The reply header contains the same fields, and the reply payload contains the query answer.

To receive messages from remote SCION hosts, hosts can register their address and port with the SCION dispatcher. The common header of a registration message uses an address of type NONE. The payload contains the address type of the registered address, the address itself and the layer 4 port.

To send messages to remote SCION hosts, hosts fill in the common header with the address type, the address and the layer 4 port of the remote host.

Reads and writes to the connection are thread safe.

Index

• Constants
• Variables
• func IsDispatcherError(err error) bool
• func IsSpecificSysError(err error, errno syscall.Errno) bool
• func IsSysError(err error) bool
• type CommandBitField
• type Confirmation
  • func (c *Confirmation) DecodeFromBytes(b []byte) error
  • func (c *Confirmation) SerializeTo(b []byte) (int, error)
• type Conn
  • func Dial(address string) (*Conn, error)
  • func DialTimeout(address string, timeout time.Duration) (*Conn, error)
  • func Register(dispatcher string, ia addr.IA, public *addr.AppAddr, bind *overlay.OverlayAddr, ...) (*Conn, uint16, error)
  • func RegisterTimeout(dispatcher string, ia addr.IA, public *addr.AppAddr, bind *overlay.OverlayAddr, ...) (*Conn, uint16, error)
  • func (conn *Conn) Read(buf []byte) (int, error)
  • func (conn *Conn) ReadFrom(buf []byte) (int, net.Addr, error)
  • func (conn *Conn) WriteTo(buf []byte, dst net.Addr) (int, error)
• type DispatcherService
  • func NewDispatcherService(name string) DispatcherService
• type Listener
  • func Listen(laddr string) (*Listener, error)
  • func (listener *Listener) Accept() (net.Conn, error)
  • func (listener *Listener) String() string
• type OverlayPacket
  • func (p *OverlayPacket) DecodeFromBytes(b []byte) error
  • func (p *OverlayPacket) SerializeTo(b []byte) (int, error)
• type ReadPacketizer
  • func NewReadPacketizer(conn net.Conn) *ReadPacketizer
  • func (r *ReadPacketizer) Read(b []byte) (int, error)
• type Registration
  • func (r *Registration) DecodeFromBytes(b []byte) error
  • func (r *Registration) SerializeTo(b []byte) (int, error)
• type WriteStreamer
  • func NewWriteStreamer(conn net.Conn) *WriteStreamer
  • func (writer *WriteStreamer) Write(b []byte) error

Constants

const (
	// DefaultDispPath contains the system default for a dispatcher socket.
	DefaultDispPath = "/run/shm/dispatcher/default.sock"

	// DefaultDispSocketFileMode allows read/write to the user and group only.
	DefaultDispSocketFileMode = 0770
)

Variables

var (
	ErrNoAddress             common.ErrMsg = "no address found"
	ErrNoPort                common.ErrMsg = "missing port"
	ErrPayloadTooLong        common.ErrMsg = "payload too long"
	ErrIncompleteFrameHeader common.ErrMsg = "incomplete frame header"
	ErrBadFrameLength        common.ErrMsg = "bad frame length"
	ErrBadCookie             common.ErrMsg = "bad cookie"
	ErrBadAddressType        common.ErrMsg = "bad address type"
	ErrIncompleteAddress     common.ErrMsg = "incomplete IP address"
	ErrIncompletePort        common.ErrMsg = "incomplete UDP port"
	ErrIncompleteMessage     common.ErrMsg = "incomplete message"
	ErrBadLength             common.ErrMsg = "bad length"
	ErrBufferTooSmall        common.ErrMsg = "buffer too small"
)

Possible errors

Functions

func IsDispatcherError

func IsDispatcherError(err error) bool

func IsSpecificSysError

func IsSpecificSysError(err error, errno syscall.Errno) bool

func IsSysError

func IsSysError(err error) bool

Types

type CommandBitField

type CommandBitField uint8

const (
	CmdBindAddress CommandBitField = 0x04
	CmdEnableSCMP  CommandBitField = 0x02
	CmdAlwaysOn    CommandBitField = 0x01
)

type Confirmation

type Confirmation struct {
	Port uint16
}

func (*Confirmation) DecodeFromBytes

func (c *Confirmation) DecodeFromBytes(b []byte) error

func (*Confirmation) SerializeTo

func (c *Confirmation) SerializeTo(b []byte) (int, error)

type Conn

type Conn struct {
	*net.UnixConn
	// contains filtered or unexported fields
}

Conn implements the ReliableSocket framing protocol over UNIX sockets.

func Dial

func Dial(address string) (*Conn, error)

Dial connects to the UNIX socket specified by address.

func DialTimeout

func DialTimeout(address string, timeout time.Duration) (*Conn, error)

DialTimeout acts like Dial but takes a timeout.

A timeout of 0 means infinite timeout.

To check for timeout errors, call serrors.IsTimeout on the error.

func Register

func Register(dispatcher string, ia addr.IA, public *addr.AppAddr, bind *overlay.OverlayAddr,
	svc addr.HostSVC) (*Conn, uint16, error)

Register connects to a SCION Dispatcher's UNIX socket. Future messages for address public or bind in AS ia which arrive at the dispatcher can be read by calling Read on the returned Conn structure.

func RegisterTimeout

func RegisterTimeout(dispatcher string, ia addr.IA, public *addr.AppAddr,
	bind *overlay.OverlayAddr, svc addr.HostSVC, timeout time.Duration) (*Conn, uint16, error)

RegisterTimeout acts like Register but takes a timeout.

A timeout of 0 means infinite timeout.

To check for timeout errors, call serrors.IsTimeout on the error.

func (*Conn) Read

func (conn *Conn) Read(buf []byte) (int, error)

Read blocks until it reads the next framed message payload from conn and stores it in buf. The first return value contains the number of payload bytes read. buf must be large enough to fit the entire message. No addressing data is returned, only the payload. On error, the number of bytes returned is meaningless.

func (*Conn) ReadFrom

func (conn *Conn) ReadFrom(buf []byte) (int, net.Addr, error)

ReadFrom works similarly to Read. In addition to Read, it also returns the last hop (usually, the border router) which sent the message.

func (*Conn) WriteTo

func (conn *Conn) WriteTo(buf []byte, dst net.Addr) (int, error)

WriteTo blocks until it sends buf as a single framed message through conn. The ReliableSocket message header will contain the address and port information in dst. On error, the number of bytes returned is meaningless. On success, the number of bytes is always len(buf).

type DispatcherService

type DispatcherService interface {
	Register(ia addr.IA, public *addr.AppAddr, bind *overlay.OverlayAddr,
		svc addr.HostSVC) (net.PacketConn, uint16, error)
	RegisterTimeout(ia addr.IA, public *addr.AppAddr, bind *overlay.OverlayAddr,
		svc addr.HostSVC, timeout time.Duration) (net.PacketConn, uint16, error)
}

DispatcherService controls how SCION applications open sockets in the SCION world.

func NewDispatcherService

func NewDispatcherService(name string) DispatcherService

NewDispatcherService creates a new dispatcher API endpoint on top of a UNIX STREAM reliable socket. If name is empty, the default dispatcher path is chosen.

type Listener

type Listener struct {
	*net.UnixListener
}

Listener listens on Unix sockets and returns Conn sockets on Accept().

func Listen

func Listen(laddr string) (*Listener, error)

Listen listens on UNIX socket laddr.

func (*Listener) Accept

func (listener *Listener) Accept() (net.Conn, error)

Accept returns sockets which implement the SCION ReliableSocket protocol for reading and writing.

func (*Listener) String

func (listener *Listener) String() string

type OverlayPacket

type OverlayPacket struct {
	Address *net.UDPAddr
	Payload []byte
}

OverlayPacket contains metadata about a SCION packet going through the reliable socket framing protocol.

func (*OverlayPacket) DecodeFromBytes

func (p *OverlayPacket) DecodeFromBytes(b []byte) error

func (*OverlayPacket) SerializeTo

func (p *OverlayPacket) SerializeTo(b []byte) (int, error)

type ReadPacketizer

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

ReadPacketizer splits a stream of reliable socket frames into packets.

FIXME(scrye): This will be deleted when we move to SEQPACKET.

func NewReadPacketizer

func NewReadPacketizer(conn net.Conn) *ReadPacketizer

func (*ReadPacketizer) Read

func (r *ReadPacketizer) Read(b []byte) (int, error)

type Registration

type Registration struct {
	IA            addr.IA
	PublicAddress *net.UDPAddr
	BindAddress   *net.UDPAddr
	SVCAddress    addr.HostSVC
}

Registration contains metadata for a SCION Dispatcher registration message.

func (*Registration) DecodeFromBytes

func (r *Registration) DecodeFromBytes(b []byte) error

func (*Registration) SerializeTo

func (r *Registration) SerializeTo(b []byte) (int, error)

type WriteStreamer

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

WriteStreamer sends a packet via a stream. It is guaranteed to block until the whole packet has been sent (or an error occurred).

FIXME(scrye): This will be delete when we move to SEQPACKET.

func NewWriteStreamer

func NewWriteStreamer(conn net.Conn) *WriteStreamer

func (*WriteStreamer) Write

func (writer *WriteStreamer) Write(b []byte) error