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.
El handshake
TLS 1.3 protege los bytes; los tres mensajes cortos prueban quién está en cada extremo.
- 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.
- 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.
- En un primer stream, el dialer envía Hello con su clave pública de kolo-id.
- El listener responde Proof: su clave pública y una firma Ed25519ctx sobre el valor del exporter y las dos claves.
- 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.
- 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-secureCompila 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.
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.
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() boolAllowWindowGrowth 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() errorClose closes the connection with code 0.
func (Conn) CloseWithError
func (c *Conn) CloseWithError(code uint64, msg string) errorCloseWithError closes the connection, sending code and msg to the peer, as kolotransport.Conn.CloseWithError.
func (Conn) Context
func (c *Conn) Context() context.ContextContext 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.AddrLocalAddr 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.AddrRemoteAddr returns the peer's UDP address.
func (Conn) RemotePublicKey
func (c *Conn) RemotePublicKey() ed25519.PublicKeyRemotePublicKey returns a copy of the peer's kolo-id public key.
func (Conn) Stats
func (c *Conn) Stats() kolotransport.ConnStatsStats 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.AddrAddr returns the local address of the listener.
func (Listener) Close
func (l *Listener) Close() errorClose 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,DialdevuelveErrTimeouty el listener descarta la conexión.MaxPending: 64 conexiones por listener en handshake o a la espera deAccept, de 1 a 1000. Por encima, el listener cierra al instante cada conexión nueva con el código 1, y el dialer recibekolotransport.ErrPeerClosed. ElMaxConnsde kolo-transport (100 por defecto) también cuenta estas conexiones.Transportse pasa a kolo-transport sin cambios, con sus límites. Debe ser nil paraNewListener.Conn.AllowWindowGrowthllama aAllowWindowGrowthde kolo-transport sobre la conexión, aceptada, marcada o deListener.Dial. Llámala cuando tu propia política admita al peer; ella no decide nada. Devuelve false cuandoTransport.WindowGrowthestá desactivado, que es el valor por defecto, o cuando la conexión ha terminado.Conn.Statsdevuelve elConnStatsde kolo-transport para la conexión, aceptada, marcada o deListener.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. remotedebe ser una clave de 32 bytes, que no sea la tuya ni un punto de orden pequeño; si no,DialdevuelveErrInvalidArgument.- 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
MaxPendingduranteHandshakeTimeout. Con elMaxConnsPerIPde 4 de kolo-transport, hacen falta unasMaxPending/MaxConnsPerIPdirecciones (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.
Dialvuelve 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 vekolotransport.ErrPeerClosedcon 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
DialoAcceptvuelvan. - 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
AcceptllenaMaxPending, y entonces el listener rechaza a todo el mundo. - Después de
NewListener, usa soloReadPacket,WritePacketyAddren el listener de kolo-transport. El listener de kolo-secure es su propietario y lo cierra.
Errores
| Error | Mensaje |
|---|---|
ErrAuthentication | kolosecure: peer authentication failed |
ErrClosed | kolosecure: closed |
ErrInvalidArgument | kolosecure: invalid argument |
ErrInvalidConfig | kolosecure: invalid config |
ErrProtocol | kolosecure: invalid handshake message |
ErrTimeout | kolosecure: handshake timeout |
ErrUnexpectedPeer | kolosecure: unexpected peer key |
ErrUnsupportedVersion | kolosecure: 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
- RFC 9846, The Transport Layer Security (TLS) Protocol Version 1.3, sección 7.5, Exporters (Proposed Standard, July 2026; obsoletes RFC 8446).
- Toma: el valor del exportador TLS que firma cada lado.
- RFC 5705, Keying Material Exporters for TLS (Proposed Standard, March 2010).
- Toma: las etiquetas del exportador.
- RFC 9266, Channel Bindings for TLS 1.3 (Proposed Standard, July 2022).
- Toma: la idea del channel binding tls-exporter.
- No implementa: el tipo de channel binding tal como lo usan otros protocolos.
- RFC 8471, The Token Binding Protocol Version 1.0 (Proposed Standard, October 2018).
- Toma: la idea de firmar el material de claves exportado.
- No implementa: sus mensajes.
- RFC 9261, Exported Authenticators in TLS (Proposed Standard, July 2022).
- Toma: la idea de firmar el material de claves exportado.
- No implementa: sus mensajes.
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
- Toma: Ed25519ctx con el contexto
kolo-secure/proof/v0.
- Toma: Ed25519ctx con el contexto
- RFC 8827, WebRTC Security Architecture (Proposed Standard, January 2021).
- Toma: se lista por el modelo de amenazas.