Build your own 'AirTags' 🏷 today! Framework for tracking personal Bluetooth devices via Apple's massive Find My network.

Last update: Aug 5, 2022

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?

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 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.
    • If the Manage Plug-Ins... button does not appear. Run this command in terminal sudo defaults write "/Library/Preferences/com.apple.mail" EnableBundles 1
  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 accessory. To create a new accessory, 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.

Deploy to device. Connect a supported device via USB to your Mac and hit the Deploy button next to the accessory's name and choose the corresponding. Instead of using OpenHaystack's integrated deployment, you may also copy the public key used for advertising (right click on accessory) and deploy it manually.

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 is deployed on the accessory, e.g., an attached micro:bit.

Losing (2)

In short, the accessories broadcast the public key as Bluetooth Low Energy (BLE) advertisements (see firmware). Nearby iPhones will not be able to distinguish our accessories 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 accessories. 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?

In principle, any Bluetooth device can be turned into an OpenHaystack accessory that is trackable via Apple's Find My network. Currently, we provide a convenient deployment method of our OpenHaystack firmwares for a small number of embedded devices (see table below). We also support Linux devices via our generic HCI script. Feel free to port OpenHaystack to other devices that support Bluetooth Low Energy based on the source code of our firmware and the specification in our paper. Please share your results with us!

Platform Tested on Deploy via app Comment
Nordic nRF51 BBC micro:bit v1 βœ“ Only supports nRF51288 at this time (see issue #6).
Espressif ESP32 SP32-WROOM, ESP32-WROVER βœ“ Deployment can take up to 3 minutes. Requires Python 3. Thanks @fhessel.
Linux HCI Raspberry Pi 4 w/ Raspbian Should support any Linux machine.

Setup

Authors

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. doi:10.2478/popets-2021-0045 πŸ“„ Paper πŸ“„ Preprint.
  • Alexander Heinrich, Milan Stute, and Matthias Hollick. DEMO: OpenHaystack: A Framework for Tracking Personal Bluetooth Devices via Apple’s Massive Find My Network. 14th ACM Conference on Security and Privacy in Wireless and Mobile (WiSec ’21), 2021.
  • 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.

GitHub

https://github.com/seemoo-lab/openhaystack
Comments
  • 1. Support for MacOS Mail 16.0

    Describe the bug The OpenHaystack MacOS Mail plugin is not compatible with Mail 16.0, which ships with macOS 12.3

    OpenHaystack version: Version 0.5.1 (1)

    macOS version: 12.3

    Reviewed by klinquist at 2022-03-15 17:40
  • 2. Device switches from green to yellow and back when turned on/off, but there are no location reports

    Hi all,

    my device does seem to be doing something, as it becomes yellow when I turn it off and goes back to green when I turn it back on, but there is no location report. I am completely fine with debugging this, I just need some pointers where to start :)

    Best, Linus

    Reviewed by glatteis at 2022-05-09 10:37
  • 3. Problem with ESP32 (ESPRESSIF)

    When i want to deploy an Airtag i get this error: Deploying to microbit failed. Please reconnect the device over USB

    (To be honest, I don't know what to add here, since I have little affection for the mateire)

    OpenHaystack version: Version 0.3.7

    macOS version: 11.4 (20F71)

    Bildschirmfoto 2021-06-07 um 18 59 52

    2021-06-07 19 04 14

    Reviewed by KatzeMau at 2021-06-07 17:08
  • 4. error when flashing esp32

    ESP32 % ./flash_esp32.sh -p /dev/cu.usbserial-0001 "yaAusUDjMLRkXaRqZ0TLTvWeM9cbW3fdCtxnQD/xySI=" esptool.py v3.0 Found 2 serial ports Serial port /dev/cu.usbserial-0001 Connecting........_ Detecting chip type... ESP32 Chip is ESP32-D0WDQ6 (revision 1) Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None Crystal is 40MHz MAC: ac:67:b2:36:9c:ac Uploading stub... Running stub... Stub running... Erasing region (may be slow depending on size)... Erase completed successfully in 0.1 seconds. Staying in bootloader. esptool.py v3.0 Found 2 serial ports Serial port /dev/cu.usbserial-0001 Connecting.......................___...............__ /dev/cu.usbserial-0001 failed to connect: Failed to connect to Espressif device: Timed out waiting for packet header Serial port /dev/cu.Bluetooth-Incoming-Port Connecting.......................___...............__ /dev/cu.Bluetooth-Incoming-Port failed to connect: Failed to connect to Espressif device: Timed out waiting for packet header

    A fatal error occurred: Could not connect to an Espressif device on any of the 2 available serial ports. cleanup ...

    This is the error I get and idk what to do any advice would be appreciated

    Reviewed by jaekim24 at 2021-04-30 20:28
  • 5. Deploy firmware on ESP32 fails

    I would like to ask for help, If I run ./flash_esp32.sh -p /dev/cu.usbserial-0001 "my public key in base64", I got:

    esptool.py v3.0
    Found 4 serial ports
    Serial port /dev/cu.usbserial-0001
    Connecting........__
    Detecting chip type... ESP32
    Chip is ESP32-D0WDQ6 (revision 1)
    Features: WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
    Crystal is 40MHz
    MAC: XXXXXXXXX
    Uploading stub...
    Running stub...
    Stub running...
    Erasing region (may be slow depending on size)...
    Erase completed successfully in 0.1 seconds.
    Staying in bootloader.
    esptool.py v3.0
    Found 4 serial ports
    Serial port /dev/cu.usbserial-0001
    Connecting........_____....._____....._____....._____....._____....._____....._____
    /dev/cu.usbserial-0001 failed to connect: Failed to connect to Espressif device: Timed out waiting for packet header```
    
    As I understand "erasing" of the device works fine, but then "writing" fails. Am I missing something?
    Reviewed by mowtschan at 2021-04-14 13:27
  • 6. Unable to get key into "OFFLINEFINDINGPUBLICKEYHERE!" for nRF51822 firmware

    Hey thank you for this great project! i have an issue with making the firmware for nRF51822, i don't know how to enter the public key in to the firmware. /* don't makeconstso we can replace key in compiled binary image */ static char public_key[28] = "OFFLINEFINDINGPUBLICKEYHERE!"; I tried to paste the advertisement key (Base64) from the open haystack app there, this doesn't work the make commands gives this error error: initializer-string for array of 'char' is too long [-Werror] What's the right way to get the advertisement key from the app into the main.c file for the nRF51822. Thank you for answering the question!

    Reviewed by Z-pi at 2021-03-09 23:20
  • 7. The reported location is not accurate

    Describe the bug I try on Raspberry pi and ESP 32. Both of them have reported the wrong location comparing with the location in Find my app from my iPhone.

    Expected behavior Showing the same location as shown in Find my app

    Screenshots If applicable, add screenshots to help explain your problem.

    OpenHaystack version: Version 0.3.7 (1)

    macOS version: Big Sur

    Additional context Add any other context about the problem here.

    Reviewed by iamfaith at 2021-07-06 01:34
  • 8. Power consumption during trakking

    How many Power need the BBC when trakking ?

    3V Battery Pack take how many Time ? And how often take the BBC send the Signal out ? Instantly or 30 min or 1 hour or ever when other IOS Device "Ping" it takes a "Pong" ?!

    Big Thanks for the Project and Help.

    Reviewed by PrinzEric at 2021-03-10 09:06
  • 9. Incompatible Plug-ins Disabled after laters OSx Monterey update 12.1 (21C52)

    Hi,

    OpenHaystack is not working after latest update of OS Monterey 12.1 (21C52)

    Incompatible Plug-ins Disabled
    Mail 
    Mail has disabled the following plug-ins:
    OpenHaystackMail.mailbundle
    Contact the makers of these plug-ins for versions that are compatible with Mail 15.0.
    

    Everything used to work fine before this latest update.

    I've tried to uninstall the plugin, restart my Mac and follow these steps again:

    • Download a precompiled binary release from our GitHub page.
    • Alternative: build the application from source via Xcode.
    • Open OpenHaystack. This will ask you to install the Mail plugin in ~/Library/Mail/Bundle.
    • Open a terminal and run sudo spctl --master-disable, which will disable Gatekeeper and allow our Apple Mail plugin to run.
    • Open Apple Mail. Go to Preferences β†’ General β†’ Manage Plug-Ins... and activate the checkbox next to OpenHaystackMail.mailbundle.
    • If the Manage Plug-Ins... button does not appear. Run this command in terminal sudo defaults write "/Library/Preference/com.apple.mail" EnableBundles 1
    • Allow access and restart Mail.
    • Open a terminal and enter sudo spctl --master-enable, which will enable Gatekeeper again.

    But still not working.

    Screenshots

    Screenshot 2021-12-18 at 15 25 40 Screenshot 2021-12-18 at 13 04 01

    OpenHaystack version: Version 0.4.1 (1)

    macOS version: 12.1 (21C52)

    Additional context Plugin used to work perfectly before update.

    Thanks

    Reviewed by Furtivo360 at 2021-12-18 15:34
  • 10. Flash common Aliexpress nRF51822

    Hi, i was wondering what i need to flash pre built nRF51822 chips that can be found on alixpress. I have a few of these laying around home for a little project and it would be awsome to use them as trackers.

    Item: https://it.aliexpress.com/item/32885909449.html

    Does anyone know what tool i need and how to mount them as volumes so i can copy the file like the microbit tutorial?

    Reviewed by francescofact at 2021-03-07 09:29
  • 11. Tracking airtag

    Reviewing other comments and question I have realized that openhaystack cannot be used to track existing airtags. If may ask a general question - any thoughts on how to track locations of existing airtags using any other way? Thanks in advance.

    Reviewed by satishkn at 2022-03-31 14:20
  • 12. Does the AirTag use a different BLE advertisement format than the one presented in Table 2?

    If i am not mistaken, Table 2 in the paper was for iPhones and macs using the find my network, does the AirTag also use the same format with 28 byte long public keys? What if any are the differences between iPhones and AirTags in BLE packets?

    Reviewed by Nxtv2 at 2022-08-06 13:00
  • 13. How to modify OHServerApp Address and Port?

    I've been able to build and run the OHServerApp from https://github.com/Sn0wfreezeDev/openhaystack (simple_server branch). How can I modify the IP address and Port of the OHServerApp running on my Mac, so I will be to access it from inside my network with the mobile version? I've understood that I need to modify some Vapor settings somehow, but I'm not able to. I am not familiar with XCode or Swift in general. Thanks.

    Reviewed by mattiasandri at 2022-08-02 14:36
  • 14. OHServerApp

    Hi everybody, i have compiled the OHServerApp with 0.0.0.0 and Port 8099 in Vapor HTTPServer. App runs, but whatever i do, the Server always shows {"error":true,"reason":"Not Found"}. Is it possible, that Someone is making the App with 0.0.0.0 IP for me?

    I don't know, what the Problem is, do I have to pay attention to anything when creating the project with xcode? Is it possible to run Openhaystack and OHServer Side by Side, or should the server run alone to avoid any Problems?

    Thank You

    Reviewed by Systm21 at 2022-07-22 17:04
  • 15. ESP32 C3 Not booting

    Describe the bug When I succesfully flash an ESP32 -c3-mini-1 or the ESP32-C3-DevKitC-02 both fail to boot:

    rst:0x10 (RTCWDT_RTC_RST),boot:0xc (SPI_FAST_FLASH_BOOT)
    SPIWP:0xee
    mode:DIO, clock div:1
    load:0x3fcd6100,len:0x17a8
    load:0x73252029,len:0x2323203a
    Invalid image block, can't boot.
    ets_main.c 333
    SP-ROM:esp32c3-api1-20210207
    Build:Feb  7 2021
    

    To Reproduce Steps to reproduce the behavior:

    1. Install IDF using ./install.sh esp32c3
    2. Build the bootloader with idf.py build
    3. Flash the ESP32: ./flash_esp32.sh -p /dev/tty.usbserial-14120 "KEY"
    4. Successful flash
    5. Use screen to monitor the device: screen /dev/tty.usbserial-14120 115200
    6. See the error

    Expected behavior Not bootloop

    Screenshots see error log

    OpenHaystack version: 0.5.2

    macOS version: 12.4

    Reviewed by bruvv at 2022-07-17 14:05
  • 16. Apple API startDate and endDate parameters

    I am using a custom application through the OHServerApp, and I am able to download location reports just fine.

    I tried modifying the OHServerApp code to also send startDate and endDate, but Apple seems to ignore those fields.

    Could anyone confirm that Apple just ignores those fields? If so, how did the OH Team discover those attributes at all? Do those fields get ignored if iPhones or other Apple devices send them?

    Using those fields would save me tons of traffic...

    Reviewed by dakhnod at 2022-07-17 00:43
MiniVendingMachine - SwiftUI demo Apple Watch app to open a mini vending machine via bluetooth

Mini Vending Machine Use Apple Watch to open vending machine cells. Note: This a

Apr 8, 2022
RxBluetoothKit is a Bluetooth library that makes interaction with BLE devices much more pleasant.
RxBluetoothKit is a Bluetooth library that makes interaction with BLE devices much more pleasant.

RxBluetoothKit is a Bluetooth library that makes interaction with BLE devices much more pleasant. It's backed by RxSwift and CoreBluetooth and it prov

Aug 9, 2022
Fluetooth - Flutter library for sending bytes to Bluetooth devices on Android/iOS

A Flutter library for sending bytes to Bluetooth devices. Available on Android a

Jan 2, 2022
iOS Bluetooth LE framework
iOS Bluetooth LE framework

Features A futures interface replacing protocol implementations. Timeout for Peripheral connection, Service scan, Service + Characteristic discovery a

Aug 5, 2022
Bluejay is a simple Swift framework for building reliable Bluetooth LE apps.
Bluejay is a simple Swift framework for building reliable Bluetooth LE apps.

Bluejay is a simple Swift framework for building reliable Bluetooth LE apps. Bluejay's primary goals are: Simplify talking to a single Bluetooth LE pe

Aug 3, 2022
Blocks Based Bluetooth LE Connectivity framework for iOS/watchOS/tvOS/OSX. Quickly configure centrals & peripherals, perform read/write operations, and respond characteristic updates.
Blocks Based Bluetooth LE Connectivity framework for iOS/watchOS/tvOS/OSX. Quickly configure centrals & peripherals, perform read/write operations, and respond characteristic updates.

ExtendaBLE Introduction ExtendaBLE provides a very flexible syntax for defining centrals and peripherals with ease. Following a blocks based builder a

Jul 31, 2022
Simple, block-based, lightweight library over CoreBluetooth. Will clean up your Core Bluetooth related code.
Simple, block-based, lightweight library over CoreBluetooth. Will clean up your Core Bluetooth related code.

LGBluetooth Simple, block-based, lightweight library over CoreBluetooth. Steps to start using Drag and Drop it into your project Import "LGBluetooth.h

Apr 26, 2022
Omnipod Bluetooth PumpManager For Loop

OmniBLE Omnipod Bluetooth PumpManager For Loop Status This module is at the very beginning stages of development and does not even compile yet. DO NOT

Apr 21, 2022
Diabetes: test the FreeStyle Libre glucose sensor as a Bluetooth Low Energy device, even directly from an Apple Watch.
Diabetes: test the FreeStyle Libre glucose sensor as a Bluetooth Low Energy device, even directly from an Apple Watch.

Since the FreeStyle Libre 2 / 3 glucose sensors are Bluetooth Low Energy devices, I am trying to leverage their capabilities to implement something ne

Aug 5, 2022
Bluetooth mapping in Swift
Bluetooth mapping in Swift

Bluetonium is part of the E-sites iOS Suite. Bluetonium is a Swift Library that makes it easy to communicate with Bluetooth devices. Features ?? Servi

Jul 19, 2022
Bluetooth mesh messaging SDK for apps

Berkanan SDK Berkanan SDK enables Bluetooth mesh messaging between nearby apps. It's the framework used by Berkanan Messenger (Product Hunt, TechCrunc

Jun 22, 2022
The easiest way to use Bluetooth (BLE )in ios,even bady can use.
The easiest way to use Bluetooth (BLE )in ios,even bady can use.

The easiest way to use Bluetooth (BLE )in ios,even bady can use.

Aug 6, 2022
🌍 Nearby earthquake tracking app
🌍 Nearby earthquake tracking app

Earthquake Tracker Description An application for tracking earthquakes in a radius of 2500 km from the user's location in the last month. Information

Dec 9, 2021
Nearby earthquake tracking app
Nearby earthquake tracking app

Earthquake Tracker Description An application for tracking earthquakes in a radius of 2500 km from the user's location in the last month. Information

Dec 9, 2021
A simple framework that brings Apple devices together - like a family
A simple framework that brings Apple devices together - like a family

Apple Family A simple framework that brings Apple devices together - like a family. It will automatically use bluetooth, wifi, or USB to connect and c

May 5, 2022
πŸ“±πŸ“² A wrapper for the MultipeerConnectivity framework for automatic offline data transmission between devices
πŸ“±πŸ“² A wrapper for the MultipeerConnectivity framework for automatic offline data transmission between devices

A wrapper for Apple's MultipeerConnectivity framework for offline data transmission between Apple devices. This framework makes it easy to automatical

Jul 15, 2022
BluetoothKit Easily communicate between iOS devices using BLE.

BluetoothKit Easily communicate between iOS devices using BLE. Background Apple mostly did a great job with the CoreBluetooth API, but because it enca

Aug 5, 2022
A very simple library to discover and retrieve data from nearby devices (even if the peer app works at background).
A very simple library to discover and retrieve data from nearby devices (even if the peer app works at background).

Discovery: A simple library to discover and retrieve data from nearby devices. Discovery is a very simple but useful library for discovering nearby de

Jun 29, 2022
The official Swift Library for Vital API, HealthKit and Devices

vital-ios The official Swift Library for Vital API, HealthKit and Devices Install We currently support SPM. Documentation Please refer to the official

Jul 28, 2022