History

Mike Brady 0f476da0ee Update the pair_ap library. Thanks again to ejurgensen for this code.		2022-09-26 17:24:04 +01:00
..
evrtsp	Update to the latest version of ejurgensen's pair_ap library. With thanks.	2021-11-14 14:13:31 +00:00
.gitignore	Update to the latest version of ejurgensen's pair_ap library. With thanks.	2021-11-14 14:13:31 +00:00
README.md	Update pair_ap to 0.8 (fixes incorrect pair-list response)	2021-07-15 23:22:56 +02:00
client-example.c	Update the pair_ap library. Thanks again to ejurgensen for this code.	2022-09-26 17:24:04 +01:00
pair-internal.h	Update the pair_ap library. Thanks again to ejurgensen for this code.	2022-09-26 17:24:04 +01:00
pair-tlv.c	Update the pair_ap library. Thanks again to ejurgensen for this code.	2022-09-26 17:24:04 +01:00
pair-tlv.h	Include pair_ap as a simple directory.	2021-07-07 14:11:32 +00:00
pair.c	Add update to ejurgensen's pair_ap library. Thanks as always.	2021-12-08 11:59:09 +00:00
pair.h	Update the pair_ap library. Thanks again to ejurgensen for this code.	2022-09-26 17:24:04 +01:00
pair_fruit.c	Update the pair_ap library. Thanks again to ejurgensen for this code.	2022-09-26 17:24:04 +01:00
pair_homekit.c	Update the pair_ap library. Thanks again to ejurgensen for this code.	2022-09-26 17:24:04 +01:00
server-example.c	Update to the latest version of ejurgensen's pair_ap library. With thanks.	2021-11-14 14:13:31 +00:00

README.md

pair_ap

C client implementation of pairing for:

Apple TV device verification, which became mandatory with tvOS 10.2 (this is called fruit mode in pair_ap)
Homekit pairing (also for AirPlay 2)

Credit goes to @funtax and @ViktoriiaKh for doing some of the heavy lifting.

Requirements

libsodium
libgcrypt or libopenssl
libplist (only for Apple TV device verification)

To build the example client and server you also need libevent2. If the dependencies are met you can build simply by running 'make'.

Homekit pairing

Since I haven't been able to find much information on the internet on how Homekit pairing is designed, here is a write-up of my current understanding. If you know better, please help improve this.

With Homekit pairing, there may be a controller (e.g. the Home app), and a number of devices/accessories (e.g. speakers). The controller acts as a client and can make requests for pairing. After it is paired it can also add other "third-party" pairings to the device, it can remove pairings and it can ask for a list of pairings.

Other parties, e.g. the Music app or just iOS as an Airplay sender, can also pair with devices/accesssories in a similar manner, but they are not full- fledged Homekit controllers and thus don't make requests for adding, removing or listing pairings.

The controller uses /pair-add to make sure that all devices on a network get the ID and public key of all the other devices, so that the user only needs to pair a device once.

Normal pairing with one-time code

For a normal first-time pairing, the client needs a one-time code (the device announces via mDNS whether a code is required). The client calls /pair-pin-start and the device displays the code. There is also QR-based pairing, which is (probably?) an encoded code.

After obtaining the code, the client initiates a three step /pair-setup sequence, which results in both peers registering each other's ID and public key. Henceforth, a pairing is verified with the two step /pair-verify, where the parties check eachothers identify. Saving the peer's ID + public key isn't strictly necessary if client or server doesn't care about verifying the peer, i.e. that /pair-setup has actually been completed.

The result of /pair-verify is a shared secret that is used for symmetric encryption of the following communication between the parties.

Transient pairing

Some devices don't require a code from the user for pairing (e.g. an Airport Express 2). If so, the client just needs to go through a two-step /pair-setup sequence which results in a shared secret, which is then used for encrypted communication. A fixed code of 3939 is used.

The controller can still use /pair-add etc. towards such devices.

"fruit" pairing

Like normal Homekit pairing, this consists of first requesting a code with /pair-pin-start, then a three-step /pair-setup and finally a two-step /pair-verify. After that the communication is encrypted with the resulting shared secret.