doc/desfire.md

   1 # DESFire card
   2
   3 ## Documentation
   4
   5 [DESFire Light datasheet MF2DL(H)x0](https://www.nxp.com/docs/en/data-sheet/MF2DLHX0.pdf)
   6
   7 [Features and Hints AN12343](https://www.nxp.com/docs/en/application-note/AN12343.pdf)
   8
   9 [Quick Start Guide AN12341](https://www.nxp.com/docs/en/application-note/AN12341.pdf)
  10
  11 [LRP Specification](https://www.nxp.com/docs/en/application-note/AN12304.pdf)
  12
  13 [NTAG 424 DNA NT4H2421Gx](https://www.nxp.com/docs/en/data-sheet/NT4H2421Gx.pdf)
  14
  15 [NTAG features and hints - LRP mode](https://www.nxp.com/docs/en/application-note/AN12321.pdf)
  16
  17 [ev2 samples AN12196](https://www.nxp.com/docs/en/application-note/AN12196.pdf)
  18
  19 [MIFARE Application Directory AN10787](https://www.nxp.com/docs/en/application-note/AN10787.pdf)
  20
  21 [Symmetric key diversifications AN10922](https://www.nxp.com/docs/en/application-note/AN10922.pdf)
  22
  23 ## Source code
  24
  25 [desfire_crypto from proxmark3](https://github.com/RfidResearchGroup/proxmark3/blob/master/armsrc/desfire_crypto.c)
  26
  27 [libfreefare](https://github.com/nfc-tools/libfreefare)
  28
  29 [desfire-tools-for-android](https://github.com/skjolber/desfire-tools-for-android)
  30
  31 [nfcjlib](https://github.com/andrade/nfcjlib/)
  32
  33 [java-card-desfire-emulation](https://github.com/gathigai/java-card-desfire-emulation)
  34
  35 [ChameleonMiniDESFireStack](https://github.com/maxieds/ChameleonMiniDESFireStack/)
  36
  37 [LRP/ev2 nfc-ev2-crypto](https://github.com/icedevml/nfc-ev2-crypto)
  38
  39 ## Communication channel with a card:
  40
  41 The card can work with a combination of: key type - command set - secure channel - communication mode
  42
  43 *key types:*
  44
  45 **des** - 8-byte key. can be present in a form of **2tdea** key with length 16 bytes by duplicating contents twice.
  46
  47 **2tdea** - 16-byte key
  48
  49 **3tdea** - 24-byte key. can be disabled on the card level.
  50
  51 **aes** - 16-byte AES-128 key
  52
  53 *command sets:*
  54
  55 **native** - raw commands
  56
  57 **native iso** - wraps raw commands into the ISO APDU. **CLA** = 0x90, **INS** = command code, **data** = the remaining data from raw command
  58
  59 **iso** - works only for some commands: ISO select by ISO ID (if enabled), authenticate, read and write in the **plain** mode, read in the **mac** mode
  60
  61 *secure channels:*
  62
  63 **d40** - old secure channel that can work only with **des** and **2tdea** keys
  64
  65 **ev1** - secure channel that can work with all the keys: **des**, **2tdea**, **3tdea**, **aes**
  66
  67 **ev2** - the newest channel that can work with **aes** key only
  68
  69 *communication modes*
  70
  71 **plain** - just plain data between card and reader
  72
  73 **maced** - mac applied to request/response/both (may be sent or not)
  74
  75 **encrypted** - encrypted data in the request/response/both in the ev2 channel data signed with mac.
  76
  77 ## Card architecture
  78
  79 The card has several applications on it and the applications have files and some other objects.
  80
  81 Each card has a master application with AID 0x000000 that saves the card's configuration.
  82
  83 Master application has many keys with different purposes, but commands show that there is only one key - card master key.
  84
  85 Each application may have its own key type and set of keys. Each file can only have links to these keys in its access rights.
  86
  87 ## Card structure:
  88
  89 - Application
  90 - Application number: 1 byte
  91 - Application ISO number: if set at the time of application creation. It can be selected by this ID in the ISO command set.
  92 - Application DF name: 1-16 chars. It can be selected by this name in the ISO command set.
  93 - Key settings: number of keys, key type, key config (what can do/not user with keys)
  94 - Keys: up to 14 keys (indexes 0..d)
  95 - Key versions: key version of corresponding key
  96 - Files:
  97   - File number: 1 byte
  98   - File ISO number: should be present if and only if application created with ISO number.
  99   - File type: standard, backup, value, cyclic record, linear record, transaction mac
 100   - Some settings that belong to file type (size for standard file for example)
 101   - File communication mode: plain/maced/encrypted
 102   - File access right: there are 4 modes: read/write/read-write/change settings. And each mode access can be: key0..keyD, E - free access, F - deny access
 103
 104 ## DESFire Light:
 105
 106 The card has one preinstalled master file (ISO ID 0x3f00) and one application (0xdf01)
 107
 108 In the application, there are 6 files:
 109
 110 - 0x00 Standard data file with size 256 bytes
 111 - 0x01 Cyclic record file with 5 records with size 16 bytes each
 112 - 0x03 Value file
 113 - 0x04 Standard data file with size 256 bytes
 114 - 0x0f Transaction MAC file with size 256 bytes
 115 - 0x1f Standard data file with size 32 bytes. Used for FCI.
 116
 117 User can't create/delete files (except Transaction MAC file).
 118
 119 ISO file IDs, the other files and application parameters can be changed via SetConfiguration command only.
 120
 121 The card has two secure channels: EV2 and LRP. By default, EV2 is on. LRP can be switched on by issuing SetConfiguration command and after that, it can't be switched off.
 122
 123 Application on the card can't be selected by DESFire native select. Needs to issue ISO select command. All the commands that can work in LRP channel have **--appisoid** option
 124
 125 Transaction MAC file - the only file that can be created and deleted. By default, all transaction operations (operations with Value and Record file) need to issue CommitReaderID command.
 126 So (to fast check- it is needed to delete this file) it has default file id - 0x0f.
 127
 128 FCI sends from card to reader after selecting the application (df01 by default)
 129
 130 If it needs to have more space for FCI - just change the ID of one of the bigger files to 0x1f (and the current ID to something else) via SetConfiguration command.
 131
 132 ## How to
 133
 134 ### How to get card UID
 135
 136 The card can return UID in encrypted communication mode. Needs to authenticate with any key from the card.
 137
 138 `hf mfdes getuid` - authenticate with default key
 139
 140 `hf mfdes getuid -s d40` - via d40 secure channel
 141
 142 `hf mfdes getuid -s ev2 -t aes -k 11223344556677889900112233445566` - via ev2 secure channel with specified aes key
 143
 144 ### How to get/set default communication channel settings
 145
 146 All the commands use these settings by default if a more important setting is not specified in the command line.
 147
 148 `hf mfdes default` - get channel settings
 149
 150 `hf mfdes default -n 1 -t aes` - set key number 1 and key type aes
 151
 152 ### How to guess default communication channel settings
 153
 154 `hf mfdes detect` - simply detect key for master application (PICC level)
 155
 156 `hf mfdes detect --save` - detect key and save to defaults. look after to output of `hf mfdes default`
 157
 158 `hf mfdes detect -s d40` - detect via channel d40
 159
 160 `hf mfdes detect --dict mfdes_default_keys` - detect key with help of dictionary file
 161
 162 `hf mfdes detect --aid 123456 -n 2` - detect key 2 from application with AID 123456
 163
 164 ### How to try communication channel settings
 165
 166 `hf mfdes auth -n 0 -t des -k 1122334455667788 --aid 123456` - try application 123456 master key
 167
 168 `hf mfdes auth -n 0 -t aes --save` - try PICC AES master key and save the configuration to defaults if authentication succeeds
 169
 170 ### How to look at the application list on the card
 171
 172 `hf mfdes lsapp --no-auth` - show applications list without authentication
 173
 174 `hf mfdes lsapp` - show applications list with authentication from default settings
 175
 176 `hf mfdes lsapp --files` - show applications list with their files
 177
 178 `hf mfdes getaids --no-auth` - this command can return a simple AID list if it is enabled in the card settings
 179
 180 ### How to look/dump files from the application file list
 181
 182 `hf mfdes lsfiles --aid 123456 -t aes` - file list for application 123456 with aes key
 183
 184 `hf mfdes dump --aid 123456` - shows files and their contents from application 123456
 185
 186 ### How to change key
 187
 188 Changing key algorithm can be done only in one case - change card master key.
 189
 190 Key algorithm for application can be chosen only on its creation.
 191
 192 `hf mfdes changekey -t des --newalgo aes --newkey 11223344556677889900112233445566 --newver a5` - change picc master key from des default to aes
 193
 194 `hf mfdes changekey --aid 123456 -t des -n 0 -k 5555555555555555 --newkey 1122334455667788` - change application master key from one key to another
 195
 196 `hf mfdes changekey --aid 123456 -t des -n 0 --newkeyno 1 --oldkey 5555555555555555 --newkey 1122334455667788` - change key 1 with authentication with key 0 (app master key)
 197
 198 ### How to create the application
 199
 200 `hf mfdes createapp --aid 123456 --fid 2345 --dfname aid123456 --dstalgo aes` - create an application with ISO file ID, df name, and key algorithm AES
 201
 202 `hf mfdes createapp --aid 123456` - create an application 123456 with DES key algorithm and without ISO file ID. in this case, iso file id can't be provided for application's files
 203
 204 ### How to create files
 205
 206 `hf mfdes createfile --aid 123456 --fid 01 --isofid 0001 --size 000010` - create standard file with ISO ID and default access settings
 207
 208 `hf mfdes createfile --aid 123456 --fid 01 --isofid 0001 --size 000010 --backup` - create backup file
 209
 210 Create standard file with mac access mode and specified access settings. access settings can be changed later with command `hf mfdes chfilesettings`
 211
 212 `hf mfdes createfile --aid 123456 --fid 01 --isofid 0001 --size 000010 --amode mac --rrights free --wrights free --rwrights free --chrights key0`
 213
 214 `hf mfdes createvaluefile --aid 123456 --fid 01 --isofid 0001 --lower 00000010 --upper 00010000 --value 00000100` - create value file
 215
 216 `hf mfdes createrecordfile --aid 123456 --fid 01 --isofid 0001 --size 000010 --maxrecord 000010` - create linear record file
 217
 218 `hf mfdes createrecordfile --aid 123456 --fid 01 --isofid 0001 --size 000010 --maxrecord 000010 --cyclic` - create cyclic record file
 219
 220 `hf mfdes createmacfile --aid 123456 --fid 01 --rawrights 0FF0 --mackey 00112233445566778899aabbccddeeff --mackeyver 01` - create transaction mac file
 221
 222 ### How to delete files
 223
 224 `hf mfdes deletefile --aid 123456 --fid 01` - delete file
 225
 226 ### How to read/write files
 227
 228 *read:*
 229
 230 `hf mfdes read --aid 123456 --fid 01` - autodetect file type (with `hf mfdes getfilesettings`) and read its contents
 231
 232 `hf mfdes read --aid 123456 --fid 01 --type record --offset 000000 --length 000001` - read one last record from a record file
 233
 234 *read via ISO command set:*
 235
 236 Here it is needed to specify the type of the file because there is no `hf mfdes getfilesettings` in the ISO command set
 237
 238 `hf mfdes read --aid 123456 --fileisoid 1000 --type data -c iso` - select application via native command and then read file via ISO
 239
 240 `hf mfdes read --appisoid 0102 --fileisoid 1000 --type data -c iso` - select all via ISO commands and then read
 241
 242 `hf mfdes read --appisoid 0102 --fileisoid 1100 --type record -c iso --offset 000005 --length 000001` - read one record (number 5) from file ID 1100 via ISO command set
 243
 244 `hf mfdes read --appisoid 0102 --fileisoid 1100 --type record -c iso --offset 000005 --length 000000` - read all the records (from 5 to 1) from file ID 1100 via ISO command set
 245
 246 *write:*
 247
 248 `hf mfdes write --aid 123456 --fid 01 -d 01020304` - autodetect file type (with `hf mfdes getfilesettings`) and write data with offset 0
 249
 250 `hf mfdes write --aid 123456 --fid 01 --type data -d 01020304 --commit` - write backup data file and commit
 251
 252 `hf mfdes write --aid 123456 --fid 01 --type value -d 00000001` increment value file
 253
 254 `hf mfdes write --aid 123456 --fid 01 --type value -d 00000001 --debit` decrement value file
 255
 256 `hf mfdes write --aid 123456 --fid 01 --type record -d 01020304` write data to a record file
 257
 258 `hf mfdes write --aid 123456 --fid 01 --type record -d 01020304 --updaterec 0` update record 0 (latest) in the record file.
 259
 260 *write via iso command set:*
 261
 262 `hf mfdes write --appisoid 1234 --fileisoid 1000 --type data -c iso -d 01020304` write data to std/backup file via ISO command set
 263
 264 `hf mfdes write --appisoid 1234 --fileisoid 2000 --type record -c iso -d 01020304` send record to record file via ISO command set
 265
 266 *transactions:*
 267
 268 For more detailed samples look at the next howto.
 269
 270 `hf mfdes write --aid 123456 --fid 01 -d 01020304 --readerid 010203` write data to the file with CommitReaderID command before and CommitTransaction after write
 271
 272 ### How to work with transaction mac
 273
 274 There are two types of transactions with mac: with and without the CommitReaderID command. The type can be chosen by `hf mfdes createmacfile` command.
 275
 276 By default, the application works with transactions. All the write operations except write to standard file need to be committed by CommitTransaction command.
 277
 278 CommitTransaction command issued at the end of each write operation (except standard file).
 279
 280 Mac mode of transactions can be switched on by creating a mac file. There may be only one file with this file type for one application.
 281
 282 Command CommitReaderID enable/disable mode can be chosen at the creation of this file.
 283
 284 When CommitReaderID is enabled, it is needed to issue this command once per transaction. The transaction can't be committed without this command.
 285
 286 When the command is disabled - CommitReaderID returns an error.
 287
 288 *more info from MF2DL(H)x0 datasheet (link at the top of this document):*
 289
 290 10.3.2.1 Transaction MAC Counter (page 41)
 291
 292 10.3.2.5 Transaction MAC Reader ID and its encryption (page 43)
 293
 294 10.3.3 Transaction MAC Enabling (page 44)
 295
 296 10.3.4 Transaction MAC Calculation (page 45)
 297
 298 10.3.4.3 CommitReaderID Command (page 47)
 299
 300 *create mac file:*
 301
 302 `hf mfdes createmacfile --aid 123456 --fid 0f --rawrights 0FF0 --mackey 00112233445566778899aabbccddeeff --mackeyver 01` - create transaction mac file. CommitReaderID disabled
 303
 304 `hf mfdes createmacfile --aid 123456 --fid 0f --rawrights 0F10 --mackey 00112233445566778899aabbccddeeff --mackeyver 01` - create transaction mac file. CommitReaderID enabled with key 1
 305
 306 *read mac and transactions counter from mac file:*
 307
 308 `hf mfdes read --aid 123456 --fid 0f` - with type autodetect
 309
 310 *write to data file without CommitReaderID:*
 311
 312 `hf mfdes write --aid 123456 --fid 01 -d 01020304`
 313
 314 *write to data file with CommitReaderID:*
 315
 316 `hf mfdes write --aid 123456 --fid 01 -d 01020304 --readerid 010203`
 317
 318 *write to data file with CommitReaderID and decode previous reader ID:*
 319
 320 step 1. read mac file or read all the files to get transaction mac counter
 321
 322 `hf mfdes read --aid 123456 --fid 0f` - read mac file
 323
 324 `hf mfdes dump --aid 123456` - read all the files
 325
 326 step 2. write something to a file with CommitReaderID command and provide the key that was set by `hf mfdes createmacfile` command
 327
 328 `hf mfdes write --aid 123456 --fid 01 -d 01020304 --readerid 010203 --trkey 00112233445566778899aabbccddeeff`
 329
 330 ### How to switch DESFire Light to LRP mode
 331
 332 Remove failed authentication counters (if needs, but strongly recommended)
 333
 334 `hf mfdes setconfig --appisoid df01 -t aes -s ev2 --param 0a --data 00ffffffff`
 335
 336 or in the LRP mode
 337
 338 `hf mfdes setconfig --appisoid df01 -t aes -s lrp --param 0a --data 00ffffffff`
 339
 340 Switch LRP mode on
 341
 342 `hf mfdes setconfig --appisoid df01 -t aes -s ev2 --param 05 --data 00000000010000000000`
 343
 344