Skip to content

Latest commit

 

History

History
190 lines (175 loc) · 7.7 KB

README.md

File metadata and controls

190 lines (175 loc) · 7.7 KB
Raw

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:

![Connecting PN532]

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