Smartcards mit eigenen Werkzeugen beschreiben
FlexKey ist nur ein Weg, Smartcards für TheFlex zu beschreiben. Wenn Sie Karten bereits mit einem eigenen Programm ausgeben, zum Beispiel mit einem Kartendrucker oder einem Ausweissystem, können Sie das Zertifikat auch selbst auf die Karte schreiben. TheFlex liest jede Karte, die so aufgebaut ist, wie auf dieser Seite beschrieben.
Die Seite richtet sich an Entwickler. Für den normalen Einsatz reicht FlexKey.
Auf einen Blick
| Karte | MIFARE DESFire EV1, EV2 oder EV3, ISO/IEC 14443-4 Typ A |
| Anwendung | AID 000002, 5 AES-128-Schlüssel, Schlüsseleinstellungen 0x0F |
| Schlüssel | Schlüssel 3 = Ihr AES Key. Mit ihm liest TheFlex das Zertifikat |
| Datei | Standard Data File Nr. 1, Kommunikation unverschlüsselt (0x00), alle Zugriffsrechte auf Schlüssel 3 |
| Inhalt | Die .p12-Datei (PKCS#12) unverändert ab Byte 0, Rest der Datei mit 0x00 aufgefüllt |
| Konfiguration | JSON mit AID, AES Key, Schlüsselnummer, Datei und Zertifikatspasswort, per QR-Code oder MDM an TheFlex |
AID, Dateinummer und Schlüssel sind einstellbar. Die Werte oben sind die Standardwerte von TheFlex und FlexKey. Wenn Sie andere Werte verwenden, müssen sie in der Konfiguration genauso stehen.
Anforderungen an die Karte
| Anforderung | Warum |
|---|---|
| MIFARE DESFire EV1 oder neuer (EV2, EV3 im EV1-kompatiblen Modus) | TheFlex nutzt die DESFire-EV1-Befehle. DESFire Light, MIFARE Classic, Ultralight und NTAG beherrschen sie nicht |
| ISO/IEC 14443-4 Typ A (IsoDep) | So spricht Android mit der Karte |
| Anwendung anlegen erlaubt | Entweder steht der Hauptschlüssel der Karte (PICC Master Key) auf Werkseinstellung, oder Ihr Programm kennt ihn. Bei neuen Karten ist das so |
| Anwendungen auflisten ohne Anmeldung | TheFlex sucht die Anwendung über GetApplicationIDs. Das klappt, wenn der PICC Master Key auf Werkseinstellung steht oder in den Schlüsseleinstellungen der Karte das freie Auflisten erlaubt ist (Bit 1, bei neuen Karten gesetzt) |
| Freier Speicher | Größe der .p12-Datei, aufgerundet auf volle 256 Byte, plus etwas Verwaltung. 4096-Bit-Schlüssel (etwa 5,5 KB): 8 KB-Karte. 2048-Bit-Schlüssel (etwa 2,7 KB): 4 KB reichen |
Welche Kartentypen passen, steht ausführlich unter Welche Karten passen?
Aufbau auf der Karte
Anwendung
| Feld | Wert | Bedeutung |
|---|---|---|
| AID | 000002 | Auf der Leitung niederwertiges Byte zuerst: 02 00 00 |
| Schlüsseleinstellungen | 0x0F | Dateien ohne Anmeldung auflisten und anlegen erlaubt, Schlüssel ändern nur mit Schlüssel 0 |
| Anzahl und Art der Schlüssel | 0x85 | 5 Schlüssel (0 bis 4), Typ AES-128 |
Schlüssel
| Nr. | Wert | Verwendung |
|---|---|---|
| 0 | Werkseinstellung (16 x 00) | Hauptschlüssel der Anwendung. TheFlex braucht ihn nicht |
| 1, 2, 4 | Werkseinstellung | Nicht verwendet |
| 3 | Ihr AES Key (16 Byte) | Lesen und Schreiben des Zertifikats. In der Konfiguration readKey |
FlexKey lässt Schlüssel 0 auf der Werkseinstellung. Mit ihm kann man die Anwendung löschen, aber das Zertifikat nicht lesen: Dafür ist Schlüssel 3 nötig. Sie können Schlüssel 0 in Ihrem Programm auf einen eigenen Wert setzen. TheFlex liest die Karte trotzdem, und FlexKey kann sie weiterhin neu beschreiben.
Datei
| Feld | Wert | Bedeutung |
|---|---|---|
| Typ | Standard Data File | Befehl CreateStdDataFile (0xCD) |
| Nummer | 0x01 | In der Konfiguration fileID |
| Kommunikation | 0x00 | Unverschlüsselt (plain). Das Zertifikat selbst ist durch das Passwort der .p12-Datei geschützt |
| Zugriffsrechte | 0x33 0x33 | Lesen, Schreiben, Lesen+Schreiben und Rechte ändern: jeweils Schlüssel 3 |
| Größe | Vielfaches von 256 Byte | Mindestens so groß wie die .p12-Datei |
Inhalt der Datei
- Ab Byte 0 die .p12-Datei (PKCS#12, DER-kodiert) Byte für Byte, ohne Base64 und ohne eigene Kopfdaten.
- Die restlichen Bytes bis zum Dateiende sind
0x00. - Die .p12-Datei enthält den privaten Schlüssel und das Zertifikat des Anwenders. Das Passwort ist für alle Karten gleich und steht in der Konfiguration als
certPw.
TheFlex liest immer die ganze Datei und öffnet sie als PKCS#12. Die Nullen am Ende stören dabei nicht.
Befehlsfolge zum Beschreiben
So beschreibt FlexKey eine Karte. Ihr Programm kann jede DESFire-Bibliothek verwenden, entscheidend ist das Ergebnis auf der Karte.
| Schritt | Befehl | Code | Daten | Hinweis |
|---|---|---|---|---|
| 1 | SelectApplication | 5A | 00 00 00 | Ebene der Karte (PICC) |
| 2 | Authenticate (DES) | 0A | Schlüssel 00, Wert 8 x 00 | Nur nötig, wenn die Karte das freie Anlegen von Anwendungen nicht erlaubt. Fehler hier ignoriert FlexKey |
| 3 | CreateApplication | CA | 02 00 00 0F 85 | Antwort DE (gibt es schon) ist in Ordnung |
| 4 | SelectApplication | 5A | 02 00 00 | |
| 5 | AuthenticateAES | AA | Schlüssel 00, Wert 16 x 00 | Schlägt bei Karten fehl, deren Schlüssel 0 geändert wurde. Dann Schritt 6 auslassen |
| 6 | ChangeKey | C4 | Schlüssel 03, neu: AES Key, alt: 16 x 00 | Nur bei neuen Karten. Ist Schlüssel 3 schon gesetzt, schlägt der Befehl fehl, das ist in Ordnung |
| 7 | AuthenticateAES | AA | Schlüssel 03, Wert: AES Key | Muss klappen, sonst passt der AES Key nicht zur Karte |
| 8 | CreateStdDataFile | CD | 01 00 33 33 Größe (3 Byte, niederwertiges Byte zuerst) | Antwort DE (gibt es schon): Datei wird überschrieben |
| 9 | AuthenticateAES | AA | Schlüssel 03, Wert: AES Key | Erneut anmelden, wie FlexKey es tut |
| 10 | WriteData | 3D | 01, Offset 00 00 00, Länge (3 Byte), Daten | .p12-Datei plus Nullen bis zur Dateigröße |
| 11 | ReadData | BD | 01, Offset 00 00 00, Länge der .p12-Datei | Empfohlen: zurücklesen und vergleichen |
Die Befehle werden im ISO/IEC 7816-4-Rahmen gesendet: 90 <Code> 00 00 <Lc> <Daten> 00. Die Karte antwortet mit 91 00 (in Ordnung), 91 AF (weitere Daten folgen) oder 91 <Fehlercode>. Häufige Fehlercodes: AE Anmeldung fehlgeschlagen, 9D keine Berechtigung, BE Datei zu klein, 0E Speicher voll, DE gibt es schon.
Für Karten, die schon einmal beschrieben wurden, gilt dieselbe Folge: Schritt 3 und 8 melden dann DE, Schritt 6 schlägt fehl, alles andere läuft wie bei einer neuen Karte.
So liest TheFlex die Karte
Damit Sie Ihr Ergebnis prüfen können, hier die Schritte von TheFlex:
- Anmeldung an der Karte mit dem DES-Standardschlüssel. Das Ergebnis ist egal.
- GetVersion (
60) und GetApplicationIDs (6A), darin wird die AID aus der Konfiguration gesucht. - SelectApplication (
5A) und GetKeySettings (45). - GetFileIDs (
6F) und GetFileSettings (F5) ohne Anmeldung. Deshalb muss in den Schlüsseleinstellungen der Anwendung das freie Auflisten erlaubt sein (Bit 1 von0x0F). - AuthenticateAES (
AA) mitreadKeyundauthKeyaus der Konfiguration. - ReadData (
BD) über die ganze Dateigröße. - Die Daten als PKCS#12 mit
certPwöffnen und das Zertifikat für die Anmeldung verwenden.
Konfiguration für TheFlex
TheFlex braucht dieselben Werte, mit denen die Karte beschrieben wurde. Sie werden als JSON übergeben:
{
"applicationID": [0, 0, 2],
"authKey": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16],
"readKey": 3,
"fileID": 1,
"certPw": "Passwort-der-p12-Dateien"
}Die Werte von authKey oben sind nur Platzhalter. Verwenden Sie einen eigenen Zufallswert.
| Feld | Inhalt |
|---|---|
applicationID | AID als 3 Bytes, höchstwertiges Byte zuerst. AID 000002 ist [0, 0, 2] |
authKey | AES Key als 16 Bytes. Nicht 16 x 0: Das ist die Werkseinstellung, die Karte wäre ungeschützt. FlexKey lehnt diesen Wert ab |
readKey | Nummer des Schlüssels für das Zertifikat, Standard 3 |
fileID | Nummer der Datei, Standard 1 |
certPw | Passwort der .p12-Dateien |
Bytes als Zahlen von -128 bis 127
Die Bytes in applicationID und authKey stehen als Dezimalzahlen mit Vorzeichen im JSON, so wie Java sie speichert. Werte über 127 werden um 256 verringert: Hex f3 (243) wird -13, Hex 80 (128) wird -128, Hex 7f bleibt 127.
Geben Sie immer alle fünf Felder an. Fehlende Felder ersetzt TheFlex durch seine Standardwerte.
Das JSON kommt auf demselben Weg zu TheFlex wie bei FlexKey, siehe TheFlex einrichten:
- als QR-Code, der in TheFlex gescannt wird, oder
- als Wert des MDM-Schlüssels
NFCConfig.
TheFlex nimmt das JSON im Klartext an. FlexKey gibt es zusätzlich verschlüsselt aus (Wert beginnt mit FLXKEY1:). Dieses Format erzeugt nur FlexKey. Wenn Sie den Klartext verteilen, behandeln Sie ihn wie ein Passwort: Wer ihn hat, kann Ihre Karten lesen.
Ergebnis prüfen
- Eine Karte mit Ihrem Programm beschreiben.
- Das JSON per QR-Code in ein TheFlex-Gerät einspielen.
- Die Anmeldung mit der Karte testen, siehe Testen.
Zum Vergleich können Sie eine Karte mit FlexKey und denselben Werten beschreiben. Karten aus Ihrem Programm und aus FlexKey sind dann gleich aufgebaut, FlexKey kann Ihre Karten auch neu beschreiben.