Network/Services/DoorLock

DoorLock
Participants
Skills	Electronics
Status	Active
Niche	Electronics
Purpose	Infra
Tool	No
Location	Front Door
Cost
Tool category	Electronics

DoorLock Property "Tool Image" (as page type) with input value "File:{{{Picture}}}" contains invalid characters or is incomplete and therefore can cause unexpected results during a query or annotation process. {{{Picture}}} {{#if:No | [[Tool Owner::{{{ProjectParticipants}}} | }} {{#if:No | [[Tool Cost::{{{Cost}}} | }}

Summary

This page is an overview of the hardware+software system we built around the doorlock.

Architecture

Door scanner

We have an Asia-Teco scanner speaks the wiegand protocol (details can be found here: https://a.aliexpress.com/_EJOtZhl). It has the following pinout on the cable:

VCC (+12V)	Red
GND	Black
D0/RX/4R+	Green
D1/TX/4R-	White
LED	Blue
BEEP	Yellow
WG26/WG34	Gray

An arduino combined with a stepup converter is used to translate the wiegand protocol to a text-based format which is exposed over usb-serial. The code for this can be found here. This is linked together according to the following schematic, using a long piece of cat5 as the cable:

This arduino is connected using USB to spacenanny, and we run the tag scanner software there (https://gitea.vm.nurd.space/NURDspace/tag-scanner).

Tag Scanner

To read out the scanner, we use the tag-scanner software [1]. Once started, it will connect to the serial port on which the scanner is connected and wait for the scanner to send tokens. On reception of a valid token, the token is combined with a seed, and hashed using SHA256. The hashed token is used to perform a lookup in tokens.json, which contains a mapping of token -> username. If a valid match is found, a HTTP call will be made to the door lock api to disengage the door lock. If there is no valid match, a warning will be logged and a message will be posted on mqtt.

For testing purposes, the tag-scanner has a mock class to use in place of the physical tag scanner. This will automaticallty be used if there is no usb serial device available. It will present itself as a prompt which can be used to enter a token. The following is an example of running the tag-scanner in development mode, authenticating both a valid and an invalid token:

alita [tag-scanner] >> ./tag_scanner.py
INFO: Connected to localhost:1883
INFO: Scanner not found, running with a mock scanner
>> s 111234
INFO: Authorized access request for r3boot, disengaging door lock
INFO: Door lock has been engaged
>> s 111235
WARNING: Unknown token scanned: 69747dfa5ace63e857f16a73c268ce37b668a522eb6209a8b4478f3226a5d74e
>>

Furthermore, the tag-scanner will report auditing events via mqtt. The topic on which the messages is posted is '/door/access'. First, there are two messages used to signal the starting+stopping of the application:

{"host": "alita", "application": "tag-scanner", "level": "INFO", "subject": "application", "event": "starting", "timestamp": "1705766869.1188245"}
{"host": "alita", "application": "tag-scanner", "level": "INFO", "subject": "application", "event": "stopping", "timestamp": "1705766870.3937583"}

When a token is found to be valid, the following message is sent:

{"host": "alita", "application": "tag-scanner", "level": "INFO", "username": "r3boot", "event": "authorized", "timestamp": "1705767030.312545"}

When an unknown token is scanned, the following message is sent. Note that the token value is salted+hashed.

{"host": "alita", "application": "tag-scanner", "level": "INFO", "token": "69747dfa5ace63e857f16a73c268ce37b668a522eb6209a8b4478f3226a5d74e", "event": "unknown_token", "timestamp": "1705767085.1585684"}

For more information about tag-scanner, please see the README.md file in the tag-scanner repository.

Door controller

To control the EAN420 lock, we use a rest api which triggers the correct pins on the gpio ports of spacenanny. The code for this api can be found here. The rest api is secured with mutual-tls certificates based on a PKI infrastructure which is dedicated for the lock system. Access will only be granted if the api is presented with a valid certificate with an allowed Subject. Further details about this software can be found in the README.md file provided in the repository.

Lock controller

The api itself consists of three different parts globally. The Lock classes provide access to setup, status, open and close functionality for the lock. These classes will detect if the code is running on a raspberry pi. If this is not the case, a mock class will be loaded which simulates the working of the lock. This allows development of the software without access to physical hardware.

REST api

On top of the Lock classes is a Server class. This provides a flask-based api with built-in TLS support. Once a client connects, the validity of the presented certificate is checked, and a check is performed to determine if the Subject of the certificate is allowed to submit requests. Once the client is authenticated, it can call the `/v1/doorlock` using the GET and PUT methods.

If you call `GET /v1/doorlock`, the system will fetch the current state of the lock and return this as json:

{"locked": true}

If you call `PUT /v1/doorlock`, the lock will be disengaged for a configurable amount of time, after which the door lock is re-engaged. This is a blocking call, and it will return a blob of json containing the status of the operation:

{"status": true}

You can also do a GET request on the root of the api. This will return a piece of json with an overview how the API works:

{
    "endpoints": {
        "/v1/doorlock": {
            "GET": {
                "name": "status",
                "description": "Fetch the current lock status of the door"
            },
            "PUT": {
                "name": "unlock",
                "description": "Run the unlock procedure"
            }
        }
     }
}

Managing the certificates

Generating certificates for a new client is done using the `./scripts/gen_certificates.sh` script. The first time this script runs, it will automatically create the required CA certificates. You need to provide one required parameter, the Common Name for the new certificate. The CN is used by the api for authentication, and you also must add this CN to its configuration file.

alita [door_controller] >> ./scripts/gen_certificate.sh test
[+] Generating key and csr with subject /C=NL/ST=Gelderland/L=Wageningen/O=NURDspace/OU=Spacenanny/CN=test
.......+.........+...................+...+............+..+..........+.....+......+..........+........++++++
-----
[+] Signing csr with ca subject /C=NL/ST=Gelderland/L=Wageningen/O=NURDspace/OU=Spacenanny/CN=ca
Certificate request self-signature ok
subject=C = NL, ST = Gelderland, L = Wageningen, O = NURDspace, OU = Spacenanny, CN = test

You can also add a DNS-SAN as a paramter to bind the certificate to a certain host.

alita [door_controller] >> ./scripts/gen_certificate.sh test alita.local
[+] Generating key and csr with subject /C=NL/ST=Gelderland/L=Wageningen/O=NURDspace/OU=Spacenanny/CN=test
...+.........+........+..........+.........+...+...+.................+.+......+......++++++
-----
[+] Signing csr with ca subject /C=NL/ST=Gelderland/L=Wageningen/O=NURDspace/OU=Spacenanny/CN=ca and SAN DNS:alita.local
Certificate request self-signature ok
subject=C = NL, ST = Gelderland, L = Wageningen, O = NURDspace, OU = Spacenanny, CN = test

MQTT event logging

Finally, all operational actions performed by this api are logged via mqtt to the `door/access` topic. Starting and stopping of the application submits the following events:

{"host": "alita", "application": "door_controller", "level": "INFO", "subject": "application", "event": "starting", "timestamp": "1705786235.4849396"}
{"host": "alita", "application": "door_controller", "level": "INFO", "subject": "application", "event": "stopping", "timestamp": "1705786250.7989783"}

When the lock is disengaged, the following event is logged:

{"host": "alita", "application": "door_controller", "level": "INFO", "subject": "lock", "event": "disengaged", "timestamp": "1705786238.1767676"}

After 5 seconds, the lock is reengaged, leading to the following event to be logged:

{"host": "alita", "application": "door_controller", "level": "INFO", "subject": "lock", "event": "engaged", "timestamp": "1705786243.1771927"}

Usage

Adding an unknown token

Open the tag-scanner logfile on spacenanny:

journalctl -fu tag-scanner

Ask the user to tap their tag at the scanner, and copy the token found in the logs. Next, on nurdservices, run doortoken.sh to register the tag info and upload the tokens to spacenanny:

doortoken.sh add <LDAP username>
doortoken.sh upload