FreeBSD Bluetooth management — Apple stack research RESEARCH

How macOS Bluetooth works (a fully closed bluetoothd + IOBluetooth/CoreBluetooth + IOBluetoothFamily.kext stack), why there is zero Apple open-source for it, why FreeBSD's ancient Netgraph stack can't do BLE, and what an Apple-shape Bluetooth path would actually require. Companion to the WiFi management and Keychain plans.

1. How the closed Apple stack works

macOS Bluetooth is layered exactly like the WiFi stack: a kernel driver family, a closed userspace management daemon that owns all the policy, and public framework facades that proxy to it over IPC. From the controller up:

The key structural fact: like wifid, bluetoothd is a single monolithic policy daemon. The frameworks do no Bluetooth work themselves — they are XPC stubs. Everything that matters (pairing state machines, GATT, profile logic, the proprietary protocols) lives inside the one closed binary.

1.1 The architecture

1.2 Two frameworks because there are two Bluetooths

This trips people up, so it's worth stating plainly. "Bluetooth" is really two mostly-separate protocol families sharing a radio:

• Bluetooth Classic (BR/EDR) — the older connection-oriented world: RFCOMM serial links, A2DP audio, HFP headset, HID. Apple exposes this through IOBluetooth.framework.
• Bluetooth Low Energy (BLE) — the newer low-power world built on GATT (attribute database of services/characteristics): watches, sensors, beacons, trackers, and Apple's own Continuity/proximity features. Apple exposes this through CoreBluetooth.framework.

They have different pairing security (Classic link keys vs BLE's SMP/LTK), different L2CAP usage, and different discovery (inquiry vs LE advertising/scanning). bluetoothd implements both. This split is why the FreeBSD gap is so damaging: FreeBSD has the Classic half and none of the BLE half — and CoreBluetooth, the API the modern world targets, is the BLE half.

1.3 What bluetoothd actually owns

1.4 The proprietary layer — MagicPairing & Continuity

Beyond standard Bluetooth, bluetoothd implements two Apple-only protocols that are the actual "magic" and are entirely undocumented (known only through reverse engineering of bluetoothd strings and device firmware):

• MagicPairing — Apple's proprietary pairing for AirPods and Magic Keyboard/Mouse/Trackpad. You pair once, and the keys sync via iCloud so the peripheral works on every device on your account. It rides on top of standard HCI (so it works with off-the-shelf radios) but is not part of any Bluetooth spec. TU Darmstadt's analysis reverse-engineered it from bluetoothd and the AirPods' RTKit firmware, and found ten security flaws across the iOS/macOS/RTKit implementations. (Heinze et al., MagicPairing, WiSec 2020)
• Continuity — a family of BLE advertisement messages Apple devices broadcast for Handoff, AirDrop discovery, proximity pairing ("bring AirPods near your Mac"), Universal Clipboard, and instant hotspot. Reverse-engineered and catalogued by the furiousMAC/continuity project. This is the BLE half of how Apple devices find each other before falling back to AWDL/WiFi for bulk transfer.

Neither is portable — they depend on iCloud key infrastructure (MagicPairing) and the broader Continuity daemon ecosystem. Even with a perfect BLE stack, AirDrop-grade interop would require reimplementing these closed protocols.

1.5 Where pairing keys live — the keychain tie-in

Bluetooth bonding produces long-lived secrets (Classic link keys, BLE LTKs) that must persist across reboots and be available before login (so a paired keyboard works at the login window). On macOS these live in a mix of com.apple.Bluetooth.plist and keychain-protected storage. This is the same problem the Keychain plan addresses for WiFi PSKs: a com.apple.bluetoothd would want a system-scoped secret store for bond keys — exactly the System-keychain consumer that plan calls out. Bluetooth and WiFi both push toward the same secd-equivalent.

2. Open-source status — there is none

This is the headline difference from every other component we've researched. Apple publishes no Bluetooth implementation at all.

3. The protocol layers, explained

Because "port Bluetooth" means rebuilding these layers, here's what each is — and which half (Classic / BLE) it belongs to.

Notice the pattern: every "missing on FreeBSD" row is a BLE row. The Classic stack is largely complete; the entire LE side (ATT/GATT/SMP/LE-L2CAP/LE-GAP) does not exist.

4. FreeBSD's Bluetooth stack today

A Netgraph-based design committed in 2002 (shipped in 5.0), split across kernel Netgraph nodes and userland daemons — structurally not unlike a host stack, and notably it already separates transport / link / management much as a clean design would.

So FreeBSD's "brain" is split across hcsecd (pairing/keys) + sdpd (discovery) + bthidd (HID) rather than one bluetoothd. That's actually a cleaner, more BSD-shaped decomposition — but it covers Classic only.

5. The BLE gap, and why BlueZ doesn't rescue us

5.1 Why we can't just take BlueZ

BlueZ is Linux's stack and the obvious "wpa_supplicant of Bluetooth" — full BLE/GATT/mesh, actively maintained. But it's the iwd problem, worse:

• License: GPL-2.0 (libraries LGPL). Cannot go in FreeBSD base; ports-only at best.
• Kernel coupling: BlueZ moved most of the host stack into the Linux kernel (the bluetooth subsystem: AF_BLUETOOTH sockets, the mgmt API, kernel L2CAP/SMP). bluetoothd(BlueZ) is a thin manager over that kernel stack — it does not contain a portable host stack. Porting it means porting or emulating the Linux kernel Bluetooth subsystem, not just building a daemon.
• IPC: D-Bus API, foreign to the Mach/DO world.

So BlueZ gives you a manager whose engine lives in a kernel you don't have. There is no clean, BSD-licensed, net80211-style userland BLE engine to adopt — the single biggest difference from the WiFi situation.

6. What an Apple-shape Bluetooth path would require

Unlike WiFi (where the kernel was ready and only a userland brain was needed), Bluetooth needs the kernel/stack BLE layer built first. Three ways to get there:

6.1 The hypothetical com.apple.bluetoothd

Whichever engine option wins, the Apple-shape layer on top is a daemon that — per the shipped system's convention — keeps Apple's own launchd label com.apple.bluetoothd (the running image labels its daemons com.apple.configd, com.apple.hostnamed, … outright; see the Keychain plan's naming note). It exposes CoreBluetooth/IOBluetooth-equivalent APIs over DO/Mach (consistent with the project's IPC choice):

@protocol NCCentralManager
- (void)scanForPeripheralsWithServices:(NSArray<NCUUID *> *)services;
- (void)connectPeripheral:(NCPeripheral *)peripheral;
@end
@protocol NCPeripheral
- (NSString *)identifier;          // CBPeripheral analog
- (NSNumber *)RSSI;
- (void)discoverServices:(NSArray<NCUUID *> *)services;
@end
@protocol NCCharacteristic
- (NCUUID *)UUID;
- (NSData *)value;
- (void)setNotifyValue:(BOOL)enabled;
@end

Backed by the chosen engine for the actual GATT/SMP work, persisting bond keys in the System keychain. This is the direct analog of wifid-fbsd — a thin Apple-shape brain over a protocol engine — except the engine has to be built, not adopted.

7. The AirDrop / Continuity tie-in

Bluetooth isn't independent of the WiFi work. Apple's proximity magic is a two-radio dance:

• BLE handles discovery — devices broadcast Continuity advertisements so a nearby Mac knows an iPhone is there and offering AirDrop.
• AWDL (the WiFi plan's gap) handles the high-speed transfer once discovery completes.
• Bonjour/mDNS (the mDNSResponder plan) names the services.

So full AirDrop interop requires all three gaps closed — BLE (here), AWDL (WiFi), and Bonjour — plus the closed Continuity/MagicPairing protocols reimplemented. That makes AirDrop a long-horizon, cross-cutting goal, not a single deliverable. The realistic near-term scope here is standard BLE (connect to a heart-rate monitor, a BLE keyboard, a sensor) — not Apple-proprietary peer interop.

8. Open questions

9. References

• MagicPairing analysis (TU Darmstadt): Heinze et al., "MagicPairing: Apple's Take on Securing Bluetooth Peripherals," WiSec 2020
• Apple Continuity BLE protocol (reverse-engineered): github.com/furiousMAC/continuity
• IOBluetooth internals writeup: colemancda — Hacking IOBluetooth
• Apple "Bluetooth on OS X" (archived): developer.apple.com — Bluetooth on OS X
• CoreBluetooth API reference: developer.apple.com/documentation/corebluetooth
• FreeBSD Bluetooth handbook: docs.freebsd.org — Bluetooth (ng_bluetooth, hcsecd, sdpd, bthidd)
• BlueZ (Linux stack, for contrast): bluez.org
• Companion plans: WiFi management, Keychain port, mDNSResponder