Time clock terminals

Caution

Experimental: The terminal protocol is tested against a simulated card but not yet with real readers and badges. Use terminals for trials first and report anything that seems wrong.

People stamp at a terminal at the entrance with a badge. Klokk works with NTAG 424 DNA badges (ISO 14443, AES-128): the card proves at every stamp that it holds its key, so a copy is refused. Cards that only send their number (125 kHz, MIFARE Classic UID) can be copied for a few euros and are not supported. Off by default: a super admin switches it on under API & Extensions → Access for people → Time clock terminals. Badges need DATA_KEY (the company’s card key is sealed with it).

Pairing a terminal

1. An admin adds the terminal under Admin → Terminals (name, location) and receives a pairing code — valid ten minutes, once.
2. The code and Klokk’s address are entered on the device. It makes its own key pair and registers the public key.
3. The device and the terminal page show a fingerprint; the admin confirms only if both match. A new pairing code forgets the device’s key.

Per terminal: the departments whose people may stamp there (none chosen: everyone in the company), Show time and vacation balance (with the person’s PIN unless Show without PIN) and Stamp with badge and PIN.

Issuing badges

On the terminal page the admin chooses the person and holds a new card in factory state to the terminal within two minutes. Klokk sets a key of its own on the card — derived from the company’s card key and the card’s UID — and checks the new key before it records the card. The UID is stored only as a keyed hash. People see their badges under Profile → Badges & PIN, block a lost one there at once and set their six-digit PIN.

Security and privacy

• The terminal holds no key, no list of people and no card assignments; it relays the card’s bytes. A stolen terminal reveals nothing.
• Every stamp starts with a fresh challenge: a copied card, a card with another key or a recorded conversation is refused (and noted in the audit log).
• Every request of the terminal is signed (Ed25519), carries the time (±1 minute) and a nonce used once.
• The terminal learns a first name only after the card proved itself; balances only after the PIN (by default). Five wrong PINs lock the card’s PIN for an hour.
• No biometrics, no photos. Stamps happen at Klokk’s time and are marked with the terminal in the time overview and the audit log.
• Stamps a terminal recorded while Klokk was out of reach (at most 72 hours back) are taken once each and always wait for approval — the card could not prove itself then.

Terminal devices and other systems

The terminal protocol is open for terminal software (for example an Android tablet with NFC, or a PC with a PC/SC reader): every request is signed as klokk-terminal-v1\n METHOD \n PATH \n TIME \n NONCE \n hex(SHA-256(body)) in the headers Klokk-Terminal, Klokk-Time, Klokk-Nonce, Klokk-Signature.

POST /api/v1/terminal/pair	pairing code and public key (unsigned)
GET /api/v1/terminal/status	confirmed?, name, what the terminal offers
POST /api/v1/terminal/card, /card/step	the card’s UID, then each reply of the card; the answer is the next command (APDU) or the result
POST /api/v1/terminal/stamp, /info, /session/end	after the card: stamp (in, out, break), balances, done
POST /api/v1/terminal/offline	stamps recorded offline, numbered

Existing terminal systems can stamp through the REST API instead (acting for people, a company key with write:clock). Checking the card is then up to that system — Klokk does not see the card.