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.
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.
- O seu dispositivo se conecta ao pin com kolo-secure e envia ADD com o ID do log e uma capacidade.
- 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.
- 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.
- Qualquer peer que conheça a chave do dono e o ID do log pode puxar o log do pin, como texto cifrado.
- 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-pinCompila 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.
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:
pinned 3 entries, 2305 bytes used
phone holds 3 verified entries; reading one without its key: kololog: entry key not availableO 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.
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
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
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
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_000DefaultMaxBytes is the default Options.MaxBytes: 100 GB.
const DefaultMaxOwners = 100_000DefaultMaxOwners 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) errorRemove 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) errorRevoke 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) errorServe 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) boolCovers 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 intOutcome 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() stringString 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) SelectionSelect 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
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.
- Para cada pin, o cliente calcula um peso: SHA-256 do ID do pin e do ID do log.
- Os pins são ordenados pelo peso, do mais pesado ao mais leve.
- 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.
- 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.
Capacidade e cota
Uma capacidade é a permissão assinada do dono para um pin: quais logs, quantos bytes, até quando.
- 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.
- Um dispositivo a envia no ADD. A capacidade, não a conexão, diz de quem é o espaço que o log usa.
- 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.
- 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.
- A cada minuto o pin remove os logs dos donos cuja capacidade expirou.
- 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é umhost:portIPv4. O comandokolo-pinrecusa um endereço IPv6 em-listen,-healthou-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étricaskolo_pin_owner_recordsekolo_pin_owner_records_maxmostram isso.Options.AddTimeout(-add-timeout): o máximo de tempo que umAddpode gastar, o pull incluído. Passado esse tempo oAdddáErrBusye 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 porKOLO_PIN_MAX_CONNSeKOLO_PIN_MAX_CONNS_PER_IP. Donos atrás de um mesmo NAT compartilham um endereço: aumente-max-conns-per-ippara 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
MaxBytese paraUsedaté ser excluído, então umAddpode responderErrQuotaExceededouErrDiskFullpor 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óximoAddo fixa, eRemoverespondeErrBusyenquanto 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 registradelete failed, log keptuma vez, edropped after retryquando 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ãoAddretornaErrTooLarge. 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áximoMaxCapabilitySize(8353) bytes. Os tempos são segundos Unix inteiros, até 2^53-1, eExpiresprecisa vir depois deIssued. - 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 deTimeout(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.
SelecteAddManyescolhemDefaultCopies(2) peers quando n é 0 ou menos.AddManysubstitui um peer inalcançável no máximoMaxFallback(2) vezes.Options.Dirprecisa ser privado. Ele é criado com modo 0700, eidentity.keycom 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:7452e-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,-healthou-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.UpdateouReplica.ApplyDeleteda kolo-store, que verificam antes cada assinatura, hash e prova, então ele nunca guarda uma entrada forjada.ErrInvalidquer 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/v0ekolo-pin/revoke/v0.ParseCapabilityeParseRevocationnunca 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
IssueRevocationa cobre, todos os logs desse dono são excluídos. Uma nota de revogação é assinada, então qualquer um pode entregá-la comRevoke. Addfunciona com qualquer identidade, porque a autoridade vem na capability.StatuseRemoveexigem 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-pincontê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-pinserve métricas do Prometheus em127.0.0.1:7452(-metrics,offpara desligar), eOptions.Metricsentrega as mesmas métricaskolo_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
AddManynã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
MaxBytese 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
MaxBytescom as menores entradas ocupam na memória cerca de 0,42 vezMaxBytes, 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. AjusteMaxBytes(-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
| Erro | Mensagem |
|---|---|
ErrBusy | pin: pinning peer busy |
ErrDiskFull | pin: pinning peer disk full |
ErrExpired | pin: capability expired |
ErrInvalid | pin: log data does not verify |
ErrInvalidArgument | pin: invalid argument |
ErrInvalidCapability | pin: invalid capability |
ErrNoPeer | pin: no pinning peer accepted the log |
ErrNotFound | pin: log not found |
ErrOwnerLimit | pin: owner limit reached |
ErrProtocol | pin: protocol error |
ErrQuotaExceeded | pin: owner quota exceeded |
ErrRevoked | pin: capability revoked or replaced |
ErrTooLarge | pin: too large |
ErrUnauthorized | pin: not authorized |
ErrUnreachable | pin: 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
- RFC 9162, Certificate Transparency Version 2.0 (Experimental, December 2021).
- Usa: a verificação de logs em que o peer de fixação se apoia, por meio da kolo-log e da kolo-sync.
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
- Usa: Ed25519ctx, para as assinaturas das capabilities e das notas de revogação.
- RFC 4918, HTTP Extensions for WebDAV (Proposed Standard, June 2007), status 507, and RFC 9110, HTTP Semantics (Internet Standard, June 2022), status 413.
- Usa: os limites de armazenamento, recusados antes de gravar, com respostas distintas.
- Não implementa: o HTTP em si.
- Thaler and Ravishankar, Using name-based mappings to increase hit rates, IEEE/ACM Transactions on Networking, 1998.
- Usa: o rendezvous hashing para o
Select, com pesos SHA-256.
- Usa: o rendezvous hashing para o
- NIST FIPS 180-4 (2015).
- Usa: SHA-256, para os pesos de
Select.
- Usa: SHA-256, para os pesos de