kolo docsbeta

kolo-pin

Um peer que guarda dados criptografados para outras pessoas sem conseguir lê-los.

Nesta página

Um peer de fixação mantém os logs da kolo-log de outras pessoas disponíveis enquanto os donos estão offline: o histórico de um chat, ou o que um dos seus dispositivos escreveu, para os seus outros dispositivos. Ele é uma réplica da kolo-sync sem as chaves das entradas, e verifica o que guarda como faria um monitor de Certificate Transparency (RFC 9162). Ele verifica e guarda registros assinados, textos cifrados e marcadores de exclusão, e os serve a qualquer cliente da kolo-sync, por pull ou com Fetch, mas nunca tem as chaves para lê-los. Um dono o autoriza com uma capability assinada que expira; não existem contas. O Select distribui os dados entre peers de fixação com rendezvous hashing. O pacote Go se chama pin, e o comando kolo-pin roda um peer de fixação em um servidor pequeno.

Todos os passos

Um pin só guarda texto cifrado

O pin mantém o seu log online enquanto os seus dispositivos estão desligados. Ele vê tamanhos, quantidades e horários, não o conteúdo.

  1. O seu dispositivo se conecta ao pin com kolo-secure e envia ADD com o ID do log e uma capacidade.
  2. O pin confere a capacidade e então puxa o log do seu dispositivo com kolo-sync. O seu dispositivo o oferece só com acesso ao texto cifrado, então nenhuma chave de entrada é enviada.
  3. O pin guarda os registros, o texto cifrado e os marcadores de exclusão sob o dono, e responde com as entradas, os bytes usados, a cota e a validade.
  4. Qualquer peer que conheça a chave do dono e o ID do log pode puxar o log do pin, como texto cifrado.
  5. As chaves de entrada só vêm dos dispositivos do dono. Sem elas, nem o pin nem os outros peers conseguem ler as entradas.

Instalação

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

Compila com CGO_ENABLED=0 para gerar um binário estático. O comando fica em cmd/kolo-pin; Rode um peer de fixação em uma VPS mostra o uso dele passo a passo.

Início rápido

Este programa roda um peer de fixação no loopback, com os dados em um diretório temporário. A Alice fixa um log e fica offline, e depois o celular dela puxa o texto cifrado do log a partir do peer de fixação.

main.go
package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	koloid "github.com/ciranda-dev/kolo-id"
	"github.com/ciranda-dev/kolo-pin"
	kolosecure "github.com/ciranda-dev/kolo-secure"
	kolostore "github.com/ciranda-dev/kolo-store"
	kolosync "github.com/ciranda-dev/kolo-sync"
)

func main() {
	dir, err := os.MkdirTemp("", "kolo-pin")
	if err != nil {
		log.Fatal(err)
	}
	defer os.RemoveAll(dir)
	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	// The pinning peer: its key and store live in dir.
	pid, err := pin.LoadIdentity(dir)
	if err != nil {
		log.Fatal(err)
	}
	ln, err := kolosecure.Listen(ctx, "127.0.0.1:0", pid, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer ln.Close()
	sctx, stop := context.WithCancel(ctx)
	served := make(chan error, 1)
	go func() { served <- pin.Serve(sctx, ln, pin.Options{Dir: dir}) }()
	peer := pin.Peer{ID: pid.PublicKey(), Addr: ln.Addr().String()}

	// Alice writes a log and lets the pinning peer keep it for 30 days, up to 100 MB.
	alice, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	as := kolostore.New(kolostore.NewMemory())
	l, err := as.Create(alice)
	if err != nil {
		log.Fatal(err)
	}
	for _, v := range []string{"hello", "from", "alice"} {
		if _, err := l.Append([]byte(v)); err != nil {
			log.Fatal(err)
		}
	}
	capability, err := pin.Issue(alice, pin.Capability{Peer: peer.ID, Expires: time.Now().Add(30 * 24 * time.Hour), Quota: 100_000_000})
	if err != nil {
		log.Fatal(err)
	}
	info, err := pin.Add(ctx, alice, peer, l, capability)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("pinned %d entries, %d bytes used\n", info.Entries, info.Used)
	logID := l.ID()
	as.Close() // alice goes offline

	// Her phone pulls the ciphertext from the pinning peer and checks it against her key.
	phone, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	conn, err := kolosecure.Dial(ctx, peer.Addr, phone, peer.ID, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	ps := kolostore.New(kolostore.NewMemory())
	defer ps.Close()
	header, err := kolosync.FetchHeader(ctx, conn, alice.PublicKey(), logID)
	if err != nil {
		log.Fatal(err)
	}
	rep, err := ps.OpenReplica(alice.PublicKey(), logID, header)
	if err != nil {
		log.Fatal(err)
	}
	if err := kolosync.Pull(ctx, conn, rep); err != nil {
		log.Fatal(err)
	}
	_, err = rep.Get(0)
	fmt.Printf("phone holds %d verified entries; reading one without its key: %v\n", rep.Len(), err)

	stop()
	if err := <-served; err != context.Canceled {
		log.Fatal(err)
	}
}

Ele imprime:

Texto
pinned 3 entries, 2305 bytes used
phone holds 3 verified entries; reading one without its key: kololog: entry key not available

O celular recebe as chaves das entradas depois, dos próprios dispositivos da Alice, com acesso Keys da kolo-sync. Aí só as chaves trafegam, porque o texto cifrado já está lá. Para manter um log em vários peers de fixação, veja Como escolher peers de fixação.

Referência da API

A referência da API é gerada a partir do código Go e está em inglês.

Pacote pin · github.com/ciranda-dev/kolo-pin · v0.1.0

Package pin runs and uses pinning peers: a peer that stores encrypted data for others without being able to read it.

A pinning peer keeps kolo-log logs available while their owners are offline. Serve runs one on a kolo-secure listener. Add makes it pull an owner's log over kolo-sync, as a replica without entry keys, under a capability the owner signed; Status and Remove ask about or delete a log, and Revoke delivers a revoke note. Any kolo-sync client pulls or fetches the hosted logs from it like from any other replica, as ciphertext only. Select and AddMany spread a log over several pinning peers.

Experimental: the API may change before v1.0.0.

Comando

kolo-pin
usage:
  kolo-pin run -data DIR [flags]   run a pinning peer
  kolo-pin id -data DIR            print the pinning peer's public key, creating it if needed

Run "kolo-pin run -h" for the flags and their environment variables.

kolo-pin run

kolo-pin run
Usage of kolo-pin run:
  -add-timeout time
    	the most time one add may spend pulling a log, such as 10m; default none (KOLO_PIN_ADD_TIMEOUT)
  -data dir
    	data dir, private (0700): identity.key and the store (KOLO_PIN_DATA)
  -health address
    	TCP address of the HTTP health endpoint /healthz, IPv4, or "off" (KOLO_PIN_HEALTH) (default "127.0.0.1:7451")
  -listen address
    	UDP address for kolo-secure connections, IPv4; "0.0.0.0:7450" on a VPS (KOLO_PIN_LISTEN) (default "127.0.0.1:7450")
  -log-format format
    	format of the logs on stderr: text or json (KOLO_PIN_LOG_FORMAT) (default "text")
  -log-level level
    	level: debug, info, warn or error (KOLO_PIN_LOG_LEVEL) (default "info")
  -max-bytes bytes
    	the most bytes stored for all owners, such as 500MB or 2TiB (KOLO_PIN_MAX_BYTES) (default "100GB")
  -max-conns string
    	the most connections at once, handshaking or open; default 100, up to 10000 (KOLO_PIN_MAX_CONNS)
  -max-conns-per-ip string
    	the most connections from one source address; default 4, at most -max-conns (KOLO_PIN_MAX_CONNS_PER_IP)
  -max-owners string
    	the most owner records kept, one per owner key ever seen; default 100000 (KOLO_PIN_MAX_OWNERS)
  -metrics address
    	TCP address of the Prometheus endpoint /metrics, IPv4, or "off" (KOLO_PIN_METRICS) (default "127.0.0.1:7452")
  -owners keys
    	comma-separated hex owner keys to accept; empty accepts any owner, and anyone can then fill the disk (KOLO_PIN_OWNERS)

kolo-pin id

kolo-pin id
Usage of kolo-pin id:
  -data dir
    	data dir, private (0700): identity.key and the store (KOLO_PIN_DATA)

Constantes

const (
	// CapabilityContext is the Ed25519ctx context of a capability signature.
	CapabilityContext = "kolo-pin/capability/v0"
	// RevokeContext is the Ed25519ctx context of a revoke note signature.
	RevokeContext = "kolo-pin/revoke/v0"
	// MaxLogs is the most log IDs one capability lists.
	MaxLogs = 256
	// MaxCapabilitySize is the size of a capability that lists MaxLogs logs.
	MaxCapabilitySize = 1 + 2*32 + 3*10 + 2 + MaxLogs*32 + ed25519.SignatureSize
)
const (
	// DefaultCopies is the number of pinning peers Select and AddMany choose when n is 0 or less.
	DefaultCopies = 2
	// MaxFallback is how many more peers AddMany tries, in Select's order, when chosen ones are unreachable.
	MaxFallback = 2
)
const (
	// MaxRequestSize is the largest request a pinning peer reads: an ADD with a capability of MaxLogs logs.
	MaxRequestSize = 1 + 1 + kololog.LogIDSize + 2 + MaxCapabilitySize
	// Timeout bounds reading one request and writing one answer.
	Timeout = 60 * time.Second
)
const DefaultMaxBytes = 100_000_000_000

DefaultMaxBytes is the default Options.MaxBytes: 100 GB.

const DefaultMaxOwners = 100_000

DefaultMaxOwners is the default Options.MaxOwners: a revoke-only record is about 50 bytes and a capability at most 8353, so 100,000 records take at most 0.8 GB.

Variáveis

var (
	// ErrInvalidArgument means a nil identity, log or listener, a key of the wrong size (also in a log's header), or a missing option.
	ErrInvalidArgument = errors.New("pin: invalid argument")
	// ErrInvalidCapability means a capability or revoke note that is malformed or whose signature does not verify.
	ErrInvalidCapability = errors.New("pin: invalid capability")
	// ErrUnauthorized means the pinning peer refused the capability: another peer or owner, a log it does not
	// cover, an owner the peer does not accept, a bad signature, or an issue time in the future.
	ErrUnauthorized = errors.New("pin: not authorized")
	// ErrExpired means the capability has expired.
	ErrExpired = errors.New("pin: capability expired")
	// ErrRevoked means the capability was revoked, or replaced by a newer one from the same owner.
	ErrRevoked = errors.New("pin: capability revoked or replaced")
	// ErrQuotaExceeded means the write would take the owner past the quota in its capability.
	ErrQuotaExceeded = errors.New("pin: owner quota exceeded")
	// ErrDiskFull means the write would take the pinning peer past its total byte limit.
	ErrDiskFull = errors.New("pin: pinning peer disk full")
	// ErrOwnerLimit means the pinning peer already keeps the most owner records it accepts and the owner is not one of them.
	ErrOwnerLimit = errors.New("pin: owner limit reached")
	// ErrNotFound means the pinning peer does not hold the log for this owner.
	ErrNotFound = errors.New("pin: log not found")
	// ErrInvalid means the log the pinning peer pulled does not verify; nothing past the last valid entry was kept.
	ErrInvalid = errors.New("pin: log data does not verify")
	// ErrTooLarge means a message or log entry over kolo-sync's MaxMessageSize, or a request over MaxRequestSize.
	ErrTooLarge = errors.New("pin: too large")
	// ErrBusy means the pinning peer could not finish now, for example a sync that timed out; try again later.
	ErrBusy = errors.New("pin: pinning peer busy")
	// ErrProtocol means a malformed, truncated or unexpected message, or another protocol version.
	ErrProtocol = errors.New("pin: protocol error")
	// ErrUnreachable means the pinning peer could not be reached, or the connection broke before it answered.
	ErrUnreachable = errors.New("pin: pinning peer unreachable")
	// ErrNoPeer means AddMany found no pinning peer that accepted the log.
	ErrNoPeer = errors.New("pin: no pinning peer accepted the log")
)

Funções

func Issue

func Issue(owner *koloid.Identity, c Capability) ([]byte, error)

Issue signs c with the owner's identity and returns the encoded capability, in whole seconds.

func IssueMany

func IssueMany(owner *koloid.Identity, peers []Peer, c Capability) ([][]byte, error)

IssueMany issues c for each peer, all with the same issue time, in the order of peers.

func IssueRevocation

func IssueRevocation(owner *koloid.Identity, peer ed25519.PublicKey, through time.Time) ([]byte, error)

IssueRevocation signs a revoke note: peer drops owner's logs if its capability was issued at or before through.

func LoadIdentity

func LoadIdentity(dir string) (*koloid.Identity, error)

LoadIdentity returns the pinning peer's identity in dir, creating it (mode 0600) on first use.

func Remove

func Remove(ctx context.Context, id *koloid.Identity, peer Peer, logID kololog.LogID) error

Remove asks the pinning peer to delete the log logID; id must be the log's owner.

func Revoke

func Revoke(ctx context.Context, id *koloid.Identity, peer Peer, note []byte) error

Revoke gives the pinning peer a revoke note from IssueRevocation; anyone may deliver it.

func Serve

func Serve(ctx context.Context, node *kolosecure.Listener, opts Options) error

Serve runs a pinning peer on node, which must listen with LoadIdentity(opts.Dir), until ctx is done. It closes the connections it accepted and its store before it returns ctx.Err() or the listener's error.

Tipos

type Capability

type Capability struct {
	Owner   ed25519.PublicKey // the log owner who signs it; Issue sets it
	Peer    ed25519.PublicKey // the one pinning peer it is for
	Logs    []kololog.LogID   // the logs it covers; empty means every log of Owner
	Issued  time.Time         // newer capabilities replace older ones; zero means now in Issue
	Expires time.Time         // after this the pinning peer drops the logs
	Quota   uint64            // the most bytes Owner's logs may take on Peer; 0 means only the peer's own limit
}

Capability lets one pinning peer keep and serve an owner's logs until it expires; the owner signs it.

func ParseCapability
func ParseCapability(b []byte) (Capability, error)

ParseCapability decodes a capability and checks its owner's signature; it never panics on untrusted input. It does not check the time: the pinning peer does, against its own clock.

func (Capability) Covers
func (c Capability) Covers(logID kololog.LogID) bool

Covers reports whether c covers the log logID.

type Info

type Info struct {
	Entries uint64    // entries of the log it holds
	Used    uint64    // bytes the owner's logs take on it
	Quota   uint64    // the owner's quota from the capability in use; 0 means none
	Expires time.Time // when that capability expires and the logs are dropped
}

Info is what a pinning peer holds of one log and its owner.

func Add
func Add(ctx context.Context, id *koloid.Identity, peer Peer, log kolosync.Source, capability []byte) (Info, error)

Add asks the pinning peer to keep log under capability, and serves it the log's ciphertext until it has pulled and verified it. Call it again after new entries or deletes. id only opens the connection.

func Status
func Status(ctx context.Context, id *koloid.Identity, peer Peer, logID kololog.LogID) (Info, error)

Status returns what the pinning peer holds of the log logID; id must be the log's owner.

type Options

type Options struct {
	// Dir is the data directory, holding identity.key and the store. It must be private; it is created with mode 0700.
	Dir string
	// MaxBytes is the most bytes the peer stores for all owners together. Default DefaultMaxBytes.
	MaxBytes uint64
	// Owners lists the owner keys the peer accepts capabilities and revoke notes from. Empty accepts any owner, and
	// Serve then logs a warning: anyone can fill MaxBytes and MaxOwners.
	Owners []ed25519.PublicKey
	// MaxOwners is the most owner records the peer keeps: one per owner key with a capability in use, a held log or a
	// revoke note, which stays after expiry so a revoked capability is never accepted again. A request that would
	// add one past it is ErrOwnerLimit; owners already kept are not affected. Default DefaultMaxOwners.
	MaxOwners uint64
	// AddTimeout bounds the time one Add may spend pulling a log, entries already stored are kept. Zero means no
	// limit but the connection's idle timeout and the owner's quota.
	AddTimeout time.Duration
	// Logger receives the peer's events; nil discards them.
	Logger *slog.Logger
	// Metrics, if set, gets the peer's kolo_pin_* metrics while Serve runs. Their labels never hold keys, IDs or addresses.
	Metrics prometheus.Registerer
}

Options configures Serve.

type Outcome

type Outcome int

Outcome is what happened when AddMany tried one peer.

const (
	// Accepted means the peer pulled and verified the log.
	Accepted Outcome = iota + 1
	// Refused means the peer answered with an error, or no capability named it.
	Refused
	// Unreachable means the peer could not be reached or the connection broke.
	Unreachable
)
func (Outcome) String
func (o Outcome) String() string

String returns "accepted", "refused" or "unreachable".

type Peer

type Peer struct {
	ID    ed25519.PublicKey
	Addr  string // host:port, IPv4
	Group string // where it is hosted, such as a provider or region; used by Select
}

Peer is a pinning peer: its kolo-id key, its IPv4 address and an optional group label.

type Report

type Report struct {
	Results      []Result // every peer tried, in order
	Accepted     int      // how many peers accepted the log
	SharedGroups bool     // as in Selection
}

Report is the result of AddMany.

func AddMany
func AddMany(ctx context.Context, id *koloid.Identity, peers []Peer, log kolosync.Source, capabilities [][]byte, n int) (Report, error)

AddMany adds log to the n peers Select chooses, using the capability that names each one. An unreachable peer is replaced by the next peer in Select's order that was not chosen, at most MaxFallback times. It returns ErrNoPeer if none accepted, and ctx.Err() if ctx ended first; the Report always lists the tries made.

type Result

type Result struct {
	Peer    Peer
	Outcome Outcome
	Info    Info  // set when Accepted
	Err     error // set unless Accepted
}

Result is one peer AddMany tried.

type Revocation

type Revocation struct {
	Owner   ed25519.PublicKey
	Peer    ed25519.PublicKey
	Through time.Time
}

Revocation revokes every capability an owner issued for one pinning peer at or before Through.

func ParseRevocation
func ParseRevocation(b []byte) (Revocation, error)

ParseRevocation decodes a revoke note and checks its owner's signature; it never panics on untrusted input.

type Selection

type Selection struct {
	Peers        []Peer // the chosen peers, highest weight first
	SharedGroups bool   // there were fewer groups than peers to choose, so some chosen peers share a group
}

Selection is the result of Select.

func Select
func Select(peers []Peer, logID kololog.LogID, n int) Selection

Select returns the n peers with the highest rendezvous weight for logID, from different groups when it can. A peer without a group counts as its own group. Peers with an invalid ID are skipped, and of repeated IDs one is kept.

Bom saber

Todos os passos

Como um pin é escolhido

Hashing de rendezvous: todo dispositivo calcula a mesma escolha para um log, sem coordenação. Aqui os pesos estão encurtados.

  1. Para cada pin, o cliente calcula um peso: SHA-256 do ID do pin e do ID do log.
  2. Os pins são ordenados pelo peso, do mais pesado ao mais leve.
  3. Select pega o pin mais pesado de cada grupo até ter cópias suficientes, 2 por padrão. O pin 1 é pulado: o grupo dele já tem o pin 3. Com poucos grupos, os próximos mais pesados completam.
  4. Adicione o pin 5, em um grupo novo. Para este log ele fica em segundo, então toma o lugar do pin 4. Um log em que ele não fica no topo continua como estava.
Todos os passos

Capacidade e cota

Uma capacidade é a permissão assinada do dono para um pin: quais logs, quantos bytes, até quando.

  1. O dono emite uma capacidade para um pin: a chave do pin, os horários de emissão e de validade, uma cota em bytes e os logs que ela cobre (nenhum listado quer dizer todos), assinada pelo dono.
  2. Um dispositivo a envia no ADD. A capacidade, não a conexão, diz de quem é o espaço que o log usa.
  3. O pin confere a assinatura, que ela nomeia este pin e cobre o log, que o dono é permitido, que ela não foi emitida mais de 60 segundos à frente do relógio do pin e que não expirou.
  4. Em cada escrita o pin soma os bytes novos ao total do dono. Passar da cota dá ErrQuotaExceeded e passar do limite do pin, ErrDiskFull. Exclusões sempre passam; nada é despejado.
  5. A cada minuto o pin remove os logs dos donos cuja capacidade expirou.
  6. REVOKE, assinado pelo dono, cancela todas as capacidades emitidas até um momento. O pin remove os logs do dono se a atual for cancelada.

Limites

  • Só IPv4. Peer.Addr é um host:port IPv4. O comando kolo-pin recusa um endereço IPv6 em -listen, -health ou -metrics, incluindo a forma v4-mapped, e sai com 2.
  • Options.MaxBytes, o total de todos os donos: DefaultMaxBytes, 100 GB. Uma gravação além disso é ErrDiskFull.
  • Capability.Quota, por dono, em bytes: 0 quer dizer só o limite do próprio peer. Uma gravação além disso é ErrQuotaExceeded.
  • Options.MaxOwners (-max-owners): os registros de dono que o peer guarda, um por chave de dono que já teve uma capacidade ou nota de revogação aceita, DefaultMaxOwners, 100.000. Uma nota ou capacidade de uma chave nova além do limite é ErrOwnerLimit (código de resposta 11), então chaves descartáveis não conseguem encher o disco nem fazer cada início ler uma lista sem limite. Os donos já guardados nunca são recusados, e o registro de uma chave não cresce com as notas dela. As métricas kolo_pin_owner_records e kolo_pin_owner_records_max mostram isso.
  • Options.AddTimeout (-add-timeout): o máximo de tempo que um Add pode gastar, o pull incluído. Passado esse tempo o Add dá ErrBusy e as entradas guardadas até ali são mantidas. O padrão é nenhum limite.
  • As conexões vêm dos limites da kolo-transport, definidos por -max-conns (100 por padrão, de 1 a 10.000, em handshake ou abertas) e -max-conns-per-ip (4 por padrão, no máximo -max-conns), ou por KOLO_PIN_MAX_CONNS e KOLO_PIN_MAX_CONNS_PER_IP. Donos atrás de um mesmo NAT compartilham um endereço: aumente -max-conns-per-ip para eles.
  • Os dois limites são verificados antes de qualquer coisa ser guardada, e nada é removido para abrir espaço. Os bytes são contados como chaves e valores guardados, não como blocos de disco. As exclusões sempre passam, então um dono acima de uma cota reduzida ainda consegue excluir.
  • Se uma exclusão falha (um erro de disco, ou o log do dono aberto no mesmo processo), o log fica no disco e continua contando para a cota do dono, para MaxBytes e para Used até ser excluído, então um Add pode responder ErrQuotaExceeded ou ErrDiskFull por um espaço que o dono não vê. Um log que a capability em uso ainda cobre continua sendo servido, então o próximo Add o fixa, e Remove responde ErrBusy enquanto a exclusão dele falha. Um log que ela não cobre não é oferecido nem informado: a varredura tenta a exclusão de novo depois de um minuto, e depois de cada vez o dobro do tempo, até 64 minutos, assim como a próxima inicialização. O comando registra delete failed, log kept uma vez, e dropped after retry quando uma tentativa seguinte dá certo.
  • Uma entrada precisa caber em uma única mensagem da kolo-sync, MaxMessageSize (4 MiB), junto com o seu registro e o custo extra da criptografia, senão Add retorna ErrTooLarge. Uma entrada de exatamente 4 MiB já é grande demais. Divida arquivos grandes em várias entradas.
  • Uma capability lista no máximo MaxLogs (256) IDs de log, ou nenhum para todos os logs do dono, e tem no máximo MaxCapabilitySize (8353) bytes. Os tempos são segundos Unix inteiros, até 2^53-1, e Expires precisa vir depois de Issued.
  • O peer de fixação aceita um horário de emissão de no máximo 60s no futuro em relação ao próprio relógio, e verifica as capabilities expiradas a cada minuto.
  • Uma requisição tem no máximo MaxRequestSize (8389) bytes. As requisições de uma conexão são respondidas uma de cada vez, e cada uma é lida e respondida dentro de Timeout (60s).
  • A conexão a um peer de fixação desiste depois de 10s, com ErrUnreachable.
  • Um log aberto é fechado depois de um minuto sem uso, e no máximo 64 ficam abertos ao mesmo tempo. Os usados há mais tempo são fechados primeiro, nunca um que está recebendo um pull.
  • Select e AddMany escolhem DefaultCopies (2) peers quando n é 0 ou menos. AddMany substitui um peer inalcançável no máximo MaxFallback (2) vezes.
  • Options.Dir precisa ser privado. Ele é criado com modo 0700, e identity.key com modo 0600. Um diretório que outros possam acessar é recusado.
  • O comando kolo-pin: por padrão, -listen é 127.0.0.1:7450, -health é 127.0.0.1:7451, -metrics é 127.0.0.1:7452 e -max-bytes é 100GB. Ele sai com 0 depois de SIGINT ou SIGTERM, com 1 quando não consegue iniciar (como uma porta já em uso) e com 2 em uma flag inválida, inclusive um endereço inválido em -listen, -health ou -metrics.

Segurança

  • O peer de fixação vê quais chaves de dono e IDs de log ele hospeda, quantas entradas eles têm e os seus tamanhos, os registros assinados, quando cada log cresce, tem algo excluído ou é puxado, e, em cada requisição, a chave, o endereço IP e os tempos de quem fez a requisição. Ele não consegue ler as entradas. Qualquer um que conheça uma chave de dono e um ID de log pode puxar dele o texto cifrado e os registros desse log, ou pedi-los com Fetch, e ficar sabendo das mesmas coisas.
  • Tudo o que ele guarda passou por Replica.Update ou Replica.ApplyDelete da kolo-store, que verificam antes cada assinatura, hash e prova, então ele nunca guarda uma entrada forjada. ErrInvalid quer dizer que o log não passou na verificação, e só o que foi verificado antes é mantido.
  • As capabilities e as notas de revogação são assinaturas Ed25519ctx do dono, com os contextos kolo-pin/capability/v0 e kolo-pin/revoke/v0. ParseCapability e ParseRevocation nunca entram em pânico com entrada não confiável.
  • Para cada dono, o peer de fixação guarda a capability mais nova. Uma mais antiga, ou outra com o mesmo horário de emissão, é ErrRevoked; receber a mesma de novo não tem problema. Uma mais nova substitui a anterior na hora: os logs que ela não cobre mais são excluídos, e a cota dela vale a partir daí.
  • Quando a capability expira, ou uma nota de revogação de IssueRevocation a cobre, todos os logs desse dono são excluídos. Uma nota de revogação é assinada, então qualquer um pode entregá-la com Revoke.
  • Add funciona com qualquer identidade, porque a autoridade vem na capability. Status e Remove exigem que a chave da conexão seja a do dono do log.
  • A exclusão é de melhor esforço. O peer de fixação aplica os novos marcadores de exclusão de um dono no próximo Add, conforme a kolo-sync os entrega, e descarta os textos cifrados deles nessa mesma gravação. Um peer que não segue o protocolo guarda o que tem, e blocos de disco antigos ainda podem conter bytes excluídos. Veja Exclusão.
  • Nenhum erro carrega bytes que um peer enviou. Os logs do comando kolo-pin contêm chaves públicas, IDs de log, endereços e tamanhos, nunca uma chave privada, uma seed ou uma chave de entrada.
  • O comando kolo-pin serve métricas do Prometheus em 127.0.0.1:7452 (-metrics, off para desligar), e Options.Metrics entrega as mesmas métricas kolo_pin_* a quem usa a biblioteca. Elas só contêm totais do peer inteiro e valores fixos de rótulo, nunca uma chave de dono, um ID de log, uma chave de peer, um endereço IP ou um número por dono. O endpoint não tem autenticação, então mantenha-o no loopback. Veja Monitorar um peer de fixação.

Limites conhecidos

  • AddMany não tenta de novo em segundo plano. Chame a função outra vez.
  • Os clientes chegam a um peer de fixação diretamente, no endereço em que ele escuta, então ele precisa de um endereço que todos eles alcancem. O Kolo Chat nunca chega a um pin por um relay.
  • Não há limite de taxa de requisições além da cota do dono, de MaxBytes e dos limites de conexão, stream, tamanho e tempo da kolo-transport e da kolo-sync.
  • Um log aberto mantém na memória os hashes da sua árvore e uma cópia compacta de cada registro, cerca de 250 bytes por entrada, e lê os textos cifrados do disco. O limite de 64 logs abertos conta logs, não entradas, então essa memória é limitada pelo disco, não pela RAM. No pior caso, 64 logs abertos que enchem MaxBytes com as menores entradas ocupam na memória cerca de 0,42 vez MaxBytes, cerca de 40 GB para um peer cheio de 100 GB, e qualquer peer que conheça as chaves de dono e os IDs de log deles pode fazer o peer de fixação abri-los. Ajuste MaxBytes (-max-bytes) e as cotas dos donos à RAM que você tem.
  • Abrir um log o lê e o verifica inteiro, então ler muitos logs ociosos custa ao peer de fixação CPU e leituras de disco.
  • Todos os testes rodam em 127.0.0.1. Travessia de NAT real, uma VPS real, stores de muitos gigabytes, um sistema de arquivos cheio (informado como ErrBusy), diferença de relógio acima de 60s e uso de memória por muito tempo com muitos donos não são testados.
  • Experimental. A API pode mudar antes da v1.0.0.

Erros

ErroMensagem
ErrBusypin: pinning peer busy
ErrDiskFullpin: pinning peer disk full
ErrExpiredpin: capability expired
ErrInvalidpin: log data does not verify
ErrInvalidArgumentpin: invalid argument
ErrInvalidCapabilitypin: invalid capability
ErrNoPeerpin: no pinning peer accepted the log
ErrNotFoundpin: log not found
ErrOwnerLimitpin: owner limit reached
ErrProtocolpin: protocol error
ErrQuotaExceededpin: owner quota exceeded
ErrRevokedpin: capability revoked or replaced
ErrTooLargepin: too large
ErrUnauthorizedpin: not authorized
ErrUnreachablepin: pinning peer unreachable

Teste os erros com errors.Is. Uma resposta do peer de fixação volta como o próprio valor de erro, como ErrQuotaExceeded. ErrUnreachable e ErrInvalidArgument de uma conexão que falhou envolvem o erro da kolo-secure. Quando ctx termina primeiro, as funções do cliente retornam ctx.Err(), e AddMany também, em vez de ErrNoPeer; cada Result no seu Report mantém o seu próprio Err.

Referências