Codes and Data for the Exposure Notification on the Raspberry Pi. Exposure Notification Service, previously called Contact Tracing, is the name used by Apple and Google in their documents. The code here implements the Apple-Google Protocol on Raspberry Pis which run Debian-based systems.
-
Fully implemented the Apple-Google Protocol on Privacy-Preserving Contact Tracing on the Raspberry Pi based system.
-
Each device can do both advertising (broadcasting) and scanning (observing), and can record other devices using the same Exposure Notification Service. It is compatible with other types of devices such as iPhones and Android phones.
-
Each device uses random and non-resolvable MAC addresses, random IDs (called Rolling Proximity Identifiers) and encrypted data that change every 15 minutes to protect privacy.
-
Each device records all data locally and auto-deletes any data more than 14 days old.
-
-
Available in two versions:
-
The Version with Encryption - A complete version that implements Apple-Google Protocol with all advertising data encrypted.
-
The Version without Encryption - A version that does not apply encryption. The MAC address is not random, the RPI and metadata are unencrypted. This version can be used for research purposes and data collection.
-
-
The prototype has the capability to handle occasional hardware glitches. No hardware is perfect. The code detects when the Bluetooth module stops working and resets the module immediately.
The developed code has been tested on different models of Raspberry Pi: Raspberry Pi Zero W, Raspberry Pi 3, and Raspberry Pi 4.
The code can be used in all the Raspberry Pi models that have a Bluetooth module. The smallest and least expensive one is Raspberry Pi Zero W.
We recommend using the latest Raspbian System for a Raspberry Pi. The OS comes with Python 3 and Git already installed.
First, Python 3 and bash commands are used to execute the code. The following libraries are required in Python 3. The bluepy library is used for Bluetooth scanning, while pyaes is used for the cryptography part. To install these libraries, run the following commands:
$ sudo pip3 install bluepy
$ sudo pip3 install pyaes
Next, make sure the bash scripts (.sh) are executable. If not, use the following commands:
$ chmod +x ContactTracing_BLE.sh
$ chmod +x ContactTracing_BLE_Enpt.sh
If you are using the version with encryption, you need to set up Encrypt_RPI_AEM.py to be executed automatically and periodically. To do so, use crontab -e to open the crontab file and add the following line to the crontab file.
*/15 * * * * cd YOUR_PATH/Exposure-Notification-on-RPi/ && python3 Encrypt_RPI_AEM.py
This line ensures that the system will execute Encrypt_RPI_AEM.py file every 15 minutes, so that the random MAC address, Rolling Proximity Identifier (RPI) and (Associated Encrypted Metadata) AEM changes every 15 minutes. Remember to change YOUT_PATH.
You can wait after the system executes Encrypt_RPI_AEM.py once, or you can manually execute Encrypt_RPI_AEM.py to generate the TEK. Once the TEK is generated, you can run the code by typing
$ ./ContactTracing_BLE_Enpy.sh
The result is stored in a CTData_XXXX.csv file in the Data folder.
If you do not need the version with encryption, there is no need to set up Encrypt_RPI_AEM.py. Instead, it is recommended that you change the RPI in the STATIC_RPI.conf. Otherwise, you will see multiple devices that have the same RPI. To execute the code, run
$ ./ContactTracing_BLE.sh
The result is stored in a CTData_XXXX.csv file in the Data folder.
The code records the information of other BLE devices that use the same service (the Exposure Notification Service). The output is in a CTData_XXXXt.csv file. An example of the csv file is given below.
The first column is the Unix Time and its unit is seconds. The second column is the MAC addresses of other BLE devices seen. This could be a random non-resolvable MAC address or a public MAC address, depending on the protocol the other device uses. The third column is the RSSI (dBm). The fourth column is the Service UUID, and it is 0xFD6F for the Exposure Notification Service. The fifth column is the RPI of the other device, and the last column is the metadata. The detailed information about Service UUID, RPI, and metadata can be found here.
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
Chang Li (ANTD/ITL/NIST): Implemented the Bluetooth communication part based on Apple-Google Bluetooth Specification (Version 1.2). Built-up the system and tested it.
Lu Shi (ANTD/ITL/NIST): Implemented the cryptography part based on Apple-Google Cryptography Specification (Version 1.2). Wrote the Python file cryptolib.py.
This works implements Apple-Google Protocol on Privacy-Preserving Contact Tracing. Detailed information can be found on their website and in their documents.
See LICENSE.md
Please contact Chang Li (chang.li@nist.gov), Lu Shi (lu.shi@nist.gov), or Nader Moayeri (nader.moayeri@nist.gov) if you have any questions. Thank you.