kolo docsbeta

Security

What the Kolo libraries protect, how they do it, and what they leave to you.

On this page

Status

Every Kolo library is experimental. The API (for kolo-node, also its command line and config file, and for kolo-pin, also its command line) may change before v1.0.0, and only the latest v0.x release of a library receives security fixes.

To report a vulnerability, do not use public issues, pull requests or discussions. Report it privately through GitHub on the library's repository: open a private security advisory (Security tab, "Report a vulnerability"), at https://github.com/ciranda-dev/<library>/security/advisories/new. Only the maintainers can see it. Include a description of the issue, the affected version and, if possible, steps to reproduce it. If private reporting is not available, open a public issue that only asks for a private contact, with no details about the vulnerability.

Keys

An identity is an Ed25519 key, and only its 32-byte seed is stored, in the key file (kolo-id).

  • Save and SaveNew write the key file with mode 0600 and create a missing parent directory with mode 0700.
  • On unix, Load, Save and SaveNew return ErrInsecureKeyFile when the key file or its directory is not owned by the effective user or has group or other mode bits set. Load refuses a symlink and any file that is not regular.
  • The seed is never printed, logged or serialized. Printing an *Identity or encoding it as JSON shows only the public key. UnmarshalJSON and UnmarshalText always return ErrNotDecodable.
  • kolo-node creates its -identity file on the first run with mode 0600, never replaces an existing one, and never logs the seed.
  • Identity.Clear and Phrase.Clear zero the key material the library holds. Erasing is best effort: the Go runtime and the standard library keep copies no library code can reach, so treat a process that held a key as one that may still contain it.

Recovery phrase and devices

A person can have several devices (kolo-id). The 24 words of a BIP-39 phrase give the person key (SLIP-0010 for Ed25519). The person key certifies approver devices, an approver certifies ordinary devices, and each device signs with its own key.

Holder ofCanCannot
The 24 wordsderive the person key, certify any device, revoke any deviceread group data that only devices hold
An approver device keywhat an ordinary device can, certify and revoke ordinary devicescertify or revoke an approver
An ordinary device keysign as that device, revoke itselfcertify or revoke other devices
A certificate alonenothing: it is publicsign anything
  • Whoever has the words is the person, for good. A leaked phrase cannot be repaired inside the same identity: create a new phrase. The library never stores, prints or encodes a phrase, and an error names a position, never a word. Generate the words in the application, never let the user pick them, and ask for them only in a restore flow.
  • Typed words that pass the checksum can still be wrong: one random typing error in 256 passes. Show the person key after a restore.
  • The verifier chooses the person: VerifyDevice needs the expected person and has no mode without a certificate. It checks expiry, revocations and every signature.
  • Revocations are permanent. The person key or the device itself revokes up to a serial. An approver revokes one exact certificate, named by the SHA-256 of its body, issuer and parent, so it cannot burn a key or revoke a certificate that does not exist yet. Revoking an approver voids every certificate it issued.
  • The library keeps no state. Revocation is as fresh as the records a verifier holds, so the application carries revocations to every verifier and keeps them.
  • A stolen approver can certify ordinary devices until the phrase revokes it, and can revoke the person's ordinary devices. Keep the phrase, and certify a second approver when there are two devices.

To link a device, kolo-invite uses a short-lived, one-use device invite. The person types into the approving device the 12 digits the new device shows; the approve calls take only the match that typing returns. 12 digits are 39.9 bits. A refused request, or one nobody answers within DevicePendingTTL (2 minutes), burns the code. An approver by invite needs the 24 words typed on a device of the person; they are never carried by an invite or any message.

In a kolo-braid group, the devices package trusts a person only when an admin recorded a certificate of it, so a plain member cannot invent one. Approver-issued certificates cannot fill the roster: 128 of 1024 slots stay for certificates the person key issued.

Signatures and contexts

Every signature is Ed25519ctx (RFC 8032) with its own context string, so a signature made for one message type never verifies as another. A signing context is 1 to 255 bytes. Verify returns false on any bad input and rejects small-order public keys. These are the signing contexts in the code:

ContextSignsLibrary
kolo-log/header/v0log headerkolo-log
kolo-log/record/v1entry recordkolo-log
kolo-log/tree-head/v0signed tree headkolo-log
kolo-log/delete/v0delete markerkolo-log
kolo-secure/proof/v0handshake proof of a keykolo-secure
kolo-dht/announce/v1announce recordkolo-dht
kolo-dht/punch-reply/v1answer to a punch requestkolo-dht
kolo-invite/request/v0join requestkolo-invite
kolo-pin/capability/v0capability for a pinning peerkolo-pin
kolo-pin/revoke/v0revoke notekolo-pin
kolo-id/device-link/v0device certificatekolo-id
kolo-id/device-accept/v0a device's acceptance of its certificatekolo-id
kolo-id/device-revoke/v0device revocationkolo-id
kolo-braid/device-admit/v0a device's proof in a join requestkolo-braid

Other inputs carry their own tag in the same style but are not signatures: kolo-log/key/v0 (key commitment hash), kolo-log/entry/v0 (associated data of entry ciphertexts), kolo-dht/punch/v1 (HMAC-SHA256 of a PUNCH), kolo-dht/punch-secret/v1 (HKDF of the punch secret), kolo-dht/node-id/v1 (node ID hash), EXPERIMENTAL-kolo-secure/channel-binding/v0 (TLS exporter label) and kolo-kv/op/v0 (op format tag). kolo-invite also uses kolo-invite/request/v0 as the HPKE info of requests, and adds kolo-invite/answer/v0 (HPKE info of answers), kolo-invite/fingerprint/v0 (fingerprint hash) and kolo-invite/id/v0, kolo-invite/topic/v0, kolo-invite/auth/v0 and kolo-invite/hpke/v0 (HKDF labels on the invite secret). Every context that starts with kolo-id/device- is reserved: Sign returns ErrInvalidContext for it and VerifyDevice refuses it, so no application signature can pass as a certificate or a revocation. kolo-sync signs nothing.

Channels

kolo-transport runs QUIC with TLS 1.3. The listener presents an ephemeral self-signed certificate and the dialer accepts any such certificate, so on its own it protects against passive observers only.

kolo-secure ties the TLS 1.3 channel to kolo-id keys. Each side signs the protocol version, its role, a 32-byte TLS exporter value and both public keys under kolo-secure/proof/v0, so a proof does not verify on another connection, for the other role, or for another pair of peers. Any valid key authenticates: deciding whether to trust it is up to the application.

  • There is no forward secrecy or rekeying beyond TLS 1.3.
  • The dialer sends its key first, so an active prober learns it, and learns the listener's key by connecting. Passive observers see neither. Addresses, timing and sizes are visible.

kolo-relay forwards an end-to-end kolo-secure connection. It cannot read or change the inner packets and cannot pose as either peer, but it can drop, delay or end them. It learns both keys of every session, both clients' addresses, which keys hold reservations, when sessions start and end, and the sizes and timing of the inner packets.

Untrusted input

Bytes from the network or from another peer are checked before they are used.

  • kolo-codec decoding returns an error, never a panic. Lengths are checked against the caller's maximum and the input before anything is allocated, and a failed read consumes nothing.
  • kolo-id Verify returns false on any bad input, a key of the wrong size included, and never panics. The certificate, offer and revocation decoders and the phrase parser never panic and refuse oversized input before parsing.
  • Every kolo-log Decode function and verifier takes untrusted bytes and returns an error or false, never a panic. A reader trusts only the owner's public key and the log ID, and VerifiedHead is the only head VerifyInclusion and VerifyConsistency accept. JSON is never signed: a JSON Head is trusted only after VerifyHead.
  • kolo-secure reads handshake messages with a length of at most two bytes and a body of at most 256 bytes, so a peer cannot make the reader allocate more.
  • kolo-sync checks the length prefix of every message (at most 4 MiB) before allocating and verifies the peer's head, against the owner key and log ID, before it reads anything else. Every chunk goes through Replica.Update, every late key through Replica.AddKey, checked against the key commitment, and the delete markers of one STATE answer go to one Replica.ApplyDelete after every item is checked, all or none. Fetch checks each entry with kololog.OpenEntry against the head you give it, with an inclusion proof for the index asked. ErrDiverged comes only with owner-signed evidence; a fork past the entries held gives ErrInvalid.
  • Replica.Update returns ErrDiverged when the owner signed two histories. On any error the replica stays exactly as it was.
  • kolo-kv verifies the head with kololog.VerifyHead under the log's owner key when it opens or refreshes. An op with another tag or kind, a key, value or list over its limit, non-minimal varints or trailing bytes is ErrCorrupt.
  • kolo-braid verifies every head, record, proof and entry from a peer, and closes the connection on a message that is malformed, over its bound, of another group, version or type, with trailing bytes, or that does not verify. Evidence against a strand counts only when the key that signed both objects is that strand's key, and a key that is not a member's, a settler's or a pin's gets nothing from kolo-sync.
  • kolo-dht drops requests past its rate limits before they are decoded, and gives the ANNOUNCEs that need a key agreement or a signature check a budget of their own.
  • kolo-invite refuses a frame over its bound from its length, before reading its body. An unknown invite and a request that does not decrypt or verify get the same ErrInvalid, and a low-order key is refused before anything is counted.
  • kolo-audio and kolo-video decode data a peer controls. A corrupt Opus packet returns ErrInvalidPacket and a fault in the translated codec is recovered, so one packet costs one frame. Every VP8 and VP9 frame header is checked against MaxPixels before libvpx allocates anything. For H.264, every packet is parsed and bounded in Go before the operating system's codec sees it, and only NAL unit types 1, 5, 7 and 8 pass.
  • Callbacks such as AcceptFunc, Allow, AllowReserve, AllowConnect and the kolo-sync authorize refuse when they panic.
  • Errors from kolo-codec, kolo-transport, kolo-secure, kolo-relay and kolo-sync never include text or values the peer sent, only numeric codes where a protocol has them.

Sync access

kolo-sync names a log by its owner's public key and its log ID, in Offer, Withdraw(owner, logID), authorize(peer, owner, logID) and on the wire, so one owner can neither replace nor withdraw another's log by reusing its ID. Offer refuses a source whose header is not signed by src.Header().LogKey or names another log ID.

authorize is asked on every request, for any owner and log ID, so a revoked peer stops at its next request. A nil authorize, a panic or any other value means NoAccess. Ciphertext gives everything but the entry keys, and Keys hands the entry keys over for good. A missing, an unoffered and an unauthorized log, and a log ID offered only under another owner, take one path and give the same bytes, and a stored log that is not offered is never read.

A pull with nothing new reads no ciphertext on either side. One STATE answer looks at most at 32768 entries and reads only the delete markers and keys it sends.

Invites

A kolo-invite code holds a 16-byte fingerprint of the inviter's key and a 256-bit secret, never an address. Whoever has it can ask to join, and only that: the inviter decides, on its own clock and its own disk, and must be online.

  • An accepted joiner gets the payload of the accept. The inviter learns the joiner's kolo-id key, its join data and, from the connection, its address. Joiners stores the key, the data and the join time. The joiner learns the inviter's key and address.
  • The joiner talks only to a peer whose authenticated kolo-secure key matches the fingerprint. The secret never reaches the network: the DHT sees a topic derived one way from it, and the request travels sealed with HPKE and signed under kolo-invite/request/v0. A fresh 32-byte challenge on every stream stops replays.
  • A code is single use unless MaxUses says more, and lives for its TTL (zero never expires) on the inviter's clock. Once ended, it still answers for Linger (5 minutes), then its secret is erased. Uses are counted in one durable batch before the answer, so concurrent joins never go over MaxUses.
  • Revoke stops new joins only. A joiner already accepted keeps its payload.
  • Rate limits per source and per invite run before any HPKE or signature work. A holder of a Manual code can still fill MaxPending from many keys and addresses.
  • The DHT servers that store an invite's topic can link a joiner's address to the inviter's key at the time of the join. They cannot tell which invite it is or read the request.
  • A Code prints only its ID, and Stats holds no IDs, keys or addresses.

Pinning peers

A kolo-pin pinning peer is a replica with Ciphertext access only. It never gets an entry key or any plaintext, so it cannot read what it stores. Everything it stores went through Replica.Update or Replica.ApplyDelete, so it never stores a forged entry.

  • It sees which owner keys and log IDs it hosts, their entry counts and sizes, the signed records, when each log grows, is deleted from or is pulled, and for every request the requester's key, IP address and timing.
  • Anyone who knows an owner key and log ID can pull its ciphertext and records from it, or fetch a range of entries with kolo-sync Fetch, and learn the same. It serves with Ciphertext access only, so no answer from it carries a key.
  • A hosted log is identified by its owner key and log ID, so another owner's log with the same ID is pinned, served and dropped on its own.
  • An open log keeps about 250 bytes of memory per entry, and up to 64 logs are open, so in the worst case that memory reaches about 0.42 times the byte limit, and any peer that knows the owner keys and log IDs can make the pinning peer open them. Its operator sets the byte limit for the RAM.
  • An owner allows it with a capability signed under kolo-pin/capability/v0, for one pinning peer, with an expiry and an optional quota. The newest capability of an owner wins, and an older one replayed is ErrRevoked. When it expires, or a revoke note covers it, the pinning peer deletes every log of that owner.
  • The kolo-pin command's /metrics endpoint (127.0.0.1:7452 by default) shows totals for the whole peer only, never an owner key, log ID, peer key or IP address. It has no authentication, so it stays on loopback unless you set another address (Monitoring a pinning peer).

Deletion

kolo-log deletes an entry by destroying its key and signing a delete marker, so every proof still holds. The author key, log ID, index, padded size, ciphertext hash and key commitment of each entry are public. Its content, real size and write time are not, also after deletion. Delete and ApplyDelete take many entries at once and commit them together, all or nothing: the storage keeps the record and the marker in place of the ciphertext and the key. The log clears the keys it uses, but the cipher's internal copy stays in memory until the runtime reuses it.

kolo-sync carries the marker to every peer with Ciphertext or Keys access and applies the markers of one STATE answer in one commit. A peer can leave out a marker and serve the live entry to Fetch, but it cannot make a live entry look deleted without the owner's signed marker. With PullWith and NoMarkers, a pull neither requests nor stores delete markers, so a peer that deleted entries, or claims it did, cannot erase them from a replica. kolo-kv Delete destroys every value of a key since its last delete, in one write. A deleted kolo-kv key's name stays in its delete entry, so keep secrets in values, not in keys.

Storage

kolo-store trusts the node's own disk.

  • Each entry's key is stored in the clear, on its own next to its ciphertext.
  • Every change is one synced batch that kolo-log commits before it shows the change. A failed write returns the backend's error and changes nothing.
  • OpenPebble creates the store directory with mode 0700 and refuses one that group or others can access, that another user owns, or that is swapped while it opens, and makes every file Pebble creates there mode 0600, since they hold the entry keys. Permissions, owner and file modes are not checked on Windows.
  • Open and OpenReplica verify everything again with kolo-log, against the key you pass them. Owner checks the stored owner key only against the header's own signature.
  • Every read after Open checks the stored entry against its record again. An entry changed on disk is ErrCorrupt wrapping kololog.ErrStorageMismatch.
  • Adopt brings a closed own log up to a replica of it in one batch and keeps every deletion of either side, so a stored deletion is never undone. It refuses a replica the stored log is not a prefix of, shorter or forked (kololog.ErrRollback), and a batch of 2 GiB or more (ErrTooLarge).
  • A store holds one log per log ID. Opening an ID held for another owner returns kololog.ErrBadLogHeader, changes nothing on disk and never returns that owner's log.
  • OpenReplica replays a stored catch-up target through Update, so it is checked like a fresh update.
  • Pass kololog.WithTrustedHead with the last head you published, so an older stored snapshot returns kololog.ErrRollback. That is the anchor against a rollback of the disk.
  • Deletion on disk is best effort: the key is removed in the same write that stores the marker, but a backup, a filesystem snapshot, the write-ahead log or freed disk blocks keep a working key. The open log refuses an old entry value put back, but after a reopen that value makes the deleted entry readable again with no error, and a log removed with Store.Delete leaves its old bytes until compaction.

What Kolo does not protect against

  • A peer that does not follow the protocol, or that kept a key or plaintext before a delete, and old copies of a disk (Deletion).
  • A peer with Ciphertext or Keys access that makes the server read the log again and again (kolo-sync).
  • An active man in the middle on a plain kolo-transport connection (kolo-transport).
  • Someone who steals a kolo-id key: there is no forward secrecy or rekeying beyond TLS 1.3 (kolo-secure).
  • Traffic analysis: addresses, timing and sizes are visible, and a relay sees the metadata of every session it carries (kolo-relay). Audio can use opus.Config.CBR so that packet sizes do not tell speech from silence, but DTX still shows silence (kolo-audio).
  • Privacy of topics and addresses on the DHT: its traffic is not encrypted, and anyone can announce any topic. An attacker with many /24 prefixes is not resisted, and some probe and punch abuse is left open by design (kolo-dht).
  • Anyone who holds a leaked invite code, until it is revoked or ends, and what DHT servers learn at the time of a join (kolo-invite).
  • The metadata a pinning peer sees, and a disk filled by strangers on a pinning peer that accepts any owner (kolo-pin).
  • True topic claims, and floods of keys from one or many addresses (kolo-swarm).
  • Access control through a private network: the list of entry nodes is not a secret, and anyone who learns one entry address can bootstrap from it, look up topics and announce on them. Use Allow, kolo-secure keys, kolo-invite and signed records for access (kolo-swarm, kolo-node).
  • A change to the store directory path after it was opened, by someone with write access to a parent directory, and a disk write that marks a replica as an own log (kolo-store).
  • The number of distinct source addresses, the CPU and bandwidth spent per packet, and the OS UDP receive buffer (kolo-transport).
  • A kolo-moq relay you run: connections are encrypted hop by hop by kolo-secure, so the relay can read the media, catalogs and data tracks it forwards, unless the objects are sealed with secobj. Sealed objects still show the relay the room, who publishes and who watches, and the size and timing of every object, and it can drop, delay or withhold them. A member who controls the relay can make objects that seem to come from another member, because every member holds every sender's key (kolo-moq, kolo-media).
  • A crash in the Windows H.264 decoder, which runs in your process, and damaged H.264 slices that pass the checks, which Windows conceals and returns as pictures without an error; native libvpx, which decodes without memory safety (the portable engine is the safer choice for untrusted peers); and whatever the encryption of your own transport does not cover (kolo-video, kolo-audio).
  • In a braid, admins who add or remove anyone, settlers who try to choose the order of concurrent entries (it is not fair), and a removed member, which keeps everything it received. Settlement stops while fewer than q settlers are online, and a settler that signs two histories stops it for good. Braid.ServeConn trusts the key a connection reports, so pass only connections whose key was proved in a handshake, and the kv map has no access control: any active member writes any key (kolo-braid).

Contact

To report a problem, write to hello@ciranda.dev.