kolo docsbeta

kolo-secure

Un canal cifrado y autenticado entre dos peers de Kolo, vinculado a sus claves de kolo-id.

En esta página

kolo-transport cifra una conexión QUIC con TLS 1.3, pero no dice quién está al otro lado. kolo-secure añade eso: después del handshake de QUIC, cada peer firma un valor del exportador TLS de la conexión (RFC 9846, sección 7.5), el channel binding de RFC 9266, con su clave de kolo-id bajo Ed25519ctx (RFC 8032), y una conexión solo se devuelve cuando la firma del peer es correcta. Solo añade la identidad; no decide en qué claves confiar.

Todos los pasos

El handshake

TLS 1.3 protege los bytes; los tres mensajes cortos prueban quién está en cada extremo.

  1. El dialer abre una conexión QUIC con TLS 1.3. El certificado es una clave desechable, no la identidad del peer: TLS por sí solo no prueba nada sobre quién está al otro lado.
  2. Los dos lados derivan el mismo valor de 32 bytes de la sesión TLS (un exporter). Alguien que reenviara desde el medio obtendría dos valores distintos.
  3. En un primer stream, el dialer envía Hello con su clave pública de kolo-id.
  4. El listener responde Proof: su clave pública y una firma Ed25519ctx sobre el valor del exporter y las dos claves.
  5. El dialer comprueba la clave que esperaba y la firma, y envía Finish, su propia firma. El listener la comprueba antes de aceptar la conexión.
  6. Protegido: el contenido y su integridad, y las dos claves. No se oculta: las direcciones IP, los puertos, los tamaños, el ritmo y las claves ante cualquiera que se conecte.

Instalación

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

Compila sin cgo.

Inicio rápido

Dos identidades nuevas en 127.0.0.1. El dialer exige la clave pública del listener, y el listener le devuelve un stream con lo que recibe.

main.go
package main

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

	koloid "github.com/ciranda-dev/kolo-id"
	kolosecure "github.com/ciranda-dev/kolo-secure"
)

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

	server, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	client, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}

	l, err := kolosecure.Listen(ctx, "127.0.0.1:0", server, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer l.Close()
	go func() {
		c, err := l.Accept(ctx)
		if err != nil {
			return
		}
		fmt.Printf("dialer is %x\n", c.RemotePublicKey())
		s, err := c.AcceptStream(ctx)
		if err != nil {
			return
		}
		io.Copy(s, s)
		s.Close()
	}()

	c, err := kolosecure.Dial(ctx, l.Addr().String(), client, server.PublicKey(), nil)
	if err != nil {
		log.Fatal(err)
	}
	defer c.Close()
	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 en hexadecimal la clave pública del dialer y hello kolo. Un nodo real carga su identidad con koloid.Load y obtiene la clave del peer al que se conecta del mismo sitio donde obtuvo la dirección.

Referencia de la API

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

Paquete kolosecure · github.com/ciranda-dev/kolo-secure · v0.1.0

Package kolosecure authenticates a kolo-transport connection with the kolo-id identities of both peers.

After the QUIC handshake, each side signs the connection's TLS exporter value (RFC 9846 section 7.5), its role and both public keys with its kolo-id key, and checks the peer's signature. A connection is returned only once the peer has proved it holds its key on this very connection, so a proof cannot be replayed on another connection, reflected, or relayed by a man in the middle.

Experimental: the API may change before v1.0.0.

Variables

var (
	// ErrInvalidConfig means a Config field is out of range.
	ErrInvalidConfig = errors.New("kolosecure: invalid config")
	// ErrInvalidArgument means a nil or zero identity, a nil transport listener, a bad remote key, or an address kolo-transport refuses.
	ErrInvalidArgument = errors.New("kolosecure: invalid argument")
	// ErrClosed means the listener is closed.
	ErrClosed = errors.New("kolosecure: closed")
	// ErrProtocol means a handshake message was malformed, truncated, too large or unexpected.
	ErrProtocol = errors.New("kolosecure: invalid handshake message")
	// ErrUnsupportedVersion means the peer speaks another handshake version.
	ErrUnsupportedVersion = errors.New("kolosecure: unsupported handshake version")
	// ErrUnexpectedPeer means the peer key is not the expected one, or is the local key.
	ErrUnexpectedPeer = errors.New("kolosecure: unexpected peer key")
	// ErrAuthentication means the peer's proof did not verify, or its key cannot be authenticated.
	ErrAuthentication = errors.New("kolosecure: peer authentication failed")
	// ErrTimeout means the handshake took longer than HandshakeTimeout.
	ErrTimeout = errors.New("kolosecure: handshake timeout")
)

Tipos

type Config

type Config struct {
	// Transport is passed to kolotransport.Listen or kolotransport.Dial; nil means its defaults. It must be nil for NewListener.
	Transport *kolotransport.Config
	// HandshakeTimeout bounds the kolo-secure handshake after the QUIC handshake. Default 10s, from 1s to 60s.
	HandshakeTimeout time.Duration
	// MaxPending caps the connections of a Listener that are handshaking or waiting for Accept. Listener only. Default 64, from 1 to 1000.
	MaxPending int
}

Config sets the limits of a Listener or a Dial. A zero field takes its default.

type Conn

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

Conn is a connection whose peer has proved it holds RemotePublicKey.

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

Dial connects to addr as id and returns once the listener has proved it holds remote. The listener checks the dialer's proof after Dial returns; if it rejects it, the connection closes with code 1.

func DialAny
func DialAny(ctx context.Context, addr string, id *koloid.Identity, cfg *Config) (*Conn, error)

DialAny is like Dial but accepts any listener key; check RemotePublicKey before trusting the connection.

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) AllowWindowGrowth
func (c *Conn) AllowWindowGrowth() bool

AllowWindowGrowth marks the connection as trusted for kolo-transport window growth, as kolotransport.Conn.AllowWindowGrowth. Call it once your own policy admits RemotePublicKey. It reports false when Config.Transport.WindowGrowth is off or the connection has ended.

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

Close closes the connection with code 0.

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

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

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

Context is canceled when the connection ends; its context.Cause is a kolo-transport error with no peer text.

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

LocalAddr returns the local UDP address.

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

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

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

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

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

RemoteAddr returns the peer's UDP address.

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

RemotePublicKey returns a copy of the peer's kolo-id public key.

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

Stats returns the connection's statistics as kolo-transport measures them, handshake and streams together. It is cheap, never blocks, is safe from any goroutine and is the zero value once the connection has ended.

type Listener

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

Listener accepts authenticated connections on one UDP socket.

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

Listen opens a kolo-transport listener on addr, such as "127.0.0.1:0", and authenticates each connection as id.

func NewListener
func NewListener(tl *kolotransport.Listener, id *koloid.Identity, cfg *Config) (*Listener, error)

NewListener authenticates the connections of tl as id; it owns tl and closes it, also when it fails. cfg.Transport must be nil, since tl is already configured.

func (Listener) Accept
func (l *Listener) Accept(ctx context.Context) (*Conn, error)

Accept waits for the next connection whose peer has proved its identity; failed handshakes are skipped.

func (Listener) Addr
func (l *Listener) Addr() net.Addr

Addr returns the local address of the listener.

func (Listener) Close
func (l *Listener) Close() error

Close stops accepting, ends pending handshakes and closes every connection of the listener, accepted or not. It is safe to call more than once.

func (Listener) Dial
func (l *Listener) Dial(ctx context.Context, addr netip.AddrPort, remote ed25519.PublicKey) (*Conn, error)

Dial connects to addr from the listener's socket (kolo-transport MaxDialed bounds these) and returns once the peer has proved it holds remote. remote is checked as in Dial, and the dialer's proof is checked by the peer after Dial returns.

Conviene saber

Límites

kolo-secure solo funciona con IPv4. Una dirección IPv6, incluida la forma v4-mapped, se rechaza con ErrInvalidArgument, que también coincide con el ErrInvalidArgument de kolo-transport. Los nombres de host solo se resuelven a IPv4, así que un nombre sin dirección IPv4 falla con un error de resolución.

Campos de Config (nil o cero significa el valor por defecto; fuera de rango es ErrInvalidConfig):

  • HandshakeTimeout: 10s para el handshake de kolo-secure después del de QUIC, de 1s a 60s. Por encima, Dial devuelve ErrTimeout y el listener descarta la conexión.
  • MaxPending: 64 conexiones por listener en handshake o a la espera de Accept, de 1 a 1000. Por encima, el listener cierra al instante cada conexión nueva con el código 1, y el dialer recibe kolotransport.ErrPeerClosed. El MaxConns de kolo-transport (100 por defecto) también cuenta estas conexiones.
  • Transport se pasa a kolo-transport sin cambios, con sus límites. Debe ser nil para NewListener.
  • Conn.AllowWindowGrowth llama a AllowWindowGrowth de kolo-transport sobre la conexión, aceptada, marcada o de Listener.Dial. Llámala cuando tu propia política admita al peer; ella no decide nada. Devuelve false cuando Transport.WindowGrowth está desactivado, que es el valor por defecto, o cuando la conexión ha terminado.
  • Conn.Stats devuelve el ConnStats de kolo-transport para la conexión, aceptada, marcada o de Listener.Dial: tiempos de ida y vuelta, bytes y paquetes, pérdidas, la ventana de congestión, el controlador de congestión y los cambios de camino (mira kolo-transport). Es la vista del transporte, así que el handshake y tus streams cuentan juntos, y kolo-secure no añade nada. Nunca se bloquea y es el valor cero una vez terminada la conexión.

Valores fijos:

  • Los mensajes del handshake tienen un cuerpo de 1 a 256 bytes, precedido de una longitud de dos bytes como mucho. Cualquier otra cosa es ErrProtocol. Cada mensaje real ocupa como máximo 98 bytes.
  • remote debe ser una clave de 32 bytes, que no sea la tuya ni un punto de orden pequeño; si no, Dial devuelve ErrInvalidArgument.
  • Un handshake fallido cierra la conexión con el código de error de aplicación 1.
  • Un peer que completa QUIC y luego no envía nada ocupa un hueco de MaxPending durante HandshakeTimeout. Con el MaxConnsPerIP de 4 de kolo-transport, hacen falta unas MaxPending / MaxConnsPerIP direcciones (16 con los valores por defecto) para llenar el listener, y volver a conectarse lo mantiene lleno.

Seguridad

  • Cada firma cubre la versión del protocolo, el rol de quien firma, el valor del exportador de 32 bytes y las dos claves públicas, bajo el contexto Ed25519ctx (RFC 8032) kolo-secure/proof/v0. Una prueba no se verifica en otra conexión, para el otro rol ni para otro par de peers. Se rechaza a un peer que presenta tu propia clave.
  • La etiqueta del exportador es EXPERIMENTAL-kolo-secure/channel-binding/v0. Un relay que empalma dos sesiones TLS obtiene dos valores sin relación, así que el handshake falla en los dos lados.
  • Las 14 codificaciones que Go decodifica a uno de los 8 puntos de orden pequeño se rechazan comparando bytes, antes de verificar ninguna firma.
  • Dial vuelve en cuanto el listener ha demostrado su clave y se ha enviado la prueba del dialer. Si el listener rechaza esa prueba, cierra la conexión y el dialer ve kolotransport.ErrPeerClosed con el código 1.
  • Los bytes que el peer envía por otros streams antes de comprobar su prueba solo llegan a la aplicación después de que Dial o Accept vuelvan.
  • El dialer envía su clave primero, así que quien sondee activamente la conoce, y conoce la clave del listener al conectarse. Los observadores pasivos no ven ninguna de las dos. Las direcciones, los tiempos y los tamaños son visibles.
  • No hay secreto hacia adelante ni renovación de claves más allá de TLS 1.3. Una clave de kolo-id robada permite al ladrón hacerse pasar por ese nodo en conexiones nuevas.
  • Los mensajes de error no incluyen nada que haya enviado el peer, salvo el código numérico de cierre o reinicio de QUIC que conserva kolo-transport.

Límites conocidos

  • Experimental. La API puede cambiar antes de v1.0.0.
  • La versión 0 solo acepta la versión 0. No hay negociación de versión.
  • Aquí solo se acota el handshake. Después, una conexión es una conexión normal de kolo-transport con sus límites.
  • Una aplicación que deja de llamar a Accept llena MaxPending, y entonces el listener rechaza a todo el mundo.
  • Después de NewListener, usa solo ReadPacket, WritePacket y Addr en el listener de kolo-transport. El listener de kolo-secure es su propietario y lo cierra.

Errores

ErrorMensaje
ErrAuthenticationkolosecure: peer authentication failed
ErrClosedkolosecure: closed
ErrInvalidArgumentkolosecure: invalid argument
ErrInvalidConfigkolosecure: invalid config
ErrProtocolkolosecure: invalid handshake message
ErrTimeoutkolosecure: handshake timeout
ErrUnexpectedPeerkolosecure: unexpected peer key
ErrUnsupportedVersionkolosecure: unsupported handshake version

Comprueba los errores con errors.Is. Una dirección que kolo-transport rechaza da el ErrInvalidArgument de kolo-secure envolviendo el de kolo-transport, así que coinciden los dos. Los demás errores de kolo-transport, como kolotransport.ErrPeerClosed, kolotransport.ErrHandshake o un kolotransport.ErrInvalidConfig por un Transport incorrecto, se transmiten sin cambios.

Referencias