MiFare Protocol Guide for metraTec MiFare Readers and Modules Date: June 2009 Version: 1.
Table of Content List of Abbreviations................................................................................................................4 1. Introduction.........................................................................................................................5 1.1. General Procedure........................................................................................................5 1.2.Further Documents.........................................................................
5.2. Get Access Bit (GAB)..................................................................................................23 5.3. Sector Trailer Manipulation (STM)...............................................................................24 5.3.1. Set key and Access bits (SKA)..................................................................................25 5.3.2. Set Key Only (SKO)..................................................................................................26 5.4.
List of Abbreviations ATQA Answer to request, ISO 14443A – a number code showing some information on the card. See Appendix for examples. PICC Proximity IC Card (the official word for transponder card) SAK „Select Acknowledge“ – a number code showing some information on the card, e.g. type of card, etc. See Appendix for examples.
1. Introduction This document describes the metraTec firmware protocol for all metraTec RFID readers that work with RFID transponders according to ISO14443A/MiFare (by NXP). This includes the DeskID MiFare USB, the QR14 OEM module as well as several custom reader units. The target audience for this document are programmers, who need to communicate with the reader and want to write their own software for this task.
1.2.Further Documents For an even deeper understanding of the operating principle it might be useful to read all datasheets and norms regarding your transponder IC, esp. ISO 14443-3.
2. Communication Principle The communication between the reader and the host system is based on ASCII strings. Each string is terminated with a carriage-return and will be transmitted with MSB fist. The communication from the reader to the host system (i.e. the response) is the same as above but in most cases the response from the reader comprises more than one line.
3. Reader Instructions This list gives an overview of all the existing instructions that directly influence the reader itself. All commands that are connected to the transponder, can be found in the next chapter.
3.2. Revision (REV) The revision command requests the device type and hard- and software revision of the reader. The reader returns its device type and it’s hard- and software revision. Revision has no parameters and returns no error codes.
3.4. Wake Up (WAK) The wake up command ends the power save mode. Reader will restore its last state prior to the standby. If successful it returns GMO (“Good Morning”). Wake up has no parameters. Instruction: WAK Response, if successful: GMO, DNS (if not in Standby-Mode) Possible Error Response: UPA 3.5. Read Input Pin (RIP) This command is used to read the current state of an input pin.
e.g. Set pin 0 high: WOP00HI e.g. Set pin 0 low: WOP00LOW Response, if successful: OK! Possible Error Response: NOR, EHX, UPA 3.7. Cyclic Redundancy Check On (CON) This commands turns on the Cyclic Redundancy Check (CRC) of the computer-to-reader communication. This is used to detect transmission errors between the reader and the computer.
3.8. Cyclic Redundancy Check Off (COF) This command turns off the Cyclic Redundancy Check (CRC) of the computer-to-reader communication. This is the default setting. This command will work with or without the (optional) CRC. If successful it returns OK!. Instruction: COF, or COF 4F5E, or cof E005 Response, if successful: OK! Possible Error Response: UPA 3.9. Save Static Key (SSK) The reader has a persistent memory which is able to save up to 24 keys for the MiFare Crypto1 unit.
SSK23FFFFFFFFFFFF Possible Error Response: UPA Unknown parameter EDX Location fail, or other characters than 0-9 EHX Key-Parameter is missing or other characters than 0-9 and A-F WDL Key is not 6 bytes long NOR Location given is higher than 23 3.10. Save Temporary Key (STK) This command saves one key in the reader temporarily until a power down or a reset occurs. The only parameter is the Key to save, which is a 6 Byte ASCII String (12 Chars).
SKU{Type}[Loc] Parameter Description Type The type of the key: Loc TEMP chooses the temporary key STAT chooses the static key Use this parameter only with STAT-Parameter! Specifies the zero based location of the static key. See SSK command.
4. General ISO 14443A Commands This list gives an overview of the existing commands that can be used with any transponder that is based on ISO14443A, including all MiFare dialects. Any commands that are specific to a certain type of MiFare-Type can be found in the next chapter.
IVF 02 Possible error codes: Unknown parameter UPA 4.2. Select Tag (SEL) Before you can exchange data with a MiFare chip, the transponder has to be activated (or „selected“ in the ISO14443 language). There are two different modes to select a card. Manual Transponder Select (MTS), which needs the UID of the transponder (via a previous INV command) or Automatic Transponder Select (ATS). 4.2.1.
Sometimes it is useful to work with all cards in the field. For this purpose an optional parameter “CYC” exists. When using the “CYC” parameter it is necessary to run an inventory (INV) before. After that, all transponders in the inventory list will be selected cyclically by sending SEL ATS CYC for each transponder.
C2DF6084 Possible error codes: UPA Unknown parameter TNR Tag not responding (left the field since the INV command) 4.3. Read Data from Tag (RDT) The read data command is used to retrieve the data stored in a transponder. Normally it returns 16 bytes. For compatibility to other ISO/IEC 14443-1 to 4 transponder than MiFare classic, it has a direct read mode, marked with the first parameter “DRT”. In this mode the second parameter is the custom command.
CMD Custom Read Command, one hexadecimal byte Table 5: Read command parameter description Response, if successful: Number of lines is equal to the number of read blocks. If “DRT” is not set each line is 16 Bytes (32 ASCII chars, hexadecimal) long. i.e.
command also has a direct write mode, marked with the first parameter “DRT”. The number of bytes will not be checked in this mode and it depends on the second parameter (Data). To write to MiFare Ultralight cards (which only have four bytes per block) the first parameter becomes “W4”. This parameter writes 4 bytes to the card. The selected block has to be writable for this command to work. ATTENTION If you write wrong data to the trailer block of a sector (the fourth block of every sector, e.g.
WDT00112233445566778899AABBCCDDEEFF18 Possible error codes: UPA Unknown parameter EHX The string cannot be interpreted as valid data or contains non hex characters BAE Block no. not readable, i.e. wrong key, see Block– and Access Mode BNA Block no. not authenticated (only MiFare classic) NMA No MiFare chip 1k or 4k authenticated (only ALL-Mode) WDL The hex string does not have the correct length (i.e.
5. MiFare Classic Commands This section describes commands only to be used with MiFare Classic (1K or 4K) chips.
Response, if successful: OK! Examples: Direct authentication of block 8 (sector 2) with keytype B and key FFFFFFFFFFFFh AUTDRTFFFFFFFFFFFFB8 Possible error codes: UPA Unknown parameter BIH Block no. is too high (i.e. bigger than 63 at MiFare 1k) ATE Authentication Error (i.e. wrong key) NKS No Key Select, select a temporary or a static key (use STK or SSK) CNS Card is Not Selected 5.2.
Block 13 (sector 3) is authenticated and all blocks of this sector should be returned GABALL Response: 0 1 0 (Block 12 in Block Mode 2) 0 0 1 (Block 13 in Block Mode 4) 0 1 1 (Block 14 in Block Mode 5) 1 1 0 (Block 15 in Access-Mode 3) Block 145 (sector 33) is authenticated and all blocks of this sector should be read GABALL Response: 0 1 0 (Block 144-148 in Block Mode 2) 0 0 1 (Block 149-153 in Block Mode 4) 0 1 1 (Block 154-159 in Block Mo
There are different ways to manipulate data in the sector trailer by using these modes: Set key and Access Bits (SKA) Set Keys Only (SKO) Direct over write-data command (only advanced user! Included for upward compatibility to new MiFare Standards, e.g. MiFare+) 5.3.1. Set key and Access bits (SKA) Use this mode to set both the access keys and the access bits of a specific sector.
Examples: Write Key A (665544332211), Key B (112233445566) and block mode 3 (1 1 0) for block 2 STMSKA21106655443322 112233445566 Write Key A (000000000000), Key B (FFFFFFFFFFFF) and access mode 3 (1 0 1) for block 3 STMSKA21010000000000 00 FFFFFFFFFFFF Possible error codes: UPA Unknown parameter BAE An unauthenticated block is chosen BNA Block not authenticated, Block No.
C1, C2, C3 BCD-Coded Mode, 0 or 1 KeyA MiFare authentication key A; 6 Bytes hexadecimal coded ASCII-string (16 chars) KeyB MiFare authentication key B; 6 Bytes hexadecimal coded ASCII-string (16 chars) Table 10: SKO mode parameter description Response, if successful: OK! Examples: Sector 5 which contains block 20 get the keys 112233445566 (key A) and 665544332211 (key B) STMSKO20112233445566665544332211 Possible error codes: UPA Unknown parameter BAE
Increment - adds a value (given as parameter) to the value present in a chosen block (inputblock) and writes the result to the outputblock. (Mode 3) Decrement - subtracts a value (given as parameter) to the value present in a chosen block (inputblock) and writes the result to the outputblock. (Mode 3, 4) Direct Write - writes 4 value bytes and one address byte direct to the Block (Mode 3) Restore - Writes the Date from the outputblock to the inputblock. (Mode 3, 4) 5.4.1.
VALINITSAB0020200005 Possible error codes: UPA Unknown Parameter NMA No MiFare 1k or 4k chip authenticated WDL Initial value is not 6 bytes long EDX In/Output block or value missing, or other character than ‘0’ to ‘9’ EHX The initial value is missing, or other characters the 0.. 9 and A ..
Parameter Description MOD Selected either increment (INC) or decrement (DEC) VALUE unsigned hexadecimal value (summand/subtrahend) Inputblock 1 decimal Byte, i.e. 0 to 63 for Mifare 1k, or 0 to 255 for Mifare 4k, but not trailer Outputblo ck 1 decimal Byte, i.e.
5.4.3. Restore This command is used for powerful backups. If the input –and outputblock are not the same, this command restores the result written in the outputblock to the inputblock. The outputblock has to be in the correct value block format for this command to work.
6.
BNW Block Not Writable BAE Block Access Error BNA Block Not Authenticated AKW Access bits or Keys not Writable UKB Use Key B for authentication UKA Use Key B for authentication KNC Keys not changeable BIH Block is too high (i.e. bigger than 63 at MiFare 1k) ATE Authentication Error (i.e.
Sector Block Absolute Block Nr Funktion 15 3 63 Sector Trailer (Key A, access bits, Key B) 15 2 62 Data 15 1 61 Data 15 0 60 Data … … … … 0 3 3 Sector Trailer (Key A, access bits, Key B) 0 2 2 Data 0 1 1 Data 0 0 0 Data Table 14: Memory organization of the MiFare 1k chip (16 sectors á 4 blocks á 16 bytes (Sector 0 in Block 0 is the manufacturer block) Sector Block Funktion 32 to 39 15 Sector Trailer (Key A, Access, Key B) 32 to 39 14 Data 32 to 39 … … 32
one or both of the keys for each block. That means, that e.g. you can use Key A in your customer application which is only able to read the data, but use Key B in your internal application to initialize the cards with full write access. To identify the access rights for a sector there are three bits, called access bits C1, C2 and C3. With these three bits eight different modes are possible with these access bits. C1 is the LSB.
Block Mode 0: This is the transport configuration (delivery state). In this mode the block is readable and all data manipulating commands are enabled. But who is allowed to change the Block Mode itself? The sector trailer has its own access bits, where exactly this and some other details are configured. The set of access right stored in the trailer block is called „Access Mode“. Here you can configure whether Key A, Key B or the access bits are read/writeable.
7. Version Control Version Change by Date 1.0 created KD 11.3.
Contact / Support metraTec GmbH Werner-Heisenberg-Str. 1 D-39106 Magdeburg Tel.: +49 (0)391 251906-00 Fax: +49 (0)391 251906-01 Email: support@metratec.com Web: http://www.metratec.com Copyright © 2009 metraTec GmbH Nachdruck, Vervielfältigung oder Übersetzung dieser Benutzeranleitung, auch auszugsweise, sind ohne schriftliche Genehmigung der metraTec GmbH nicht gestattet. Alle Marken sind Eigentum ihrer jeweiligen Inhaber. Alle Rechte vorbehalten.