MQTTHomeKeyLock

A NFC Reader that Exposes a Homekit HomeKey Lock and publishes over mqtt

Still under development

Configuration

Configuration is done via a Docker Environment Variables, with the following configurables:

Category	Veriable Name	Description	Default
Docker	TZ	The Container Timezone	"Europe/London"
Logging	LOG_LEVEL	Level to log messages at. All logs related to this codebase use INFO level (20).	"20"
Name	LOCK_NAME	A lock name to be used to identify the lock in MQTT and HomeKit	"NFC_LOCK"
NFC	NFC_PORT	Path to serial port of the connected NFC module	"USB0"
	NFC_DRIVER	Nfcpy driver to use with your device. Implementation was only tested for PN532, other modules have to be verified separately (if supported by nfcpy);	"pn532"
	NFC_BROADCAST	Configures if to use broadcast frames and ECP. If this parameter is true but used NFC device is not based on PN532, will cause an exception to be raised, set to false only if such problems occur	"True"
HAP	HAP_PORT	Network port of the virtual accessory	"51926"
	HAP_PERSIST	File to store HAP-python pairing data in	"/persist/hap.state"
HomeKey	HOMEKEY_PERSIST	File to save endpoint and issuer configuration data in	"/persist/homekey.json"
	HOMEKEY_EXPRESS	Configures if to trigger express mode on devices that have it enabled. If set to `false`, bringing a device to the reader will display the key on the screen while asking for biometric authentication. Beware that this doesn't increase security as express mode is disabled on ECP level, so a would-be attacker could always 'excite' the device with express ECP frame and bring it to the reader	"True"
	HOMEKEY_FINISH	Color of the home key art to display on your device. Usually, finish of the first NFC lock added to your home defines which color the keys are going to be, even if more locks are added; Possible values: `black` `tan` `gold` `silver`	"black"
	HOMEKEY_FLOW	Minimum viable digital key transaction flow do. By default, reader attempts to do as least actions as possible, with fallback to next level of authentication only happening if the previous one failed. Setting this setting to `standard` or `attestation` will force protocol to fall back to those flows even if they're not required for successful auth. Possible values: `fast` `standard` `attestation`	"fast"
Lock	LOCK_SHOULD_RELOCK	If the virtual lock should automatically lock after unlocking	"True"
MQTT	MQTT_SERVER	The MQTT Server to post updates to	"192.168.1.2"
	MQTT_PORT	The port on which to connect to the MQTT server	"1883"
	MQTT_CLIENT_ID	The client ID to use in MQTT	"mqtt-homekey-lock"
	MQTT_AUTH	If it should use MQTT Authentication	"False"
	MQTT_USER	The user that should be used when connecting to MQTT	""
	MQTT_PASS	The password that should be used when connecting to MQTT	""
	MQTT_PREFIX_TOPIC	The prefix topic to use when posting to MQTT	"mqtt-homekey-lock"
	MQTT_HASS_ENABLED	If it should post Home Assistant auto configuration settings in MQTT	"True"
	MQTT_STATUS_TOPIC	The status topic to watch for home assistant status	"homeassistant/status"
Prometheus	PROMETHEUS_ENABLED	Should prometheus metrics be exported.	"True"
	PROMETHEUS_PORT	The port prometheus metrics should be exported on.	"8000"

Requirements

Running this project requires the following:

• An operating system: Linux or macOS;
• Docker instilation;
• A PN532 module connected to a PC or SBC via UART (not through I2C or SPI);
• Either Ethernet or Wi-Fi to ensure HAP can be discovered.

When using a PC, connect the PN532 to a UART adapter, and then connect the adapter to the PC as follows:

Notes

• This code is provided as-is. Considering the sensitive nature of authentication and security, I assume no responsibility for any issues that may arise while using this project;
• Information is provided here for learning and DIY purposes only, usage in commercial applications is highly discouraged.
• Refrain from posting raw logs as they may contain sensitive information, such as reader private key, issuer id's, etc.
• If you find a bug, feel free to raise an issue;

Credits

This project would have been impossible without the contributions of:

• @kupa22 - for full HAP part analysis, NFC protocol research;
• @kormax - Proof of Concept, ECP, NFC protocol research;

Special thanks to:

• @gm3197 - for finding clues about ISO18013 being used in Home Key protocol;
• @KhaosT - for creating a demo that caused Home Key to appear in Wallet, which partially inspired me/others to go on this journey;
• @ikalchev and @bdraco for developing HAP-Python and helping with accepting in changes that were needed for this project;
• Other people, who gave their input on demo app improvement.

References

• Learning material:
  • Apple Home Key - kupa22 - HAP part, deriviation info;
  • Apple Home Key - kormax - extra Home Key info;
  • Enhanced Contactless Polling - Broadcast Frames, ECP.