Stempelterminals

Achtung

Experimentell: Das Terminalprotokoll ist gegen eine nachgebildete Karte getestet, aber noch nicht mit echten Lesern und Ausweisen erprobt. Setzen Sie Terminals zunächst zur Erprobung ein und melden Sie, was Ihnen falsch vorkommt.

Personen stempeln an einem Terminal am Eingang mit einer Ausweiskarte. Klokk arbeitet mit NTAG 424 DNA (ISO 14443, AES-128): Die Karte beweist bei jedem Stempeln, dass sie ihren Schlüssel kennt – eine Kopie wird abgewiesen. Karten, die nur ihre Nummer senden (125 kHz, UID von MIFARE Classic), lassen sich für wenige Euro kopieren und werden nicht unterstützt. Ab Werk ausgeschaltet: Ein Super-Admin schaltet es unter API & Erweiterungen → Zugriff für Personen → Stempelterminals ein. Ausweise brauchen DATA_KEY (der Kartenschlüssel der Firma ist damit versiegelt).

Terminal koppeln

1. Ein Admin legt das Terminal unter Admin → Terminals an (Name, Standort) und erhält einen Kopplungscode – zehn Minuten gültig, einmalig.
2. Code und Adresse von Klokk werden am Gerät eingegeben. Es erzeugt sein eigenes Schlüsselpaar und meldet den öffentlichen Schlüssel.
3. Gerät und Terminalseite zeigen einen Fingerabdruck; der Admin bestätigt nur, wenn beide übereinstimmen. Ein neuer Kopplungscode verwirft den Schlüssel des Geräts.

Je Terminal: die Abteilungen, deren Personen dort stempeln dürfen (keine Auswahl: die ganze Firma), Zeitkonto und Resturlaub anzeigen (mit der PIN der Person, außer bei Anzeige ohne PIN) und Stempeln mit Karte und PIN.

Ausweise ausgeben

Auf der Terminalseite wählt der Admin die Person und hält innerhalb von zwei Minuten eine neue Karte im Werkszustand an das Terminal. Klokk setzt einen eigenen Schlüssel auf die Karte – abgeleitet aus dem Kartenschlüssel der Firma und der UID der Karte – und prüft den neuen Schlüssel, bevor die Karte erfasst wird. Die UID wird nur als verschlüsselter Hash gespeichert. Personen sehen ihre Ausweise unter Profil → Ausweise & PIN, sperren eine verlorene Karte dort sofort und legen ihre sechsstellige PIN fest.

Sicherheit und Datenschutz

• Das Terminal hält keinen Schlüssel, keine Personenliste und keine Kartenzuordnung; es reicht nur die Bytes der Karte weiter. Ein gestohlenes Terminal verrät nichts.
• Jedes Stempeln beginnt mit einer frischen Challenge: Eine kopierte Karte, eine Karte mit anderem Schlüssel oder ein aufgezeichneter Ablauf wird abgewiesen (und im Audit-Log vermerkt).
• Jede Anfrage des Terminals ist signiert (Ed25519), trägt die Uhrzeit (±1 Minute) und einen Einmalwert.
• Das Terminal erfährt einen Vornamen erst, wenn die Karte sich bewiesen hat; Salden erst nach der PIN (Standard). Fünf falsche PINs sperren die PIN der Karte für eine Stunde.
• Keine Biometrie, keine Fotos. Gestempelt wird zur Zeit von Klokk; Zeitübersicht und Audit-Log nennen das Terminal.
• Was ein Terminal ohne Verbindung zu Klokk erfasst hat (höchstens 72 Stunden zurück), wird je einmal übernommen und wartet immer auf Freigabe – die Karte konnte sich in dem Moment nicht beweisen.

Terminalgeräte und andere Systeme

Das Terminalprotokoll steht Terminal-Software offen (etwa einem Android-Tablet mit NFC oder einem PC mit PC/SC-Leser): Jede Anfrage ist signiert als klokk-terminal-v1\n METHODE \n PFAD \n ZEIT \n NONCE \n hex(SHA-256(Body)) in den Kopfzeilen Klokk-Terminal, Klokk-Time, Klokk-Nonce, Klokk-Signature.

POST /api/v1/terminal/pair	Kopplungscode und öffentlicher Schlüssel (ohne Signatur)
GET /api/v1/terminal/status	bestätigt?, Name, was das Terminal anbietet
POST /api/v1/terminal/card, /card/step	UID der Karte, dann jede Antwort der Karte; die Antwort ist der nächste Befehl (APDU) oder das Ergebnis
POST /api/v1/terminal/stamp, /info, /session/end	nach der Karte: stempeln (Kommen, Gehen, Pause), Salden, fertig
POST /api/v1/terminal/offline	ohne Verbindung erfasste Stempelungen, nummeriert

Vorhandene Terminalsysteme können stattdessen über die REST-API stempeln (Für Personen handeln, ein Firmen-Schlüssel mit write:clock). Die Prüfung der Karte liegt dann bei diesem System – Klokk sieht die Karte nicht.