Add: Apple/Google BLE Exposure Notification Service (v1.2)

Author: micolous

scapy/contrib/exposure_notification.py

@@ -0,0 +1,68 @@
+# -*- mode: python3; indent-tabs-mode: nil; tab-width: 4 -*-
+# exposure_notification.py - Apple/Google Exposure Notification System
+#
+# This file is part of Scapy
+# See http://www.secdev.org/projects/scapy for more information
+# Copyright (C) 2020 Michael Farrell <[email protected]>
+# This program is published under a GPLv2 (or later) license
+#
+# scapy.contrib.description = Apple/Google Exposure Notification System (ENS)
+# scapy.contrib.status = loads
+"""
+Apple/Google Exposure Notification System (ENS), formerly known as
+Privacy-Preserving Contact Tracing Project.
+
+This module parses the Bluetooth Low Energy beacon payloads used by the system.
+This does **not** yet implement any cryptographic functionality.
+
+More info:
+
+* `Apple: Privacy-Preserving Contact Tracing`__
+* `Google: Exposure Notifications`__
+* `Wikipedia: Exposure Notification`__
+
+__ https://www.apple.com/covid19/contacttracing/
+__ https://www.google.com/covid19/exposurenotifications/
+__ https://en.wikipedia.org/wiki/Exposure_Notification
+
+Bluetooth protocol specifications:
+
+* `v1.1`_ (April 2020)
+* `v1.2`_ (April 2020)
+
+.. _v1.1: https://blog.google/documents/58/Contact_Tracing_-_Bluetooth_Specification_v1.1_RYGZbKW.pdf
+.. _v1.2: https://covid19-static.cdn-apple.com/applications/covid19/current/static/contact-tracing/pdf/ExposureNotification-BluetoothSpecificationv1.2.pdf
+"""  # noqa: E501
+
+from scapy.fields import StrFixedLenField
+from scapy.layers.bluetooth import EIR_Hdr, EIR_ServiceData16BitUUID, \
+    EIR_CompleteList16BitServiceUUIDs, LowEnergyBeaconHelper
+from scapy.packet import bind_layers, Packet
+
+
+EXPOSURE_NOTIFICATION_UUID = 0xFD6F
+
+
+class Exposure_Notification_Frame(Packet, LowEnergyBeaconHelper):
+    """Apple/Google BLE Exposure Notification broadcast frame."""
+    name = "Exposure Notification broadcast"
+
+    fields_desc = [
+        # Rolling Proximity Identifier
+        StrFixedLenField("identifier", None, 16),
+        # Associated Encrypted Metadata (added in v1.2)
+        StrFixedLenField("metadata", None, 4),
+    ]
+
+    def build_eir(self):
+        """Builds a list of EIR messages to wrap this frame."""
+
+        return LowEnergyBeaconHelper.base_eir + [
+            EIR_Hdr() / EIR_CompleteList16BitServiceUUIDs(svc_uuids=[
+                EXPOSURE_NOTIFICATION_UUID]),
+            EIR_Hdr() / EIR_ServiceData16BitUUID() / self
+        ]
+
+
+bind_layers(EIR_ServiceData16BitUUID, Exposure_Notification_Frame,
+            svc_uuid=EXPOSURE_NOTIFICATION_UUID)

test/contrib/exposure_notification.uts

@@ -0,0 +1,59 @@
+% Exposure Notification System tests
+#
+# Type the following command to launch start the tests:
+# $ test/run_tests -P "load_contrib('exposure_notification')" -t test/contrib/exposure_notification.uts
+
++ ENS tests
+
+= Setup
+
+def next_eir(p):
+   return EIR_Hdr(p[Padding].load)
+
+= Presence check
+
+Exposure_Notification_Frame
+
+= Raw payload copied from BluetoothExplorer.app
+
+d = hex_bytes('17df1d67405e3395470e62ca4fda6a9303687b31')
+p = Exposure_Notification_Frame(d)
+
+assert p.identifier == hex_bytes('17df1d67405e3395470e62ca4fda6a93')
+assert p.metadata == hex_bytes('03687b31')
+
+= Raw captured payload
+
+d = hex_bytes('02011a03036ffd17166ffde23f352fa09307a85d4194912443180d484dc151')
+p = EIR_Hdr(d)
+
+# First is a flags header
+assert EIR_Flags in p
+
+# Then the 16-bit Service Class ID
+p = next_eir(p)
+assert p[EIR_CompleteList16BitServiceUUIDs].svc_uuids == [
+    EXPOSURE_NOTIFICATION_UUID]
+
+# Then the ENS
+p = next_eir(p)
+assert p[EIR_ServiceData16BitUUID].svc_uuid == EXPOSURE_NOTIFICATION_UUID
+assert p[Exposure_Notification_Frame].identifier == hex_bytes(
+    'e23f352fa09307a85d4194912443180d')
+assert p[Exposure_Notification_Frame].metadata == hex_bytes('484dc151')
+
+# Rebuild the payload.
+p2 = p[Exposure_Notification_Frame].build_eir()
+
+# Our captured payload was from a mobile phone, but build_eir presumes that
+# we're broadcasting as an non-connectable, LE-only beacon. We need to adjust
+# these flags to match the captured packet.
+p2[0] = EIR_Hdr() / EIR_Flags(flags=[
+    'general_disc_mode', 'simul_le_br_edr_ctrl', 'simul_le_br_edr_host'])
+
+# Ensure we didn't mutate LowEnergyBeaconHelper.base_eir just then.
+assert LowEnergyBeaconHelper.base_eir[0][EIR_Flags].flags == [
+    'general_disc_mode', 'br_edr_not_supported']
+
+# Assemble all packet bytes
+assert b''.join(map(raw, p2)) == d