Smartcards beschreiben mit FlexKey
FlexKey ist das Windows-Werkzeug, mit dem Sie die persönlichen Zertifikate Ihrer Anwender auf Smartcards schreiben. Es erzeugt außerdem die Smartcard-Konfiguration: den Schlüssel, den TheFlex braucht, um die Karten zu lesen. FlexKey erhalten Sie mit Ihrer TheFlex-Lizenz.

Wo dieser Schritt in der gesamten Einrichtung steht, zeigt Login mit Smartcard.
Was Sie brauchen
| FlexKey | Für Windows. Java ist enthalten, Sie starten es mit einem Doppelklick auf flexkey.exe. |
| Kartenleser | Ein Leser für kontaktlose Karten am PC, z. B. HID Omnikey 5022 CL. |
| Smartcards | Typ MIFARE DESFire, z. B. MIFARE DESFire EV1 8K. Neue, leere Karten funktionieren ohne Vorarbeit. Welche Karten passen und wie viel Speicher nötig ist, steht unter Welche Karten passen? |
| Zertifikate | Die persönlichen Zertifikate als .p12-Dateien, alle mit demselben Passwort. Wie sie entstehen, steht unter Zertifikate. |
Systemvoraussetzungen
| Windows | Windows 10 oder 11 |
| Java | Im FlexKey-Paket enthalten (Ordner embedded_java), nichts zu installieren. Wer flexkey.jar direkt startet, braucht Java 11 oder neuer mit dem Modul java.smartcardio. Das ist in jedem üblichen JDK und JRE enthalten, z. B. SapMachine, Eclipse Temurin oder Oracle Java. Geprüft mit Java 11 und 21 |
| Kartenleser | Ein PC/SC-Leser (CCID) für kontaktlose Karten nach ISO/IEC 14443 Typ A, der DESFire-Befehle an die Karte durchreicht. Windows bringt den Treiber für CCID-Leser mit. Empfohlen: HID Omnikey 5022 CL |
| Windows-Dienst | Der Dienst Smartcard (SCardSvr) muss laufen. Windows startet ihn normalerweise, sobald ein Leser angeschlossen ist |
| Schreibrecht | Im Ordner von FlexKey. Dort legt FlexKey FlexKeyConfig.json, settings.xml und den Ordner logs an. Legen Sie FlexKey deshalb nicht unter C:\Programme ab |
Sind mehrere Leser angeschlossen, nimmt FlexKey den, auf dem eine Karte liegt. Notebooks melden oft zusätzliche Leser, etwa einen eingebauten Kontaktleser oder einen virtuellen Leser von Windows. Welchen Leser FlexKey sieht, zeigt die Statuszeile unten.
Vorhandene Ausweiskarten
Bereits genutzte Karten, etwa Mitarbeiterausweise eines Zutrittssystems, sind vom Hersteller oft gegen Änderungen gesperrt. FlexKey kann sie dann nicht beschreiben. Testen Sie solche Karten vorab mit einem Exemplar.
1. FlexKey einmalig einrichten
FlexKey starten.
Mit dem Stift-Button oben rechts in den Bearbeitungsmodus wechseln.
Die vier Felder füllen:
Feld Inhalt AppID Bereich auf der Karte, in dem das Zertifikat liegt. Standard: 000002FileID Datei in diesem Bereich. Standard: 1AES Key Schlüssel, mit dem die Karte verschlossen wird: genau 32 Zeichen aus 0-9unda-fCert PW Das gemeinsame Passwort der .p12-Dateien Mit dem Disketten-Button speichern.

AppID und FileID lassen Sie am besten auf dem Standard. Ändern müssen Sie sie nur, wenn auf den Karten an dieser Stelle schon etwas anderes liegt.
Für den AES Key nehmen Sie einen Zufallswert. FlexKey erzeugt ihn auf Knopfdruck: Im Bearbeitungsmodus erscheint rechts neben dem Feld der Button Zufälligen AES Key erzeugen. Vorher warnt FlexKey: Ist schon ein AES Key eingerichtet, werden alle damit beschriebenen Karten unbrauchbar. Übernommen wird der neue Key erst mit dem Disketten-Button.
Alternativ mit OpenSSL:
openssl rand -hex 16Verwenden Sie nie einen Beispielwert aus einer Anleitung. Einen AES Key aus lauter Nullen nimmt FlexKey nicht an: Damit wäre die Karte ungeschützt.
Außerhalb des Bearbeitungsmodus zeigt FlexKey AES Key und Cert PW nur verdeckt an.
Gut aufbewahren
AES Key und Cert PW gelten für alle Karten Ihres Unternehmens. FlexKey speichert sie in der Datei FlexKeyConfig.json neben flexkey.exe. Sichern Sie diese Datei an einem geschützten Ort, wie ein Passwort.
Wer die Werte ändert, muss alle Karten neu beschreiben und die Konfiguration erneut an alle Geräte verteilen. Legen Sie sie deshalb einmal fest und ändern Sie sie danach nicht mehr.
2. Karten beschreiben
- Den Kartenleser anschließen. Die Statuszeile unten zeigt, ob ein Leser erkannt und eine Karte aufgelegt ist.
- Den Ordner mit den .p12-Dateien per Drag and Drop in die große freie Fläche ziehen. FlexKey listet alle Zertifikate darin auf.
- Ein Zertifikat auswählen. Daneben erscheinen seine Details.
- Eine Karte auf den Leser legen.
- Write NFC klicken. FlexKey schreibt das Zertifikat und liest es zur Kontrolle gleich wieder zurück.
- Die Karte mit dem Namen des Anwenders beschriften.
Hat alles geklappt, meldet FlexKey unten links: Zertifikat geschrieben und geprüft!

Für die nächste Karte: Karte tauschen, nächstes Zertifikat auswählen, Write NFC.
Zertifikat lässt sich nicht laden
Steht bei einem Zertifikat Fehler beim Laden: Das Zertifikatspasswort ist falsch., passt das Cert PW nicht zum Passwort der .p12-Datei. Korrigieren Sie es im Bearbeitungsmodus und speichern Sie. FlexKey lädt die Zertifikate danach sofort neu.
Ein Zertifikat, das sich nicht laden lässt, schreibt FlexKey nicht auf die Karte. TheFlex könnte es ohnehin nicht verwenden.
Karte neu beschreiben oder löschen
Eine Karte kann jederzeit neu beschrieben werden, zum Beispiel mit einem verlängerten Zertifikat oder für einen anderen Anwender. Schlägt das Schreiben fehl, zeigt FlexKey die Ursache und, wenn es hilft, den Hinweis, die Karte zu formatieren.
Der rote Papierkorb-Button löscht die Karte vollständig. Danach kann sie wie eine neue Karte beschrieben werden.
Wenn etwas nicht klappt
FlexKey zeigt jeden Fehler in einem Fenster an: was passiert ist und was Sie tun können. Die Details zu jedem Schritt stehen im Protokoll. Sie öffnen es mit dem Button </> unten rechts. FlexKey schreibt das Protokoll außerdem in die Datei logs\flexkey.log im FlexKey-Ordner (die letzten drei Tage). Diese Datei hilft uns, wenn Sie sich an den Support wenden.
| Meldung | Ursache | Lösung |
|---|---|---|
| Kein Kartenleser gefunden. | Leser nicht angeschlossen oder ohne Treiber | Leser anschließen. In der Statuszeile muss sein Name erscheinen |
| Keine Karte auf dem Kartenleser ... | Keine Karte aufgelegt | Karte flach auf den Leser legen, bis die Statuszeile Karte verbunden zeigt |
| Der Windows-Smartcard-Dienst läuft nicht. | Dienst Smartcard gestoppt | Dienst in der Windows-Diensteverwaltung starten oder den Leser neu anschließen |
| Der Kartenleser wird von einem anderen Programm verwendet. | Ein anderes Programm hält den Leser fest | Das andere Programm schließen |
| Eingabe prüfen beim Speichern | AppID, FileID oder AES Key haben das falsche Format, oder AppID 000000 bzw. ein AES Key aus lauter Nullen | Die Meldung nennt das Feld und die erwartete Länge. Der AES Key hat genau 32 Zeichen und ist ein Zufallswert |
| Kein AES Key eingerichtet beim Schreiben | FlexKey hat keine Konfiguration gefunden, zum Beispiel weil FlexKeyConfig.json in einem anderen Ordner liegt | Die FlexKeyConfig.json neben flexkey.exe kopieren und FlexKey neu starten. Bei der ersten Einrichtung AES Key und Cert PW eintragen und speichern |
| Zertifikat nicht lesbar beim Schreiben | Die .p12-Datei lässt sich nicht öffnen, meist passt das Cert PW nicht | Cert PW korrigieren und speichern. Ist die Datei beschädigt, das Zertifikat neu ausstellen |
| Anmeldung mit dem konfigurierten AES Key fehlgeschlagen. | Die Karte wurde mit einem anderen AES Key beschrieben | Den damals verwendeten AES Key eintragen oder die Karte formatieren |
| Die Anwendung 000002 ist nicht auf der Karte und konnte nicht angelegt werden. | Karte ist gegen Änderungen gesperrt oder keine DESFire-Karte | Andere Karte verwenden, siehe Welche Karten passen? |
| Auf der Karte ist nicht genug Speicher für das Zertifikat. | Karte zu klein oder schon belegt | Karte formatieren. Bei Zertifikaten mit 4096-Bit-Schlüssel eine 8-KB-Karte verwenden |
| Die Kommunikation mit der Karte wurde unterbrochen. | Karte während des Schreibens bewegt | Karte liegen lassen und erneut schreiben |
| Die Prüfung nach dem Schreiben ist fehlgeschlagen ... | Die Daten auf der Karte weichen ab | Erneut schreiben. Die Karte bis dahin nicht ausgeben |
| Konfiguration nicht lesbar beim Start | FlexKeyConfig.json ist beschädigt | FlexKey sichert die Datei als FlexKeyConfig.unlesbar-... und startet mit Standardwerten. AES Key und Cert PW neu eintragen |
| Speichern fehlgeschlagen | Kein Schreibrecht im FlexKey-Ordner | FlexKey in einen Ordner mit Schreibrecht kopieren |
| FlexKey konnte nicht gestartet werden | Java fehlt oder ist zu alt, oder ein Teil des Pakets fehlt | Die Meldung nennt die Java-Version. Das FlexKey-Paket vollständig neu entpacken |
3. Konfiguration an TheFlex übergeben
TheFlex braucht dieselben vier Werte wie FlexKey, um die Karten zu lesen. FlexKey stellt sie auf zwei Wegen bereit:
- QR-Code: FlexKey zeigt ihn neben den Einstellungen. Er wird in TheFlex gescannt, gut für einzelne Geräte.
- Wert für MDM: Der Button mit den geschweiften Klammern { } (Wert für MDM anzeigen) öffnet einen Dialog. Kopieren legt den Wert in die Zwischenablage. Er wird in der Geräteverwaltung als
NFCConfigeingetragen, gut für viele Geräte.

Beides ist verschlüsselt, der MDM-Wert beginnt mit FLXKEY1:. TheFlex versteht das ab Version 6.3.0. Für ältere TheFlex-Versionen bietet der Dialog Klartext kopieren (ältere TheFlex) an.
Wie Sie die Konfiguration in TheFlex einspielen, steht unter Login mit Smartcard.
Vertraulich behandeln
QR-Code und MDM-Wert sind verschlüsselt, aber sie sind trotzdem der Schlüssel zu Ihren Karten: Wer sie in ein TheFlex einspielt, kann die Karten lesen. Hängen Sie den QR-Code nicht aus und geben Sie den Wert nur an die Personen weiter, die Geräte einrichten.
Eigene Werkzeuge statt FlexKey
FlexKey ist nur ein Beispiel. Wenn Sie Karten mit einem eigenen Programm ausgeben, können Sie das Zertifikat auch selbst schreiben. Wie die Karte dafür aufgebaut sein muss, steht unter Smartcards mit eigenen Werkzeugen beschreiben.