kolo docsbeta

Peers

A peer is an Ed25519 key. Two peers are the same peer when their public keys are equal.

On this page

A peer is a program that holds a kolo-id identity: an Ed25519 key pair. There are no user names and no accounts. The public key is the peer's name on the network, and every other library refers to a peer by it.

The key

  • koloid.Generate makes a new identity. Save and SaveNew write it to a file and Load reads it back, so a peer keeps the same key across restarts.
  • The key file holds only the 32-byte seed, written with mode 0600.
  • PublicKey returns the 32-byte public key, and PublicKeyString the same key as hex. Printing an *Identity shows only the public key; the seed never appears in any output.

What "equal" means

Two peers are the same peer when their public keys are equal, byte for byte: a.PublicKey().Equal(b.PublicKey()). Addresses do not count. A peer can change its IP address and port and still be the same peer, and two peers behind one address are still two peers.

Programs often show the first few bytes of a key as a short label, as the Get started chat does. That label is for people to read. Never use it to decide who someone is: compare the whole key.

How a peer proves its key

  • A signature from Sign names a context string, such as kolo-log/record/v1, and verifies only under that context, so a signature made for one message type is never accepted as another.
  • A kolo-secure connection is TLS 1.3 tied to both peers' keys. When it opens, each side knows the other's public key, and a dialer that asked for a given key gets that key or an error.

One person, several devices

A peer is one device key. A person who uses several devices has one key on each, and kolo-id can tie them to one person:

  • A 24-word recovery phrase (BIP-39) gives the person key. The library never stores or prints it.
  • The person key certifies approver devices, and an approver certifies ordinary devices, so the person key never lives on a device. Each device keeps its own random key and its certificate, in a .cert file next to the key file.
  • VerifyDevice checks a device's message for the person you expect. A lost device is revoked without losing the identity.

See Recovery phrase and devices. kolo-invite links a new device by invite, and the devices package of kolo-braid keeps the devices of a person in a group.

Good to know