Um convite deixa alguém novo entrar em um grupo. Um membro, quem convida, cria um convite e recebe um código curto para enviar. A pessoa que entra usa o código, e quem convida aceita o pedido na hora ou aprova ou recusa. O código carrega uma impressão digital da chave da kolo-id de quem convida e um segredo de 256 bits, nunca um endereço: quem entra encontra quem convida em um topic da kolo-swarm derivado do segredo, ou usa uma conexão que já tem. Quem convida guarda os seus convites e quem entrou em um backend da kolo-store, então uma reinicialização mantém tudo. O pedido de entrada e a sua resposta são selados com o HPKE (RFC 9180), e todo valor público é derivado do segredo do convite com o HKDF (RFC 5869), então o segredo em si nunca viaja. O pacote Go se chama invite. Um convite de dispositivo, por sua vez, vincula um dispositivo novo a uma pessoa, com um certificado da kolo-id.
Entrar com um código de convite
Você mesmo passa o código para quem entra. Ele não tem endereço: quem entra encontra quem convida pelo DHT.
- Quem convida cria 32 bytes aleatórios, o segredo. O código é koloinv0 e 84 caracteres base32: uma impressão digital da chave de quem convida, o segredo e um checksum. Do segredo saem o ID do convite, um topic, um valor de autenticação e uma chave de cifra.
- Quem convida se anuncia no topic do convite. Quem entra lê o código, busca o topic e só fica com um peer cuja chave bata com a impressão digital.
- Quem entra envia OPEN e recebe um desafio novo de 32 bytes. O seu REQUEST vai selado com HPKE para a chave do convite: o valor de autenticação, a sua chave, uma chave para a resposta, os seus dados e a sua assinatura.
- Quem convida envia RECEIVED na hora e depois confere o pedido. Um convite automático aceita na hora; um manual espera Accept ou Deny.
- ANSWER vai selado para a chave de resposta de quem entra: aceito com o payload, ou recusado, expirado, esgotado ou revogado.
Instalação
go get github.com/ciranda-dev/kolo-invitePrecisa do Go 1.26 ou mais recente, por causa de crypto/hpke. Compila sem cgo. Convide alguém para um grupo, em um programa de terminal mostra um programa completo passo a passo.
Início rápido
Este programa roda um nó de bootstrap, alguém que convida e alguém que entra, tudo no loopback, com os convites em um diretório temporário. A Alice cria um convite que precisa da aprovação dela, o Bob entra com o código e a Alice aprova.
package main
import (
"context"
"fmt"
"log"
"net"
"net/netip"
"os"
"path/filepath"
"time"
kolodht "github.com/ciranda-dev/kolo-dht"
koloid "github.com/ciranda-dev/kolo-id"
invite "github.com/ciranda-dev/kolo-invite"
kolostore "github.com/ciranda-dev/kolo-store"
koloswarm "github.com/ciranda-dev/kolo-swarm"
)
func identity() *koloid.Identity {
id, err := koloid.Generate()
if err != nil {
log.Fatal(err)
}
return id
}
// swarm looks its topics up every 5 seconds instead of every 10 minutes, so Bob finds Alice's invite fast.
func swarm(ctx context.Context, id *koloid.Identity, server netip.AddrPort) *koloswarm.Swarm {
sw, err := koloswarm.New(ctx, "127.0.0.1:0", id, &koloswarm.Config{LookupInterval: 5 * time.Second})
if err != nil {
log.Fatal(err)
}
if err := sw.Bootstrap(ctx, []netip.AddrPort{server}); err != nil {
log.Fatal(err)
}
return sw
}
func main() {
dir, err := os.MkdirTemp("", "kolo-invite")
if err != nil {
log.Fatal(err)
}
defer os.RemoveAll(dir)
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
// A bootstrap node on loopback, so peers can find each other.
server, err := kolodht.New(ctx, "127.0.0.1:0", identity(), &kolodht.Config{Server: true})
if err != nil {
log.Fatal(err)
}
defer server.Close()
saddr := server.Addr().(*net.UDPAddr).AddrPort()
// Alice, the inviter: her invites live in dir.
alice := identity()
db, err := kolostore.OpenPebble(filepath.Join(dir, "invites"))
if err != nil {
log.Fatal(err)
}
defer db.Close()
in, err := invite.Open(db, alice, nil)
if err != nil {
log.Fatal(err)
}
defer in.Close()
asw := swarm(ctx, alice, saddr)
defer asw.Close()
go in.Announce(ctx, asw)
go func() {
for {
ev, err := asw.Next(ctx)
if err != nil {
return
}
if ev.Kind == koloswarm.Connected {
go in.ServePeer(ctx, ev.Peer)
}
}
}()
go func() {
for {
ev, err := in.Next(ctx)
if err != nil {
return
}
if ev.Kind == invite.Requested {
fmt.Printf("request from %q\n", ev.Data)
if err := in.Approve(ev.Request, []byte("welcome to the group")); err != nil {
log.Print(err)
}
}
}
}()
s, info, err := in.Create(&invite.CreateOptions{TTL: time.Hour, Manual: true})
if err != nil {
log.Fatal(err)
}
fmt.Printf("invite code, %d characters: %s\n", len(s), s)
// Bob, the joiner, got the code from Alice in a message.
bob := identity()
bsw := swarm(ctx, bob, saddr)
defer bsw.Close()
code, err := invite.Parse(s)
if err != nil {
log.Fatal(err)
}
if err := bsw.Join(ctx, code.Topic(), &koloswarm.JoinOptions{Lookup: true}); err != nil {
log.Fatal(err)
}
for {
ev, err := bsw.Next(ctx)
if err != nil {
log.Fatal(err)
}
if ev.Kind != koloswarm.Connected || !code.Matches(ev.Peer.PublicKey()) {
continue
}
payload, err := invite.JoinConn(ctx, ev.Peer.Conn(), bob, code, &invite.JoinOptions{Data: []byte("Bob")})
if err != nil {
log.Fatal(err)
}
fmt.Printf("bob joined: %s\n", payload)
break
}
bsw.Leave(code.Topic())
joiners, err := in.Joiners(info.ID)
if err != nil {
log.Fatal(err)
}
fmt.Printf("alice's store: %d joiner, who sent %q\n", len(joiners), joiners[0].Data)
}Ele imprime isto, com um código novo a cada execução:
invite code, 92 characters: koloinv0tttsxqasttqy4saldb5klkuuqj3f5oaoiyznmxnpyeeeivyqzsta3exv4cfgqos2rupudbqrbi5eh7zdviqa
request from "Bob"
bob joined: welcome to the group
alice's store: 1 joiner, who sent "Bob"O código é a única coisa que a Alice envia para o Bob, pelo meio em que ela confiar. A aplicação mantém o seu único swarm e o seu próprio loop de eventos: Announce roda ao lado dele, e o loop chama ServePeer do lado de quem convida e JoinConn do lado de quem entra. Joiners lê o store, então esse registro sobrevive a uma reinicialização. Aqui os swarms buscam os seus topics a cada 5 segundos, porque o Bob pode buscar antes de a Alice anunciar; com o padrão da kolo-swarm, ele poderia esperar até uns 12 minutos pela próxima busca.
Vincular um dispositivo
Um convite de dispositivo adiciona um dispositivo novo a uma pessoa, com certificados de dispositivo da kolo-id. Um dispositivo aprovador cria o convite, o dispositivo novo mostra 12 dígitos, a pessoa os digita no aprovador, e o aprovador assina um certificado para a chave do dispositivo novo e o devolve dentro da resposta selada. A chave de pessoa, derivada das 24 palavras, nunca fica em um dispositivo, e um convite nunca leva as palavras. Isso precisa da kolo-id v0.1.0.
No dispositivo aprovador, cuja identidade é a que Open recebe:
CreateDevice(opts)cria um conviteManualde um único uso. O código duraDefaultDeviceTTL, 5 minutos, a menos queDeviceOptions.TTLdefina outro valor positivo, eInfo.Deviceé true. Mostre o código só para o dispositivo novo.- Em um evento
Requested,PendingLink(req)devolve a chave do dispositivo novo e o nome que ele escolheu, nunca os dígitos. A pessoa digita emMatchDevice(typed)os 12 dígitos que o dispositivo novo mostra, e ela devolve umDeviceMatchpara o pedido pendente com esses dígitos, ouErrFingerprint. Os espaços são ignorados e a comparação leva um tempo constante. Quando a mesma chave pede de novo com outro nome, a correspondência deixa de valer (ErrNotFound) e a pessoa digita os dígitos outra vez. ApproveDevice(match, &DeviceApproval{...})vincula um dispositivo comum.Signeré a identidade deste dispositivo,Certo seu certificado de aprovador eSerialo número de série do certificado novo, no mínimo 1, escolhido por quem chama. Um certificado de aprovador expirado, ou um comum, éErrNotApprover.ApproveApprover(match, &ApproverApproval{...})vincula um aprovador.Personé uma função que deriva a chave de pessoa das 24 palavras digitadas neste dispositivo, por exemplo comkoloid.Phrase.Person. Ela só roda depois de a correspondência ser verificada, e a chave que ela devolve é usada uma vez e apagada antes de a chamada retornar, com sucesso e em cada erro. É preciso exatamente um entreExpectPerson(a pessoa a que este dispositivo já pertence) eFirstDevice, ou a chamada retornaErrPersonRequired. Outra chave de pessoa, como uma frase digitada errado com uma soma de verificação válida, éErrPersonMismatche não assina nada.Deny(req)recusa um pedido de dispositivo e queima o código. Um pedido que ninguém responde dentro deOptions.DevicePendingTTL, 2 minutos por padrão, é retirado e também queima o código. Quem entra e cancela não o queima, e quem pede de novo mantém o prazo do seu primeiro pedido.Approveem um convite de dispositivo éErrInvalidArgument.
No dispositivo novo, DeviceFingerprint(code, inviterKey, deviceKey) dá os 12 dígitos a mostrar, e JoinDevice envia o pedido e devolve um DeviceLink com a chave de pessoa e o certificado pronto. DeviceJoinOptions precisa de exatamente um entre Person, a chave de pessoa que o dispositivo espera, e FirstDevice, ou a chamada retorna ErrPersonRequired. JoinDevice verifica se o certificado nomeia a chave deste dispositivo, se encadeia com a chave de pessoa, tem assinaturas válidas e foi assinado por quem convida ou pela chave de pessoa. Qualquer outra coisa é ErrProtocol. Guarde o certificado com koloid.SaveCert e apresente-o aos grupos com o pacote devices da kolo-braid.
Este programa é o examples/linkdevice do repositório. Um notebook vincula um celular como dispositivo comum e um tablet como aprovador, em loopback e em memória.
// Command linkdevice links two new devices to a person on loopback, in memory: a phone as an ordinary device, approved by
// the laptop, and a tablet as an approver, approved by the laptop after the person types the 24 words on it.
package main
import (
"context"
"crypto/ed25519"
"fmt"
"log"
"net"
"net/netip"
"time"
koloid "github.com/ciranda-dev/kolo-id"
invite "github.com/ciranda-dev/kolo-invite"
kolosecure "github.com/ciranda-dev/kolo-secure"
kolostore "github.com/ciranda-dev/kolo-store"
koloswarm "github.com/ciranda-dev/kolo-swarm"
)
func check(err error) {
if err != nil {
log.Fatal(err)
}
}
// peer is what ServePeer needs to know about a connection.
type peer struct{ conn *kolosecure.Conn }
func (p peer) Conn() koloswarm.Conn { return p.conn }
func (p peer) PublicKey() ed25519.PublicKey { return p.conn.RemotePublicKey() }
func (p peer) Addr() netip.AddrPort {
return p.conn.RemoteAddr().(*net.UDPAddr).AddrPort()
}
func (p peer) Topics() []koloswarm.Topic { return nil }
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
// The person creates a phrase on the laptop, and the person key certifies the laptop as an approver. The key is
// derived only here and then cleared: it is never stored.
phrase, err := koloid.GeneratePhrase()
check(err)
words := phrase.Words()
person, err := phrase.Person()
check(err)
phrase.Clear()
personKey := person.PublicKey()
laptop, err := koloid.Generate()
check(err)
offer, err := person.OfferDeviceCert(laptop.PublicKey(), &koloid.IssueOptions{Serial: 1, Approver: true})
check(err)
laptopCert, err := laptop.AcceptDeviceCert(offer, personKey)
check(err)
person.Clear()
// The laptop is the inviter. Its application serves every connection it accepts.
db := kolostore.NewMemory()
defer db.Close()
in, err := invite.Open(db, laptop, nil)
check(err)
defer in.Close()
ln, err := kolosecure.Listen(ctx, "127.0.0.1:0", laptop, nil)
check(err)
defer ln.Close()
go func() {
for {
c, err := ln.Accept(ctx)
if err != nil {
return
}
go in.ServePeer(ctx, peer{c})
}
}()
// Link the phone: an ordinary device. The code goes to the phone out of band.
phone, err := koloid.Generate()
check(err)
code := newCode(in)
conn, err := kolosecure.Dial(ctx, ln.Addr().String(), phone, laptop.PublicKey(), nil)
check(err)
defer conn.Close()
shown, err := invite.DeviceFingerprint(code, laptop.PublicKey(), phone.PublicKey())
check(err)
fmt.Println("the phone shows:", shown)
done := make(chan *invite.DeviceLink, 1)
go func() {
link, err := invite.JoinDevice(ctx, conn, phone, code, &invite.DeviceJoinOptions{Name: "Maria's phone", Person: personKey})
check(err)
done <- link
}()
req := nextRequest(ctx, in)
fmt.Printf("the laptop shows the request of %q and asks for the digits the phone shows\n", req.Name)
// The person types the digits the phone shows; only what matches a pending request can be approved.
match, err := in.MatchDevice(shown)
check(err)
check(in.ApproveDevice(match, &invite.DeviceApproval{Signer: laptop, Cert: laptopCert, Serial: 1}))
link := <-done
fmt.Println("phone is an ordinary device of the person:", link.Person.Equal(personKey) && !link.Cert.Approver())
// Link the tablet as an approver: the person types the 24 words on the laptop, which derives the person key, signs
// and clears it at once. The words never leave the laptop.
tablet, err := koloid.Generate()
check(err)
code = newCode(in)
conn2, err := kolosecure.Dial(ctx, ln.Addr().String(), tablet, laptop.PublicKey(), nil)
check(err)
defer conn2.Close()
shown, err = invite.DeviceFingerprint(code, laptop.PublicKey(), tablet.PublicKey())
check(err)
go func() {
link, err := invite.JoinDevice(ctx, conn2, tablet, code, &invite.DeviceJoinOptions{Name: "Maria's tablet", Person: personKey})
check(err)
done <- link
}()
req = nextRequest(ctx, in)
match, err = in.MatchDevice(shown)
check(err)
derive := func() (*koloid.Identity, error) {
typed, err := koloid.ParseWords(words)
if err != nil {
return nil, err
}
defer typed.Clear()
return typed.Person()
}
check(in.ApproveApprover(match, &invite.ApproverApproval{Person: derive, ExpectPerson: laptopCert.Person(), Serial: 2}))
link = <-done
fmt.Println("tablet is an approver of the person:", link.Person.Equal(personKey) && link.Cert.Approver())
}
func newCode(in *invite.Inviter) invite.Code {
s, _, err := in.CreateDevice(nil)
check(err)
code, err := invite.Parse(s)
check(err)
return code
}
// nextRequest waits for the next request of a link-a-device invite and returns what an approver shows.
func nextRequest(ctx context.Context, in *invite.Inviter) invite.LinkRequest {
for {
ev, err := in.Next(ctx)
check(err)
if ev.Kind == invite.Requested {
req, err := in.PendingLink(ev.Request)
check(err)
return req
}
}
}Ele imprime isto, com outros dígitos a cada execução:
the phone shows: 379 379 009 487
the laptop shows the request of "Maria's phone" and asks for the digits the phone shows
phone is an ordinary device of the person: true
tablet is an approver of the person: trueOs dígitos são digitados, nunca clicados: uma aplicação não deve calculá-los no aprovador nem mostrá-los ali para confirmação, porque a barreira só se mantém enquanto a pessoa digita o que o dispositivo novo mostra. Para tornar um dispositivo comum um aprovador sem convite, a pessoa digita as 24 palavras nesse dispositivo, que verifica se a chave derivada é igual a DeviceLink.Person e certifica a si mesmo com a kolo-id; nada viaja.
Referência da API
A referência da API é gerada a partir do código Go e está em inglês.
Package invite pairs new members with an existing one: an inviter creates an invite, a joiner uses it, and the inviter accepts, approves or denies.
An invite code is a short string that carries a fingerprint of the inviter's kolo-id key and a 256-bit secret, never an address. The joiner finds the inviter on a kolo-swarm topic derived one-way from the secret, or uses a connection it already has, sends a request sealed with HPKE (RFC 9180) to a key derived from the secret and signed with its kolo-id key, and gets a sealed accept with a payload, or an explicit deny, expired, used up or revoked answer. The inviter enforces expiry on its own clock, counts uses atomically and durably, and keeps its invites and joiners in a kolo-store backend. Like kolo-sync, it works per connection: the application keeps its swarm and event loop, runs Announce, and calls ServePeer or JoinConn on its peers.
Experimental: the API may change before v1.0.0.
Constantes
const (
// DefaultDeviceTTL is how long a link-a-device code lasts when DeviceOptions.TTL is zero.
DefaultDeviceTTL = 5 * time.Minute
// DefaultMaxDeviceName is the default of Options.MaxDeviceName and DeviceJoinOptions.MaxName, in bytes.
DefaultMaxDeviceName = 64
// DefaultMaxDevicePayload is the default of DeviceJoinOptions.MaxPayload, in bytes: an answer is under 600.
DefaultMaxDevicePayload = 4096
)The link-a-device defaults.
const Linger = 5 * time.MinuteLinger is how long an ended invite stays announced and still answers (stored accepts, denies, its state); then its secret is erased.
const Prefix = "koloinv0"Prefix starts every invite code written in lower case; its last character is the format version.
Variáveis
var (
// ErrInvalidArgument means a nil identity, backend, swarm, peer or connection, bad Options or CreateOptions, a
// swarm of another identity, or a store of another inviter.
ErrInvalidArgument = errors.New("invite: invalid argument")
// ErrInvalidCode means a string that is not an invite code: wrong prefix or version, mixed case, bad base32,
// wrong length or checksum.
ErrInvalidCode = errors.New("invite: invalid invite code")
// ErrNotFound means no invite or no pending request with that ID.
ErrNotFound = errors.New("invite: not found")
// ErrClosed means the Inviter is closed.
ErrClosed = errors.New("invite: closed")
// ErrDenied means the inviter denied the request.
ErrDenied = errors.New("invite: denied")
// ErrExpired means the invite expired on the inviter's clock.
ErrExpired = errors.New("invite: expired")
// ErrUsedUp means the invite has no uses left.
ErrUsedUp = errors.New("invite: used up")
// ErrRevoked means the inviter revoked the invite.
ErrRevoked = errors.New("invite: revoked")
// ErrInvalid means the inviter could not authenticate the request: it does not know the invite, or the request
// does not decrypt or verify.
ErrInvalid = errors.New("invite: request refused as invalid")
// ErrRateLimited means the inviter refused the request under its rate limits; try again later.
ErrRateLimited = errors.New("invite: rate limited")
// ErrBusy means the inviter could not take the request now (too many pending requests in all or from this
// source, or its storage failed), or Announce is already running.
ErrBusy = errors.New("invite: busy")
// ErrTooLarge means join data over the inviter's MaxData, a payload over the joiner's MaxPayload, or a payload
// too large to send.
ErrTooLarge = errors.New("invite: too large")
// ErrProtocol means a malformed, truncated or unexpected message, another protocol version, or a peer that is
// not the inviter.
ErrProtocol = errors.New("invite: protocol error")
// ErrUnreachable means the stream or connection failed, or ctx ended, before the inviter received the request.
ErrUnreachable = errors.New("invite: inviter unreachable")
// ErrNotAnswered means the inviter received the request, but the connection failed or ctx ended before its answer.
ErrNotAnswered = errors.New("invite: request not answered")
// ErrNotApprover means the certificate that ApproveDevice was given is not an unexpired approver certificate, or the
// signer is not an approver; only an approver may link a device.
ErrNotApprover = errors.New("invite: signer is not an approver")
// ErrFingerprint means MatchDevice found no pending link-a-device request with the typed fingerprint.
ErrFingerprint = errors.New("invite: fingerprint does not match")
// ErrPersonMismatch means the person key given to ApproveApprover is not the one the approving device belongs to.
ErrPersonMismatch = errors.New("invite: person key is not the expected one")
// ErrPersonRequired means ApproveApprover or JoinDevice was given neither the person it expects nor FirstDevice.
ErrPersonRequired = errors.New("invite: expected person or FirstDevice required")
// ErrIDCollision means a new invite got the 128-bit ID of a stored one; it does not happen in practice.
ErrIDCollision = errors.New("invite: invite ID collision")
)Funções
func DeviceFingerprint
func DeviceFingerprint(code Code, inviter, device ed25519.PublicKey) (string, error)DeviceFingerprint returns the fingerprint the new device shows for code, the inviter's key (its connection's remote key) and its own device key. The code must be the inviter's (Code.Matches), else ErrInvalidArgument.
func JoinConn
func JoinConn(ctx context.Context, conn koloswarm.Conn, id *koloid.Identity, code Code, opts *JoinOptions) ([]byte, error)JoinConn asks the inviter of code, on conn, to let id join, and returns the payload of the accept. conn must be a connection to the inviter (code.Matches its remote key), for example from a Connected event of a swarm that joined code.Topic(); the inviter must run ServePeer on it. JoinConn opens one stream and waits for the answer as long as ctx allows: a Manual invite waits for a person, so give ctx a deadline or cancel it.
The answers are ErrDenied, ErrExpired, ErrUsedUp, ErrRevoked, ErrInvalid, ErrRateLimited, ErrBusy and ErrTooLarge. A failed connection or ctx ending is ErrUnreachable before the inviter received the request and ErrNotAnswered after; both wrap the cause, and asking again is safe.
Tipos
type ApproverApproval
type ApproverApproval struct {
// Person derives the person key from the words the person typed on this device. It is called only after the match checks
// pass, without the inviter's lock; its key is cleared before ApproveApprover returns, whatever the result.
Person func() (*koloid.Identity, error)
// ExpectPerson is the person key this device already belongs to; another key is ErrPersonMismatch and nothing is signed.
ExpectPerson ed25519.PublicKey
// FirstDevice says this device has no person yet, so there is nothing to expect. Exactly one of ExpectPerson and
// FirstDevice is required (ErrPersonRequired): the person key cannot be checked otherwise.
FirstDevice bool
// Serial is the serial of the new certificate, at least 1, chosen by the caller.
Serial uint64
// ExpiresAt is zero for a certificate that never expires.
ExpiresAt time.Time
}ApproverApproval is the choices of ApproveApprover.
type Code
type Code struct {
// contains filtered or unexported fields
}Code is a parsed invite code. It holds the invite secret behind a pointer, so it prints only its ID, also inside other values.
func Parse
func Parse(s string) (Code, error)Parse reads an invite code: all in lower case, or all in upper case. It does not trim spaces.
func (Code) Format
func (c Code) Format(f fmt.State, _ rune)Format prints String for every verb.
func (Code) GoString
func (c Code) GoString() stringGoString returns the same as String.
func (Code) ID
func (c Code) ID() IDID returns the invite's ID; zero for a zero Code.
func (Code) Matches
func (c Code) Matches(key ed25519.PublicKey) boolMatches reports whether key is the inviter's kolo-id key: a 16-byte fingerprint of it is in the code.
func (Code) String
func (c Code) String() stringString returns the invite ID as hex, never the secret.
func (Code) Topic
func (c Code) Topic() koloswarm.TopicTopic returns the kolo-swarm topic on which the inviter announces the invite; zero for a zero Code.
type CreateOptions
type CreateOptions struct {
// TTL is how long the invite can be used, on the inviter's clock; zero means it never expires.
TTL time.Duration
// MaxUses is how many joiners can be accepted; zero means 1 (single use).
MaxUses int
// Manual makes each request wait for Approve or Deny; otherwise requests within the invite rules are accepted.
Manual bool
// Payload is what an auto-approved joiner receives, at most 1 GiB; it must be empty with Manual.
Payload []byte
}CreateOptions describes a new invite.
type DeviceApproval
type DeviceApproval struct {
// Signer is the approving device's identity; its key must be the Inviter's.
Signer *koloid.Identity
// Cert is the approver certificate of Signer.
Cert *koloid.DeviceCert
// Serial is the serial of the new certificate, at least 1, chosen by the caller.
Serial uint64
// ExpiresAt is zero for a certificate that never expires.
ExpiresAt time.Time
}DeviceApproval is the choices of ApproveDevice.
type DeviceJoinOptions
type DeviceJoinOptions struct {
// Name is the name the approver sees; required, letters, numbers, marks, punctuation, symbols and single spaces.
Name string
// MaxName is the longest Name in bytes: default DefaultMaxDeviceName. An inviter with a smaller Options.MaxDeviceName refuses
// a longer one.
MaxName int
// MaxPayload bounds the answer JoinDevice accepts, in bytes: default DefaultMaxDevicePayload.
MaxPayload int
// Person is the person key the new device expects to join; another key is ErrProtocol.
Person ed25519.PublicKey
// FirstDevice says this device belongs to no person yet. Exactly one of Person and FirstDevice is required
// (ErrPersonRequired): without a person to compare, the approver's person key cannot be checked.
FirstDevice bool
// contains filtered or unexported fields
}DeviceJoinOptions sets what JoinDevice sends and accepts.
type DeviceLink
type DeviceLink struct {
// Person is the person key the certificate chains to: pin it as the person.
Person ed25519.PublicKey
// Cert is the finished certificate; Cert.Approver() is true only when the person key signed it (ApproveApprover).
Cert *koloid.DeviceCert
}DeviceLink is the result of JoinDevice.
func JoinDevice
func JoinDevice(ctx context.Context, conn koloswarm.Conn, id *koloid.Identity, code Code, o *DeviceJoinOptions) (*DeviceLink, error)JoinDevice asks the inviter of a link-a-device code, on conn, to link id as a device, waits for the approval and returns the certificate, after it checked it. Show DeviceFingerprint on screen before calling it. The errors are those of JoinConn; a certificate that fails a check is ErrProtocol. The checks are in docs/guide.md.
type DeviceMatch
type DeviceMatch struct {
// contains filtered or unexported fields
}DeviceMatch is a pending link-a-device request whose fingerprint the person typed. Only MatchDevice makes one, and the two approve calls take nothing else. An application must not compute the fingerprint itself (DeviceFingerprint is for the new device): it must ask the person to type what the new device shows. The match names the request as it was when matched: if the same key asks again with another name, the match no longer applies.
func (DeviceMatch) Request
func (m DeviceMatch) Request() RequestIDRequest returns the request the match names, for example to look its name up with PendingLink.
type DeviceOptions
type DeviceOptions struct {
// TTL is how long the code can be used, on the inviter's clock: default DefaultDeviceTTL; negative is an error.
TTL time.Duration
}DeviceOptions describes a link-a-device invite.
type Event
type Event struct {
Kind EventKind
Invite ID
Request RequestID
Joiner ed25519.PublicKey
Data []byte
State State
}Event is one thing that happened to the invites; which fields are set depends on Kind.
type EventKind
type EventKind intEventKind says what an Event reports.
const (
// Requested means Joiner asks to join through a Manual invite, with its Data; answer with Approve or Deny.
// Requested events are never dropped.
Requested EventKind = iota + 1
// Withdrawn means a request reported by Requested left before Approve or Deny: the joiner left or the invite ended.
Withdrawn
// Joined means Joiner was accepted, with its Data; Request is set for a Manual invite.
Joined
// Ended means the invite reached State: expired, used up or revoked.
Ended
)The event kinds.
func (EventKind) String
func (k EventKind) String() stringString returns the kind's name.
type ID
type ID [16]byteID identifies an invite; it is derived from the invite secret and reveals nothing about it.
func (ID) String
func (id ID) String() stringString returns the ID as hex.
type Info
type Info struct {
ID ID
Created time.Time
// Expires is the end of the TTL, zero for none.
Expires time.Time
// Ended is when the invite stopped being usable, zero while Active.
Ended time.Time
MaxUses int
Used int
Manual bool
// Device is set for a link-a-device invite made by CreateDevice.
Device bool
State State
}Info describes an invite.
type Inviter
type Inviter struct {
// contains filtered or unexported fields
}Inviter creates invites and answers the requests that use them. It is safe for concurrent use.
func Open
func Open(db kolostore.Backend, id *koloid.Identity, opts *Options) (*Inviter, error)Open loads the invites stored in db, a kolo-store backend used for nothing else, for the inviter id. It does not close db. The backend holds the secrets and payloads of live invites in clear: keep it private.
func (Inviter) Announce
func (in *Inviter) Announce(ctx context.Context, sw *koloswarm.Swarm) errorAnnounce keeps sw joined, announce only, to the topics of the live invites, oldest first, until ctx ends or the Inviter is closed, then leaves them. It never reads sw's events. sw must be opened with the Inviter's identity. A topic sw cannot join (MaxTopics, a network error) is tried again with backoff from 1s to 1 minute. One Announce runs at a time; another returns ErrBusy.
func (Inviter) Approve
func (in *Inviter) Approve(req RequestID, payload []byte) errorApprove accepts a pending request and sends payload (at most 1 GiB) to the joiner. It returns ErrExpired, ErrUsedUp or ErrRevoked if the invite ended, also when that ended the request, and ErrNotFound if the joiner left.
func (Inviter) ApproveApprover
func (in *Inviter) ApproveApprover(m DeviceMatch, a *ApproverApproval) errorApproveApprover links the matched device as an APPROVER of the person key a.Person derives, signed once and cleared at once. The words never reach this library or the network. The other errors are those of ApproveDevice.
func (Inviter) ApproveDevice
func (in *Inviter) ApproveDevice(m DeviceMatch, a *DeviceApproval) errorApproveDevice links the matched device as an ordinary device of the person of a.Cert. ErrNotApprover means a.Cert is not an unexpired approver certificate of a.Signer; the other errors are those of Approve. The signed offer reaches the new device inside the answer.
func (Inviter) Close
func (in *Inviter) Close() errorClose stops the Inviter: Announce and ServePeer return ErrClosed and pending requests are left unanswered. Later calls return ErrClosed, except Stats. It does not close the backend. A second Close returns nil.
func (Inviter) Create
func (in *Inviter) Create(opts *CreateOptions) (string, Info, error)Create makes a new invite, stores it, and returns its code and its Info. The code is the invite's secret: give it only to the joiner.
func (Inviter) CreateDevice
func (in *Inviter) CreateDevice(opts *DeviceOptions) (string, Info, error)CreateDevice makes a link-a-device invite: Manual, one use, short-lived, burned by a refusal or an unanswered request. The code is the invite's secret: show it only to the new device. The rules are in docs/guide.md.
func (Inviter) Deny
func (in *Inviter) Deny(req RequestID) errorDeny refuses a pending request; the joiner gets ErrDenied, now and whenever it asks again with this invite. Like Approve, it checks the invite's state first and returns the same errors. A refusal of a link-a-device request also burns its code, in memory at once; a failed store write of that end is retried by the clock and is not an error here, and one that is still failing when the process stops is lost (the invite then lives on until its TTL).
func (Inviter) Joiners
func (in *Inviter) Joiners(id ID) ([]Joiner, error)Joiners returns the joiners the invite accepted, from the store, in key order.
func (Inviter) List
func (in *Inviter) List() ([]Info, error)List returns every stored invite, ended ones included, oldest first.
func (Inviter) MatchDevice
func (in *Inviter) MatchDevice(typed string) (DeviceMatch, error)MatchDevice finds the pending link-a-device request whose fingerprint is typed, the digits the person read on the new device's screen (spaces are ignored). It returns ErrFingerprint when none matches. The comparison takes the same time for every digit.
func (Inviter) Next
func (in *Inviter) Next(ctx context.Context) (Event, error)Next returns the next event, waiting until there is one, ctx ends or the Inviter is closed.
func (Inviter) PendingLink
func (in *Inviter) PendingLink(req RequestID) (LinkRequest, error)PendingLink returns what to show for the pending request req of a link-a-device invite: ErrNotFound for a request that is gone, ErrInvalidArgument for a request of another kind of invite.
func (Inviter) Revoke
func (in *Inviter) Revoke(id ID) errorRevoke ends an active invite now; pending requests are answered revoked. An invite that already ended is left as it is.
func (Inviter) ServePeer
func (in *Inviter) ServePeer(ctx context.Context, p Peer) errorServePeer answers the invite requests p sends until its connection ends (nil), ctx ends (its error) or the Inviter is closed (ErrClosed). It must be the only caller of AcceptStream on p's connection. A peer whose shared topics are all invite topics, and that has had no stream for Timeout, is disconnected: knowing a topic is not enough to hold a connection.
func (Inviter) Stats
func (in *Inviter) Stats() StatsStats returns the Inviter's gauges and totals; it is safe to call at any time, also after Close.
type JoinOptions
type JoinOptions struct {
// Data is sent to the inviter with the request, for example a display name; the inviter refuses more than its
// MaxData (default 64 KiB) with ErrTooLarge.
Data []byte
// MaxPayload caps the payload JoinConn accepts, in bytes; a larger one is ErrTooLarge. Default 1 MiB.
MaxPayload int
// contains filtered or unexported fields
}JoinOptions sets what JoinConn sends and accepts.
type Joiner
type Joiner struct {
Key ed25519.PublicKey
Data []byte
Joined time.Time
}Joiner is a joiner an invite accepted, as stored.
type LinkRequest
type LinkRequest struct {
Request RequestID
Invite ID
// Device is the key the request is signed with, the key that would be certified.
Device ed25519.PublicKey
// Name is the name the new device chose; it proves nothing, so two requests with one name differ only by their fingerprints.
Name string
}LinkRequest is what an approver shows for a pending link-a-device request. It has no fingerprint: the person types the one the new device shows into MatchDevice.
type Options
type Options struct {
// Timeout bounds the messages of a stream until its request is decided, the write of each answer, and how long
// a connection that shares only invite topics may stay without a stream. Default 30s.
Timeout time.Duration
// PendingTTL withdraws a request that waited this long for Approve or Deny, as if its joiner had left; the joiner
// may ask again. Zero means a request waits until it is decided, the joiner leaves or the invite ends.
PendingTTL time.Duration
// MaxData caps the join data the Inviter receives in one request, in bytes. Default 64 KiB.
MaxData int
// MaxPending caps the requests waiting for Approve or Deny, all invites. Default 1024.
MaxPending int
// MaxPendingPerSource caps the pending requests from one source. Default 16.
MaxPendingPerSource int
// MaxPendingDevices caps the requests waiting for ApproveDevice, Approve or Deny on link-a-device invites, all invites
// together; the next one is refused with ErrBusy. Default 4: one new device and a few retries.
MaxPendingDevices int
// DevicePendingTTL is how long a link-a-device request waits for a person; then it is withdrawn and the invite is
// revoked, so the code is burned. Default 2 minutes.
DevicePendingTTL time.Duration
// MaxDeviceName caps the device name of a link-a-device request, in bytes. Default DefaultMaxDeviceName, range 1 to MaxData.
MaxDeviceName int
// MaxStreams caps the streams handled at once on one connection. Default 8.
MaxStreams int
// SourceRate caps the requests per minute from one source, in a bucket of that size. Default 60.
SourceRate int
// InviteRate caps the requests per minute for one invite, in a bucket of that size. Default 600.
InviteRate int
// MaxSources caps the sources the rate limiter tracks; a new source past it is rate limited. Default 4096.
MaxSources int
// MaxEvents caps the queued Joined, Withdrawn and Ended events; past it the oldest is dropped. Default 1024.
MaxEvents int
}Options sets the safety bounds of an Inviter. A zero field takes its default; a negative one is ErrInvalidArgument.
type Peer
type Peer interface {
Conn() koloswarm.Conn
Addr() netip.AddrPort
PublicKey() ed25519.PublicKey
Topics() []koloswarm.Topic
}Peer is a connected peer as kolo-swarm reports it in a Connected event; *koloswarm.Peer satisfies it.
type RequestID
type RequestID uint64RequestID identifies a pending request for Approve and Deny; it stays the same when the joiner asks again.
type State
type State intState is the state of an invite.
const (
// Active means the invite can be used.
Active State = iota + 1
// Expired means the invite's TTL is over on the inviter's clock.
Expired
// UsedUp means the invite accepted MaxUses joiners.
UsedUp
// Revoked means Revoke ended the invite.
Revoked
)The invite states.
func (State) String
func (s State) String() stringString returns the state's name.
type Stats
type Stats struct {
Active int // invites that can be used
Ended int // invites that ended, lingering ones included
Announced int // invite topics Announce has joined on the swarm
Pending int // requests waiting for Approve or Deny
Requests uint64 // requests received
Accepted uint64 // joiners accepted, each counted once
Denied uint64 // Deny calls that answered a request
RefusedInvalid uint64 // requests that did not authenticate
RefusedLimited uint64 // requests refused by a rate limit
RefusedBusy uint64 // requests refused for MaxPending, MaxPendingPerSource or a storage error
RefusedEnded uint64 // requests answered expired, used up or revoked
RefusedLarge uint64 // requests over MaxData
StreamsRefused uint64 // streams reset past MaxStreams
IdleClosed uint64 // connections closed for sharing only invite topics without a stream for Timeout
EventsDropped uint64 // events dropped past MaxEvents
}Stats are an Inviter's gauges and totals; the totals only grow.
Bom saber
Usos, validade e revogação
A validade e os usos ficam só no armazenamento de quem convida, nunca no código.
- Um convite começa Active, com uma validade (nenhuma quando o TTL é 0) e um número de usos (1 quando não é informado). Aqui ele tem 3.
- Aceitar conta um uso e guarda quem entrou. Se essa pessoa perguntar de novo, recebe a mesma resposta e nenhum uso é contado.
- Recusar guarda um não para essa pessoa e não gasta nenhum uso. O convite continua Active para os outros.
- O convite termina em um estado: UsedUp quando o último uso é gasto, Expired no fim da validade, Revoked quando você o revoga. Revoked vence UsedUp, e UsedUp vence Expired.
- Cinco minutos depois do fim, o segredo é apagado e o topic é deixado, então o código para de funcionar. Revogar não tira nada dos peers que já entraram.
Limites
- Só IPv4, como a kolo-swarm. Os limites de taxa contam por origem: o endereço IPv4 remoto da conexão, ou a chave remota quando ela não tem endereço.
Optionsreúne os limites de quem convida. Um campo zerado usa o valor padrão, e um negativo éErrInvalidArgument.Timeout, 30s: limita as mensagens de um stream até o pedido ser decidido, e a escrita de cada resposta. Um peer que só compartilha topics de convite com quem convida e fica esse tempo sem nenhum stream é desconectado. A verificação roda a cadaTimeout/4, então o fechamento acontece entreTimeoute 1,25 vezesTimeout.MaxData, 64 KiB (no máximo 1 GiB): os dados de entrada de um pedido. Mais que isso éErrTooLarge, recusado pelo tamanho do frame antes de os dados serem lidos.MaxPending, 1024: pedidos esperandoApproveouDeny, somando todos os convites.MaxPendingPerSource, 16: o mesmo, vindo de uma única origem. Acima de qualquer um dos dois, um pedido recebeErrBusy.PendingTTL, nenhum por padrão: quanto tempo um pedidoManualespera porApproveouDenyantes de ser retirado, como se quem pediu tivesse ido embora. Zero espera até ser decidido, então uma aplicação que expõe convitesManualamplamente deveria defini-lo, por exemplo para uma hora: sem ele, quem tem um código pode manter pedidos pendentes até encherMaxPending.MaxStreams, 8: streams atendidos ao mesmo tempo em uma conexão. Os excedentes são cancelados.- Os dados de entrada são um nome ou uma chave, não um arquivo: mantenha
MaxDatapequeno. Um frame é lido em um buffer que cresce com os bytes que chegam, então um peer que envia só um cabeçalho não faz o convidante alocar nada para o tamanho declarado, mas um que envia o corpo inteiro pode fazer um stream reter atéMaxDatabytes (MaxStreamsvezesMaxDatapor conexão). - O backend guarda em claro os segredos e as cargas dos convites vivos, então mantenha-o privado.
SourceRate, 60 pedidos por minuto vindos de uma origem, eInviteRate, 600 por minuto para um convite, cada um com rajadas de até esse número. Acima de qualquer um dos dois, um pedido recebeErrRateLimited.MaxSources, 4096: origens que o limitador de taxa acompanha. Uma origem cuja margem já se recarregou por completo é esquecida, e uma origem nova é limitada quando nenhuma pode ser esquecida.MaxEvents, 1024: eventosJoined,WithdrawneEndedna fila. Acima disso, o mais antigo é descartado e contado emStats.EventsDropped. Os eventosRequestednunca são descartados, e nunca passam do número de pedidos pendentes.JoinOptions.MaxPayload, 1 MiB: a maior carga útil que quem entra aceita. Mais que isso éErrTooLarge.MaxPendingDevices, 4: pedidos pendentes de convites para vincular um dispositivo, somando todos os convites. Acima disso, um pedido recebeErrBusy.MaxDeviceName, 64 bytes (de 1 aMaxData): o nome de um dispositivo novo. Um nome são letras, números, marcas, pontuação e símbolos em UTF-8 com um único espaço entre eles, sem espaço no início, no fim ou duplo, e sem caracteres de controle, de formatação, invisíveis ou ignoráveis por padrão. Qualquer outro nome é recusado como inválido.DevicePendingTTL, 2 minutos: quanto tempo um pedido para vincular um dispositivo espera pela pessoa antes de ser retirado e ter o código queimado.DeviceOptions.TTL, 5 minutos por padrão, é quanto tempo dura um código de dispositivo; qualquer valor positivo é aceito.- No dispositivo novo,
DeviceJoinOptions.MaxNameé 64 bytes eMaxPayload4096 bytes; uma resposta tem menos de 600 bytes. Uma oferta tem no máximo 450 bytes, o limite da kolo-id. - O registro guardado de um convite de dispositivo é a versão 1 e termina com uma marca
device. Os outros registros de convite são da versão 0. CreateOptions: umTTLzerado nunca expira. UmMaxUseszerado quer dizer 1, e não há limite superior.Payloadtem no máximo 1 GiB e precisa estar vazio comManual; para uma carga útil diferente por pessoa, useManuale chameApprovepelo código.- Cargas úteis e dados de entrada têm no máximo 1 GiB, porque o tamanho de um frame é um uint32. Os frames OPEN e CHALLENGE têm no máximo 64 bytes. Qualquer outro frame tem no máximo
max(512, Padmé(n + 256)) + 256bytes, em que n éMaxDatapara os pedidos, em quem convida, ouMaxPayloadpara as respostas, em quem entra, e um maior é rejeitado pelo tamanho antes de o corpo ser lido. - Um código tem 92 caracteres:
koloinv0(o0é a versão do formato) e base32.Parseaceita o código todo em minúsculas ou todo em maiúsculas, e não remove espaços. Linger, 5 minutos: quanto tempo um convite encerrado continua anunciado e respondendo. Depois o segredo dele é apagado e o topic é abandonado, e quem perdeu a sua aceitação não consegue mais recebê-la de novo.Announcedivide oMaxTopicsdo swarm (padrão 16 na kolo-swarm, no máximo 32) com os topics da própria aplicação, e ocupa com convites todos os que estiverem livres, os mais antigos primeiro. Entre nos seus próprios topics antes de iniciarAnnounce, ou aumenteMaxTopicspara caber tudo: umJoindepois dele pode falhar com o erro deMaxTopicsda kolo-swarm. Um topic em que o swarm não consegue entrar (não há nenhum livre, um erro de rede) é tentado de novo com uma espera que cresce de 1s até 1 minuto;Stats.Announcedmostra quantos estão anunciados. Um convite contado emStats.Activemas não anunciado não é encontrado por quem quer entrar: só é alcançado por uma conexão que já existe. Um convite antigo que nunca expira e nunca é usado mantém o seu topic, e os mais novos esperam atrás dele: dê umTTLaos convites, ou revogue comRevokeos que você não precisa mais.- O swarm de quem entra busca um topic quando entra nele e depois a cada
LookupInterval(padrão de 10 minutos na kolo-swarm) mais até um quinto desse tempo, ao acaso. Quem começa antes de quem convida estar online pode esperar esse tempo, até uns 12 minutos com o padrão; umLookupIntervalmenor ajuda. ApproveeDenyverificam primeiro o estado do convite e retornamErrExpired,ErrUsedUpouErrRevokedse ele terminou, também quando esse fim é o que encerrou o pedido (por exemplo, o outro de dois pedidos pendentes de um convite de uso único depois que o primeiro foi aprovado). Eles lembram os últimosMaxPendingpedidos desse tipo.- O armazenamento só cresce com o que a aplicação faz, nunca com o que os peers enviam: um registro por convite (cerca de 100 bytes mais a carga útil), um por pessoa aceita (a carga útil e os dados dela) e um marcador por
Deny. Os registros dos convites encerrados ficam, paraListeJoiners.
Segurança
- O código carrega uma impressão digital de 16 bytes da chave de quem convida. Quem entra só conversa com um peer cuja chave autenticada da kolo-secure bate com ela, e depois vincula a chave completa ao pedido. Se passar por quem convida exige uma segunda pré-imagem de um valor de 128 bits para essa chave específica.
- O segredo tem 256 bits e nunca chega à rede. A DHT vê um topic derivado dele em um só sentido, e o pedido viaja selado com HPKE (RFC 9180) dentro de uma conexão da kolo-secure, assinado pela chave da kolo-id de quem entra com o contexto
kolo-invite/request/v0. Não dá para adivinhar o segredo offline, então nenhum PAKE é usado. - Os servidores da DHT que guardam o topic de um convite veem a chave e o endereço de quem o anuncia e de cada peer que o busca. Eles conseguem ligar o endereço de quem entra à chave de quem convida no momento da entrada, e ver por quanto tempo o convite fica anunciado. Não conseguem saber qual convite é, nem ler o pedido ou respondê-lo. Uma conexão que você já tem com quem convida dispensa a busca.
- Cada stream começa com um desafio novo de 32 bytes de quem convida, vinculado ao pedido. Um pedido capturado falha em qualquer outro stream, e um stream aceita um único pedido.
- Os usos são contados em um único lote durável do store antes de a resposta ser enviada, sob uma única trava, então entradas simultâneas nunca passam de
MaxUses. Quem pergunta de novo depois de ser aceito recebe a mesma carga útil e não gasta nenhum uso. Uma recusa é guardada do mesmo jeito: essa pessoa recebeErrDeniedtoda vez que pergunta de novo com este convite. - A expiração só é verificada pelo relógio de quem convida, sem tolerância; quem entra não envia nenhum horário. Um
Approvedepois da expiração éErrExpired, mesmo para um pedido que chegou antes. Quando quem convida vê um fim, ele o guarda, e atrasar o relógio nunca reabre o convite. Atrasar o relógio antes disso estende o convite na mesma medida, e adiantá-lo encerra o convite mais cedo. - Pedidos e respostas são preenchidos até tamanhos Padmé com um mínimo de 512 bytes, então uma recusa, uma rejeição e uma aceitação com uma carga útil de até 508 bytes têm o mesmo tamanho na rede. Quem convida sempre envia RECEIVED antes de decidir ou rejeitar, manual ou não, também para um pedido rejeitado pelo tamanho. Cargas úteis e dados de entrada maiores mostram a sua faixa Padmé, no máximo cerca de 12% acima do tamanho, e o tempo até a resposta ainda revela uma decisão manual.
- Convites desconhecidos, e pedidos que não se decifram ou não se verificam, recebem o mesmo
ErrInvalid. IDs e topics vêm do segredo de 256 bits e não podem ser enumerados. Uma chave de resposta ou uma chave encapsulada de ordem baixa é recusada antes de qualquer decisão ou contagem. - Os limites de taxa valem antes de qualquer trabalho de HPKE ou de assinatura. Quem tem um código
Manualainda consegue encherMaxPendingcom muitas chaves vindas de muitos endereços. Quem convida vê cada uma como um eventoRequestede pode usarDenyouRevoke. - As respostas são seladas para uma chave que quem entra cria a cada pedido e não são assinadas: elas vêm da chave de quem convida, por uma conexão presa a essa chave.
- Um
Codeguarda o seu segredo atrás de um ponteiro e imprime só o seu ID, também dentro de outros valores.Statsnão contém IDs, chaves nem endereços, então pode ser exportado como métricas com rótulos fixos. Revokeimpede novas entradas e nada mais. Quem já foi aceito mantém a carga útil que recebeu, como qualquer peer mantém o que já chegou até ele.- O código de um convite de dispositivo é o ponto fraco: quem o vê pode enviar um pedido antes do dispositivo real. A pessoa precisa digitar em
MatchDeviceos 12 dígitos que o dispositivo novo mostra, e as chamadas de aprovação só aceitam oDeviceMatchque ela devolve. Uma aplicação que mostra os dígitos na tela do aprovador para serem clicados, ou que os calcula ela mesma, perde essa barreira. - Os dígitos são HKDF-SHA256 (RFC 5869) sobre o segredo do convite, ligado à chave de quem convida e à do dispositivo, lido módulo 10^12: 39,9 bits. Na máquina que o repositório mediu, achar uma chave de dispositivo com uma impressão digital de 12 dígitos escolhida leva cerca de 127 dias de núcleo, e fazer isso dentro dos 2 minutos que um pedido pode esperar exigiria cerca de 90 000 núcleos. São números medidos e extrapolados.
- Um pedido de dispositivo recusado ou sem resposta queima o código em memória na hora, mesmo quando o disco falha. Quem tem um código pode encher
MaxPendingDevicese bloquear o dispositivo real; o aprovador vê cada pedido e pode revogar o código comRevokee começar de novo. - Só um dispositivo aprovador vincula um dispositivo, então um dispositivo comum roubado não consegue vincular nada. Um aprovador roubado pode vincular dispositivos até ser revogado, como dizem as notas de segurança da kolo-id.
- As 24 palavras nunca viajam em um convite nem em nenhuma mensagem:
ApproveApproverchama uma função que deriva a chave de pessoa, assina uma vez e apaga a chave. - O dispositivo novo verifica o que recebe: um certificado para outra chave de dispositivo, para outra pessoa que não a que ele fixou, assinado por uma terceira chave ou com uma assinatura inválida é
ErrProtocol. - Um nome pode imitar outro com letras parecidas. São os dígitos, não o nome, que identificam o pedido.
Limites conhecidos
ServePeerprecisa ser o único a chamarAcceptStreamna sua conexão. Uma aplicação que roda outro protocolo de streams com o mesmo peer decide, por conexão, qual deles a atende.- A kolo-swarm não avisa o outro lado sobre um topic em que você entra depois, em uma conexão que já existe. Depois de
JoinConn, quem entra sai do topic do convite antes de entrar no topic do grupo: a kolo-swarm então fecha na hora a conexão que era só do convite, e o topic do grupo chega em uma conexão nova que o leva desde o início. Senão, quem convida vê a conexão só com o topic do convite e a fecha depois deTimeout. - Os pedidos pendentes só existem enquanto quem entra espera no seu stream, e nenhum sobrevive a uma reinicialização. Os eventos também não são guardados:
Joinersé o registro durável. Closedeixa os pedidos pendentes sem resposta, e quem esperava recebeErrNotAnswered.- Todos os testes rodam em 127.0.0.1, então uma travessia de NAT real não foi testada.
- Experimental. A API pode mudar antes da v1.0.0.
Erros
| Erro | Mensagem |
|---|---|
ErrBusy | invite: busy |
ErrClosed | invite: closed |
ErrDenied | invite: denied |
ErrExpired | invite: expired |
ErrFingerprint | invite: fingerprint does not match |
ErrIDCollision | invite: invite ID collision |
ErrInvalid | invite: request refused as invalid |
ErrInvalidArgument | invite: invalid argument |
ErrInvalidCode | invite: invalid invite code |
ErrNotAnswered | invite: request not answered |
ErrNotApprover | invite: signer is not an approver |
ErrNotFound | invite: not found |
ErrPersonMismatch | invite: person key is not the expected one |
ErrPersonRequired | invite: expected person or FirstDevice required |
ErrProtocol | invite: protocol error |
ErrRateLimited | invite: rate limited |
ErrRevoked | invite: revoked |
ErrTooLarge | invite: too large |
ErrUnreachable | invite: inviter unreachable |
ErrUsedUp | invite: used up |
Teste os erros com errors.Is, porque a maioria chega envolvida com detalhes, como invite: invalid invite code: checksum mismatch. Quem entra recebe a maioria das respostas de quem convida como o próprio valor de erro: ErrDenied, ErrExpired, ErrUsedUp, ErrRevoked, ErrInvalid, ErrRateLimited ou ErrBusy. ErrTooLarge chega envolvido: dados de entrada acima do MaxData de quem convida, dados acima de 1 GiB que JoinConn rejeita antes de enviar qualquer coisa, ou uma carga útil acima de MaxPayload. Uma recusa sempre chega como ErrDenied, nunca como um tempo esgotado. ErrUnreachable (antes de quem convida receber o pedido) e ErrNotAnswered (depois) envolvem a causa, ctx.Err() incluído, e perguntar de novo é seguro. Do lado de quem convida, Approve e Deny retornam ErrExpired, ErrUsedUp ou ErrRevoked quando o convite terminou, e ErrNotFound quando quem entra foi embora, e um segundo Announce enquanto outro roda retorna ErrBusy. Os erros do backend, de leitura e de escrita, os de Open incluídos, voltam como invite: store: ... envolvendo o erro do backend; depois de uma escrita que falha, nada muda. Open, e Joiners para um registro de quem entrou, retornam um erro que envolve kolostore.ErrCorrupt para dados guardados que não decodificam ou não conferem. Nos convites de dispositivo, MatchDevice retorna ErrFingerprint quando nenhum pedido pendente tem os dígitos digitados, ApproveDevice retorna ErrNotApprover quando o seu certificado não é um certificado de aprovador válido do assinante, ApproveApprover e JoinDevice retornam ErrPersonRequired sem uma pessoa esperada nem FirstDevice, e ApproveApprover retorna ErrPersonMismatch quando a chave derivada não é ExpectPerson.
Referências
- RFC 9180, Hybrid Public Key Encryption (Informational, February 2022).
- Usa: o modo base com a suíte X25519 para o pedido e a resposta, e o DeriveKeyPair a partir de 32 bytes de segredo.
- Não implementa: os modos PSK e Auth e o exporter; a prova do convite é um valor de autenticação dentro do texto cifrado, e a resposta usa uma segunda operação HPKE para uma chave que quem entra envia.
- RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF) (Informational, May 2010).
- Usa: o ID, o topic, o valor de autenticação e a semente do HPKE derivados, com um rótulo cada um.
- RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA) (Informational, January 2017).
- Usa: Ed25519ctx, por meio da kolo-id, para a assinatura do pedido com o seu próprio contexto.
- RFC 4648, The Base16, Base32, and Base64 Data Encodings (Proposed Standard, October 2006).
- Usa: base32 para o código.
- Não implementa: o preenchimento e as maiúsculas; a forma escrita é em minúsculas.
- Nikitin et al., Reducing Metadata Leakage from Encrypted Files and Communication with PURBs, PETS 2019.
- Usa: os comprimentos Padmé para os textos em claro selados, com um mínimo de 512 bytes.
- W3C TAG, Good Practices for Capability URLs (First Public Working Draft, 18 February 2014).
- Usa: um segredo impossível de adivinhar que expira e pode ser revogado.
- Não implementa: o segredo nunca chega a um servidor; só valores derivados chegam à rede.