kolo docsbeta

kolo-relay

Un relay opcional y autoalojado que une a dos peers de Kolo que no pueden conectarse directamente.

En esta página

kolo-relay permite que dos peers se conecten cuando ninguno puede llegar al otro, por ejemplo si los dos están detrás de un NAT simétrico o de un CGNAT, o detrás de un cortafuegos que solo deja salir tráfico. Un peer reserva una plaza en un relay con una dirección accesible; otro peer pide al relay la clave de ese peer, y el relay une a los dos y copia los bytes entre ellos, con asignaciones, duraciones y cuotas basadas en TURN (RFC 8656). Los dos peers mantienen de extremo a extremo una conexión normal de kolo-secure, así que el relay reenvía texto cifrado que no puede leer. Como la política relay de WebRTC, el relay está desactivado salvo que la aplicación lo active: nunca busca relays, nunca prueba antes un camino directo y nunca recurre por su cuenta a un relay. Consulta Relay.

Todos los pasos

Directo, o a través de un relay

El relay nunca es una alternativa silenciosa: lo elige tu app, por su dirección y su clave.

  1. Cuando hay camino directo, los peers se conectan directamente y ningún relay participa.
  2. El destino se conecta al relay con kolo-secure y envía Reserve. El relay mantiene la reserva hasta una hora.
  3. El iniciador se conecta al relay y envía Connect con la clave del destino.
  4. El relay avisa al destino con Incoming y la clave del iniciador. El destino acepta o rechaza, y el relay responde OK.
  5. El relay une los dos streams. Dentro de ellos los peers abren su propia conexión kolo-secure, de extremo a extremo, y el destino comprueba que es el iniciador anunciado.
  6. El relay no puede leer los paquetes. Conoce las dos claves, las dos direcciones, cuándo empieza y termina la sesión, y el tamaño y el ritmo de los paquetes. Cada sesión tiene límites: 1 hora, 1 GiB en cada sentido, 60 segundos sin actividad.

Instalación

go get github.com/ciranda-dev/kolo-relay

Compila sin cgo.

Inicio rápido

Este programa arranca un relay en loopback, reserva una plaza para un peer y se conecta a él desde otro peer a través del relay.

main.go
package main

import (
	"context"
	"fmt"
	"io"
	"log"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	kolorelay "github.com/ciranda-dev/kolo-relay"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	relayID, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	targetID, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	dialerID, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}

	relay, err := kolorelay.Listen(ctx, "127.0.0.1:0", relayID, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer relay.Close()
	addr, key := relay.Addr().String(), relayID.PublicKey()

	res, err := kolorelay.Reserve(ctx, addr, key, targetID, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Close()
	go func() {
		c, err := res.Accept(ctx)
		if err != nil {
			return
		}
		s, err := c.AcceptStream(ctx)
		if err != nil {
			return
		}
		io.Copy(s, s)
		s.Close()
	}()

	c, err := kolorelay.Dial(ctx, addr, key, dialerID, targetID.PublicKey(), nil)
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()
	fmt.Printf("connected to %x through relay %x\n", c.RemotePublicKey()[:4], c.RelayPublicKey()[:4])
	s, err := c.OpenStream(ctx)
	if err != nil {
		log.Fatal(err)
	}
	if _, err := s.Write([]byte("hello kolo")); err != nil {
		log.Fatal(err)
	}
	s.Close()
	reply, err := io.ReadAll(s)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%s\n", reply)
}

Imprime los primeros bytes de la clave del destino y de la clave del relay, y después hello kolo devuelto por el destino. En un despliegue real, el relay se ejecuta en un host con dirección pública y carga su identidad con koloid.Load; los peers obtienen su dirección y su clave de su propia configuración, y un destino indica a los demás, a través de la aplicación, en qué relay ha reservado.

Referencia de la API

La referencia de la API se genera a partir del código Go y está en inglés.

Paquete kolorelay · github.com/ciranda-dev/kolo-relay · v0.1.0

Package kolorelay lets two Kolo peers that cannot reach each other connect through a relay they chose.

The peers run a kolo-secure connection end to end; its packets travel inside streams of each peer's own connection to the relay, so the relay forwards ciphertext of a session it is not part of. Using a relay is always an explicit choice of the application.

Experimental: the API may change before v1.0.0.

Variables

var (
	// ErrInvalidConfig means a Config or ServerConfig field is out of range, or a kolo-transport Network in it is not "udp4".
	ErrInvalidConfig = errors.New("kolorelay: invalid config")
	// ErrInvalidArgument means a nil or zero identity, an IPv6 address (v4-mapped included),
	// or a target key that is not 32 bytes or is the local or the relay's key.
	ErrInvalidArgument = errors.New("kolorelay: invalid argument")
	// ErrClosed means the Server or Reservation is closed.
	ErrClosed = errors.New("kolorelay: closed")
	// ErrProtocol means a relay message was malformed, truncated, too large or unexpected.
	ErrProtocol = wire.ErrProtocol
	// ErrUnsupportedVersion means the other side speaks another kolo-relay version.
	ErrUnsupportedVersion = wire.ErrUnsupportedVersion
	// ErrUnavailable means the target cannot be reached through the relay: no reservation,
	// MaxSessionsPerTarget sessions, or the relay or the target refused.
	ErrUnavailable = errors.New("kolorelay: target unavailable through the relay")
	// ErrNotAllowed means the relay does not let this key reserve.
	ErrNotAllowed = errors.New("kolorelay: not allowed by the relay")
	// ErrLimit means MaxReservations, MaxSessions or MaxSessionsPerPeer was reached; trying later may work.
	ErrLimit = limits.ErrLimit
	// ErrReservationEnded means the reservation ended: its lifetime passed, the key reserved again,
	// the relay closed, or the connection was lost.
	ErrReservationEnded = errors.New("kolorelay: reservation ended")
)

Tipos

type Config

type Config struct {
	// Relay configures the connection to the relay. Nil means kolo-secure's defaults with a 5s keep-alive; a non-nil value is used as given.
	Relay *kolosecure.Config
	// Peer configures the end-to-end connection. Nil means the defaults; kolorelay sets the listener-only transport fields.
	Peer *kolosecure.Config
	// ControlTimeout bounds each exchange with the relay and the wait for a relayed peer's handshake.
	// Default 20s, 5s above the relay's default ConnectTimeout; from 1s to 60s.
	ControlTimeout time.Duration
	// MaxPending caps the incoming sessions not yet returned by Accept. Default 16, from 1 to 256.
	MaxPending int
	// SendQueue is how many packets a session queues before it drops the oldest. Default 512, from 8 to 1024.
	SendQueue int
	// AllowFunc says whether an initiator may reach this reservation. Nil allows every key; a panic refuses.
	AllowFunc func(initiator ed25519.PublicKey) bool
}

Config sets the limits of a peer that reserves on a relay or dials through one. A zero field takes its default.

type Conn

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

Conn is a connection to a peer through a relay; the peer proved RemotePublicKey end to end, and the relay only sees ciphertext.

func Dial
func Dial(ctx context.Context, relayAddr string, relayKey ed25519.PublicKey, id *koloid.Identity, target ed25519.PublicKey, cfg *Config) (*Conn, error)

Dial connects to target through the relay at relayAddr, whose key is relayKey, and returns once target has proved its key end to end. The relay must hold a reservation for target. Nothing is tried directly: the connection always goes through the relay.

func (Conn) AcceptStream
func (c *Conn) AcceptStream(ctx context.Context) (*kolotransport.Stream, error)

AcceptStream waits for the next bidirectional stream opened by the peer.

func (Conn) AcceptUniStream
func (c *Conn) AcceptUniStream(ctx context.Context) (*kolotransport.ReceiveStream, error)

AcceptUniStream waits for the next unidirectional stream opened by the peer.

func (Conn) Close
func (c *Conn) Close() error

Close closes the connection with code 0 and releases its resources.

func (Conn) CloseWithError
func (c *Conn) CloseWithError(code uint64, msg string) error

CloseWithError closes the connection, sending code and msg to the peer, as kolosecure.Conn.CloseWithError.

func (Conn) Context
func (c *Conn) Context() context.Context

Context is canceled when the connection ends, also when the relay ends the session; its context.Cause is a kolo-transport error.

func (Conn) OpenStream
func (c *Conn) OpenStream(ctx context.Context) (*kolotransport.Stream, error)

OpenStream opens a bidirectional stream, as kolosecure.Conn.OpenStream.

func (Conn) OpenUniStream
func (c *Conn) OpenUniStream(ctx context.Context) (*kolotransport.SendStream, error)

OpenUniStream opens a unidirectional stream, as kolosecure.Conn.OpenUniStream.

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

RelayAddr returns the UDP address of the relay this connection goes through.

func (Conn) RelayPublicKey
func (c *Conn) RelayPublicKey() ed25519.PublicKey

RelayPublicKey returns a copy of the key of the relay this connection goes through.

func (Conn) RemotePublicKey
func (c *Conn) RemotePublicKey() ed25519.PublicKey

RemotePublicKey returns a copy of the peer's kolo-id public key, proved end to end.

func (Conn) Stats
func (c *Conn) Stats() kolotransport.ConnStats

Stats returns the transport statistics of the end-to-end connection, which crosses the relay: its round trip time is the whole path. It is the zero value after the connection has ended.

type Reservation

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

Reservation makes this peer reachable through one relay and receives the connections other peers make to it there.

func Reserve
func Reserve(ctx context.Context, relayAddr string, relayKey ed25519.PublicKey, id *koloid.Identity, cfg *Config) (*Reservation, error)

Reserve asks the relay at relayAddr, whose key is relayKey, to make id reachable there until the relay ends the reservation or Close.

func (Reservation) Accept
func (r *Reservation) Accept(ctx context.Context) (*Conn, error)

Accept waits for the next peer that connected through the relay and proved its key end to end. After the relay ends the reservation it returns an error wrapping ErrReservationEnded; connections already returned keep working.

func (Reservation) Close
func (r *Reservation) Close() error

Close ends the reservation and closes its connection to the relay, with every connection Accept returned. It is safe to call more than once.

type Server

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

Server is a relay: peers reserve on it, and it joins other peers to them, copying bytes it cannot read.

func Listen
func Listen(ctx context.Context, addr string, id *koloid.Identity, cfg *ServerConfig) (*Server, error)

Listen starts a relay on addr, such as "127.0.0.1:0", authenticated as id. Clients must know id's public key.

func (Server) Addr
func (s *Server) Addr() net.Addr

Addr returns the relay's local UDP address.

func (Server) Close
func (s *Server) Close() error

Close ends every session and reservation, closes every connection and waits for them. It is safe to call more than once.

type ServerConfig

type ServerConfig struct {
	// Secure configures the relay's listener. Nil means the relay defaults in the README; a non-nil value is used as given.
	Secure *kolosecure.Config
	// MaxReservations caps the reserved keys. Default 64, from 1 to 100000.
	MaxReservations int
	// MaxSessions caps the sessions being set up or open. Default 16, from 1 to 10000.
	MaxSessions int
	// MaxSessionsPerPeer caps the sessions one key has started. Default 4 or MaxSessions if lower, at most MaxSessions.
	MaxSessionsPerPeer int
	// MaxSessionsPerTarget caps the sessions to one reserved key; beyond it the relay answers Unavailable.
	// Default 8 or MaxSessions if lower, at most MaxSessions.
	MaxSessionsPerTarget int
	// ReservationLifetime ends a reservation; the peer must reserve again. Default 1h, from 1s to 24h.
	ReservationLifetime time.Duration
	// MaxSessionDuration ends a session. Default 1h, from 1s to 24h.
	MaxSessionDuration time.Duration
	// MaxSessionBytes ends a session once this many bytes went one way. Default 1 GiB, from 64 KiB to 1 TiB.
	MaxSessionBytes int64
	// SessionIdleTimeout ends a session with no byte either way. Default 60s, from 1s to 10m.
	// Keep-alive is always on, so it ends a session between live peers only if it is not above their KeepAlivePeriod (5s by default).
	SessionIdleTimeout time.Duration
	// ConnectTimeout bounds how long the target may take to accept a session. Default 15s, from 1s to 60s.
	// Default clients wait 20s for the answer, so above about 15s they need a longer ControlTimeout.
	ConnectTimeout time.Duration
	// ControlTimeout bounds how long a client may take to send its first message. Default 15s, from 1s to 60s.
	ControlTimeout time.Duration
	// RateBytes is the read rate per client connection, in bytes per second. Default 1 MiB, from 16 KiB to 1 GiB.
	RateBytes int64
	// RateBurst is the most a client connection may send at once above RateBytes. Default 256 KiB, from 16 KiB to 64 MiB.
	RateBurst int64
	// FlushInterval is the shortest time between two writes of less than a full buffer in one direction of a session.
	// Default 1ms, from 100µs to 100ms.
	FlushInterval time.Duration
	// AllowReserve says whether a key may reserve. Nil allows every key, which Listen reports with a warning; a panic refuses.
	AllowReserve func(key ed25519.PublicKey) bool
	// AllowConnect says whether from may reach to. Nil allows every pair; a panic refuses.
	// It must be fast: Server.Close waits for calls in progress.
	AllowConnect func(from, to ed25519.PublicKey) bool
	// Logger receives the warning Listen logs when AllowReserve is nil. Nil means slog.Default().
	Logger *slog.Logger
}

ServerConfig sets the limits of a relay. A zero field takes its default.

Conviene saber

Conn.Stats devuelve las estadísticas de kolo-transport de la conexión de extremo a extremo que cruza el relay: el tiempo de ida y vuelta de todo el camino, las pérdidas, la ventana de congestión y el controlador. Es el valor cero una vez terminada la conexión.

Límites

Los valores por defecto sirven para una prueba en un host con unos 8 GiB y dejan el relay abierto a cualquier clave. Antes de exponer un relay, define AllowReserve y ajusta MaxConns, las ventanas de recepción y MaxSessions a tu host; la página de límites del repositorio tiene la receta para un host de 300 MiB.

  • Solo IPv4. Una dirección IPv6 pasada a Listen, Reserve o Dial, incluida la v4-mapped, es ErrInvalidArgument antes de enviar nada. Un Network de kolo-transport distinto de "udp4" en Config o ServerConfig es ErrInvalidConfig.
  • ServerConfig (un campo a cero toma el valor por defecto; fuera de rango es ErrInvalidConfig):
    • MaxReservations: 64, de 1 a 100000. Por encima, Reserve recibe ErrLimit.
    • MaxSessions (en preparación o abiertas): 16, de 1 a 10000. Por encima, ErrLimit.
    • MaxSessionsPerPeer (iniciadas por una misma clave): 4, o MaxSessions si es menor. Por encima, ErrLimit.
    • MaxSessionsPerTarget (hacia una misma clave reservada): 8, o MaxSessions si es menor. Por encima, ErrUnavailable.
    • ReservationLifetime: 1h, de 1s a 24h. Después, la reserva termina y el peer tiene que volver a reservar; las sesiones que ya lleva siguen adelante.
    • MaxSessionDuration: 1h, de 1s a 24h.
    • MaxSessionBytes (en cada sentido): 1 GiB, de 64 KiB a 1 TiB. Pasan exactamente esos bytes y después termina la sesión entera.
    • SessionIdleTimeout (ningún byte en ningún sentido): 60s, de 1s a 10m. El keep-alive siempre está activo (5s por defecto), así que una sesión entre dos peers vivos no llega a un tiempo de espera mayor que su KeepAlivePeriod.
    • ConnectTimeout (el destino acepta una sesión): 15s, de 1s a 60s. Por encima de unos 15s, los clientes necesitan un ControlTimeout mayor que sus 20s por defecto.
    • ControlTimeout (primer mensaje del cliente): 15s, de 1s a 60s.
    • RateBytes (leídos de cada conexión de cliente, por segundo): 1 MiB, de 16 KiB a 1 GiB.
    • RateBurst: 256 KiB, de 16 KiB a 64 MiB.
    • FlushInterval: 1ms, de 100µs a 100ms.
    • Logger: nil quiere decir slog.Default(). Recibe el único aviso de un relay abierto.
  • Con Secure a nil, el relay escucha con MaxConns 128, MaxConnsPerIP 4, MaxDialed 1, MaxIncomingStreams 2, MaxStreamReceiveWindow 64 KiB y MaxConnReceiveWindow 256 KiB. Un Secure distinto de nil se usa tal cual, sin estos valores.
  • Cada sesión necesita su propia conexión de cliente, así que una dirección de origen tiene como mucho MaxConnsPerIP sesiones.
  • Config (para Reserve y Dial; un campo a cero toma el valor por defecto; fuera de rango es ErrInvalidConfig):
    • Relay: nil significa los valores por defecto de kolo-secure con un KeepAlivePeriod de 5s.
    • ControlTimeout (cada intercambio con el relay): 20s, de 1s a 60s. Un relay que no responde a tiempo da un error que envuelve os.ErrDeadlineExceeded.
    • MaxPending (sesiones que Accept aún no ha devuelto): 16, de 1 a 256.
    • SendQueue (paquetes en cola por sesión): 512, de 8 a 1024. Cuando se llena, se descarta el paquete más antiguo, como en UDP.
  • Un HandshakeTimeout a cero en Peer es 10s. Un destino espera a un peer anunciado como mucho ControlTimeout más los dos tiempos de handshake (40s con los valores por defecto) y después libera la plaza.
  • Tamaños fijos: un mensaje de control ocupa como máximo 64 bytes, una trama de paquete como máximo 1452 bytes, y el búfer de copia del relay es de 64 KiB por sentido. Los paquetes internos se quedan en 1280 bytes, porque el descubrimiento de MTU de ruta está desactivado en el camino a través del relay.
  • Reservation.Close y Conn.Close pueden tardar unos 2s: el último paquete tiene como mucho 1s para salir, y después el otro lado tiene como mucho 1s para terminar su stream. Cuando el relay termina una sesión, el Conn de cada lado se cierra en 1s aproximadamente.
  • Server.Close da a cada iniciador hasta 1s para cerrar su conexión y después termina todas las reservas.
  • Rendimiento con los valores por defecto: la ventana de stream de 64 KiB limita una sesión a 64 KiB por ida y vuelta en cada sentido, RateBytes limita cada conexión de cliente a 1 MiB/s, y la salida del relay es como mucho 2 × MaxSessions × RateBytes, 32 MiB/s. Solo hay tests en loopback.
  • Memoria: el peor caso de heap vivo del relay con los valores por defecto es de unos 7,3 GiB (7.506,8 MiB). Pon GOMEMLIMIT un poco por encima del límite de tu configuración, por ejemplo GOMEMLIMIT=8500MiB con los valores por defecto. En un host pequeño, baja MaxSessions y los límites del listener a través de Secure, y vuelve a calcular con la fórmula del README. Una conexión cuyo extremo eligió CongestionControl: "bbr" añade hasta 5,5 MiB de muestras de BBR, un término que la fórmula omite; el listener propio del relay usa Reno salvo que su Secure diga otra cosa.

Seguridad

  • El relay no es un extremo TLS de la conexión entre los peers. No puede leer ni cambiar los paquetes internos, y no puede hacerse pasar por ninguno de los dos peers. Siempre puede descartarlos, retrasarlos o terminarlos.
  • El relay conoce las dos claves de cada sesión, las direcciones de los dos clientes, qué claves tienen reservas, cuándo empiezan y terminan las sesiones, y los tamaños y tiempos de los paquetes internos.
  • El relay nunca se conecta a nadie y solo une a dos de sus propios clientes autenticados, hacia una clave que ha reservado, así que no es un proxy abierto.
  • Solo quien tiene una clave puede reservarla. Una reserva más reciente de la misma clave sustituye a la anterior.
  • Dial solo vuelve cuando target ha demostrado su clave de extremo a extremo. Un destino que recibe un peer cuya clave demostrada no es la que anunció el relay cierra esa conexión con el código 1 y nunca la devuelve.
  • Una clave de cliente o de destino que no tiene 32 bytes termina la conexión con el código 1.
  • Un pánico en AllowReserve, AllowConnect o AllowFunc rechaza. AllowConnect tiene que ser rápido: Server.Close espera a las llamadas en curso.
  • ErrUnavailable es a propósito una misma respuesta para varias causas. Una clave todavía puede conocer su propia decisión de AllowConnect y si un destino está reservado, pero nada sobre otras claves.
  • Ningún error lleva nada que hayan enviado el peer o el relay, salvo códigos numéricos.

Límites conocidos

  • Accept no vuelve a reservar después de que el relay termine una reserva. Llama a Close después de que Accept falle y luego vuelve a llamar a Reserve.
  • Conn no tiene RemoteAddr: la única dirección del camino es la del relay (RelayAddr).
  • Cada paquete se cifra dos veces y pasa por dos controles de flujo (hacia el relay y de extremo a extremo), y los dos limitan el rendimiento. No se ha medido el rendimiento en redes reales.
  • El relay es experimental. La API puede cambiar antes de v1.0.0.

Errores

ErrorMensaje
ErrClosedkolorelay: closed
ErrInvalidArgumentkolorelay: invalid argument
ErrInvalidConfigkolorelay: invalid config
ErrLimitkolorelay: relay limit reached
ErrNotAllowedkolorelay: not allowed by the relay
ErrProtocolkolorelay: invalid message
ErrReservationEndedkolorelay: reservation ended
ErrUnavailablekolorelay: target unavailable through the relay
ErrUnsupportedVersionkolorelay: unsupported protocol version

Comprueba los errores con errors.Is. El error de Accept después de que el relay termine una reserva envuelve a la vez ErrReservationEnded y el error de kolo-transport con el código del relay (2 fin de la vida útil, 3 sustituida, 4 relay cerrándose). Los errores de kolo-secure y kolo-transport se transmiten, por ejemplo kolosecure.ErrUnexpectedPeer cuando el relay no tiene relayKey.

Referencias