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).
SaveandSaveNewwrite the key file with mode 0600 and create a missing parent directory with mode 0700.- On unix,
Load,SaveandSaveNewreturnErrInsecureKeyFilewhen the key file or its directory is not owned by the effective user or has group or other mode bits set.Loadrefuses a symlink and any file that is not regular. - The seed is never printed, logged or serialized. Printing an
*Identityor encoding it as JSON shows only the public key.UnmarshalJSONandUnmarshalTextalways returnErrNotDecodable. - kolo-node creates its
-identityfile on the first run with mode 0600, never replaces an existing one, and never logs the seed. Identity.ClearandPhrase.Clearzero 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 of | Can | Cannot |
|---|---|---|
| The 24 words | derive the person key, certify any device, revoke any device | read group data that only devices hold |
| An approver device key | what an ordinary device can, certify and revoke ordinary devices | certify or revoke an approver |
| An ordinary device key | sign as that device, revoke itself | certify or revoke other devices |
| A certificate alone | nothing: it is public | sign 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:
VerifyDeviceneeds 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:
| Context | Signs | Library |
|---|---|---|
kolo-log/header/v0 | log header | kolo-log |
kolo-log/record/v1 | entry record | kolo-log |
kolo-log/tree-head/v0 | signed tree head | kolo-log |
kolo-log/delete/v0 | delete marker | kolo-log |
kolo-secure/proof/v0 | handshake proof of a key | kolo-secure |
kolo-dht/announce/v1 | announce record | kolo-dht |
kolo-dht/punch-reply/v1 | answer to a punch request | kolo-dht |
kolo-invite/request/v0 | join request | kolo-invite |
kolo-pin/capability/v0 | capability for a pinning peer | kolo-pin |
kolo-pin/revoke/v0 | revoke note | kolo-pin |
kolo-id/device-link/v0 | device certificate | kolo-id |
kolo-id/device-accept/v0 | a device's acceptance of its certificate | kolo-id |
kolo-id/device-revoke/v0 | device revocation | kolo-id |
kolo-braid/device-admit/v0 | a device's proof in a join request | kolo-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
Verifyreturns 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
Decodefunction 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, andVerifiedHeadis the only headVerifyInclusionandVerifyConsistencyaccept. JSON is never signed: a JSONHeadis trusted only afterVerifyHead. - 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 throughReplica.AddKey, checked against the key commitment, and the delete markers of one STATE answer go to oneReplica.ApplyDeleteafter every item is checked, all or none.Fetchchecks each entry withkololog.OpenEntryagainst the head you give it, with an inclusion proof for the index asked.ErrDivergedcomes only with owner-signed evidence; a fork past the entries held givesErrInvalid. Replica.UpdatereturnsErrDivergedwhen the owner signed two histories. On any error the replica stays exactly as it was.- kolo-kv verifies the head with
kololog.VerifyHeadunder 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 isErrCorrupt. - 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
ErrInvalidPacketand a fault in the translated codec is recovered, so one packet costs one frame. Every VP8 and VP9 frame header is checked againstMaxPixelsbefore 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,AllowConnectand the kolo-syncauthorizerefuse 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.
Joinersstores 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
MaxUsessays more, and lives for itsTTL(zero never expires) on the inviter's clock. Once ended, it still answers forLinger(5 minutes), then its secret is erased. Uses are counted in one durable batch before the answer, so concurrent joins never go overMaxUses. Revokestops 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
Manualcode can still fillMaxPendingfrom 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
Codeprints only its ID, andStatsholds 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 withCiphertextaccess 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 isErrRevoked. When it expires, or a revoke note covers it, the pinning peer deletes every log of that owner. - The
kolo-pincommand's/metricsendpoint (127.0.0.1:7452by 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.
OpenPebblecreates 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.OpenandOpenReplicaverify everything again with kolo-log, against the key you pass them.Ownerchecks the stored owner key only against the header's own signature.- Every read after
Openchecks the stored entry against its record again. An entry changed on disk isErrCorruptwrappingkololog.ErrStorageMismatch. Adoptbrings 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. OpenReplicareplays a stored catch-up target throughUpdate, so it is checked like a fresh update.- Pass
kololog.WithTrustedHeadwith the last head you published, so an older stored snapshot returnskololog.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.Deleteleaves 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
CiphertextorKeysaccess 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.CBRso 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.ServeConntrusts the key a connection reports, so pass only connections whose key was proved in a handshake, and thekvmap has no access control: any active member writes any key (kolo-braid).
Contact
To report a problem, write to hello@ciranda.dev.