Repository navigation
Encrypted links between phones
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.
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 |
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.
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.
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
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.
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.
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.
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.
- ADR 2026-11.8mhs is the design decision, with the exact key derivation, frame format and every cost the team accepted.
- ADR 2026-11.264w covers the identity proof that encrypted links build on.
- How a message crosses the mesh explains the catch-up and carrying that run over every link.
- The radios Knit uses describes the Bluetooth and Wi-Fi Aware links being encrypted.
- What Knit encrypts, and what stays visible covers end-to-end encryption from a user's side.
Knit is free and ad-free, funded by its supporters.
☕ Ko-fi ·
💖 GitHub Sponsors ·
Liberapay ·
Other ways to help
Supporting Knit on Ko-fi or GitHub Sponsors comes with Knit Anywhere. Liberapay goes to the developer personally.