kolo-dht es una DHT Kademlia, reforzada según S/Kademlia, que funciona sobre el mismo socket UDP que el listener QUIC de kolo-transport del nodo. Un peer anuncia un topic de 32 bytes con un registro firmado con su clave de kolo-id. Otro peer busca el topic, el servidor que guardó el registro coordina una perforación de NAT (hole punching) como describe el RFC 5128, probada con los comportamientos de NAT del RFC 4787, y quien llama obtiene una conexión de kolo-secure fijada a la clave anunciada. Nada retransmite los datos de la aplicación.
Un lookup, paso a paso
Este ejemplo usa IDs de 8 bits. Los IDs reales tienen 256 bits, la tabla guarda 20 servidores por bucket y van hasta 10 consultas a la vez.
- Tu tabla de rutas da los servidores que conoce más cercanos al topic: aquí A, B y C. La distancia es el XOR de los dos IDs.
- Envías LOOKUP a todos a la vez. Cada respuesta trae servidores más cercanos al topic, un token y los registros que haya.
- C conoce a D y a E, que están más cerca. Les preguntas en cuanto llega la respuesta: no hay rondas fijas.
- E conoce a F y a G, más cerca todavía. La lista se ordena por distancia tras cada respuesta.
- La búsqueda para cuando los 20 servidores más cercanos que conoce han respondido o han agotado su tiempo, o tras 100 consultas. Cada registro lo firma el peer que lo anunció, y la firma se comprueba.
- Un lookup devuelve registros, no conexiones. Connect es una llamada aparte, a través de un servidor que guardó el registro.
Conectar a través de dos NAT
Los dos peers están detrás de routers domésticos. Un nodo bootstrap en internet los pone en contacto; después los paquetes van directos.
- A y B anuncian cada uno un registro firmado del topic a un nodo bootstrap, cada uno desde detrás de su propio NAT.
- A busca el topic. La respuesta trae el registro firmado de B, con su clave pública y su dirección, y el nodo que lo guardó.
- A envía CONNECT a ese nodo, que pasa la petición a B. Ninguno alcanza todavía al otro: los dos NAT solo dejan entrar respuestas.
- Los dos se envían paquetes PUNCH a la vez. Cada NAT ve salir el paquete de su propio peer y abre un mapeo, así que deja entrar los del otro.
- El camino directo queda abierto: los paquetes van entre A y B sin pasar por el nodo. Después kolo-secure prueba las dos claves en la conexión.
Instalación
go get github.com/ciranda-dev/kolo-dhtCompila sin cgo.
Config.Trace es un callback para cada sonda de punch enviada y recibida, los sockets de un birthday punch y cada dirección comprobada. Config tiene este campo de tipo función, así que no se puede comparar con ==: usa reflect.DeepEqual.
Inicio rápido
Un servidor y dos peers en loopback: bob anuncia un topic, alice lo encuentra, se conecta y recibe de vuelta su mensaje.
package main
import (
"context"
"crypto/sha256"
"fmt"
"io"
"log"
"net"
"net/netip"
"time"
kolodht "github.com/ciranda-dev/kolo-dht"
koloid "github.com/ciranda-dev/kolo-id"
)
func node(ctx context.Context, server bool) *kolodht.Node {
id, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
n, err := kolodht.New(ctx, "127.0.0.1:0", id, &kolodht.Config{Server: server})
if err != nil {
log.Fatal(err)
}
return n
}
func addr(n *kolodht.Node) netip.AddrPort { return n.Addr().(*net.UDPAddr).AddrPort() }
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
server := node(ctx, true)
defer server.Close()
alice, bob := node(ctx, false), node(ctx, false)
defer alice.Close()
defer bob.Close()
for _, n := range []*kolodht.Node{alice, bob} {
if err := n.Bootstrap(ctx, []netip.AddrPort{addr(server)}); err != nil {
log.Fatal(err)
}
}
topic := kolodht.Topic(sha256.Sum256([]byte("kolo example topic")))
if err := bob.Announce(ctx, topic); err != nil {
log.Fatal(err)
}
go func() {
c, err := bob.Accept(ctx)
if err != nil {
return
}
s, err := c.AcceptStream(ctx)
if err != nil {
return
}
io.Copy(s, s)
s.Close()
}()
peers, err := alice.Lookup(ctx, topic)
if err != nil || len(peers) == 0 {
log.Fatalf("lookup: %d peers, %v", len(peers), err)
}
c, err := alice.Connect(ctx, peers[0])
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 from %x\n", reply, c.RemotePublicKey())
}Imprime hello kolo from y la clave pública de bob en hexadecimal. Sin lista, Bootstrap(ctx, nil) entra en la red pública a través de los nodos de entrada incluidos en la librería; consulta Redes públicas y privadas. Para mantener tu propia red, ejecuta unos cuantos nodos con Config.Server en direcciones públicas, como kolo-node, y pasa sus direcciones a Bootstrap.
Referencia de la API
La referencia de la API se genera a partir del código Go y está en inglés.
Package kolodht finds Kolo peers by topic on a Kademlia DHT over UDP and punches through NATs to a kolo-secure connection pinned to the announced key. IPv4 only (IPv6 is refused); experimental until v1.0.0.
Constantes
const DefaultRandomPunchInterval = 20 * time.SecondDefaultRandomPunchInterval is the default Config.RandomPunchInterval.
Variables
var (
// ErrInvalidConfig means a Config field is out of range, here or in kolo-secure or kolo-transport (wrapped too).
ErrInvalidConfig = errors.New("kolodht: invalid config")
// ErrInvalidArgument means a nil or zero identity, an IPv6 address, IPv4-mapped included (v0.1.x is IPv4 only), a record that cannot be
// used, or too many announcements.
ErrInvalidArgument = errors.New("kolodht: invalid argument")
// ErrClosed means the node is closed.
ErrClosed = errors.New("kolodht: closed")
// ErrNoNodes means no server answered.
ErrNoNodes = errors.New("kolodht: no server answered")
// ErrNotStored means no server stored the announcement.
ErrNotStored = errors.New("kolodht: announcement not stored")
// ErrUnreachable means no relay led to a connection, or both sides have a random NAT mapping.
ErrUnreachable = errors.New("kolodht: peer unreachable")
// ErrTryLater means a punch with a random mapping on one side is over a budget here or at the peer, or this node
// already runs its attempts toward the peer's host or key.
ErrTryLater = errors.New("kolodht: try later")
)Funciones
func Closer
func Closer(target, a, b [32]byte) boolCloser reports whether a is closer to target than b by XOR distance, compared as big-endian unsigned integers.
func Distance
func Distance(a, b [32]byte) [32]byteDistance returns the Kademlia XOR distance between two 32-byte IDs, such as a topic and a node ID.
func PublicServers
func PublicServers() []netip.AddrPortPublicServers returns a copy of the built-in public entry nodes, the servers Bootstrap uses when it is given nil, so a node that bootstraps from them tells them its IP address.
Tipos
type Config
type Config struct {
// Secure is passed to kolo-secure, and Secure.Transport to kolotransport.Listen. A zero Transport.KeepAlivePeriod
// becomes 5s, so NAT filters stay open for punched connections, unless Transport.IdleTimeout is 5s or less.
Secure *kolosecure.Config
// Server answers DHT queries, stores records and relays connect requests; only servers enter routing tables.
Server bool
// MaxRecords caps the records a server stores, all topics. Default 65536, from 16 to 1,000,000.
// A full store takes about MaxRecords x 710 bytes of heap, 44 MiB at the default.
MaxRecords int
// MaxRecordsPerTopic caps the records of one topic. Default 512, from 1 to 65536. One IPv4 /24 may hold a sixteenth
// of them (at least 1), so filling a topic takes 16 networks.
MaxRecordsPerTopic int
// MaxRecordsPerIP caps the records from one announcing IPv4 address, all topics. Default 256, from 1 to 65536.
MaxRecordsPerIP int
// MaxAnnouncements caps the topics this node announces at once. Default 16, from 1 to 256.
MaxAnnouncements int
// MaxInflight caps the requests waiting for a reply. Default 160, from 8 to 4096.
MaxInflight int
// MaxRelays caps the connect requests a server relays at once. Default 64, from 1 to 4096.
MaxRelays int
// MaxPunches caps the punch requests this node answers at once, and the live connections punches made on birthday
// sockets of their own (4 per /24); a new one past that is refused. Default 16, from 1 to 256.
MaxPunches int
// MaxRequestsPerIP caps the requests per second from one IPv4 address. Default 50, from 1 to 10,000.
MaxRequestsPerIP int
// MaxRequestsPerPrefix caps the requests per second from one IPv4 /24. Default 200, from MaxRequestsPerIP to 100,000.
MaxRequestsPerPrefix int
// MaxRequests caps the requests per second from everyone. Default 10,000, from MaxRequestsPerPrefix to 1,000,000.
MaxRequests int
// RequestTimeout bounds the wait for one reply. Default 1s, from 100ms to 10s.
RequestTimeout time.Duration
// PunchTimeout bounds one connect attempt through one relay, a 35s random punch included. Default 45s, from 1s to 2m.
PunchTimeout time.Duration
// MaxRandomPunches caps the punches with a random mapping on one side that this node runs at once.
// Default 1, from 1 to 16.
MaxRandomPunches int
// MaxRandomPunchesPerTarget caps the random punches toward one peer IPv4 address. Default 1, from 1 to MaxRandomPunches.
MaxRandomPunchesPerTarget int
// MaxRandomPunchesPerRequester caps the random punches answered for one requester IPv4 address. Default 1, from 1 to
// MaxRandomPunches.
MaxRandomPunchesPerRequester int
// RandomPunchInterval is the least time from the end of one random punch to the next. Default 20s, from 1s to 10m.
RandomPunchInterval time.Duration
// MaxPunchSockets caps the sockets running punches hold besides the node's own; a birthday punch needs 255. Default
// 256, or half the soft RLIMIT_NOFILE if less, from 1 to 16384.
MaxPunchSockets int
// RandomPunchCooldown is the least time from the end of a burst to the next toward its IP (and /24 at the announcer)
// or by its storer, doubled per burst toward the IP that connected nothing, up to 16x. Default 1m, from 1s to 1h.
RandomPunchCooldown time.Duration
// MaxRandomPunchesPerMinute caps those bursts started in any minute. Default 4, from 1 to 64.
MaxRandomPunchesPerMinute int
// Trace, if set, gets every punch probe and step, from the punch goroutines and never with a lock held. It must
// return fast; a slow one slows the probes. A panic in it drops that event and is not passed on. Default nil.
Trace func(TraceEvent)
}Config sets the limits of a Node. A zero field takes its default; out of range is ErrInvalidConfig.
type Node
type Node struct {
// contains filtered or unexported fields
}Node is a DHT node with one UDP socket for its DHT datagrams and its kolo-secure connections.
func New
func New(ctx context.Context, addr string, id *koloid.Identity, cfg *Config) (*Node, error)New opens a UDP socket on addr, such as "127.0.0.1:0" or ":4000", for the DHT and for kolo-secure connections as id. v0.1.x is IPv4 only: an IPv6 addr, IPv4-mapped included, is ErrInvalidArgument.
func (Node) Accept
func (n *Node) Accept(ctx context.Context) (*kolosecure.Conn, error)Accept waits for the next inbound connection, punched or direct, that no Connect in progress claimed. Unclaimed connections wait in a queue of Secure.MaxPending (default 64); when it is full, new ones are closed.
func (Node) Addr
func (n *Node) Addr() net.AddrAddr returns the local address of the node's socket.
func (Node) Announce
func (n *Node) Announce(ctx context.Context, topic Topic) errorAnnounce stores a signed record of this node at the servers closest to topic and refreshes it until Unannounce or Close; it returns once one stored it (the README lists its errors). Announcing a topic again does nothing.
func (Node) Bootstrap
func (n *Node) Bootstrap(ctx context.Context, servers []netip.AddrPort) errorBootstrap pings servers, keeps those that answer and looks up our own ID: ErrNoNodes if none answered, and ErrInvalidArgument before sending anything if any address is IPv6, IPv4-mapped included.
A nil servers list means PublicServers: the public entry nodes learn our IP and, once we Announce, store the topic and our address. To stay private pass your own servers; an empty list that is not nil is ErrInvalidArgument.
func (Node) Close
func (n *Node) Close() errorClose stops announcing, closes the socket and every connection of the node, and waits for its goroutines. It is safe to call more than once.
func (Node) Connect
func (n *Node) Connect(ctx context.Context, r Record) (*kolosecure.Conn, error)Connect punches through up to 3 relays of r, PunchTimeout each, and returns a connection pinned to r.PublicKey. A relay that fails does not stop the next; only our own limits and the context do (the README lists the errors).
func (Node) Lookup
func (n *Node) Lookup(ctx context.Context, topic Topic) ([]Record, error)Lookup returns the records of topic stored at the servers closest to it, verified and merged by key, freshest first. Our own record is left out. It returns ErrNoNodes if no server answered.
func (Node) Stats
func (n *Node) Stats() StatsStats returns the node's current state and counters; it is safe during traffic and after Close.
func (Node) Unannounce
func (n *Node) Unannounce(topic Topic)Unannounce stops refreshing the record of topic; the servers drop it within 20 minutes.
type Record
type Record struct {
// Topic is the topic the peer announced.
Topic Topic
// PublicKey is the peer's kolo-id public key.
PublicKey ed25519.PublicKey
// Addr is the peer's address as the freshest server stored it.
Addr netip.AddrPort
// contains filtered or unexported fields
}Record is a peer found on a topic: its kolo-id key and address, signed by that key and verified by Lookup. It also holds the servers that stored it, which Connect uses as relays.
func (Record) Addrs
func (r Record) Addrs() []netip.AddrPortAddrs returns every address Connect may probe or dial for r: Addr and each relay's stored peer address, once each, IPv4 only. Random-port probes go to the IPs of these addresses.
type Stats
type Stats struct {
// Servers is the number of servers in the routing table.
Servers int
// Records is the number of records this server stores.
Records int
// Requests counts the requests that passed the rate limits since New.
Requests uint64
// Limited counts the requests the rate limits dropped since New.
Limited uint64
}Stats is a snapshot of a node's state and counters; the counters only grow, so callers take differences.
type Topic
type Topic [32]byteTopic is a 32-byte value peers announce and look up, such as a hash of an application's topic name.
type TraceEvent
type TraceEvent struct {
// Kind is the step; the fields below are set as its constant says.
Kind TraceKind
// Local and Remote are the local socket address and the peer address.
Local, Remote netip.AddrPort
// Size is the probe size in bytes and TTL its IP TTL (0 is the system default).
Size, TTL int
// Count is the number of sockets or probes.
Count int
}TraceEvent is one step of a punch, passed to Config.Trace. Which fields are set depends on Kind.
func (TraceEvent) String
func (e TraceEvent) String() stringString formats e as one log line.
type TraceKind
type TraceKind intTraceKind says what a TraceEvent reports.
const (
// TraceProbeSent: a probe of Size bytes left Local for Remote, at TTL (0 is the system default).
TraceProbeSent TraceKind = iota + 1
// TraceProbeReceived: a probe of Size bytes for a punch of ours reached Local from Remote.
TraceProbeReceived
// TraceBirthdayOpened: Count sockets, the node's own included, now probe Remote (birthday punch).
TraceBirthdayOpened
// TraceRandomProbes: up to Count probes to random ports of Remote's IP start (Remote's port is 0).
TraceRandomProbes
// TraceProved: Remote echoed our nonce to Local, so the punch may dial it.
TraceProved
)func (TraceKind) String
func (k TraceKind) String() stringString returns the name of k.
Conviene saber
Redes públicas y privadas
PublicServers() devuelve una copia de los nodos de entrada públicos incluidos en la librería, como []netip.AddrPort. Ciranda los ejecuta para todos, gratis y sin garantía de disponibilidad mientras Kolo sea una beta. Node.Bootstrap(ctx, nil) los usa, de modo que un nodo sin configuración entra en la red pública y encuentra peers de otras redes.
Para mantener una red aparte, pasa tus propios servidores: un primer nodo de entrada se ejecuta con kolo-node run -first, y los demás nodos hacen bootstrap desde él. Una lista vacía que no es nil es ErrInvalidArgument y no envía ningún paquete, de modo que una aplicación que debe seguir siendo privada nunca entra por error en la red pública.
Quién ve qué cuando la lista es nil: los dos nodos de entrada ven tu dirección IP y tu puerto en cuanto haces bootstrap. Tras Announce, el topic y tu dirección se guardan en los servidores de la red pública, legibles por cualquiera que busque el topic; un topic no es un secreto, porque quien conoce sus 32 bytes puede encontrar el registro. Los nodos de entrada no tienen clave, así que un cliente no puede comprobar quién responde en una dirección, y sus direcciones van compiladas en cada versión, de modo que un cliente de una versión antigua sigue preguntando a esas direcciones. Los registros se siguen verificando y cada conexión queda fijada a la clave anunciada, así que un nodo de entrada no puede hacerse pasar por un peer, pero sí puede dar a un cliente una lista de servidores mala o no responder. Un slice nil cuenta como nil: una variable []netip.AddrPort a la que nunca añadiste nada también entra en la red pública.
Límites
- Solo IPv4.
New,BootstrapyConnectrechazan una dirección IPv6 conErrInvalidArgument, incluida la forma IPv4-mapped::ffff:a.b.c.d. Se descarta cualquier datagrama con origen IPv6. - Un campo de
Configa cero toma su valor por defecto. Un valor fuera de rango esErrInvalidConfig. MaxRecords: 65536 registros por servidor, entre todos los topics (de 16 a 1.000.000). Un registro ocupa hasta unos 710 bytes de heap, así que un almacén lleno ocupa unos 44 MiB con el valor por defecto; tenlo en cuenta enGOMEMLIMIT. Un servidor lleno rechaza registros nuevos y nunca expulsa los vigentes.MaxRecordsPerTopic: 512 (de 1 a 65536). Una /24 de IPv4 tiene como mucho un dieciseisavo de ellos, 32 con el valor por defecto.MaxRecordsPerIP: 256 por dirección IPv4 que anuncia, entre todos los topics (de 1 a 65536).MaxAnnouncements: 16 topics que anuncia este nodo (de 1 a 256). Por encima,AnnouncedevuelveErrInvalidArgument.MaxInflight: 160 peticiones a la espera de respuesta (de 8 a 4096). Las demás peticiones esperan un hueco.MaxRelays: 64 peticiones de conexión que un servidor retransmite a la vez (de 1 a 4096).MaxPunches: 16 peticiones de perforación atendidas a la vez (de 1 a 256). También pone tope a las conexiones que ocupan sockets propios de birthday punch, 4 por /24. Por encima, a una perforación aleatoria nueva se le responde «inténtalo más tarde», y nunca se cierra una ya establecida.MaxRequestsPerIP: 50 peticiones por segundo por dirección IPv4 (de 1 a 10.000).MaxRequestsPerPrefix: 200 por segundo por /24 de IPv4 (deMaxRequestsPerIPa 100.000).MaxRequests: 10.000 por segundo en total (deMaxRequestsPerPrefixa 1.000.000). Las peticiones que los superan se descartan antes de decodificarse, en ventanas de 1 segundo, y se cuentan enStats().Limited.- Los ANNOUNCE que necesitan un acuerdo de claves o una comprobación de firma (un registro, dirección, firma o share nuevos; un simple refresco no) tienen su propio presupuesto: 20 por segundo por dirección IPv4, 100 por /24 y 1000 en total (o los límites de peticiones de arriba si son menores). Pasado ese límite el ANNOUNCE no recibe respuesta y cuenta en
Stats().Limited; quien anuncia lo intenta de nuevo en su siguiente refresco. Si no, un remitente con un token de ida y vuelta válido podría hacer que el servidor gastara unos 50 microsegundos por datagrama con bytes aleatorios. RequestTimeout: 1s de espera por una respuesta (de 100ms a 10s). Una entrada de la tabla de enrutamiento se descarta después de 4 peticiones fallidas seguidas.PunchTimeout: 45s por relay, incluidos una perforación aleatoria de 35s y su handshake (de 1s a 2m). Dos mapeos consistentes abandonan un relay después de su ventana de sondeo: 10 sondas separadas 1s, más 2 xRequestTimeout.MaxRandomPunches: 1 perforación a la vez con un mapeo aleatorio en uno de los lados, en los dos roles (de 1 a 16).MaxRandomPunchesPerTargetyMaxRandomPunchesPerRequester: 1 por dirección IPv4 de peer o de solicitante (de 1 aMaxRandomPunches).RandomPunchInterval: 20s desde el final de una perforación aleatoria hasta la siguiente (DefaultRandomPunchInterval, de 1s a 10m).RandomPunchCooldown: 1m entre dos ráfagas hacia una misma dirección IPv4, o iniciadas por un mismo servidor que guarda el registro (de 1s a 1h). Para una IP o una /24 se duplica después de cada ráfaga que no conectó nada desde la /24 sondeada, hasta 16 veces más.MaxRandomPunchesPerMinute: 4 ráfagas iniciadas en cualquier minuto, en los dos roles (de 1 a 64).MaxPunchSockets: 256 sockets ocupados por perforaciones además del propio del nodo, o la mitad delRLIMIT_NOFILEblando si es menor (de 1 a 16384). Un birthday punch necesita 255; por debajo, siempre se responde «inténtalo más tarde».Secure: se pasa a kolo-secure. UnKeepAlivePerioda cero pasa a ser 5s salvo queIdleTimeoutsea de 5s o menos, para mantener abiertos los mapeos de NAT de las conexiones perforadas.- Cola de
Accept:Secure.MaxPending, 64 por defecto. Cuando está llena, las conexiones nuevas se cierran con el código 1. - Un datagrama ocupa como máximo 1200 bytes. Una respuesta lleva como máximo 20 nodos y 16 registros.
- Tabla de enrutamiento: 256 buckets de 20, como mucho 2 entradas por /24 de IPv4 en un bucket y 10 en la tabla. Un bucket lleno conserva su entrada más antigua salvo que lleve 15 minutos en silencio y luego falle un ping. El mantenimiento envía 5 pings cada 40s.
- Cada registro se guarda en cada uno de los hasta 20 servidores más cercanos que respondieron a la búsqueda de quien anuncia;
Announcetiene éxito si al menos uno lo guardó. Quien anuncia lo refresca cada 15s y vuelve a buscar el topic cada 5 minutos. Un servidor descarta un registro 20 minutos después de su último refresco, así que después deUnannouncedesaparece en menos de 20 minutos. - Una búsqueda pregunta a 10 servidores a la vez y como mucho a 100 en total. Un
Lookupcomprueba como máximo 160 firmas. Connectpregunta hasta a 3 relays, uno detrás de otro. Un nodo ejecuta como mucho 2 intentos de perforación a la vez hacia un mismo host de destino. Un servidor retransmite como mucho 2 peticiones a la vez por host solicitante y 4 por destino.Bootstrapusa como máximo 64 direcciones. Un nodo comprueba como mucho 10 servidores nuevos a la vez, con un máximo de 1 ping de comprobación por segundo por dirección, 4 por /24 y 40 en total.- Tokens de ida y vuelta: el secreto cambia cada 40s, así que un token se acepta entre 40 y 80s.
- Sondas: con dos mapeos consistentes, 10 sondas separadas 1s. Con un mapeo aleatorio, 1750 sondas separadas 20ms (35s) hacia puertos aleatorios del 1000 al 65535, mientras el lado aleatorio abre 256 sockets (incluido el suyo) y envía con TTL 5 hasta que el peer alcanza uno. Un peer responde como mucho a 4 sondas por perforación, y una sesión de perforación envía como mucho a 8 direcciones.
- Clase de NAT: las últimas 16 muestras, una por /24 de servidor. Hacen falta al menos 3 muestras; por debajo, la clase es desconocida y se comporta como consistente. Una muestra caduca a los 30 minutos.
- IDs de nodo: una dirección IPv4 tiene como mucho 8 IDs, y un servidor cambia su elección de ID como mucho una vez por minuto.
Seguridad
- Los registros se firman con Ed25519ctx bajo el contexto
kolo-dht/announce/v1, sobre el topic, la clave y la dirección de quien anuncia tal como la vio el servidor que la guarda, así que un registro no se puede trasladar a otra dirección. kolo-id rechaza las claves de orden pequeño. - Las respuestas llevan un token de ida y vuelta HMAC-SHA256 vinculado a la dirección IPv4 y al puerto del solicitante. Un servidor no guarda ni retransmite nada para una dirección que no haya recibido un paquete suyo.
- Cada PUNCH lleva un contador y un HMAC-SHA256 con un secreto que quien anuncia y el servidor acordaron en el ANNOUNCE (X25519, HKDF-SHA256). Quien anuncia descarta un PUNCH con un MAC incorrecto o un contador repetido y no responde nada. Su respuesta OK se firma bajo
kolo-dht/punch-reply/v1, así que un relay que miente se descarta al instante. - Solo se conecta a una dirección que ha devuelto el nonce de una sonda. Un servidor que miente, o un registro que señala a un desconocido, hace que un nodo envíe como mucho 1 sonda a quien anuncia y 10 a quien conecta, y nunca un paquete QUIC.
- Las sondas a puertos aleatorios solo van a una IP de peer en la que servidores de dos /16 distintas guardaron el registro.
- Una dirección obtenida de otro nodo solo se usa si es global o del mismo ámbito (loopback, link-local, privada) que ese nodo.
- No cerrado, por diseño: dos servidores confabulados en dos /16, ambos entre los más cercanos a un topic, pueden hacer que cada nodo que conecta envíe una ventana de sondas a puertos aleatorios (1750 sondas, 61 KB) a una IP que elijan. Eso son como mucho unos 1,1 KB/s por nodo que conecta, unos 60 B/s hacia una IP, o 1 KB/s aproximadamente con un host en la /24 de esa IP.
- No cerrado, por diseño: atacantes que completan perforaciones reales desde 3 /24 pueden mantener ocupada la única perforación aleatoria de quien anuncia, y atacantes que mantienen conexiones desde 4 /24 pueden bloquear birthday punches nuevos hacia él. Los peers ya conectados siguen conectados.
- Experimental. La API puede cambiar antes de v1.0.0.
Límites conocidos
- Dos peers que tienen ambos un mapeo de NAT aleatorio no pueden conectarse:
ConnectdevuelveErrUnreachable. - Dos peers detrás del mismo NAT solo se conectan si este admite hairpinning.
- El birthday punch (un mapeo aleatorio) solo se ha comprobado en un simulador de NAT dentro del proceso, no en NATs reales. Su tasa de éxito analítica es de 0,999 aproximadamente. Los NATs reales que asignan los puertos de otra forma, que limitan los mapeos por host o que limitan la frecuencia de los nuevos pueden dar peores resultados.
- En una red cuyos servidores comparten todos la misma /16, un
Connectdesde un mapeo consistente hacia uno aleatorio devuelveErrUnreachableal instante. - No se garantiza: encontrar todos los peers de un topic (los servidores pueden estar desconectados, llenos o mentir), la resistencia frente a un atacante con muchos prefijos /24, la privacidad de los topics y las direcciones, ni llegar a quien anuncia detrás de un NAT que descarta los mapeos en menos de 15s.
Errores
| Error | Mensaje |
|---|---|
ErrClosed | kolodht: closed |
ErrInvalidArgument | kolodht: invalid argument |
ErrInvalidConfig | kolodht: invalid config |
ErrNoNodes | kolodht: no server answered |
ErrNotStored | kolodht: announcement not stored |
ErrTryLater | kolodht: try later |
ErrUnreachable | kolodht: peer unreachable |
Toda llamada bloqueante (Bootstrap, Announce, Lookup y Connect) devuelve ctx.Err() en cuanto su contexto termina, y ErrClosed tras Close, también Bootstrap. Un plazo que ya pasó cuenta como terminado aunque el runtime aún no haya marcado el contexto (un tiempo de espera de petición puede dispararse antes en un temporizador grueso, como en Windows o en una VM ocupada), así que la llamada devuelve context.DeadlineExceeded, no ErrNoNodes ni ErrUnreachable, y un servidor no se marca como fallido por una petición que el plazo cortó.
Comprueba con errors.Is. ErrInvalidConfig envuelve un error de configuración de kolo-secure o de kolo-transport, así que el propio centinela de esa biblioteca también coincide; los demás errores al abrir el socket se transmiten sin cambios.
Referencias
- Maymounkov and Mazieres, Kademlia, IPTPS 2002.
- Toma: la métrica XOR, los k-buckets y la búsqueda iterativa.
- Baumgart and Mies, S/Kademlia, ICPADS 2007.
- Toma: IDs que un nodo no puede elegir libremente.
- No implementa: los puzzles criptográficos.
- RFC 4787, NAT Behavioral Requirements for Unicast UDP (BCP, February 2007).
- Toma: las clases de comportamiento de NAT, que usa el simulador.
- RFC 5128, State of P2P Communication across NATs (Informational, March 2008).
- Toma: la perforación de NAT por UDP (hole punching).
- Ford, Srisuresh and Kegel, Peer-to-Peer Communication Across Network Address Translators, USENIX ATC 2005.
- Toma: la perforación de NAT por UDP (hole punching).
- RFC 8489, Session Traversal Utilities for NAT (STUN) (Proposed Standard, February 2020).
- Toma: la idea de averiguar la dirección desde la que se ve a un peer.
- No implementa: los mensajes de STUN.
- RFC 8445, ICE: A Protocol for NAT Traversal (Proposed Standard, July 2018).
- No implementa: ICE en sí.
- RFC 9000, QUIC: A UDP-Based Multiplexed and Secure Transport (Proposed Standard, May 2021) and RFC 9443, Multiplexing Scheme Updates for QUIC (Proposed Standard, July 2023).
- Toma: un solo socket para QUIC y la DHT, que se distinguen por el primer byte (0x24 con los bits altos a cero).
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
- Toma: Ed25519ctx para los registros firmados.
- RFC 7748, Elliptic Curves for Security (Informational, January 2016).
- Toma: X25519 para el secreto de la perforación.
- RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF) (Informational, May 2010).
- Toma: la derivación del secreto de la perforación.
- RFC 2104, HMAC: Keyed-Hashing for Message Authentication (Informational, February 1997).
- Toma: la autenticación del datagrama PUNCH.
- Douceur, The Sybil Attack, IPTPS 2002.
- Toma: el modelo de amenazas.
- Heilman, Kendler, Zohar and Goldberg, Eclipse Attacks on Bitcoin's Peer-to-Peer Network, USENIX Security 2015.
- Toma: los límites por bucket y por tabla para las direcciones de un mismo rango.
- Marcus, Heilman and Goldberg, Low-Resource Eclipse Attacks on Ethereum's Peer-to-Peer Network, IACR ePrint 2018/236.
- Toma: los límites por bucket y por tabla para las direcciones de un mismo rango.