appnet

Documentation

Overview

Package appnet provides a simplified and functionally extended wrapper interface to the scionproto/scion package snet.

Dispatcher and SCION daemon connections

During the hidden initialisation of this package, the dispatcher and sciond connections are opened. The sciond connection determines the local IA. The dispatcher and sciond sockets are assumed to be at default locations, but this can be overridden using environment variables:

SCION_DISPATCHER_SOCKET: /run/shm/dispatcher/default.sock
SCION_DAEMON_ADDRESS: 127.0.0.1:30255

This is convenient for the normal use case of running the endhost stack for a single SCION AS. When running multiple local ASes, e.g. during development, the address of the sciond corresponding to the desired AS needs to be specified in the SCION_DAEMON_ADDRESS environment variable.

Wildcard IP Addresses

snet does not currently support binding to wildcard addresses. This will hopefully be added soon-ish, but in the meantime, this package emulates this functionality. There is one restriction, that applies to hosts with multiple IP addresses in the AS: the behaviour will be that of binding to one specific local IP address, which means that the application will not be reachable using any of the other IP addresses. Traffic sent will always appear to originate from this specific IP address, even if that's not the correct route to a destination in the local AS.

This restriction will very likely not cause any issues, as a fairly contrived network setup would be required. Also, sciond has a similar restriction (binds to one specific IP address).

Index

• Constants
• func ChoosePathByMetric(pathAlgo int, dst addr.IA) (snet.Path, error)
• func ChoosePathInteractive(dst addr.IA) (snet.Path, error)
• func Dial(address string) (*snet.Conn, error)
• func DialAddr(raddr *snet.UDPAddr) (*snet.Conn, error)
• func Listen(listen *net.UDPAddr) (*snet.Conn, error)
• func ListenPort(port uint16) (*snet.Conn, error)
• func MangleSCIONAddr(address string) string
• func QueryPaths(ia addr.IA) ([]snet.Path, error)
• func ResolveUDPAddr(address string) (*snet.UDPAddr, error)
• func ResolveUDPAddrAt(address string, resolver Resolver) (*snet.UDPAddr, error)
• func SetDefaultPath(addr *snet.UDPAddr) error
• func SetPath(addr *snet.UDPAddr, path snet.Path)
• func SplitHostPort(hostport string) (host, port string, err error)
• func UnmangleSCIONAddr(address string) string
• type HostNotFoundError
  • func (e *HostNotFoundError) Error() string
• type Network
  • func DefNetwork() *Network
• type Resolver
  • func DefaultResolver() Resolver
• type ResolverList
  • func (resolvers ResolverList) Resolve(name string) (*snet.SCIONAddress, error)

Constants

const (
	PathAlgoDefault = iota // default algorithm
	MTU                    // metric for path with biggest MTU
	Shortest               // metric for shortest path
)

metrics for path selection

Functions

func ChoosePathByMetric

func ChoosePathByMetric(pathAlgo int, dst addr.IA) (snet.Path, error)

ChoosePathByMetric chooses the best path based on the metric pathAlgo If the remote address is in the local IA, return (nil, nil).

func ChoosePathInteractive

func ChoosePathInteractive(dst addr.IA) (snet.Path, error)

ChoosePathInteractive presents the user a selection of paths to choose from. If the remote address is in the local IA, return (nil, nil), without prompting the user.

func Dial

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

Dial connects to the address (on the SCION/UDP network). The address can be of the form of a SCION address (i.e. of the form "ISD-AS,[IP]:port") or in the form of hostname:port.

func DialAddr

func DialAddr(raddr *snet.UDPAddr) (*snet.Conn, error)

DialAddr connects to the address (on the SCION/UDP network).

If no path is specified in raddr, DialAddr will choose the first available path. This path is never updated during the lifetime of the conn. This does not support long lived connections well, as the path *will* expire. This is all that snet currently provides, we'll need to add a layer on top that updates the paths in case they expire or are revoked.

func Listen

func Listen(listen *net.UDPAddr) (*snet.Conn, error)

Listen acts like net.ListenUDP in a SCION network. The listen address or parts of it may be nil or unspecified, signifying to listen on a wildcard address.

See note on wildcard addresses in the package documentation.

func ListenPort

func ListenPort(port uint16) (*snet.Conn, error)

ListenPort is a shortcut to Listen on a specific port with a wildcard IP address.

See note on wildcard addresses in the package documentation.

func MangleSCIONAddr

func MangleSCIONAddr(address string) string

MangleSCIONAddr mangles a SCION address string (if it is one) so it can be safely used in the host part of a URL.

func QueryPaths

func QueryPaths(ia addr.IA) ([]snet.Path, error)

QueryPaths queries the DefNetwork's sciond PathQuerier connection for paths to addr If addr is in the local IA, an empty slice and no error is returned.

func ResolveUDPAddr

func ResolveUDPAddr(address string) (*snet.UDPAddr, error)

ResolveUDPAddr parses the address and resolves the hostname. The address can be of the form of a SCION address (i.e. of the form "ISD-AS,[IP]:port") or in the form of "hostname:port". If the address is in the form of a hostname, the DefaultResolver is used to resolve the name.

func ResolveUDPAddrAt

func ResolveUDPAddrAt(address string, resolver Resolver) (*snet.UDPAddr, error)

ResolveUDPAddrAt parses the address and resolves the hostname. The address can be of the form of a SCION address (i.e. of the form "ISD-AS,[IP]:port") or in the form of "hostname:port". If the address is in the form of a hostname, resolver is used to resolve the name.

func SetDefaultPath

func SetDefaultPath(addr *snet.UDPAddr) error

SetDefaultPath sets the first path returned by a query to sciond. This is a no-op if if remote is in the local AS.

func SetPath

func SetPath(addr *snet.UDPAddr, path snet.Path)

SetPath is a helper function to set the path on an snet.UDPAddr

func SplitHostPort

func SplitHostPort(hostport string) (host, port string, err error)

SplitHostPort splits a host:port string into host and port variables. This is analogous to net.SplitHostPort, which however refuses to handle SCION addresses. The address can be of the form of a SCION address (i.e. of the form "ISD-AS,[IP]:port") or in the form of "hostname:port".

func UnmangleSCIONAddr

func UnmangleSCIONAddr(address string) string

UnmangleSCIONAddr returns a SCION address that can be parsed with with snet.ParseUDPAddr. If the input is not a SCION address (e.g. a hostname), the address is returned unchanged. This parses the address, so that it can safely join host and port, with the brackets in the right place. Yes, this means this will be parsed twice.

Assumes that address always has a port (this is enforced by the http3 roundtripper code)

Types

type HostNotFoundError

type HostNotFoundError struct {
	Host string
}

HostNotFoundError is returned by a Resolver when the name was not found, but otherwise no error occurred.

func (*HostNotFoundError) Error

func (e *HostNotFoundError) Error() string

type Network

type Network struct {
	snet.Network
	IA          addr.IA
	PathQuerier snet.PathQuerier
	// contains filtered or unexported fields
}

Network extends the snet.Network interface by making the local IA and common sciond connections public. The default singleton instance of this type is obtained by the DefNetwork function.

func DefNetwork

func DefNetwork() *Network

DefNetwork initialises and returns the singleton default Network. Typically, this will not be needed for applications directly, as they can use the simplified Dial/Listen functions provided here.

type Resolver

type Resolver interface {
	// Resolve finds an address for the name.
	// Returns a HostNotFoundError if the name was not found, but otherwise no
	// error occurred.
	Resolve(name string) (*snet.SCIONAddress, error)
}

Resolver is the interface to resolve a host name to a SCION host address. Currently, this is implemented for reading a hosts file and RAINS

func DefaultResolver

func DefaultResolver() Resolver

DefaultResolver returns the default name resolver, used in ResolveUDPAddr. It will use the following sources, in the given order of precedence, to resolve a name:

• /etc/hosts
• /etc/scion/hosts
• RAINS, if a server is configured in /etc/scion/rains.cfg. Disabled if built with !norains.

type ResolverList

type ResolverList []Resolver

ResolverList represents a list of Resolvers that are processed in sequence to return the first match.

func (ResolverList) Resolve

func (resolvers ResolverList) Resolve(name string) (*snet.SCIONAddress, error)