A kolo-dht é uma DHT Kademlia, reforçada segundo a S/Kademlia, que roda no mesmo socket UDP do listener QUIC da kolo-transport do nó. Um peer anuncia um topic de 32 bytes com um registro assinado pela sua chave da kolo-id. Outro peer busca o topic, o servidor que guardou o registro coordena um hole punch como descreve o RFC 5128, testado com os comportamentos de NAT do RFC 4787, e quem chamou recebe uma conexão da kolo-secure presa à chave anunciada. Nada retransmite os dados da aplicação.
Um lookup, passo a passo
Este exemplo usa IDs de 8 bits. Os IDs reais têm 256 bits, a tabela guarda 20 servidores por bucket e até 10 consultas rodam ao mesmo tempo.
- A sua tabela de rotas dá os servidores que ela conhece mais perto do topic: aqui A, B e C. A distância é o XOR dos dois IDs.
- Você envia LOOKUP a todos de uma vez. Cada resposta traz servidores mais perto do topic, um token e os registros que houver.
- C conhece D e E, que estão mais perto. Você pergunta a eles assim que a resposta chega: não há rodadas fixas.
- E conhece F e G, mais perto ainda. A lista é ordenada pela distância depois de cada resposta.
- A busca para quando os 20 servidores mais próximos que ela conhece responderam ou esgotaram o tempo, ou depois de 100 consultas. Cada registro é assinado pelo peer que o anunciou, e a assinatura é conferida.
- Um lookup retorna registros, não conexões. Connect é uma chamada separada, por meio de um servidor que guardou o registro.
Conectar através de dois NAT
Os dois peers estão atrás de roteadores domésticos. Um nó bootstrap na internet põe os dois em contato; depois os pacotes vão direto.
- A e B anunciam cada um um registro assinado do topic a um nó bootstrap, cada um por trás do seu próprio NAT.
- A procura o topic. A resposta traz o registro assinado de B, com a sua chave pública e o seu endereço, e o nó que o guardou.
- A envia CONNECT a esse nó, que passa o pedido a B. Nenhum alcança ainda o outro: os dois NAT só deixam entrar respostas.
- Os dois enviam pacotes PUNCH um ao outro ao mesmo tempo. Cada NAT vê sair o pacote do seu próprio peer e abre um mapeamento, e assim deixa entrar os do outro.
- O caminho direto está aberto: os pacotes vão entre A e B sem passar pelo nó. Depois o kolo-secure prova as duas chaves na conexão.
Instalação
go get github.com/ciranda-dev/kolo-dhtCompila sem cgo.
Config.Trace é um callback para cada sonda de punch enviada e recebida, os sockets de um birthday punch e cada endereço comprovado. Config tem esse campo de função, então não pode ser comparado com ==: use reflect.DeepEqual.
Início rápido
Um servidor e dois peers no loopback: bob anuncia um topic, alice o encontra, se conecta e recebe a sua mensagem de volta.
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())
}O programa imprime hello kolo from e a chave pública de bob em hex. Sem lista, Bootstrap(ctx, nil) entra na rede pública pelos nós de entrada embutidos na biblioteca; veja Redes públicas e privadas. Para manter a sua própria rede, rode alguns nós com Config.Server em endereços públicos, como o kolo-node, e passe os endereços deles a Bootstrap.
Referência da API
A referência da API é gerada a partir do código Go e está em 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.
Variáveis
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")
)Funções
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.
Bom saber
Redes públicas e privadas
PublicServers() devolve uma cópia dos nós de entrada públicos embutidos na biblioteca, como []netip.AddrPort. A Ciranda os mantém no ar para todos, de graça e sem garantia de disponibilidade enquanto o Kolo for uma beta. Node.Bootstrap(ctx, nil) os usa, então um nó sem configuração entra na rede pública e encontra peers de outras redes.
Para manter uma rede separada, passe os seus próprios servidores: um primeiro nó de entrada roda com o kolo-node run -first, e os demais nós fazem bootstrap a partir dele. Uma lista vazia que não é nil é ErrInvalidArgument e não envia nenhum pacote, então uma aplicação que precisa continuar privada nunca entra por engano na rede pública.
Quem vê o quê quando a lista é nil: os dois nós de entrada veem o seu endereço IP e a porta assim que você faz bootstrap. Depois de Announce, o topic e o seu endereço são guardados nos servidores da rede pública, legíveis por qualquer um que procure o topic; um topic não é um segredo, pois quem conhece os 32 bytes dele pode achar o registro. Os nós de entrada não têm chave, então um cliente não consegue conferir quem responde em um endereço, e os endereços deles vão compilados em cada versão, então um cliente de uma versão antiga continua perguntando a esses endereços. Os registros continuam sendo verificados e cada conexão fica presa à chave anunciada, então um nó de entrada não consegue se passar por um peer, mas pode entregar a um cliente uma lista de servidores ruim ou não responder. Um slice nil conta como nil: uma variável []netip.AddrPort em que você nunca acrescentou nada também entra na rede pública.
Limites
- Só IPv4.
New,BootstrapeConnectrecusam um endereço IPv6 comErrInvalidArgument, incluindo a forma IPv4-mapped::ffff:a.b.c.d. Um datagrama vindo de uma origem IPv6 é descartado. - Um campo de
Configzerado assume o seu padrão. Um valor fora da faixa éErrInvalidConfig. MaxRecords: 65536 registros por servidor, somando todos os topics (de 16 a 1.000.000). Um registro ocupa até cerca de 710 bytes de heap, então um armazenamento cheio ocupa cerca de 44 MiB com o padrão; inclua isso noGOMEMLIMIT. Um servidor cheio recusa novos registros e nunca remove registros ativos.MaxRecordsPerTopic: 512 (de 1 a 65536). Uma única /24 IPv4 ocupa no máximo um dezesseis avos deles, 32 com o padrão.MaxRecordsPerIP: 256 por endereço IPv4 que anuncia, somando todos os topics (de 1 a 65536).MaxAnnouncements: 16 topics que este nó anuncia (de 1 a 256). Acima disso,AnnounceretornaErrInvalidArgument.MaxInflight: 160 requisições esperando resposta (de 8 a 4096). As outras requisições esperam uma vaga.MaxRelays: 64 pedidos de conexão que um servidor repassa ao mesmo tempo (de 1 a 4096).MaxPunches: 16 pedidos de punch respondidos ao mesmo tempo (de 1 a 256). Também limita as conexões que ficam em sockets próprios de birthday punch, 4 por /24. Acima disso, um novo punch aleatório recebe como resposta “tente mais tarde”, e um já estabelecido nunca é fechado.MaxRequestsPerIP: 50 requisições por segundo por endereço IPv4 (de 1 a 10.000).MaxRequestsPerPrefix: 200 por segundo por /24 IPv4 (deMaxRequestsPerIPa 100.000).MaxRequests: 10.000 por segundo no total (deMaxRequestsPerPrefixa 1.000.000). As requisições acima desses limites são descartadas antes de serem decodificadas, em janelas de 1 segundo, e contadas emStats().Limited.- Os ANNOUNCE que precisam de um acordo de chaves ou de uma verificação de assinatura (um registro, endereço, assinatura ou share novos; um simples refresh não) têm um orçamento próprio: 20 por segundo por endereço IPv4, 100 por /24 e 1000 no total (ou os limites de requisições acima, se menores). Passado esse limite o ANNOUNCE não recebe resposta e conta em
Stats().Limited; quem anuncia tenta de novo no próximo refresh. Sem isso, um remetente com um token de ida e volta válido poderia fazer o servidor gastar uns 50 microssegundos por datagrama com bytes aleatórios. RequestTimeout: 1s de espera por uma resposta (de 100ms a 10s). Uma entrada da tabela de roteamento é descartada depois de 4 requisições seguidas que falham.PunchTimeout: 45s por relay, incluindo um punch aleatório de 35s e o seu handshake (de 1s a 2m). Dois mapeamentos consistentes desistem de um relay depois da sua janela de sondagem: 10 sondas com 1s de intervalo, mais 2 xRequestTimeout.MaxRandomPunches: 1 punch com mapeamento aleatório de um dos lados por vez, nos dois papéis (de 1 a 16).MaxRandomPunchesPerTargeteMaxRandomPunchesPerRequester: 1 por endereço IPv4 de peer ou de quem pede (de 1 aMaxRandomPunches).RandomPunchInterval: 20s entre o fim de um punch aleatório e o próximo (DefaultRandomPunchInterval, de 1s a 10m).RandomPunchCooldown: 1m entre duas rajadas para um mesmo endereço IPv4, ou iniciadas por um mesmo servidor que guardou o registro (de 1s a 1h). Para um IP ou uma /24, o valor dobra depois de cada rajada que não conectou nada da /24 sondada, até 16 vezes o valor inicial.MaxRandomPunchesPerMinute: 4 rajadas iniciadas em qualquer minuto, nos dois papéis (de 1 a 64).MaxPunchSockets: 256 sockets ocupados por punches além do próprio socket do nó, ou metade do limite flexível deRLIMIT_NOFILE, se for menor (de 1 a 16384). Um birthday punch precisa de 255; abaixo disso ele sempre recebe como resposta “tente mais tarde”.Secure: passado para a kolo-secure. UmKeepAlivePeriodzerado vira 5s, a não ser queIdleTimeoutseja de 5s ou menos, para manter abertos os mapeamentos de NAT das conexões feitas por punch.- Fila de
Accept:Secure.MaxPending, 64 por padrão. Quando ela está cheia, as novas conexões são fechadas com o código 1. - Um datagrama tem no máximo 1200 bytes. Uma resposta carrega no máximo 20 nós e 16 registros.
- Tabela de roteamento: 256 buckets de 20, com no máximo 2 entradas por /24 IPv4 em um bucket e 10 na tabela. Um bucket cheio mantém a sua entrada mais antiga, a não ser que ela tenha ficado em silêncio por 15 minutos e depois falhe em um ping. A manutenção envia 5 pings a cada 40s.
- Cada registro é guardado em cada um dos até 20 servidores mais próximos que responderam à busca de quem anuncia;
Announcedá certo se pelo menos um o guardou. Quem anuncia renova o registro a cada 15s e busca o topic de novo a cada 5 minutos. Um servidor descarta um registro 20 minutos depois da última renovação, então depois deUnannounceele some em até 20 minutos. - Uma busca consulta 10 servidores ao mesmo tempo e no máximo 100 no total. Um
Lookupverifica no máximo 160 assinaturas. Connectconsulta até 3 relays, um depois do outro. Um nó faz no máximo 2 tentativas de punch ao mesmo tempo para um mesmo host de destino. Um servidor repassa no máximo 2 pedidos ao mesmo tempo por host que pede e 4 por alvo.Bootstrapusa no máximo 64 endereços. Um nó verifica no máximo 10 servidores novos ao mesmo tempo, com no máximo 1 ping de verificação por segundo por endereço, 4 por /24 e 40 no total.- Tokens de ida e volta: o segredo muda a cada 40s, então um token é aceito por 40 a 80s.
- Sondas: com dois mapeamentos consistentes, 10 sondas com 1s de intervalo. Com um mapeamento aleatório, 1750 sondas com 20ms de intervalo (35s) para portas aleatórias de 1000 a 65535, enquanto o lado aleatório abre 256 sockets (incluindo o seu) e envia com TTL 5 até o peer alcançar um deles. Um peer responde no máximo 4 sondas por punch, e uma sessão de punch envia para no máximo 8 endereços.
- Classe de NAT: as últimas 16 amostras, uma por /24 de servidor. São necessárias pelo menos 3 amostras; abaixo disso a classe é desconhecida e se comporta como consistente. Uma amostra expira depois de 30 minutos.
- IDs de nó: um endereço IPv4 tem no máximo 8 IDs, e um servidor muda a sua escolha de ID no máximo uma vez por minuto.
Segurança
- Os registros são assinados com Ed25519ctx sob o contexto
kolo-dht/announce/v1, sobre o topic, a chave e o endereço de quem anuncia do jeito que o servidor que guarda o registro o viu, então um registro não pode ser levado para outro endereço. A kolo-id rejeita chaves de ordem pequena. - As respostas carregam um token de ida e volta HMAC-SHA256 vinculado ao endereço IPv4 e à porta de quem pede. Um servidor não guarda nem repassa nada para um endereço que não recebeu um pacote dele.
- Cada PUNCH carrega um contador e um HMAC-SHA256 sob um segredo que quem anuncia e o servidor combinaram no ANNOUNCE (X25519, HKDF-SHA256). Quem anuncia descarta um PUNCH com MAC errado ou contador repetido e não envia nada de volta. A sua resposta OK é assinada sob
kolo-dht/punch-reply/v1, então um relay mentiroso é descartado na hora. - Só um endereço que devolveu o nonce de uma sonda recebe uma conexão. Um servidor mentiroso, ou um registro que aponta para um desconhecido, faz um nó enviar no máximo 1 sonda para quem anuncia e 10 para quem conecta, e nunca um pacote QUIC.
- As sondas para portas aleatórias só vão para um IP de peer em que servidores de duas /16 diferentes guardaram o registro.
- Um endereço obtido de outro nó só é usado se for global ou estiver no mesmo escopo (loopback, link-local, privado) desse nó.
- Não resolvido, de propósito: dois servidores em conluio em duas /16, ambos entre os mais próximos de um topic, podem fazer cada nó que conecta enviar uma janela de sondas para portas aleatórias (1750 sondas, 61 KB) para um IP que eles escolherem. Isso dá no máximo cerca de 1,1 KB/s por nó que conecta, cerca de 60 B/s para um único IP, ou cerca de 1 KB/s com um host na /24 desse IP.
- Não resolvido, de propósito: atacantes que concluem punches reais a partir de 3 /24 podem manter ocupado o único punch aleatório de quem anuncia, e atacantes que mantêm conexões a partir de 4 /24 podem bloquear novos birthday punches para ele. Os peers já conectados continuam conectados.
- Experimental. A API pode mudar antes da v1.0.0.
Limites conhecidos
- Dois peers que têm, os dois, um mapeamento de NAT aleatório não conseguem se conectar:
ConnectretornaErrUnreachable. - Dois peers atrás do mesmo NAT só se conectam se ele fizer hairpinning.
- O birthday punch (um mapeamento aleatório) só é testado em um simulador de NAT dentro do processo, não em NATs reais. A sua taxa de sucesso analítica é de cerca de 0,999. NATs reais que alocam portas de outro jeito, limitam os mapeamentos por host ou limitam a taxa de novos mapeamentos podem ter um resultado pior.
- Em uma rede em que todos os servidores estão na mesma /16, um
Connectde um mapeamento consistente para um aleatório retornaErrUnreachablena hora. - Sem garantia: encontrar todos os peers de um topic (os servidores podem estar offline, cheios ou mentindo), resistência a um atacante com muitos prefixos /24, privacidade de topics e endereços, e alcançar quem anuncia atrás de um NAT que descarta mapeamentos em menos de 15s.
Erros
| Erro | Mensagem |
|---|---|
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 chamada bloqueante (Bootstrap, Announce, Lookup e Connect) retorna ctx.Err() assim que o contexto termina, e ErrClosed depois de Close, inclusive Bootstrap. Um prazo que já passou conta como encerrado mesmo que o runtime ainda não tenha marcado o contexto (um timeout de requisição pode disparar antes em um temporizador grosso, como no Windows ou em uma VM ocupada), então a chamada retorna context.DeadlineExceeded, não ErrNoNodes nem ErrUnreachable, e um servidor não é marcado como falho por uma requisição que o prazo cortou.
Teste com errors.Is. ErrInvalidConfig envolve um erro de configuração da kolo-secure ou da kolo-transport, então o sentinela da própria biblioteca também corresponde; outros erros ao abrir o socket passam adiante sem mudanças.
Referências
- Maymounkov and Mazieres, Kademlia, IPTPS 2002.
- Usa: a métrica XOR, os k-buckets e a busca iterativa.
- Baumgart and Mies, S/Kademlia, ICPADS 2007.
- Usa: IDs que um nó não pode escolher livremente.
- Não implementa: os puzzles criptográficos.
- RFC 4787, NAT Behavioral Requirements for Unicast UDP (BCP, February 2007).
- Usa: as classes de comportamento de NAT, usadas pelo simulador.
- RFC 5128, State of P2P Communication across NATs (Informational, March 2008).
- Usa: o hole punching por UDP.
- Ford, Srisuresh and Kegel, Peer-to-Peer Communication Across Network Address Translators, USENIX ATC 2005.
- Usa: o hole punching por UDP.
- RFC 8489, Session Traversal Utilities for NAT (STUN) (Proposed Standard, February 2020).
- Usa: a ideia de descobrir o endereço pelo qual um peer é visto.
- Não implementa: as mensagens do STUN.
- RFC 8445, ICE: A Protocol for NAT Traversal (Proposed Standard, July 2018).
- Não implementa: o ICE em si.
- 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).
- Usa: um só socket para o QUIC e a DHT, distinguidos pelo primeiro byte (0x24 com os bits altos zerados).
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
- Usa: Ed25519ctx para os registros assinados.
- RFC 7748, Elliptic Curves for Security (Informational, January 2016).
- Usa: X25519 para o segredo do punch.
- RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF) (Informational, May 2010).
- Usa: a derivação do segredo do punch.
- RFC 2104, HMAC: Keyed-Hashing for Message Authentication (Informational, February 1997).
- Usa: a autenticação do datagrama PUNCH.
- Douceur, The Sybil Attack, IPTPS 2002.
- Usa: o modelo de ameaças.
- Heilman, Kendler, Zohar and Goldberg, Eclipse Attacks on Bitcoin's Peer-to-Peer Network, USENIX Security 2015.
- Usa: os limites por bucket e por tabela para os endereços de uma mesma faixa.
- Marcus, Heilman and Goldberg, Low-Resource Eclipse Attacks on Ethereum's Peer-to-Peer Network, IACR ePrint 2018/236.
- Usa: os limites por bucket e por tabela para os endereços de uma mesma faixa.