doc/desfire.md

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