Skip to content

Changes

Page history
Update formmating to work better with Gitlab Markdown authored by paul's avatar paul
Show whitespace changes
Inline Side-by-side
Public-Mesh-Research-Report.md
View page @ b30c48dc
by The Briar Team # Public Mesh Research
By the Briar Team
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
# Table of Contents # Table of Contents
1. [Motivation](#orgb77977c) - [Public Mesh Research](#public-mesh-research)
2. [Transport Layers](#org3c3c551) - [Table of Contents](#table-of-contents)
1. [API Map](#orgf6c8f50) - [Motivation](#motivation)
2. [Device Map](#orgc7deb77) - [Transport Layers](#transport-layers)
3. [Source Code](#org061007d) - [Prologue](#prologue)
4. [Automation Suite](#org761cf0a) - [API Map](#api-map)
5. [Simulating Internet Shutdowns](#org1439fc1) - [Device Map](#device-map)
1. [Experiment setup](#orgea14985) - [Source Code](#source-code)
2. [1. Fake captive portal](#orgec4a93a) - [Automation Suite](#automation-suite)
3. [2. Manipulating DNS responses for some of Google’s domains](#orgfea69a7) - [Simulating Internet Shutdowns](#simulating-internet-shutdowns)
4. [Summary](#orgf1c44aa) - [Experiment setup](#experiment-setup)
6. [Bluetooth](#org7e41f02) - [Fake captive portal](#fake-captive-portal)
1. [Resources](#org0962a9c) - [Manipulating DNS responses for some of Google’s domains](#manipulating-dns-responses-for-some-of-googles-domains)
2. [BLE](#org3c75e90) - [Summary](#summary)
3. [BLESSED](#org0117473) - [Bluetooth](#bluetooth)
4. [BLE Allocator Characteristic](#org4b874c2) - [Resources](#resources)
5. [BluetoothCommunicator](#org970e8d5) - [BLE](#ble)
7. [WiFi](#org18dfbcb) - [Security](#security)
1. [Network Service Discovery (NSD)](#orge1b6347) - [Pairing Fix](#pairing-fix)
2. [Local Service Discovery (LSD)](#org7e86006) - [Existing Library](#existing-library)
3. [WiFi Client](#org38f6c2d) - [Android Permissions](#android-permissions)
4. [WiFi Direct](#orga6da152) - [BLESSED](#blessed)
8. [Alternative Transports](#org7efd1ad) - [Peer Advertisement](#peer-advertisement)
9. [Future Considerations](#org12ba11d) - [Peer Discovery](#peer-discovery)
1. [Mix-and-Match Transport Layers](#org2e599ad) - [Peer Connectivity](#peer-connectivity)
2. [Evaluate Briar's Threat Model](#org06644e6) - [GATT](#gatt)
3. [Transport Energy Draw Experiments](#orge2804d6) - [L2CAP](#l2cap)
3. [Routing Protocols [WIP]](#org8e12274) - [Notes](#notes)
1. [Existing Research](#orgd01fde7) - [BLE Allocator Characteristic](#ble-allocator-characteristic)
4. [UI/UX Research [WIP]](#orgd77c49e) - [Peer Advertisement](#peer-advertisement-1)
1. [Security Profiles](#org63e0a5d) - [Peer Discovery](#peer-discovery-1)
2. [Connectivity Profiles](#orgcec3fe9) - [Peer Connectivity](#peer-connectivity-1)
5. [Appendix](#org65e3ac0) - [Notes](#notes-1)
1. [Similar Projects](#org3415686) - [BluetoothCommunicator](#bluetoothcommunicator)
1. [Community and mesh networks:](#org69796f3) - [Peer Advertisement](#peer-advertisement-2)
2. [Darknet and friend-to-friend projects:](#orgcb9e9e6) - [Peer Discovery](#peer-discovery-2)
3. [Social P2P projects:](#orge011c69) - [Peer Connectivity](#peer-connectivity-2)
4. [Sneakernets and DTN:](#org58cb9af) - [Notes](#notes-2)
- [Wi-Fi](#wi-fi)
<a id="orgb77977c"></a> - [Network Service Discovery (NSD)](#network-service-discovery-nsd)
- [Peer Advertisement](#peer-advertisement-3)
- [Peer Discovery](#peer-discovery-3)
- [Peer Connectivity](#peer-connectivity-3)
- [Notes](#notes-3)
- [Local Service Discovery (LSD)](#local-service-discovery-lsd)
- [Peer Advertisement](#peer-advertisement-4)
- [Peer Discovery](#peer-discovery-4)
- [Peer Connectivity](#peer-connectivity-4)
- [Notes](#notes-4)
- [Wi-Fi Client](#wi-fi-client)
- [Peer Advertisement](#peer-advertisement-5)
- [Peer Discovery](#peer-discovery-5)
- [Peer Connectivity](#peer-connectivity-5)
- [Notes](#notes-5)
- [Wi-Fi Direct](#wi-fi-direct)
- [Peer Advertisement](#peer-advertisement-6)
- [Peer Discovery](#peer-discovery-6)
- [Peer Connectivity](#peer-connectivity-6)
- [Notes](#notes-6)
- [Alternative Transports](#alternative-transports)
- [OuiSync](#ouisync)
- [P2P Connections over Intranets](#p2p-connections-over-intranets)
- [LoRa / Ham Radio](#lora--ham-radio)
- [Filesystem API](#filesystem-api)
- [Future Considerations](#future-considerations)
- [Mix-and-Match Transport Layers](#mix-and-match-transport-layers)
- [Evaluate Briar's Threat Model](#evaluate-briars-threat-model)
- [Transport Energy Draw Experiments](#transport-energy-draw-experiments)
- [Routing Protocols [WIP]](#routing-protocols-wip)
- [Existing Research](#existing-research)
- [UI/UX Research [WIP]](#uiux-research-wip)
- [Security Profiles](#security-profiles)
- [Connectivity Profiles](#connectivity-profiles)
- [Appendix](#appendix)
- [Similar Projects](#similar-projects)
- [Community and mesh networks:](#community-and-mesh-networks)
- [Darknet and friend-to-friend projects:](#darknet-and-friend-to-friend-projects)
- [Social P2P projects:](#social-p2p-projects)
- [Sneakernets and DTN:](#sneakernets-and-dtn)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Motivation # Motivation
...@@ -54,46 +98,30 @@ For transports with short effective range like Bluetooth, a one-hop social mesh ...@@ -54,46 +98,30 @@ For transports with short effective range like Bluetooth, a one-hop social mesh
To potentially improve connectivity in internet shutdown scenarios, the Briar team is conducting research on using "social mesh" and "public mesh" propagation strategies for messages. To potentially improve connectivity in internet shutdown scenarios, the Briar team is conducting research on using "social mesh" and "public mesh" propagation strategies for messages.
This research covers the Briar team's findings for public mesh propagation. This research covers the Briar team's findings for public mesh propagation.
<a id="org3c3c551"></a>
# Transport Layers # Transport Layers
The base layer of any mesh networking protocol is the individual direct connections between peer devices. In this section we explore a set of possible transport layers for discovering, and connecting to peer devices. The target for this research is primarily mobile-friendly protocols, however support for other computing devices is also worth considering. The base layer of any mesh networking protocol is the individual direct connections between peer devices. In this section we explore a set of possible transport layers for discovering, and connecting to peer devices. The target for this research is primarily mobile-friendly protocols, however support for other computing devices is also worth considering.
## Prologue
<a id="orgf6c8f50"></a> ### API Map
## API Map
[TODO] fix md table [TODO] fix md table
### Device Map
<a id="orgc7deb77"></a>
## Device Map
Moto G 4G, Huawei P8 Lite 2015, Samsung J5 2016, Huawei Y6P, Samsung Galaxy A21s and Sony XZ2 Moto G 4G, Huawei P8 Lite 2015, Samsung J5 2016, Huawei Y6P, Samsung Galaxy A21s and Sony XZ2
[TODO] fix md table [TODO] fix md table
### Source Code
<a id="org061007d"></a> All of the source code for this project can be found in the [Public Mesh Testbed project](https://code.briarproject.org/briar/public-mesh-testbed) on Briar Project's gitlab. As a way of managing the many different transport layers we are testing for in this project, we use different git branches to represent different transport layer properties.
## Source Code
All of the source code for this project can be found in the [Public Mesh Testbed project](https://code.briarproject.org/briar/public-mesh-testbed) on Briar Project's website. As a way of managing the many different transport layers we are testing for in this project, we use different git branches to represent different transport-layer properties.
<a id="org761cf0a"></a>
## Automation Suite
Testing mesh networking software is often challenging from a developer's perspective because it usually entails juggling handfuls of hardware devices. In order to make it easier to create replicatable testing environments for our software, we started experimenting with Google's Mobly framework, which allows us to run replicatable p2p mesh test suites on sets of hardware devices. This is still a work-in-progress, you can track updates here: <https://code.briarproject.org/briar/public-mesh-research/-/issues/18> ### Automation Suite
Testing mesh networking software is often challenging from a developer's perspective because it usually entails juggling handfuls of hardware devices. In order to make it easier to create repeatable testing environments for our software, we started experimenting with Google's Mobly framework, which allows us to run repeatable p2p mesh test suites on sets of hardware devices. This is still a work-in-progress, you can track updates here: <https://code.briarproject.org/briar/public-mesh-research/-/issues/18>
<a id="org1439fc1"></a> ### Simulating Internet Shutdowns
## Simulating Internet Shutdowns
One aspect of our public mesh research is looking into how Android devices behave in case of an Internet shutdown. While it is clear that during a full or partial Internet shutdown, many websites and services cannot be reached from any device, it is not so clear which functionality remains intact. The Android operating system has mechanisms to detect whether a device has a working Internet connection, and we wanted to find out whether this assessment might prevent installed apps from communicating with servers that were technically still reachable. One aspect of our public mesh research is looking into how Android devices behave in case of an Internet shutdown. While it is clear that during a full or partial Internet shutdown, many websites and services cannot be reached from any device, it is not so clear which functionality remains intact. The Android operating system has mechanisms to detect whether a device has a working Internet connection, and we wanted to find out whether this assessment might prevent installed apps from communicating with servers that were technically still reachable.
...@@ -103,68 +131,50 @@ The experiments showed that it is relatively simple to simulate a partial Intern ...@@ -103,68 +131,50 @@ The experiments showed that it is relatively simple to simulate a partial Intern
This is good news for apps like Briar that are designed to operate during Internet shutdowns, making use of whatever network connectivity is available. This is good news for apps like Briar that are designed to operate during Internet shutdowns, making use of whatever network connectivity is available.
#### Experiment setup
<a id="orgea14985"></a>
### Experiment setup
The basic setup for our experiments was a Linux-based Wi-Fi router that was configured in different ways to simulate an Internet shutdown. A phone running Android 11 was used for testing. The idea was to block just enough of the network to make Android think the Internet connection was broken, and then test whether apps could still use the network. The basic setup for our experiments was a Linux-based Wi-Fi router that was configured in different ways to simulate an Internet shutdown. A phone running Android 11 was used for testing. The idea was to block just enough of the network to make Android think the Internet connection was broken, and then test whether apps could still use the network.
We already knew that a special domain name was used for checking Internet connectivity: connectivitycheck.gstatic.com. Android uses this domain to test whether the phone is connected to a Wi-Fi network with a so-called captive portal, where the user needs to accept some terms and conditions before gaining Internet access. We manipulated the DNS server to behave in different ways for that special domain name and created four distinct situations: We already knew that a special domain name was used for checking Internet connectivity: `connectivitycheck.gstatic.com`. Android uses this domain to test whether the phone is connected to a Wi-Fi network with a so-called captive portal, where the user needs to accept some terms and conditions before gaining Internet access. We manipulated the DNS server to behave in different ways for that special domain name and created four distinct situations:
Install a fake captive portal reachable at connectivitycheck.gstatic.com. Install a fake captive portal reachable at `connectivitycheck.gstatic.com`.
No captive portal, instead configure the DNS server to behave irregularly for connectivitycheck.gstatic.com and some more of Google’s domains: No captive portal, instead configure the DNS server to behave irregularly for `connectivitycheck.gstatic.com` and some more of Google’s domains:
a) return unused IP addresses, a) return unused IP addresses,
b) return DNS error responses, b) return DNS error responses,
c) do not return DNS responses at all. c) do not return DNS responses at all.
A combination of dnsmasq, nginx and iptables was used to set up these situations. A combination of `dnsmasq`, `nginx` and `iptables` was used to set up these situations.
<a id="orgec4a93a"></a>
### 1. Fake captive portal #### Fake captive portal
If you’ve used an Android phone on a public Wi-Fi network, you’re probably familiar with the basic situation created by setup 1). Right after establishing a connection to the Wi-Fi, Android shows a notification telling you that you’re required to sign in to the network in order to use it. The wireless connections settings screen shows a similar message. In addition, the Wi-Fi symbol in the status bar has a small “X” in the corner, as a hint that the network does not provide Internet access. Tapping the notification opens a browser window that usually displays the captive portal, prompting you to enter a token or simply accept some terms and conditions. If you’ve used an Android phone on a public Wi-Fi network, you’re probably familiar with the basic situation created by setup 1). Right after establishing a connection to the Wi-Fi, Android shows a notification telling you that you’re required to sign in to the network in order to use it. The wireless connections settings screen shows a similar message. In addition, the Wi-Fi symbol in the status bar has a small “X” in the corner, as a hint that the network does not provide Internet access. Tapping the notification opens a browser window that usually displays the captive portal, prompting you to enter a token or simply accept some terms and conditions.
We didn’t simulate a full-blown captive portal, just returned an unexpected HTTP response code for the relevant endpoint, connectivitycheck.gstatic.com/generate<sub>204</sub>. Usually, a router would block other network traffic until the user had completed the required confirmation steps in the captive portal. In our case, all network traffic was still possible as far as the router was concerned. We used the Chrome browser to check network access to other websites. Even though the browser showed a black bar at the top saying “No Internet connection”, we were able to browse random sites just fine. We didn’t simulate a full-blown captive portal, just returned an unexpected HTTP response code for the relevant endpoint, `connectivitycheck.gstatic.com/generate_204`. Usually, a router would block other network traffic until the user had completed the required confirmation steps in the captive portal. In our case, all network traffic was still possible as far as the router was concerned. We used the Chrome browser to check network access to other websites. Even though the browser showed a black bar at the top saying “No Internet connection”, we were able to browse random sites just fine.
#### Manipulating DNS responses for some of Google’s domains
<a id="orgfea69a7"></a> Setup 2) was different from the first one in that Android was unable to connect to `connectivitycheck.gstatic.com/generate_204` and receive any HTTP response at all.
### 2. Manipulating DNS responses for some of Google’s domains For case a), `dnsmasq` was configured to return a local IP address for that domain name. We knew this address was not in use at the time, so Android could not connect to an HTTP server at that address. For case b), `dnsmasq` was configured to return an NXDOMAIN response instead, so Android would know immediately that the address lookup had failed. For case c), `iptables` was configured to silently drop the relevant DNS requests.
Setup 2) was different from the first one in that Android was unable to connect to connectivitycheck.gstatic.com/generate<sub>204</sub> and receive any HTTP response at all.
For case a), dnsmasq was configured to return a local IP address for that domain name. We knew this address was not in use at the time, so Android could not connect to an HTTP server at that address. For case b), dnsmasq was configured to return an NXDOMAIN response instead, so Android would know immediately that the address lookup had failed. For case c), iptables was configured to silently drop the relevant DNS requests.
In all three cases, Android didn’t report that the Wi-Fi connection was broken, in contrast to setup 1). In all three cases, Android didn’t report that the Wi-Fi connection was broken, in contrast to setup 1).
Inspecting DNS traffic on the network, we were able to observe that other domains were queried without any user interaction: google.com and www.google.com. Extending the scenarios to block these domains in addition to the connectivity check did cause Android to report that the the Wi-Fi connection was broken. The small “X” on the status bar icon appeared, the Wi-Fi settings screen showed “No Internet” for the current network, and Chrome had the additional black bar at the top saying “No Internet connection”. Inspecting DNS traffic on the network, we were able to observe that other domains were queried without any user interaction: `google.com` and `www.google.com`. Extending the scenarios to block these domains in addition to the connectivity check did cause Android to report that the the Wi-Fi connection was broken. The small “X” on the status bar icon appeared, the Wi-Fi settings screen showed “No Internet” for the current network, and Chrome had the additional black bar at the top saying “No Internet connection”.
Unlike setup 1), there was no prompt to sign into the network. This makes sense, as Android was not able to reach the captive portal. Unlike setup 1), there was no prompt to sign into the network. This makes sense, as Android was not able to reach the captive portal.
As in the first setup, we used Chrome to check random websites. Except for Google, which was really blocked in this setup, we had no problems browsing the web. As in the first setup, we used Chrome to check random websites. Except for Google, which was really blocked in this setup, we had no problems browsing the web.
#### Summary
<a id="orgf1c44aa"></a>
### Summary
When an Android device thinks that its Internet connection doesn’t work, either due to a captive portal or due to certain Google domains being unreachable, apps on the device are still able to connect to IP addresses that remain reachable, and the device can still resolve DNS queries for other domains. Even though various parts of the UI indicate that the system considers the Wi-Fi connection to be offline, the system does not seem to block any traffic as a result of this assessment. When an Android device thinks that its Internet connection doesn’t work, either due to a captive portal or due to certain Google domains being unreachable, apps on the device are still able to connect to IP addresses that remain reachable, and the device can still resolve DNS queries for other domains. Even though various parts of the UI indicate that the system considers the Wi-Fi connection to be offline, the system does not seem to block any traffic as a result of this assessment.
<a id="org7e41f02"></a>
## Bluetooth ## Bluetooth
Bluetooth is a short-range radio technology that comes bundled with most modern day mobile devices. Bluetooth is a short-range radio technology that comes bundled with most modern day mobile devices.
It allows devices to discover each other, and transfer relatively small packets of data over a range of up to 33 feet. It allows devices to discover each other, and transfer relatively small packets of data over a range of up to 33 feet.
The accessibility of Bluetooth API's on most modern day smartphones makes Bluetooth an attractive transport for infrastructure-free data transfers, like those needed for a public mesh system. The accessibility of Bluetooth API's on most modern day smartphones makes Bluetooth an attractive transport for infrastructure-free data transfers, like those needed for a public mesh system.
<a id="org0962a9c"></a>
### Resources ### Resources
Background information about Bluetooth: Background information about Bluetooth:
...@@ -187,35 +197,31 @@ Background information about Bluetooth: ...@@ -187,35 +197,31 @@ Background information about Bluetooth:
<https://code.briarproject.org/briar/public-mesh-testbed/-/tree/bt-classic> <https://code.briarproject.org/briar/public-mesh-testbed/-/tree/bt-classic>
<a id="org3c75e90"></a>
### BLE ### BLE
Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is designed to reduce the energy consumption during use, without greatly impacting functional range. Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is designed to reduce the energy consumption during use, without greatly impacting functional range.
1. Security #### Security
During our research we encountered an open vulnerability which is extremely relevant to the public mesh application development space. During our research we encountered an open vulnerability which is extremely relevant to the public mesh application development space [CVE-2020-12856: A Silent Pairing Issue in Bluetooth-based Contact Tracing Apps](https://raw.githubusercontent.com/alwentiu/COVIDSafe-CVE-2020-12856/master/CVE-2020-12856-19-June-2020.pdf) by authors Alwen Tiu and Jim Mussared, released in May 2020, describes an attack which silently sends a device's Bluetooth MAC address, along with the Bluetooth Identity Resolving Key to an adversary running a spoofed BLE central. In most public mesh protocols, users publish some sort of publicly-identifiable address to the network so that other users in the network can properly route intended messages to their address, so at first this does not seem like a major security issue. However, this attack is particularly relevant even in the public mesh context, because it allows for the identification of users even after a user stops utilizing the public mesh application.
[CVE-2020-12856: A Silent Pairing Issue in Bluetooth-based Contact Tracing Apps](https://raw.githubusercontent.com/alwentiu/COVIDSafe-CVE-2020-12856/master/CVE-2020-12856-19-June-2020.pdf) by authors Alwen Tiu and Jim Mussared, released in May 2020, describes an attack which silently sends a device's Bluetooth MAC address, along with the Bluetooth Identity Resolving Key to an adversary running a spoofed BLE central. In most public mesh protocols, users publish some sort of publically-identifiable address to the network so that other users in the network can properly route intended messages to their address, so at first this does not seem like a major security issue. However, this attack is particularly relevant even in the public mesh context, because it allows for the identification of users even after a user stops utilizing the public mesh application.
1. Pairing Fix ##### Pairing Fix
With our BLE work on this project, we have put together a patch for the BLESSED library that we are using, which fixes this vulnerability by proxying GATT read and write values to remove the authentication flag which triggers automatic pairing. [TODO link the patch when we are eventually able to] With our BLE work on this project, we have put together a patch for the BLESSED library that we are using, which fixes this vulnerability by proxying GATT read and write values to remove the authentication flag which triggers automatic pairing. [TODO link the patch when we are eventually able to]
Our fix is heavily based on work by the COVIDSafe Android application team. The current version of the fix uses Java's reflection API to extract a specific field in the active \`BluetoothGatt\` object, and replace it with a proxy object that runs an \`InvocationHandler\` checking for characteristic read and write invocations. Our fix is heavily based on work by the COVIDSafe Android application team. The current version of the fix uses Java's reflection API to extract a specific field in the active `BluetoothGatt` object, and replace it with a proxy object that runs an `InvocationHandler` checking for characteristic read and write invocations.
The COVIDSafe files that implement this fix are: The COVIDSafe files that implement this fix are:
<https://github.com/AU-COVIDSafe/mobile-android/blob/master/app/src/main/java/au/gov/health/covidsafe/streetpass/StreetPassPairingFix.kt> <https://github.com/AU-COVIDSafe/mobile-android/blob/master/app/src/main/java/au/gov/health/covidsafe/streetpass/StreetPassPairingFix.kt>
<https://github.com/AU-COVIDSafe/mobile-android/blob/master/app/src/main/java/au/gov/health/covidsafe/streetpass/IBluetoothGattInvocationHandler.java> <https://github.com/AU-COVIDSafe/mobile-android/blob/master/app/src/main/java/au/gov/health/covidsafe/streetpass/IBluetoothGattInvocationHandler.java>
Because we want to utilize the BLESSED library, we apply a similar patch to the underlying \`BluetoothGatt\` object that is wrapped in the \`BluetoothPeripheral\` class. Because we want to utilize the BLESSED library, we apply a similar patch to the underlying `BluetoothGatt` object that is wrapped in the `BluetoothPeripheral` class.
2. Existing Library #### Existing Library
We have found that the open source Bluetooth library, [BLESSED](https://github.com/weliem/blessed-android) is useful for working with BLE on android. Their project README.md offers an introduction to the library for new users, and they also offer a number of [example projects](https://github.com/weliem/blessed-android/tree/master/app/src/main/java/com/welie/blessedexample) to help developers get started with BLESSED. We have found that the open source Bluetooth library, [BLESSED](https://github.com/weliem/blessed-android) is useful for working with BLE on android. Their project README.md offers an introduction to the library for new users, and they also offer a number of [example projects](https://github.com/weliem/blessed-android/tree/master/app/src/main/java/com/welie/blessedexample) to help developers get started with BLESSED.
3. Android Permissions #### Android Permissions
On a mobile device, a public mesh Bluetooth service needs to be able to run uninterrupted in the background, and also need to be able to make bluetooth advertisements and connections in the background. To do this, all of the Bluetooth Low Energy based branches of the testbed application request the following permissions: On a mobile device, a public mesh Bluetooth service needs to be able to run uninterrupted in the background, and also need to be able to make bluetooth advertisements and connections in the background. To do this, all of the Bluetooth Low Energy based branches of the testbed application request the following permissions:
...@@ -245,22 +251,18 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig ...@@ -245,22 +251,18 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig
<uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" /> <uses-permission android:name="android.permission.REQUEST_IGNORE_BATTERY_OPTIMIZATIONS" />
On the user side, they end up getting the following permission pop-ups on API 31+ devices: On the user side, they end up getting the following permission pop-ups on API 31+ devices:
- Nearby Devices - Nearby Devices
- "Let app always run in the background" - "Let app always run in the background"
- Notifications - Notifications
On older devices, (SDK 30 and earlier) the mesh testbed app requires location-based permssions which creates a UX hurdle for future public mesh applications because it could cause users to believe their locations are being tracked. On older devices, (SDK 30 and earlier) the mesh testbed app requires location-based permissions which creates a UX hurdle for future public mesh applications because it could cause users to believe their locations are being tracked.
<a id="org0117473"></a>
### BLESSED ### BLESSED
1. Peer Advertisement #### Peer Advertisement
Peer advertisement happens using BLE's peripheral advertisement protocol. Peripheral devices build a schema of characteristics, and advertise their core service UUID over the Bluetooth frequency band. Peer advertisement happens using BLE's peripheral advertisement protocol. Peripheral devices build a schema of characteristics, and advertise their core service UUID over the Bluetooth frequency band.
Using BLESSED's library, and their \`PeripheralManager\` class, you can easily create and add characteristics: Using BLESSED's library, and their `PeripheralManager` class, you can easily create and add characteristics:
BluetoothGattCharacteristic allocatorChar = new BluetoothGattCharacteristic(ALLOCATOR_UUID,PROPERTY_READ, PERMISSION_READ); BluetoothGattCharacteristic allocatorChar = new BluetoothGattCharacteristic(ALLOCATOR_UUID,PROPERTY_READ, PERMISSION_READ);
gattService.addCharacteristic(allocatorChar); gattService.addCharacteristic(allocatorChar);
...@@ -270,26 +272,26 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig ...@@ -270,26 +272,26 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig
peripheralManager.startAdvertising(adSettings, adData, scanResponse); peripheralManager.startAdvertising(adSettings, adData, scanResponse);
For more information on how the \`blessed\` branch creates and advertises it's GATT service: For more information on how the `blessed` branch creates and advertises it's GATT service:
<https://code.briarproject.org/briar/public-mesh-testbed/-/blob/blessed-gatt/app/src/main/java/org/briarproject/publicmesh/bt/BtServiceImpl.java#L261> <https://code.briarproject.org/briar/public-mesh-testbed/-/blob/blessed-gatt/app/src/main/java/org/briarproject/publicmesh/bt/BtServiceImpl.java#L261>
2. Peer Discovery #### Peer Discovery
Scanning for nearby peers is a key component of the Bluetooth Low Energy protocol. When the Bluetooth service is running, the central component of the public mesh BLE service will scan in the background looking for peripherals that are advertising the set UUID for this application. When the service discovers a nearby peripheral using the BLESSED library, it will fire the \`onDiscoveredPeripheral()\` callback function. BLESSED will also automatically handle "service discovery" which is a handshake that happens behind the scene between the devices so the central device can understand what resources are being hosted by the peripheral. BLESSED conviniently also gives you a callback on this event called \`onServicesDiscovered()\`. Scanning for nearby peers is a key component of the Bluetooth Low Energy protocol. When the Bluetooth service is running, the central component of the public mesh BLE service will scan in the background looking for peripherals that are advertising the set UUID for this application. When the service discovers a nearby peripheral using the BLESSED library, it will fire the `onDiscoveredPeripheral()` callback function. BLESSED will also automatically handle "service discovery" which is a handshake that happens behind the scene between the devices so the central device can understand what resources are being hosted by the peripheral. BLESSED conveniently also gives you a callback on this event called `onServicesDiscovered()`.
3. Peer Connectivity #### Peer Connectivity
Bluetooth Low Energy offers two different ways of actually connecting and sharing data between devices, the previously mentioned GATT service can be used to broadcast resources that centrals can connect, and read and write to. BLE also offers L2CAP, or "logical link control and adaptation protocol". L2CAP offers a "connection oriented channel" approach that is much closer to traditional socket programming than the GATT protocol. This makes programming larger data transfers with L2CAP much easier, however API support for L2CAP on android devices is worse compared to GATT, so our general thinking is to attempt to create links between devices using L2CAP, but fall back to using GATT in case devices in the handshake do not support L2CAP. Bluetooth Low Energy offers two different ways of actually connecting and sharing data between devices, the previously mentioned GATT service can be used to broadcast resources that centrals can connect, and read and write to. BLE also offers L2CAP, or "logical link control and adaptation protocol". L2CAP offers a "connection oriented channel" approach that is much closer to traditional socket programming than the GATT protocol. This makes programming larger data transfers with L2CAP much easier, however API support for L2CAP on android devices is worse compared to GATT, so our general thinking is to attempt to create links between devices using L2CAP, but fall back to using GATT in case devices in the handshake do not support L2CAP.
1. GATT ##### GATT
Like most other BLE functionalities, BLESSED allows us to easily connect to a given `BluetoothPeripheral` object by using the `centralManager.connectPeripheral()` method. For the full implementation of peer connections on the `blessed` branch: <https://code.briarproject.org/briar/public-mesh-testbed/-/blob/blessed-gatt/app/src/main/java/org/briarproject/publicmesh/bt/BtServiceImpl.java#L320>
Like most other BLE functionalities, BLESSED allows us to easily connect to a given \`BluetoothPeripheral\` object by using the \`centralManager.connectPeripheral()\` method. For the full implementation of peer connections on the \`blessed\` branch: <https://code.briarproject.org/briar/public-mesh-testbed/-/blob/blessed-gatt/app/src/main/java/org/briarproject/publicmesh/bt/BtServiceImpl.java#L320> ##### L2CAP
2. L2CAP With L2CAP, there is less of a divide between "central" and "peripheral" devices like in the GATT system. Instead of advertising a set of resources like a GATT peripheral device, with L2CAP, devices advertise a "PSM" value which is similar to a port number, and open a Bluetooth Server Socket running on that PSM value. On our `blessed` branch, we advertise the open socket if the device supports L2CAP:
With L2CAP, there is less of a divide between "central" and "peripheral" devices like in the GATT system. Instead of advertising a set of resources like a GATT peripheral device, with L2CAP, devices advertise a "PSM" value which is similar to a port number, and open a Bluetooth Server Socket running on that PSM value. On our \`blessed\` branch, we advertise the open socket if the device supports L2CAP:
```Java
if (USE_L2CAP && SDK_INT >= 29 && serverSocket == null) openServerSocket(); if (USE_L2CAP && SDK_INT >= 29 && serverSocket == null) openServerSocket();
AdvertiseSettings adSettings = new AdvertiseSettings.Builder() AdvertiseSettings adSettings = new AdvertiseSettings.Builder()
.setConnectable(true) .setConnectable(true)
...@@ -301,13 +303,13 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig ...@@ -301,13 +303,13 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig
byte[] serviceData = new byte[4]; byte[] serviceData = new byte[4];
writeUint32(psm, serviceData, 0); writeUint32(psm, serviceData, 0);
scanResponse = new AdvertiseData.Builder() scanResponse = new AdvertiseData.Builder()
.addServiceData(PARCEL_UUID, serviceData) .addServiceData(PARCEL_UUID, serviceData).build();
.build();
} }
```
Then, whenever we discover a L2CAP-compatible device, we can connect to it using a method like the \`connectViaSocket()\` method on the \`blessed\` branch: <https://code.briarproject.org/briar/public-mesh-testbed/-/blob/blessed-gatt/app/src/main/java/org/briarproject/publicmesh/bt/BtServiceImpl.java#L416> Then, whenever we discover a L2CAP-compatible device, we can connect to it using a method like the `connectViaSocket()` method on the `blessed` branch: <https://code.briarproject.org/briar/public-mesh-testbed/-/blob/blessed-gatt/app/src/main/java/org/briarproject/publicmesh/bt/BtServiceImpl.java#L416>
4. Notes #### Notes
- Some devices (eg Samsung J5 2016) receive the advertising packet but not the scan record, so if we want to provide extra information in the scan record we also need to make this information available via GATT - Some devices (eg Samsung J5 2016) receive the advertising packet but not the scan record, so if we want to provide extra information in the scan record we also need to make this information available via GATT
- BLESSED doesn't provide a wrapper for the new advertising set API, which supports new Bluetooth 5 advertising features such as periodic advertising, extended advertising and coded PHY, so if we want to use those features we'll need to use the Android API directly - BLESSED doesn't provide a wrapper for the new advertising set API, which supports new Bluetooth 5 advertising features such as periodic advertising, extended advertising and coded PHY, so if we want to use those features we'll need to use the Android API directly
...@@ -317,19 +319,16 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig ...@@ -317,19 +319,16 @@ Bluetooth Low Energy is a separate protocol from Bluetooth Classic that is desig
- Some devices allow connections to multiple peripherals when acting as a central - Some devices allow connections to multiple peripherals when acting as a central
- Some devices also support connections from multiple centrals when acting as a peripheral, but since GATT doesn't provide a way to send data to a specific central we'd need to do some creative thinking to make use of this - Some devices also support connections from multiple centrals when acting as a peripheral, but since GATT doesn't provide a way to send data to a specific central we'd need to do some creative thinking to make use of this
- L2CAP connection-oriented channels (CoC) seem to work as advertised. The server socket provides a PSM (something like a dynamic port number) that needs to be communicated to the client somehow (eg via BLE advertising). We can use L2CAP when the central and peripheral both support it and fall back to GATT when they don't - L2CAP connection-oriented channels (CoC) seem to work as advertised. The server socket provides a PSM (something like a dynamic port number) that needs to be communicated to the client somehow (eg via BLE advertising). We can use L2CAP when the central and peripheral both support it and fall back to GATT when they don't
- The P8 Lite doesn't support advertising (BluetoothAdapter#getBluetoothLeAdvertiser() returns null) - The P8 Lite doesn't support advertising (`BluetoothAdapter#getBluetoothLeAdvertiser()` returns `null`)
- The Moto G never receives the result of starting advertising (no callback to onAdvertisingStarted() or onAdvertiseFailure()) - The Moto G never receives the result of starting advertising (no callback to `onAdvertisingStarted()` or `onAdvertiseFailure()`)
- The Moto G and P8 Lite can discover the J5, but it can't discover them and they can't discover each other - The Moto G and P8 Lite can discover the J5, but it can't discover them and they can't discover each other
- The P8 Lite can connect to the J5 via GATT and exchange pings and pongs - The P8 Lite can connect to the J5 via GATT and exchange pings and pongs
- The Moto G can't connect to the J5 via GATT: it receives a callback to onConnectingPeripheral(), never receives onConnectedPeripheral(), and eventually receives onDisconnectedPeripheral() with status LMP<sub>OR</sub><sub>LL</sub><sub>RESPONSE</sub><sub>TIMEOUT</sub>. The J5 receives onCentralConnected() and onCentralDisconnected() as expected. The J5 can subsequently connect back to the Moto G, using the address it learned from the unsuccessful connection, and exchange pings and pongs - The Moto G can't connect to the J5 via GATT: it receives a callback to `onConnectingPeripheral()`, never receives `onConnectedPeripheral()`, and eventually receives `onDisconnectedPeripheral()` with status `LMP_OR_LL_RESPONSE_TIMEOUT`. The J5 receives onCentralConnected() and onCentralDisconnected() as expected. The J5 can subsequently connect back to the Moto G, using the address it learned from the unsuccessful connection, and exchange pings and pongs
- When the J5 receives a connection from the Moto G or P8 Lite, the J5 sees the same address that the Moto G/P8 Lite gets from its own BluetoothAdapter, ie the BT classic address. So it may be possible for the Moto G/P8 Lite to advertise this address via WFD (since BLE advertising isn't available) and use the address to receive GATT connections and/or BT classic connections. - When the J5 receives a connection from the Moto G or P8 Lite, the J5 sees the same address that the Moto G/P8 Lite gets from its own BluetoothAdapter, ie the BT classic address. So it may be possible for the Moto G/P8 Lite to advertise this address via WFD (since BLE advertising isn't available) and use the address to receive GATT connections and/or BT classic connections.
<a id="org4b874c2"></a>
### BLE Allocator Characteristic ### BLE Allocator Characteristic
The \`blessed\` testbed branch exemplifies how individual connections can be made using BLE. However, the one of the core features for a performant ad-hoc mesh system is the ability to make simultanious p2p connections between 3+ devices. In order to support multi-device scenarios, we developed the "allocator characteristic" system which guides incoming central devices to the correct read characteristic, in order to read arbitrary amounts of data from the advertising peripheral device. The `blessed` testbed branch exemplifies how individual connections can be made using BLE. However, the one of the core features for a performative ad-hoc mesh system is the ability to make simultaneous p2p connections between 3+ devices. In order to support multi-device scenarios, we developed the "allocator characteristic" system which guides incoming central devices to the correct read characteristic, in order to read arbitrary amounts of data from the advertising peripheral device.
The high level structure of the allocator characteristic system is built using two main characteristics: The high level structure of the allocator characteristic system is built using two main characteristics:
- Read Characteristic - Read Characteristic
...@@ -343,342 +342,276 @@ The allocator characteristic is a readable characteristic that displays a list o ...@@ -343,342 +342,276 @@ The allocator characteristic is a readable characteristic that displays a list o
When a new central tries to make a connection to the peripheral device, it will first check this list to confirm it is not already currently reading from that peripheral device. When a new central tries to make a connection to the peripheral device, it will first check this list to confirm it is not already currently reading from that peripheral device.
This system also allows centrals to monitor when a peripheral is fully busy with devices reading from it. This system also allows centrals to monitor when a peripheral is fully busy with devices reading from it.
1. Peer Advertisement #### Peer Advertisement
Peer advertisement is nearly identical to the previous BLESSED section, the Bluetooth peripheral service will advertise a characteristic with a dedicated UUID representing the public mesh application. Peer advertisement is nearly identical to the previous BLESSED section, the Bluetooth peripheral service will advertise a characteristic with a dedicated UUID representing the public mesh application.
2. Peer Discovery #### Peer Discovery
At its core, peer discovery is similar to the approach listed in the BLESSED section earlier. A central Bluetooth device scans for the UUID for the appropriate characteristic. However, with the added allocator characteristic, there is another method that peers can find each other. The allocator characteristic works as an active list of nearby peers, so higher level protocols could possibly utilize this as a way to further increase peer discovery and data propagation. At its core, peer discovery is similar to the approach listed in the BLESSED section earlier. A central Bluetooth device scans for the UUID for the appropriate characteristic. However, with the added allocator characteristic, there is another method that peers can find each other. The allocator characteristic works as an active list of nearby peers, so higher level protocols could possibly utilize this as a way to further increase peer discovery and data propagation.
3. Peer Connectivity #### Peer Connectivity
Because each peripheral has a limited number of read characteristics, protocols built on top of this strategy should prioritize quicker, more frequent connections rather than long lasting data transfers. Because each peripheral has a limited number of read characteristics, protocols built on top of this strategy should prioritize quicker, more frequent connections rather than long lasting data transfers.
A central connects to a peripheral by first by reading the peripheral's allocator characteristic, and confirming it is not already reading from that peripheral. On the connection, the central gives the peripheral it's SESSION<sub>ID</sub>, which is then added to the peripheral's allocator characteristic. By reading this update, the central receives information on which read characteristic to read from. The full handshake as implemented in \`blessed-gatt-allocator-vuln\` and \`blessed-gatt-allocator-pairfix\` is outlined below:
[TODO allocator diagram]
It can be noted that this has been a GATT-only protocol so far, the reasoning behind this is that GATT has much greater support among Android devices, especially devices running older hardware. This allocator system allows for an L2CAP-like abstraction to be made on top of regular GATT reads and writes, and this abstraction could also suport L2CAP (and potentially other transport layers like Local Service Discovery) under the hood for devices that support it. A central connects to a peripheral by first by reading the peripheral's allocator characteristic, and confirming it is not already reading from that peripheral. On the connection, the central gives the peripheral it's SESSION<sub>ID</sub>, which is then added to the peripheral's allocator characteristic. By reading this update, the central receives information on which read characteristic to read from. The full handshake as implemented in `blessed-gatt-allocator-vuln` and `blessed-gatt-allocator-pairfix` is outlined below:
[TODO allocator diagram]
4. Notes
It can be noted that this has been a GATT-only protocol so far, the reasoning behind this is that GATT has much greater support among Android devices, especially devices running older hardware. This allocator system allows for an L2CAP-like abstraction to be made on top of regular GATT reads and writes, and this abstraction could also support L2CAP (and potentially other transport layers like Local Service Discovery) under the hood for devices that support it.
<a id="org970e8d5"></a> #### Notes
### BluetoothCommunicator ### BluetoothCommunicator
BluetoothCommunicator is a BLE library built upon the core Android \`BluetoothGATT\` objects similar to BLESSED. However, unlike BLESSED, BluetoothCommunicator is geared more towards async messaging, and not a general-use library. Because of the added flexibility working with BLESSED gives us, future development of BLE mesh networking tools will likely focus on our allocator characteristic framework. However it is useful to research the BluetoothCommunicator library because it gives us insight into how a higher-level messaging framework might be built upon the allocator characteristic system. BluetoothCommunicator is a BLE library built upon the core Android `BluetoothGATT` objects similar to BLESSED. However, unlike BLESSED, BluetoothCommunicator is geared more towards async messaging, and not a general-use library. Because of the added flexibility working with BLESSED gives us, future development of BLE mesh networking tools will likely focus on our allocator characteristic framework. However it is useful to research the BluetoothCommunicator library because it gives us insight into how a higher-level messaging framework might be built upon the allocator characteristic system.
1. Peer Advertisement #### Peer Advertisement
TODO find code snippets from blechat impl TODO find code snippets from blechat impl
2. Peer Discovery #### Peer Discovery
3. Peer Connectivity
4. Notes
While the library has methods built to enable autopeering, our attempt to enable autopeering with this framework proved unsuccessful. #### Peer Connectivity
#### Notes
<a id="org18dfbcb"></a> While the library has methods built to enable auto-peering, our attempt to enable auto-peering with this framework proved unsuccessful.
## WiFi ## Wi-Fi
<a id="orge1b6347"></a>
### Network Service Discovery (NSD) ### Network Service Discovery (NSD)
1. Peer Advertisement #### Peer Advertisement
<https://developer.android.com/training/connect-devices-wirelessly/nsd#register> <https://developer.android.com/training/connect-devices-wirelessly/nsd#register>
2. Peer Discovery #### Peer Discovery
<https://developer.android.com/training/connect-devices-wirelessly/nsd#discover> <https://developer.android.com/training/connect-devices-wirelessly/nsd#discover>
3. Peer Connectivity #### Peer Connectivity
<https://developer.android.com/training/connect-devices-wirelessly/nsd#connect> <https://developer.android.com/training/connect-devices-wirelessly/nsd#connect>
4. Notes #### Notes
- It's probably worth noting that NSD is also a special case for Android apps running on ChromeOS: apps can't generally make or receive connections via the LAN, except in the case of outgoing connections to services discovered via NSD. See [briar#1362](https://code.briarproject.org/briar/briar/-/issues/1362). - It's probably worth noting that NSD is also a special case for Android apps running on ChromeOS: apps can't generally make or receive connections via the LAN, except in the case of outgoing connections to services discovered via NSD. See [briar#1362](https://code.briarproject.org/briar/briar/-/issues/1362).
- This comment suggests that NSD service resolution will fail for network interfaces that don't have an associated Network instance: - This comment suggests that NSD service resolution will fail for network interfaces that don't have an associated Network instance:
<https://cs.android.com/android/platform/superproject/+/master:packages/modules/Connectivity/service-t/src/com/android/server/NsdService.java;drc=b45a2ea782074944f79fc388df20b06e01f265f7;l=576> <https://cs.android.com/android/platform/superproject/+/master:packages/modules/Connectivity/service-t/src/com/android/server/NsdService.java;drc=b45a2ea782074944f79fc388df20b06e01f265f7;l=576>
- On at least some devices, NSD works when using a WFD legacy mode hotspot. Tested with Samsung A21s as hotspot, Nokia 1.3 as client and vice versa. Tested with the \`wifi-direct-and-nsd\` branch. - On at least some devices, NSD works when using a WFD legacy mode hotspot. Tested with Samsung A21s as hotspot, Nokia 1.3 as client and vice versa. Tested with the `wifi-direct-and-nsd` branch.
- When discovering services via NSD, one needs to resolve each service found to find out IP address, port etc. - When discovering services via NSD, one needs to resolve each service found to find out IP address, port etc.
NsdManager has a method resolveService() for this. Only one service can be resolved at a time, an error with code FAILURE<sub>ALREADY</sub><sub>ACTIVE</sub> will appear when a second simultaneous resolve request is submitted. Hence it is important not to call that method right away when new services have been discovered, instead a queue needs to be maintained and worked on one by one. Resolving a service can succeed or fail and after both events, it should be possible to resolve the next service. It seems however, that sometimes resolving neither succeeds nor fails, but instead we receive a service lost event. We don't get any updates on the resolving request afterwards, but we also cannot submit a new resolve request afterwards, they will still fail with a FAILURE<sub>ALREADY</sub><sub>ACTIVE</sub> error. Even restarting the service discovery entirely did not seem to help. - NsdManager has a method `resolveService()` for this. Only one service can be resolved at a time, an error with code `FAILURE_ALREADY_ACTIVE` will appear when a second simultaneous resolve request is submitted. Hence it is important not to call that method right away when new services have been discovered, instead a queue needs to be maintained and worked on one by one. Resolving a service can succeed or fail and after both events, it should be possible to resolve the next service. It seems however, that sometimes resolving neither succeeds nor fails, but instead we receive a service lost event. We don't get any updates on the resolving request afterwards, but we also cannot submit a new resolve request afterwards, they will still fail with a `FAILURE_ALREADY_ACTIVE` error. Even restarting the service discovery entirely did not seem to help.
- The \`lan-service-discovery-nsd-no-resolution\` branch encodes the IP address in the NSD service name, allowing us to skip the buggy resolution step. - The `lan-service-discovery-nsd-no-resolution` branch encodes the IP address in the NSD service name, allowing us to skip the buggy resolution step.
This means we can't advertise attributes, unless we encode them in the service name along with the address or fetch them separately via unicast. This (abandoned) library implements the latter approach to work around the empty attributes map issue mentioned above: - This means we can't advertise attributes, unless we encode them in the service name along with the address or fetch them separately via unicast. This (abandoned) library implements the latter approach to work around the empty attributes map issue mentioned above:
<https://github.com/youviewtv/tinydnssd> <https://github.com/youviewtv/tinydnssd>
Alternatively we could implement our own unicast protocol for fetching attributes, while still using NSD for the multicast part, to benefit from the special treatment it seems to get on some devices.
<a id="org7e86006"></a> - Alternatively we could implement our own unicast protocol for fetching attributes, while still using NSD for the multicast part, to benefit from the special treatment it seems to get on some devices.
### Local Service Discovery (LSD) ### Local Service Discovery (LSD)
"Local Service Discovery (LSD) provides a SSDP-like (http over udp-multicast) mechanism to announce the presence in specific swarms to local neighbors. It can be used either as primary peer source for local transfers or to complement other sources which only operate on global unicast addresses." - [bep<sub>0014</sub>](https://www.bittorrent.org/beps/bep_0014.html) "Local Service Discovery (LSD) provides a SSDP-like (http over udp-multicast) mechanism to announce the presence in specific swarms to local neighbors. It can be used either as primary peer source for local transfers or to complement other sources which only operate on global unicast addresses." - [bep_0014](https://www.bittorrent.org/beps/bep_0014.html)
1. Peer Advertisement #### Peer Advertisement
<https://www.bittorrent.org/beps/bep_0014.html#protocol> <https://www.bittorrent.org/beps/bep_0014.html#protocol>
The protocol could be further modified for this purpose by removing the infohash and (optional) cookie field. This comes at the effect of giving your application a more noticeable "fingerprint". The protocol could be further modified for this purpose by removing the infohash and (optional) cookie field. This comes at the effect of giving your application a more noticeable "fingerprint".
2. Peer Discovery #### Peer Discovery
To discover peers on the network, start a UdpClient at the specified addresses: A) 239.192.152.143:6771 (org-local) and B) [ff15::efc0:988f]:6771 (site-local) To discover peers on the network, start a UdpClient at the specified addresses: A) 239.192.152.143:6771 (org-local) and B) [ff15::efc0:988f]:6771 (site-local)
3. Peer Connectivity #### Peer Connectivity
Once peers are discovered, a normal TCP connection can be made with the \`HOST:PORT\` value shared in the announcement packet.
4. Notes
<a id="org38f6c2d"></a>
### WiFi Client
1. Peer Advertisement
2. Peer Discovery Once peers are discovered, a normal TCP connection can be made with the `HOST:PORT` value shared in the announcement packet.
3. Peer Connectivity #### Notes
4. Notes ### Wi-Fi Client
The \`wifi-client-request-network\` branch uses three different techniques for requesting a connection to a specific wifi network: #### Peer Advertisement
1. API >= 29 (tested on Samsung A21s and Nokia 1.3): The app uses WifiNetworkSpecifier, as recommended here. When the app requests the network, the system shows a progress indicator and searches for the network nearby. If the network isn't found, the system shows a dialog with options to try again or cancel. If the network is found, the system shows a dialog asking the user whether to connect or cancel. The app receives a callback with the user's response. The requested network does not appear in the device's list of saved networks. If the device is already connected to a wifi network with internet access, it disconnects and connects to the requested network instead. As expected, there is no warning about lack of internet access and the device stays connected to the network. The app can disconnect from the requested network by unregistering the NetworkCallback. After doing this, reconnecting to the requested network requires confirmation from the user again. The docs seem to suggest that if the app doesn't unregister the callback then the app can reconnect to the requested network in future without needing user approval again, but I haven't tested this yet. #### Peer Discovery
2. API < 29 (tested on Nexus 5X): The app creates a WifiConfiguration with a high priority value, adds the configuration via WifiManager#addNetwork(), and enables the configuration via WifiManager#enableNetwork(). This doesn't require user approval and connects to the requested network immediately, even if the device is currently connected to a network with internet access and the requested network doesn't have internet access. The requested network is added to the device's list of saved networks. There is no warning about lack of internet access and the device stays connected to the network. The app can disconnect from the requested network and remove the saved configuration by calling WifiManager#removeNetwork().
3. API < 29 (tested on Nexus 5X): As in the previous method, the app creates a WifiConfiguration with a high priority value and adds the configuration via WifiManager#addNetwork(). The app then uses reflection to call WifiManager#connect(). Like the previous method, this connects to the requested network immediately, even if the device is currently connected to a network with internet access and the requested network does not have internet access. The requested network is added to the device's list of saved networks. There is no warning about lack of internet access and the device stays connected to the network. The app can disconnect from the requested network and remove the saved configuration by calling WifiManager#removeNetwork().
#### Peer Connectivity
<a id="orga6da152"></a> #### Notes
### WiFi Direct - The `wifi-client-request-network` branch uses three different techniques for requesting a connection to a specific Wi-fi network:
1. Peer Advertisement 1. API >= 29 (tested on Samsung A21s and Nokia 1.3): The app uses `WifiNetworkSpecifier`, as recommended here. When the app requests the network, the system shows a progress indicator and searches for the network nearby. If the network isn't found, the system shows a dialog with options to try again or cancel. If the network is found, the system shows a dialog asking the user whether to connect or cancel. The app receives a callback with the user's response. The requested network does not appear in the device's list of saved networks. If the device is already connected to a Wi-fi network with internet access, it disconnects and connects to the requested network instead. As expected, there is no warning about lack of internet access and the device stays connected to the network. The app can disconnect from the requested network by unregistering the `NetworkCallback`. After doing this, reconnecting to the requested network requires confirmation from the user again. The docs seem to suggest that if the app doesn't unregister the callback then the app can reconnect to the requested network in future without needing user approval again, but I haven't tested this yet.
2. API < 29 (tested on Nexus 5X): The app creates a `WifiConfiguration` with a high priority value, adds the configuration via `WifiManager#addNetwork()`, and enables the configuration via `WifiManager#enableNetwork()`. This doesn't require user approval and connects to the requested network immediately, even if the device is currently connected to a network with internet access and the requested network doesn't have internet access. The requested network is added to the device's list of saved networks. There is no warning about lack of internet access and the device stays connected to the network. The app can disconnect from the requested network and remove the saved configuration by calling `WifiManager#removeNetwork()`.
3. API < 29 (tested on Nexus 5X): As in the previous method, the app creates a `WifiConfiguration` with a high priority value and adds the configuration via `WifiManager#addNetwork()`. The app then uses reflection to call `WifiManager#connect()`. Like the previous method, this connects to the requested network immediately, even if the device is currently connected to a network with internet access and the requested network does not have internet access. The requested network is added to the device's list of saved networks. There is no warning about lack of internet access and the device stays connected to the network. The app can disconnect from the requested network and remove the saved configuration by calling `WifiManager#removeNetwork()`.
2. Peer Discovery ### Wi-Fi Direct
3. Peer Connectivity #### Peer Advertisement
4. Notes #### Peer Discovery
#### Peer Connectivity
<a id="org7efd1ad"></a> #### Notes
## Alternative Transports ## Alternative Transports
1. OuiSync ### OuiSync
It is currently possible to route Briar one-on-one messages using a Ouisync repo by using the file export function. This idea could be further explored by building processes in Briar to more easily export large amounts of messages, or even automate the import and export of encrypted files. It is currently possible to route Briar one-on-one messages using a Ouisync repo by using the file export function. This idea could be further explored by building processes in Briar to more easily export large amounts of messages, or even automate the import and export of encrypted files.
2. P2P Connections over Intranets #### P2P Connections over Intranets
One existing question related to Ouisync and other alternative networking tools is how they perform in situations where there is a national-level intranet, and two peers both inside the intranet want to connect. If reliable ways to make p2p intranet connections are found, it could be an interesting transport layer for Briar or a similar app to implement. One existing question related to Ouisync and other alternative networking tools is how they perform in situations where there is a national-level intranet, and two peers both inside the intranet want to connect. If reliable ways to make p2p intranet connections are found, it could be an interesting transport layer for Briar or a similar app to implement.
3. LoRa / Ham Radio ### LoRa / Ham Radio
TODO TODO
4. Filesystem API ### Filesystem API
<a id="org12ba11d"></a>
## Future Considerations ## Future Considerations
<a id="org2e599ad"></a>
### Mix-and-Match Transport Layers ### Mix-and-Match Transport Layers
Out of the transport layers covered in this report, each transport layer has it's own trade-offs. By combining transport layers in interesting ways, we can create higher networking abstractions that could possibly offer better performance than each individual transport layer on it's own. One immediate example of this is using Bluetooth to advertise WiFi identifiers to bootstrap LSD connections. Doing large file transfers over LAN is much preferred to doing it over Bluetooth, so this approach could lead to better performance in situations where one peer is connected to a WiFi network that a nearby peer could also connect to. Out of the transport layers covered in this report, each transport layer has it's own trade-offs. By combining transport layers in interesting ways, we can create higher networking abstractions that could possibly offer better performance than each individual transport layer on it's own. One immediate example of this is using Bluetooth to advertise Wi-Fi identifiers to bootstrap LSD connections. Doing large file transfers over LAN is much preferred to doing it over Bluetooth, so this approach could lead to better performance in situations where one peer is connected to a Wi-Fi network that a nearby peer could also connect to.
<a id="org06644e6"></a>
### Evaluate Briar's Threat Model ### Evaluate Briar's Threat Model
<a id="orge2804d6"></a>
### Transport Energy Draw Experiments ### Transport Energy Draw Experiments
1. Outline
<a id="org8e12274"></a>
# Routing Protocols [WIP] # Routing Protocols [WIP]
<a id="orgd01fde7"></a>
## Existing Research ## Existing Research
<a id="orgd77c49e"></a>
# UI/UX Research [WIP] # UI/UX Research [WIP]
<a id="org63e0a5d"></a>
## Security Profiles ## Security Profiles
TODO insert tor screenshots TODO insert tor screenshots
<a id="orgcec3fe9"></a>
## Connectivity Profiles ## Connectivity Profiles
TODO insert figma designs TODO insert figma designs
<a id="org65e3ac0"></a>
# Appendix # Appendix
<a id="org3415686"></a>
## Similar Projects ## Similar Projects
<a id="org69796f3"></a>
### Community and mesh networks: ### Community and mesh networks:
<http://consume.net/> and <https://dek.spc.org/julian/consume/> - <http://consume.net/> and <https://dek.spc.org/julian/consume/>
<https://wirelessleiden.nl/en> and <https://wirelessleiden.nl/en/news/2022/02/wifi-network-will-be-phased-out> - <https://wirelessleiden.nl/en> and <https://wirelessleiden.nl/en/news/2022/02/wifi-network-will-be-phased-out>
<https://villagetelco.org/> and <https://villagetelco.org/mesh-potato/> - <https://villagetelco.org/> and <https://villagetelco.org/mesh-potato/>
<https://forum.xda-developers.com/t/piratebox-mobile-paw-intergrated.935157/> - <https://forum.xda-developers.com/t/piratebox-mobile-paw-intergrated.935157/>
<http://guifi.net/en> - <http://guifi.net/en>
<https://wiki.hacdc.org/index.php?title=Category:Byzantium> and <https://github.com/Byzantium/Byzantium/wiki> - <https://wiki.hacdc.org/index.php?title=Category:Byzantium> and <https://github.com/Byzantium/Byzantium/wiki>
<https://dn42.eu/Home> - <https://dn42.eu/Home>
<https://sudoroom.org/wiki/Mesh> - <https://sudoroom.org/wiki/Mesh>
<http://www.mazizone.eu/> - <http://www.mazizone.eu/>
<https://netcommons.eu/> - <https://netcommons.eu/>
<https://www.lantern.works/> - <https://www.lantern.works/>
<https://disaster.radio/> and <https://github.com/sudomesh/disaster-radio/wiki> - <https://disaster.radio/> and <https://github.com/sudomesh/disaster-radio/wiki>
<https://developer.synapse-wireless.com/getting-started/index.html> - <https://developer.synapse-wireless.com/getting-started/index.html>
<http://subnodes.org/> - <http://subnodes.org/>
<https://gitlab.epfl.ch/sacs/ssb/smallworld/gossiping-locally> - <https://gitlab.epfl.ch/sacs/ssb/smallworld/gossiping-locally>
<https://mallaveinal.net/> - <https://mallaveinal.net/>
<https://www.apc.org/en/blog/seeding-change-creating-digital-community-network-juhoan-people-namibia> - <https://www.apc.org/en/blog/seeding-change-creating-digital-community-network-juhoan-people-namibia>
<https://www.rhizomatica.org/> - <https://www.rhizomatica.org/>
<https://tylercipriani.com/blog/2022/07/31/meshtastic-a-review/> - <https://tylercipriani.com/blog/2022/07/31/meshtastic-a-review/>
<https://en.wikipedia.org/wiki/Optimized_Link_State_Routing_Protocol> - <https://en.wikipedia.org/wiki/Optimized_Link_State_Routing_Protocol>
<http://www.olsr.org/docs/README-Link-Quality.html> - <http://www.olsr.org/docs/README-Link-Quality.html>
<https://www.open-mesh.org/projects/open-mesh/wiki> - <https://www.open-mesh.org/projects/open-mesh/wiki>
<https://www.irif.fr/~jch//software/babel/> - <https://www.irif.fr/~jch//software/babel/>
<https://openmesh.wordpress.com/2011/01/30/a-list-of-open-source-ad-hoc-network-and-routing-protocolsplatforms/> - <https://openmesh.wordpress.com/2011/01/30/a-list-of-open-source-ad-hoc-network-and-routing-protocolsplatforms/>
<https://code.google.com/archive/p/adhoc-on-android/> - <https://code.google.com/archive/p/adhoc-on-android/>
<https://github.com/thinktube-kobe/airtube/wiki> - <https://github.com/thinktube-kobe/airtube/wiki>
<http://www.broadband-hamnet.org/> - <http://www.broadband-hamnet.org/>
<http://clusterduckprotocol.org/> - <http://clusterduckprotocol.org/>
<https://www.project-owl.com/> - <https://www.project-owl.com/>
<https://unsigned.io/reticulum-overview/> and <https://github.com/markqvist/Reticulum> and <https://markqvist.github.io/Reticulum/manual/> and <https://github.com/markqvist/Sideband> - <https://unsigned.io/reticulum-overview/> and <https://github.com/markqvist/Reticulum> and <https://markqvist.github.io/Reticulum/manual/> and <https://github.com/markqvist/Sideband>
<https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/esp-wifi-mesh.html> - <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/esp-wifi-mesh.html>
<https://unsigned.io/projects/rnode/> - <https://unsigned.io/projects/rnode/>
<https://rfc.zeromq.org/spec/36/> - <https://rfc.zeromq.org/spec/36/>
<https://blaubot.henning-gross.de/> - <https://blaubot.henning-gross.de/>
<https://qaul.net> and <https://qaul.github.io/qaul.net/#/qaul/README> - <https://qaul.net> and <https://qaul.github.io/qaul.net/#/qaul/README>
<a id="orgcb9e9e6"></a>
### Darknet and friend-to-friend projects: ### Darknet and friend-to-friend projects:
<https://sourceforge.net/projects/alliancep2p/> - <https://sourceforge.net/projects/alliancep2p/>
<https://code.google.com/archive/p/anonshare/> - <https://code.google.com/archive/p/anonshare/>
<https://code.google.com/archive/p/antagonist/> - <https://code.google.com/archive/p/antagonist/>
<https://cryptic6.sourceforge.net/> - <https://cryptic6.sourceforge.net/>
<https://easta.sourceforge.net/> - <https://easta.sourceforge.net/>
<https://galet.sourceforge.net/> - <https://galet.sourceforge.net/>
<https://hybrid-share.sourceforge.net/> - <https://hybrid-share.sourceforge.net/>
<https://learn.microsoft.com/en-us/openspecs/office_protocols/ms-grvprot/a4ff425f-5023-4053-ba03-d0870a06eca9> - <https://learn.microsoft.com/en-us/openspecs/office_protocols/ms-grvprot/a4ff425f-5023-4053-ba03-d0870a06eca9>
<https://www.powerfolder.com/> - <https://www.powerfolder.com/>
<http://retroshare.cc/index.html> - <http://retroshare.cc/index.html>
<https://waste.sourceforge.net/> and <http://wastekeyexchange.blogspot.com/> and <https://wasteagain.sourceforge.net/introduction.shtml> and <https://sourceforge.net/projects/swarmdarknet/> - <https://waste.sourceforge.net/> and <http://wastekeyexchange.blogspot.com/> and <https://wasteagain.sourceforge.net/introduction.shtml> and <https://sourceforge.net/projects/swarmdarknet/>
<https://www.ntop.org/products/n2n/> - <https://www.ntop.org/products/n2n/>
<https://gobby.github.io/> - <https://gobby.github.io/>
<http://sneer.me/> - <http://sneer.me/>
<https://teapotnet.org/> - <https://teapotnet.org/>
<a id="orge011c69"></a>
### Social P2P projects: ### Social P2P projects:
<https://www.gigatribe.com/en/> - <https://www.gigatribe.com/en/>
<http://kerjodando.blogspot.com/> - <http://kerjodando.blogspot.com/>
<https://www.tribler.org/> - <https://www.tribler.org/>
<http://incliq.com/> - <http://incliq.com/>
<https://github.com/mnaamani/otrtalk> - <https://github.com/mnaamani/otrtalk>
<https://secushare.org/> - <https://secushare.org/>
<https://getaether.net/> - <https://getaether.net/>
<https://github.com/coronanet> - <https://github.com/coronanet>
<https://cblgh.org/trustnet/> - <https://cblgh.org/trustnet/>
<https://cabal.chat/> - <https://cabal.chat/>
<https://radicle.xyz/> - <https://radicle.xyz/>
<https://openprivacy.ca/discreet-log/13-metadata-resistant-filesharing/> - <https://openprivacy.ca/discreet-log/13-metadata-resistant-filesharing/>
<https://github.com/jeremyckahn/chitchatter> - <https://github.com/jeremyckahn/chitchatter>
<https://github.com/sebkur/lanchat> - <https://github.com/sebkur/lanchat>
<a id="org58cb9af"></a>
### Sneakernets and DTN: ### Sneakernets and DTN:
<https://github.com/drewcrawford/sneakernet> - <https://github.com/drewcrawford/sneakernet>
<https://code.google.com/archive/p/sneakernet/> - <https://code.google.com/archive/p/sneakernet/>
<http://k0a1a.net/netless/> - <http://k0a1a.net/netless/>
<https://github.com/blanu/sneakermesh> - <https://github.com/blanu/sneakermesh>
<https://www.watershed.co.uk/studio/node/887/> and <https://github.com/Tim-Kindberg/crowdnet> - <https://www.watershed.co.uk/studio/node/887/> and <https://github.com/Tim-Kindberg/crowdnet>
<https://datatracker.ietf.org/doc/html/rfc4838> and <https://datatracker.ietf.org/doc/html/rfc5050> and <https://www.rfc-editor.org/rfc/rfc5325> and <https://datatracker.ietf.org/doc/html/rfc9171> and <https://datatracker.ietf.org/doc/html/rfc9172> - <https://datatracker.ietf.org/doc/html/rfc4838> and <https://datatracker.ietf.org/doc/html/rfc5050> and <https://www.rfc-editor.org/rfc/rfc5325> and <https://datatracker.ietf.org/doc/html/rfc9171> and <https://datatracker.ietf.org/doc/html/rfc9172>
<https://github.com/Mobisocial/dungbeetle> - <https://github.com/Mobisocial/dungbeetle>
<https://github.com/endymion/sneakernet> - <https://github.com/endymion/sneakernet>
<https://github.com/megamattron/SplinterNet> - <https://github.com/megamattron/SplinterNet>
<https://code.google.com/archive/p/twimight/> - <https://code.google.com/archive/p/twimight/>
<https://www.androidpolice.com/2014/10/31/googles-copresence-api/> - <https://www.androidpolice.com/2014/10/31/googles-copresence-api/>
<http://thaliproject.org/ExperimentWithFireChat/> - <http://thaliproject.org/ExperimentWithFireChat/>
<https://github.com/zeromq/zyre> - <https://github.com/zeromq/zyre>
<https://internet-in-a-box.org/> - <https://internet-in-a-box.org/>
<https://github.com/ole-old/BeLL-System-Documentation> - <https://github.com/ole-old/BeLL-System-Documentation>
<http://wiki.sugarlabs.org/go/Platform_Team/Sugar_Network/Architecture> - <http://wiki.sugarlabs.org/go/Platform_Team/Sugar_Network/Architecture>
<https://github.com/Muterra/doc-golix> - <https://github.com/Muterra/doc-golix>
<https://github.com/casific/murmur> - <https://github.com/casific/murmur>
<https://github.com/chrisballinger/BLEMeshChat> - <https://github.com/chrisballinger/BLEMeshChat>
<https://offlinefirst.org/> - <https://offlinefirst.org/>
<https://github.com/Nutomic/ensichat> - <https://github.com/Nutomic/ensichat>
<https://github.com/thaliproject> and <https://www.goland.org/thalimesh/> and <http://thaliproject.org/AndroidP2P/> - <https://github.com/thaliproject> and <https://www.goland.org/thalimesh/> and <http://thaliproject.org/AndroidP2P/>
<http://www.nncpgo.org/> and <https://changelog.complete.org/archives/10421-dead-usb-drives-are-fine-building-a-reliable-sneakernet> - <http://www.nncpgo.org/> and <https://changelog.complete.org/archives/10421-dead-usb-drives-are-fine-building-a-reliable-sneakernet>
<https://github.com/guardianproject/WindChime-Android> - <https://github.com/guardianproject/WindChime-Android>
<https://github.com/lulzlabs/AirChat> - <https://github.com/lulzlabs/AirChat>
<https://baydet.medium.com/dark-corners-of-multipeer-connectivity-framework-abd566422920> - <https://baydet.medium.com/dark-corners-of-multipeer-connectivity-framework-abd566422920>
<https://github.com/ssbc> and <https://handbook.scuttlebutt.nz/> and <https://ssbc.github.io/scuttlebutt-protocol-guide/> and <https://scuttlebot.io/> and <https://www.manyver.se/> - <https://github.com/ssbc> and <https://handbook.scuttlebutt.nz/> and <https://ssbc.github.io/scuttlebutt-protocol-guide/> and <https://scuttlebot.io/> and <https://www.manyver.se/>
<https://getaura.io/> - <https://getaura.io/>
<https://github.com/bantucracy/ayanda> - <https://github.com/bantucracy/ayanda>
<https://docs.ditto.live/> - <https://docs.ditto.live/>
<https://bridgefy.me/> and <https://bridgefy.me/docs/javadoc/> and <https://github.com/bridgefy/bridgefy-android-sdk-sample> and <https://eikendev.github.io/breaking-bridgefy-again/> - <https://bridgefy.me/> and <https://bridgefy.me/docs/javadoc/> and <https://github.com/bridgefy/bridgefy-android-sdk-sample> and <https://eikendev.github.io/breaking-bridgefy-again/>
<https://awala.network/> - <https://awala.network/>
<https://github.com/Hariharan-Gandhi/WiFriends> - <https://github.com/Hariharan-Gandhi/WiFriends>
<https://www.usenix.org/legacy/events/hotsec10/tech/techAbstracts.html#Aviv> and <https://www.cs.swarthmore.edu/~aviv/papers/aviv-priv_humanets.pdf> - <https://www.usenix.org/legacy/events/hotsec10/tech/techAbstracts.html#Aviv> and <https://www.cs.swarthmore.edu/~aviv/papers/aviv-priv_humanets.pdf>
<https://dtn7.github.io/> and <https://github.com/RightMesh/Terra/> and <https://github.com/NodleCode/dtn7-kotlin/> - <https://dtn7.github.io/> and <https://github.com/RightMesh/Terra/> and <https://github.com/NodleCode/dtn7-kotlin/>
<https://www.netlab.tkk.fi/~jo/papers/2014-04-wons-liberouter.pdf> and <http://liberouter.mobi/> and <https://blog.apnic.net/2018/12/18/librerouter-powering-community-networks-with-free-and-open-hardware/> and <https://research.aalto.fi/en/publications/opportunistic-networking-applications-from-theory-to-practice> - <https://www.netlab.tkk.fi/~jo/papers/2014-04-wons-liberouter.pdf> and <http://liberouter.mobi/> and <https://blog.apnic.net/2018/12/18/librerouter-powering-community-networks-with-free-and-open-hardware/> and <https://research.aalto.fi/en/publications/opportunistic-networking-applications-from-theory-to-practice>
<http://www.servalproject.org/> - <http://www.servalproject.org/>