Skip to content

Encrypted links between phones

Jeffrey Walter Mixon edited this page Nov 16, 2026 · 1 revision

When two Knit phones link over Bluetooth or Wi-Fi Aware, they now encrypt the link itself. A radio nearby that isn't one of the two phones can no longer read who's writing to whom, or what the phones pass between them. A device that sits between two phones and quietly forwards their traffic can't stay in the middle of the link either.

Encrypted links are in alpha, starting with Knit 2.12.0-alpha.0. There's nothing to set up: when both phones run that version or later, every link between them is encrypted.

Checked against Knit 2.12.0-alpha.0.

A second layer, one hop at a time

Knit already encrypts direct and group messages end to end. A message is sealed on the sender's phone, and only the people it's for can open it, however many phones carry it on the way. That hasn't changed.

End-to-end encryption protects what you write, but it can't hide the envelope. The phones that carry a message need the envelope to deliver it: the sender's Knit identity, the recipient, the time it was sent, its size, and for a group message the member list. How a message crosses the mesh explains why.

Until now, that envelope also crossed the air in the clear between every pair of linked phones, along with everything else on the link. An encrypted link wraps each hop in a second layer. The two phones on the link still read what they read before, and any other radio in range gets only ciphertext.

End-to-end encryption Encrypted link
What it protects The content of direct and group messages Everything on one link between two phones
Who holds the keys The people in the conversation The two linked phones, while the link lasts
Who it hides things from Every phone that carries the message Every radio in range except the two phones
How far it reaches One message, across every hop One hop, for every message on it

What a nearby radio could read before

Knit's Bluetooth links are L2CAP channels opened without Bluetooth pairing, so the bytes went over the air as they were. Wi-Fi Aware connections were encrypted, but with a key built into the app and the same in every copy. That kept the bytes off open air, but anyone with a copy of Knit had the key.

So a radio within range could record a link without ever joining it, and read:

  • each phone's Knit identity, which the phones exchange as the link opens
  • the list of message IDs each phone carries, which they swap to catch up
  • the envelope of every message that crossed, which shows who writes to whom, when, and how much
  • Nearby room posts and profile updates in full, since those are public by design

On an encrypted link, all of that is ciphertext to anyone but the two phones.

No more device in the middle

Knit 2.11.0 started making each phone prove its identity when a link opens. Each phone signs the opening exchange with its identity key, so a modified app can't pass itself off as your contact.

That proof tied the identity to a key, but not to the connection it was made on. A device in range of both phones could open a link to each, pass the genuine exchange back and forth between them, and end up in the middle of a link both phones took to be direct.

An encrypted link closes that gap. The identity proof now also signs the keys that encrypt this particular link. To read the traffic, a device in the middle would have to put in keys of its own, the signatures would no longer match, and the phones would refuse the link. It can still stop a link from forming, much as a jammer can, but it can't read the link or write into it.

How a link gets its keys

Before they exchange anything else, the two phones agree on keys:

sequenceDiagram
    participant D as Phone that dials
    participant R as Phone that answers
    D->>R: Fresh public key
    R->>D: Fresh public key
    Note over D,R: Both work out the same shared secret.<br/>Everything after this point is encrypted.
    D->>R: Hello: Knit identity and version
    R->>D: Hello, plus a proof signed with its identity key
    D->>R: Proof signed with its identity key
    Note over D,R: The link is up, and catch-up and messages follow
Loading

Each phone makes a new X25519 key pair for every connection attempt. The shared secret becomes two AES-256-GCM keys, one for each direction. Every encrypted frame is numbered, and the number is part of how it decrypts, so a frame that's replayed, dropped, reordered or bounced back to its sender fails to open, and the link closes.

The keys live in memory and are gone when the link ends. Your phone's long-term identity key signs the exchange but doesn't go into the link's keys. A recording of a link stays unreadable even to someone who later gets hold of either phone's identity key.

Opening a link takes one more round trip than before. Once it's up, messages, pictures and catch-up run over it as they always have.

Older versions of Knit

A phone that can encrypt links says so in its Bluetooth advert and in its Wi-Fi Aware discovery details, and a phone dialling it starts with the key exchange only when it sees that. A link between an updated phone and one on Knit 2.11 or earlier works as it always has, unencrypted, until the older phone updates.

Two updated phones don't fall back. If both can encrypt and their link opens without it, both refuse the link. Each phone's support for encryption is also part of the signed opening exchange, so between phones that already hold each other's signed profile, a device in the middle can't strip it out to force an unencrypted link.

At a first meeting the protection is weaker. Before the phones hold each other's profile, a device in the middle could make each phone look like an older version of Knit to the other, and get a link that's neither encrypted nor proven. Once the two have each other's profiles, that no longer works.

Direct links, which connect two contacts over the Internet when both turn on Connect directly to contacts, have their own encryption and don't use this exchange.

What stays visible

Encrypting the link protects what crosses it. Some things travel outside a link, or are visible whatever it carries.

Phones find each other through the Bluetooth advert and Wi-Fi Aware discovery before any link exists. Advertising pages and Wi-Fi Aware's short messages also travel without a link, carrying Nearby room posts, small public updates and short direct messages to phones that aren't linked. A nearby radio reads these as it did before, though the direct messages among them are still end-to-end encrypted.

Knit doesn't pad what it sends, so a listener can still tell when a link is busy and roughly how much crosses it.

The phone at the other end of a link decrypts it, so it sees the same envelopes it always did. A phone that links to yours on purpose also still learns your Knit identity. Encryption keeps out a radio that's only listening. It doesn't stop anyone from linking.

Checking a link

Open Diagnostics from the ⋮ menu in the chat list. The list of people your phone reaches marks each one Encrypted or Not encrypted. Not encrypted means the other phone runs an older version, or the link hasn't proven who's on the other end yet.

Below that, three counters follow the feature over time:

Counter What it counts
Links encrypted Links that finished the key exchange
Link encryption failed Links where the other side sent bytes that didn't decrypt or didn't fit the exchange. A link that drops or times out doesn't count, so on a healthy phone this stays at zero
Unencrypted links refused Times two phones that can both encrypt were offered an unencrypted link and turned it down

Encrypted links have no switch. Every link between two phones that support them is encrypted.

Going deeper

Clone this wiki locally