ACS ACR122U User manual

ACR122U
NFCReader
Application Programming Interface
Subject to change without prior notice
[email protected]
www.acs.com.hk

Table of Contents
1.0.Introduction ...............................................................................................................4
1.1.USB Interface ........................................................................................................................4
2.0.Implementation..........................................................................................................5
2.1.Communication Flow Chart of ACR122U ..............................................................................5
2.2.Smart Card Reader Interface Overview ................................................................................5
3.0.PICC Interface Description.......................................................................................6
3.1.ATR Generation.....................................................................................................................6
3.1.1.ATR format for ISO 14443 Part 3 PICCs ......................................................................6
3.1.2.ATR format for ISO 14443 Part 4 PICCs ......................................................................7
4.0.PICC Commands for General Purposes..................................................................8
4.1.Get Data.................................................................................................................................8
5.0.PICC Commands (T=CL Emulation) for Mifare Classic Memory Cards ...............9
5.1.Load Authentication Keys......................................................................................................9
5.2.Authentication ......................................................................................................................10
5.3.Read Binary Blocks .............................................................................................................13
5.4.Update Binary Blocks ..........................................................................................................14
5.5.Value Block Related Commands.........................................................................................14
5.5.1.Value Block Operation ................................................................................................14
5.5.2.Read Value Block........................................................................................................15
5.5.3.Restore Value Block....................................................................................................16
6.0.Pseudo-APDUs........................................................................................................18
6.1.Direct Transmit ....................................................................................................................18
6.2.Bi-Color LED and Buzzer Control........................................................................................18
6.3.Get the Firmware Version of the reader ..............................................................................20
6.4.Get the PICC Operating Parameter.....................................................................................20
6.5.Set the PICC Operating Parameter .....................................................................................20
7.0.Basic Program Flow for Contactless Applications..............................................22
7.1.How to Access PC/SC-Compliant Tags (ISO 14443-4)? ....................................................23
7.1.1.How to access Mifare 7-Byte UID Classic Tags .........................................................23
7.2.How to Access DESFire Tags (ISO 14443-4)? ...................................................................26
7.3.How to Access FeliCa Tags (ISO 18092)?..........................................................................27
7.4.How to Access NFC Forum Type 1 Tags (ISO 18092), e.g. Jewel and Topaz Tags?........27
7.5.Get the Current Setting of the Contactless Interface...........................................................30
Appendix A.ACR122U PC/SC Escape Command.........................................................31
Appendix B.APDU Command and Response Flow for ISO 14443-Compliant Tags..33
Appendix C.APDU Command and Response Flow for ISO 18092-Compliant Tags..34
Appendix D.Error Codes.................................................................................................35
Appendix E.Sample Codes for Setting the LED ...........................................................36
Figures
Figure 1:Communication Flow Chart of ACR122U.......................................................................... 5
Figure 2:Smart Card Reader Interface on the Device Manager...................................................... 5
Figure 3:Basic Program Flow for Contactless Applications...........................................................22
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 2 of 38
[email protected]
www.acs.com.hk

Tables
Table 1:USB Interface........................................................................................................................ 4
Table 2:ATR format for ISO 14443 Part 3 PICCs .............................................................................. 6
Table 3:ATR format for ISO 14443 Part 4 PICCs .............................................................................. 7
Table 4:Bi-Color LED and Buzzer Control Format (1 Byte) .............................................................19
Table 5:Current LED State (1 Byte) .................................................................................................19
Table 6:PICC Operating Parameter. Default Value = FF ................................................................ 21
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 3 of 38
[email protected]
www.acs.com.hk

1.0. Introduction
The ACR122U is a PC-linked contactless smart card reader/writer used for accessing ISO 14443-4
Type A and Type B, Mifare, ISO 18092 or NFC, and FeliCa tags. The ACR122U is PC/SC compliant
so it is compatible with existing PC/SC appli cations. Furthermore, the standard Microsoft CCID driver
is used to simplify driver installation.
The ACR122U serves as the intermediary device between the personal computer and the contactless
tag via the USB interface. The reader carries out the command from the PC whether the command is
used in orde r to commun icate with a conta ctless tag, or contro l the device perip herals (LED o r
buzzer).
The ACR122U uses the PC/SC APDUs for contactl ess tags following the PC/ SC Specification an d
makes use of pseudo APDUs in sending commands for ISO 18 092 tags and controlling the device
peripherals. This document will discuss the ACR122U can be used in your smart card system.
1.1. USB Interface
The ACR122U is connected to a computer throu gh USB as specified in the USB Specification 1.1.
The ACR122U is working in full-speed mode, i.e. 12 Mbps.
Pin Signal Function
1 VBUS +5 V power supply for the reader (Max. 200 mA, Normal 100 mA)
2 D- Differential signal transmits data between ACR122U and PC.
3 D+ Differential signal transmits data between ACR122U and PC.
4 GND Reference voltage level for power supply
Table 1: USB Interface
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 4 of 38
[email protected]
www.acs.com.hk

2.0. Implementation
2.1. Communication Flow Chart of ACR122U
The Standard Micro soft CCID and PC/SC drivers ar e used; thus, no ACS drivers are required
because the drivers are al ready built in side the wi ndows operating system. you’re the computer’s
registry settings can also be modified to be able to use the full capabilitie s of the ACR122 U NFC
Reader. See Appendix A for more details.
Figure 1: Communication Flow Chart of ACR122U
2.2. Smart Card Reader Interface Overview
Click on the “Devi ce Manager” to find out the “A CR122U PICC Interface”. The standard Microsoft
USB CCID Driver is used.
Figure 2: Smart Card Reader Interface on the Device Manager
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 5 of 38
[email protected]
www.acs.com.hk

3.0. PICC Interface Description
3.1. ATR Generation
If the reader detects a PICC, an ATR will be sent to the PC/SC driver for identifying the PICC.
3.1.1. ATR format for ISO 14443 Part 3 PICCs
Byte Value
(Hex) Designation Description
0 3B Initial Header
1 8N T0
Higher nibble 8 mean s: no TA1, TB1, TC1
only TD1 is following.
Lower nibble N is the nu mber of hist orical
bytes (HistByte 0 to HistByte N-1)
2 80 TD1
Higher nibble 8 mean s: no TA2, TB2, TC2
only TD2 is following.
Lower nibble 0 means T = 0
3 01 TD2
Higher nibble 0 mean s no TA3, TB3, TC3,
TD3 following.
Lower nibble 1 means T = 1
80 T1
Category indicator byte, 80 means A status
indicator may be pre sent in an optiona l
COMPACT-TLV data object
4F Application identifier Presence Indicator
0C Length
RID Registered Application Provider Ide ntifier
(RID) # A0 00 00 03 06
SS Byte for standard
C0 .. C1
Tk
Bytes for card name
4
To
3+N
00 00 00
00 RFU RFU # 00 00 00 00
4+N UU TCK Exclusive-oring of all the bytes T0 to Tk
Table 2: ATR format for ISO 14443 Part 3 PICCs
Example: ATR for MIfa re 1K = { 3B 8F 80 01 80 4F 0C A0 00 00 03 06 03 00 01 00 00
00 00 6A}
ATR
Initial
Header T0 TD1 TD2 T1 Tk Length RID Standard Card Name RFU TCK
3B 8F 80 01 80 4F 0C A0 00 00
03 06 03 00 01
00 00
00 00 6A
Where: Length (YY) =0C
RID =A0 00 00 03 06 (PC/SC Workgroup)
Standard (SS) = 03 (ISO14443A, Part 3)
Card Name (C0 .. C1) = [00 01] (MIFare 1K)
Where, Card Name (C0 .. C1)
00 01: Mifare 1K
00 02: Mifare 4K
00 03: Mifare Ultralight
00 26: MiFare Mini
….
F0 04: Topaz and Jewel
F0 11: FeliCa 212K
F0 12: Felica 424K
…FF [SAK]: Undefined
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 6 of 38
[email protected]
www.acs.com.hk

3.1.2. ATR format for ISO 14443 Part 4 PICCs
Byte Value
(Hex) Designation Description
0 3B Initial Header
1 8N T0
Higher nibble 8 means: no TA1, TB1, TC1
only TD1 is following.
Lower nibble N is the n umber of historica l
bytes (HistByte 0 to HistByte N-1)
2 80 TD1
Higher nibble 8 means: no TA2, TB2, TC2
only TD2 is following.
Lower nibble 0 means T = 0
3 01 TD2
Higher nibble 0 means no TA3, TB3, TC3,
TD3 following.
Lower nibble 1 means T = 1
XX T1
4
to
3 + N
XX
XX
XX Tk
Historical Bytes:
ISO14443A:
The historical bytes from ATS response. Refer
to the ISO14443-4 specification.
ISO14443B:
The higher layer response from the ATTRIB
response (ATQB). Refer to the ISO14443 -3
specification.
4+N UU TCK Exclusive-oring of all the bytes T0 to Tk
Table 3: ATR format for ISO 14443 Part 4 PICCs
We take for example, an ATR for DESFire which is:
DESFire (ATR) = 3B 86 80 01 06 75 77 81 02 80 00
ATR
ATS
Initial Header T0 TD1 TD2 T1 Tk TCK
3B 86 80 01 06 75 77 81 02 80 00
This ATR has 6 bytes of ATS which is: [06 75 77 81 02 80]
Note: Use the APDU “FF CA 01 00 00” to distinguish the ISO14443A-4 and ISO14443B-4
PICCs, and retrieve the full ATS if available. The ATS is retu rned for ISO 14443A-3 or
ISO14443B-3/4 PICCs.
Another example would be the ATR for ST19XRC8E which is:
ST19XRC8E (ATR) = 3B 8C 80 01 50 12 23 45 56 12 53 54 4E 33 81 C3 55
ATR
ATQB
Initial Header T0 TD1 TD2 T1 Tk TCK
3B 86 80 01 50 12 23 45 56 12 53 54 4E 33 81 C3 55
Since this card follows ISO 14443 Type B, the response would be ATQB which is 50 12 23 45 56 12
53 54 4E 33 81 C3 is 12 bytes long with no CRC-B
Note: You can refer to the ISO7816, ISO14443 and PC/SC standards for more details.
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 7 of 38
[email protected]
www.acs.com.hk

4.0. PICC Commands for General Purposes
4.1. Get Data
The “Get Data command” will return the serial number or ATS of the “connected PICC”.
Get UID APDU Format (5 Bytes)
Command Class INS P1 P2 Le
Get Data FF CA 00
01 00 00
(Full Length)
Get UID Response Format (UID + 2 Bytes) if P1 = 0x00
Response Data Out
Result UID
(LSB) UID (MSB) SW1 SW2
Get ATS of a ISO 14443 A card (ATS + 2 Bytes) if P1 = 0x01
Response Data Out
Result ATS SW1 SW2
Response Codes
Results SW1 SW2 Meaning
Success 90 00 The operation is completed successfully.
Error 63 00 The operation is failed.
Error 6A 81 Function not supported.
Example:
1. To get the serial number of the “connected PICC”
UINT8 GET_UID[5]={0xFF, 0xCA, 0x00, 0x00, 0x04};
2. To get the ATS of the “connected ISO 14443 A PICC”
UINT8 GET_ATS[5]={0xFF, 0xCA, 0x01, 0x00, 0x04};
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 8 of 38
[email protected]
www.acs.com.hk

5.0. PICC Commands (T=CL Emulation) for Mifare Classic
Memory Cards
5.1. Load Authentication Keys
The “Load Authentication Keys comm and” will load the authen tication keys into the rea der. The
authentication keys are used to authenticate the particular sector of the Mifare 1K/4K Memory Card.
Two kinds of authentication key locat ions are pr ovided, volatile and non-v olatile key locatio ns
respectively.
Load Authentication Keys APDU Format (11 Bytes)
Command Class INS P1 P2 Lc Data In
Load
Authentication
Keys FF 82 Key
Structure Key Number 06 Key
(6
bytes)
Where: Key Structure: 1 Byte.
0x00 = Key is loaded into the reader volatile memory.
Other = Reserved.
Key Number: 1 Byte).
0x00 ~ 0x01 = Key Location. Th e keys will disappear once the re ader is
disconnected from the PC.
Key: 6 Bytes.
The key value loaded into the reader. E.g. {FF FF FF FF FF FF}
Load Authentication Keys Response Format (2 Bytes)
Response Data Out
Result SW1 SW2
Response Codes
Results SW1 SW2 Meaning
Success 90 00 The operation is completed successfully.
Error 63 00 The operation is failed.
Example:
Load a key {FF FF FF FF FF FF} into the key location 0x00.
APDU = {FF 82 00 00 06 FF FF FF FF FF FF}
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 9 of 38
[email protected]
www.acs.com.hk

5.2. Authentication
The “Authentication command” uses the keys stored in the reader to do authentication with the Mifare
1K/4K card (PICC). Two types of authentication keys are used: TYPE_A and TYPE_B.
Load Authentication Keys APDU Format (6 Bytes) [Obsolete
Command Class INS P1 P2 P3 Data In
Authentication FF 88 00 Block Number Key
Type Key Number
Load Authentication Keys APDU Format (10 Bytes)
Command Class INS P1 P2 Lc Data In
Authentication FF 86 00 00 05 Authenticate Data Bytes
Authenticate Data Bytes (5 Bytes)
Byte1 Byte 2 Byte 3 Byte 4 Byte 5
Version
0x01 0x00 Block Number Key Type Key Number
Where:
Block Number: 1 Byte. This is the memory block to be authenticated.
Key Type: 1 Byte
0x60 = Key is used as a TYPE A key for authentication.
0x61 = Key is used as a TYPE B key for authentication.
Key Number: 1 Byte
0x00 ~ 0x1F = Key Location.
Note: For Mifare 1K Card, it has totally 16 sectors and each sector consists of 4 consecutive
blocks. E.g. Sector 0x00 consists of Blocks {0x00, 0x01, 0x02 and 0x03}; Sector 0x01
consists of Blocks {0x04, 0x05, 0x06 and 0x07}; the last sector 0x0F consists of Blocks
{0x3C, 0x3D, 0x3E and 0x3F}.
Once the authentication is done su ccessfully, there is no need to do the authe ntication again
provided that the blocks to be accessed are belonging to the same sector. Please refer to the
Mifare 1K/4K specification for more details.
Load Authentication Keys Response Format (2 Bytes)
Response Data Out
Result SW1 SW2
Response Codes
Results SW1 SW2 Meaning
Success 90 00 The operation is completed successfully.
Error 63 00 The operation is failed.
Document Title Here
Document Title Here Document Title Here
ACR122U NFC Reader API
Version 2.00
Page 10 of 38
[email protected]
www.acs.com.hk