ytl

README

Ytl

Yggdrasil Transports Lib

Documentation

Overview

Package ytl provides top-level logic for working with Yggdrasil network transport connections.

Although the package provides access to low-level primitives, but most clients will need only the basic interface provided by the ConnManager, ProxyManager, DeduplicationManager, YggConn and YggListener types.

In the basic case, to get started, you need to create a ConnManager object.

manager := ytl.NewConnManager(
	context.Background(), // Or your context here
	nil,
	nil,
	nil,
	nil,
)

If you want to use a specific private and public key pair, you need to pass your private key to the ConnManager constructor. If key is not passed, a new random key will be generated for each connection.

_, priv, _ := ed25519.GenerateKey(nil)
manager := ytl.NewConnManager(
	context.Background(),
	priv, // Pass your ygg private key here
	nil,
	nil,
	nil,
)

If you want to enable connetions deduplication ( aka restriction for more than one connection to each node), you need to pass DeduplicationManager object with those params to ConnManager constructor.

( See more info in DeduplicationManager type documentation. )

manager := ytl.NewConnManager(
	context.Background(),
	nil,
	nil,
	ytl.NewDeduplicationManager(true, nil),
	nil,
)

If you want to allow only subset of nodes to strait connections, you need to pass slice of there public keys to ConnManager constructor.

pub1, _, _ := ed25519.GenerateKey(nil)
pub2, _, _ := ed25519.GenerateKey(nil)
pub3, _, _ := ed25519.GenerateKey(nil)
manager := ytl.NewConnManager(
	context.Background(),
	nil,
	nil,
	nil,
	ytl.static.AllowList[]{
		pub1,
		pub2,
		pub3,
	},
)

If you want to proxify connections to certain hosts via socks proxy, you need to pass the ProxyManager object with the appropriate rules to the ConnManager constructor.

( See more info in ProxyManager type documentation. )

torProxy, _ := url.Parse("socks://localhost:9050")
i2pProxy, _ := url.Parse("socks://localhost:9060")
manager := ytl.NewConnManager(
	context.Background(),
	nil,
	ytl.NewProxyManager(
		nil, // Default proxy here or nil
		[]ytl.ProxyMapping{
			{
				// Proxify rule for tor nodes
				HostRegexp: *regexp.MustCompile(`\.onion$`),
				Proxy:      torProxy,
			},
			{
				// Proxify rule for i2p nodes
				HostRegexp: *regexp.MustCompile(`\.i2p$`),
				Proxy:      i2pProxy,
			},
		},
	),
	nil,
	nil,
)

After you have created the ConnManager object, you can use it to open outgoing connections with the Connect method ( ConnectCtx and ConnectTimeout methods are also available ).

addr, _ := url.Parse("tcp://0.0.0.0:1337")
conn, err := manager.Connect(addr)
if err != nil { panic(err) }

Returned YggConn object has interface similar to net.Conn but with extra methods. So it can be used wherever net.Conn is used.

If you want to listen incoming connections you need to use ConnManager.Listen method

addr, _ := url.Parse("tcp://127.0.0.1:1337")
listener, err := manager.Listen(addr)
if err != nil { panic(err) }
for {
	conn, err := listener.Accept()
	if err != nil {
		// Handle error
	}
}

Index

• func KeyFromOptionalKey(key ed25519.PrivateKey) ed25519.PrivateKey
• type ConnManager
  • func NewConnManager(ctx context.Context, key ed25519.PrivateKey, proxy *ProxyManager, ...) *ConnManager
  • func NewConnManagerWithTransports(ctx context.Context, key ed25519.PrivateKey, proxy *ProxyManager, ...) *ConnManager
  • func (c *ConnManager) Connect(uri url.URL) (*YggConn, error)
  • func (c *ConnManager) ConnectCtx(ctx context.Context, uri url.URL) (*YggConn, error)
  • func (c *ConnManager) ConnectTimeout(uri url.URL, timeout time.Duration) (*YggConn, error)
  • func (c *ConnManager) Listen(uri url.URL) (ygg YggListener, err error)
• type DeduplicationManager
  • func NewDeduplicationManager(secureMode bool, blockKey ed25519.PublicKey) *DeduplicationManager
  • func (d *DeduplicationManager) Check(key ed25519.PublicKey, isSecure uint, closeMethod func()) func()
• type ProxyManager
  • func NewProxyManager(defaultProxy *url.URL, mapping []ProxyMapping) ProxyManager
  • func (p *ProxyManager) Get(uri url.URL) *url.URL
• type ProxyMapping
• type YggConn
  • func ConnToYggConn(conn net.Conn, transport_key ed25519.PublicKey, allow *static.AllowList, ...) *YggConn
  • func (y *YggConn) Close() (err error)
  • func (y *YggConn) GetPublicKey() (ed25519.PublicKey, error)
  • func (y *YggConn) GetVer() (*static.ProtoVersion, error)
  • func (y *YggConn) LocalAddr() net.Addr
  • func (y *YggConn) Read(b []byte) (n int, err error)
  • func (y *YggConn) RemoteAddr() net.Addr
  • func (y *YggConn) SetDeadline(t time.Time) (err error)
  • func (y *YggConn) SetReadDeadline(t time.Time) (err error)
  • func (y *YggConn) SetWriteDeadline(t time.Time) (err error)
  • func (y *YggConn) Write(b []byte) (n int, err error)
• type YggListener
  • func (y *YggListener) Accept() (ygg YggConn, err error)
  • func (y *YggListener) Addr() net.Addr
  • func (y *YggListener) Close() error

Functions

func KeyFromOptionalKey

func KeyFromOptionalKey(key ed25519.PrivateKey) ed25519.PrivateKey

If key is not nil, retruns it as is. If key is nil, generate new random key.

Types

type ConnManager

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

Incapsulate list of transport realisations and other lower level managers. Manage opening & auto-closing connections, keys, proxys & dedupliaction.

func NewConnManager

func NewConnManager(
	ctx context.Context,
	key ed25519.PrivateKey,
	proxy *ProxyManager,
	dm *DeduplicationManager,
	allowList *static.AllowList,
) *ConnManager

Create new ConnManager with default transports list.

Key can be nill.

func NewConnManagerWithTransports

func NewConnManagerWithTransports(
	ctx context.Context,
	key ed25519.PrivateKey,
	proxy *ProxyManager,
	dm *DeduplicationManager,
	allowList *static.AllowList,
	transports []static.Transport,
) *ConnManager

Create new ConnManager with custom transports list.

Key can be nill.

func (*ConnManager) Connect

func (c *ConnManager) Connect(uri url.URL) (*YggConn, error)

Selects the appropriate transport implementation based on the uri scheme and opens the connection.

If ConnManager was constructed with non nil ProxyManager, it will be used to selection proxy based on uri host.

If ConnManager was constructed with non nil private key, it will pass to transport implementation. Otherwise new random key will be used for each call.

If ConnManager was constructed with non nil DeduplicationManager, it will be used to close duplicate connections on early stage.

func (*ConnManager) ConnectCtx

func (c *ConnManager) ConnectCtx(ctx context.Context, uri url.URL) (*YggConn, error)

Selects the appropriate transport implementation based on the uri scheme and opens the connection.

If ConnManager was constructed with non nil ProxyManager, it will be used to selection proxy based on uri host.

If ConnManager was constructed with non nil private key, it will pass to transport implementation. Otherwise new random key will be used for each call.

If ConnManager was constructed with non nil DeduplicationManager, it will be used to close duplicate connections on early stage.

It also accepts a context that allows you to cancel the process ahead of time.

func (*ConnManager) ConnectTimeout

func (c *ConnManager) ConnectTimeout(uri url.URL, timeout time.Duration) (*YggConn, error)

Selects the appropriate transport implementation based on the uri scheme and opens the connection.

If ConnManager was constructed with non nil ProxyManager, it will be used to selection proxy based on uri host.

If ConnManager was constructed with non nil private key, it will pass to transport implementation. Otherwise new random key will be used for each call.

If ConnManager was constructed with non nil DeduplicationManager, it will be used to close duplicate connections on early stage.

It also accepts a timeout param. After timeout expires, the connection process will be canceled.

func (*ConnManager) Listen

func (c *ConnManager) Listen(uri url.URL) (ygg YggListener, err error)

Selects the appropriate transport implementation based on the uri scheme and create listener object that accpet incoming connections.

type DeduplicationManager

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

Stores info about all active connections. Call callback if one of them need to be closed.

func NewDeduplicationManager

func NewDeduplicationManager(secureMode bool, blockKey ed25519.PublicKey) *DeduplicationManager

If secureMode is disabled all new duplicated connections will closed immediately. Otherwise from group of duplicated connections will select one with higher SecurityLvl param, and other will be closed.

Any connection with blockKey will be closed anyway. This param may be used to prevent node connect to itself.

func (*DeduplicationManager) Check

func (d *DeduplicationManager) Check(key ed25519.PublicKey, isSecure uint, closeMethod func()) func()

Accept public key of connected node, security lvl of connection and callback function that will be called when DeduplicationManager decied to close current connection.

Check if new connection is duplicate. If it is not, returns callback that this connection MUST call on close. If it is duplicate and if it must be closed returns nill.

type ProxyManager

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

Stores ProxyMappings and match URLs to proxy

func NewProxyManager

func NewProxyManager(defaultProxy *url.URL, mapping []ProxyMapping) ProxyManager

func (*ProxyManager) Get

func (p *ProxyManager) Get(uri url.URL) *url.URL

Retruns proxy matched to URI by it host

type ProxyMapping

type ProxyMapping struct {
	// RegExp for host matching
	HostRegexp regexp.Regexp
	// Proxy (may be nil)
	Proxy *url.URL
}

ProxyMapping is a representation of the correspondence between hosts that fall under the regular expression and proxy that should be used to connect to these hosts.

type YggConn

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

Wraper that represents connection with other yggdrasil node.

Incapsulate analysing handshake pkg and communicate with DeduplicationManager.

func ConnToYggConn

func ConnToYggConn(conn net.Conn, transport_key ed25519.PublicKey, allow *static.AllowList, secureTranport uint, dm *DeduplicationManager) *YggConn

Wraps regular net connection to YggConn.

Accepts optinal transport key, list of allowded nodes, security lvl of connection and optional DeduplicationManager.

If connection has key different transport key or has key that does not contatain in allow list or duplicates oter connection with the same node, it will be closed. Otherwise, it will be available as a normal connection.

func (*YggConn) Close

func (y *YggConn) Close() (err error)

func (*YggConn) GetPublicKey

func (y *YggConn) GetPublicKey() (ed25519.PublicKey, error)

Returns public key of of connected node if handshake pkg was successfully received and parsed.

func (*YggConn) GetVer

func (y *YggConn) GetVer() (*static.ProtoVersion, error)

Returns version of yggdrasil protocol using for this connection if handshake pkg was successfully received and parsed.

func (*YggConn) LocalAddr

func (y *YggConn) LocalAddr() net.Addr

func (*YggConn) Read

func (y *YggConn) Read(b []byte) (n int, err error)

func (*YggConn) RemoteAddr

func (y *YggConn) RemoteAddr() net.Addr

func (*YggConn) SetDeadline

func (y *YggConn) SetDeadline(t time.Time) (err error)

func (*YggConn) SetReadDeadline

func (y *YggConn) SetReadDeadline(t time.Time) (err error)

func (*YggConn) SetWriteDeadline

func (y *YggConn) SetWriteDeadline(t time.Time) (err error)

func (*YggConn) Write

func (y *YggConn) Write(b []byte) (n int, err error)

type YggListener

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

Allows accepting incoming connections

func (*YggListener) Accept

func (y *YggListener) Accept() (ygg YggConn, err error)

Accept waits for and returns the next connection to the listener.

func (*YggListener) Addr

func (y *YggListener) Addr() net.Addr

Addr returns the listener's network address.

func (*YggListener) Close

func (y *YggListener) Close() error

Close closes the listener. Any blocked Accept operations will be unblocked and return errors.