OpenWifiPass: the grantor half of Apple's Wi-Fi password sharing

The grantor side of a protocol, not a consumer app

OpenWifiPass is described as an open source implementation of Apple's Wi-Fi Password Sharing protocol in Python, and more precisely as an implementation of the grantor role in that protocol.

The distinction matters, because the protocol has two sides. The requestor is the device that wants a password, typically a phone joining a network it has been invited to. The grantor is the device that already knows the password and hands it over. Apple ships the requestor side in its own devices, so the interesting engineering question, and the one this project answers, is the grantor side, which is what a third party device would need to do to offer the same convenience.

That makes the project a piece of protocol archaeology rather than an application. The topics attached to the repository say as much, listing apple, opack, password-sharing, reverse-engineering and wifi, and the package description in the setup metadata calls it an open Apple Wi-Fi Password Sharing implementation.

The provenance is unusually well documented for a hobby project. The code is the result of reverse engineering efforts by the Open Wireless Link project, and the README carries a disclaimer noting that the former owlink website is no longer associated with the project and asking readers to disregard it. The author is Jannik Lorenz, and the work sits alongside a bachelor thesis at the Technical University of Darmstadt on reverse engineering and breaking the Apple Wi-Fi Password Sharing protocol, and a USENIX Security 2021 paper on attacks against the wider Apple wireless ecosystem.

So the appropriate way to read this code is as a published research artefact. It is not affiliated with or endorsed by Apple, and it is licensed under the GNU General Public License v3.0.

The disclaimer says the code does not verify the requestor

The most important paragraph in the README is the disclaimer, and it should be quoted rather than paraphrased.

OpenWifiPass is experimental software, the result of reverse engineering efforts, and the code serves solely documentary and educational purposes. It is untested and incomplete.

The example the README gives of what that means is specific: the code does not verify the identity of the requestor. The consequence stated in the README is that you should not use this implementation with sensitive Wi-Fi credentials.

That is a security architecture statement, not a missing feature. In a protocol where one device asks another for a password over Bluetooth, the requestor has to be able to establish that it is the device the network owner invited, otherwise anyone in radio range can request the credential. The grantor implementation here does not do that check, which means a successful run shares the SSID and PSK with whichever requestor asked.

The other caveats in the disclaimer are worth noting too. The status is experimental, the code is incomplete, and it is not affiliated with or endorsed by Apple, which matters if you are considering the legal position of reimplementing a proprietary protocol.

Taken together, these are the boundaries of the project. It is a research artefact for understanding how the protocol works and for reproducing published research, and the README says plainly that it is not something to point at a network you care about.

Bluetooth Low Energy on Linux, and root for the Bluetooth stack

The requirements section is two lines, and both matter.

The hardware requirement is a Bluetooth Low Energy radio, with a Raspberry Pi 4 given as the example. The operating system requirement is Linux, and the reason given is the bluepy dependency.

That dependency is not incidental. The protocol runs over Bluetooth Low Energy advertisements and connections, and bluepy is the Python binding to the BlueZ stack on Linux. The README notes that it also needs super user privileges to use the Bluetooth subsystem, which is why the run command is prefixed with sudo.

So the setup is: a Linux machine with a working BlueZ stack, a BLE capable adapter, and the ability to run as root. A Raspberry Pi 4 is a natural fit because it has BLE on board and is a common target for this kind of hardware work, but any Linux box with a BLE radio will do.

The Python side needs four runtime dependencies, listed in the packaging metadata: bluepy, cryptography, hkdf, and pycryptodomex. The presence of an HKDF implementation and two cryptography libraries tells you the protocol involves key derivation and symmetric cryptography, which is consistent with a session where a shared secret protects the credential exchange.

The package itself is modest. It requires Python 3.6 or later, declares itself an alpha with a Development Status of 3, and the classifiers cover Python 3.6 through 3.9 on POSIX Linux, with the intended audience listed as information technology and science or research.

The message exchange is a requestor role, not a password grabber

The README shows what a successful run looks like, and the output is the most useful piece of documentation in the repository because it names the protocol messages in order.

sudo -E python3 -m openwifipass --ssid OWL --psk '$uper$ecretPassword'

The output that follows starts with scanning, reports an SSID match in a PWS advertisement, connects to the device, and then walks through the message exchange: send PWS1, receive PWS2, send M1, receive M2, send M3, receive M4, send PWS3, receive PWS4, and finally reports that Wi-Fi Password Sharing completed.

Two rounds of a PWS message pair bracket a round of M messages, which is the shape of a session negotiation followed by a credential transfer. The SSID match against a PWS advertisement is how the grantor finds the requestor, since the requestor advertises the network it wants and the grantor answers only for the network it holds.

The command line is worth reading closely as well. The credentials are passed as arguments, with the README drawing attention to shell quoting, and the example uses single quotes to stop the shell expanding the dollar sign in the password. That is a small detail that has bitten a lot of people.

The -E flag on sudo preserves the environment, which is what the README's own usage line shows, and the run mode is a console script entry point named openwifipass, with a module entry point behind it.

OPACK is the reusable piece, and it has its own document

The repository contains more than the protocol implementation. There is a reusable OPACK serialiser and deserialiser, and a separate OPACK.md file explains it.

OPACK is the encoding used inside these messages, and the fact that it is packaged as a reusable component with its own documentation tells you something about how the reverse engineering was structured. Protocol work like this rarely ends at one protocol: the byte level format underneath is usually reusable across several message types, and separating it means the same serializer can be pointed at different message families.

For a reader, that is the most valuable part of the project to start with. The protocol logic is only interesting once you can see how the payloads are encoded, and a documented serialiser with tests gives you that without reading a hex dump by eye.

The repository layout backs this up. There is an openwifipass package directory, a tests directory, a Makefile, a setup.py and setup.cfg, a Manifest.in, a requirements-dev.txt, a deploy.sh script, the OPACK.md document, the README and the LICENSE.

For a project of this size, the presence of a test suite and a separate OPACK document is a good sign, and it is also a reminder that the README's untested warning is about the protocol behaviour rather than about the code having no tests at all.

The Makefile shows a small codebase with a full CI gauntlet

The build file is the clearest evidence of how the project is developed, and it is small enough to read at a glance.

The phony targets are ci, checkformat, isort, lint, pylint, test and autoformat, and the ci target runs isort, checkformat, lint, pylint and test in sequence. The virtual environment is created with virtualenv, the development requirements come from requirements-dev.txt, and the package itself is installed in editable mode.

The individual tools are the standard Python set: black for format checking, flake8 for linting, pylint with the rcfile from setup.cfg, isort for import ordering, and pytest for the tests. The autoformat target runs isort and then black over the tree.

The interesting structural detail is the dependency chain. Every target depends on the venv, and the venv activation file depends on setup.py, requirements-dev.txt and the Makefile. In other words, changing a dependency or the build file invalidates the environment and it gets rebuilt, so a stale virtualenv cannot silently mask a dependency problem.

The lint targets are scoped, with pylint pointed at the openwifipass package and the tests, and isort run over openwifipass and tests separately. That is the shape of a project where the code is small, the public surface is a single command line entry point, and the maintainer wants the style of a handful of files to stay consistent.

Editorial conclusion

OpenWifiPass suits a security researcher or student who wants to read a working reverse engineered Bluetooth Low Energy protocol and see the message exchange step by step, since the code is small, documented and accompanied by two academic write-ups of the same work. It does not suit anyone intending to use it as a credential sharing tool in production, and the README is explicit that the code is untested, incomplete and does not verify the identity of the requestor. Before you run it at all, read the disclaimer, use a Bluetooth Low Energy radio on Linux with the bluepy dependency available, and make sure the SSID and PSK you test with are throwaway values, because the grantor role hands the password to any requestor that asks.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. seemoo-lab/openwifipass on GitHub