Find, connect, encrypt, replicate.
Four steps, and no server of ours in the path of your data. Each step is one or two libraries, and each library has its own page in the docs.
Find
Peers announce a topic and look it up in a distributed hash table. No directory server.
A topic is 32 bytes the peers agree on, usually a hash. Kolo keeps no list of topics; the bytes mean nothing to it.
To be found, a peer stores a record signed with its key at the 20 servers closest to the topic, and refreshes it every 15 seconds. A server drops a record 20 minutes after its last refresh.
To find the others, a peer looks the topic up, gets their signed records back and checks each signature. kolo-swarm does both and keeps connections to the peers it finds.
A new peer needs a first address. With none given, it uses the two public entry nodes that Ciranda runs, built into kolo-dht. For a network of your own, you give it one or more bootstrap nodes you run, and the public ones are not used.
Connect
Peers open a direct connection, through their routers when they can. A relay steps in only if you run one and ask for it.
kolo-transport is one QUIC connection between two peers, with streams in both directions and hard limits on unread data, streams and connections. The DHT shares its UDP socket.
The server that stored a record relays a connect request, and the two peers punch through their NATs. When one side's NAT picks random ports, they punch with the birthday technique.
A pair that cannot be punched gets an error, not a silent fallback. Your app may then pass the address and key of a kolo-relay you run; the peers connect end to end through it and the relay forwards ciphertext it cannot read.
Encrypt
Every connection is TLS 1.3, tied to both peers' keys. Every signature has its own context. Every log entry has its own key.
kolo-transport alone encrypts against passive observers but does not say who is on the other side. kolo-secure adds that: after the handshake each peer signs the connection's exporter value with its kolo-id key, and the connection is returned only when the other side's signature checks out.
The signature is valid for that one connection, so it cannot be replayed on another. Any valid key authenticates; deciding whether to trust it is up to your app.
Every signature is Ed25519 with a context string (RFC 8032), so a signature made for one message type never verifies as another.
Each log entry is encrypted with its own random key. A peer can store an entry, serve it and check its proofs without being able to read it.
Replicate
Each peer keeps a signed, append-only log. Others pull it and check every piece before they keep it.
kolo-log · kolo-store · kolo-sync · kolo-kv
A log belongs to one key, its writer. Entries are the leaves of a Merkle tree hashed as in RFC 9162, and the owner signs the tree head: the size of the log and the root hash.
An inclusion proof shows that an entry is in a signed head. A consistency proof shows that a newer head only added entries to an older one. A reader trusts two things, the owner's public key and the log ID, and checks everything else against them.
kolo-sync copies a log by pulling only. A replica that gets a bad head, proof or entry keeps nothing and stays as it was. If the owner signed two different histories, the two heads are the proof.
Deleting an entry destroys its key and signs a delete marker; every proof still holds. It is best effort: a peer that already had the key can keep it. kolo-kv builds a one-writer key-value store on such a log.
What is not in the path
- No machine of ours carries your data. Peers meet through two public entry nodes that Ciranda runs, or through bootstrap nodes of yours. There is no public relay: the relay is yours to run, and off unless you turn it on.
- No accounts. A peer is a key, and two peers are the same peer when their public keys are equal, byte for byte.
- No IPv6 yet. Kolo is IPv4 only in version 0.1.0, and the docs say so on every page where it matters.
How we build
- Signed and checked
- Encrypted between peers
- Direct when possible
- No central server
- Small libraries
- Standard crypto only