seemoo-lab / openhaystack

# OpenHaystack
OpenHaystack is a framework for tracking personal Bluetooth devices via Apple's massive Find My network. Use it to create your own tracking _tags_ that you can append to physical objects (keyrings, backpacks, ...) or integrate it into other Bluetooth-capable devices such as notebooks.
## Table of contents
- What is _OpenHaystack_?
 - History
 - Disclaimer
- How to use _OpenHaystack_?
 - System requirements
 - Installation
 - Usage
- How does Apple's Find My network work?
 - Pairing
 - Losing
 - Finding
 - Searching
- How to track other Bluetooth devices?
- OpenHaystack Mobile
- Authors
- References
- License
## What is _OpenHaystack_?
OpenHaystack is an application that allows you to create your own accessories that are tracked by Apple's Find My network. All you need is a Mac and a BBC micro:bit or any other Bluetooth-capable device.
By using the app, you can track your accessories anywhere on earth without cellular coverage. Nearby iPhones will discover your accessories and upload their location to Apple's servers when they have a network connection.
### History
OpenHaystack is the result of reverse-engineering and security analysis work of Apple's _Find My network_ (or _offline finding_). We at the Secure Mobile Networking Lab of TU Darmstadt started analyzing offline finding after its initial announcement in June 2019. We identified how Apple devices can be found by iPhones devices, even when they are offline through this work. The whole system is a clever combination of Bluetooth advertisements, public-key cryptography, and a central database of encrypted location reports. We disclosed a specification of the closed parts of offline finding and conducted a comprehensive security and privacy analysis.
We found two distinct vulnerabilities. The most severe one, which allowed a malicious application to access location data, has meanwhile been fixed by Apple (CVE-2020-9986).
For more information about the security analysis, please read our paper.
Since its release, we received quite a bit of press and media coverage.
### Disclaimer
OpenHaystack is experimental software. The code is untested and incomplete. For example, OpenHaystack accessories using our firmware broadcast a fixed public key and, therefore, are trackable by other devices in proximity (this might change in a future release). OpenHaystack is not affiliated with or endorsed by Apple Inc.
## How to use _OpenHaystack_?
OpenHaystack consists of two components. First, we provide a macOS application that can display the last reported location of your personal Bluetooth devices. Second, the firmware image enables Bluetooth devices to broadcast beacons that make them discoverable by iPhones.
### System requirements
OpenHaystack requires macOS 11 (Big Sur).
### Installation
The OpenHaystack application requires a custom plugin for Apple Mail. It is used to download location reports from Apple's servers via a private API (technical explanation: the plugin inherits Apple Mail's