Skip to content

Rotating tags in the Bluetooth advert

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

A Knit phone advertises over Bluetooth LE about once a second so the phones around it can find it. Knit is moving that advert from your phone's Knit ID to a tag that changes every 15 minutes. Your contacts can still pick your phone out of a crowd before the two of you link. Anyone else, including a scanner app that never heard of Knit, sees 16 bytes that don't match anything and don't connect one quarter-hour to the next.

Knit 2.12.0 lays the groundwork: phones read tags and quietly hand their contacts the keys to recognize them, while release builds still advertise the Knit ID. A later release turns the tags on, and by then contacts will already hold each other's keys. There's nothing to set up either way.

Checked against Knit 2.12.0-beta.0.

Why the advert needed to change

Phones find each other by advertising, and an advert is a broadcast: any Bluetooth scanner in range can read it, whether or not it runs Knit. Knit's advert is 24 bytes, and 16 of them have been the phone's Knit ID.

Your Knit ID is a random number your phone generated from its own encryption keys when you set up Knit. It isn't your phone number, your name or anything built into the hardware. It does stay the same from day to day, through Bluetooth restarts and phone restarts, because that's how your contacts' phones know you.

Anything in an advert that stays the same lets a scanner tell it's hearing the same phone again. Bluetooth already changes the address a phone advertises from every few minutes so that passing devices can't do this. Rotating tags give the advert's contents the same property, while still letting contacts recognize each other on sight.

A tag in place of your Knit ID

With tags on, those 16 bytes hold a tag. The phone works it out from three things:

  • a presence key, 32 random bytes that only your phone and your contacts hold
  • your Knit ID
  • the current 15-minute slot of wall-clock time

These go through HMAC-SHA256, a keyed hash, and 108 bits of the result become the tag. Without the key, a tag looks like random bytes, and one tag gives no hint of the next. The first 20 bits are a fixed prefix, which is how older versions of Knit end up handling a tag correctly (see Older versions of Knit). A bit in the advert's flags byte says the advert carries a tag.

Your Knit ID goes into the hash so that each tag belongs to one phone. Two phones holding the same key still air different tags, so a key passed from one phone to another can't make the second phone's tags read as the first's.

Turning Bluetooth off and on, or restarting the phone, also gets a fresh tag within the same slot, so the advert before and the advert after can't be matched.

The advert used to carry a short summary of the messages the phone holds, so neighbours could tell whether they had catching up to do. That summary would link one tag to the next, so a phone airing a tag leaves it blank. Phones still catch up as soon as they link.

How your contacts recognize you

sequenceDiagram
    participant A as Your phone
    participant B as A contact's phone
    participant S as A scanner nearby
    A->>B: Your presence key, over a link, sealed for B alone
    Note over B: Works out every tag you'd air<br/>over the last 8 hours and the next half hour
    A-->>B: Advert carrying this slot's tag
    A-->>S: The same advert
    Note over B: The tag is in its table: it's you
    Note over S: 16 bytes that match nothing
Loading

A contact who holds your presence key can work out your tags ahead of time. Each phone keeps a table of the tags its contacts would air over the last 8 hours and the next half hour, and updates it as time moves on. When it hears an advert, it looks the tag up. A match names the contact. A tag with no match costs the phone nothing, and it treats the advert as a stranger's.

That's what lets Knit show a contact as nearby, and pick the right phone to link to, before either phone has said who it is. Strangers can still link. Knit learns who a stranger is once the link proves it, as Encrypted links between phones describes, and a stranger counts among the people nearby only once linked.

Recognition relies on the two phones' clocks roughly agreeing. Your contact's phone recognizes your tag if your clock runs up to about half an hour ahead of theirs, or several hours behind. Outside that range your phones still link the way strangers do, and the link works out who's who.

Who gets your key

Your presence key goes to your direct contacts and no one else:

  • people you accepted yourself
  • people you verified
  • people you've written to in a direct message

Anyone you've blocked is left out. So is anyone you only share a group with, since someone else decided they could reach you.

The key travels in its own encrypted message, straight from your phone to the contact's, over a live link on which the contact's phone has proven who it is. It's never flooded across the mesh or left with a carrier, so the phones in between don't learn who your contacts are. Every key message is padded to the same 128 bytes, and between phones on Knit 2.12.0 or later it also rides inside the encrypted link.

Presence keys stay out of backups. A restored phone makes new ones and hands them out as it meets its contacts again.

When the key changes

Your phone holds three keys at a time: the previous one, the current one and the next. Once a week the next key becomes current. Contacts receive the next key ahead of time, so a weekly change is invisible to anyone you've met during the week.

The key also changes straight away when someone leaves the set of people who should hold it: when you remove a contact, block someone or stop verifying them. Your phone makes a fresh current and next key and moves its advert to the new key at once, so the person who left sees bytes that match nothing, like any stranger. Your other contacts get the new key the next time your phones link, and until then they find you by linking, the way a stranger would.

Someone you add later gets your next key, and gets the current one only if it became current within the past day. A new contact can't go back over days of your tags they happened to record before you met.

How the tag rotates

At each 15-minute boundary your phone stops its adverts and starts new ones carrying the new tag. Starting new adverts, rather than editing the old ones in place, gives them a new Bluetooth address too, so the address doesn't tie the old tag to the new one. The standard advert and the long-range (Coded PHY) one move together.

The advert also names the channel a neighbour dials to open a link. Your phone opens a new channel at each rotation and keeps the old one listening for 30 seconds, so a dial already under way still lands.

Phones linked to yours hear the next tag over the link about three and a half minutes before it goes on air. A linked phone then knows the new tag the moment it appears, and doesn't mistake you for a new phone and dial you a second time.

Rotation happens the next time your phone is awake after the boundary. Knit doesn't wake the phone just to rotate. A phone linked to others is awake often and rotates within a minute or two. A phone lying idle with nobody around can keep one tag until Android next wakes it, which in deep sleep can be hours.

A phone never airs the same tag twice. If its clock is set back, or a fifth Bluetooth restart lands in one slot, it airs a random tag that nobody recognizes until the clock moves past the last slot it used. If its clock ran far ahead and was then put right, the phone starts a new key, so it's unrecognizable only until that key reaches its contacts, not until real time catches up with the slots it already used.

Who dials whom

Two phones shouldn't dial each other at the same moment, so Knit settles who opens a link from the adverts alone. Until now, the phone with the larger Knit ID dialed. Tags change the rule:

Your phone advertises Theirs advertises Who dials
Its Knit ID Its Knit ID The larger Knit ID, as before
A tag Its Knit ID Your phone
Its Knit ID A tag Their phone
A tag A tag The larger tag, so the role changes hands as the tags rotate

Older versions of Knit

Phones on Knit 2.11 and earlier can't read tags, but they still link with phones that air them. A tag's fixed prefix tells an older phone to leave the dialing to the newer one, and the newer phone dials it. Until it updates, an older phone may list a tag-airing phone more than once among the people nearby, and its link to that phone may drop more often. Updating to Knit 2.12.0 or later, when you can, clears both.

What stays visible

Tags keep the advert's contents unreadable to any scanner that doesn't hold your key. Your contacts hold it, so they can recognize your phone wherever they are. That's what the key is for, and it's why it goes only to direct contacts and changes when one leaves.

A few details outside the tag change on their own schedule. The advert's capability bytes, which describe your version of Knit, rarely change at all. A device paired with your phone, such as a watch or a car, can recognize your phone's Bluetooth address whatever the tag says, which is how Bluetooth pairing works and isn't something an app can change.

Once two phones link, they introduce themselves by Knit ID, as they always have. Between phones on Knit 2.12.0 or later, that introduction happens inside the encrypted link.

Going deeper

Clone this wiki locally