OMNIKEY Contactless Smart Card Reader Developer

OMNIKEY Contactless Smart Card Reader Developer
OMNIKEY
Contactless Smart Card Readers
Developer Guide
5321-903, Rev. B.4
January 2015
hidglobal.com
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Contents
1
Purpose ................................................................................................................................................ 7
2
Contactless Reader Coverage ....................................................................................................... 7
3
Getting Started .................................................................................................................................. 8
3.1
Driver Installation.............................................................................................................................................................. 8
3.1.1
3.2
3.2.1
3.2.2
3.2.3
3.2.4
3.2.5
3.2.6
4
How to Access Contactless Cards through PC/SC ........................................................................................... 18
ATR Generation .............................................................................................................................................................. 20
4.2.1
4.2.2
CPU Cards ....................................................................................................................................................................................20
Storage Cards .............................................................................................................................................................................20
Accessing Asynchronous Cards ................................................................................................... 21
5.1
MIFARE DESFire Card ................................................................................................................................................... 21
5.1.1
5.1.2
6
PC/SC Functionality and Reader Availability ................................................................................................................ 12
Driver Version Detection ........................................................................................................................................................ 13
OMNIKEY Proprietary API Detection ................................................................................................................................ 13
Card and Reader Detection ................................................................................................................................................... 14
Card Type Detection and RFID Settings.......................................................................................................................... 16
Air Interface Baud Rate Configuration ............................................................................................................................. 17
PC/SC 2.0 ........................................................................................................................................... 18
4.1
4.2
5
Reader Name for Contact/Contactless Slot................................................................................................................... 12
OMNIKEY Workbench ................................................................................................................................................... 12
Example: Write Card Data through ISO 7816-4 Framed APDU ............................................................................. 21
Example: Read Card Data through ISO 7816-4 Framed APDU ............................................................................. 22
Accessing Synchronous Cards (Storage) ................................................................................. 23
6.1
MIFARE Card .................................................................................................................................................................... 23
6.1.1
6.1.2
6.1.3
6.1.4
6.2
Increment (Card Command) .............................................................................................................................. 24
Decrement (Card Command) ............................................................................................................................ 24
Emulation Mode ....................................................................................................................................................... 25
Application Directory (MAD) ............................................................................................................................. 25
iCLASS Card...................................................................................................................................................................... 26
6.2.1
6.3
MIFARE
MIFARE
MIFARE
MIFARE
Card Access through SCardCLICCTransmit .................................................................................................................. 26
ST LRI64 Support (PC/SC 2.0 add-on)................................................................................................................. 27
6.3.1
6.3.2
Update Binary ............................................................................................................................................................................. 28
Read Binary ................................................................................................................................................................................. 29
6.4 ISO15693-3 Memory Card Support ......................................................................................................................... 29
7
Communication with MIFARE Plus ............................................................................................. 30
7.1
7.2
7.3
7.4
ISO 14443 A – Part 4 card communication ........................................................................................................ 30
ISO 14443 A – Part 3 card communication......................................................................................................... 30
Open Generic Session .................................................................................................................................................... 31
Generic Card Commands ............................................................................................................................................. 31
7.4.1
7.5
8
Key Numbering Scheme .............................................................................................................................................. 33
Key Container and Slots .............................................................................................................................................. 35
Key Update Rules ...........................................................................................................................................................36
Standard Communication with iCLASS Card .......................................................................... 37
9.1
9.2
January 2015
Close Generic Session................................................................................................................................................... 32
OMNIKEY Contactless Smart Card Reader Keys .................................................................... 33
8.1
8.2
8.3
9
MIFARE Plus commands with the GENERIC INTERFACE Command APDU Samples ................................ 32
APDU Structure for Standard Communication.................................................................................................. 37
Commands Available in Standard Communication Mode ............................................................................ 37
Page 2 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9.2.1
9.2.2
9.2.3
9.2.4
9.2.5
9.2.6
9.3
Select Page (Card Command)............................................................................................................................................. 38
Load Key ....................................................................................................................................................................................... 39
GetKeySlotInfo (Reader Command).................................................................................................................................. 41
Authenticate (Card Command) .......................................................................................................................................... 42
Read (Card Command) ..........................................................................................................................................................43
Update (Card Command)......................................................................................................................................................44
Communication in Standard Mode .........................................................................................................................45
10 Secured Communication with the iCLASS Card ..................................................................... 46
10.1 Multi-Step Approach to a Secure Card Reader System ............................................................................... 46
10.1.1
10.1.2
10.1.3
10.1.4
10.1.5
10.1.6
10.1.7
10.1.8
Authenticity between Host and Reader ..........................................................................................................................46
Confidentiality of USB Data Exchange ............................................................................................................................46
Integrity of Transmitted Data ..............................................................................................................................................46
Authenticity between Reader and Card .........................................................................................................................46
Integrity of the Radio Frequency (RF) Transmission ................................................................................................46
Confidentiality of the RF Transmission ........................................................................................................................... 47
Authentication of the Host for Read/Write Session .................................................................................................. 47
Protection against Known Attacks.................................................................................................................................... 47
10.2 APDU Structure for Secured Communication................................................................................................... 48
10.2.1
10.2.2
10.2.3
10.2.4
Data Header (DH) .....................................................................................................................................................................49
Signature Generation ..............................................................................................................................................................49
Session Key Generation .........................................................................................................................................................49
Proprietary Host and Reader Datagram Example ......................................................................................................50
10.3 Instructions (INS) for Secured Communication ................................................................................................. 51
10.3.1
10.3.2
10.3.3
10.3.4
10.3.5
10.3.6
10.3.7
10.3.8
Manage Session (Reader Command) ................................................................................................................................ 51
Select Page (Card Command)............................................................................................................................................. 52
Load Key (Reader Command) ............................................................................................................................................ 52
Authenticate (Card Command) .......................................................................................................................................... 52
Read (Card Command) .......................................................................................................................................................... 52
Update (Card Command)...................................................................................................................................................... 52
GetKeySlotInfo (Reader Command)................................................................................................................................. 52
Update Card Key ....................................................................................................................................................................... 53
10.4 Communication at Secured Mode ...........................................................................................................................54
10.5 Session at Secured Mode APDUs Example ......................................................................................................... 55
11
Reading ISO15693 ........................................................................................................................... 58
11.1 Products ............................................................................................................................................................................. 58
11.2 Tags ...................................................................................................................................................................................... 58
11.3 Commands.........................................................................................................................................................................59
11.3.1
11.3.2
11.3.3
11.3.4
11.3.5
11.3.6
11.3.7
Get Data ........................................................................................................................................................................................ 59
Put Data ....................................................................................................................................................................................... 60
Lock ................................................................................................................................................................................................. 61
Get Security Status .................................................................................................................................................................. 62
Read Binary Command...........................................................................................................................................................64
Update Binary Command ...................................................................................................................................................... 65
Update Single Byte Command ............................................................................................................................................66
12 OMNIKEY 5321 PAY Application Interface ............................................................................... 67
12.1 PayPass Card Transactions ........................................................................................................................................ 67
12.2 LED and Buzzer Control .............................................................................................................................................. 67
12.2.1
12.2.2
12.2.3
12.2.4
SIGNAL Command – PayPass Signal ................................................................................................................................ 68
SIGNAL Command – PayPass Signal MAIN LED ......................................................................................................... 68
SIGNAL Command – PayPass Signal Additional LEDs ............................................................................................. 69
SIGNAL Command – PayPass Signal Tone .................................................................................................................... 69
12.3 Switch-over the Operating Mode ........................................................................................................................... 70
Page 3 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
13 Driver Configuration via ProxFormat ......................................................................................... 71
13.1 Overview ............................................................................................................................................................................. 71
13.2 ATR Format ........................................................................................................................................................................ 71
13.2.1
ATR Example ............................................................................................................................................................................... 71
13.3 Available ProxFormat Settings ................................................................................................................................. 72
13.3.1 ProxFormat Settings on Systems Running Windows ............................................................................................... 73
13.3.2 ProxFormat Settings on Systems Running Linux and MacOS X .......................................................................... 73
14 ProxFormat Settings ...................................................................................................................... 74
14.1
14.2
14.3
14.4
Wiegand Raw Data Mode ...........................................................................................................................................74
Standard Format Modes ..............................................................................................................................................74
Automatic Mode..............................................................................................................................................................74
Custom Format Mode ................................................................................................................................................... 75
14.4.1 CustomProxFormat Settings ............................................................................................................................................... 75
14.5 Example: H10301 PROX Card .................................................................................................................................... 76
14.5.1
14.5.2
14.5.3
14.5.4
Standard Format ....................................................................................................................................................................... 76
Wiegand Raw Data................................................................................................................................................................... 76
CustomProxFormat Settings ............................................................................................................................................... 76
ATRs of a H10301 Card ........................................................................................................................................................... 76
14.6 Example: H10302 PROX Card ................................................................................................................................... 77
14.6.1
14.6.2
14.6.3
14.6.4
Standard Format ....................................................................................................................................................................... 77
Wiegand Raw Data................................................................................................................................................................... 77
CustomProxFormat Settings ............................................................................................................................................... 77
ATRs of a H10302 Card .......................................................................................................................................................... 77
14.7 Example: H10304 PROX Card ................................................................................................................................... 78
14.7.1
14.7.2
14.7.3
14.7.4
Standard Format ....................................................................................................................................................................... 78
Wiegand Raw Data................................................................................................................................................................... 78
CustomProxFormat Settings ............................................................................................................................................... 78
ATRs of a H10304 Card .......................................................................................................................................................... 78
14.8 Example: Corp 1000 PROX Card ............................................................................................................................. 79
14.8.1
14.8.2
14.8.3
14.8.4
January 2015
Standard Format ....................................................................................................................................................................... 79
Wiegand Raw Data................................................................................................................................................................... 79
CustomProxFormat Settings ............................................................................................................................................... 79
ATRs of a Corp 1000 Card .................................................................................................................................................... 79
Page 4 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Copyright
©2011 - 2015 HID Global Corporation/ASSA ABLOY AB. All rights reserved. This document
may not be reproduced, disseminated or republished in any form without the prior written
permission of HID Global Corporation.
Trademarks
HID GLOBAL, HID, the HID logo, iCLASS, iCLASS Elite, OMNIKEY, and Seos are the
trademarks or registered trademarks of HID Global Corporation, or its licensors, in the U.S.
and other countries.
MIFARE, MIFARE DESFire, MIFARE DESFire EV1, and MIFARE Ultralight are registered
trademarks of NXP B.V. and are used under license.
my-d is a registered trademark of Infineon Technologies
PayPass is a registered trademark of MasterCard
Document History
Page 5 of 102
Version
Author(s) Date
Description
B.4
CT
2014-01-20
OMNIKEY 5421, reformat.
B.3
J. Maatuq
2012-03-23
- Corrected product name •OMNIKEY 5321 Pay ->
OMNIKEY 5321 PAY
- Some layout changes
- typo corrections
B.2
J. Maatuq
2012-02-09
Added new products 4121 CL, 5021 CL, 5321 CLi, 5321 Pay,
5325 Prox
Added new products and documented Workbench
Added Driver Configuration via ProxFormat and
ProxFormat Settings section
B.1
W Waitz
2010-11-10
Added iCLASS Elite enabled readers. Modified section
10.3.4 Get Security Status
B.0
W Waitz
2010-08-05
MIFARE Plus, PAY API and Review
A.1.19
S Schwab 2009-07-17
Chapter 9, supported tags
A.1.18
S Schwab 2009-07-16
Added footnotes for iCode SL2
A.1.17
W Waitz
2009-05-13
Review to version 1.16 and error correction
A.0
T Muth
2009-02-16
Updated to HID template
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Firmware History
FW Version
Special Features
Remarks
5.20, 1.75
MIF, MKS, IST, ISE, EMD,
HSK,
iCLASS secured mode, HID application read,
iCLASS High Security Key supported,
EMD Suppression in firmware supported,
EMVCo Contactless L1
5.10
MIF, MKS, IST, ISE
iCLASS secured mode, HID application read
5.00
MIF, MKS, IST, ISE
iCLASS secured mode, HID application read
1.03, 1.04
MIF, MKS, IST
iCLASS memory access
1.01, 1.02
MIF, MKS
1.00
MIF
MIFARE support
Synchronous Card Special Features
MIF
= MIFARE Functionalities
MKS = MIFARE Key Storage
MSK = MIFARE Secured Key Loading
IST
= iCLASS Standard Mode Communication
ISE
= iCLASS Secured Mode Communication
EMD = Electromagnetic Disturbance
HSK = High Security Key
Contacts
For additional offices around the world, see www.hidglobal.com corporate offices.
Americas & Corporate
Asia Pacific
611 Center Ridge Drive
Austin, TX 78753
USA
Phone:
866-607-7339
Fax:
949-732-2120
19/F 625 King’s Road
North Point, Island East
Hong Kong
Phone:
852 3160 9833
Fax:
852 3160 4809
Europe, Middle East and Africa
Brazil
Phoenix Road
Haverhill, Suffolk CB9 7AE
England
Phone:
+44 1440 711 822
Fax:
+44 1440 714 840
Condomínio Business Center
Av. Ermano Marchetti, 1435
Galpão A2 CEP 05038001
Lapa - São Paulo/SP
Brazil
Phone:
55 11 5514-7100
HID Global Customer Support: support.hidglobal.com
January 2015
Page 6 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
1
Purpose
This is a guide for developers integrating contactless storage or CPU cards using
®
OMNIKEY Contactless Smart Card readers.
2 Contactless Reader Coverage
The following OMNIKEY contactless readers are covered by this document:
• OMNIKEY 4121 CL
Mobile Smart Card including an Express Card interface with the same functionality as
OMNIKEY 5321, but it has a contactless interface.
• OMNIKEY 5021 CL
Desktop reader in a closed small housing with the same functionality as the OMNIKEY
5321, but a contactless-only reader.
• OMNIKEY 5321
Desktop Smart Card reader with contact and contactless interface, contactless
interface featuring full contactless functionality as described in this developers guide.
• OMNIKEY 5321 CL
Desktop reader in a closed housing, same functionality as OMNIKEY 5321 but
contactless-only reader.
• OMNIKEY 5321 CR
Desktop reader in a waterproof (Clean Room) closed housing, same functionality as
OMNIKEY 5321 but contactless-only reader.
• OMNIKEY 5321 CLi
Desktop Smart Card reader in a closed housing, with contactless-only interface.
Contactless interface supports iCLASS-only.
• OMNIKEY 5321 PAY
Desktop reader in a closed housing, same functionality as OMNIKEY 5321. Has EMVCo
Terminal Level 1 approval according to EMV 2.0 specification [EMVCo].
• OMNIKEY 5325 Prox
Desktop Smart Card reader with contact and contactless interface. Contactless
interface features operating on 125 kHz (Prox). Section 3 PC/SC 2.0 is applicable for
this reader.
• OMNIKEY 5421
Desktop Smart Card reader with contact and contactless interface. The functionality
is the same as the OMNIKEY 5321, but it uses a different transceiver chip.
• OMNIKEY 6321
Mobile Smart Card reader with SIM-sized contact and contactless interface.
Contactless interface features full contactless functionality.
• OMNIKEY 6321 CLi
Mobile Smart Card reader with contactless-only interface. Contactless interface
supports iCLASS only.
• Readers with iCLASS Elite Key
All enabled iCLASS Elite Key readers (list previously) are covered by this document.
All readers listed are based on the OMNIKEY Contactless Smart Card RFID chipset.
Therefore this document uses the term 5x21 to reference these OMNIKEY readers.
Page 7 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3 Getting Started
This chapter describes how to install the drivers necessary to operate the OMNIKEY
Contactless Smart Card reader in a Windows based environment.
Note: Other operating systems, such as Linux, are also supported by the OMNIKEY
Contactless Smart Card reader.
3.1
Driver Installation
The OMNIKEY Contactless Smart Card driver is mandatory for all systems that require
support for contactless smart cards.
OMNIKEY Contactless Smart Card reader is a CCID compliant device. This means that the
contact interface can be operated without an OMNIKEY proprietary driver installed.
However, for contactless cards, the OMNIKEY proprietary OMNIKEY Contactless Smart
Card driver is necessary.
The following steps describe how to install the OMNIKEY Contactless Smart Card driver:
1.
Go to http://www.hidglobal.com/omnikey. Based on the appropriate reader, click the
driver icon. Download the latest OMNIKEY Contactless Smart Card driver installation
package for Windows.
2. Run the installation package and follow the instructions. The installation package
extracts all the necessary driver files to your hard drive. Take note of the location to
which the files were copied.
3. Connect the reader to your computers USB port. At this time you have only
extracted, not installed the driver files.
4. The Found New Hardware Wizard appears. To continue driver installation, click Next.
Note: On Windows XP systems, the Microsoft Windows CCID Class driver may be
activated without showing the Found New Hardware Wizard. If this is the case,
replace the Microsoft PC/SC driver manually with the OMNIKEY proprietary PC/SC
driver using the Device Manager.
January 2015
Page 8 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
5. Select Search for a suitable driver for my device (recommended) and click Next.
6. Then, select Specify a Location and click Next.
Page 9 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
7. Click Browse and go to the location where you previously installed the driver
package. To continue, click OK.
8. If the driver was found, click Next.
January 2015
Page 10 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9. If the driver is a beta driver and not digitally signed, the following dialogue appears.
Click Continue Anyway.
10. The following message appears and the green LED illuminates on the OMNIKEY
Contactless Smart Card reader.
If the installation was successful, the green LED on the reader illuminates and the
reader is listed in the OMNIKEY Workbench as OMNIKEY Contactless Smart Card
reader.
Your reader is ready for use. Do a quick smart card system check using the OMNIKEY
Workbench described in Section 3.2 OMNIKEY Workbench.
Page 11 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3.1.1
Reader Name for Contact/Contactless Slot
The OMNIKEY Contactless Smart Card reader is a dual slot reader. This means that from
the application and smart card resource manager viewpoint there are two readers
available, each represented by its respective reader name. OMNIKEY CardMan 5x21 n
identifies the contact slot and OMNIKEY CardMan 5x21-CL n stands for the contactless slot.
The n represents a slot number 0, 1… etc. This allows card tracking through the contact and
air interface.
3.2 OMNIKEY Workbench
The OMNIKEY Workbench provides a quick test of the smart card system. It lists all
available OMNIKEY readers, driver files with version, firmware version, and allows the
configuration of the RFID/air interface.
Go to http://www.hidglobal.com/omnikey > select the OMNIKEY Reader > click the driver
icon to download the latest OMNIKEY Workbench for Windows.
Start former versions of the Diagnostic Tool from the Control Panel.
3.2.1
PC/SC Functionality and Reader Availability
The General Information application shows in the PC/SC Functionality tab if the Resource
Manager is running and lists all connected OMNIKEY readers.
Figure 1: PC/SC Functionality
January 2015
Page 12 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3.2.2
Driver Version Detection
In addition, the File Versions tab shows smart card system services version, manufacturer
data and driver files.
Figure 2: File Version
3.2.3
OMNIKEY Proprietary API Detection
The API tab shows the APIs installed on your system, including the OMNIKEY Synchronous
API.
Figure 3: API
Page 13 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3.2.4
Card and Reader Detection
The OMNIKEY Workbench creates a separate entry for each available OMNIKEY reader
interface in the application table. The entries indicate their respective reader names - the
same names you use within the PC/SC framework. Click an entry to open the reader’s
information and settings.
For a quick connectivity test of your contactless card,
1.
Select the OMNIKEY CardMan 5x21-CL 0 tab
2. Place a contactless card on the reader.
3. When the card is detected, the Status field switches from No smart card inserted to
Smart card inserted and the ATR field displays the card’s ATR.
See Section 4.2 ATR Generation, for further information on how the Answer to Reset (ATR)
is generated for contactless smart cards.
The OMNIKEY Workbench has an internal flat database that allows a quick lookup of the
ATR. If it is a known card, a description displays in the Smart Card Name field. For
contactless cards the card’s unique ID (UID) displays in the Smart Card Name field and in
the Protocol field the card standard for example, T=CL and the selected baud rate displays.
Figure 4: Reader View - No Smart Card
January 2015
Page 14 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Figure 5: Reader View - Smart Card Inserted
Page 15 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3.2.5
Card Type Detection and RFID Settings
OMNIKEY Contactless Smart Card reader supports multiple 13.56 MHz contactless
standards and protocols including ISO14443A, ISO14443B, ISO15694, iCLASS, I-CODE.
Acquire information about a card within the RFID field in a predefined search order. With
built-in anti-collision, once a card is detected it is the only card in which the reader is
connected.
The OMNIKEY Workbench has a RFID Settings tab within the reader view that allows
configuration of the reader card and their respective search order. See Section 3.2.4 Card
and Reader Detection.
Figure 6: RFID Settings
The left pane contains a list of active card types. The right pane contains a list of available
card types that are supported by the reader but are not included in the card search. Move
card types from the left to the right pane using the
and
buttons. Change the search
order with the
and
buttons.
Activate this setting using the Apply button. The Reset button discards any unsaved
changes.
Note: The search order is forward-looking to improve system performance. The last
successfully detected card type automatically moves to the top of the search order,
regardless of its position within the order set on the RFID Settings tab.
January 2015
Page 16 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3.2.6
Air Interface Baud Rate Configuration
For ISO 14443 cards, the air interface transmission speed can be 106 kbps, 212 kbps, 424
kbps, or 848 kbps. By default, the contactless interface is set to 424 kbps. Change the
interface transmission speed to a different value through the OMNIKEY Workbench
Baudrate settings tab.
Figure 7: RFID Settings
To view or change the baud rate, select the card type (ISO14443A or ISO14443B) and
change the maximum Baud Rate field. Finalize your setting, click Apply.
Figure 8: Baud Rate Settings
Page 17 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
4 PC/SC 2.0
With the OMNIKEY 5x21 PC/SC driver, access ISO14443A/B or ISO15693 contactless cards
through the same framework as ISO7816 contact cards. This makes card integration a snap
for any developer who is already familiar with PC/SC. Even valuable PC/SC resource
manager functions, such as card tracking, are available for contactless card integration.
®
®
The Microsoft Developer Network (MSDN ) Library contains valuable information and a
complete documentation of the SCard API within the MSDN Platform SDK.
See http://msdn.microsoft.com/en-us/library/ms953432.aspx.
You can directly access contactless CPU cards through the PC/SC driver. For storage cards
®
other than MIFARE , an additional library – the OMNIKEY synchronous API – is necessary.
Whether using direct PC/SC access or the OMNIKEY synchronous API, only a small set of
functions are required to write your first hello card program.
Integrate your card through:
PC/SC 2.0 compliant APDU’s
OMNIKEY Synchronous API
MIFARE
YES
YES
iCLASS
NO
YES
LRI64
YES
NO
4.1 How to Access Contactless Cards through PC/SC
The following steps provide a guideline to create your first contactless smart card
application using industry standard, PC/SC compliant API function calls. The function
definitions provided are taken verbatim from the MSDN Library [MSDNLIB]. For additional
descriptions of these and other PC/SC functions provided by the Microsoft Windows
PC/SC smart card components, refer directly to the MSDN Library. See
http://msdn.microsoft.com/en-us/library/ms953432.aspx.
1.
Establish Context
This step initializes the PC/SC API and allocates all resources necessary for a smart
card session. The SCardEstablishContext function establishes the resource manager
context (scope) within which database operations is performed.
LONG SCardEstablishContext( IN DWORD dwScope,
IN LPCVOID pvReserved1,
IN LPCVOID pvReserved2,
OUT LPSCARDCONTEXT phContext);
2. Get Status Change
Check the status of the reader for card insertion, removal, or availability of the reader.
This SCardGetStatusChange function blocks execution until the current availability of
the cards in a specific set of readers change. The caller supplies a list of monitored
readers and the maximum wait time (in milliseconds) for an action to occur on one of
the listed readers.
LONG SCardGetStatusChange( IN
IN
IN
IN
January 2015
SCARDCONTEXT hContext,
DWORD dwTimeout,
OUT LPSCARD_READERSTATE rgReaderStates,
DWORD cReaders);
Page 18 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3. List Readers
Gets a list of all PC/SC readers using the SCardListReaders function. Look for
OMNIKEY CardMan 5x21-CL 0 in the returned list. If multiple OMNIKEY Contactless
Smart Card readers are connected to your system, they will be enumerated.
Example: OMNIKEY CardMan 5x21-CL 1, and OMNIKEY CardMan 5x21-CL 2.
Analyze the complete string. OMNIKEY CardMan 5x21 also has a contact interface.
Look for -CL in the reader name to ensure you are referring to the contactless
interface in the following calls.
LONG SCardListReaders( IN SCARDCONTEXT hContext,
IN LPCTSTR mszGroups,
OUT LPTSTR mszReaders,
IN OUT LPDWORD pcchReaders);
4. Connect
Connect to the card. The SCardConnect function establishes a connection (using a
specific resource manager context) between the calling application and a smart card
contained by a specific reader. If no card exists in the specified reader, an error is
returned.
LONG SCardConnect( IN SCARDCONTEXT hContext,
IN LPCTSTR szReader,
IN DWORD dwShareMode,
IN DWORD dwPreferredProtocols,
OUT LPSCARDHANDLE phCard,
OUT LPDWORD pdwActiveProtocol);
5. Exchange Data and Commands with the Card
Exchange command and data through APDUs. The SCardTransmit function sends a
service request to the smart card, expecting to receive data back from the card.
LONG SCardTransmit( IN SCARDHANDLE hCard,
IN LPCSCARD_I0_REQUEST pioSendPci,
IN LPCBYTE pbSendBuffer,
IN DWORD cbSendLength,
IN OUT LPSCARD_IO_REQUEST pioRecvPci,
OUT LPBYTE pbRecvBuffer,
IN OUT LPDWORD pcbRecvLength);
Note: For unsupported PC/SC 2.0 storage cards, call an OMNIKEY proprietary API
function such as SCardCLICCTransmit instead. This function exposes additional
functionality of the OMNIKEY 5x21-CL reader that is not yet defined in PC/SC
standards. Otherwise, you are still using the standard PC/SC framework to track
cards, list readers, etc. Even the smart card handle is the same.
6. Disconnect
It is not necessary to disconnect the card after the completion of transactions, but it
is recommended. The SCardDisconnect function terminates a connection previously
opened between the calling application and a smart card in the target reader.
LONG SCardDisconnect( IN SCARDHANDLE hCard,
IN DWORD dwDisposition);
7. Release
This step ensures all system resources are released. The SCardReleaseContext
function closes an established resource manager context, freeing any resources
allocated under that context.
LONG SCardReleaseContext( IN SCARDCONTEXT hContext);
Page 19 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
4.2 ATR Generation
Unlike contact cards, contactless cards do not generate an ATR. Instead, they generate an
Answer to Select (ATS). To make contactless cards available within the PC/SC framework,
OMNIKEY Contactless Smart Card reader generates a PC/SC compliant ATR according to
PC/SC v2.01.
Download the documents from the PC/SC Workgroup at the following web address:
http://www.pcscworkgroup.com/specifications/specdownload.php.
4.2.1
CPU Cards
Contactless smart cards (cards with a CPU) expose their ATS or information bytes through
ATR mapping according to PC/SC 2.01 - Part 3: Requirements for PC-Connected Interface
Devices, section 3.1.3.2.3.1 Contactless Smart Cards, Table 3.5.
4.2.2
Storage Cards
The ATR of storage cards (for example, cards without a CPU) is composed as described in
PC/SC 2.01 - Part 3: Requirements for PC-Connected Interface Devices, section 3.1.3.2.3.2
Contactless Storage Cards, Table 3.6. For the host application to identify a storage and
card type properly, its standard and card name is mapped according to PC/SC 2.01 - Part 3:
Requirements for PC-Connected Interface Devices - Supplemental Document.
Note: The Registered Application Provider Identifier (RID) returned by the OMNIKEY
Contactless Smart Card reader for storage cards (cards without a CPU) is A0 00 03 06 0A,
indicating a PC/SC compliant ATR generation.
January 2015
Page 20 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
5 Accessing Asynchronous Cards
Asynchronous cards contain a CPU or are memory cards accessible through standard
PC/SC using Microsoft’s library winscard.dll. This type of card supports at least one of the
asynchronous protocols T=0 or T=1. The Microsoft Platform SDK contains PC/SC sample
code for Visual C/C++ and Visual Basic.
No additional libraries or third-party software components are necessary to integrate
contactless CPU cards.
5.1
MIFARE DESFire Card
MIFARE DESFire cards are accessed through ISO7816-4 compliant framed APDU
commands (ISO7816-4 framing).
New versions of MIFARE DESFire EV1 cards support extended APDU commands. For this
the driver must switch to MIFARE DESFire native mode. This native mode is not default for
the OMNIKEY Contactless Smart Card reader. For proper protocol settings use the
following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\RFID
DesfireNative=0x00000001
Note: Restart the OMNIKEY Contactless Smart Card driver after changing the registry key
(disconnect and reconnect the reader).
5.1.1
Example: Write Card Data through ISO 7816-4 Framed APDU
Command Syntax
CLA
INS
P1
P2
Lc
File No.
Offset
Length
Data
Le
‘90’
‘3D’
‘00’
‘00’
‘xx’
‘xx’
‘xxxxxx’
‘xxxxxx’
‘xx’ … ‘xx’
‘00’
Lc = 7+ DataLength; Le=0 (no other values accepted)
Response Syntax
Response Data
SW1
SW2
empty
‘xx’
‘xx’
Status Codes
Page 21 of 102
SW1
SW2
Description
'90'
'00'
success
'91’
'xx
error (see the MIFARE DESFire data sheet)
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
5.1.2
Example: Read Card Data through ISO 7816-4 Framed APDU
Command Syntax
CLA
INS
P1
P2
Lc
File No.
Offset
Length
Data
Le
‘90’
‘BD’
‘00’
‘00’
‘07’
‘xx’
‘xxxxxx’
‘LLLLLL’
empty
‘00’
Le=0 (no other values accepted)
Response Syntax
Response Data
SW1
SW2
‘xx’ ... ‘xx’ (‘LLLLLL’ bytes)
‘xx’
‘xx’
Status Codes
January 2015
SW1
SW2
Description
'90'
'00'
success
'91’
'xx
error (see to the MIFARE DESFire data sheet)
Page 22 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
6 Accessing Synchronous Cards (Storage)
OMNIKEY provides two ways to integrate contactless storage cards. One option is
OMNIKEY’s proprietary synchronous API library, or for MIFARE cards, directly through
PC/SC 2.0 compliant function calls. Access storage cards not supported through PC/SC 2.0
compliant APDU exchanges through OMNIKEY proprietary synchronous API.
The synchronous API for Windows systems resides in a DLL named scardsyn.dll. Download
the Synchronous API for OMNIKEY Contactless Smart Card readers from
www.hidglobal.com/omnikey and execute the setup
CardMan_Synchronous_API_V2_0_0_0.exe. The setup includes this DLL. The download
also contains sample code for MIFARE and iCLASS cards. For information about this API,
reference the help file cmsync.hlp available in the c:\Program Files\HID Global\SyncAPI\Help folder after installation of the synchronous API with default settings.
The OMNIKEY Synchronous API is used whenever a card has not yet found its way into the
PC/SC 2.0 standard. Currently, only MIFARE cards can be integrated through PC/SC 2.0
compliant APDU.
Integrate Card through
PC/SC 2.0 compliant APDUs
OMNIKEY Synchronous API
MIFARE
Yes
Yes
iCLASS
No
Yes
No special drivers are required for PC/SC 2.0 compliant card integration with Windows or
Linux. OMNIKEY’s latest drivers provide seamless cross-platform support allowing industry
standard-compliant contactless card integration.
6.1
MIFARE Card
OMNIKEY Contactless Smart Card readers support MIFARE Mini, MIFARE 1K, MIFARE 4K
®
and MIFARE Ultralight cards.
The following functions are supported through PC/SC:
GetUID
LoadKey
Authenticate
Verify
Implemented according to [PCSC 2.01]
Update Binary
Read Binary
Increment
OMNIKEY proprietary extension of PC/SC
Decrement
OMNIKEY proprietary extension of PC/SC
MIFARE Emulation Mode
OMNIKEY proprietary extension of PC/SC
CM_IOCTL_SET_RFID_CONTROL_FLAGS
Reference the [PCSC 2.01] and [MIFARE] for documentation of PC/SC 2.0 compliant
MIFARE card access. The following section only describes usage of functions that are not
already documented in [PCSC 2.01]. They are part of an OMNIKEY proprietary extension of
PC/SC.
Page 23 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
6.1.1
MIFARE Increment (Card Command)
This command increments the value of a block, if the card and block supports this
functionality:
Command Syntax
CLA
‘FF’
INS
‘D4’
P1
MSB of block address
P2
LSB of block address
LC
4
Data Field
Four bytes value indicating block increment (LSB first)
Le
empty
Response Syntax
Data Field
6.1.2
Empty
SW1
SW2
status word as described below
‘90’
‘00’
Success
'65'
‘81’
memory failure (unsuccessful increment)
‘69’
‘81’
incompatible command
‘69’
‘82’
security status not satisfied
‘69’
‘86’
command not allowed
‘6A’
‘81’
function not supported
‘6A’
‘82’
invalid block address
MIFARE Decrement (Card Command)
This command decrements the value of a block, if the card and block support this
functionality:
Command Syntax
CLA
‘FF’
INS
‘D8’
P1
MSB of block address
P2
LSB of block address
LC
4
Data Field
Four byte value indicating block decrement (LSB first)
Le
Empty
Response Syntax
Data Field
January 2015
Empty
SW1
SW2
status word as described below
‘90’
‘00’
Success
'65'
‘81’
memory failure (unsuccessful decrement)
‘69’
‘81’
incompatible command
‘69’
‘82’
security status not satisfied
‘69’
‘86’
command not allowed
‘6A’
‘81’
function not supported
‘6A’
‘82’
invalid block address
Page 24 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
6.1.3
MIFARE Emulation Mode
By default, the OMNIKEY Contactless Smart Card driver exposes standard MIFARE storage
cards through a PC/SC 2.01 compliant interface. This driver-level MIFARE emulation mode
makes standard MIFARE cards available through standard APDUs even though the card
itself does not support any asynchronous protocols supported directly by native PC/SC
components.
Dual-interface cards work differently. Their CPU supports communication through
ISO14443A part 4 (T=CL) allowing on-card MIFARE emulation rather than host-side
MIFARE emulation. This means that OMNIKEY Contactless Smart Card reader’s default
mode (for example, host-side MIFARE emulation) must be disabled to support the on-card
MIFARE emulation of a dial-interface card.
There are two ways to switch between host-side and card-side MIFARE emulation:
1.
Registry keys
2. IO controls using the PC/SC function ScardControl() as described in Appendix A2.8
MIFARE Emulation Mode (OMNIKEY Proprietary API).
The following registry keys let you switch between OMNIKEY MIFARE emulation mode
(default) and on-card MIFARE emulation.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\RFID
ControlFlags=0x00000004
OMNIKEY’s host-side MIFARE emulation ON
default
ControlFlags=0x00000000 OMNIKEY’s host-side MIFARE emulation OFF
T=CL, for on-card MIFARE emulation
Note: Restart the OMNIKEY Contactless Smart Card driver after changing the registry keys
(disconnect and then reconnect the reader).
6.1.4
MIFARE Application Directory (MAD)
To access the MIFARE Application Directory (MAD), two commands are necessary –
Authenticate and Read. The following steps describe how to retrieve a MAD from a
MIFARE card:
1.
Authenticate block 3 with the Public key A0A1A2A3A4A5 and authentication mode
A.
2. Read Block 3.
3. Read Block 2.
4. Read Block 1.
For information about the block content see:
http://www.nxp.com/acrobat_download2/other/identification/,001830.pdf
http://www.mifare.net
Page 25 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
6.2 iCLASS Card
Only access iCLASS cards through OMNIKEY’s proprietary scardsyn API. This synchronous
API contains a function that is dedicated to accessing contactless cards using the standard
PC/SC card handle.
OMNIKEY Contactless Smart Card readers expose all iCLASS functions necessary to access
any of the application areas on an iCLASS card. The two modes of communication
supported are:
1.
Standard mode communication
2. Secured mode communication (OMNIKEY proprietary mode)
Note: OMNIKEY Contactless Smart Card readers do not allow WRITE access to the HID
application (1st application on page 0). For READ access to the HID application, secured
communication (available for firmware version 5.00 and greater) is mandatory.
Note: Standard readers provide secured mode communication only between standard HID
iCLASS. However, there is also a possibility for secured mode communication between HID
iCLASS Elite cards (available for firmware version 5.20 and greater). For details, contact
your local Sales Representative.
6.2.1
Card Access through SCardCLICCTransmit
SCardCLICCTransmit is the OMNIKEY proprietary function to access HID iCLASS cards
through the OMNIKEY synchronous API. It supports both, standard and secure
communication modes and is defined as follows:
OKERR
IN
IN
IN
IN
ENTRY SCardCLICCTransmit (
IN SCARDHANDLE ulHandleCard,
PUCHAR
pucSendData,
ULONG
ulSendDataBufLen,
OUT PUCHAR pucReceivedData,
OUT PULONG pulReceivedDataBufLen );
Parameter
Description
ulHandleCard
handle to the card, provided from the PC/SC smart card resource
manager after connecting to the card with SCardConnect
pucSendData
buffer for data sent to the reader/card, typically a command APDU
ulSendDataBufLen
length of the data to be sent
pucReceivedData
buffer for data received from reader/card, typically data and status
pulReceivedDataBufLen
before the call: length (in bytes) of the receive buffer
after the call: number of bytes actually received
Command Syntax
***
CLA
INS
P1
P2
Lc
Input Data or Datagram
Le
‘8x’
‘xx’
‘xx’
‘xx’
‘xx’
‘xx’ ... ‘xx’ (Lc bytes)
‘xx’
Response Syntax
***
January 2015
Response Data or Datagram
SW1
SW2
‘xx’ .. ‘xx’ (Le or max bytes)
‘xx’
‘xx’
Page 26 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Status Codes
SW1
SW2
Description
'90'
'00'
success
'64'
'00'
card execution error
'67'
'00'
wrong length
'68'
'00'
invalid class (CLA) byte
'69'
'82'
security status not satisfied. This can include wrong data structure, wrong
keys, incorrect padding.
'6A'
'81'
invalid instruction (INS) byte
'6B'
'00'
wrong parameter P1 or P2
The error codes defined in the previous Status Codes table are valid for all the commands.
Command specific error codes are documented with their respective command
documentation.
Note: The error code 6982 security status not satisfied, received during secured
communication, blocks any further commands. Remove and reinsert the card to reactivate
communication with the card.
6.3 ST LRI64 Support (PC/SC 2.0 add-on)
ST Microelectronics’ LRI64 is a memory tag IC with 64-bit Unique ID (UID) and WORM user
area. The following table lists PC/SC 2.01 compliant functions that are available for LRI64
based storage cards.
Get UID
Update Binary
implemented according to [PCSC 2.01]
Read Binary
This ISO15693 compliant IC is not accessible with standard driver settings. It requires the
following registry key setting:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\RFID]
"ControlFlags"=dword:00000010
See the [PCSC 2.01] and [LRI64] for documentation of PC/SC 2.0 compliant LRI64 card
access. The following section describes usage of functions that are not already
documented in [PCSC 2.01].
Page 27 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
6.3.1
Update Binary
UpdateBinary requires block numbers within the WORM memory area (Write-Once ReadMany).
Examples:
Write ‘121314’ to block ‘0D’ (decimal 12):
Command APDU:
‘FFD6000D03121314’
Response APDU:
‘9000’
Attempt to write ‘101112 to block ‘0A’ (10 decimal):
Command APDU:
‘FFD6000A03101112’
Response APDU:
‘6282’
For blocks 10 and 11 this works out fine, however, because we previously wrote to
block 12, the card responds with ‘6282’ End of file reached before writing Lc bytes.
After the first write access to block 12 only read operations are supported.
The following APDU attempts to write to block 7:
Command APDU:
‘FFD6000701FF’
Response APDU:
‘6581’
The card responds with ‘6581’ Memory failure (unsuccessful writing) because this is a
UID byte - write access to the UID area is always locked.
January 2015
Page 28 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
6.3.2
Read Binary
The ReadBinary command is available for all blocks of the LRI64 chip.
Examples:
Reading all 15 blocks from 0 to 14
Command APDU:
‘FFB0000000’
Response APDE:
‘xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx9000’
Attempt to read 16 blocks
Command APDU:
‘FFB0000010’
Response APDE:
‘xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx6282’
The response is ‘6282’ or End of file reached before reading expected number of
bytes. Even though the warning ‘6282’ is returned, all bytes from block 0 up to block
14 are read correctly.
Read blocks 10 and 11 (2 bytes)
Command APDU:
‘FFB0000A02’
Response APDE:
‘xxxx9000’
Attempt to read an invalid block number:
Command APDU:
‘FFB0000F01’
Response APDE:
‘6A82’
The response is the error code ‘6A82’ because block number 15 does not exist.
6.4 ISO15693-3 Memory Card Support
For detailed information about supported ISO15693 Tags, reference Section 10 Reading
ISO15693, page 58.
READ BINARY and UPDATE BINARY is compliant to PS/SC2.01. See Section 4 PC/SC 2.0.
Page 29 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
7 Communication with MIFARE Plus
Depending on the card security level, the reader activates the MIFARE Plus card in the ISO
14443A Layer 3 or in the ISO 14443A Layer 4 (T=CL).
Security Level
Protocol Type
MIFARE Plus SL 0
ISO 14443 A – 4
MIFARE Plus SL 1
ISO 14443 A – 3
MIFARE Plus SL 2
ISO 14443 A – 3
MIFARE Plus SL 3
ISO 14443 A – 4
Note: The OMNIKEY synchronous API does not support the new MIFARE Plus cards (for
example SL1 cards). Use the command set from PC/SC 2.01 part 3. The MIFARE functions
from the sample application, contactlessdemoVC and contactlessdemoVB require the
synchronous API. These applications do not work with MIFARE Plus cards.
7.1
ISO 14443 A – Part 4 card communication
If the card is activated in protocol layer 4, the application communicates with the MIFARE
Plus card by calling SCardTransmit. The card command is transferred directly to the
MIFARE Plus card by using the T=CL protocol layer. The T=CL protocol layer is completed
by the driver. The application uses this type of communication for all card commands in
SL0 and SL3. For MIFARE Plus details, reference the MIFARE Plus data sheet from NXP
(www.nxp.com).
The application executes the card provisioning in security level 0 or the AES authentication
in security level 3 by direct transferring the MIFARE Plus commands.
7.2 ISO 14443 A – Part 3 card communication
If activating the card in protocol layer 3, the application does not use the direct card
communication. For this type of communication, a transparent transmission channel to the
card is necessary. There is an amendment proposal for the PC/SC specification part 3 (HID
and NXP) in discussion with the PC/SC work group.
Because the standardization is not concluded, the OMNIKEY Contactless Smart Card
reader provides an HID proprietary transparent channel. In this channel the application
communicates with generic card commands. See Sections 7.3 Open Generic Session, 7.4
Generic Card Commands and 7.5 Close Generic Session.
January 2015
Page 30 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
7.3 Open Generic Session
Stop the driver activity for card tracking and initialize the generic command session. Take
the card control to the application.
INIT GENERIC SESSION Command APDU
Command
Class
INS
P1
P2
Lc
Data In
Le
Init Session
0xFF
0xA0
0x00
0x07
0x03
0x01 0x00 0x01
-
INIT GENERIC SESSION Command Output
Data Out
SW1 SW2 = 0x9000
At first the application must send the following APDU with SCardTransmit.
Send
FFA0000703010001
Receive
9000
7.4 Generic Card Commands
Write the MIFARE Plus command in a transparent channel to the card. The Application
sends the Generic Card Command APDU with SCardTransmit.
GENERIC CARD COMMAND APDU
Command
Card
Command
Class
INS
P1
0xFF
0x0
0xA0
0
P2
Lc
0x0
6+n
5
Data In
Le
01 00 F3 00 00 64 + MIFARE Plus
command
00
Preamble
MIFARE Plus card command
Explanation
01 00 F3 00 00 64
E1 81
ISO14443-3 RATS
01 00 F3 00 00 64
0A 01 70 02 90 00
ISO14443-4 First Authentication
Never change the red labelled preamble.
The green labeled data field is the PCB and CID. The application is responsible for the
correct usage of the Protocol Control Byte (PCB) 0000 1010. The green labeled bit 0 is the
block number. See ISO 14443-4 clause 7.5.3 Block numbering rules.
GENERIC CARD COMMAND Output
Data Out
RF Controller Status
MIFARE Plus card answer
SW1 SW2
Byte1 Byte 2
Byte 3 … n-2
Byte n-1 Byte n
00 00
[PCB+CID]
SC
Data
0x9000
successful
[0A 01]
90
[ XX XX … XX ]
0x6400
no card answer (TimeOut)
0x9000
successful ACK answer from
MIFARE card
0x9000
successful NAK answer from
MIFARE card
08 04
0A
08 04
one-byte value
from range:
00-09, 0B-0F
The green labeled PCB, CID filed is only available if the card is switched to ISO14443-4. If
desired, leave the data field empty. The status code in this sample is successful code.
Page 31 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
7.4.1
MIFARE Plus commands with the GENERIC INTERFACE Command APDU
Samples
Switching to ISO14443 part 4 (RATS) Sample
Send
FFA00005080100F3000064E08100
Receive
00000C757784024D46505F454E479000
First Authentication Sample
Send
FFA000050C0100F30000640A017002900000
Receive
00000A0190XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX9000
SL1 authentication Sample
Send
FFA00005090100F300006476049000
Receive
000090XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX9000
7.5 Close Generic Session
Continue the driver activity for card tracking and close the generic command session. Take
the card control from the application to the driver.
CLOSE GENERIC SESSION Command APDU
Command
Class
INS
P1
P2
Lc
Data In
Le
Close
Session
0xFF
0xA0
0x00
0x07
0x03
0x01 0x00 0x02
-
INIT GENERIC SESSION Command Output
Data Out
SW1 SW2 = 0x9000
After the generic interface session, close the session. Do not skip this step.
The application must send the following APDU with SCardTransmit.
Send
Receive
January 2015
FFA0000703010002
9000
Page 32 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
8 OMNIKEY Contactless Smart Card Reader Keys
The OMNIKEY Contactless Smart Card reader has a set of built-in cryptographic keys, some
of which are implemented in volatile memory and others in non-volatile memory.
8.1
Key Numbering Scheme
Cryptographic keys are referenced by a unique key number between 0x00 and 0xFE. Each
key number refers to a key of pre-defined length for a specific card type. For cards such as
MIFARE and iCLASS, multiple key numbers are reserved.
The OMNIKEY key number is used to determine key usage, key length, and to map the
reader key to the third party card key.
Examples:
Reader Key number ‘0A’ refers to the 6 byte MIFARE key 10, KMIF10
Reader Key number ‘24’ refers to the 8 byte iCLASS Default key for application 1 on
page 1
See MIFARE and iCLASS for detailed documentation. Contact your card manufacturer for
information about any key values.
Keys Numbers and Key Names
Key #
Key Name
Key
Length
Key
Type
6 bytes
Card
Key
Non- volatile memory
Memory Type
6-byte (MIFARE) keys
‘00’ to
‘1F’
KMIF0 (MIFARE Key 0) to KMIF31 (MIFARE
Key 31)
8-byte (iCLASS) keys
Page 33 of 102
‘20’
KIAMC (KMC0, Kc for application 2 of page
0 on Book 0 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘21’
KMDC HID Master Key (KMD0, Kd for
application 1 of page 0 on Book 0 of
iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘22’
RFU (previously used for HID Master
Key KMDO)
8 bytes
Card
Key
Non-volatile memory
‘23’
KMC0 (Default Master Key for application
2 of page 0 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘24’
KMD1 (Default Master Key for application
1 of page 1 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘25’
KMC1 (Default Master Key for application
2 of page 1 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘26’
KMD2 (Default Master Key for application
1 of page 2 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘27’
KMC2 (Default Master Key for application
2 of page 2 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘28’
KMD3 (Default Master Key for application
1 of page 3 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘29’
KMC3 (Default Master Key for application
2 of page 3 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘2A’
KMD4 (Default Master Key for application
1 of page 4 of iCLASS card)
8 bytes
Card
Key
Non-volatile memory
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Key
Length
Key
Type
KMC4 (Default Master Key for application
2) of page 4 of iCLASS card
8 bytes
Card
Key
Non- volatile memory
‘2C’
KMD5 (Default Master Key for application
1 of page 5 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘2D’
KMC5 (Default Master Key for application
2 of page 5 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘2E’
KMD6 (Default Master Key for application
1 of page 6 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘2F’
KMC6 (Default Master Key for application
2 of page 6 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘30’
KMD7 (Default Master Key for application
1 of page 7 of iCLASS card)
8 bytes
Card
Key
Non-volatile memory
‘31’
KMC7 (Default Master Key for application
2 of page 7 of iCLASS card)
8 bytes
Card
Key
Non- volatile memory
‘32’
KMTD (Master Transport Key for
application 1 of Picopass cards)
8 bytes
Card
Key
Non volatile memory
‘33’
KMTC (Master Transport Key for
application 2 of Picopass cards)
8 bytes
Card
Key
Non- volatile memory
‘34’
KMD0B1 (Default Master Key for
application 1 of page 0 on Book 1 of
iCLASS card)
8 bytes
Card
Key
Non-volatile memory
‘35’..’7F’
RFU
KCUR (Custom read key)
16
bytes
Reader
Key
Non-volatile memory
KCUW (Custom write Key)
16
bytes
Reader
Key
Non- volatile memory
KENC (Card data encryption key)
16
bytes
Card
Key
Non- volatile memory
8 bytes
Card
Key
Key #
Key Name
‘2B’
Memory Type
16-byte keys
‘80’
‘81’
‘82’
24- byte keys
‘B0’..’CF’
RFU
32-byte keys
‘D0’..’DF’
RFU
0xF0 to 0xFF are volatile keys
0xF0
KVAK (volatile application key)
‘F1’...‘FF’
RFU
Volatile memory
Note: OMNIKEY Contactless Smart Card reader firmware version 5.00 is the first to support
all keys listed above. Readers with firmware version 1.03 and 1.04 only support key
numbers 0x20 and 0xF0.
Key number 0x21 to Key number 0x31 (except 0x22) are the default keys for iCLASS cards.
Key number 0x32 and 0x33 are the default transport keys for Inside cards.
Keys 0x21 and 0x22 are stored in the reader. The remaining non-volatile keys 0x23 to 0x33
are stored in the registry.
Key 0x21 cannot be updated. Updates of key 0x22 are RFU and currently not supported.
January 2015
Page 34 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
8.2 Key Container and Slots
The OMNIKEY Contactless Smart Card reader key container is organized in fixed-length
key slots. These key slots allow easy usage of cryptographic keys. It is not necessary that
the host application knows anything about the physical storage location. Load keys into a
key container by referring to a key slot and a key number. Key access and usage are
managed by the reader firmware. For security purposes, keys can only be used and
updated, but they can never be read. As an additional security measure, keys are diversified
with two 16-byte secret keys before being committed to a key container.
Key slot properties are available for advanced users. This feature is designed to ensure
proper use of a single key in case there are more keys than key slots.
Key Container of OMNIKEY Contactless Smart Card Reader
Page 35 of 102
Key Slot
(KS) Number
KS
Length
Default
Stored Key
Name
Default
Stored Key
Number
‘00’
12
KMIF0
’00’
….
12
-------
----
‘1F’
12
KMIF31
’1F’
‘20’
16
KCUR
’80’
’21’
16
KCUW
’81’
’22’
16
KENC
’82’
’23’
08
KIAMC
’20’
'24’
08
KMDO
’22’
’25’
08
KMDC
’21’
’26’
08
KVAK
’F0’
’27’
08
KMC0
’23’
’28’
08
KMD1
’24’
’29’
08
KMC1
’25’
’2A’
08
KMD2
’26’
’2B’
08
KMC2
’27’
’2C’
08
KMD3
’28’
’2D’
08
KMC3
’29’
’2E’
08
KMD4
’2A’
’2F’
08
KMC4
’2B’
’30’
08
KMD5
’2C’
’31’
08
KMC5
’2D’
’32’
08
KMD6
’2E’
’33’
08
KMC6
’2F’
’34’
08
KMD7
’30’
’35’
08
KMC7
’31’
’36’
08
KMTD
’32
’37’
08
KMTC
’33’
’38’
08
KMD0B1
’34’
Remarks
No key slot information is available for
these key slots. Retrieving information
will return SW1SW2 6300.
Key slot information is available.
No key slot information is available for
these key slots. Retrieving information
will return SW1SW2 6300.
Key slot information is available.
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
8.3 Key Update Rules
The following table lists update rules for keys being used by the reader system. Key
updates relate to keys residing in the OMNIKEY reader. Those keys are used for
authentication of the reader to the card or to encrypt data written to the card.
Key Name
KMIF0
to
KMIF31
KIAMC
Key
Number
‘20’
’21’
KMDO
’22’
KCUW
KENC
KVAK
’80’
’81’
’82’
’F0’
KMC0
6-byte MIFARE keys can be loaded/updated by using
the SCardCLWriteMIFAREKeyToReader function of
synchronous API. A key sent to reader may be plain or
3-DES encrypted with the KCUR or KCUW .
For more details (for example, padding for 3-DES
encryption) see the synchronous API help file
cmsync.hlp.
Standard Mode:
- Always
8-byte iCLASS key. This key is the transport key Kc0
(authenticates to application 2 on page 0).
Secured Mode:
- Read session
- Write session
Never
Authenticates the reader to the HID application of an
iCLASS card for read access. This authentication
requires secure mode operation. Write access to the
HID application is not allowed.
Never
RFU
Secured mode:
- read session
Authenticates the reader to establish a secured
session. Grants the application read access. This key
can also be used to encrypt the MIFARE key in
SCardCLWriteMIFAREKeyToReader function.
Secured mode:
- read session
- write session
Authenticates the reader to establish a secured
session. Grants the application read-only access. This
key can also be used to encrypt the MIFARE key in
SCardCLWriteMIFAREKeyToReader function.
Secured mode:
- read session
- write session
Encrypts data written to the card or decrypts data
read from the card. Requires read/update INS bits to
be set accordingly. If INS bits are set for DES, the first
8 bytes of KENC are used. For 3-DES operations, all 16
bytes are used.
Standard Mode:
- Always
Authenticates any application on the iCLASS card. The
sequence is as follows:
Load KVAK with the 8-byte value, Authenticate with
KVAK
Load KVAK with new 8-byte value, Authenticate with
KVAK.
Secured Mode:
- Read session
- Write session
Never
iCLASS default keys for free memory zones. May be
used to authenticate to any non-HID application on an
iCLASS card. This allows quick evaluation of iCLASS
cards without knowledge of the default keys.
Never
Picopass transport keys set by the card manufacturer.
to
KMC7
KMD1
to
Description
Always
’00’ to
‘1F’
KMDC
KCUR
Key
Update Rule
’23‘ to
’31’ and
‘34’
KMD7, and
KMD0B1
KMTD - KMTC
January 2015
’32’
’33’
Page 36 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9 Standard Communication with iCLASS Card
Standard communication means there is no authentication of the host application (for
example Microsoft Windows) to the OMNIKEY 5x21-CL. Unless the card itself has built-in
mechanisms for confidential communication, the channel between host and reader is
unprotected, exposing the connecting USB cable to eavesdropping.
9.1
APDU Structure for Standard Communication
iCLASS cards are supported through ISO7816 compliant APDU exchange. Command and
response APDUs are exchanged through the OMNIKEY proprietary API function
SCardCLICCTransmit residing in the OMNIKEY synchronous API.
Command APDU (through pucSendData)
CLA
INS
P1
P2
Lc
Data in
Le
‘80’
‘xx’
‘xx’
‘xx’
‘xx’
‘xx’ … ‘xx’
‘xx’
Response APDU (through pucReceivedData)
Data out
SW2
SW1
‘xx’ … ‘xx’
‘xx’
‘xx’
9.2 Commands Available in Standard Communication Mode
Card commands are referred to by their respective instruction (INS) byte as part of a
command APDU sent by SCardCLICCTransmit. The following table lists all INS values
supported by the OMNIKEY Contactless Smart Card reader in standard communication
mode.
List of Supported INS bytes (APDU Commend Set)
Page 37 of 102
Instruction (INS)
Description
Command Type
‘82’
Load Key
reader command
‘C4’
GetKeySlotInfo
reader command
‘A6’
Select Page
card command
‘88’
Authenticate
card command
‘B0’
Read
card command
‘D6’
Update
card command
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9.2.1
Select Page (Card Command)
iCLASS comes with various card configurations. Every iCLASS card has at least one page
(page 0). Cards such as the iCLASS 2x8KS, provide additional pages 1 to 7. In addition to
pages, iCLASS cards also have books. To select a certain memory block on an iCLASS card,
you need to know its book number, page number, and block number.
Select the appropriate page and book before authentication to an iCLASS card application
for performing read/write access. In the context of iCLASS cards, an application area and
memory area are synonymous.
Currently, only cards with more than 16 kbit of total memory capacity have an additional
book. The following section describes parameters of the Select Page command.
Command Syntax
CLA
‘80’
INS
‘A6’
P1
‘00’: Select the only page of iCLASS 2KS or single page of 16KS
’01’: Select page of multi-page iCLASS 16KS (8x2KS) or 32KS
P2
Specifies whether data is requested from the card
’00’: no data requested
’04’: request for 8-byte card serial number
’08’: request for 8-byte configuration block data
’0C’: request for 8-byte application issuer data
LC
for P1=’00’: standard mode: empty; secured mode: ‘00’
for P1=’01’: ‘01’
Data Field
for P1=’00’: empty
for P1=’01’: book number and page number according to format below
Le
for P2=’00’: empty
for P2>’00’: ’00’ or ‘08’
Data Field Format for Page Number & Book Selection
b7
0
b6
0
b5
b4
b3
b2
0
Book number
st
0: for 1 book
nd
1: for 2 book on iCLASS 32KS
b1
0
Page number 0-7
b0
Page Selection Examples
January 2015
Data Field
Description
‘03’
select page 3 of an iCLASS 8x2KS card
‘03’
select page 3 of book 0 of an iCLASS 32KS (book 0: 8x2KS) card
‘13’
select page 3 of book 1 of an iCLASS 32KS (book 1: 8x2KS) card
‘10’
select book 1 (16KS) of an iCLASS 32KS
‘00’
select book 0 (16KS) of an iCLASS 32KS
Page 38 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Response Syntax
Data Field
empty or
8 byte card response, in case of a previous request for such data
SW1
SW2
status word as described below
‘90’
‘00’
Success
‘62’
‘83’
requested page number does not exist
‘6C’
‘xx’
wrong length Le. xx returns the number of data available
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
Note: If the application resides on page 0 of an 8x2KS iCLASS card or on the single page of
an iCLASS 16KS or iCLASS 2KS card, the Select Page command is not necessary. It is
helpful to call Select Page anyway, in case you need to retrieve the card serial number,
configuration block, or application issuer data.
9.2.2
Load Key
Load Key command loads an iCLASS card key and stores it in reader memory, thus
preparing the reader for subsequent card authentication commands. OMNIKEY Contactless
Smart Card reader can only store one such key at a time.
Command Syntax
CLA
‘80’: standard mode operation
’84’: secured mode operation
INS
‘82’
P1
‘xx’ specifies key location according to byte format below
P2
‘xx’ key number (see Key Numbering Scheme)
LC
‘08’
Data Field
8 byte key
Le
Empty
P1 - Format for Key Location
b7
b6
b5
b4
b3
b2
b1
b0
Description
0: card key
1: reader key
x
0: plain transmission
1: secured transmission (not available)
x
0: key loaded in volatile memory
1: key loaded in non-volatile memory.
x
x
0: RFU (non-zero value returns error)
0
0
0
0
b0..b3 must be set to 0
Note: Only load a key in volatile memory once during any given card session. Unless you
need to authenticate to any additional application with a different key, you can use the
stored key throughout the session for more than one authentication.
Page 39 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Response Syntax
Data Field
Empty
SW1
SW2
status word as described below
‘90’
‘00’
success
‘63’
‘00’
no further information given (warning)
‘63’
‘81’
loading/updating is not allowed
‘63’
‘82’
card key not supported
‘63’
‘83’
reader key not supported
‘63’
‘84’
plaintext transmission not supported
‘63’
‘85’
secured transmission not supported
‘63’
‘86’
volatile memory is not available
‘63’
‘87’
non-volatile memory is not available
‘63’
‘88’
key number not valid
‘63’
‘89’
key length is not correct
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
January 2015
Page 40 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9.2.3
GetKeySlotInfo (Reader Command)
The GetKeySlotInfo reader command provides access to key slot status information.
OMNIKEY Contactless Smart Card reader provides a set of predefined key slots in the key
container. Easily load key slots with keys by referring to the key number (for example, key
reference) rather than loading the actual 8 byte key by value. The slot for key storage is
automatically determined by the reader system.
Command Syntax
CLA
‘80’: standard mode operation
’84’: secured mode operation
INS
‘C4’
P1
‘00’
P2
‘xx’ key slot number. See Section 8.2 Key Container and Slots.
LC
standard mode: empty; secured mode: ‘00’
Data Field
8 byte key
Le
‘00’ or ‘02’
Response Syntax
Data Field
2 byte key information
see Key Information and Key Access Option below
SW1
SW2
status word as described below
‘90’
‘00’
success
‘63’
‘00’
no further information given (warning)
‘63’
‘01’
key slot does not contain valid key or empty key slot
‘62’
‘83’
requested key slot does not exist
‘6C’
‘xx’
more data available than requested; xx returns available data size
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
Key Information (contained in Data Field)
b15
b14
B13
b12
b11
b10
b9
b8
Key
Access
Option
RFU
b7
b6
b5
b4
b3
b2
b1
b0
key number according to
7.1-Key Numbering Scheme
’FF’ means empty key slot
Key Access Option (contained in b9, b8 of Data Field)
Page 41 of 102
b9
B8
Key Access Option
0
0
key can be loaded for any plaintext and secured transmission.
0
1
key can only be loaded in OMNIKEY proprietary secured mode
1
0
key can never be loaded
1
1
RFU
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9.2.4
Authenticate (Card Command)
The Authenticate command authenticates the reader system to the card application of the
selected page. For iCLASS authentication, this command requires previous page selection.
Command Syntax
CLA
‘80’: standard mode operation
’84’: secured mode operation
INS
‘88’
P1
‘xx’ key type:
’00’: Inside Contactless or iCLASS debit key Kd (i.e. application 1)
’01’: Inside Contactless or iCLASS credit key Kc (i.e. application 2)
’60’: MIFARE Key A
’61’: MIFARE Key B
’FF’: key type unknown or not necessary
all other values: RFU
P2
‘xx’ key number. See Section 8.1 Key Numbering Scheme.
LC
length of address
iCLASS: standard mode: empty; secured mode: ‘00’
other cards: ‘01’ or ‘02’ (max 2 address bytes supported)
Data Field
iCLASS: empty
other cards: one or two byte address
Le
empty
Response Syntax
Data Field
empty
SW1
SW2
status word as described below
‘90’
‘00’
success
‘63’
‘00’
no further information given (warning)
‘69’
‘83’
authentication cannot be done
‘69’
‘84’
reference key not useable
‘69’
‘88’
key number not valid
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
January 2015
Page 42 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9.2.5
Read (Card Command)
The Read command reads a data block from the given block address. For the iCLASS card,
only eight bytes can be read at a time. For information about available blocks reference
[HID_ICLASS]. This command requires previous page selection and, depending on the
iCLASS card configuration, authentication to the iCLASS application.
Command Syntax
CLA
‘80’: standard mode operation
’84’: secured mode operation
INS
‘B0’
P1
MSB of block number
P2
LSB of block number
LC
standard mode: empty; secured mode: ‘00’
Data Field
empty
Le
‘00’ or ‘08’
’20’: if supported by card, up to 32 bytes can be returned
Response Syntax
Data Field
8 byte block returned from the card (iCLASS)
32 bytes returned if card supports it
SW1
SW2
status word as described below
‘90’
‘00’
success
‘62’
‘81’
part of returned data may be corrupted
‘62’
‘82’
end of file reached before reading all requested bytes
‘69’
‘81’
command incompatible
‘69’
‘86’
command not allowed
‘6A’
‘81’
function not supported
‘6A’
‘82’
file not found or addressed block or byte does not exist
‘6C’
‘xx’
more data available than requested; xx returns available data size, typically ‘08’
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
Note: Reading blocks without valid authentication or trying to read data without read
permission, will set all returned data to ‘FF’.
Page 43 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9.2.6
Update (Card Command)
The Update command writes a data block to a given block address. For the iCLASS card,
only eight bytes can be written at a time. For further information about available blocks
reference [HID_ICLASS]. This command requires previous page selection and, depending
on the iCLASS card configuration, authentication to the iCLASS application.
Command Syntax
CLA
‘80’: standard mode operation
’84’: secured mode operation
INS
‘D6’
P1
MSB of block number
P2
LSB of block number
LC
‘08’ (iCLASS only allows 8 bytes per call)
Data Field
8 bytes to be written to card
Le
empty
Response Syntax
Data Field
empty
SW1
SW2
status word as described below
‘90’
‘00’
success
‘62’
‘82’
end of file reached before writing all Lc bytes
‘65’
‘81’
memory failure (unsuccessful writing)
‘69’
‘81’
command incompatible
‘69’
‘86’
command not allowed
‘6A’
‘81’
function not supported
‘6A’
‘82’
file not found or addressed block or byte does not exist
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
Note: Updating without authenticating to the corresponding application returns ‘6400‘
Card Execution Error.
January 2015
Page 44 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
9.3 Communication in Standard Mode
Establish Context
1
2
3
Connect Card
4
Select Page
5
Load Key
6
Authenticate Application
7
Read/Update
No
Yes
Same Page
Yes
Further
Read/Update
Yes
Same
Application
No
No
8
Disconnect Card
9
Release Context
Page 45 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10 Secured Communication with the iCLASS Card
For a desktop smart card reader, such as the OMNIKEY Contactless Smart Card reader,
security mainly evolves from the following scenarios:
• Authenticity between the host application and the reader
• Confidentiality of data transmitted through USB cable
• Integrity of transmitted data
• Authenticity between the reader and the card
• Confidentiality and integrity of the RF transmission
• Confidentiality of data stored in cards
OMNIKEY Contactless Smart Card reader provides an end-to-end security scheme to fulfill
the security requirements listed above.
Note: Secured mode communication requires reader firmware version 5.00 or greater.
10.1 Multi-Step Approach to a Secure Card Reader System
10.1.1
Authenticity between Host and Reader
Authenticity between host and reader is enforced with a mutual authentication scheme
that requires a 16-byte transport key (Kcur or Kcuw) and a proprietary algorithm. Only
initiate sessions upon successful completion of this one-step mutual authentication
process.
Note: This feature prevents unauthorized reader usage. Additional information about this
process is available under NDA.
10.1.2
Confidentiality of USB Data Exchange
The Contactless Smart Card reader has a built-in mechanism that protects against
eavesdropping and replay attacks on USB traffic. The data transmitted through a USB
cable is triple DES encrypted with the Session Key (Ks). This key is generated during the
mutual authentication process. It is unique for every session. Therefore, traffic recorded in
one session cannot be replayed in another session.
10.1.3
Integrity of Transmitted Data
Data transmitted between host and reader is digitally signed with an eight-byte Message
Authentication Code (MAC) which is appended to the data. This is done to detect any
inconsistencies that may occur due to erroneous or modified data.
10.1.4
Authenticity between Reader and Card
iCLASS cards allow authentication of the reader system to the card. This is done by proving
knowledge of a shared secret, the iCLASS card application key KIAMC or KMDC . Applications
that are protected with such a key require successful reader authentication before
read/write access to card data is granted.
10.1.5
Integrity of the Radio Frequency (RF) Transmission
Data integrity of an RF transmission with an iCLASS card is enforced with a two-byte
checksum (based on CRC algorithm).
January 2015
Page 46 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.1.6
Confidentiality of the RF Transmission
The Contactless Smart Card reader supports an important feature to guarantee
confidentiality: it encrypts data before writing data to the card and decrypts data read
from the card. Confidentiality in this context means that data is securely transmitted
between the card and the reader without an eavesdropper reading the data in plaintext.
10.1.7
Authentication of the Host for Read/Write Session
The Contactless Smart Card reader contains two keys KCUR and KCUW that are used to
control access to read and write functions respectively. Initiating a reader session with KCUR
makes it a read-only session thus blocking functions that write to the card. Starting a
session with KCUW enables the reader for both read and write access.
Note: This is part of a host-to-reader authentication mechanism, not to be confused with
reader-to-card authentication enforced by the card itself.
10.1.8
Protection against Known Attacks
Replay Attacks:
The data header contains a datagram that is different with every APDU exchange.
The reader ensures that no frame is repeated.
Plain Text Attack:
For some critical commands, there is a built-in delay to prevent a plain text attack. If
there is any error in the data header or signature, the session is immediately
terminated. One can commence communication only after starting a new session.
Page 47 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.2 APDU Structure for Secured Communication
The Contactless Smart Card reader provides a unique mechanism to secure the
communication channel using OMNIKEY’s proprietary cryptographic envelope which
protects the transmitted data from eavesdroppers.
Secured communication requires additional steps to prepare data before sending it to the
reader system and after receiving data from the reader. The underlying triple DES
algorithm requires a block size that is a multiple of 8. Therefore, the datagram has a built-in
padding scheme. Authenticity of the plaintext is enforced with an 8 byte signature.
Command Syntax
CLA
INS
P1
P2
Lc
Input Datagram (sent to the reader)
Le
‘84’
‘xx’
‘xx’
‘xx’
‘xx’
‘xx ... xx’
‘xx’
Input Datagram (sent to the reader)
3-DES{KS, (
Data Header
(DH)
Size of INS
related data
LcINS
INS related
data
(INSData)
Padding
Bytes
(PB)
Signature
‘xxxxxxxx’
‘xx’
‘xx ... xx’
’80 ... 00’
‘xx ... xx’
4 bytes
1 byte
LcINS bytes
P bytes
8 bytes
)}
P = number of padding bytes to satisfy (4+1+ LcINS+P) is multiple of 8.
Response Syntax
Output Datagram (received from the reader)
SW2
SW1
‘xx ... xx’
‘xx’
‘xx’
Output Datagram (received from the reader)
3-DES{KS, (
Data Header (DH)
Size of Card
Response
LcR
Card
Response
Padding
Bytes
(PB)
Signature
‘xxxxxxxx’
‘xx’
‘xx ... xx’
’80 ... 00’
‘xx ... xx’
4 bytes
1 byte
n bytes
P bytes
8 bytes
)}
P = number of padding bytes to satisfy (4+1+ LcINS+P) is multiple of 8.
Note: If no valid session key Ks is available due to a previous error during the Start Session
command, all datagram bytes are set to ‘00’. Therefore the host would receive ’00 ... 00’ ||
SW1 || SW2 as response from the reader.
January 2015
Page 48 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.2.1
Data Header (DH)
Data Header
Byte 0
Byte 1
Host data header (HDH)
Byte 2
Byte 3
Reader data header (RDH)
When the host system sends a Host Data Header (HDH) to the reader, the reader must
acknowledge the HDH in its response by returning the 1’s complement of the original HDH.
This allows the host to check whether it receives data originating from the correct data
header.
When the reader sends a Reader Data Header (RDH) to the host, the host must
acknowledge the RDH in its next request by sending the 1’s complement of the preceding
RDH. This allows the reader to check whether the data sent by the host follows a previous
reader response.
10.2.2 Signature Generation
The OMNIKEY Contactless Smart Card reader signature generation is based on an 8-byte
Message Authentication Code (MAC). The MAC value is calculated by taking the last 8
bytes of a DES CBC encrypted data block consisting of DH, LcINSData, INSData, and
padding bytes. Kcur or Kcuw are used as signing keys.
The following steps describe how padding is applied to create a data block that can be
signed using a DES CBC operation:
• Append '80' to the right of the data block.
• If the resulting data block length is a multiple of eight, no further padding is required.
• Do zero (‘00’) padding until the data block size reaches a multiple of eight.
10.2.3 Session Key Generation
The session key Ks is derived from an 8-byte random number and the MAC transmitted to
the reader during Start Session. For the Start Session command, LcINSData equals 8
(length of the random number) and INSData contains the 8-byte random number.
All secured communication calls following a successful session key negotiation are 3DES
encrypted with Ks.
Page 49 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.2.4 Proprietary Host and Reader Datagram Example
Host
Reader
Step 1: Start session
Data Header
HDH
3DES (KCUR.
INSData
Padding
MAC
08
xxxxxxxxx
800000
xxxxxxxx
RDH
HDH0
Rnd
LcINSData
)
Rnd8
Rnd
Session Key (Ks) = Rnd8 + MAC
Data Header
3DES (KS,
HDH
RDH
~HDH0
RDH0
LcR
Padding
MAC
00
800000
xxxxxxxx
)
Rnd
Step n: Any other command
Data Header
3DES (KS,
LcINSData
HDH
RDH
HDHn
~RDHn-1 xx
INSData
Padding
MAC
xxxxxxxxx
80xxxxx
xxxxxxxx
)
Rnd
Data Header
3DES (KS,
HDH
RDH
~HDHn
RDHn
LcR
Padding
MAC
xx
80xxxxx
xxxxxxxx
)
Rnd
Note: This is a read-only session because KCUR was used in the start session command. If
KCUW were used to start the session, both read and write operations would be allowed. The
HID application is always read-only.
January 2015
Page 50 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.3 Instructions (INS) for Secured Communication
Card commands are referred to by their respective instruction (INS) byte as part of a
command APDU sent by SCardCLICCTransmit. OMNIKEY Contactless Smart Card reader
with firmware version 5.00 or greater supports the following secured mode instructions:
List of INS bytes for Secured Communication
Instruction (INS)
Description
Command Type
‘C4’
GetKeySlotInfo
reader command
‘72’
Manage Session
reader command
‘82’
Load Key
reader command
‘A6’
Select Page
card command
‘88’
Authenticate
card command
‘B0’
Read
card command
‘D6’
Update
card command
‘24’
Update Card Key
card command
In the following sections the command structure is described. LcINS and INSData are part
of the OMNIKEY proprietary structure.
Notes:
Secured mode and Standard Mode use different formatting of P1, bit 7 and bit 6 of the
Read/Update commands (INS 0xB0 and 0xD6 respectively). Use the two LSBits of P1 to
control the encryption of data read or updated.
Lc must always be transmitted in secured mode.
10.3.1
Manage Session (Reader Command)
The Manage Session command is used to start or end a session.
Command Syntax
CLA
‘84’
INS
‘72’
P1
‘00’: start session
’01’: end session
other values: RFU
P2
P1 = ‘00’ (start session)
P1 = ’01’ (end session)
‘00’: start read only session
’01’: start read/write session
‘00’
Lc
‘08’: challenge size
‘00’
Data Field
8-byte random number (challenge)
empty
Le
empty
Response Syntax
Data Field
empty
SW1
SW2
status word as described below
‘90’
‘00’
success
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
Note: A session is automatically ended if the card is removed.
Page 51 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.3.2 Select Page (Card Command)
Except for the CLA byte ‘84’, the syntax for Select Page in secured mode is identical to the
command described in 8.2.1-Select Page (Card Command).
10.3.3 Load Key (Reader Command)
Except for the CLA byte ‘84’, the syntax for Load Key in secured mode is identical to the
Load Command described in 8.2.2-Load Key.
10.3.4 Authenticate (Card Command)
Except for the CLA byte ‘84’, the syntax for Authenticate in secured mode is identical to
the command described in 8.2.4-Authenticate (Card Command).
10.3.5 Read (Card Command)
Except for the CLA byte ‘84’, and the additional formatting rules for P1 described below,
the syntax for the Read command in secured mode is identical to the command described
in 8.2.5-Read (Card Command).
P1 Formatting for Secured Mode
b7
b6
0
0
0
1
1
0
1
1
b5 – b0
Description
Plain
Block Nr. MSB
DES Encryption
Triple DES Encryption
RFU
Data needs to be decrypted with the KENC to get the plaintext data.
10.3.6 Update (Card Command)
Except for the CLA byte ‘84’, and additional formatting of P1 described below, the syntax
for the Update command in secured mode is identical with the command described
in 8.2.6-Update (Card Command).
P1 Formatting for Secured Mode
b7
b6
0
0
0
1
1
0
1
1
b5 – b0
Description
Plain
Block Nr. MSB
DES Encryption
Triple DES Encryption
RFU
Data is encrypted with KENC before storing it on the card.
10.3.7 GetKeySlotInfo (Reader Command)
Except for the CLA byte ‘84’, the syntax for 7.3.7 GetKeySlotInfo in secured mode is
identical to the command described in 8.2.3-GetKeySlotInfo (Reader Command).
January 2015
Page 52 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.3.8 Update Card Key
The Update Card Key command is used to change KC or KD.
Command Syntax
CLA
‘84’
INS
‘24’
P1
‘00’: New key for KD (application 1)
’01’: New key for KC (application 2)
other values: RFU
P2
Key number where new key is stored.
Lc
‘00’: empty
Data Field
empty
Le
empty
Response Syntax
Data Field
empty
SW1
SW2
status word as described below
‘90’
‘00’
Success
'65'
'81'
Memory failure (unsuccessful writing)
'69'
'81' ‘86’
Command incompatible
Command not allowed
'6A'
'81'
Function not supported
Reference section 5.2.1-Card Access through SCardCLICCTransmit for additional status
words common to all iCLASS access functions.
The sequences for using UpdateCardKey command are as follows:
3. 1.
If the desired change of the key is not in page 0, the page has to be selected
by a Select Page command.
4. 2.
Load transport/old key by Load Key command.
5. 3.
Authenticate the card with the old key (key number as used for Load Key in
step 2).
6. 4.
Load new key by Load Key command.
7. 5.
Now send the UpdateCardKey command with specific P2 (New Key number
as loaded in step 4).
Note: Only update KD (application 1) after authentication with KD, and only update KC
(application 2) after authentication with KC.
CAUTION: Do not write directly to address 3, 4 where KC and KD are stored, this will
destroy the keys.
Page 53 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.4 Communication at Secured Mode
1
Establish Context
2
3
Connect Card
4
Start Session
5
Select Page
6
Load Key
7
Authenticate Application
8
Read/Update
Further
Read/Update
No
Yes
Same
Page
Yes
Yes
Same
Application
No
No
9
10
11
January 2015
End Session
Disconnect Card
Release Context
Page 54 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
10.5 Session at Secured Mode APDUs Example
KCUR = ‘A0A1A2A3A4A5A6A7A8A9AAABACADAEAF’, Read-only session
Host Reader
1.
Start Session
CLA
INS
P1
P2
Lc
OMNIKEY Proprietary Input Datagram (sent to reader) CLEAR
‘84’
‘72’
‘00’
‘00’
‘18’
‘1422’
‘9D2B’
‘08’
‘4A895F20C
2D30B5E’
‘800000’
‘9E5052819C5A8D3C
’
HDH
(Rnd)
RDH
(Rnd)
LcINS
Rnd8
(INSData)
Padding
Signature
DH
MAC
‘FD274CE840FA9AD139E4FC2923653A88743CB5986DB4F7A0’
OMNIKEY Proprietary Input datagram (sent to reader) ENCIPHERED
Signature = DESEn {(A0A1A2A3A4A5A6A7),(14229D2B084A895F20C2D30B5E800000)}
= 8A8D430D608714FE9E5052819C5A8D3C
9E5052819C5A8D3C (last eight bytes of DES encryption)
Enciphered datagram = 3-DESEn{
(A0A1A2A3A4A5A6A7A8A9AAABACADAEAF),
(14229D2B084A895F20C2D30B5E8000009E5052819C5A8D3C) }
= FD274CE840FA9AD139E4FC2923653A88743CB5986DB4F7A0 (24 byte input
datagram)
SessionKey (KS) = Rnd8 + MAC = 4A895F20C2D30B5E9E5052819C5A8D3C
OMNIKEY Proprietary Output Datagram (received from reader)
SW1SW2
A04B84A4DE515FD8A9D40DFFE703FBF1
9000
‘EBDD’
E00C
00
800000
E367401E2DA8FACB
~HDH
RDH(Rnd)
LcR
Padding
Signature
DH
MAC
3DESDec{(4A895F20C2D30B5E9E5052819C5A8D3C),(A04B84A4DE515FD8A9D40DFFE7
03FBF1) }
= EBDDE00C00800000E367401E2DA8FACB
Signature
= DESEn{(4A895F20C2D30B5E),( EBDDE00C00800000) }
= E367401E2DA8FACB
Note: A public source library to accomplish all security protocols introduced in the secured
communication mode is available from OMNIKEY upon request.
Page 55 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
2. Authenticate HID Application
CLA
INS
P1
P2
Lc
OMNIKEY Proprietary Send Datagram
84
88
00
21
10
B3F1
1FF3
00
800000
B50318C9E871191A
HDH
(Rnd)
~RDH
LcINS
Padding
Signature
DH
MAC
B5FD83E756CA03DE54FBEA5546E8867D
Proprietary Data
Signature = DESEn{(4A895F20C2D30B5E),(B3F11FF300800000)}
= B50318C9E871191A
Proprietary Data = 3-DESEn{(4A895F20C2D30B5E9E5052819C5A8D3C),(
B3F11FF300800000B50318C9E871191A) }
= B5FD83E756CA03DE54FBEA5546E8867D
OMNIKEY Proprietary Response Datagram
SW1SW2
78A10C4FCC7EBC2C516354A56C4C7818
9000
4C0E
7D55
00
800000
D2D0B0B4E34EBDBE
~HDH
RDH(Rnd)
LcR
Padding
Signature
DH
MAC
3-DESDec{(4A895F20C2D30B5E9E5052819C5A8D3C),
(78A10C4FCC7EBC2C516354A56C4C7818) }
= 4C0E7D5500800000D2D0B0B4E34EBDBE
Signature
= DESEn{(4A895F20C2D30B5E),( 4C0E7D5500800000) }
= D2D0B0B4E34EBDBE
Note: A public source library to accomplish all security protocols introduced in the
secured communication mode is available from OMNIKEY upon request.
January 2015
Page 56 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
3. Read Block 6
CLA
INS
P1
P2
Lc
84
B0
00
06
10
OMNIKEY Proprietary Send Datagram
Le
6762
08
82AA
HDH
~RDH
(Rnd)
00
800000
LcINS Padding
DH
F63AB82BED09B039
Signature
MAC
2FABB8F0533E742383F4FE9045142859
Proprietary Data
Signature
= DESEn{(4A895F20C2D30B5E),( 676282AA00800000)}
= F63AB82BED09B039
Proprietary Data
= 3-DESEn{(4A895F20C2D30B5E9E5052819C5A8D3C),
( 676282AA00800000F63AB82BED09B039) }
= 2FABB8F0533E742383F4FE9045142859
OMNIKEY Proprietary Response Datagram
SW1
SW2
AA401E3D849B881044FF4D847977D9070C589338C097F163
9000
989D
2A94
08
000000000000E414
800000
3101DDB971C922FF
~HDH
RDH(Rnd)
LcR
Response Data
Padding
Signature
DH
MAC
3-DESDec { (4A895F20C2D30B5E9E5052819C5A8D3C),
(AA401E3D849B881044FF4D847977D9070C589338C097F163)}
= 989D2A9408000000000000E4148000003101DDB971C922FF
Signature
= DESEn{(4A895F20C2D30B5E),(
989D2A9408000000000000E414800000) }
= 1CDF21DCA31BABDB3101DDB971C922FF
= 3101DDB971C922FF (last 8-byte block)
Note: A public source library to accomplish all security protocols introduced in the secured
communication mode is available from OMNIKEY upon request.
Page 57 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11 Reading ISO15693
11.1 Products
This document describes the commands for ISO 15693 support of OMNIKEY Contactless
Smart Card reader.
Applicable readers are:
OMNIKEY 5321 USB
OMNIKEY 6321 USB
OMNIKEY 5321 CL
OMNIKEY 5321 CR
OMNIKEY 5421
Applicable drivers and operating system:
MS Windows Drivers Version from1.2.0.6.
11.2 Tags
The following tags and functions are covered by this document
• iCODE (see the following table)
• LRI 64
• SLC Montalbano Technology
• Texas Instruments Tag-it
1
2
• Infineon (MY-D, MY-D light)
• All ISO 15693-3 compliant Tags with support for functions marked as optional.
(Include tag functions Inventory, Stay Quiet …etc.)
Support for ICODE tags
Card Type
Chip Type
Support
ICODE 1
SL2 ICS30 01
UID, (Not ISO15693 Part3 compliant)
ICODE SLI
SL2 ICS20
Full
ICODE EPC
SL2 ICS10
Not supported
ICODE UID
SL2 ICS11
Not supported
ICODE UID-TOP
SL2 ICS12
Not supported
ICODE SLI-S / SLI-S HC
SL2 ICS53 / ICS54
Full support. Exception is GetSecurityStatus,
which is not supported by the card. For further
information see the datasheet [iCODE SL2].
1
Tag-it Standard and Pro do only support READ BINARY, UPDATE BINARY, GET DATA PICC memory and
LOCK, Applicable at MS Windows Drivers Version 1.2.0.14
2
Applicable at MS Windows Drivers Version 1.2.0.14
January 2015
Page 58 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11.3 Commands
11.3.1
Get Data
This Get Data command will retrieve information about the inserted command depending
on the inserted card. It can be used for kind of contactless cards.
GET DATA Command APDU
Command
Class
INS
P1
P2
Lc
Data In
Le
Get Data
0xFF
0x30
XX
0x00
-
-
XX
P1/P2 denotation
P1
P2
Description
0x00
0x00
RFU
0x01
0x00
RFU
0x02
0x00
AFI of a ISO 15693 card is returned if supported
0x03
0x00
DSFID of a ISO 15693 card is returned if supported
0x04
0x00
PICC memory size is returned if supported
0x05
0x00
IC reference is returned if supported
0x06
0x00
EAS sequence (only for I-CODE SLI cards) is returned ,
Note: EAS sequence is a bit stream which is sent LSB first !!!
GET DATA Command Output
Data Out
Data + SW1 SW2
Le = 0x00, this means: Return full length of the data
SW1SW2 Examples
Page 59 of 102
SW1
SW2
Meaning
Warning
‘62’
‘82’
End of data reached before Le bytes (Le is greater than data
length).
Error
‘6A’
‘81’
Function not supported
‘6C’
‘xx’
Wrong length (wrong number Le; ‘XX’ encodes the exact
number) if Le is less than the available UID length)
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11.3.2
Put Data
Use this command to write system information to a contactless card.
Put Data Command APDU
Command
Class
INS
P1
P2
Lc
Data In
Le
Put Data
0xFF
0x30
0x00
0x01
3+N
See table
-
Put Data bytes
Byte 1
Byte 2
Byte 3
Byte 4..n
Version
0x01
Flag1
Flag2
Data
Put Data Flag denotation for version 0x01
Flag1
Flag2
0x00
0x00
RFU
0x01
0x00
RFU
0x02
0x00
AFI of a ISO 15693 card is written if supported
0x03
0x00
DSFID of a ISO 15693 card is written if supported
0x04
0x00
RFU
0x05
0x00
RFU
0x06
0x00
EAS bit is written (for I-Code SLI) cards. Data field consists of one byte (bit 0
3
is the new value of the EAS bit)
0x00
0x01
Stay quiet (the PICC does not answer any more any response), currently not
supported
The following table introduces examples of SW1SW2 and their meaning.
Put data Command Error Codes
Warning
Error
3
4
SW1
SW2
Meaning
'62'
'82'
Block or field is locked
'63'
'00'
No information is given
‘64’
‘00’
Execution error
‘6A’
‘81’
Function not supported
'69'
'82'
Security status not satisfied
‘86’
Command not allowed, no ISO15693-3 chip
4
EAS is supported by MY-D; EAS must be enabled in AFI byte (bit 2)!
The chip does not support the optional ISO15693-3 command type.
January 2015
Page 60 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11.3.3
Lock
Use this command to lock the memory area of a contactless card.
5
Lock APDU
Command
Class
INS
P1
P2
Lc
Data In
Le
Lock
0xFF
0x30
0x00
0x02
3+N
See table
-
Lock data bytes
Byte 1
Byte 2
Byte 3
Byte 4..n
Version 0x01
Flag1
Flag2
Data
Lock Flag denotation for version 0x01
Flags1
Flags2
Data1
Data2
0x00
0x00
Data field contains in 2 bytes the block number
Address
(MSB)
Address
(LSB)
0x01
0x00
RFU
-
-
0x02
0x00
AFI of a ISO 15693 card is locked if supported
-
-
0x03
0x00
DSFID of a ISO 15693 card is locked if supported
-
-
0x04
0x00
RFU
-
-
0x05
0x00
RFU
-
-
0x06
0x00
EAS bit (only for I-CODE SLI cards) is locked
-
-
The following table introduces SWISW2 examples.
Lock Command Error Codes
Warning
Error
SW1
SW2
Meaning
'62'
'82'
Block or field already locked
'63'
'00'
No information is given
‘6A’
‘81’
Function not supported
'69'
'82'
Security status not satisfied
'86'
Command not allowed, no ISO15693-3 chip
5
Command is not supported by MY-D light; to set and get security you can use the generic command.
Reference the Infineon MY-D light specification and OK5x21_ISO15693_GenericCardCommands.doc
Page 61 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11.3.4
Get Security Status
Use this command to retrieve the security status of some memory area of a contactless
6
card.
Get Security Status Command APDU
Command
Class
INS
P1
P2
Lc
Data In
Le
Get Security Status
0xFF
0x30
0x00
0x03
3+N
See table
XX
Get Security Status data bytes
Byte 1
Byte 2
Byte 3
Byte 4..n
Version
0x01
Flag1
Flag2
Data
Get Security Status Flag denotation for version 0x01
Flag1
Flag2
Data1
Data2
0x00
0x00
0x01
0x00
Block
Address (MSB)
Address (LSB)
RFU
-
-
0x02
0x00
AFI (only supported for MY-D, not MY-D
light)
-
-
0x03
0x00
DSFID (currently not supported)
-
-
0x04
0x00
RFU
-
-
0x05
0x00
RFU
-
-
0x06
0x00
EAS
-
-
(not supported by ICODE-SLI)
Le codes the number of bytes for which the security status should be retrieved.
6
Command is not supported by MY-D light; to set and get security, use the generic command. Reference the
Infineon MY-D light specification and OK5x21_ISO15693_GenericCardCommands.doc
January 2015
Page 62 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
For each address/block number/page number, retrieved is one byte with the security
status.
ICODE SLI
Data 1, Data 2 contains the block number (0 – 27). Each block has 4 bytes.
LRI 64
Data 1, Data 2 contains the block number (0 – 14). Each block has 1 byte.
SLC
Montalbano
Technology
Data 1, Data 2 contains the block number (0 – 63). Each block has 8 bytes.
MIFARE 1k
Data1, Data2 contains the block number (0 - ((16 * 4) –1) )
Note: MIFARE 1k has 16 sectors. Each sector has 4 blocks.
Each block has 16 bytes.
(Get Security Status currently not supported)
MIFARE 4k
Data1, Data2 contains the block number (0 - ((32 * 4 + 16*4) –1) )
Note: MIFARE 4k has 32 sectors which have 4 blocks and 16 sectors which
have 16 blocks.
Each block has 16 bytes.
(Get Security Status currently not supported)
MIFARE Ultralight
Data1, Data 2 contains the page number (0 – 15). Each page has 4 bytes.
(Get Security Status currently not supported)
MIFARE Mini
Data1, Data2 contains the block number (0 - ((5 * 4) –1) )
Note: MIFARE Mini has 5 sectors. Each sector has 4 blocks.
Each block has 16 bytes.
(Get Security Status currently not supported)
MY-D
Data 1, Data 2 contains the block number.
(SRF55V10P: 0 – 247, SRF55V02P: 0 – 55) Each block has 4 bytes.
The following describes the security status byte.
Type of card
B7
B6
B5
B4
B3
B2
B1
B0
ISO15693-3 compliant chip
x
x
x
x
x
x
x
Write access bit
MIFARE 1K
x
x
x
x
x
C1
C2
C3
MIFARE 4K
x
x
x
x
x
C1
C2
C3
MIFARE Ultralight
x
x
x
x
x
x
x
Lock bit
MIFARE Mini
x
x
x
x
x
C1
C2
C3
X ….. no meaning
The following table describes examples of SW1SW2 and their description:
Get Security Status Error Codes
SW1
Warning
Error
7
SW2
Description
'63'
'00'
No information is given
‘64’
‘00’
Execution error
‘6A’
‘81’
Function not supported
'69'
7
'82'
Security status not satisfied
‘86’
Command not allowed, no ISO15693-3 chip
The chip does not support the optional ISO15693-3 command type.
Page 63 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11.3.5
Read Binary Command
If the Le field contains only bytes set to '00', then all the bytes until the end of the file shall
8
be read within the limit of 256 for a short Le field or 65 536 for an extended Le field .
Read Binary Command APDU
Command
Class
INS
P1
P2
Read Binary
0xFF
0xB0
Address
MSB
Address
LSB
Lc
Data in
-
-
Le
XX
Read Binary Command Output
Data Out
Data + SW1 SW2
Read Binary Command Error Codes
SW1
SW2
Meaning
'62'
'81'
Part of returned data may be corrupted.
'82'
End of file reached before reading expected number of bytes.
Warning
'69'
Error
'6A'
'6C'
'81'
Command incompatible.
'82'
Security status not satisfied.
‘86’
Command not allowed.
'81'
Function not supported.
'82'
File not found / Addressed block or byte does not exist.
'XX'
Wrong length (wrong number Le; 'XX' is the exact number).
Le must be a multiple of the block size !
8
Currently are extended APDU’s only supported for Texas Instruments Tag-it and Infineon MY-D.
January 2015
Page 64 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11.3.6
Update Binary Command
The Lc field contains the length of the field Data in field. For a short Lc field the data length
is
9
1 <= Lc < 256 and for an extended Lc field the data length is 1 <= NC < 65 536.
Update Binary Command APDU
Command
Class
INS
P1
P2
Update Binary
0xFF
0xD6
Address MSB
Address LSB
Lc
XX
Data in
Le
Data
-
Update Binary Command Output
Data Out
SW1 SW2
Update Binary Command Error Codes
Warning
SW1
SW2
Meaning
'62'
'81'
A part of the returned data may be corrupted.
'82'
End of file reached before writing Lc bytes.
'65'
'81'
Memory failure (unsuccessful writing).
'69'
'81'
Command incompatible.
'82'
Security status not satisfied.
‘86’
Command not allowed.
Error
'6A'
'81'
Function not supported.
'82'
File not found / Addressed block or byte does not exist.
Lc must be a multiple of the block size!
9
Currently are extended APDU’s only supported for Texas Instruments Tag-it and Infineon MY-D.
Page 65 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
11.3.7
Update Single Byte Command
Use this command to write a single byte within a block. Currently, this command is only
supported for Infineon MY-D.
Update Single Byte Command APDU
Command
Class
INS
P1
P2
Lc
Data In
Le
Update Single Byte
0xFF
0xD7
0x00
0x00
6
See table
-
Update Single Byte Data bytes
Byte 1
Byte 2
Byte 3
Byte 4
Byte 5
Byte 6
Version
0x01
Block Address
MSB
Block Address
LSB
Offset within
Block MSB
Offset within
Block LSB
Data to be
written
The offset must be less than block size.
Update Single Byte Command Output
Data Out
SW1 SW2
Update Single Byte Command Error Codes
Error
January 2015
SW1
SW2
Meaning
'65'
'81'
Memory failure (unsuccessful writing).
'69'
'82'
Security status not satisfied.
'6A'
'81'
Function not supported.
'82'
File not found / Addressed block or byte does not
exist.
Page 66 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
12 OMNIKEY 5321 PAY Application Interface
The OMNIKEY 5321 PAY has an EMVCo Contactless Level 1 Type Approval. The application
interface (API) is compliant with PC/SC 2.01.
12.1 PayPass Card Transactions
For card detection, the application uses the SCCardStatusChange() function. If a PAY card
is present check the SCARD_STATE_MUTE status flag. If the SCARD_STATE_MUTE status
flag is 1, the PCD has found more than one card in the operation volume (collision
detected). If this status flag is zero, then the application continues with the card
transactions, for example, Select PPSE (Proximity Payment System Environment).
For transactions with a PAY Card, the application uses the SCardTransmit() function.
See Appendix A.7.10 EMVCo Contactless Level 2 Transactions.
If all transactions are complete the application must disconnect the card with the
dwDisposition value SCARD_UNPOWER_CARD. This is necessary for the correct card
removal procedure of the PCD.
12.2 LED and Buzzer Control
For LED and buzzer control the device provides a PC/SC IO-C0ntrol. Use this IO-Control
for the activation of OMNIKEY 5321 PAY read indication. The OMNIKEY 5321 PAY can use
™
the PayPass light/LED method for read indication and the additional tree indicators must
light the sequence. An audio indication (buzzer) can be used to indicate the success tone.
For more information about the light/LED read indication method, see the relevant
®
ongoing specification from EMVCo and MasterCard PayPass.
Table 1: Parameter for IO-Control SIGNAL
SCardControl Parameter
Description
dwControlCode
CM_IOCTL_SIGNAL
lpInBuffer
+0
PPARAM_SIGNAL
nInBufferSize
>= 3
lpOutBuffer
Empty
nOutBufferSize
>= 0
lpBytesReturned
0
UCHAR
ucCommand
UCHAR
ucParam1
UCHAR
ucParam2
UCHAR
ucRFU[10]
Table 2: Summary of SIGNAL Commands
Command
Page 67 of 102
Value
Description
PAYPASS_SIGNAL
0x20
Complete PayPass Audio and Visual Sequence
PAYPASS_SIGNAL_MAINLED
0x21
Control of Main LED
PAYPASS_SIGNAL_ADDLED
0x22
Control of additional PayPass LED 2-4
ACOUSTIC_SIGNAL_BEEPER_ON
0x10
Control of PayPass Audio Tone ON
ACOUSTIC_SIGNAL_BEEPER_OFF
0x11
Control of PayPass Audio Tone OFF
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
12.2.1
SIGNAL Command – PayPass Signal
This command clones the PayPass Audio and Visual Sequence for the event Card read
complete successful, according to MasterCard PayPass Terminal Implementation Guide.
Table 3: Parameter for SIGNAL Command – PayPass Signal
Parameter
Description
lpInBuffer
12.2.2
Command
Param1
Param2
RFU
20
loudness
--
--
nInBufferSize
>= 2
lpOutBuffer
Empty
nOutBufferSize
>= 0
lpBytesReturned
0
SIGNAL Command – PayPass Signal MAIN LED
The reader main LED (red/green bicolor) is by default under control of the firmware and
driver. In cases of MasterCard PayPass terminal implementation, an application control of
this LED is required. With this command the application assumes the LED control.
Table 4: Parameter for SIGNAL Command – PayPass Signal MAIN LED
Parameter
Description
Command Param1
lpInBuffer
21
nInBufferSize
>= 4
lpOutBuffer
Empty
nOutBufferSize
>= 0
lpBytesReturned
0
00 – CCID ESC
command
01 – USB Pipe
Control
Param2
Param3
RFU
LED
status
00 – by default
03 – application controlled
--
For LED control, before receiving the PICC answer, the application must use Param1 = 01 as,
USB Pipe Control Command.
Param2 is coded as 0000 00xx ( bit 2…7 is RFU ).
Table 5 - Summary of Param2
LED status
Bit 0
Bit 1
Value
Description
1
bicolor green
LED on
0
bicolor green
LED off
1
bicolor red
LED on
0
bicolor red
LED off
For details, see the code example in Appendix A.7.12 PayPass Signal MAIN LED.
January 2015
Page 68 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
12.2.3
SIGNAL Command – PayPass Signal Additional LEDs
For the status of the contactless payment application the MasterCard PayPass terminal
implementation requires three additional LEDs for visual indication. For example the
contactless application process was completed successfully. These three LEDs are
exclusive for the application. Driver and firmware do not use these three additional LEDs.
Table 6 - Parameter for SIGNAL Command – PayPass Signal Additional LEDs
Parameter
Description
Command Param1
lpInBuffer
22
nInBufferSize
>= 3
lpOutBuffer
Empty
nOutBufferSize
>= 0
lpBytesReturned
0
00 – CCID ESC command
01 – USB Pipe Control
Param2
Param3
RFU
LED status
--
--
Param2 is coded as 0000 0xxx ( bit 3…7 is RFU )
Summary of Param2
LED status
Bit 0
Bit 1
Bit 2
Value
Description
1
green LED2 on
0
green LED2 off
1
green LED3 on
0
green LED3 off
1
green LED4 on
0
green LED4 off
For details see the code example in Appendix A.7.13 PayPass Signal Additional LEDs.
12.2.4 SIGNAL Command – PayPass Signal Tone
No command parameters are required. The command code 0x10
(ACOUSTIC_SIGNAL_BEEPER_ON) turn on the buzzer and the command code 0x11
(ACOUSTIC_SIGNAL_BEEPER_OFF) turn off the buzzer. See the Table 8 - Summary of
SIGNAL Commands.
For details, see Appendix A.7.14 PayPass Signal Tone.
Page 69 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
12.3 Switch-over the Operating Mode
The OMNIKEY 5321 PAY requires the EMVCo Level 1 PCD processing. After the driver is
installed, the PCD (Proximity Coupling Device) starts in PAY mode by default. Also use the
reader in standard ISO mode. For dynamically changing between RFID-ISO and EMVCo L1
mode, the driver supports an IO-Control, described in this chapter. See also the code
example in Appendix A.7.11 Set RFID operating mode.
Note: The operating volume is optimized for EMVCo L1. This is not compliant with the
requirements of ISO / ICAO.
Parameter for IO-Control Set RFID Operation Mode
SCardControl Parameter
Description
dwControlCode
CM_IOCTL_SET_OPERATION_MODE
lpInBuffer
+0
nInBufferSize
>= 1
lpOutBuffer
Empty
nOutBufferSize
>= 0
lpBytesReturned
0
bOperationMode
0x10
OPERATION_MODE_RFID_ISO
0x11
OPERATION_MODE_RFID_PAYPASS
If the reader is switched to ISO mode, use the complete functionality of a standard
OMNIKEY Contactless Smart Card reader.
Note: Currently the EMVCo type approval is confined to the firmware version 1.75. This
firmware version does not support the read and write operations of iCLASS cards.
For a static usage in ISO mode switch the reader behavior with the following registry entry:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CardInterface]
ContactlessDefault=dword:00000000
January 2015
Page 70 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
13 Driver Configuration via ProxFormat
13.1 Overview
The OMNIKEY reader driver can be configured for a wide range of HID PROX card formats
both standard and custom, allowing the card reader system to process any Wiegand raw
bit stream. Driver settings control how raw data is being translated to data fields such as
facility code (FAC) and card number (CN) that are meaningful within the scope of physical
access control systems (PACS).
This chapter describes the ProxFormat setting available to control the OMNIKEY reader
driver. This document also describes how the system can be configured to return either
PACS facility code and card number or just raw Wiegand data.
13.2 ATR Format
The OMNIKEY 5x25 PROX reader returns PROX card data in an answer to reset (ATR)
commonly used in PC/SC-based smart card systems.
For HID PROX cards, the first byte of the ATR is always 3B hex. It is followed by a byte that
indicates in its LSB nibble how many PROX data bytes will follow. The third byte holds the
card’s ProxFormat.
13.2.1
ATR Example
The following ATR was generated by a card that returned the Wiegand raw data 00 02 25
64 hex = 100010010101100100 bin.
ATR = 3B 05 00 00 02 25 64
^ ^^ ^^ ^^ ^^ ^^
| historical bytes
|
5 historical bytes following (LSb nibble)
Historical bytes 00 00 02 25 64
^^ ^^ ^^ ^^ ^^
|| *card data*
||
PROX format (here 0, meaning Wiegand raw)
The same card, with ProxFormat set to H10301 would return ATR=3B06010001004786 hex
– a card with FAC=1 and CN=4786.
Described later in this guide is how to parse and translate raw data to data fields according
to the applicable PROX Format.
Page 71 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
13.3 Available ProxFormat Settings
In addition to HID PROX standard card formats such as H10301, H10302, H10304, H10320
and Corp 1000 there are hundreds of proprietary formats. This means, that the same bit
stream can be interpreted in many different ways using ProxFormat settings shown below.
Table 7: ProxFormat Settings
ProxFormat Value Hex
Data content
Windows
Linux/MacOS
1
No key
Wiegand Raw
-
Yes (default)
00
Wiegand Raw
-
Yes
Yes
01
H10301
26 bit (FAC+CN)
Yes
No
02
H10302
37 bit (CN)
Yes
No
04
H10304
37 bit (FAC+CN)
Yes
No
14
H10320
32 bit clock/data card
Yes
No
64
Corp 1000
35 bit (CIC+CN)
Yes
No
AUTO
Automatic mode
Yes
Yes (default)
CUSTOM
Customer defined
Yes
Yes
FE
FF
January 2015
Card format
3
No
1
During driver installation on Windows-based systems, no ProxFormat key is set. The driver interprets this as if
ProxFormat were set to zero i.e. the ATR returns Wiegand raw data.
2
ProxFormat settings are not part of the driver installation on systems running Linux/MacOS. The driver interprets
this as if ProxFormat were set to zero FE hex (automatic mode)
3
Setting ProxFormat to CUSTOM requires additional registry keys CostomProxFormat.
Page 72 of 102
2
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
13.3.1
ProxFormat Settings on Systems Running Windows
By default, the OMNIKEY reader system returns raw Wiegand data. This default behavior
can be changed using the ProxFormat Windows registry entry. Note that it requires
administrator rights to install and configure the OMNIKEY PROX reader driver and PROX
card registry settings.
The ProxFormat registry entry resides in the following registry path:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan]
Figure 9: ProxFormat Registry Entry
13.3.2
ProxFormat Settings on Systems Running Linux and MacOS X
By default, Linux and MacOSX-based systems are configured to automatic PROX card
detection mode. Driver configuration settings are read from a file named cmrfid.ini residing
in /etc/ directory. The INI file contains sections and entries similar to the Windows registry
settings.
Examples:
Contents of file cmrfid.ini to set ProxFormat to AUTO
[ProximityOptions]
ProxFormat = 254
Contents of file cmrfid.ini to set ProxFormat to CUSTOM
[ProximityOptions]
ProxFormat = 255
[CustomProxFormat-A]
StartBit = 14
BitLength = 10
[CustomProxFormat-B]
StartBit = 1
BitLength = 13
Page 73 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
14 ProxFormat Settings
14.1 Wiegand Raw Data Mode
ProxFormat = 0
This mode gives you the greatest flexibility. This is important in systems without a wellknown card population i.e. where the card format can vary or even is unknown. Having this
flexibility comes at a price though, any parsing that otherwise is done by the driver would
have to be done by the hoist application.
14.2 Standard Format Modes
H10301, H10302, H10304, H10320 and Corporate 1000 are standard card formats supported
via dedicated ProxFormat setting according to the following table.
CARD
FORMAT FAC / CIC CN
ProxFormat Setting
(hex format)
ATR
H10301
AAAA
BBBBBB
01
3B 06 01 AA AA BB BB BB
H10302
-
BBBBBBBBBBBB
02
3B 07 02 BB BB BB BB BB BB
H10304
AAAAA
BBBBBB
04
3B 07 04 0A AA AA BB BB BB
H10320
-
BBBBBBBB
14
3B 05 14 BB BB BB BB
Corp 1k
AAAA
BBBBBBBB
64
3B 07 64 AA AA BB BB BB BB
Example:
Setting ProxFormat to ‘01’ instructs the driver to interpret the series of bits received from a
PROX card as HID H10301 formatted PROX data. The rightmost six BCD formatted digits of
the historical byte block represent the card number CN. The card number can also be
found engraved on the card.
With ProxFormat set to ‘01’, a card with FAC=0001 and CN=000061 would return an ATR
of ‘3B 06 01 00 01 00 00 61’.
TIP: If you do not know whether you have a standard or custom formatted card, set
ProxFormat to hex FE (AUTO). Then present the card. If the reader can detect a standard
card format, it will return its respective ProxFormat value in the third ATR byte. This is a
quick way to find out the format of the most popular cards.
14.3 Automatic Mode
ProxFormat = FE hex = 254 dec
In AUTO mode, the driver tries to parse the bit stream and match it with a known format.
This mode is only recommended for the following card formats
H10301, H10302, H10320 and Corporate 1000
Note: that automatic mode is restricted to the card formats listed above. H10304 is not
part of this list because the reader system can’t distinguish H10302 cards from H10304
cards. They are both 37 bit formats. The only difference between the two formats is that
H10304 formatted cards contain a facility code whereas H10302 cards do not.
January 2015
Page 74 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
14.4 Custom Format Mode
ProxFormat set to FFhex = 255dec. This mode requires additional CustomProxFormat
settings. This mode allows you to configure the card system for any standard or
customized card format.
14.4.1
CustomProxFormat Settings
In addition to setting ProxFormat to 255dec, CustomProxFormat settings must be set. This
tells the OMNIKEY PROX reader driver where to find meaningful data fields within the raw
Wiegand bit sequence.
The raw bit-data-stream can be split into up to 15 several data-fields. Each data field is
labeled with a letter (A, B …etc.). Each data field is defined by its StartBit and BitLength.
Data fields may reflect a card number CN or a facility code FAC.
The StartBit entry specifies the position in the bit-data-stream, starting with the least
significant bit (LSb) – that’s all the way to the right.
Example:
00000100 bin … bit0=0, bit1=0, bit 2=1,….
Whenever custom ProxFormat is used, there have to be additional settings to define start
bits and the number of bits for the required custom format. For an HID PROX H10301
formatted card, you would need the following additional entries to get its FAC and CN with
ProxFormat set to 255. These entries tell the driver where to start and how many bits to
interpret as data field for any given section.
Windows Registry:
[HKLM\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]
StartBit=dword00000011
BitLength=dword:00000008
[HKLM\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]
StartBit=dword00000001
BitLength=dword:00000010
Linux/MaxOSX ini file:
[CustomProxFormat-A]
StartBit = 17
BitLength = 8
[CustomProxFormat-B]
StartBit = 1
BitLength = 16
Page 75 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
The following sections show CustomProxFormat entries for some standard PROX card
formats including the raw data and resulting parsed and interpreted data fields for facility
code and card number.
14.5 Example: H10301 PROX Card
The following example demonstrates how to extract the facility code FAC=1 and card
number CN=12345 from a H10301 formatted 26 bit PROX card. With its two parity bits this
card can hold 24 information bits.
14.5.1
Standard Format
The standard format H10301 is supported via ProxFormat = 1 and 254(AUTO)
14.5.2 Wiegand Raw Data
ProxFormat = 0
ATR:
3B 05 00 02 02 60
Historical Bytes:
02 02 60
bin
000000PaaaaaaaabbbbbbbbbbbbbbbbP
00000010000000100110000001110011
P Parity Bit
a Facility Code (FAC) bits
b Card Number (CN) bits
FAC =
00000001 bin =
0001
CN = 0011000000111001 bin = 012345
73 hex
73 hex = 00000010000000100110000001110011
dec (4 digits, defined by H10301 format)
dec (6 digits, defined by H10301 format)
14.5.3 CustomProxFormat Settings
ProxFormat = 255
Windows CustomProxFormat Settings:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]
StartBit=dword:00000011
BitLength=dword:00000008
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]
StartBit=dword:00000001
BitLength=dword:00000010
Linux, MacOSX CustomProxFormat Settings:
[CustomProxFormat-A]
StartBit = 17
BitLength = 8
[CustomProxFormat-B]
StartBit = 1
BitLength = 16
14.5.4 ATRs of a H10301 Card
H10301 PROX card FAC=1, CN=12345
January 2015
ProxFormat = 0 (RAW)
3B 05 00 02 02 60 73
ProxFormat = 1 (H10301)
3B 06 01 00 01 01 23 45
ProxFormat = 254 (AUTO)
3B 06 01 00 01 01 23 45
ProxFormat = 255 (CUSTOM)
CustomProxFormat\A: StartBit/Length = 17/8
CustomProxFormat\B: StartBit/Length = 1/16
3B 06 FF 00 01 01 23 45
Page 76 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
14.6 Example: H10302 PROX Card
The following example demonstrates how to extract the card number CN=1 from a H10302
formatted 37 bit PROX card. This type of card has no facility code available. With its two
parity bits this card can hold 35 information bits.
14.6.1
Standard Format
The standard format H10302 is supported via ProxFormat = 2 and 254(AUTO)
14.6.2 Wiegand Raw Data
ProxFormat = 0
ATR:
3B 06 00 00 00 00 00 02 hex
Historical Bytes:
00 00 00 00 02 hex =
0000000000000000000000000000000000010 bin
PaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaP
0000000000000000000000000000000000010
P Parity Bit
a Card Number (CN) bits
CN = 00000000000000000000000000000000001 bin = 00000000001 dec (11 digits,
defined by H10302 format)
FAC = N/A
14.6.3 CustomProxFormat Settings
ProxFormat = 255
Windows CustomProxFormat Settings:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]
StartBit=dword:00000001
BitLength=dword:00000023
Linux, MacOSX CustomProxFormat Settings:
[CustomProxFormat-A]
StartBit = 1
BitLength = 35
14.6.4 ATRs of a H10302 Card
H10302 PROX card
CN=00000000001
Page 77 of 102
ProxFormat = 0 (RAW)
3B 06 00 00 00 00 00 02
ProxFormat = 2 (H10302)
3B 07 02 00 00 00 00 00 01
ProxFormat = 254 (AUTO)
3B 07 02 00 00 00 00 00 01
ProxFormat = 255 (CUSTOM)
CustomProxFormat\A: StartBit/Length = 1/35
3B 07 FF 00 00 00 00 00 01
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
14.7 Example: H10304 PROX Card
This example demonstrates how to extract the facility code FAC=65535 and card number
CN=524287 from a H10304 formatted 37 bit PROX card. With its two parity bits this card
can hold 35 information bits.
14.7.1
Standard Format
The standard format H10304 is supported via ProxFormat = 4. Do not use AUTO due to
ambiguous results when used with other 37 bit formats.
14.7.2 Wiegand Raw Data
ProxFormat = 0
ATR:
3B 06 00 0F FF FF FF FF hex
Historical Bytes:
0F FF FF FF FF hex =
0111111111111111111111111111111111111 bin
PaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbP
0111111111111111111111111111111111111
P Parity Bit
a Facility Code bits (FAC)
b Card Number bits (CN)
FAC =
1111111111111111 bin = 65535 dec (4 digits, defined by H10304 format)
CN = 1111111111111111111 bin = 524287 dec (6 digits, defined by H10304 format)
14.7.3 CustomProxFormat Settings
ProxFormat = 255
Windows CustomProxFormat Settings:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]
StartBit=dword:00000014
BitLength=dword:00000010
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]
StartBit=dword:00000001
BitLength=dword:00000013
Linux, MacOSX CustomProxFormat Settings:
[CustomProxFormat-A]
StartBit = 20
BitLength = 16
[CustomProxFormat-B]
StartBit = 1
BitLength = 19
14.7.4 ATRs of a H10304 Card
H10301 PROX card FAC=1, CN=12345
January 2015
ProxFormat = 0 (RAW)
3B 06 00 0F FF FF FF FF
ProxFormat = 4 (H10304)
3B 07 04 06 55 35 52 42 87
ProxFormat = 255 (CUSTOM)
CustomProxFormat\A: StartBit/Length = 20/16
CustomProxFormat\B: StartBit/Length = 1/19
3B 07 FF 06 55 35 52 42 87
Page 78 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
14.8 Example: Corp 1000 PROX Card
The following example demonstrates how to extract the customer ID code CIC=4096 and
card number CN=2 from a Corp 1000 formatted 35 bit PROX card. Due to three parity bits
this card format holds 32 information bits.
14.8.1
Standard Format
The standard format Corp 1000 is supported via ProxFormat = 100 or 254(AUTO)
14.8.2 Wiegand Raw Data
ProxFormat = 0
ATR:
3B 06 00 03 FF E0 00 05
Historical Bytes:
03 FF E0 00 05
01111111111111000000000000000000101 bin
PPaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbP
01111111111111000000000000000000101
P Parity Bit
a Facility Code (FAC) bits
b Card Number (CN) bits
CIC =
111111111111 bin =
4095
format)
CN = 00000000000000000010 bin = 00000002
format)
hex
hex =
dec (4 digits, defined by Corp 1000
dec (8 digits, defined by Corp 1000
14.8.3 CustomProxFormat Settings
ProxFormat = 255
[HKEY_LOCAL_MACHINE
Windows CustomProxFormat Settings:
\SYSTEM\CurrentCont
rolSet\Control\Card
Man\CustomProxFormat\A]
StartBit=dword:00000015
BitLength=dword:0000000C
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]
StartBit=dword:00000001
BitLength=dword:00000014
Linux, MacOSX CustomProxFormat Settings:
[CustomProxFormat-A]
StartBit = 21
BitLength = 12
[CustomProxFormat-B]
StartBit = 1
BitLength = 20
14.8.4 ATRs of a Corp 1000 Card
Corp 1000 PROX card
CIC=4095, CN=2
Page 79 of 102
ProxFormat = 0 (RAW)
3B 06 00 03 FF E0 00 05
ProxFormat = 100 (Corp 1000)
3B 07 64 40 95 00 00 00 02
ProxFormat = 254 (AUTO)
3B 07 64 40 95 00 00 00 02
ProxFormat = 255 (CUSTOM)
CustomProxFormat\A: StartBit/Length = 21/12
CustomProxFormat\B: StartBit/Length = 1/20
3B 07 FF 40 95 00 00 00 02
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Appendix: A Application Programming
The following C++ sample project is part of the synchronous API which can be downloaded
from our website at www.hidglobal.com/omnikey.
If you choose the default installation settings, sample code is found in:
c:\Program Files\HID Global\Sync-API\Samples\contactlessdemovc.
Sample code for Visual Basic is also available and found in:
c:\Program Files\Samples\contactlessdemovb.
The sample uses the OMNIKEY synchronous API and demonstrates how to select a reader,
connect a card, and access either a MIFARE or iCLASS card.
A.1
Overview
From the Connected Reader list (top-left corner), select the reader. The list contains all
readers available to the smart card resource manager. When a card is inserted, displayed
are the ATR, UID and Card Name fields. From the Reader Related Function frame, select
the functions with or without a card in the RF field.
Only use the MIFARE Functions using Sync API frame when a MIFARE card is in the field.
Use the ISO 7816/iCLASS/PCSC 2.01 frame for APDU exchange with a CPU card
(asynchronous card) in the field.
Each processed command produces output in the output log. Clear the log with the
Refresh Output Screen button. The return status of the last executed function is shown in
the Last Operation Status frame.
Close the application with the Exit button.
Figure 10: Sample Program Screen
January 2015
Page 80 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.2
Reader Related Functions
Reader related functions do not require a card in the field.
To store a MIFARE key, complete the following:
• Define a key number to determine where to store the key.
• Select plain or secured as the mode of the key transmission. For secured
transmissions, use transmission key number 0x80 or 0x81.
• Enter the key in hex string format to the text field MIFARE Key. For plain
transmissions enter a 6 byte, 12 hex digit value (no spaces). For secured transmission
enter an 8 byte value.
• Click on the Write MIFARE Key to Reader button to load the key to reader memory.
A.3
MIFARE Functions Using Synchronous API
Before using the MIFARE Functions using Sync API, authenticate the card. (MIFARE
UltraLight does not need authentication).
To authenticate to a block of the card complete the following:
• In the field Block Nr, enter the authentication block number.
• In the field Access Option choose to supply a key number or plain key.
• In the field Authentication Mode choose Mode A or B.
• Press the Authenticate button.
Upon successful authentication, you can read and write data blocks and use the increment
and decrement functions.
A.4
PC/SC 2.01
Enter an APDU according to PC/SC 2.01 to access storage cards such as MIFARE cards
directly without using the OMNIKEY proprietary synchronous API.
A.5
ISO 7816 - APDU
Enter an APDU for your CPU (asynchronous) card and send the APDU the same way as an
ISO7816 contact card.
A.6
iCLASS Standard Mode
Present an iCLASS card to the reader RF field, and send APDUs directly to the card, see
Section 9 Standard Communication with iCLASS Card. This is an easy way of experimenting
with the available functions.
Page 81 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7
Code Examples
This section lists coding examples for a PC/SC 2.01 compliant implementation.
A.7.1
Getting the Card UID (PC/SC 2.01)
The following function retrieves the unique card ID (UID) currently connected to the card
through the air interface. Use the UID as the card serial number. The UID is available for
every ISO 14443 A/B or ISO 15693 compliant cards. It does not matter whether the card is
a CPU or storage card. This makes GetUID the ideal candidate for Hello Card type
applications. If you do not have access to application keys, the UID serves as a valuable
identifier allowing card lookup on a backend database.
BOOLEAN GetUID(UCHAR *UID, int &sizeofUID)
{
ucByteSend[0] = 0xFF;//CLA
ucByteSend[1] = 0xCA;//INS
ucByteSend[2] = 0x00;//P1
ucByteSend[3] = 0x00;//P2
ucByteSend[4] = 0x00;//Le
ulnByteSend = 5;
printf(\nRetrieving the UID..........);
SCard_Status = SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,
ucByteReceive, &dwRecvLength);
if (SCard_Status != SCARD_S_SUCCESS)
{
printf(\nProblem in SCardTransmit, Erro rcode = 0x%04X,SCard_Status);
return FALSE;
}
if(ucByteReceive[dwRecvLength-2] != 0x90 || ucByteReceive[dwRecvLength-1] !=
0x00)
{
printf(\nWrong return code: %02X%02X,
ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);
return FALSE;
}
sizeofUID = dwRecvLength-2;
memcpy(UID,ucByteReceive,sizeofUID);
return TRUE;
}
January 2015
Page 82 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.2 Loading a MIFARE Key (PC/SC 2.01)
The following code loads a MIFARE key to the reader. The key is stored in non-volatile
memory. Once loaded, it remains available throughout the reader session.
BOOLEAN LoadKey(UCHAR ucKeyNr, UCHAR *ucKey, UCHAR ucKeyLength)
{
ucByteSend[0] = 0xFF;
//CLA
ucByteSend[1] = 0x82;
//INS
ucByteSend[2] = 0x20;
//P1 card key, plain transmission, non-volatile
memory
ucByteSend[3] = ucKeyNr;
//P2 key number for MIFARE could be 0x00 to 0x31)
ucByteSend[4] = ucKeyLength;//Lc
memcpy(ucByteSend+5,ucKey, ucKeyLength );
ulnByteSend = 5+ucKeyLength;
printf(\nLoading Key to the reader..........);
SCard_Status = SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,
ucByteReceive, &dwRecvLength);
if (SCard_Status != SCARD_S_SUCCESS)
{
printf(\nProblem in SCardTransmit, Erro rcode = 0x%04X,SCard_Status);
return FALSE;
}
if(ucByteReceive[dwRecvLength-2] != 0x90 || ucByteReceive[dwRecvLength-1] !=
0x00)
{
printf(\nWrong return code: %02X%02X,
ucByteReceive[dwRecvLength -2],ucByteReceive[dwRecvLength-1]);
return FALSE;
}
return TRUE;
}
Page 83 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.3
MIFARE 1K/4K Authenticate (PC/SC 2.01)
The following code demonstrates how to authenticate a MIFARE card.
BOOLEAN Authenticate(UCHAR BlockNr, UCHAR ucKeyNr, UCHAR ucKeyType)
{
ucByteSend[0] = 0xFF;
// CLA
ucByteSend[1] = 0x88;
// INS
ucByteSend[2] = 0x00;
// P1, MIFARE Block Number MSB, for MIFARE it is
always 0x00
ucByteSend[3] = BlockNr;
// MIFARE Block Number LSB
ucByteSend[4] = ucKeyType; // P3
ucByteSend[5] = ucKeyNr;
ulnByteSend = 6;
printf(\nAuthenticating ..........);
SCard_Status = SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,
ucByteReceive, &dwRecvLength);
if (SCard_Status != SCARD_S_SUCCESS)
{
printf(\nProblem in SCardTransmit, Erro rcode = 0x%04X,SCard_Status);
return FALSE;
}
if(ucByteReceive[dwRecvLength-2] != 0x90 || ucByteReceive[dwRecvLength-1] !=
0x00)
{
printf(\nWrong return code: %02X%02X,
ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);
return FALSE;
}
return TRUE;
}
January 2015
Page 84 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.4
MIFARE 1K/4K Write (PC/SC 2.01)
BOOLEAN UpdateBinary(UCHAR BlockNr, UCHAR *ucDataToWrite, UCHAR ucDataLenght)
{
ucByteSend[0] = 0xFF;//CLA
ucByteSend[1] = 0xD6;//INS
ucByteSend[2] = 0x00;//P1, MIFARE Block Number MSB, for MIFARE it is always
0x00
ucByteSend[3] = BlockNr;//MIFARE Block Number LSB
ucByteSend[4] = ucDataLenght;
memcpy(ucByteSend+5,ucDataToWrite, ucDataLenght);
ulnByteSend = 5+ucDataLenght;
printf(\nUpdating Block ..........);
SCard_Status = SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,
ucByteReceive, &dwRecvLength);
if (SCard_Status != SCARD_S_SUCCESS)
{
printf(\nProblem in SCardTransmit, Erro rcode = 0x%04X,SCard_Status);
return FALSE;
}
if(ucByteReceive[dwRecvLength-2] != 0x90 || ucByteReceive[dwRecvLength-1] !=
0x00)
{
printf(\nWrong return code: %02X%02X,
ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);
return FALSE;
}
return TRUE;
}
Page 85 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.5
MIFARE 1K/4K Read (PC/SC 2.01)
BOOLEAN ReadBinary(UCHAR BlockNr, UCHAR *ucDataRead, UCHAR &ucDataLenght)
{
ucByteSend[0] = 0xFF;//CLA
ucByteSend[1] = 0xB0;//INS
ucByteSend[2] = 0x00;//P1, MIFARE Block Number MSB, for MIFARE it is always
0x00
ucByteSend[3] = BlockNr;//MIFARE Block Number LSB
ucByteSend[4] = 0x10;//Le
ulnByteSend = 5;
dwRecvLength = 255;
printf(\nReading Block ..........);
SCard_Status = SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,
ucByteReceive, &dwRecvLength);
if (SCard_Status != SCARD_S_SUCCESS)
{
printf(\nProblem in SCardTransmit, Erro rcode = 0x%04X,SCard_Status);
return FALSE;
}
if(ucByteReceive[dwRecvLength-2] != 0x90 || ucByteReceive[dwRecvLength-1] !=
0x00)
{
printf(\nWrong return code: %02X%02X,
ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);
return FALSE;
}
ucDataLenght = (unsigned char)dwRecvLength -2;
memcpy(ucDataRead,ucByteReceive,ucDataLenght);
return TRUE;
}
January 2015
Page 86 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.6
MIFARE 1K/4K Increment (OMNIKEY Proprietary API)
BOOLEAN Increment(UCHAR BlockNr, UCHAR *ucDataTobeIncremented, UCHAR
ucDataLenght)
{
ucByteSend[0] = 0xFF;//CLA
ucByteSend[1] = 0xD4;//INS
ucByteSend[2] = 0x00;//P1, MIFARE Block Number MSB, for MIFARE it is always
0x00
ucByteSend[3] = BlockNr;//MIFARE Block Number LSB
ucByteSend[4] = ucDataLenght;
memcpy(ucByteSend+5,ucDataTobeIncremented, ucDataLenght);
ulnByteSend = 5+ucDataLenght;
printf(\nIncrementing Block ..........);
SCard_Status = SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,
ucByteReceive, &dwRecvLength);
if (SCard_Status != SCARD_S_SUCCESS)
{
printf(\nProblem in SCardTransmit, Erro rcode = 0x%04X,SCard_Status);
return FALSE;
}
if(ucByteReceive[dwRecvLength-2] != 0x90 || ucByteReceive[dwRecvLength-1] !=
0x00)
{
printf(\nWrong return code: %02X%02X,
ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);
return FALSE;
}
return TRUE;
}
Page 87 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.7
MIFARE 1K/4K Decrement (OMNIKEY Proprietary API)
BOOLEAN Decrement(UCHAR BlockNr, UCHAR *ucDataTobeDecremented, UCHAR
ucDataLenght)
{
ucByteSend[0] = 0xFF;//CLA
ucByteSend[1] = 0xD8;//INS
ucByteSend[2] = 0x00;//P1, MIFARE Block Number MSB, for MIFARE it is always
0x00
ucByteSend[3] = BlockNr;//MIFARE Block Number LSB
ucByteSend[4] = ucDataLenght;
memcpy(ucByteSend+5,ucDataTobeDecremented, ucDataLenght);
ulnByteSend = 5+ucDataLenght;
printf(\nDecrementing Block ..........);
SCard_Status = SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,
ucByteReceive, &dwRecvLength);
if (SCard_Status != SCARD_S_SUCCESS)
{
printf(\nProblem in SCardTransmit, Erro rcode = 0x%04X,SCard_Status);
return FALSE;
}
if(ucByteReceive[dwRecvLength-2] != 0x90 || ucByteReceive[dwRecvLength-1] !=
0x00)
{
printf(\nWrong return code: %02X%02X,
ucByteReceive[dwRecvLength2],ucByteReceive[dwRecvLength-1]);
return FALSE;
}
return TRUE;
}
A.7.8
MIFARE Emulation Mode (OMNIKEY Proprietary API)
With the following code switch the MIFARE Emulation Mode on and off.
#define CM_IOCTL_SET_RFID_CONTROL_FLAGS
SCARD_CTL_CODE(3213)
DWORD
dwActiveProtocol;
//DWORD
dwControlFlag = 0xFFFFFFFF // On
DWORD
dwControlFlag = 0x00000004 // On
//DWORD
dwControlFlag = 0x00000000 // Off
BYTE
BYTE
DWORD
DWORD
DWORD
DWORD
DWORD
DWORD
InBuffer[16];
OutBuffer[16];
dwInBufferSize ;
dwOutBufferSize;
dwBytesReturned;
*Mask
= (DWORD *)InBuffer;
*Value
= (DWORD *)InBuffer+1;
dwControlCode
= CM_IOCTL_SET_RFID_CONTROL_FLAGS;
memset(InBuffer, 0x00, sizeof(InBuffer));
memset(OutBuffer, 0x00, sizeof(OutBuffer));
*Mask
= 0x00000004;
*Value
= dwControlFlag & *Mask;
dwInBufferSize = 8;
dwOutBufferSize = 0;
dwBytesReturned = 0;
January 2015
Page 88 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
SCard_Status = SCardControl(hCard,
dwControlCode,
(LPCVOID)InBuffer,
dwInBufferSize,
(LPVOID)OutBuffer,
dwOutBufferSize,
&dwBytesReturned);
if (SCard_Status == SCARD_S_SUCCESS)
{
if(dwControlFlag)
sprintf(szText,MIFARE\t);
else
sprintf(szText,T=CL\t);
}
else
{
sprintf(szText,IO Cntrol error\r);
}
// The card is disconnected after changing the MIFARE emulation mode
do
{
sReaderState.szReader = szReaderName;
sReaderState.dwCurrentState = SCARD_STATE_EMPTY;
sReaderState.dwEventState = SCARD_STATE_EMPTY;
SCardGetStatusChange(hContext,50,&sReaderState,1);
}
while((sReaderState.dwEventState & SCARD_STATE_PRESENT) == 0);
A.7.9
iCLASS Select Page (OMNIKEY Proprietary API)
The following code selects page 0x01 of an 8x2KS iCLASS card and returns the card serial
number.
//Select page 0x02 of a 8x2KS iCLASS card
UCHAR ucDataSend[7] = {0};
ULONG ulNoOfDataSend = 7;
UCHAR ucReceivedData[64] = {0};
ULONG ulNoOfDataReceived = 64;
ucDataSend
ucDataSend
ucDataSend
ucDataSend
ucDataSend
ucDataSend
ucDataSend
[0]
[1]
[2]
[3]
[4]
[5]
[6]
=
=
=
=
=
=
=
0x80
0xA6
0x01
0x04
0x01
0x01
0x08
//CLA, standard mode
//INS
//P1
//P2, return card serial number
//Lc
//Page number
//Le
SCard_Status = SCardCLICCTransmit(hCard,ucDataSend,ulNoOfDataSend,
ucReceivedData,&ulNoOfDataReceived);
if(SCard_Status!= SCARD_S_SUCCESS)
{
printf(Error in SCardCLICCTransmit, with error code %8X, SCard_Status);
exit(-1);
}
Page 89 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.10 EMVCo Contactless Level 2 Transactions
The following code example shows a typical OMNIKEY 5321 PAY transaction loop.
SCARDCONTEXT
SCARDHANDLE
SCARD_READERSTATE
CHAR*
DWORD
DWORD
DWORD
UCHAR
DWORD
UCHAR
DWORD
DWORD
hContext;
hCard;
sReaderState;
szReaderName;
dwShareMode;
dwPreferredProtocols;
dwActiveProtocols;
ucByteSend[256];
dwNByteSend;
abByteReceive[256];
dwRecvLength;
SCard_Status;
UCHAR
CLA,INS,..
abSelectPPSE[20] = {0x00,0xA4,0x04,0x00,
//
0x0E,
// Lc
0x32,0x50,0x41,0x59,0x2E,0x53,0x59,
//
0x53,0x2E,0x44,0x44,0x46,0x30,0x31,
0x00};
//
Data field
Le
// TODO: Code for PAY application
do
{
// wait for card
do
{
sReaderState.szReader = szReaderName;
sReaderState.dwCurrentState = SCARD_STATE_EMPTY;
sReaderState.dwEventState = SCARD_STATE_EMPTY;
SCardGetStatusChange(hContext,30,&sReaderState,1);
Sleep(20);
}
while((sReaderState.dwEventState & SCARD_STATE_PRESENT) == 0);
if ((sReaderState.dwEventState & SCARD_STATE_MUTE) != 0)
{
// Card present, Collision detected
// TODO: Code for PAY application
// wait for remove card
do
{
sReaderState.szReader = szReaderName;
sReaderState.dwCurrentState = SCARD_STATE_PRESENT;
sReaderState.dwEventState = SCARD_STATE_PRESENT;
SCardGetStatusChange(hContext,30,&sReaderState,1);
Sleep(20);
}
while((sReaderState.dwEventState & SCARD_STATE_EMPTY) == 0);
January 2015
Page 90 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
continue;
}
// TODO: Code for PAY application
// Connect card
dwShareMode = SCARD_SHARE_SHARED;
dwPreferredProtocols = SCARD_PROTOCOL_T1;
SCard_Status = SCardConnect( hContext,
szReaderName,
dwShareMode,
dwPreferredProtocols,
&hCard,
&dwActiveProtocols );
// TODO: Code for PAY application
memcpy( abByteSend, abSelectPPSE, 20);
dwNByteSend = 20;
do
{
dwRecvLength = 256;
SCard_Status = SCardTransmit ( hCard,
SCARD_PCI_T1,
abByteSend,
dwNByteSend,
NULL,
abByteReceive,
&dwRecvLength );
// TODO: Code for PAY application
}
while( /*TODO: Code for PAY application*/ );
// now disconnect the card
SCard_Status = SCardDisconnect( hCard, SCARD_UNPOWER_CARD );
// TODO: Code for PAY application
// wait for remove card
do
{
sReaderState.szReader = szReaderName;
sReaderState.dwCurrentState = SCARD_STATE_PRESENT;
sReaderState.dwEventState = SCARD_STATE_PRESENT;
SCardGetStatusChange(hContext,30,&sReaderState,1);
Sleep(20);
}
while( (sReaderState.dwEventState & SCARD_STATE_EMPTY) == 0 );
// TODO: Code for PAY application
}
while( /*TODO: Code for PAY application*/ );
// TODO: Code for PAY application
Page 91 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.11 Set RFID operating mode
The following code example shows setting the operating mode:
#define CM_IOCTL_SET_OPERATION_MODE
#define OPERATION_MODE_RFID_ISO
#define OPERATION_MODE_RFID_PAYPASS
BYTE
BYTE
DWORD
DWORD
DWORD
DWORD
SCARD_CTL_CODE (3107)
0x10
0x11
InBuffer[4];
OutBuffer[4];
dwInBufferSize;
dwOutBufferSize;
dwBytesReturned;
dwControlCode = CM_IOCTL_SET_OPERATION_MODE;
memset(InBuffer, 0x00, sizeof(InBuffer));
memset(OutBuffer, 0x00, sizeof(OutBuffer));
*InBuffer
= OPERATION_MODE_RFID_PAYPASS
dwInBufferSize = 1;
dwOutBufferSize = 0;
dwBytesReturned = 0;
SCard_Status = SCardControl (hCard,
dwControlCode,
(LPCVOID)InBuffer,
dwInBufferSize,
(LPVOID)OutBuffer,
dwOutBufferSize,
&dwBytesReturned);
January 2015
Page 92 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.12 PayPass Signal MAIN LED
The following code example shows an application using the reader main LED.
#define
#define
CM_IOCTL_SIGNAL
PAYPASS_SIGNAL_MAINLED
BYTE
BYTE
DWORD
DWORD
DWORD
DWORD
BYTE
BYTE
BYTE
InBuffer[4];
OutBuffer[4];
dwInBufferSize ;
dwOutBufferSize;
dwBytesReturned;
dwControlCode;
bUSBMode
= 0x01;
bReaderLEDs = 0x02;
bLEDMode
= 0x03;
SCARD_CTL_CODE (3058)
0x21
// USB Pipe Control
// red LED on
// application controlled
// TODO: Code for PAY application
memset(InBuffer, 0x00, sizeof(InBuffer));
memset(OutBuffer, 0x00, sizeof(OutBuffer));
dwControlCode
InBuffer[0]
InBuffer[1]
InBuffer[2]
InBuffer[3]
dwInBufferSize
dwOutBufferSize
dwBytesReturned
=
=
=
=
=
=
=
=
CM_IOCTL_SIGNAL;
PAYPASS_SIGNAL_MAINLED;
bUSBMode;
(bReaderLEDs) & 0x03;
bLEDMode;
4;
0;
0;
SCard_Status = SCardControl( hCard,
dwControlCode,
(LPCVOID)InBuffer,
dwInBufferSize,
(LPVOID)OutBuffer,
dwOutBufferSize,
&dwBytesReturned );
if (SCard_Status != SCARD_S_SUCCESS)
{
// TODO: Code for PAY application
}
// TODO: Code for PAY application
Page 93 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.13 PayPass Signal Additional LEDs
The following code example shows an application using the three additional LEDs.
#define
#define
CM_IOCTL_SIGNAL
PAYPASS_SIGNAL_ADDLED
BYTE
BYTE
DWORD
DWORD
DWORD
DWORD
InBuffer[4];
OutBuffer[4];
dwInBufferSize ;
dwOutBufferSize;
dwBytesReturned;
dwControlCode;
BYTE
BYTE
bUSBMode
= 0x01;
bReaderLEDs = 0x1C;
SCARD_CTL_CODE (3058)
0x22
// USB Pipe Control
// all additional green LEDs on
memset(InBuffer, 0x00, sizeof(InBuffer));
memset(OutBuffer, 0x00, sizeof(OutBuffer));
dwControlCode
InBuffer[0]
InBuffer[1]
InBuffer[2]
dwInBufferSize
dwOutBufferSize
dwBytesReturned
=
=
=
=
=
=
=
CM_IOCTL_SIGNAL;
PAYPASS_SIGNAL_ADDLED;
bUSBMode;
(bReaderLEDs >> 2) & 0x07;
3;
0;
0;
SCard_Status = SCardControl( hCard,
dwControlCode,
(LPCVOID)InBuffer,
dwInBufferSize,
(LPVOID)OutBuffer,
dwOutBufferSize,
&dwBytesReturned );
if (SCard_Status != SCARD_S_SUCCESS)
{
// TODO: Code for PAY application
}
// TODO: Code for PAY application
January 2015
Page 94 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
A.7.14 PayPass Signal Tone
The following code example shows an application using the buzzer.
#define
#define
#define
CM_IOCTL_SIGNAL
ACOUSTIC_SIGNAL_BEEPER_ON
ACOUSTIC_SIGNAL_BEEPER_OFF
BYTE
BYTE
DWORD
DWORD
DWORD
DWORD
InBuffer[4];
OutBuffer[4];
dwInBufferSize ;
dwOutBufferSize;
dwBytesReturned;
dwControlCode;
SCARD_CTL_CODE (3058)
0x10
0x11
memset(InBuffer, 0x00, sizeof(InBuffer));
memset(OutBuffer, 0x00, sizeof(OutBuffer));
dwControlCode
InBuffer[0]
dwInBufferSize
dwOutBufferSize
dwBytesReturned
=
=
=
=
=
CM_IOCTL_SIGNAL;
ACOUSTIC_SIGNAL_BEEPER_ON;
1;
0;
0;
SCard_Status = SCardControl( hCard,
dwControlCode,
(LPCVOID)InBuffer,
dwInBufferSize,
(LPVOID)OutBuffer,
dwOutBufferSize,
&dwBytesReturned );
// TODO: Code for PAY application
memset(InBuffer, 0x00, sizeof(InBuffer));
memset(OutBuffer, 0x00, sizeof(OutBuffer));
dwControlCode
InBuffer[0]
dwInBufferSize
dwOutBufferSize
dwBytesReturned
=
=
=
=
=
CM_IOCTL_SIGNAL;
ACOUSTIC_SIGNAL_BEEPER_OFF;
1;
0;
0;
SCard_Status = SCardControl( hCard,
dwControlCode,
(LPCVOID)InBuffer,
dwInBufferSize,
(LPVOID)OutBuffer,
dwOutBufferSize,
&dwBytesReturned );
// TODO: Code for PAY application
Page 95 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Appendix: B Accessing iCLASS Memory
The following describes the free zones of two typical iCLASS memory layouts.
Memory Layout
Shown is the memory layout of an iCLASS 2KS, iCLASS 16KS or page 0 of an iCLASS 8x2KS
card.
Block Number
Block Description (block size eight bytes)
‘00’
card serial number
‘01’
configuration block
’02’
e-Purse
‘03’
Kd (so-called debit key, key for application 1)
’04’
Kc (so-called credit key, key for Application 2)
’05’
application issuer area
‘06’
….
HID application
’12’
’13’
….
‘1F’ (2KS)
‘FF’ (16KS)
Free zones in iCLASS 2KS, iCLASS 16KS or page 0 of iCLASS 8x2KS
Shown is the memory layout of an iCLASS 8x2KS on pages 1 to 7.
Block
Size: 8 bytes
’00’
card serial number
’01’
configuration block
’02’
e-Purse
’03’
Kd (so-called debit key, key for application 1)
’04’
Kc (so-called credit key, key for Application 2)
’05’
application issuer area
’06’
….
application 1 (free zones in iCLASS 8x2KS other than page 0)
‘xx’
‘xx’+1
….
application 2 (free zones in iCLASS 8x2KS other than page 0)
‘1F’
January 2015
Page 96 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Appendix: C Application 2 - Assigning Space
By default, iCLASS cards have the application limit set to the last byte of its respective
memory area. This means the complete memory area is reserved for application 1 and the
size of application 2 is set to zero. The application limit can be set to a different block
number to support an additional application. To do this, the page’s configuration block
must be overwritten.
1.
Select the page you want to configure.
2. Authenticate with the selected page Kd.
3. Read 8 bytes from block 0x01 – the configuration block.
4. Replace the first byte with the block number ‘xx’ of the new application limit.
5. Leave the remaining bytes of the configuration block unchanged and write all 8 bytes
back to the configuration block 0x01.
6. Remove the card.
Page 97 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Appendix: D iCLASS Read/Write Memory - 2KS, 16KS or 8x2KS
page 0
1.
Insert card.
2. Connect to card.
3. For secured mode: Start Session.
4. Authenticate with KMC0 , (P1 = 0x01, P2 = 0x23).
If the key is not an iCLASS default key, the new key has to be loaded as KIAMC or KVAK ,
and in the authenticate command the key number of KIAMC or KVAK must be used.
5. Read/write any block (block number 0x13 to 0x1F for 2KS and 0xFF for 16KS).
6. For secured mode: End Session.
7. Disconnect from card.
8. Remove card.
January 2015
Page 98 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Appendix: E
1.
iCLASS 8x2KS Card - Pages 1 to 7 Read/Write
Memory
Insert card.
2. Connect to card.
3. For secured mode: Start Session.
4. Select page N (N = 1 to 7).
5. Authenticate with KMDN / KMCN (P1 = 0x00 for KMDN ,or 0x01 for KMCN , P2 = KMDN ,/
KMCN (See Section 8.1 Key Numbering Scheme).
6. If the key is other than iCLASS default key, the new key has to be loaded as KIAMC or
KVAK , and in the authenticate command the key number of KIAMC or KVAK must be
used.
7. Read/write any block (block number 0x13 to 0x1F for 2KS and 0xFF for 16KS).
8. For secured mode: End Session.
9. Disconnect card.
10. Remove card.
Page 99 of 102
January 2015
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Appendix: F
Terms and Abbreviations
The following lists abbreviations used throughout this document.
January 2015
CSNR
Card Serial Number
HDH
Host Data Header
INSData
Instruction Specific Data
KCUR
Customer Read Key
KCUW
Customer Write Key
KDOKM
OMNIKEY Diversified Master Key
KENC
Card Data Encryption Key
KIAMC
Key for Application 2 at page 0
KMCN
Page N Application 2’s Master Key of iCLASS card
KMDC
HID Master Key Current
KMDN
Page N Application 1’s Master Key of iCLASS card
KMDNB1
Page N Application 1’s on Book 1 Master Key of iCLASS card
KMDO
HID Master Key Old
KMTD
PicoPass Master Transport key for application 1
KMTC
PicoPass Master Transport key for application 2
KOKM
OMNIKEY Master Key
KS
Session Key
KVAK
Any Volatile Application Master Key
LcINS
Instruction specific data (INSData) length.
LcR
Card Response data length
PCD
Proximity Coupling Device
PICC
Proximity IC Card
PPSE
Proximity Payment System Environment
RDH
Reader Data Header
RSNR
Reader Serial Number
Page 100 of 102
OMNIKEY Contactless Smart Card Readers Developers Guide, 5321-903, Rev. B.4
Appendix: G References
[DESFIRE]
MIFARE DESFire Data Sheets
http://www.nxp.com/documents/short_data_sheet/MF3ICDX21_41_81_SDS.pdf
[EMVCo]
Europay Mastercard Visa Corporation
http://www.emvco.com/approvals.aspx?id=86
[ICLASSD]
iCLASS card specifications from HID.
[iCODE SL2]
ICODE SL2 Data Sheet
http://www.nxp.com/acrobat_download/other/identification/SL113730.pdf
[ISO7816-4]
Information Technology Identification Cards Integrated Circuit(s) Cards with Contacts, Part 4:
Inter-industry Commands for Interchange
[LRI64]
ST Microelectronics datasheet for LRI64
[MIFARE]
MIFARE Data Sheets
http://www.nxp.com/acrobat_download2/other/identification/M001053_MF1ICS50_rev5_3.
pdf
[MSDNLIB]
Microsoft Developer Network Library; http://msdn.microsoft.com/library/
[PCSC_2.01]
PC/SC Workgroup Specifications 2.01
http://www.pcscworkgroup.com/
[PICO2KS]
PICOTAG and PICOCRYPT secured 2KS data sheet from the Inside Contactless
[PICO16KS]
PICOTAG and PICOCRYPT secured 16KS data sheet from the Inside Contactless
Page 101 of 102
January 2015
hidglobal.com
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising