https://github.com/seemoo-lab/openhaystack Skip to content Sign up * Why GitHub? Features - + Mobile - + Actions - + Codespaces - + Packages - + Security - + Code review - + Project management - + Integrations - + GitHub Sponsors - + Customer stories- * Team * Enterprise * Explore + Explore GitHub - Learn and contribute + Topics - + Collections - + Trending - + Learning Lab - + Open source guides - Connect with others + The ReadME Project - + Events - + Community forum - + GitHub Education - + GitHub Stars program - * Marketplace * Pricing Plans - + Compare plans - + Contact Sales - + Nonprofit - + Education - [ ] [search-key] * # In this repository All GitHub | Jump to | * No suggested jump to results * # In this repository All GitHub | Jump to | * # In this organization All GitHub | Jump to | * # In this repository All GitHub | Jump to | Sign in Sign up {{ message }} seemoo-lab / openhaystack * Notifications * Star 197 * Fork 14 Build your own 'AirTags' today! Framework for tracking personal Bluetooth devices via Apple's massive Find My network. owlink.org AGPL-3.0 License 197 stars 14 forks Star Notifications * Code * Issues 0 * Pull requests 0 * Actions * Projects 0 * Security * Insights More * Code * Issues * Pull requests * Actions * Projects * Security * Insights main Switch branches/tags [ ] Branches Tags Nothing to show {{ refName }} default View all branches Nothing to show {{ refName }} default View all tags 1 branch 1 tag Go to file Code Clone HTTPS GitHub CLI [https://github.com/s] Use Git or checkout with SVN using the web URL. [gh repo clone seemoo] Work fast with our official CLI. Learn more. * Open with GitHub Desktop * Download ZIP Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching GitHub Desktop If nothing happens, download GitHub Desktop and try again. Go back Launching Xcode If nothing happens, download Xcode and try again. Go back Launching Visual Studio If nothing happens, download the GitHub extension for Visual Studio and try again. Go back Latest commit @schmittner schmittner Add generic HCI script (fixes #3) ... a4ca840 Mar 4, 2021 Add generic HCI script (fixes #3) a4ca840 Git stats * 12 commits Files Permalink Failed to load latest commit information. Type Name Latest commit message Commit time .github/workflows Fix build pipeline Mar 4, 2021 CVE-2020-9986/OFReadKeys Clean up after move of OFFetchReports Mar 4, 2021 Firmware Initial commit Mar 3, 2021 OpenHaystack Clean up after move of OFFetchReports Mar 4, 2021 Resources Add CVE-2020-9986 Mar 4, 2021 .gitignore Initial commit Mar 3, 2021 .gitmodules Initial commit Mar 3, 2021 HCI.py Add generic HCI script (fixes #3) Mar 4, 2021 LICENSE Initial commit Mar 3, 2021 README.Reproducibility.md Clean up after move of OFFetchReports Mar 4, 2021 README.md Add generic HCI script (fixes #3) Mar 4, 2021 View code README.md OpenHaystack application icon 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. Screenshot of the app 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 + Loosing + Finding + Searching * How to track other Bluetooth devices? * Authors * References * License What is OpenHaystack? OpenHaystack is an application that allows you to create your own tags 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 micro:bit tag anywhere on earth without cellular coverage. Nearby iPhones will discover your tag 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. Disclaimer OpenHaystack is experimental software. The code is untested and incomplete. For example, OpenHaystack tags 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 entitlements required to use this API). Therefore, the installation procedure is slightly different and requires you to temporarily disable Gatekeeper. Our plugin does not access any other private data such as emails (see source code). 1. Download a precompiled binary release from our GitHub page. Alternative: build the application from source via Xcode. 2. Open OpenHaystack. This will ask you to install the Mail plugin in ~/Library/Mail/Bundle. 3. Open a terminal and run sudo spctl --master-disable, which will disable Gatekeeper and allow our Apple Mail plugin to run. 4. Open Apple Mail. Go to Preferences - General - Manage Plug-Ins... and activate the checkbox next to OpenHaystackMail.mailbundle. 5. Allow access and restart Mail. 6. Open a terminal and enter sudo spctl --master-enable, which will enable Gatekeeper again. Usage Adding a new tag. To create a new tag, you just need to enter a name for it and optionally select a suitable icon and a color. The app then generates a new key pair that is used to encrypt and decrypt the location reports. The private key is stored in your Mac's keychain. Upon deploying, the app will try to flash our firmware image with the new public key to a USB-connected BBC micro:bit v1. However, you may also copy the public key used for advertising and deploy it via some other mechanism. Display devices' locations. It can take up to 30 minutes until you will see the first location report on the map on the right side. The map will always show all your items' most recent locations. You can click on every item to check when the last update was received. By clicking the reload button, you can update the location reports. How does Apple's Find My network work? We briefly explain Apple's offline finding system (aka Find My network). Please refer to our PETS paper and Apple's accessory specification for more details. We provide a schematic overview (from our paper) and explain how we integrate the different steps in OpenHaystack below. Find My Overview Pairing (1) To use Apple's Find My network, we generate a public-private key pair on an elliptic curve (P-224). The private key remains on the Mac securely stored in the keychain, and the public key will be deployed on the tag, e.g., an attached micro:bit. Loosing (2) In short, the tags broadcast the public key as Bluetooth Low Energy (BLE) advertisements (see firmware. Nearby iPhones will not be able to distinguish our tags from a genuine Apple device or certified accessory. Finding (3) When a nearby iPhone receives a BLE advertisement, the iPhone fetches its current location via GPS, encrypts it using public key from the advertisement, and uploads the encrypted report to Apple's server. All iPhones on iOS 13 or newer do this by default. OpenHaystack is not involved in this step. Searching (4) Apple does not know which encrypted locations belong to which Apple account or device. Therefore, every Apple user can download any location report as long as they know the corresponding public key. This is not a security issue: all reports are end-to-end encrypted and cannot be decrypted unless one knows the corresponding private key (stored in the keychain). We leverage this feature to download the reports from Apple that have been created for our OpenHaystack tags. We use our private keys to decrypt the location reports and show the most recent one on the map. Apple protects their database against arbitrary access by requiring an authenticated Apple user to download location reports. We use our Apple Mail plugin, which runs with elevated privileges, to access the required authentication information. The OpenHaystack app communicates with the plugin while downloading reports. This is why you need to keep Mail open while using OpenHaystack. How to track other Bluetooth devices? Currently, we only provide a convenient deployment method of our OpenHaystack firmware for the BBC micro:bit. However, you should be able to implement the advertisements on other devices that support Bluetooth Low Energy based on the source code of our firmware and the specification in our paper. In addition, you can easily turn any Linux machine (including Raspberry Pi) into a tag that can be tracked via the Find My network. Our Python script uses HCI calls to configure Bluetooth advertising. You can copy the required ADVERTISMENT_KEY from the app by right-clicking on your accessory. Then run the script: sudo python3 HCI.py --key Setup Authors * Alexander Heinrich (@Sn0wfreezeDev, email) * Milan Stute (@schmittner, email, web) References * Alexander Heinrich, Milan Stute, Tim Kornhuber, Matthias Hollick. Who Can Find My Devices? Security and Privacy of Apple's Crowd-Sourced Bluetooth Location Tracking System. Proceedings on Privacy Enhancing Technologies (PoPETs), 2021. Preprint. * Tim Kornhuber. Analysis of Apple's Crowd-Sourced Location Tracking System. Technical University of Darmstadt, Master's thesis, 2020. * Apple Inc. Find My Network Accessory Specification - Developer Preview - Release R3. 2020. Download. License OpenHaystack is licensed under the GNU Affero General Public License v3.0. About Build your own 'AirTags' today! Framework for tracking personal Bluetooth devices via Apple's massive Find My network. owlink.org Topics macos apple reverse-engineering bluetooth microbit location-tracker find-my offline-finding airtag Resources Readme License AGPL-3.0 License Releases 1 Release v0.3.0 Latest Mar 3, 2021 Contributors 2 * @schmittner schmittner Milan Stute * @Sn0wfreezeDev Sn0wfreezeDev Alexander Heinrich Languages * Swift 69.7% * Objective-C 27.3% * Python 1.3% * Other 1.7% * (c) 2021 GitHub, Inc. * Terms * Privacy * Security * Status * Docs * Contact GitHub * Pricing * API * Training * Blog * About You can't perform that action at this time. You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.