-
Notifications
You must be signed in to change notification settings - Fork 730
feat: GATT Client Identity Signaling & Connection Deduplication #627
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
callebtc
wants to merge
1
commit into
main
Choose a base branch
from
feat/gatt-client-identify-yourself
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,184 @@ | ||
| # Bitchat Mesh: Direct Client Identity Signaling & Connection Deduplication Spec | ||
|
|
||
| ## 1. Overview | ||
| This specification details the mechanism for Bitchat nodes to signal their persistent **Peer Identity** over Bluetooth Low Energy (BLE) to prevent duplicate connections. | ||
|
|
||
| In a privacy-preserving mesh network, devices frequently rotate their MAC addresses. This creates a problem where two nodes might establish multiple redundant connections to each other (thinking they are new devices), wasting limited connection slots and battery power. | ||
|
|
||
| This spec defines a dual-strategy approach: | ||
| 1. **Passive Signaling:** Inclusion of Peer ID in BLE Scan Responses (Server-side). | ||
| 2. **Active Signaling:** A dedicated GATT "Identity Characteristic" for clients to write their ID immediately upon connection. | ||
|
|
||
| **Target Audience:** Android & iOS Engineering Teams. | ||
|
|
||
| --- | ||
|
|
||
| ## 2. Protocol Constants | ||
|
|
||
| ### 2.1 UUIDs | ||
| All Bitchat BLE operations use the following 128-bit UUIDs. | ||
|
|
||
| | Name | UUID | Usage | | ||
| |------|------|-------| | ||
| | **Service UUID** | `F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C` | The main Bitchat Mesh Service. | | ||
| | **Data Characteristic** | `A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5D` | Main channel for `BitchatPacket` transfer (Notify/Write). | | ||
| | **Identity Characteristic** | `A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5E` | **(NEW)** For clients to signal identity (Write/WriteNr). | | ||
|
|
||
| ### 2.2 Data Formats | ||
| * **Peer ID Truncation:** For BLE signaling, the full 64-char hex Peer ID is truncated to the **first 8 bytes** (16 hex characters). | ||
| * **Byte Order:** Big-Endian (Network Byte Order). | ||
|
|
||
| --- | ||
|
|
||
| ## 3. Passive Signaling (Advertisements) | ||
| *Already implemented on Android and iOS.* | ||
|
|
||
| When acting as a Peripheral (Server), the node **MUST** include its truncated Peer ID in the **Scan Response** packet. | ||
|
|
||
| * **Data Type:** Service Data (0x16) | ||
| * **UUID:** `F47B5E2D-4A9E-4C5A-9B3F-8E1D2C3A4B5C` (16-bit or 128-bit representation depending on space) | ||
| * **Payload:** First 8 bytes of Peer ID. | ||
|
|
||
| **Behavior:** | ||
| * Scanners (Clients) can map the ephemeral MAC address to this Peer ID *before* connecting. | ||
| * If the Scanner is already connected to this Peer ID (via a different MAC), it **MUST NOT** initiate a new connection. | ||
|
|
||
| --- | ||
|
|
||
| ## 4. Active Signaling (Identity Characteristic) | ||
| *New implementation requirement.* | ||
|
|
||
| When acting as a Central (Client), the node cannot advertise its ID to the Server if the Server is not scanning. Therefore, the Client **MUST** write its identity to the Server immediately after connection establishment. | ||
|
|
||
| ### 4.1 Client Implementation Spec | ||
| 1. **Connect** to the Peripheral. | ||
| 2. **Discover Services**. | ||
| 3. Check for the existence of `Identity Characteristic` (`...C5E`). | ||
| 4. **Action:** If present, write the local truncated Peer ID (8 bytes) to this characteristic. | ||
| * **Write Type:** `WRITE_TYPE_NO_RESPONSE` (preferred for speed) or `WRITE_TYPE_DEFAULT`. | ||
| 5. **Timing:** This MUST be the **first** action after service discovery, before enabling notifications on the Data Characteristic. | ||
|
|
||
| #### Android Reference (Client) | ||
| ```kotlin | ||
| // In onServicesDiscovered() | ||
| val identityChar = service.getCharacteristic(IDENTITY_CHARACTERISTIC_UUID) | ||
| if (identityChar != null) { | ||
| // 1. Prepare 8-byte ID | ||
| val idBytes = myPeerID.chunked(2).map { it.toInt(16).toByte() } | ||
| .toByteArray().take(8).toByteArray() | ||
|
|
||
| // 2. Write to characteristic | ||
| identityChar.value = idBytes | ||
| identityChar.writeType = BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE | ||
| gatt.writeCharacteristic(identityChar) | ||
| } | ||
| ``` | ||
|
|
||
| ### 4.2 Server Implementation Spec | ||
| 1. **Add Characteristic:** The GATT Server MUST include the `Identity Characteristic` in its service definition. | ||
| * **Properties:** `Write` | `Write No Response` | ||
| * **Permissions:** `Write` | ||
| 2. **Handle Write Request:** When a write request is received on this UUID: | ||
| * **Extract** the 8-byte Peer ID. | ||
| * **Bind** the identity to the current connection handle (MAC address). | ||
| * **Execute Deduplication Policy** (see Section 5). | ||
|
|
||
| #### Android Reference (Server) | ||
| ```kotlin | ||
| // In onCharacteristicWriteRequest() | ||
| if (characteristic.uuid == IDENTITY_CHARACTERISTIC_UUID) { | ||
| val peerID = value.joinToString("") { "%02x".format(it) } | ||
|
|
||
| // 1. Update internal mapping (MAC -> PeerID) | ||
| connectionTracker.setDevicePeerID(device.address, peerID) | ||
|
|
||
| // 2. Deduplication Check | ||
| val duplicate = connectionTracker.getConnectedDevices().values.firstOrNull { | ||
| it.peerID == peerID && it.device.address != device.address | ||
| } | ||
|
|
||
| if (duplicate != null) { | ||
| // Peer is already connected via a different MAC | ||
| Log.w(TAG, "Deduplication: Rejecting new connection from $peerID") | ||
|
|
||
| // Respond success to complete the transaction gracefully | ||
| if (responseNeeded) { | ||
| gattServer.sendResponse(device, requestId, GATT_SUCCESS, 0, null) | ||
| } | ||
|
|
||
| // Terminate the NEW connection | ||
| gattServer.cancelConnection(device) | ||
| return | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| --- | ||
|
|
||
| ## 5. Deduplication Policy | ||
|
|
||
| The goal is to allow only **one** logical connection between any two peers, regardless of direction (Client/Server) or MAC address rotation. | ||
|
|
||
| ### 5.1 Rules | ||
| 1. **Peer ID Primacy:** The persistent Peer ID is the source of truth, not the MAC address. | ||
| 2. **First-Come-First-Served:** The *existing* stable connection is preferred. A new incoming connection attempting to claim the same Peer ID will be rejected. | ||
| 3. **Cross-Role Deduplication:** | ||
| * If Node A is connected to Node B (A=Client, B=Server). | ||
| * And Node B tries to connect to Node A (B=Client, A=Server). | ||
| * If both sides identify correctly, one link is redundant. | ||
| * *Current Policy:* Bitchat currently treats dual-direction links as acceptable but suboptimal. However, strict deduplication via **Active Signaling** will treat the second link as a duplicate if the application layer maps them to the same ID. | ||
| * **Strict Mode (Recommended):** If `PeerID_X` is connected as a client, do NOT accept `PeerID_X` as a server. | ||
|
|
||
| ### 5.2 Conflict Resolution Flow | ||
| 1. **New Connection (Incoming):** Device `AA:BB:CC` connects. | ||
| 2. **Identity Signal:** Device writes ID `12345678`. | ||
| 3. **Lookup:** Server checks list of *other* active connections. | ||
| * Is `12345678` connected via `DD:EE:FF`? | ||
| 4. **Decision:** | ||
| * **Yes:** Disconnect `AA:BB:CC` immediately. (Keep the old, stable link). | ||
| * **No:** Accept `AA:BB:CC` and update the map. | ||
|
|
||
| --- | ||
|
|
||
| ## 6. iOS Implementation Notes | ||
|
|
||
| ### Swift Implementation Guidance | ||
| The iOS `CoreBluetooth` implementation should mirror the logic above. | ||
|
|
||
| **CBPeripheralManagerDelegate:** | ||
| In `didReceiveWrite requests`: | ||
| ```swift | ||
| func peripheralManager(_ peripheral: CBPeripheralManager, didReceiveWrite requests: [CBATTRequest]) { | ||
| for request in requests { | ||
| if request.characteristic.uuid == CBUUID(string: "A1B2C3D4-E5F6-4A5B-8C9D-0E1F2A3B4C5E") { | ||
| let peerData = request.value | ||
| // 1. Parse PeerID | ||
| // 2. Check Connection Manager for existing PeerID | ||
| // 3. If duplicate, cancel connection: | ||
| // peripheralManager.respond(to: request, withResult: .success) | ||
| // // Wait briefly or disconnect immediately? | ||
| // // CBCentralManager usually handles disconnects, but as a Peripheral, | ||
| // // you simply stop processing. To force disconnect, you might need | ||
| // // to let the Central handle the rejection or implement app-layer timeout. | ||
| // // NOTE: iOS Peripheral cannot force-disconnect a Central easily. | ||
| // // Alternative: Send an app-layer "Disconnect" packet or error response. | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **Note on iOS Peripheral Disconnects:** | ||
| Unlike Android, iOS `CBPeripheralManager` does not have a direct `cancelConnection` for a specific central. | ||
| * **Strategy:** If a duplicate is detected, the iOS Peripheral should respond with a custom GATT Error (if possible) or simply ignore further data requests, causing the Central (if Bitchat) to timeout. | ||
| * **Preferred Strategy:** The Android/iOS **Client** (Central) is the one that typically manages the connection lifecycle. If the Server detects a duplicate, it could write a specific "Go Away" code to the characteristic or simply refuse to process further packets. | ||
| * **Protocol Refinement:** If the Server responds with `GATT_SUCCESS`, the Client assumes it's accepted. If the Server responds with an error (e.g., `CBATTError.insufficientResources` or a custom code), the Client should disconnect itself. | ||
|
|
||
| **Refined Server Logic (Cross-Platform):** | ||
| If the Server detects a duplicate: | ||
| 1. Respond to the Write Request with `GATT_SUCCESS` (to satisfy the protocol). | ||
| 2. Internally flag this `CBCentral` as "Rejected". | ||
| 3. Ignore any subsequent data writes from this Central. | ||
| 4. (Optional) If the Central subscribes to the Data Characteristic, send a single "Disconnect Command" packet and then stop notifying. | ||
|
|
||
| ### Android Compliance | ||
| The Android implementation provided in the Reference section uses `gattServer.cancelConnection(device)`, which effectively terminates the link. iOS devices acting as Clients will see this as a disconnection and should handle it gracefully (auto-retry logic should respect the fact that it might be a purposeful disconnect, but standard backoff applies). |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Android’s GATT stack only allows one outstanding operation at a time, and this path issues
writeCharacteristic(identityChar)and then immediately proceeds to write the CCCD. On devices that enforce serialization (common), the subsequentwriteDescriptorcan return false/never execute, leaving notifications disabled and the connection unable to receive data even though it is marked “connected.” This is especially risky withWRITE_TYPE_NO_RESPONSE, which provides no completion signal to gate the descriptor write. Consider queueing the CCCD write and only enabling notifications after the identity write completes (or use a write type with a completion callback).Useful? React with 👍 / 👎.