A kolo-swarm entra em topics e mantém no máximo uma conexão da kolo-secure por chave remota com os peers encontrados neles. Um Swarm roda o seu próprio nó da kolo-dht: ele anuncia e busca os topics em que entrou, se conecta aos peers que encontra, com backoff e jitter, e aceita os peers que se conectam a ele. Com relays listados em Config.Relays, um peer que ele não alcança diretamente é discado por uma kolo-relay que os dois peers têm na lista. Uma conexão que a aplicação abriu de outro jeito entra por Attach. Ela prefere os caminhos diretos e usa um relay por último, como faz o ICE (RFC 8445), e limita as conexões por endereço contra os ataques de eclipse descritos por Heilman et al..
Entrar em um topic
Você dá um topic; o kolo-swarm encontra os peers dele e entrega conexões, uma por peer.
- Join anuncia o seu registro assinado no topic em até 20 servidores do DHT perto dele, e busca o topic.
- Cada registro encontrado é um evento Found. Por padrão o kolo-swarm conecta até 3 peers ao mesmo tempo e mantém no máximo 64 peers, conectados ou sendo discados.
- Connect pede a um servidor que guardou o registro do peer que repasse o pedido. Depois os dois lados enviam pacotes para abrir um caminho direto (hole punching).
- kolo-secure prova as chaves dos dois peers na conexão nova.
- Em um stream novo, o peer com a chave maior envia hello com os topics em que encontrou o outro. A chave menor decide e responde com um número de geração.
- Fica uma conexão por peer; uma duplicada é fechada. O app recebe Connected, e Lost quando ela termina. As reconexões esperam de 1 segundo a 10 minutos.
Instalação
go get github.com/ciranda-dev/kolo-swarmCompila sem cgo.
Início rápido
Um servidor da kolo-dht e dois swarms no loopback entram no mesmo topic, se conectam e devolvem uma mensagem.
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"
koloswarm "github.com/ciranda-dev/kolo-swarm"
)
func swarm(ctx context.Context, server netip.AddrPort) *koloswarm.Swarm {
id, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
s, err := koloswarm.New(ctx, "127.0.0.1:0", id, nil)
if err != nil {
log.Fatal(err)
}
if err := s.Bootstrap(ctx, []netip.AddrPort{server}); err != nil {
log.Fatal(err)
}
return s
}
func connected(ctx context.Context, s *koloswarm.Swarm) *koloswarm.Peer {
for {
ev, err := s.Next(ctx)
if err != nil {
log.Fatal(err)
}
if ev.Kind == koloswarm.Connected {
return ev.Peer
}
}
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
sid, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
server, err := kolodht.New(ctx, "127.0.0.1:0", sid, &kolodht.Config{Server: true})
if err != nil {
log.Fatal(err)
}
defer server.Close()
saddr := server.Addr().(*net.UDPAddr).AddrPort()
alice, bob := swarm(ctx, saddr), swarm(ctx, saddr)
defer alice.Close()
defer bob.Close()
topic := koloswarm.Topic(sha256.Sum256([]byte("kolo example topic")))
if err := bob.Join(ctx, topic, &koloswarm.JoinOptions{Announce: true}); err != nil {
log.Fatal(err)
}
if err := alice.Join(ctx, topic, &koloswarm.JoinOptions{Lookup: true}); err != nil {
log.Fatal(err)
}
pa, pb := connected(ctx, alice), connected(ctx, bob)
fmt.Printf("alice connected to %x (direct %v)\n", pa.PublicKey()[:8], pa.Direct())
go func() {
st, err := pb.Conn().AcceptStream(ctx)
if err != nil {
return
}
io.Copy(st, st)
st.Close()
}()
st, err := pa.Conn().OpenStream(ctx)
if err != nil {
log.Fatal(err)
}
if _, err := st.Write([]byte("hello kolo")); err != nil {
log.Fatal(err)
}
st.Close()
reply, err := io.ReadAll(st)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%s from %x\n", reply, pa.PublicKey()[:8])
}O programa imprime os primeiros 8 bytes da chave de bob com direct true (a conexão veio da kolo-dht) e depois hello kolo devolvido. Sem lista, Bootstrap(ctx, nil) entra na rede pública pelos nós de entrada embutidos na kolo-dht. Para uma rede privada, faça bootstrap a partir de alguns servidores da kolo-dht seus, como o kolo-node; veja Redes públicas e privadas.
Referência da API
A referência da API é gerada a partir do código Go e está em inglês.
Package koloswarm joins Kolo topics and keeps connections to the peers found on them.
A Swarm owns a kolo-dht node. It announces and looks up the topics it joined, dials the peers it finds with backoff, accepts the peers that dial it, and keeps at most one kolo-secure connection per remote key, within fixed limits on peers, inbound peers, dials and handshakes. It uses relays only when Config.Relays lists some: then a peer it cannot reach directly is dialed through a kolo-relay that both peers list. Connect dials a known key at a known address, and a connection the application opened another way enters through Attach.
Bootstrap with no servers and no Config.BootstrapNodes joins the public network: Ciranda's entry nodes learn the node's IP address and public key, and an announced topic hash and IP address become visible there. Pass an explicit list to stay private.
v0.1.x is IPv4 only, and IPv6 input, IPv4-mapped included, is refused with ErrInvalidArgument.
Experimental: the API may change before v1.0.0.
Variáveis
var (
// ErrInvalidConfig means a Config field is out of range, here or in kolo-dht (whose error is wrapped).
ErrInvalidConfig = errors.New("koloswarm: invalid config")
// ErrInvalidArgument means a nil identity or Conn, an IPv6 address (v0.1.x is IPv4 only), invalid JoinOptions, a
// topic already joined, MaxTopics reached, or a Connect key, topic or address that cannot be used.
ErrInvalidArgument = errors.New("koloswarm: invalid argument")
// ErrClosed means the swarm is closed.
ErrClosed = errors.New("koloswarm: closed")
// ErrRefused means a connection was refused by Allow, a limit, the lack of a shared topic, or the peer; for
// Connect also the key's, host's or address's backoff, the dial rate, or Leave of the topic.
ErrRefused = errors.New("koloswarm: connection refused")
// ErrWait wraps ErrRefused: Connect was refused for now by a backoff (of the key, the address, the key at the
// address, or the host), the dial rate, a dial to the host in progress, or MaxConnecting dials running.
ErrWait = fmt.Errorf("%w: wait", ErrRefused)
// ErrDuplicate means the pair of keys already has a connection that this one does not replace, or, for Connect, a
// lookup dial, a proved dial or a hello of the key, or a Connect dial of it at the same address.
ErrDuplicate = errors.New("koloswarm: duplicate connection")
// ErrProtocol means the peer sent a malformed hello, or none in time.
ErrProtocol = errors.New("koloswarm: protocol error")
// ErrLost means a connection ended for another reason: the peer closed it, or it timed out or failed; or a Connect
// dial failed.
ErrLost = errors.New("koloswarm: connection lost")
)Funções
func LoadNodes
func LoadNodes(path string) ([]string, error)LoadNodes reads a file of bootstrap nodes: one host:port per line, as in ParseNodes, where "#" starts a comment and blank lines are ignored. It reads only a regular file of at most 64 KiB; a bad line is ErrInvalidArgument.
func ParseNodes
func ParseNodes(s string) ([]string, error)ParseNodes parses a comma-separated list of at most 16 bootstrap nodes, each host:port with an IPv4 address or a host name and a port from 1 to 65535. Spaces around entries and empty entries are ignored and duplicates dropped; IPv6 in any form, port 0, more entries or anything else invalid is ErrInvalidArgument.
Tipos
type Config
type Config struct {
// DHT is passed to kolodht.New. A zero MaxAnnouncements becomes MaxTopics, a lower one is refused, and zero
// kolo-transport MaxDialed, MaxConns and MaxMemory are raised to cover MaxPeers, and MaxMemory also the growth
// WindowGrowth allows. With Allow set, WindowGrowth lets the connections Allow admitted grow their windows.
DHT *kolodht.Config
// MaxPeers caps connected peers plus dials in progress, inbound and outbound. Default 64, from 1 to 1024.
MaxPeers int
// MaxInbound caps the peers that connected to us. Default MaxPeers/2 rounded up, from 1 to MaxPeers.
MaxInbound int
// MaxConnectPeers caps the places Swarm.Connect holds. Default MaxPeers/4, from 1 to MaxPeers - MaxInbound; when
// MaxInbound equals MaxPeers it must be unset, and Connect is always refused.
MaxConnectPeers int
// MaxTopics caps the topics joined at once. Default 16, from 1 to 32.
MaxTopics int
// MaxConnecting caps kolo-dht Connect calls in progress, and separately relay dials and Swarm.Connect dials, and
// is also the Swarm.Connect dial starts per RetryMin. Default 3, from 1 to 16.
MaxConnecting int
// MaxHandshakes caps hellos in progress. From 4 up, a quarter is kept for Attach and another for known keys (an
// outbound slot, or an outbound connection that lasted 15s). Default 16, from 1 to 256.
MaxHandshakes int
// MaxHandshakesPerIP caps hellos in progress from one source host, or through one relay. Default 4 (or
// MaxHandshakes if lower), from 1 to MaxHandshakes.
MaxHandshakesPerIP int
// MaxCandidates caps the keys kept from lookups, split equally between joined topics; the backoff of up to twice
// as many dropped keys, and keys Swarm.Connect dialed, is kept. Default 1024, from 16 to 32768.
MaxCandidates int
// MaxEvents caps the queued Found events, and separately the queued Unreachable events; more are dropped.
// Default 64, from 16 to 4096.
MaxEvents int
// HelloTimeout bounds the hello on a new connection. Default 10s, from 1s to 60s.
HelloTimeout time.Duration
// LookupInterval is the time between lookups of a topic, plus up to a fifth of it at random. Default 10m, from
// 1s to 1h.
LookupInterval time.Duration
// RetryMin is the shortest wait before dialing a key again, and the period in which Swarm.Connect starts at most
// MaxConnecting dials, so raising it slows Connect. Default 1s, from 100ms to 1m.
RetryMin time.Duration
// RetryMax is the longest wait before dialing a key again. Default 10m, from RetryMin to 1h.
RetryMax time.Duration
// Allow, if set, is asked before every dial and every new connection; false or a panic refuses. addr is the
// address to dial or the connection's remote address, zero when the Conn has none.
Allow func(key ed25519.PublicKey, addr netip.AddrPort) bool
// BootstrapNodes are the entry nodes Bootstrap uses when it is given none: at most 16 host:port entries, each an
// IPv4 address or a host name resolved to IPv4, as from ParseNodes or LoadNodes. The default is empty, and Bootstrap
// then falls back to kolo-dht's public entry nodes, which then receive this node's IP address and public key; set
// it to stay off the public network.
BootstrapNodes []string
// Relays, if not empty, connect peers that cannot connect directly: at most 16, in order of preference. While a
// topic is joined with Announce the swarm keeps a reservation at each and admits the peers that come through
// them, and a key whose kolo-dht Connect failed is dialed through them in turn, the one that carried it last
// first, with the swarm's own DHT.Secure settings. Two peers meet through any relay both list. Empty never uses
// a relay.
Relays []Relay
}Config sets the limits of a Swarm. A zero field takes its default; out of range is ErrInvalidConfig.
type Conn
type Conn interface {
RemotePublicKey() ed25519.PublicKey
OpenStream(ctx context.Context) (*kolotransport.Stream, error)
AcceptStream(ctx context.Context) (*kolotransport.Stream, error)
OpenUniStream(ctx context.Context) (*kolotransport.SendStream, error)
AcceptUniStream(ctx context.Context) (*kolotransport.ReceiveStream, error)
Context() context.Context
Close() error
CloseWithError(code uint64, msg string) error
}Conn is an authenticated connection to one peer; *kolosecure.Conn and *kolorelay.Conn both satisfy it. RemotePublicKey must be a key the connection has proved, as those two do; the swarm trusts it without a check.
type Event
type Event struct {
Kind EventKind
Topic Topic // set for Found and Unreachable
PublicKey ed25519.PublicKey // the remote key, or the relay's key for RelayChanged
Addr netip.AddrPort // the remote address; zero for RelayChanged
Peer *Peer // set for Connected and Lost
Err error // set for Unreachable and Lost, and for RelayChanged when the reservation is not held
}Event is one thing that happened in the swarm; which fields are set depends on Kind.
type EventKind
type EventKind intEventKind says what an Event reports.
const (
// Found means a lookup of Topic returned PublicKey at Addr, for the first time since it was last absent.
Found EventKind = iota + 1
// Connected means Peer is connected; its Conn is ready for streams.
Connected
// Unreachable means kolo-dht could not connect to PublicKey, found on Topic; Err is kolodht.ErrUnreachable. With
// Config.Relays set, it comes only after the relays failed too.
Unreachable
// Lost means the connection of a Peer returned by an earlier Connected ended. Err says why, with nothing the peer
// chose: ErrDuplicate (replaced, or closed as a duplicate), ErrClosed (closed here), ErrRefused or ErrProtocol (the
// peer refused it), or ErrLost (anything else).
Lost
// RelayChanged means the reservation at the relay whose key is PublicKey is held (Err nil) or not held; Err is
// then kolorelay.ErrNotAllowed, kolorelay.ErrLimit, kolorelay.ErrReservationEnded, kolosecure.ErrUnexpectedPeer,
// ErrInvalidConfig (that relay's key cannot be used; the swarm stops using it), ErrClosed (no announced topic is
// joined) or ErrLost (anything else). Topic, Addr and Peer are zero. Only the newest one per relay waits in the
// queue.
RelayChanged
)The event kinds.
func (EventKind) String
func (k EventKind) String() stringString returns the kind's name.
type JoinOptions
type JoinOptions struct {
// Announce publishes our record on the topic.
Announce bool
// Lookup finds the other peers of the topic and dials them.
Lookup bool
// MaxPeers caps the peers dialed or admitted for this topic. Default and maximum: Config.MaxPeers.
MaxPeers int
}JoinOptions says how to join a topic. Announce publishes our record; Lookup finds and dials others.
type Peer
type Peer struct {
// contains filtered or unexported fields
}Peer is a connected peer: one connection to one remote key.
func (Peer) Addr
func (p *Peer) Addr() netip.AddrPortAddr returns the peer's UDP address, or the zero AddrPort if its Conn has no RemoteAddr method.
func (Peer) Conn
func (p *Peer) Conn() ConnConn returns the connection; the peer is lost when its Context ends.
func (Peer) Direct
func (p *Peer) Direct() boolDirect reports whether the connection is direct, from kolo-dht or Connect, rather than through one of Config.Relays or from Attach.
func (Peer) Outbound
func (p *Peer) Outbound() boolOutbound reports whether the peer holds one of our outbound places (not capped by MaxInbound), whichever side opened the kept connection.
func (Peer) PublicKey
func (p *Peer) PublicKey() ed25519.PublicKeyPublicKey returns a copy of the peer's kolo-id public key.
func (Peer) Topics
func (p *Peer) Topics() []TopicTopics returns the topics this peer currently shares with us, as far as the peer claimed them: a topic hash is not secret, so any peer can claim it. Config.Allow, which sees the key, is where to admit only known members.
type Relay
type Relay struct {
// Addr is the relay's host:port, an IPv4 address or a host name resolved to IPv4, in the form of a
// BootstrapNodes entry. A name must point to one relay process.
Addr string
// PublicKey is the relay's kolo-id public key.
PublicKey ed25519.PublicKey
}Relay is a kolo-relay that peers of the network may list, used when a direct connection fails.
func LoadRelays
func LoadRelays(path string) ([]Relay, error)LoadRelays reads a file of relays, one host:port@key per line as in ParseRelays, where "#" starts a comment and blank lines are ignored. It reads only a regular file of at most 64 KiB; a bad line is ErrInvalidArgument.
func ParseRelays
func ParseRelays(s string) ([]Relay, error)ParseRelays parses a comma-separated list of at most 16 relays, each host:port@key with the key as 64 hex characters. Spaces and empty entries are ignored and duplicates dropped; one key with two addresses, one address with two keys, IPv6 in any form, port 0 or anything else invalid is ErrInvalidArgument.
type Swarm
type Swarm struct {
// contains filtered or unexported fields
}Swarm keeps connections to the peers of the topics it joined, on its own kolo-dht node.
func New
func New(ctx context.Context, addr string, id *koloid.Identity, cfg *Config) (*Swarm, error)New opens a kolo-dht node on addr, such as "127.0.0.1:0" or ":4000", as id, and starts the swarm on it. v0.1.x is IPv4 only: an IPv6 addr, IPv4-mapped included, is ErrInvalidArgument.
func (Swarm) Addr
func (s *Swarm) Addr() net.AddrAddr returns the local address of the node's UDP socket.
func (Swarm) Attach
func (s *Swarm) Attach(ctx context.Context, c Conn, outbound bool) errorAttach runs the hello on a connection the application opened (outbound if we did) and returns nil once the peer is admitted. The connection must authenticate RemotePublicKey itself, as kolo-secure and kolo-relay do: the hello carries no proof, so a key the peer merely claims lets it impersonate any key. The swarm owns c from the call on; both ends must call it at once (see the README). With Config.Relays, it counts as relayed: a direct connection to the key replaces it.
func (Swarm) Bootstrap
func (s *Swarm) Bootstrap(ctx context.Context, servers []netip.AddrPort) errorBootstrap passes servers to kolo-dht Bootstrap; its ErrNoNodes passes through, and its ErrInvalidArgument is wrapped in ours. An IPv6 server address, IPv4-mapped included, is ErrInvalidArgument. With no servers it resolves Config.BootstrapNodes instead (ErrNoNodes if none resolves), each name within 5s and ctx.
With neither, a nil servers list joins the public network: Ciranda's entry nodes built into kolo-dht learn this node's IP address and public key, and Join with Announce publishes the topic hash and IP address there. A nil slice from a flag or an empty parse counts as nil. To stay private, pass your own non-empty list or set Config.BootstrapNodes; an empty list that is not nil is ErrInvalidArgument and sends nothing.
func (Swarm) Close
func (s *Swarm) Close() errorClose closes every peer connection and the node, and waits for the swarm's goroutines. It is safe to call more than once.
func (Swarm) Connect
func (s *Swarm) Connect(ctx context.Context, topic Topic, pub ed25519.PublicKey, addr netip.AddrPort, from netip.Addr) errorConnect dials pub at addr, which the peer at from supplied (zero: unknown, so global addresses only), and runs the hello for topic; it returns nil once this dial's connection is admitted. Errors: ErrInvalidArgument for unusable arguments, ErrRefused for Allow, a limit or the peer (ErrWait when a backoff, the dial rate or dials in progress refuse it for now), ErrDuplicate when the key already has a place or a hello, or a Connect dial at addr, and ErrLost when the dial fails (wrapping kolosecure.ErrUnexpectedPeer when another key answered). See the guide for the rest.
func (Swarm) Join
func (s *Swarm) Join(ctx context.Context, topic Topic, opts *JoinOptions) errorJoin announces topic, looks it up, or both (nil opts), and connects to the peers found. With Announce it returns once kolo-dht stored our record, and its errors pass through; the topic is then not joined. Lookups run every LookupInterval in the background. If Leave(topic) runs during Join, Join returns context.Canceled. With Announce and Config.Relays, it first waits for the first reservation attempt at each relay, in parallel, except relays known down.
func (Swarm) Leave
func (s *Swarm) Leave(topic Topic)Leave stops announcing and looking up topic, and closes the peers that share no other topic with us; with Config.Relays, those closes may finish after it returns.
func (Swarm) Next
func (s *Swarm) Next(ctx context.Context) (Event, error)Next returns the next event. Connected and Lost are never dropped; Found and Unreachable are dropped past MaxEvents. A peer can be replaced by a newer connection to the same key: its Lost, with ErrDuplicate, comes before the new Connected.
func (Swarm) PublicKey
func (s *Swarm) PublicKey() ed25519.PublicKeyPublicKey returns a copy of the swarm's kolo-id public key.
type Topic
type Topic = kolodht.TopicTopic is a 32-byte topic, the same type as kolo-dht's.
Bom saber
Redes públicas e privadas
Uma rede é o conjunto de servidores da kolo-dht que se conhecem entre si, e um nó pertence à rede dos nós de entrada a partir dos quais faz bootstrap. Sem nenhuma lista, Bootstrap(ctx, nil) entra na rede pública pelos nós de entrada embutidos na kolo-dht (kolodht.PublicServers), que a Ciranda mantém no ar para todos, de graça e sem garantia de disponibilidade enquanto o Kolo for uma beta. Config.BootstrapNodes é vazia por padrão; quando é preenchida, ou quando você passa servidores, esses são usados no lugar. Uma lista vazia que não é nil é ErrInvalidArgument e não envia nada, então uma aplicação que precisa continuar privada nunca entra por engano na rede pública.
Quem fica sabendo o quê na rede pública: sem lista, os dois nós de entrada recebem o endereço IP e a chave pública do nó com o primeiro pacote, e todo nó da rede pública que ele consulta, ou que o consulta, também os vê. Com Join e Announce, o hash do topic e o endereço IP do nó são guardados na rede pública, e qualquer um que procure esse topic pode lê-los; Lookup sozinho mostra o hash do topic aos nós que ele pergunta. Nada esconde o endereço. Para continuar privado, nunca conte com o padrão: passe a sua própria lista para Config.BootstrapNodes ou para Bootstrap. Uma lista nil significa a rede pública também quando vem de uma flag, de um arquivo de configuração ou de um resultado vazio de ParseNodes, então verifique que ela não está vazia antes da chamada; uma lista vazia que não é nil é ErrInvalidArgument e serve de guarda, por exemplo servers := []netip.AddrPort{} antes de acrescentar as suas próprias entradas.
- A rede pública não precisa de configuração. Outra rede pública, cujos operadores publicam seus nós de entrada, é alcançada colocando essa lista em
Config.BootstrapNodes(vinda deParseNodesouLoadNodes), ou passando-a aBootstrap. - Uma rede privada roda os seus próprios nós de entrada. O primeiro nó de entrada começa sem lista (kolo-node
run -first, ou um servidor da kolo-dht que nunca chamaBootstrap), os outros nós de entrada fazem bootstrap a partir dele, e cada membro lista só esses nós de entrada. Rode pelo menos dois em hosts que fiquem no ar, com a porta UDP aberta.
ParseNodes analisa uma lista separada por vírgulas e LoadNodes lê um arquivo, uma entrada por linha, com comentários # e linhas em branco ignorados; um BOM UTF-8 e CRLF são aceitos, e só um arquivo regular de no máximo 64 KiB é lido. Uma entrada é host:port com um endereço IPv4 ou um nome de host e uma porta de 1 a 65535. IPv6 em qualquer forma, a porta 0, mais de 16 entradas ou uma linha ruim é ErrInvalidArgument.
Os nomes de host da lista são resolvidos para IPv4 a cada Bootstrap, com o resolvedor do sistema, em paralelo, cada nome em 5s e dentro do prazo do ctx: no máximo 8 endereços por nome e 64 no total, os endereços literais primeiro. O endereço de um nome só é mantido se for global ou estiver no escopo do endereço do próprio swarm (loopback, link-local ou privado), então uma resposta DNS não consegue apontar o swarm para uma rede local que ele não recebeu; com um endereço não especificado como 0.0.0.0 só contam respostas globais. Os endereços literais são mantidos como configurados. Nomes que não resolvem são ignorados; se nada resolve, Bootstrap devolve ErrNoNodes.
O que ela é: separação por topologia. Um servidor da kolo-dht só conhece outros servidores pelos servidores que consulta e pelos que lhe enviam requisições, e uma busca só consulta servidores conhecidos assim, então duas redes com nós de entrada diferentes nunca veem os servidores, os registros nem os peers uma da outra (um teste verifica isso com duas redes em um mesmo host).
O que ela não é: controle de acesso. A lista não é um segredo. Quem descobrir um endereço de entrada pode fazer bootstrap a partir dele, buscar topics e anunciar neles, e um nó de entrada que também conhece os servidores de outra rede junta as duas. Decida quem pode se conectar com Config.Allow e as chaves da kolo-secure, admita membros com a kolo-invite e confie só em registros assinados.
Este programa inicia uma rede privada no loopback: um primeiro nó de entrada, um segundo que se junta a ele, e dois swarms que fazem bootstrap só a partir deles e se conectam.
// Command private starts a private network on loopback: two entry nodes of its own and two swarms that bootstrap
// only from them.
package main
import (
"context"
"crypto/sha256"
"fmt"
"log"
"net"
"net/netip"
"time"
kolodht "github.com/ciranda-dev/kolo-dht"
koloid "github.com/ciranda-dev/kolo-id"
koloswarm "github.com/ciranda-dev/kolo-swarm"
)
func identity() *koloid.Identity {
id, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
return id
}
// entryNode starts a kolo-dht server; with no servers it is the first node of a new network.
func entryNode(ctx context.Context, servers []netip.AddrPort) *kolodht.Node {
n, err := kolodht.New(ctx, "127.0.0.1:0", identity(), &kolodht.Config{Server: true})
if err != nil {
log.Fatal(err)
}
if len(servers) > 0 {
if err := n.Bootstrap(ctx, servers); err != nil {
log.Fatal(err)
}
}
return n
}
func addr(n *kolodht.Node) netip.AddrPort { return n.Addr().(*net.UDPAddr).AddrPort() }
func connected(ctx context.Context, s *koloswarm.Swarm) *koloswarm.Peer {
for {
ev, err := s.Next(ctx)
if err != nil {
log.Fatal(err)
}
if ev.Kind == koloswarm.Connected {
return ev.Peer
}
}
}
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
first := entryNode(ctx, nil)
defer first.Close()
second := entryNode(ctx, []netip.AddrPort{addr(first)})
defer second.Close()
// The list an application would read from its own config, a flag or an environment variable.
nodes, err := koloswarm.ParseNodes(addr(first).String() + "," + addr(second).String())
if err != nil {
log.Fatal(err)
}
topic := koloswarm.Topic(sha256.Sum256([]byte("kolo private example")))
var swarms []*koloswarm.Swarm
for range 2 {
s, err := koloswarm.New(ctx, "127.0.0.1:0", identity(), &koloswarm.Config{BootstrapNodes: nodes})
if err != nil {
log.Fatal(err)
}
defer s.Close()
if err := s.Bootstrap(ctx, nil); err != nil {
log.Fatal(err)
}
if err := s.Join(ctx, topic, nil); err != nil {
log.Fatal(err)
}
swarms = append(swarms, s)
}
p := connected(ctx, swarms[0])
connected(ctx, swarms[1])
fmt.Printf("private network: %d entry nodes, connected to %x\n", len(nodes), p.PublicKey()[:8])
}Ele imprime private network: 2 entry nodes, connected to e 16 caracteres hexadecimais. A mesma rede com o kolo-node, no loopback, com as chaves em um diretório temporário novo:
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/a/node.key" -first
kolo-node run -listen 127.0.0.1:7448 -identity "$dir/b/node.key" -bootstrap 127.0.0.1:7447Os membros então listam os dois nós de entrada, por exemplo em um arquivo lido com LoadNodes:
# entry nodes of our network
127.0.0.1:7447
127.0.0.1:7448 # second entry nodeFallback por relay
Dois peers cuja conexão direta falha, por exemplo dois computadores atrás de firewalls que só deixam passar tráfego de saída, podem se encontrar por uma kolo-relay. Cada lado roda a sua própria conexão kolo-secure através dela, então o relay copia bytes cifrados, e o alvo prova a sua chave como em uma conexão direta. A kolo-sync aceita uma conexão assim como uma direta.
Os relays são uma configuração da rede, como os nós de entrada: Config.Relays é uma lista ordenada de no máximo 16 valores Relay (Addr, PublicKey), vazia por padrão, e com a lista vazia o swarm não roda nenhum código de relay. ParseRelays e LoadRelays leem a lista como host:port@key, com a chave em 64 caracteres hexadecimais, com as regras de ParseNodes e LoadNodes:
# relays of our network
203.0.113.20:7448@<64 hex characters>
relay.example.org:7448@<64 hex characters> # resolved to IPv4 at each useNew recusa, com ErrInvalidConfig, um endereço IPv6 em qualquer forma, a porta 0, um nome inválido, uma chave que não tem 32 bytes ou que é a nossa, 17 entradas, e uma chave em dois endereços ou um endereço com duas chaves. Uma duplicata exata é descartada.
- Um peer que anuncia um topic mantém uma reserva em cada relay da lista, feita antes de
Joinanunciar. Um swarm que só entra em topics comLookupnão mantém nenhuma. Depois do últimoLeaveanunciado, o swarm fecha as suas reservas e os peers de entrada por relay que vieram por elas. - Dois peers se encontram por qualquer relay que os dois tenham na lista, identificado pela chave; as listas não precisam ter a mesma ordem. Listas sem nenhum relay em comum não dão conexão por relay.
- No primeiro contato, os relays só são tentados depois que o
Connectdireto falhou, não quando ele respondeu para tentar mais tarde: primeiro o relay que levou essa chave da última vez, depois a ordem da lista, pulando os relays sabidamente fora do ar. Uma chave que precisou de um relay antes é discada diretamente e pelos relays ao mesmo tempo, e uma conexão direta que dá certo substitui a que passa pelo relay (LostcomErrDuplicate, depoisConnectedcomDirect()verdadeiro). - O primeiro contato pode levar até 3 × o
PunchTimeoutda kolo-dht (135s no padrão dela) quando os punches começam mas nunca conectam, e depois uma discagem de no máximo 60s por relay tentado. - Um
Peerpor relay temDirect()falso e umAddr()zero. OConn()dele é um*kolorelay.ConncujoRelayPublicKey()nomeia o relay. As conexões por relay usam as configuraçõesDHT.Securedo próprio swarm, eAllowé consultado para um peer por relay com endereço zero antes do handshake de ponta a ponta. RelayChangedinforma a reserva de cada relay da lista:Errnil quando ela está mantida, oukolorelay.ErrNotAllowed,kolorelay.ErrLimit,kolorelay.ErrReservationEnded,kolosecure.ErrUnexpectedPeer(outra chave respondeu),ErrInvalidConfig(a chave não pode ser usada; esse relay deixa de ser usado),ErrClosedouErrLost.
O que o operador de um relay fica sabendo está na página da kolo-relay.
Limites
- Só IPv4. Um endereço IPv6, incluindo o IPv4-mapped, passado para
New,BootstrapouAttachéErrInvalidArgument. Um registro de busca ou uma conexão da kolo-dht com um endereço assim é descartado antes deAllowvê-lo. - Um campo de
Configzerado assume o seu padrão. Um valor fora da faixa éErrInvalidConfig. MaxPeers: 64 peers conectados mais as conexões em abertura, de entrada e de saída (de 1 a 1024).MaxInbound:MaxPeers/2 arredondado para cima, 32 com o padrão (de 1 aMaxPeers). Cada topic tem a mesma divisão: os peers de entrada ocupam no máximo ceil(MaxPeersdo topic xMaxInbound/MaxPeers) das suas vagas, 32 de 64 com os padrões. Uma conexão sem topic em comum que tenha vaga é fechada com o código 3.JoinOptions.MaxPeers: padrão e máximoConfig.MaxPeers. Fora da faixa éErrInvalidArgument.MaxTopics: 16 topics ao mesmo tempo (de 1 a 32). Acima disso,JoinretornaErrInvalidArgument. Um hello carrega no máximo 32 topics.MaxConnecting: 3 chamadas aConnectda kolo-dht ao mesmo tempo (de 1 a 16), e, contadas à parte, outras tantas discagens por relay.Config.Relays: no máximo 16 relays, vazia por padrão.MaxHandshakes: 16 hellos em andamento (de 1 a 256). A partir de 4, um quarto fica reservado paraAttache outro quarto para chaves conhecidas.MaxHandshakesPerIP: 4 hellos de um mesmo endereço IPv4 ou por um mesmo relay, ouMaxHandshakes, se for menor (de 1 aMaxHandshakes). No máximo 2 hellos rodam ao mesmo tempo por chave.MaxCandidates: 1024 chaves vindas de buscas em todos os topics, divididas igualmente entre os topics em que o swarm entrou (de 16 a 32768). O estado de backoff de até o dobro disso em chaves descartadas é mantido.MaxEvents: 64 eventosFoundna fila e, separadamente, 64Unreachable(de 16 a 4096); os mais novos são descartados. No máximo 2 xMaxPeers+ 2 xMaxEventseventos ficam esperando.HelloTimeout: 10s para um hello inteiro (de 1s a 60s). Cada etapa do hello tem 2s, ouHelloTimeout, se for menor. Um hello que perde a sua janela fecha a conexão com o código 5.LookupInterval: 10m entre buscas de um topic, mais até um quinto disso ao acaso (de 1s a 1h). As buscas são puladas enquanto o topic está no seu limite.RetryMin: 1s (de 100ms a 1m).RetryMax: 10m (deRetryMina 1h). A espera antes de abrir conexão de novo com uma chave depois de n falhas éRetryMin+ uniform[0, min(RetryMax,RetryMin·2^n) -RetryMin).- Uma conexão que dura 15s zera a contagem de falhas da sua chave; uma que termina antes disso conta como falha.
- O
ErrTryLaterda kolo-dht não é uma falha, mas cada um aumenta a espera da chave, a partir doRandomPunchIntervalda kolo-dht (20s por padrão) atéRetryMax, ou até esse intervalo, se for maior. - Um host recebe no máximo duas conexões em abertura ao mesmo tempo.
- Um HELLO tem no máximo 1026 bytes e um REPLY no máximo 1044.
DHT: umMaxAnnouncementszerado viraMaxTopics, e um menor éErrInvalidConfig. Os limites zerados da kolo-transport são aumentados:MaxDialedparaMaxPeers+MaxHandshakes+MaxPendingda kolo-secure, no mínimo 32 (144 com os padrões);MaxConnsparaMaxInbound+MaxHandshakes+MaxPending, no mínimo 100 (112 com os padrões);MaxMemorypara (MaxConns+MaxDialed) xMaxConnReceiveWindow, no mínimo 1 GiB. Dimensione esses valores para a memória que o processo pode usar, e definaGOMEMLIMITum pouco abaixo dela.BootstrapNodes: vazia por padrão, no máximo 16 entradas. Cada nome é uma consulta DNS a cadaBootstrap, e 16 nós de entrada são mais do que uma rede precisa para continuar alcançável; o limite é o mesmo do kolo-node, então a mesma lista serve nos dois.- Fixos: no máximo 8 endereços por nome de bootstrap e 64 no total, 5s por nome resolvido em paralelo dentro do
ctx, e um arquivo doLoadNodesde no máximo 64 KiB. - No loopback, todos os peers são um único host para os limites por endereço da kolo-dht e da kolo-transport. Testes com muitos peers locais precisam aumentar esses limites.
Transferências mais rápidas para peers admitidos
Um stream da kolo-transport move no máximo uma janela por tempo de ida e volta, e as janelas começam pequenas em toda conexão porque um peer hostil pode fazer um aplicativo reter memória para dados não lidos. A kolo-transport pode fazê-las crescer em uma conexão que o aplicativo marca como de confiança, e nunca fica sabendo quem é um peer. O swarm marca uma conexão quando o Allow admitiu o peer dela, então o crescimento é só para os peers que você escolheu:
cfg := &koloswarm.Config{
DHT: &kolodht.Config{Secure: &kolosecure.Config{Transport: &kolotransport.Config{
WindowGrowth: true,
MaxStreamReceiveWindow: 256 << 10,
MaxConnReceiveWindow: 256 << 10, // equal, so a connection nobody marked keeps exactly the old windows
}}},
Allow: func(key ed25519.PublicKey, addr netip.AddrPort) bool { return paired[string(key)] },
}- O crescimento é concedido a toda conexão que o
Allowadmitiu, pelo caminho aceito, pelo discado e porAttach, quando o swarm já a transformou em umPeer. Para um aplicativo cujoAllowé uma lista de pareados, isso é só o peer pareado. - Uma conexão que o
Allowrecusou, ou que o swarm não admitiu por outro motivo (sem topic em comum, cheio), nunca é marcada. SemAllownão há decisão de confiança, então o swarm não marca nada e nenhuma conexão cresce, mesmo comWindowGrowthligado. Uma conexão por relay também nunca é marcada. WindowGrowthestá desligado por padrão e então nenhuma janela cresce. Quando o swarm derivaMaxMemory(um valor zero) ele soma o crescimento queMaxGrownMemorypermite (64 MiB por padrão), então a verificação de memória da kolo-transport continua passando com qualquerMaxPeers.
Segurança
AttacheConnconfiam na chave que uma conexão informa: a conexão precisa autenticarRemotePublicKeypor conta própria, como a kolo-secure e a kolo-relay fazem, porque o hello não leva nenhuma prova.Peer.Topicsé o que o peer alegou. UseConfig.Allowpara admitir só chaves que você conhece.MaxInboundreserva parte das vagas, no geral e por topic, para peers escolhidos a partir de buscas, contra ataques de eclipse.- Metade da cota de candidatos de cada topic fica reservada para chaves conhecidas. O resto é uma amostra aleatória uniforme dos outros registros da busca; a ordem dos registros, a idade informada e o endereço alegado nunca contam.
- Uma conexão de
Attachnunca substitui uma da kolo-dht (ErrDuplicate). Uma da kolo-dht substitui uma anexada. - O
Errde um eventoLosté um sentinela puro, sem nada que o peer tenha escolhido. Peer.Conn().Close()encerra uma conexão atual, por exemplo depois que uma chave é banida.- Experimental. A API pode mudar antes da v1.0.0.
Limites conhecidos
- Dois peers só se encontram por um relay quando as suas
Config.Relaystêm um em comum. Quem disca não tem como saber onde o outro lado fez a reserva, então tenta os seus relays um de cada vez. - Sem garantia: encontrar ou alcançar todos os peers (os limites da kolo-dht), alegações de topic verdadeiras, resistência a muitas chaves vindas de um ou de muitos endereços (uma enxurrada pode lotar a parte amostrada de todas as cotas), e equilíbrio entre topics além dos limites por topic.
- Em uma abertura simultânea, cada lado pode ver
Connected,Lost,Connectedpara uma mesma chave. - Um peer cujas conexões feitas por punch estão lotadas responde “tente mais tarde” enquanto elas durarem, então a sua chave pode ficar esperando sem nenhum evento
Unreachable.
Erros
| Erro | Mensagem |
|---|---|
ErrClosed | koloswarm: closed |
ErrDuplicate | koloswarm: duplicate connection |
ErrInvalidArgument | koloswarm: invalid argument |
ErrInvalidConfig | koloswarm: invalid config |
ErrLost | koloswarm: connection lost |
ErrProtocol | koloswarm: protocol error |
ErrRefused | koloswarm: connection refused |
ErrWait | %w: wait |
Teste com errors.Is. ErrInvalidConfig envolve um erro de configuração da kolo-dht, e Bootstrap envolve o ErrInvalidArgument da kolo-dht no nosso, então os dois sentinelas correspondem; o ErrNoNodes da kolo-dht, e o ErrNotStored ou ErrNoNodes de Join com Announce, passam adiante sem mudanças. O Err de um evento Lost é ErrDuplicate (código de fechamento 2), ErrRefused (3 ou 4), ErrProtocol (5), ErrClosed (fechado aqui) ou ErrLost.
Referências
- Heilman, Kendler, Zohar and Goldberg, Eclipse Attacks on Bitcoin's Peer-to-Peer Network, USENIX Security 2015.
- Usa: os limites de conexões contra ataques de eclipse.
- RFC 8445, ICE: A Protocol for NAT Traversal (Proposed Standard, July 2018).
- Usa: o caminho por relay por último.
- Não implementa: o ICE em si.
- RFC 8656, TURN: Relay Extensions to STUN (Proposed Standard, February 2020).
- Usa: a duração das alocações.
- Não implementa: o formato de mensagens do TURN.
- RFC 9000, QUIC: A UDP-Based Multiplexed and Secure Transport (Proposed Standard, May 2021).
- Usa: os códigos de erro de aplicação (seção 20.2).
- RFC 1123, Requirements for Internet Hosts - Application and Support (Internet Standard, October 1989).
- Usa: a verificação da sintaxe dos nomes de host (seção 2.1).