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

• Variables
• type AppAddr
  • func AppAddrFromRaw(buf common.RawBytes, addrType addr.HostAddrType) (*AppAddr, error)
  • func (a *AppAddr) Len() int
  • func (a *AppAddr) Network() string
  • func (a *AppAddr) String() string
  • func (a *AppAddr) Write(buf common.RawBytes) (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, bind *AppAddr, svc addr.HostSVC) (*Conn, uint16, error)
  • func RegisterTimeout(dispatcher string, ia addr.IA, public, bind *AppAddr, svc addr.HostSVC, ...) (*Conn, uint16, error)
  • func (conn *Conn) Read(buf []byte) (int, error)
  • func (conn *Conn) ReadFrom(buf []byte) (int, net.Addr, error)
  • func (conn *Conn) ReadN(msgs []Msg) (int, error)
  • func (conn *Conn) String() string
  • func (conn *Conn) Write(buf []byte) (int, error)
  • func (conn *Conn) WriteN(bufs []Msg) (int, error)
  • func (conn *Conn) WriteNAll(bufs []Msg) (int, error)
  • func (conn *Conn) WriteTo(buf []byte, dst net.Addr) (int, error)
• type Listener
  • func Listen(laddr string) (*Listener, error)
  • func (listener *Listener) Accept() (net.Conn, error)
  • func (listener *Listener) String() string
• type Msg

Variables

var (

	// MaxLength contains the maximum payload length for the ReliableSocket framing protocol.
	MaxLength = (1 << 16) - 1 - hdrLen
)

var (
	NilAppAddr = &AppAddr{
		Addr: addr.HostNone{},
		Port: 0,
	}
)

Types

type AppAddr

type AppAddr struct {
	Addr addr.HostAddr
	Port uint16
}

AppAddr is a L3 + L4 address container, it currently only supports UDP for L4.

func AppAddrFromRaw

func AppAddrFromRaw(buf common.RawBytes, addrType addr.HostAddrType) (*AppAddr, error)

func (*AppAddr) Len

func (a *AppAddr) Len() int

func (*AppAddr) Network

func (a *AppAddr) Network() string

func (*AppAddr) String

func (a *AppAddr) String() string

func (*AppAddr) Write

func (a *AppAddr) Write(buf common.RawBytes) (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 negative timeout means infinite timeout.

To check for timeout errors, type assert the returned error to *net.OpError and call method Timeout().

func Register

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

Register connects to a SCION Dispatcher's UNIX socket. Future messages for address a 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, bind *AppAddr, svc addr.HostSVC,
	timeout time.Duration) (*Conn, uint16, error)

RegisterTimeout acts like Register but takes a timeout.

A negative timeout means infinite timeout.

To check for timeout errors, type assert the returned error to *net.OpError and call method Timeout().

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

func (conn *Conn) ReadN(msgs []Msg) (int, error)

ReadN is an extension of Read that allows callers to receive multiple messages from a ReliableSocket using a reduced number of system calls. ReadN copies data sequentially over each buf slice contained in msgs, blocking until at least one packet has been read. The function returns immediately if at least one packet has been read and the next one is not yet available. Each buffer contains a full packet (similarly to datagram oriented protocols). ReadN returns the number of packets read. For each packet, the copied field of the Msg struct contains the number of bytes in the read packet.

func (*Conn) String

func (conn *Conn) String() string

func (*Conn) Write

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

Write blocks until it sends buf as a single framed message through conn. On error, the number of bytes returned is meaningless. On success, the number of bytes is always len(buf).

func (*Conn) WriteN

func (conn *Conn) WriteN(bufs []Msg) (int, error)

WriteN is an extension of Write that allows callers to send multiple messages through a ReliableSocket using a reduced number of system calls. WriteN copies data sequentially from each buf slice contained in msgs. Destination address information can be specified in the addr field of each message. If the address is nil, then a HostTypeNone address is assumed. The function copies as many message as it can fit inside its internal buffer and then flushes those messages to the underlying socket in as few syscalls as possible. Each buffer is copied in its entirety (similarly to datagram oriented protocols); the copied field of struct Msg is reset to 0 for written packets. WriteN returns the number of packets written.

func (*Conn) WriteNAll

func (conn *Conn) WriteNAll(bufs []Msg) (int, error)

WriteNAll is a helper function that repeatedly blocks until all messages in bufs are sent on the underlying socket. WriteNAll returns the number of written messages; on success, this is equal to len(bufs).

func (*Conn) WriteTo

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

WriteTo works similarly to Write. In addition to Write, the ReliableSocket message header will contain the address and port information in dst.

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 Msg

type Msg struct {
	Buffer []byte
	Copied int
	Addr   *AppAddr
}