Writing smartcards with your own tools
FlexKey is only one way to write smartcards for TheFlex. If you already issue cards with your own program, for example with a card printer or a badge system, you can write the certificate to the card yourself. TheFlex reads every card that is structured as described on this page.
This page is aimed at developers. For normal use, FlexKey is all you need.
At a glance
| Card | MIFARE DESFire EV1, EV2 or EV3, ISO/IEC 14443-4 type A |
| Application | AID 000002, 5 AES-128 keys, key settings 0x0F |
| Keys | Key 3 = your AES Key. TheFlex reads the certificate with it |
| File | Standard data file no. 1, plain communication (0x00), all access rights on key 3 |
| Content | The .p12 file (PKCS#12) unchanged from byte 0, rest of the file filled with 0x00 |
| Configuration | JSON with AID, AES Key, key number, file and certificate password, handed to TheFlex via QR code or MDM |
AID, file number and key can be configured. The values above are the defaults of TheFlex and FlexKey. If you use other values, they must be the same in the configuration.
Card requirements
| Requirement | Why |
|---|---|
| MIFARE DESFire EV1 or newer (EV2, EV3 in EV1 compatible mode) | TheFlex uses the DESFire EV1 commands. DESFire Light, MIFARE Classic, Ultralight and NTAG do not support them |
| ISO/IEC 14443-4 type A (IsoDep) | This is how Android talks to the card |
| Creating applications allowed | Either the card master key (PICC master key) is at factory default, or your program knows it. This is the case with new cards |
| Listing applications without authentication | TheFlex looks for the application with GetApplicationIDs. This works if the PICC master key is at factory default or the card key settings allow free listing (bit 1, set on new cards) |
| Free memory | Size of the .p12 file, rounded up to full 256 bytes, plus some overhead. 4096 bit keys (about 5.5 KB): 8 KB card. 2048 bit keys (about 2.7 KB): 4 KB is enough |
Which card types are suitable is described in detail in Which cards are suitable?
Structure on the card
Application
| Field | Value | Meaning |
|---|---|---|
| AID | 000002 | On the wire least significant byte first: 02 00 00 |
| Key settings | 0x0F | Listing and creating files without authentication allowed, changing keys only with key 0 |
| Number and type of keys | 0x85 | 5 keys (0 to 4), type AES-128 |
Keys
| No. | Value | Use |
|---|---|---|
| 0 | Factory default (16 x 00) | Application master key. TheFlex does not need it |
| 1, 2, 4 | Factory default | Not used |
| 3 | Your AES Key (16 bytes) | Reading and writing the certificate. readKey in the configuration |
FlexKey leaves key 0 at factory default. With it, the application can be deleted, but the certificate cannot be read: that requires key 3. You can set key 0 to your own value in your program. TheFlex still reads the card, and FlexKey can still rewrite it.
File
| Field | Value | Meaning |
|---|---|---|
| Type | Standard data file | Command CreateStdDataFile (0xCD) |
| Number | 0x01 | fileID in the configuration |
| Communication | 0x00 | Plain. The certificate itself is protected by the password of the .p12 file |
| Access rights | 0x33 0x33 | Read, write, read+write and change rights: key 3 each |
| Size | Multiple of 256 bytes | At least as large as the .p12 file |
File content
- From byte 0 the .p12 file (PKCS#12, DER encoded) byte by byte, without Base64 and without any header of your own.
- The remaining bytes up to the end of the file are
0x00. - The .p12 file contains the private key and the certificate of the user. The password is the same for all cards and is stored in the configuration as
certPw.
TheFlex always reads the whole file and opens it as PKCS#12. The zeros at the end do not interfere.
Command sequence for writing
This is how FlexKey writes a card. Your program can use any DESFire library, what counts is the result on the card.
| Step | Command | Code | Data | Note |
|---|---|---|---|---|
| 1 | SelectApplication | 5A | 00 00 00 | Card level (PICC) |
| 2 | Authenticate (DES) | 0A | Key 00, value 8 x 00 | Only needed if the card does not allow free creation of applications. FlexKey ignores errors here |
| 3 | CreateApplication | CA | 02 00 00 0F 85 | Response DE (already exists) is fine |
| 4 | SelectApplication | 5A | 02 00 00 | |
| 5 | AuthenticateAES | AA | Key 00, value 16 x 00 | Fails on cards whose key 0 has been changed. Then skip step 6 |
| 6 | ChangeKey | C4 | Key 03, new: AES Key, old: 16 x 00 | Only for new cards. If key 3 is already set, the command fails, which is fine |
| 7 | AuthenticateAES | AA | Key 03, value: AES Key | Must succeed, otherwise the AES Key does not match the card |
| 8 | CreateStdDataFile | CD | 01 00 33 33 size (3 bytes, least significant byte first) | Response DE (already exists): the file is overwritten |
| 9 | AuthenticateAES | AA | Key 03, value: AES Key | Authenticate again, as FlexKey does |
| 10 | WriteData | 3D | 01, offset 00 00 00, length (3 bytes), data | .p12 file plus zeros up to the file size |
| 11 | ReadData | BD | 01, offset 00 00 00, length of the .p12 file | Recommended: read back and compare |
The commands are sent wrapped in ISO/IEC 7816-4: 90 <code> 00 00 <Lc> <data> 00. The card responds with 91 00 (OK), 91 AF (more data follows) or 91 <error code>. Common error codes: AE authentication failed, 9D permission denied, BE file too small, 0E memory full, DE already exists.
The same sequence applies to cards that have been written before: steps 3 and 8 then report DE, step 6 fails, everything else runs as with a new card.
How TheFlex reads the card
So you can check your result, these are the steps of TheFlex:
- Authentication at card level with the DES default key. The result does not matter.
- GetVersion (
60) and GetApplicationIDs (6A), the AID from the configuration is searched for there. - SelectApplication (
5A) and GetKeySettings (45). - GetFileIDs (
6F) and GetFileSettings (F5) without authentication. This is why the key settings of the application must allow free listing (bit 1 of0x0F). - AuthenticateAES (
AA) withreadKeyandauthKeyfrom the configuration. - ReadData (
BD) over the whole file size. - Open the data as PKCS#12 with
certPwand use the certificate for the login.
Configuration for TheFlex
TheFlex needs the same values that were used to write the card. They are passed as JSON:
{
"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": "password-of-the-p12-files"
}The values of authKey above are only placeholders. Use your own random value.
| Field | Content |
|---|---|
applicationID | AID as 3 bytes, most significant byte first. AID 000002 is [0, 0, 2] |
authKey | AES Key as 16 bytes. Not 16 x 0: that is the factory default and would leave the card unprotected. FlexKey rejects this value |
readKey | Number of the key for the certificate, default 3 |
fileID | Number of the file, default 1 |
certPw | Password of the .p12 files |
Bytes as numbers from -128 to 127
The bytes in applicationID and authKey are written in the JSON as signed decimal numbers, the way Java stores them. Values above 127 are reduced by 256: hex f3 (243) becomes -13, hex 80 (128) becomes -128, hex 7f stays 127.
Always specify all five fields. TheFlex replaces missing fields with its default values.
The JSON reaches TheFlex the same way as with FlexKey, see Set up TheFlex:
- as a QR code that is scanned in TheFlex, or
- as the value of the MDM key
NFCConfig.
TheFlex accepts the JSON in plain text. FlexKey additionally outputs it encrypted (value starts with FLXKEY1:). Only FlexKey creates this format. If you distribute the plain text, treat it like a password: whoever has it can read your cards.
Check the result
- Write a card with your program.
- Import the JSON into a TheFlex device via QR code.
- Test the login with the card, see Test.
For comparison, you can write a card with FlexKey and the same values. Cards from your program and from FlexKey then have the same structure, and FlexKey can also rewrite your cards.