DWORDavmask.net

OMNIKEYContactlessSmartCardReadersDeveloperGuide5321-903,Rev.
B.
4January2015hidglobal.
comOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page2of102Contents1Purpose.
72ContactlessReaderCoverage73GettingStarted83.
1DriverInstallation.
83.
1.
1ReaderNameforContact/ContactlessSlot.
123.
2OMNIKEYWorkbench123.
2.
1PC/SCFunctionalityandReaderAvailability.
123.
2.
2DriverVersionDetection133.
2.
3OMNIKEYProprietaryAPIDetection133.
2.
4CardandReaderDetection.
143.
2.
5CardTypeDetectionandRFIDSettings.
163.
2.
6AirInterfaceBaudRateConfiguration.
174PC/SC2.
0.
184.
1HowtoAccessContactlessCardsthroughPC/SC.
184.
2ATRGeneration.
204.
2.
1CPUCards.
204.
2.
2StorageCards.
205AccessingAsynchronousCards215.
1MIFAREDESFireCard215.
1.
1Example:WriteCardDatathroughISO7816-4FramedAPDU.
215.
1.
2Example:ReadCardDatathroughISO7816-4FramedAPDU.
226AccessingSynchronousCards(Storage)236.
1MIFARECard236.
1.
1MIFAREIncrement(CardCommand)246.
1.
2MIFAREDecrement(CardCommand)246.
1.
3MIFAREEmulationMode.
256.
1.
4MIFAREApplicationDirectory(MAD)256.
2iCLASSCard.
266.
2.
1CardAccessthroughSCardCLICCTransmit.
266.
3STLRI64Support(PC/SC2.
0add-on)276.
3.
1UpdateBinary.
286.
3.
2ReadBinary296.
4ISO15693-3MemoryCardSupport.
297CommunicationwithMIFAREPlus307.
1ISO14443A–Part4cardcommunication307.
2ISO14443A–Part3cardcommunication.
307.
3OpenGenericSession.
317.
4GenericCardCommands317.
4.
1MIFAREPluscommandswiththeGENERICINTERFACECommandAPDUSamples.
327.
5CloseGenericSession.
328OMNIKEYContactlessSmartCardReaderKeys338.
1KeyNumberingScheme.
338.
2KeyContainerandSlots358.
3KeyUpdateRules369StandardCommunicationwithiCLASSCard379.
1APDUStructureforStandardCommunication.
379.
2CommandsAvailableinStandardCommunicationMode37OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page3of102January20159.
2.
1SelectPage(CardCommand)389.
2.
2LoadKey.
399.
2.
3GetKeySlotInfo(ReaderCommand)419.
2.
4Authenticate(CardCommand)429.
2.
5Read(CardCommand)439.
2.
6Update(CardCommand)449.
3CommunicationinStandardMode4510SecuredCommunicationwiththeiCLASSCard4610.
1Multi-StepApproachtoaSecureCardReaderSystem4610.
1.
1AuthenticitybetweenHostandReader.
4610.
1.
2ConfidentialityofUSBDataExchange.
4610.
1.
3IntegrityofTransmittedData.
4610.
1.
4AuthenticitybetweenReaderandCard4610.
1.
5IntegrityoftheRadioFrequency(RF)Transmission.
4610.
1.
6ConfidentialityoftheRFTransmission4710.
1.
7AuthenticationoftheHostforRead/WriteSession.
4710.
1.
8ProtectionagainstKnownAttacks.
4710.
2APDUStructureforSecuredCommunication.
4810.
2.
1DataHeader(DH)4910.
2.
2SignatureGeneration4910.
2.
3SessionKeyGeneration4910.
2.
4ProprietaryHostandReaderDatagramExample.
5010.
3Instructions(INS)forSecuredCommunication5110.
3.
1ManageSession(ReaderCommand)5110.
3.
2SelectPage(CardCommand)5210.
3.
3LoadKey(ReaderCommand)5210.
3.
4Authenticate(CardCommand)5210.
3.
5Read(CardCommand)5210.
3.
6Update(CardCommand)5210.
3.
7GetKeySlotInfo(ReaderCommand)5210.
3.
8UpdateCardKey.
5310.
4CommunicationatSecuredMode.
5410.
5SessionatSecuredModeAPDUsExample.
5511ReadingISO156935811.
1Products5811.
2Tags.
5811.
3Commands.
5911.
3.
1GetData.
5911.
3.
2PutData6011.
3.
3Lock6111.
3.
4GetSecurityStatus6211.
3.
5ReadBinaryCommand.
6411.
3.
6UpdateBinaryCommand.
6511.
3.
7UpdateSingleByteCommand.
6612OMNIKEY5321PAYApplicationInterface6712.
1PayPassCardTransactions6712.
2LEDandBuzzerControl.
6712.
2.
1SIGNALCommand–PayPassSignal.
6812.
2.
2SIGNALCommand–PayPassSignalMAINLED6812.
2.
3SIGNALCommand–PayPassSignalAdditionalLEDs6912.
2.
4SIGNALCommand–PayPassSignalTone6912.
3Switch-overtheOperatingMode.
70OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page4of10213DriverConfigurationviaProxFormat7113.
1Overview7113.
2ATRFormat.
7113.
2.
1ATRExample7113.
3AvailableProxFormatSettings.
7213.
3.
1ProxFormatSettingsonSystemsRunningWindows7313.
3.
2ProxFormatSettingsonSystemsRunningLinuxandMacOSX7314ProxFormatSettings7414.
1WiegandRawDataMode7414.
2StandardFormatModes.
7414.
3AutomaticMode.
7414.
4CustomFormatMode.
7514.
4.
1CustomProxFormatSettings7514.
5Example:H10301PROXCard7614.
5.
1StandardFormat.
7614.
5.
2WiegandRawData.
7614.
5.
3CustomProxFormatSettings7614.
5.
4ATRsofaH10301Card.
7614.
6Example:H10302PROXCard7714.
6.
1StandardFormat.
7714.
6.
2WiegandRawData.
7714.
6.
3CustomProxFormatSettings7714.
6.
4ATRsofaH10302Card.
7714.
7Example:H10304PROXCard.
7814.
7.
1StandardFormat.
7814.
7.
2WiegandRawData.
7814.
7.
3CustomProxFormatSettings7814.
7.
4ATRsofaH10304Card.
7814.
8Example:Corp1000PROXCard7914.
8.
1StandardFormat.
7914.
8.
2WiegandRawData.
7914.
8.
3CustomProxFormatSettings7914.
8.
4ATRsofaCorp1000Card.
79OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page5of102January2015Copyright2011-2015HIDGlobalCorporation/ASSAABLOYAB.
Allrightsreserved.
Thisdocumentmaynotbereproduced,disseminatedorrepublishedinanyformwithoutthepriorwrittenpermissionofHIDGlobalCorporation.
TrademarksHIDGLOBAL,HID,theHIDlogo,iCLASS,iCLASSElite,OMNIKEY,andSeosarethetrademarksorregisteredtrademarksofHIDGlobalCorporation,oritslicensors,intheU.
S.
andothercountries.
MIFARE,MIFAREDESFire,MIFAREDESFireEV1,andMIFAREUltralightareregisteredtrademarksofNXPB.
V.
andareusedunderlicense.
my-disaregisteredtrademarkofInfineonTechnologiesPayPassisaregisteredtrademarkofMasterCardDocumentHistoryVersionAuthor(s)DateDescriptionB.
4CT2014-01-20OMNIKEY5421,reformat.
B.
3J.
Maatuq2012-03-23-CorrectedproductnameOMNIKEY5321Pay->OMNIKEY5321PAY-Somelayoutchanges-typocorrectionsB.
2J.
Maatuq2012-02-09Addednewproducts4121CL,5021CL,5321CLi,5321Pay,5325ProxAddednewproductsanddocumentedWorkbenchAddedDriverConfigurationviaProxFormatandProxFormatSettingssectionB.
1WWaitz2010-11-10AddediCLASSEliteenabledreaders.
Modifiedsection10.
3.
4GetSecurityStatusB.
0WWaitz2010-08-05MIFAREPlus,PAYAPIandReviewA.
1.
19SSchwab2009-07-17Chapter9,supportedtagsA.
1.
18SSchwab2009-07-16AddedfootnotesforiCodeSL2A.
1.
17WWaitz2009-05-13Reviewtoversion1.
16anderrorcorrectionA.
0TMuth2009-02-16UpdatedtoHIDtemplateOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page6of102FirmwareHistoryFWVersionSpecialFeaturesRemarks5.
20,1.
75MIF,MKS,IST,ISE,EMD,HSK,iCLASSsecuredmode,HIDapplicationread,iCLASSHighSecurityKeysupported,EMDSuppressioninfirmwaresupported,EMVCoContactlessL15.
10MIF,MKS,IST,ISEiCLASSsecuredmode,HIDapplicationread5.
00MIF,MKS,IST,ISEiCLASSsecuredmode,HIDapplicationread1.
03,1.
04MIF,MKS,ISTiCLASSmemoryaccess1.
01,1.
02MIF,MKS1.
00MIFMIFAREsupportSynchronousCardSpecialFeaturesMIF=MIFAREFunctionalitiesMKS=MIFAREKeyStorageMSK=MIFARESecuredKeyLoadingIST=iCLASSStandardModeCommunicationISE=iCLASSSecuredModeCommunicationEMD=ElectromagneticDisturbanceHSK=HighSecurityKeyContactsForadditionalofficesaroundtheworld,seewww.
hidglobal.
comcorporateoffices.
Americas&CorporateAsiaPacific611CenterRidgeDriveAustin,TX78753USAPhone:866-607-7339Fax:949-732-212019/F625King'sRoadNorthPoint,IslandEastHongKongPhone:85231609833Fax:85231604809Europe,MiddleEastandAfricaBrazilPhoenixRoadHaverhill,SuffolkCB97AEEnglandPhone:+441440711822Fax:+441440714840CondomínioBusinessCenterAv.
ErmanoMarchetti,1435GalpoA2CEP05038001Lapa-SoPaulo/SPBrazilPhone:55115514-7100HIDGlobalCustomerSupport:support.
hidglobal.
comOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page7of102January20151PurposeThisisaguidefordevelopersintegratingcontactlessstorageorCPUcardsusingOMNIKEYContactlessSmartCardreaders.
2ContactlessReaderCoverageThefollowingOMNIKEYcontactlessreadersarecoveredbythisdocument:OMNIKEY4121CLMobileSmartCardincludinganExpressCardinterfacewiththesamefunctionalityasOMNIKEY5321,butithasacontactlessinterface.
OMNIKEY5021CLDesktopreaderinaclosedsmallhousingwiththesamefunctionalityastheOMNIKEY5321,butacontactless-onlyreader.
OMNIKEY5321DesktopSmartCardreaderwithcontactandcontactlessinterface,contactlessinterfacefeaturingfullcontactlessfunctionalityasdescribedinthisdevelopersguide.
OMNIKEY5321CLDesktopreaderinaclosedhousing,samefunctionalityasOMNIKEY5321butcontactless-onlyreader.
OMNIKEY5321CRDesktopreaderinawaterproof(CleanRoom)closedhousing,samefunctionalityasOMNIKEY5321butcontactless-onlyreader.
OMNIKEY5321CLiDesktopSmartCardreaderinaclosedhousing,withcontactless-onlyinterface.
ContactlessinterfacesupportsiCLASS-only.
OMNIKEY5321PAYDesktopreaderinaclosedhousing,samefunctionalityasOMNIKEY5321.
HasEMVCoTerminalLevel1approvalaccordingtoEMV2.
0specification[EMVCo].
OMNIKEY5325ProxDesktopSmartCardreaderwithcontactandcontactlessinterface.
Contactlessinterfacefeaturesoperatingon125kHz(Prox).
Section3PC/SC2.
0isapplicableforthisreader.
OMNIKEY5421DesktopSmartCardreaderwithcontactandcontactlessinterface.
ThefunctionalityisthesameastheOMNIKEY5321,butitusesadifferenttransceiverchip.
OMNIKEY6321MobileSmartCardreaderwithSIM-sizedcontactandcontactlessinterface.
Contactlessinterfacefeaturesfullcontactlessfunctionality.
OMNIKEY6321CLiMobileSmartCardreaderwithcontactless-onlyinterface.
ContactlessinterfacesupportsiCLASSonly.
ReaderswithiCLASSEliteKeyAllenablediCLASSEliteKeyreaders(listpreviously)arecoveredbythisdocument.
AllreaderslistedarebasedontheOMNIKEYContactlessSmartCardRFIDchipset.
Thereforethisdocumentusestheterm5x21toreferencetheseOMNIKEYreaders.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page8of1023GettingStartedThischapterdescribeshowtoinstallthedriversnecessarytooperatetheOMNIKEYContactlessSmartCardreaderinaWindowsbasedenvironment.
Note:Otheroperatingsystems,suchasLinux,arealsosupportedbytheOMNIKEYContactlessSmartCardreader.
3.
1DriverInstallationTheOMNIKEYContactlessSmartCarddriverismandatoryforallsystemsthatrequiresupportforcontactlesssmartcards.
OMNIKEYContactlessSmartCardreaderisaCCIDcompliantdevice.
ThismeansthatthecontactinterfacecanbeoperatedwithoutanOMNIKEYproprietarydriverinstalled.
However,forcontactlesscards,theOMNIKEYproprietaryOMNIKEYContactlessSmartCarddriverisnecessary.
ThefollowingstepsdescribehowtoinstalltheOMNIKEYContactlessSmartCarddriver:1.
Gotohttp://www.
hidglobal.
com/omnikey.
Basedontheappropriatereader,clickthedrivericon.
DownloadthelatestOMNIKEYContactlessSmartCarddriverinstallationpackageforWindows.
2.
Runtheinstallationpackageandfollowtheinstructions.
Theinstallationpackageextractsallthenecessarydriverfilestoyourharddrive.
Takenoteofthelocationtowhichthefileswerecopied.
3.
ConnectthereadertoyourcomputersUSBport.
Atthistimeyouhaveonlyextracted,notinstalledthedriverfiles.
4.
TheFoundNewHardwareWizardappears.
Tocontinuedriverinstallation,clickNext.
Note:OnWindowsXPsystems,theMicrosoftWindowsCCIDClassdrivermaybeactivatedwithoutshowingtheFoundNewHardwareWizard.
Ifthisisthecase,replacetheMicrosoftPC/SCdrivermanuallywiththeOMNIKEYproprietaryPC/SCdriverusingtheDeviceManager.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page9of102January20155.
SelectSearchforasuitabledriverformydevice(recommended)andclickNext.
6.
Then,selectSpecifyaLocationandclickNext.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page10of1027.
ClickBrowseandgotothelocationwhereyoupreviouslyinstalledthedriverpackage.
Tocontinue,clickOK.
8.
Ifthedriverwasfound,clickNext.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page11of102January20159.
Ifthedriverisabetadriverandnotdigitallysigned,thefollowingdialogueappears.
ClickContinueAnyway.
10.
ThefollowingmessageappearsandthegreenLEDilluminatesontheOMNIKEYContactlessSmartCardreader.
Iftheinstallationwassuccessful,thegreenLEDonthereaderilluminatesandthereaderislistedintheOMNIKEYWorkbenchasOMNIKEYContactlessSmartCardreader.
Yourreaderisreadyforuse.
DoaquicksmartcardsystemcheckusingtheOMNIKEYWorkbenchdescribedinSection3.
2OMNIKEYWorkbench.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page12of1023.
1.
1ReaderNameforContact/ContactlessSlotTheOMNIKEYContactlessSmartCardreaderisadualslotreader.
Thismeansthatfromtheapplicationandsmartcardresourcemanagerviewpointtherearetworeadersavailable,eachrepresentedbyitsrespectivereadername.
OMNIKEYCardMan5x21nidentifiesthecontactslotandOMNIKEYCardMan5x21-CLnstandsforthecontactlessslot.
Thenrepresentsaslotnumber0,1…etc.
Thisallowscardtrackingthroughthecontactandairinterface.
3.
2OMNIKEYWorkbenchTheOMNIKEYWorkbenchprovidesaquicktestofthesmartcardsystem.
ItlistsallavailableOMNIKEYreaders,driverfileswithversion,firmwareversion,andallowstheconfigurationoftheRFID/airinterface.
Gotohttp://www.
hidglobal.
com/omnikey>selecttheOMNIKEYReader>clickthedrivericontodownloadthelatestOMNIKEYWorkbenchforWindows.
StartformerversionsoftheDiagnosticToolfromtheControlPanel.
3.
2.
1PC/SCFunctionalityandReaderAvailabilityTheGeneralInformationapplicationshowsinthePC/SCFunctionalitytabiftheResourceManagerisrunningandlistsallconnectedOMNIKEYreaders.
Figure1:PC/SCFunctionalityOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page13of102January20153.
2.
2DriverVersionDetectionInaddition,theFileVersionstabshowssmartcardsystemservicesversion,manufacturerdataanddriverfiles.
Figure2:FileVersion3.
2.
3OMNIKEYProprietaryAPIDetectionTheAPItabshowstheAPIsinstalledonyoursystem,includingtheOMNIKEYSynchronousAPI.
Figure3:APIOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page14of1023.
2.
4CardandReaderDetectionTheOMNIKEYWorkbenchcreatesaseparateentryforeachavailableOMNIKEYreaderinterfaceintheapplicationtable.
Theentriesindicatetheirrespectivereadernames-thesamenamesyouusewithinthePC/SCframework.
Clickanentrytoopenthereader'sinformationandsettings.
Foraquickconnectivitytestofyourcontactlesscard,1.
SelecttheOMNIKEYCardMan5x21-CL0tab2.
Placeacontactlesscardonthereader.
3.
Whenthecardisdetected,theStatusfieldswitchesfromNosmartcardinsertedtoSmartcardinsertedandtheATRfielddisplaysthecard'sATR.
SeeSection4.
2ATRGeneration,forfurtherinformationonhowtheAnswertoReset(ATR)isgeneratedforcontactlesssmartcards.
TheOMNIKEYWorkbenchhasaninternalflatdatabasethatallowsaquicklookupoftheATR.
Ifitisaknowncard,adescriptiondisplaysintheSmartCardNamefield.
Forcontactlesscardsthecard'suniqueID(UID)displaysintheSmartCardNamefieldandintheProtocolfieldthecardstandardforexample,T=CLandtheselectedbaudratedisplays.
Figure4:ReaderView-NoSmartCardOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page15of102January2015Figure5:ReaderView-SmartCardInsertedOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page16of1023.
2.
5CardTypeDetectionandRFIDSettingsOMNIKEYContactlessSmartCardreadersupportsmultiple13.
56MHzcontactlessstandardsandprotocolsincludingISO14443A,ISO14443B,ISO15694,iCLASS,I-CODE.
AcquireinformationaboutacardwithintheRFIDfieldinapredefinedsearchorder.
Withbuilt-inanti-collision,onceacardisdetecteditistheonlycardinwhichthereaderisconnected.
TheOMNIKEYWorkbenchhasaRFIDSettingstabwithinthereaderviewthatallowsconfigurationofthereadercardandtheirrespectivesearchorder.
SeeSection3.
2.
4CardandReaderDetection.
Figure6:RFIDSettingsTheleftpanecontainsalistofactivecardtypes.
Therightpanecontainsalistofavailablecardtypesthataresupportedbythereaderbutarenotincludedinthecardsearch.
Movecardtypesfromthelefttotherightpaneusingtheandbuttons.
Changethesearchorderwiththeandbuttons.
ActivatethissettingusingtheApplybutton.
TheResetbuttondiscardsanyunsavedchanges.
Note:Thesearchorderisforward-lookingtoimprovesystemperformance.
Thelastsuccessfullydetectedcardtypeautomaticallymovestothetopofthesearchorder,regardlessofitspositionwithintheordersetontheRFIDSettingstab.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page17of102January20153.
2.
6AirInterfaceBaudRateConfigurationForISO14443cards,theairinterfacetransmissionspeedcanbe106kbps,212kbps,424kbps,or848kbps.
Bydefault,thecontactlessinterfaceissetto424kbps.
ChangetheinterfacetransmissionspeedtoadifferentvaluethroughtheOMNIKEYWorkbenchBaudratesettingstab.
Figure7:RFIDSettingsTovieworchangethebaudrate,selectthecardtype(ISO14443AorISO14443B)andchangethemaximumBaudRatefield.
Finalizeyoursetting,clickApply.
Figure8:BaudRateSettingsOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page18of1024PC/SC2.
0WiththeOMNIKEY5x21PC/SCdriver,accessISO14443A/BorISO15693contactlesscardsthroughthesameframeworkasISO7816contactcards.
ThismakescardintegrationasnapforanydeveloperwhoisalreadyfamiliarwithPC/SC.
EvenvaluablePC/SCresourcemanagerfunctions,suchascardtracking,areavailableforcontactlesscardintegration.
TheMicrosoftDeveloperNetwork(MSDN)LibrarycontainsvaluableinformationandacompletedocumentationoftheSCardAPIwithintheMSDNPlatformSDK.
Seehttp://msdn.
microsoft.
com/en-us/library/ms953432.
aspx.
YoucandirectlyaccesscontactlessCPUcardsthroughthePC/SCdriver.
ForstoragecardsotherthanMIFARE,anadditionallibrary–theOMNIKEYsynchronousAPI–isnecessary.
WhetherusingdirectPC/SCaccessortheOMNIKEYsynchronousAPI,onlyasmallsetoffunctionsarerequiredtowriteyourfirsthellocardprogram.
Integrateyourcardthrough:PC/SC2.
0compliantAPDU'sOMNIKEYSynchronousAPIMIFAREYESYESiCLASSNOYESLRI64YESNO4.
1HowtoAccessContactlessCardsthroughPC/SCThefollowingstepsprovideaguidelinetocreateyourfirstcontactlesssmartcardapplicationusingindustrystandard,PC/SCcompliantAPIfunctioncalls.
ThefunctiondefinitionsprovidedaretakenverbatimfromtheMSDNLibrary[MSDNLIB].
ForadditionaldescriptionsoftheseandotherPC/SCfunctionsprovidedbytheMicrosoftWindowsPC/SCsmartcardcomponents,referdirectlytotheMSDNLibrary.
Seehttp://msdn.
microsoft.
com/en-us/library/ms953432.
aspx.
1.
EstablishContextThisstepinitializesthePC/SCAPIandallocatesallresourcesnecessaryforasmartcardsession.
TheSCardEstablishContextfunctionestablishestheresourcemanagercontext(scope)withinwhichdatabaseoperationsisperformed.
LONGSCardEstablishContext(INDWORDdwScope,INLPCVOIDpvReserved1,INLPCVOIDpvReserved2,OUTLPSCARDCONTEXTphContext);2.
GetStatusChangeCheckthestatusofthereaderforcardinsertion,removal,oravailabilityofthereader.
ThisSCardGetStatusChangefunctionblocksexecutionuntilthecurrentavailabilityofthecardsinaspecificsetofreaderschange.
Thecallersuppliesalistofmonitoredreadersandthemaximumwaittime(inmilliseconds)foranactiontooccurononeofthelistedreaders.
LONGSCardGetStatusChange(INSCARDCONTEXThContext,INDWORDdwTimeout,INOUTLPSCARD_READERSTATErgReaderStates,INDWORDcReaders);OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page19of102January20153.
ListReadersGetsalistofallPC/SCreadersusingtheSCardListReadersfunction.
LookforOMNIKEYCardMan5x21-CL0inthereturnedlist.
IfmultipleOMNIKEYContactlessSmartCardreadersareconnectedtoyoursystem,theywillbeenumerated.
Example:OMNIKEYCardMan5x21-CL1,andOMNIKEYCardMan5x21-CL2.
Analyzethecompletestring.
OMNIKEYCardMan5x21alsohasacontactinterface.
Lookfor-CLinthereadernametoensureyouarereferringtothecontactlessinterfaceinthefollowingcalls.
LONGSCardListReaders(INSCARDCONTEXThContext,INLPCTSTRmszGroups,OUTLPTSTRmszReaders,INOUTLPDWORDpcchReaders);4.
ConnectConnecttothecard.
TheSCardConnectfunctionestablishesaconnection(usingaspecificresourcemanagercontext)betweenthecallingapplicationandasmartcardcontainedbyaspecificreader.
Ifnocardexistsinthespecifiedreader,anerrorisreturned.
LONGSCardConnect(INSCARDCONTEXThContext,INLPCTSTRszReader,INDWORDdwShareMode,INDWORDdwPreferredProtocols,OUTLPSCARDHANDLEphCard,OUTLPDWORDpdwActiveProtocol);5.
ExchangeDataandCommandswiththeCardExchangecommandanddatathroughAPDUs.
TheSCardTransmitfunctionsendsaservicerequesttothesmartcard,expectingtoreceivedatabackfromthecard.
LONGSCardTransmit(INSCARDHANDLEhCard,INLPCSCARD_I0_REQUESTpioSendPci,INLPCBYTEpbSendBuffer,INDWORDcbSendLength,INOUTLPSCARD_IO_REQUESTpioRecvPci,OUTLPBYTEpbRecvBuffer,INOUTLPDWORDpcbRecvLength);Note:ForunsupportedPC/SC2.
0storagecards,callanOMNIKEYproprietaryAPIfunctionsuchasSCardCLICCTransmitinstead.
ThisfunctionexposesadditionalfunctionalityoftheOMNIKEY5x21-CLreaderthatisnotyetdefinedinPC/SCstandards.
Otherwise,youarestillusingthestandardPC/SCframeworktotrackcards,listreaders,etc.
Eventhesmartcardhandleisthesame.
6.
DisconnectItisnotnecessarytodisconnectthecardafterthecompletionoftransactions,butitisrecommended.
TheSCardDisconnectfunctionterminatesaconnectionpreviouslyopenedbetweenthecallingapplicationandasmartcardinthetargetreader.
LONGSCardDisconnect(INSCARDHANDLEhCard,INDWORDdwDisposition);7.
ReleaseThisstepensuresallsystemresourcesarereleased.
TheSCardReleaseContextfunctionclosesanestablishedresourcemanagercontext,freeinganyresourcesallocatedunderthatcontext.
LONGSCardReleaseContext(INSCARDCONTEXThContext);OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page20of1024.
2ATRGenerationUnlikecontactcards,contactlesscardsdonotgenerateanATR.
Instead,theygenerateanAnswertoSelect(ATS).
TomakecontactlesscardsavailablewithinthePC/SCframework,OMNIKEYContactlessSmartCardreadergeneratesaPC/SCcompliantATRaccordingtoPC/SCv2.
01.
DownloadthedocumentsfromthePC/SCWorkgroupatthefollowingwebaddress:http://www.
pcscworkgroup.
com/specifications/specdownload.
php.
4.
2.
1CPUCardsContactlesssmartcards(cardswithaCPU)exposetheirATSorinformationbytesthroughATRmappingaccordingtoPC/SC2.
01-Part3:RequirementsforPC-ConnectedInterfaceDevices,section3.
1.
3.
2.
3.
1ContactlessSmartCards,Table3.
5.
4.
2.
2StorageCardsTheATRofstoragecards(forexample,cardswithoutaCPU)iscomposedasdescribedinPC/SC2.
01-Part3:RequirementsforPC-ConnectedInterfaceDevices,section3.
1.
3.
2.
3.
2ContactlessStorageCards,Table3.
6.
Forthehostapplicationtoidentifyastorageandcardtypeproperly,itsstandardandcardnameismappedaccordingtoPC/SC2.
01-Part3:RequirementsforPC-ConnectedInterfaceDevices-SupplementalDocument.
Note:TheRegisteredApplicationProviderIdentifier(RID)returnedbytheOMNIKEYContactlessSmartCardreaderforstoragecards(cardswithoutaCPU)isA00003060A,indicatingaPC/SCcompliantATRgeneration.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page21of102January20155AccessingAsynchronousCardsAsynchronouscardscontainaCPUorarememorycardsaccessiblethroughstandardPC/SCusingMicrosoft'slibrarywinscard.
dll.
ThistypeofcardsupportsatleastoneoftheasynchronousprotocolsT=0orT=1.
TheMicrosoftPlatformSDKcontainsPC/SCsamplecodeforVisualC/C++andVisualBasic.
Noadditionallibrariesorthird-partysoftwarecomponentsarenecessarytointegratecontactlessCPUcards.
5.
1MIFAREDESFireCardMIFAREDESFirecardsareaccessedthroughISO7816-4compliantframedAPDUcommands(ISO7816-4framing).
NewversionsofMIFAREDESFireEV1cardssupportextendedAPDUcommands.
ForthisthedrivermustswitchtoMIFAREDESFirenativemode.
ThisnativemodeisnotdefaultfortheOMNIKEYContactlessSmartCardreader.
Forproperprotocolsettingsusethefollowingregistrykey:HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\RFIDDesfireNative=0x00000001Note:RestarttheOMNIKEYContactlessSmartCarddriverafterchangingtheregistrykey(disconnectandreconnectthereader).
5.
1.
1Example:WriteCardDatathroughISO7816-4FramedAPDUCommandSyntaxCLAINSP1P2LcFileNo.
OffsetLengthDataLe'90''3D''00''00''xx''xx''xxxxxx''xxxxxx''xx'…'xx''00'Lc=7+DataLength;Le=0(noothervaluesaccepted)ResponseSyntaxResponseDataSW1SW2empty'xx''xx'StatusCodesSW1SW2Description'90''00'success'91''xxerror(seetheMIFAREDESFiredatasheet)OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page22of1025.
1.
2Example:ReadCardDatathroughISO7816-4FramedAPDUCommandSyntaxCLAINSP1P2LcFileNo.
OffsetLengthDataLe'90''BD''00''00''07''xx''xxxxxx''LLLLLL'empty'00'Le=0(noothervaluesaccepted)ResponseSyntaxResponseDataSW1SW2'xx'.
.
.
'xx'('LLLLLL'bytes)'xx''xx'StatusCodesSW1SW2Description'90''00'success'91''xxerror(seetotheMIFAREDESFiredatasheet)OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page23of102January20156AccessingSynchronousCards(Storage)OMNIKEYprovidestwowaystointegratecontactlessstoragecards.
OneoptionisOMNIKEY'sproprietarysynchronousAPIlibrary,orforMIFAREcards,directlythroughPC/SC2.
0compliantfunctioncalls.
AccessstoragecardsnotsupportedthroughPC/SC2.
0compliantAPDUexchangesthroughOMNIKEYproprietarysynchronousAPI.
ThesynchronousAPIforWindowssystemsresidesinaDLLnamedscardsyn.
dll.
DownloadtheSynchronousAPIforOMNIKEYContactlessSmartCardreadersfromwww.
hidglobal.
com/omnikeyandexecutethesetupCardMan_Synchronous_API_V2_0_0_0.
exe.
ThesetupincludesthisDLL.
ThedownloadalsocontainssamplecodeforMIFAREandiCLASScards.
ForinformationaboutthisAPI,referencethehelpfilecmsync.
hlpavailableinthec:\ProgramFiles\HIDGlobal\Sync-API\HelpfolderafterinstallationofthesynchronousAPIwithdefaultsettings.
TheOMNIKEYSynchronousAPIisusedwheneveracardhasnotyetfounditswayintothePC/SC2.
0standard.
Currently,onlyMIFAREcardscanbeintegratedthroughPC/SC2.
0compliantAPDU.
IntegrateCardthroughPC/SC2.
0compliantAPDUsOMNIKEYSynchronousAPIMIFAREYesYesiCLASSNoYesNospecialdriversarerequiredforPC/SC2.
0compliantcardintegrationwithWindowsorLinux.
OMNIKEY'slatestdriversprovideseamlesscross-platformsupportallowingindustrystandard-compliantcontactlesscardintegration.
6.
1MIFARECardOMNIKEYContactlessSmartCardreaderssupportMIFAREMini,MIFARE1K,MIFARE4KandMIFAREUltralightcards.
ThefollowingfunctionsaresupportedthroughPC/SC:GetUIDImplementedaccordingto[PCSC2.
01]LoadKeyAuthenticateVerifyUpdateBinaryReadBinaryIncrementOMNIKEYproprietaryextensionofPC/SCDecrementOMNIKEYproprietaryextensionofPC/SCMIFAREEmulationModeOMNIKEYproprietaryextensionofPC/SCCM_IOCTL_SET_RFID_CONTROL_FLAGSReferencethe[PCSC2.
01]and[MIFARE]fordocumentationofPC/SC2.
0compliantMIFAREcardaccess.
Thefollowingsectiononlydescribesusageoffunctionsthatarenotalreadydocumentedin[PCSC2.
01].
TheyarepartofanOMNIKEYproprietaryextensionofPC/SC.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page24of1026.
1.
1MIFAREIncrement(CardCommand)Thiscommandincrementsthevalueofablock,ifthecardandblocksupportsthisfunctionality:CommandSyntaxCLA'FF'INS'D4'P1MSBofblockaddressP2LSBofblockaddressLC4DataFieldFourbytesvalueindicatingblockincrement(LSBfirst)LeemptyResponseSyntaxDataFieldEmptySW1SW2statuswordasdescribedbelow'90''00'Success'65''81'memoryfailure(unsuccessfulincrement)'69''81'incompatiblecommand'69''82'securitystatusnotsatisfied'69''86'commandnotallowed'6A''81'functionnotsupported'6A''82'invalidblockaddress6.
1.
2MIFAREDecrement(CardCommand)Thiscommanddecrementsthevalueofablock,ifthecardandblocksupportthisfunctionality:CommandSyntaxCLA'FF'INS'D8'P1MSBofblockaddressP2LSBofblockaddressLC4DataFieldFourbytevalueindicatingblockdecrement(LSBfirst)LeEmptyResponseSyntaxDataFieldEmptySW1SW2statuswordasdescribedbelow'90''00'Success'65''81'memoryfailure(unsuccessfuldecrement)'69''81'incompatiblecommand'69''82'securitystatusnotsatisfied'69''86'commandnotallowed'6A''81'functionnotsupported'6A''82'invalidblockaddressOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page25of102January20156.
1.
3MIFAREEmulationModeBydefault,theOMNIKEYContactlessSmartCarddriverexposesstandardMIFAREstoragecardsthroughaPC/SC2.
01compliantinterface.
Thisdriver-levelMIFAREemulationmodemakesstandardMIFAREcardsavailablethroughstandardAPDUseventhoughthecarditselfdoesnotsupportanyasynchronousprotocolssupporteddirectlybynativePC/SCcomponents.
Dual-interfacecardsworkdifferently.
TheirCPUsupportscommunicationthroughISO14443Apart4(T=CL)allowingon-cardMIFAREemulationratherthanhost-sideMIFAREemulation.
ThismeansthatOMNIKEYContactlessSmartCardreader'sdefaultmode(forexample,host-sideMIFAREemulation)mustbedisabledtosupporttheon-cardMIFAREemulationofadial-interfacecard.
Therearetwowaystoswitchbetweenhost-sideandcard-sideMIFAREemulation:1.
Registrykeys2.
IOcontrolsusingthePC/SCfunctionScardControl()asdescribedinAppendixA2.
8MIFAREEmulationMode(OMNIKEYProprietaryAPI).
ThefollowingregistrykeysletyouswitchbetweenOMNIKEYMIFAREemulationmode(default)andon-cardMIFAREemulation.
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\RFIDControlFlags=0x00000004OMNIKEY'shost-sideMIFAREemulationONdefaultControlFlags=0x00000000OMNIKEY'shost-sideMIFAREemulationOFFT=CL,foron-cardMIFAREemulationNote:RestarttheOMNIKEYContactlessSmartCarddriverafterchangingtheregistrykeys(disconnectandthenreconnectthereader).
6.
1.
4MIFAREApplicationDirectory(MAD)ToaccesstheMIFAREApplicationDirectory(MAD),twocommandsarenecessary–AuthenticateandRead.
ThefollowingstepsdescribehowtoretrieveaMADfromaMIFAREcard:1.
Authenticateblock3withthePublickeyA0A1A2A3A4A5andauthenticationmodeA.
2.
ReadBlock3.
3.
ReadBlock2.
4.
ReadBlock1.
Forinformationabouttheblockcontentsee:http://www.
nxp.
com/acrobat_download2/other/identification/,001830.
pdfhttp://www.
mifare.
netOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page26of1026.
2iCLASSCardOnlyaccessiCLASScardsthroughOMNIKEY'sproprietaryscardsynAPI.
ThissynchronousAPIcontainsafunctionthatisdedicatedtoaccessingcontactlesscardsusingthestandardPC/SCcardhandle.
OMNIKEYContactlessSmartCardreadersexposealliCLASSfunctionsnecessarytoaccessanyoftheapplicationareasonaniCLASScard.
Thetwomodesofcommunicationsupportedare:1.
Standardmodecommunication2.
Securedmodecommunication(OMNIKEYproprietarymode)Note:OMNIKEYContactlessSmartCardreadersdonotallowWRITEaccesstotheHIDapplication(1stapplicationonpage0).
ForREADaccesstotheHIDapplication,securedcommunication(availableforfirmwareversion5.
00andgreater)ismandatory.
Note:StandardreadersprovidesecuredmodecommunicationonlybetweenstandardHIDiCLASS.
However,thereisalsoapossibilityforsecuredmodecommunicationbetweenHIDiCLASSElitecards(availableforfirmwareversion5.
20andgreater).
Fordetails,contactyourlocalSalesRepresentative.
6.
2.
1CardAccessthroughSCardCLICCTransmitSCardCLICCTransmitistheOMNIKEYproprietaryfunctiontoaccessHIDiCLASScardsthroughtheOMNIKEYsynchronousAPI.
Itsupportsboth,standardandsecurecommunicationmodesandisdefinedasfollows:OKERRENTRYSCardCLICCTransmit(INSCARDHANDLEulHandleCard,INPUCHARpucSendData,INULONGulSendDataBufLen,INOUTPUCHARpucReceivedData,INOUTPULONGpulReceivedDataBufLen);ParameterDescriptionulHandleCardhandletothecard,providedfromthePC/SCsmartcardresourcemanagerafterconnectingtothecardwithSCardConnectpucSendDatabufferfordatasenttothereader/card,typicallyacommandAPDUulSendDataBufLenlengthofthedatatobesentpucReceivedDatabufferfordatareceivedfromreader/card,typicallydataandstatuspulReceivedDataBufLenbeforethecall:length(inbytes)ofthereceivebufferafterthecall:numberofbytesactuallyreceivedCommandSyntaxCLAINSP1P2LcInputDataorDatagram***Le'8x''xx''xx''xx''xx''xx'.
.
.
'xx'(Lcbytes)'xx'ResponseSyntaxResponseDataorDatagram***SW1SW2'xx'.
.
'xx'(Leormaxbytes)'xx''xx'OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page27of102January2015StatusCodesSW1SW2Description'90''00'success'64''00'cardexecutionerror'67''00'wronglength'68''00'invalidclass(CLA)byte'69''82'securitystatusnotsatisfied.
Thiscanincludewrongdatastructure,wrongkeys,incorrectpadding.
'6A''81'invalidinstruction(INS)byte'6B''00'wrongparameterP1orP2TheerrorcodesdefinedinthepreviousStatusCodestablearevalidforallthecommands.
Commandspecificerrorcodesaredocumentedwiththeirrespectivecommanddocumentation.
Note:Theerrorcode6982securitystatusnotsatisfied,receivedduringsecuredcommunication,blocksanyfurthercommands.
Removeandreinsertthecardtoreactivatecommunicationwiththecard.
6.
3STLRI64Support(PC/SC2.
0add-on)STMicroelectronics'LRI64isamemorytagICwith64-bitUniqueID(UID)andWORMuserarea.
ThefollowingtablelistsPC/SC2.
01compliantfunctionsthatareavailableforLRI64basedstoragecards.
GetUIDimplementedaccordingto[PCSC2.
01]UpdateBinaryReadBinaryThisISO15693compliantICisnotaccessiblewithstandarddriversettings.
Itrequiresthefollowingregistrykeysetting:[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\RFID]"ControlFlags"=dword:00000010Seethe[PCSC2.
01]and[LRI64]fordocumentationofPC/SC2.
0compliantLRI64cardaccess.
Thefollowingsectiondescribesusageoffunctionsthatarenotalreadydocumentedin[PCSC2.
01].
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page28of1026.
3.
1UpdateBinaryUpdateBinaryrequiresblocknumberswithintheWORMmemoryarea(Write-OnceRead-Many).
Examples:Write'121314'toblock'0D'(decimal12):CommandAPDU:'FFD6000D03121314'ResponseAPDU:'9000'Attempttowrite'101112toblock'0A'(10decimal):CommandAPDU:'FFD6000A03101112'ResponseAPDU:'6282'Forblocks10and11thisworksoutfine,however,becausewepreviouslywrotetoblock12,thecardrespondswith'6282'EndoffilereachedbeforewritingLcbytes.
Afterthefirstwriteaccesstoblock12onlyreadoperationsaresupported.
ThefollowingAPDUattemptstowritetoblock7:CommandAPDU:'FFD6000701FF'ResponseAPDU:'6581'Thecardrespondswith'6581'Memoryfailure(unsuccessfulwriting)becausethisisaUIDbyte-writeaccesstotheUIDareaisalwayslocked.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page29of102January20156.
3.
2ReadBinaryTheReadBinarycommandisavailableforallblocksoftheLRI64chip.
Examples:Readingall15blocksfrom0to14CommandAPDU:'FFB0000000'ResponseAPDE:'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx9000'Attempttoread16blocksCommandAPDU:'FFB0000010'ResponseAPDE:'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx6282'Theresponseis'6282'orEndoffilereachedbeforereadingexpectednumberofbytes.
Eventhoughthewarning'6282'isreturned,allbytesfromblock0uptoblock14arereadcorrectly.
Readblocks10and11(2bytes)CommandAPDU:'FFB0000A02'ResponseAPDE:'xxxx9000'Attempttoreadaninvalidblocknumber:CommandAPDU:'FFB0000F01'ResponseAPDE:'6A82'Theresponseistheerrorcode'6A82'becauseblocknumber15doesnotexist.
6.
4ISO15693-3MemoryCardSupportFordetailedinformationaboutsupportedISO15693Tags,referenceSection10ReadingISO15693,page58.
READBINARYandUPDATEBINARYiscomplianttoPS/SC2.
01.
SeeSection4PC/SC2.
0.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page30of1027CommunicationwithMIFAREPlusDependingonthecardsecuritylevel,thereaderactivatestheMIFAREPluscardintheISO14443ALayer3orintheISO14443ALayer4(T=CL).
SecurityLevelProtocolTypeMIFAREPlusSL0ISO14443A–4MIFAREPlusSL1ISO14443A–3MIFAREPlusSL2ISO14443A–3MIFAREPlusSL3ISO14443A–4Note:TheOMNIKEYsynchronousAPIdoesnotsupportthenewMIFAREPluscards(forexampleSL1cards).
UsethecommandsetfromPC/SC2.
01part3.
TheMIFAREfunctionsfromthesampleapplication,contactlessdemoVCandcontactlessdemoVBrequirethesynchronousAPI.
TheseapplicationsdonotworkwithMIFAREPluscards.
7.
1ISO14443A–Part4cardcommunicationIfthecardisactivatedinprotocollayer4,theapplicationcommunicateswiththeMIFAREPluscardbycallingSCardTransmit.
ThecardcommandistransferreddirectlytotheMIFAREPluscardbyusingtheT=CLprotocollayer.
TheT=CLprotocollayeriscompletedbythedriver.
TheapplicationusesthistypeofcommunicationforallcardcommandsinSL0andSL3.
ForMIFAREPlusdetails,referencetheMIFAREPlusdatasheetfromNXP(www.
nxp.
com).
Theapplicationexecutesthecardprovisioninginsecuritylevel0ortheAESauthenticationinsecuritylevel3bydirecttransferringtheMIFAREPluscommands.
7.
2ISO14443A–Part3cardcommunicationIfactivatingthecardinprotocollayer3,theapplicationdoesnotusethedirectcardcommunication.
Forthistypeofcommunication,atransparenttransmissionchanneltothecardisnecessary.
ThereisanamendmentproposalforthePC/SCspecificationpart3(HIDandNXP)indiscussionwiththePC/SCworkgroup.
Becausethestandardizationisnotconcluded,theOMNIKEYContactlessSmartCardreaderprovidesanHIDproprietarytransparentchannel.
Inthischanneltheapplicationcommunicateswithgenericcardcommands.
SeeSections7.
3OpenGenericSession,7.
4GenericCardCommandsand7.
5CloseGenericSession.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page31of102January20157.
3OpenGenericSessionStopthedriveractivityforcardtrackingandinitializethegenericcommandsession.
Takethecardcontroltotheapplication.
INITGENERICSESSIONCommandAPDUCommandClassINSP1P2LcDataInLeInitSession0xFF0xA00x000x070x030x010x000x01-INITGENERICSESSIONCommandOutputDataOutSW1SW2=0x9000AtfirsttheapplicationmustsendthefollowingAPDUwithSCardTransmit.
SendFFA0000703010001Receive90007.
4GenericCardCommandsWritetheMIFAREPluscommandinatransparentchanneltothecard.
TheApplicationsendstheGenericCardCommandAPDUwithSCardTransmit.
GENERICCARDCOMMANDAPDUCommandClassINSP1P2LcDataInLeCardCommand0xFF0xA00x000x056+n0100F3000064+MIFAREPluscommand00PreambleMIFAREPluscardcommandExplanation0100F3000064E181ISO14443-3RATS0100F30000640A0170029000ISO14443-4FirstAuthenticationNeverchangetheredlabelledpreamble.
ThegreenlabeleddatafieldisthePCBandCID.
TheapplicationisresponsibleforthecorrectusageoftheProtocolControlByte(PCB)00001010.
Thegreenlabeledbit0istheblocknumber.
SeeISO14443-4clause7.
5.
3Blocknumberingrules.
GENERICCARDCOMMANDOutputDataOutRFControllerStatusMIFAREPluscardanswerSW1SW2Byte1Byte2Byte3…n-2Byten-1Byten0000[PCB+CID]SCData0x9000successful[0A01]90[XXXX…XX]0x6400nocardanswer(TimeOut)08040A0x9000successfulACKanswerfromMIFAREcard0804one-bytevaluefromrange:00-09,0B-0F0x9000successfulNAKanswerfromMIFAREcardThegreenlabeledPCB,CIDfiledisonlyavailableifthecardisswitchedtoISO14443-4.
Ifdesired,leavethedatafieldempty.
Thestatuscodeinthissampleissuccessfulcode.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page32of1027.
4.
1MIFAREPluscommandswiththeGENERICINTERFACECommandAPDUSamplesSwitchingtoISO14443part4(RATS)SampleSendFFA00005080100F3000064E08100Receive00000C757784024D46505F454E479000FirstAuthenticationSampleSendFFA000050C0100F30000640A017002900000Receive00000A0190XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX9000SL1authenticationSampleSendFFA00005090100F300006476049000Receive000090XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX90007.
5CloseGenericSessionContinuethedriveractivityforcardtrackingandclosethegenericcommandsession.
Takethecardcontrolfromtheapplicationtothedriver.
CLOSEGENERICSESSIONCommandAPDUCommandClassINSP1P2LcDataInLeCloseSession0xFF0xA00x000x070x030x010x000x02-INITGENERICSESSIONCommandOutputDataOutSW1SW2=0x9000Afterthegenericinterfacesession,closethesession.
Donotskipthisstep.
TheapplicationmustsendthefollowingAPDUwithSCardTransmit.
SendFFA0000703010002Receive9000OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page33of102January20158OMNIKEYContactlessSmartCardReaderKeysTheOMNIKEYContactlessSmartCardreaderhasasetofbuilt-incryptographickeys,someofwhichareimplementedinvolatilememoryandothersinnon-volatilememory.
8.
1KeyNumberingSchemeCryptographickeysarereferencedbyauniquekeynumberbetween0x00and0xFE.
Eachkeynumberreferstoakeyofpre-definedlengthforaspecificcardtype.
ForcardssuchasMIFAREandiCLASS,multiplekeynumbersarereserved.
TheOMNIKEYkeynumberisusedtodeterminekeyusage,keylength,andtomapthereaderkeytothethirdpartycardkey.
Examples:ReaderKeynumber'0A'referstothe6byteMIFAREkey10,KMIF10ReaderKeynumber'24'referstothe8byteiCLASSDefaultkeyforapplication1onpage1SeeMIFAREandiCLASSfordetaileddocumentation.
Contactyourcardmanufacturerforinformationaboutanykeyvalues.
KeysNumbersandKeyNamesKey#KeyNameKeyLengthKeyTypeMemoryType6-byte(MIFARE)keys'00'to'1F'KMIF0(MIFAREKey0)toKMIF31(MIFAREKey31)6bytesCardKeyNon-volatilememory8-byte(iCLASS)keys'20'KIAMC(KMC0,Kcforapplication2ofpage0onBook0ofiCLASScard)8bytesCardKeyNon-volatilememory'21'KMDCHIDMasterKey(KMD0,Kdforapplication1ofpage0onBook0ofiCLASScard)8bytesCardKeyNon-volatilememory'22'RFU(previouslyusedforHIDMasterKeyKMDO)8bytesCardKeyNon-volatilememory'23'KMC0(DefaultMasterKeyforapplication2ofpage0ofiCLASScard)8bytesCardKeyNon-volatilememory'24'KMD1(DefaultMasterKeyforapplication1ofpage1ofiCLASScard)8bytesCardKeyNon-volatilememory'25'KMC1(DefaultMasterKeyforapplication2ofpage1ofiCLASScard)8bytesCardKeyNon-volatilememory'26'KMD2(DefaultMasterKeyforapplication1ofpage2ofiCLASScard)8bytesCardKeyNon-volatilememory'27'KMC2(DefaultMasterKeyforapplication2ofpage2ofiCLASScard)8bytesCardKeyNon-volatilememory'28'KMD3(DefaultMasterKeyforapplication1ofpage3ofiCLASScard)8bytesCardKeyNon-volatilememory'29'KMC3(DefaultMasterKeyforapplication2ofpage3ofiCLASScard)8bytesCardKeyNon-volatilememory'2A'KMD4(DefaultMasterKeyforapplication1ofpage4ofiCLASScard)8bytesCardKeyNon-volatilememoryOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page34of102Key#KeyNameKeyLengthKeyTypeMemoryType'2B'KMC4(DefaultMasterKeyforapplication2)ofpage4ofiCLASScard8bytesCardKeyNon-volatilememory'2C'KMD5(DefaultMasterKeyforapplication1ofpage5ofiCLASScard)8bytesCardKeyNon-volatilememory'2D'KMC5(DefaultMasterKeyforapplication2ofpage5ofiCLASScard)8bytesCardKeyNon-volatilememory'2E'KMD6(DefaultMasterKeyforapplication1ofpage6ofiCLASScard)8bytesCardKeyNon-volatilememory'2F'KMC6(DefaultMasterKeyforapplication2ofpage6ofiCLASScard)8bytesCardKeyNon-volatilememory'30'KMD7(DefaultMasterKeyforapplication1ofpage7ofiCLASScard)8bytesCardKeyNon-volatilememory'31'KMC7(DefaultMasterKeyforapplication2ofpage7ofiCLASScard)8bytesCardKeyNon-volatilememory'32'KMTD(MasterTransportKeyforapplication1ofPicopasscards)8bytesCardKeyNonvolatilememory'33'KMTC(MasterTransportKeyforapplication2ofPicopasscards)8bytesCardKeyNon-volatilememory'34'KMD0B1(DefaultMasterKeyforapplication1ofpage0onBook1ofiCLASScard)8bytesCardKeyNon-volatilememory'35'.
.
'7F'RFU16-bytekeys'80'KCUR(Customreadkey)16bytesReaderKeyNon-volatilememory'81'KCUW(CustomwriteKey)16bytesReaderKeyNon-volatilememory'82'KENC(Carddataencryptionkey)16bytesCardKeyNon-volatilememory24-bytekeys'B0'.
.
'CF'RFU32-bytekeys'D0'.
.
'DF'RFU0xF0to0xFFarevolatilekeys0xF0KVAK(volatileapplicationkey)8bytesCardKeyVolatilememory'F1'.
.
.
'FF'RFUNote:OMNIKEYContactlessSmartCardreaderfirmwareversion5.
00isthefirsttosupportallkeyslistedabove.
Readerswithfirmwareversion1.
03and1.
04onlysupportkeynumbers0x20and0xF0.
Keynumber0x21toKeynumber0x31(except0x22)arethedefaultkeysforiCLASScards.
Keynumber0x32and0x33arethedefaulttransportkeysforInsidecards.
Keys0x21and0x22arestoredinthereader.
Theremainingnon-volatilekeys0x23to0x33arestoredintheregistry.
Key0x21cannotbeupdated.
Updatesofkey0x22areRFUandcurrentlynotsupported.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page35of102January20158.
2KeyContainerandSlotsTheOMNIKEYContactlessSmartCardreaderkeycontainerisorganizedinfixed-lengthkeyslots.
Thesekeyslotsalloweasyusageofcryptographickeys.
Itisnotnecessarythatthehostapplicationknowsanythingaboutthephysicalstoragelocation.
Loadkeysintoakeycontainerbyreferringtoakeyslotandakeynumber.
Keyaccessandusagearemanagedbythereaderfirmware.
Forsecuritypurposes,keyscanonlybeusedandupdated,buttheycanneverberead.
Asanadditionalsecuritymeasure,keysarediversifiedwithtwo16-bytesecretkeysbeforebeingcommittedtoakeycontainer.
Keyslotpropertiesareavailableforadvancedusers.
Thisfeatureisdesignedtoensureproperuseofasinglekeyincasetherearemorekeysthankeyslots.
KeyContainerofOMNIKEYContactlessSmartCardReaderKeySlot(KS)NumberKSLengthDefaultStoredKeyNameDefaultStoredKeyNumberRemarks'00'12KMIF0'00'Nokeyslotinformationisavailableforthesekeyslots.
RetrievinginformationwillreturnSW1SW26300.
….
12'1F'12KMIF31'1F''20'16KCUR'80'Keyslotinformationisavailable.
'21'16KCUW'81''22'16KENC'82''23'08KIAMC'20''24'08KMDO'22''25'08KMDC'21''26'08KVAK'F0'Nokeyslotinformationisavailableforthesekeyslots.
RetrievinginformationwillreturnSW1SW26300.
'27'08KMC0'23'Keyslotinformationisavailable.
'28'08KMD1'24''29'08KMC1'25''2A'08KMD2'26''2B'08KMC2'27''2C'08KMD3'28''2D'08KMC3'29''2E'08KMD4'2A''2F'08KMC4'2B''30'08KMD5'2C''31'08KMC5'2D''32'08KMD6'2E''33'08KMC6'2F''34'08KMD7'30''35'08KMC7'31''36'08KMTD'32'37'08KMTC'33''38'08KMD0B1'34'OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page36of1028.
3KeyUpdateRulesThefollowingtablelistsupdaterulesforkeysbeingusedbythereadersystem.
KeyupdatesrelatetokeysresidingintheOMNIKEYreader.
Thosekeysareusedforauthenticationofthereadertothecardortoencryptdatawrittentothecard.
KeyNameKeyNumberKeyUpdateRuleDescriptionKMIF0toKMIF31'00'to'1F'Always6-byteMIFAREkeyscanbeloaded/updatedbyusingtheSCardCLWriteMIFAREKeyToReaderfunctionofsynchronousAPI.
Akeysenttoreadermaybeplainor3-DESencryptedwiththeKCURorKCUW.
Formoredetails(forexample,paddingfor3-DESencryption)seethesynchronousAPIhelpfilecmsync.
hlp.
KIAMC'20'StandardMode:-AlwaysSecuredMode:-Readsession-Writesession8-byteiCLASSkey.
ThiskeyisthetransportkeyKc0(authenticatestoapplication2onpage0).
KMDC'21'NeverAuthenticatesthereadertotheHIDapplicationofaniCLASScardforreadaccess.
Thisauthenticationrequiressecuremodeoperation.
WriteaccesstotheHIDapplicationisnotallowed.
KMDO'22'NeverRFUKCUR'80'Securedmode:-readsessionAuthenticatesthereadertoestablishasecuredsession.
Grantstheapplicationreadaccess.
ThiskeycanalsobeusedtoencrypttheMIFAREkeyinSCardCLWriteMIFAREKeyToReaderfunction.
KCUW'81'Securedmode:-readsession-writesessionAuthenticatesthereadertoestablishasecuredsession.
Grantstheapplicationread-onlyaccess.
ThiskeycanalsobeusedtoencrypttheMIFAREkeyinSCardCLWriteMIFAREKeyToReaderfunction.
KENC'82'Securedmode:-readsession-writesessionEncryptsdatawrittentothecardordecryptsdatareadfromthecard.
Requiresread/updateINSbitstobesetaccordingly.
IfINSbitsaresetforDES,thefirst8bytesofKENCareused.
For3-DESoperations,all16bytesareused.
KVAK'F0'StandardMode:-AlwaysSecuredMode:-Readsession-WritesessionAuthenticatesanyapplicationontheiCLASScard.
Thesequenceisasfollows:LoadKVAKwiththe8-bytevalue,AuthenticatewithKVAKLoadKVAKwithnew8-bytevalue,AuthenticatewithKVAK.
KMC0toKMC7KMD1toKMD7,andKMD0B1'23'to'31'and'34'NeveriCLASSdefaultkeysforfreememoryzones.
Maybeusedtoauthenticatetoanynon-HIDapplicationonaniCLASScard.
ThisallowsquickevaluationofiCLASScardswithoutknowledgeofthedefaultkeys.
KMTD-KMTC'32''33'NeverPicopasstransportkeyssetbythecardmanufacturer.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page37of102January20159StandardCommunicationwithiCLASSCardStandardcommunicationmeansthereisnoauthenticationofthehostapplication(forexampleMicrosoftWindows)totheOMNIKEY5x21-CL.
Unlessthecarditselfhasbuilt-inmechanismsforconfidentialcommunication,thechannelbetweenhostandreaderisunprotected,exposingtheconnectingUSBcabletoeavesdropping.
9.
1APDUStructureforStandardCommunicationiCLASScardsaresupportedthroughISO7816compliantAPDUexchange.
CommandandresponseAPDUsareexchangedthroughtheOMNIKEYproprietaryAPIfunctionSCardCLICCTransmitresidingintheOMNIKEYsynchronousAPI.
CommandAPDU(throughpucSendData)CLAINSP1P2LcDatainLe'80''xx''xx''xx''xx''xx'…'xx''xx'ResponseAPDU(throughpucReceivedData)DataoutSW2SW1'xx'…'xx''xx''xx'9.
2CommandsAvailableinStandardCommunicationModeCardcommandsarereferredtobytheirrespectiveinstruction(INS)byteaspartofacommandAPDUsentbySCardCLICCTransmit.
ThefollowingtablelistsallINSvaluessupportedbytheOMNIKEYContactlessSmartCardreaderinstandardcommunicationmode.
ListofSupportedINSbytes(APDUCommendSet)Instruction(INS)DescriptionCommandType'82'LoadKeyreadercommand'C4'GetKeySlotInforeadercommand'A6'SelectPagecardcommand'88'Authenticatecardcommand'B0'Readcardcommand'D6'UpdatecardcommandOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page38of1029.
2.
1SelectPage(CardCommand)iCLASScomeswithvariouscardconfigurations.
EveryiCLASScardhasatleastonepage(page0).
CardssuchastheiCLASS2x8KS,provideadditionalpages1to7.
Inadditiontopages,iCLASScardsalsohavebooks.
ToselectacertainmemoryblockonaniCLASScard,youneedtoknowitsbooknumber,pagenumber,andblocknumber.
SelecttheappropriatepageandbookbeforeauthenticationtoaniCLASScardapplicationforperformingread/writeaccess.
InthecontextofiCLASScards,anapplicationareaandmemoryareaaresynonymous.
Currently,onlycardswithmorethan16kbitoftotalmemorycapacityhaveanadditionalbook.
ThefollowingsectiondescribesparametersoftheSelectPagecommand.
CommandSyntaxCLA'80'INS'A6'P1'00':SelecttheonlypageofiCLASS2KSorsinglepageof16KS'01':Selectpageofmulti-pageiCLASS16KS(8x2KS)or32KSP2Specifieswhetherdataisrequestedfromthecard'00':nodatarequested'04':requestfor8-bytecardserialnumber'08':requestfor8-byteconfigurationblockdata'0C':requestfor8-byteapplicationissuerdataLCforP1='00':standardmode:empty;securedmode:'00'forP1='01':'01'DataFieldforP1='00':emptyforP1='01':booknumberandpagenumberaccordingtoformatbelowLeforP2='00':emptyforP2>'00':'00'or'08'DataFieldFormatforPageNumber&BookSelectionb7b6b5b4b3b2b1b0000Booknumber0:for1stbook1:for2ndbookoniCLASS32KS0Pagenumber0-7PageSelectionExamplesDataFieldDescription'03'selectpage3ofaniCLASS8x2KScard'03'selectpage3ofbook0ofaniCLASS32KS(book0:8x2KS)card'13'selectpage3ofbook1ofaniCLASS32KS(book1:8x2KS)card'10'selectbook1(16KS)ofaniCLASS32KS'00'selectbook0(16KS)ofaniCLASS32KSOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page39of102January2015ResponseSyntaxDataFieldemptyor8bytecardresponse,incaseofapreviousrequestforsuchdataSW1SW2statuswordasdescribedbelow'90''00'Success'62''83'requestedpagenumberdoesnotexist'6C''xx'wronglengthLe.
xxreturnsthenumberofdataavailableReferencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
Note:Iftheapplicationresidesonpage0ofan8x2KSiCLASScardoronthesinglepageofaniCLASS16KSoriCLASS2KScard,theSelectPagecommandisnotnecessary.
ItishelpfultocallSelectPageanyway,incaseyouneedtoretrievethecardserialnumber,configurationblock,orapplicationissuerdata.
9.
2.
2LoadKeyLoadKeycommandloadsaniCLASScardkeyandstoresitinreadermemory,thuspreparingthereaderforsubsequentcardauthenticationcommands.
OMNIKEYContactlessSmartCardreadercanonlystoreonesuchkeyatatime.
CommandSyntaxCLA'80':standardmodeoperation'84':securedmodeoperationINS'82'P1'xx'specifieskeylocationaccordingtobyteformatbelowP2'xx'keynumber(seeKeyNumberingScheme)LC'08'DataField8bytekeyLeEmptyP1-FormatforKeyLocationb7b6b5b4b3b2b1b0Descriptionx0:cardkey1:readerkeyx0:plaintransmission1:securedtransmission(notavailable)x0:keyloadedinvolatilememory1:keyloadedinnon-volatilememory.
x0:RFU(non-zerovaluereturnserror)0000b0.
.
b3mustbesetto0Note:Onlyloadakeyinvolatilememoryonceduringanygivencardsession.
Unlessyouneedtoauthenticatetoanyadditionalapplicationwithadifferentkey,youcanusethestoredkeythroughoutthesessionformorethanoneauthentication.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page40of102ResponseSyntaxDataFieldEmptySW1SW2statuswordasdescribedbelow'90''00'success'63''00'nofurtherinformationgiven(warning)'63''81'loading/updatingisnotallowed'63''82'cardkeynotsupported'63''83'readerkeynotsupported'63''84'plaintexttransmissionnotsupported'63''85'securedtransmissionnotsupported'63''86'volatilememoryisnotavailable'63''87'non-volatilememoryisnotavailable'63''88'keynumbernotvalid'63''89'keylengthisnotcorrectReferencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page41of102January20159.
2.
3GetKeySlotInfo(ReaderCommand)TheGetKeySlotInforeadercommandprovidesaccesstokeyslotstatusinformation.
OMNIKEYContactlessSmartCardreaderprovidesasetofpredefinedkeyslotsinthekeycontainer.
Easilyloadkeyslotswithkeysbyreferringtothekeynumber(forexample,keyreference)ratherthanloadingtheactual8bytekeybyvalue.
Theslotforkeystorageisautomaticallydeterminedbythereadersystem.
CommandSyntaxCLA'80':standardmodeoperation'84':securedmodeoperationINS'C4'P1'00'P2'xx'keyslotnumber.
SeeSection8.
2KeyContainerandSlots.
LCstandardmode:empty;securedmode:'00'DataField8bytekeyLe'00'or'02'ResponseSyntaxDataField2bytekeyinformationseeKeyInformationandKeyAccessOptionbelowSW1SW2statuswordasdescribedbelow'90''00'success'63''00'nofurtherinformationgiven(warning)'63''01'keyslotdoesnotcontainvalidkeyoremptykeyslot'62''83'requestedkeyslotdoesnotexist'6C''xx'moredataavailablethanrequested;xxreturnsavailabledatasizeReferencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
KeyInformation(containedinDataField)b15b14B13b12b11b10b9b8b7b6b5b4b3b2b1b0RFUKeyAccessOptionkeynumberaccordingto7.
1-KeyNumberingScheme'FF'meansemptykeyslotKeyAccessOption(containedinb9,b8ofDataField)b9B8KeyAccessOption00keycanbeloadedforanyplaintextandsecuredtransmission.
01keycanonlybeloadedinOMNIKEYproprietarysecuredmode10keycanneverbeloaded11RFUOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page42of1029.
2.
4Authenticate(CardCommand)TheAuthenticatecommandauthenticatesthereadersystemtothecardapplicationoftheselectedpage.
ForiCLASSauthentication,thiscommandrequirespreviouspageselection.
CommandSyntaxCLA'80':standardmodeoperation'84':securedmodeoperationINS'88'P1'xx'keytype:'00':InsideContactlessoriCLASSdebitkeyKd(i.
e.
application1)'01':InsideContactlessoriCLASScreditkeyKc(i.
e.
application2)'60':MIFAREKeyA'61':MIFAREKeyB'FF':keytypeunknownornotnecessaryallothervalues:RFUP2'xx'keynumber.
SeeSection8.
1KeyNumberingScheme.
LClengthofaddressiCLASS:standardmode:empty;securedmode:'00'othercards:'01'or'02'(max2addressbytessupported)DataFieldiCLASS:emptyothercards:oneortwobyteaddressLeemptyResponseSyntaxDataFieldemptySW1SW2statuswordasdescribedbelow'90''00'success'63''00'nofurtherinformationgiven(warning)'69''83'authenticationcannotbedone'69''84'referencekeynotuseable'69''88'keynumbernotvalidReferencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page43of102January20159.
2.
5Read(CardCommand)TheReadcommandreadsadatablockfromthegivenblockaddress.
FortheiCLASScard,onlyeightbytescanbereadatatime.
Forinformationaboutavailableblocksreference[HID_ICLASS].
Thiscommandrequirespreviouspageselectionand,dependingontheiCLASScardconfiguration,authenticationtotheiCLASSapplication.
CommandSyntaxCLA'80':standardmodeoperation'84':securedmodeoperationINS'B0'P1MSBofblocknumberP2LSBofblocknumberLCstandardmode:empty;securedmode:'00'DataFieldemptyLe'00'or'08''20':ifsupportedbycard,upto32bytescanbereturnedResponseSyntaxDataField8byteblockreturnedfromthecard(iCLASS)32bytesreturnedifcardsupportsitSW1SW2statuswordasdescribedbelow'90''00'success'62''81'partofreturneddatamaybecorrupted'62''82'endoffilereachedbeforereadingallrequestedbytes'69''81'commandincompatible'69''86'commandnotallowed'6A''81'functionnotsupported'6A''82'filenotfoundoraddressedblockorbytedoesnotexist'6C''xx'moredataavailablethanrequested;xxreturnsavailabledatasize,typically'08'Referencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
Note:Readingblockswithoutvalidauthenticationortryingtoreaddatawithoutreadpermission,willsetallreturneddatato'FF'.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page44of1029.
2.
6Update(CardCommand)TheUpdatecommandwritesadatablocktoagivenblockaddress.
FortheiCLASScard,onlyeightbytescanbewrittenatatime.
Forfurtherinformationaboutavailableblocksreference[HID_ICLASS].
Thiscommandrequirespreviouspageselectionand,dependingontheiCLASScardconfiguration,authenticationtotheiCLASSapplication.
CommandSyntaxCLA'80':standardmodeoperation'84':securedmodeoperationINS'D6'P1MSBofblocknumberP2LSBofblocknumberLC'08'(iCLASSonlyallows8bytespercall)DataField8bytestobewrittentocardLeemptyResponseSyntaxDataFieldemptySW1SW2statuswordasdescribedbelow'90''00'success'62''82'endoffilereachedbeforewritingallLcbytes'65''81'memoryfailure(unsuccessfulwriting)'69''81'commandincompatible'69''86'commandnotallowed'6A''81'functionnotsupported'6A''82'filenotfoundoraddressedblockorbytedoesnotexistReferencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
Note:Updatingwithoutauthenticatingtothecorrespondingapplicationreturns'6400'CardExecutionError.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page45of102January20159.
3CommunicationinStandardModeEstablishContextConnectCardSelectPageLoadKeyAuthenticateApplicationYesRead/UpdateNoDisconnectCardYesSamePageYesNo12345678ReleaseContext9FurtherRead/UpdateNoSameApplicationOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page46of10210SecuredCommunicationwiththeiCLASSCardForadesktopsmartcardreader,suchastheOMNIKEYContactlessSmartCardreader,securitymainlyevolvesfromthefollowingscenarios:AuthenticitybetweenthehostapplicationandthereaderConfidentialityofdatatransmittedthroughUSBcableIntegrityoftransmitteddataAuthenticitybetweenthereaderandthecardConfidentialityandintegrityoftheRFtransmissionConfidentialityofdatastoredincardsOMNIKEYContactlessSmartCardreaderprovidesanend-to-endsecurityschemetofulfillthesecurityrequirementslistedabove.
Note:Securedmodecommunicationrequiresreaderfirmwareversion5.
00orgreater.
10.
1Multi-StepApproachtoaSecureCardReaderSystem10.
1.
1AuthenticitybetweenHostandReaderAuthenticitybetweenhostandreaderisenforcedwithamutualauthenticationschemethatrequiresa16-bytetransportkey(KcurorKcuw)andaproprietaryalgorithm.
Onlyinitiatesessionsuponsuccessfulcompletionofthisone-stepmutualauthenticationprocess.
Note:Thisfeaturepreventsunauthorizedreaderusage.
AdditionalinformationaboutthisprocessisavailableunderNDA.
10.
1.
2ConfidentialityofUSBDataExchangeTheContactlessSmartCardreaderhasabuilt-inmechanismthatprotectsagainsteavesdroppingandreplayattacksonUSBtraffic.
ThedatatransmittedthroughaUSBcableistripleDESencryptedwiththeSessionKey(Ks).
Thiskeyisgeneratedduringthemutualauthenticationprocess.
Itisuniqueforeverysession.
Therefore,trafficrecordedinonesessioncannotbereplayedinanothersession.
10.
1.
3IntegrityofTransmittedDataDatatransmittedbetweenhostandreaderisdigitallysignedwithaneight-byteMessageAuthenticationCode(MAC)whichisappendedtothedata.
Thisisdonetodetectanyinconsistenciesthatmayoccurduetoerroneousormodifieddata.
10.
1.
4AuthenticitybetweenReaderandCardiCLASScardsallowauthenticationofthereadersystemtothecard.
Thisisdonebyprovingknowledgeofasharedsecret,theiCLASScardapplicationkeyKIAMCorKMDC.
Applicationsthatareprotectedwithsuchakeyrequiresuccessfulreaderauthenticationbeforeread/writeaccesstocarddataisgranted.
10.
1.
5IntegrityoftheRadioFrequency(RF)TransmissionDataintegrityofanRFtransmissionwithaniCLASScardisenforcedwithatwo-bytechecksum(basedonCRCalgorithm).
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page47of102January201510.
1.
6ConfidentialityoftheRFTransmissionTheContactlessSmartCardreadersupportsanimportantfeaturetoguaranteeconfidentiality:itencryptsdatabeforewritingdatatothecardanddecryptsdatareadfromthecard.
Confidentialityinthiscontextmeansthatdataissecurelytransmittedbetweenthecardandthereaderwithoutaneavesdropperreadingthedatainplaintext.
10.
1.
7AuthenticationoftheHostforRead/WriteSessionTheContactlessSmartCardreadercontainstwokeysKCURandKCUWthatareusedtocontrolaccesstoreadandwritefunctionsrespectively.
InitiatingareadersessionwithKCURmakesitaread-onlysessionthusblockingfunctionsthatwritetothecard.
StartingasessionwithKCUWenablesthereaderforbothreadandwriteaccess.
Note:Thisispartofahost-to-readerauthenticationmechanism,nottobeconfusedwithreader-to-cardauthenticationenforcedbythecarditself.
10.
1.
8ProtectionagainstKnownAttacksReplayAttacks:ThedataheadercontainsadatagramthatisdifferentwitheveryAPDUexchange.
Thereaderensuresthatnoframeisrepeated.
PlainTextAttack:Forsomecriticalcommands,thereisabuilt-indelaytopreventaplaintextattack.
Ifthereisanyerrorinthedataheaderorsignature,thesessionisimmediatelyterminated.
Onecancommencecommunicationonlyafterstartinganewsession.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page48of10210.
2APDUStructureforSecuredCommunicationTheContactlessSmartCardreaderprovidesauniquemechanismtosecurethecommunicationchannelusingOMNIKEY'sproprietarycryptographicenvelopewhichprotectsthetransmitteddatafromeavesdroppers.
Securedcommunicationrequiresadditionalstepstopreparedatabeforesendingittothereadersystemandafterreceivingdatafromthereader.
TheunderlyingtripleDESalgorithmrequiresablocksizethatisamultipleof8.
Therefore,thedatagramhasabuilt-inpaddingscheme.
Authenticityoftheplaintextisenforcedwithan8bytesignature.
CommandSyntaxCLAINSP1P2LcInputDatagram(senttothereader)Le'84''xx''xx''xx''xx''xx.
.
.
xx''xx'InputDatagram(senttothereader)DataHeader(DH)SizeofINSrelateddataLcINSINSrelateddata(INSData)PaddingBytes(PB)Signature'xxxxxxxx''xx''xx.
.
.
xx''80.
.
.
00''xx.
.
.
xx'4bytes1byteLcINSbytesPbytes8bytesP=numberofpaddingbytestosatisfy(4+1+LcINS+P)ismultipleof8.
ResponseSyntaxOutputDatagram(receivedfromthereader)SW2SW1'xx.
.
.
xx''xx''xx'OutputDatagram(receivedfromthereader)P=numberofpaddingbytestosatisfy(4+1+LcINS+P)ismultipleof8.
Note:IfnovalidsessionkeyKsisavailableduetoapreviouserrorduringtheStartSessioncommand,alldatagrambytesaresetto'00'.
Thereforethehostwouldreceive'00.
.
.
00'||SW1||SW2asresponsefromthereader.
DataHeader(DH)SizeofCardResponseLcRCardResponsePaddingBytes(PB)Signature'xxxxxxxx''xx''xx.
.
.
xx''80.
.
.
00''xx.
.
.
xx'4bytes1bytenbytesPbytes8bytes3-DES{KS,()}3-DES{KS,()}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page49of102January201510.
2.
1DataHeader(DH)DataHeaderByte0Byte1Byte2Byte3Hostdataheader(HDH)Readerdataheader(RDH)WhenthehostsystemsendsaHostDataHeader(HDH)tothereader,thereadermustacknowledgetheHDHinitsresponsebyreturningthe1'scomplementoftheoriginalHDH.
Thisallowsthehosttocheckwhetheritreceivesdataoriginatingfromthecorrectdataheader.
WhenthereadersendsaReaderDataHeader(RDH)tothehost,thehostmustacknowledgetheRDHinitsnextrequestbysendingthe1'scomplementoftheprecedingRDH.
Thisallowsthereadertocheckwhetherthedatasentbythehostfollowsapreviousreaderresponse.
10.
2.
2SignatureGenerationTheOMNIKEYContactlessSmartCardreadersignaturegenerationisbasedonan8-byteMessageAuthenticationCode(MAC).
TheMACvalueiscalculatedbytakingthelast8bytesofaDESCBCencrypteddatablockconsistingofDH,LcINSData,INSData,andpaddingbytes.
KcurorKcuwareusedassigningkeys.
ThefollowingstepsdescribehowpaddingisappliedtocreateadatablockthatcanbesignedusingaDESCBCoperation:Append'80'totherightofthedatablock.
Iftheresultingdatablocklengthisamultipleofeight,nofurtherpaddingisrequired.
Dozero('00')paddinguntilthedatablocksizereachesamultipleofeight.
10.
2.
3SessionKeyGenerationThesessionkeyKsisderivedfroman8-byterandomnumberandtheMACtransmittedtothereaderduringStartSession.
FortheStartSessioncommand,LcINSDataequals8(lengthoftherandomnumber)andINSDatacontainsthe8-byterandomnumber.
Allsecuredcommunicationcallsfollowingasuccessfulsessionkeynegotiationare3DESencryptedwithKs.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page50of10210.
2.
4ProprietaryHostandReaderDatagramExample3DES(KCUR.
)3DES(KS,)DataHeaderLcINSDataHDHRDHHDH008RndRndINSDataxxxxxxxxxRnd8Padding800000MACxxxxxxxxSessionKey(Ks)=Rnd8+MACStep1:StartsessionDataHeaderLcRHDHRDH~HDH0RDH000RndPadding800000MACxxxxxxxxHostReader3DES(KS,)DataHeaderLcINSDataHDHRDHHDHn~RDHn-1xxRndINSDataxxxxxxxxxPadding80xxxxxMACxxxxxxxxStepn:Anyothercommand3DES(KS,)DataHeaderLcRHDHRDH~HDHnRDHnxxRndPadding80xxxxxMACxxxxxxxxNote:Thisisaread-onlysessionbecauseKCURwasusedinthestartsessioncommand.
IfKCUWwereusedtostartthesession,bothreadandwriteoperationswouldbeallowed.
TheHIDapplicationisalwaysread-only.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page51of102January201510.
3Instructions(INS)forSecuredCommunicationCardcommandsarereferredtobytheirrespectiveinstruction(INS)byteaspartofacommandAPDUsentbySCardCLICCTransmit.
OMNIKEYContactlessSmartCardreaderwithfirmwareversion5.
00orgreatersupportsthefollowingsecuredmodeinstructions:ListofINSbytesforSecuredCommunicationInstruction(INS)DescriptionCommandType'C4'GetKeySlotInforeadercommand'72'ManageSessionreadercommand'82'LoadKeyreadercommand'A6'SelectPagecardcommand'88'Authenticatecardcommand'B0'Readcardcommand'D6'Updatecardcommand'24'UpdateCardKeycardcommandInthefollowingsectionsthecommandstructureisdescribed.
LcINSandINSDataarepartoftheOMNIKEYproprietarystructure.
Notes:SecuredmodeandStandardModeusedifferentformattingofP1,bit7andbit6oftheRead/Updatecommands(INS0xB0and0xD6respectively).
UsethetwoLSBitsofP1tocontroltheencryptionofdatareadorupdated.
Lcmustalwaysbetransmittedinsecuredmode.
10.
3.
1ManageSession(ReaderCommand)TheManageSessioncommandisusedtostartorendasession.
CommandSyntaxCLA'84'INS'72'P1'00':startsession'01':endsessionothervalues:RFUP2P1='00'(startsession)P1='01'(endsession)'00':startreadonlysession'01':startread/writesession'00'Lc'08':challengesize'00'DataField8-byterandomnumber(challenge)emptyLeemptyResponseSyntaxDataFieldemptySW1SW2statuswordasdescribedbelow'90''00'successReferencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
Note:Asessionisautomaticallyendedifthecardisremoved.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page52of10210.
3.
2SelectPage(CardCommand)ExceptfortheCLAbyte'84',thesyntaxforSelectPageinsecuredmodeisidenticaltothecommanddescribedin8.
2.
1-SelectPage(CardCommand).
10.
3.
3LoadKey(ReaderCommand)ExceptfortheCLAbyte'84',thesyntaxforLoadKeyinsecuredmodeisidenticaltotheLoadCommanddescribedin8.
2.
2-LoadKey.
10.
3.
4Authenticate(CardCommand)ExceptfortheCLAbyte'84',thesyntaxforAuthenticateinsecuredmodeisidenticaltothecommanddescribedin8.
2.
4-Authenticate(CardCommand).
10.
3.
5Read(CardCommand)ExceptfortheCLAbyte'84',andtheadditionalformattingrulesforP1describedbelow,thesyntaxfortheReadcommandinsecuredmodeisidenticaltothecommanddescribedin8.
2.
5-Read(CardCommand).
P1FormattingforSecuredModeb7b6b5–b0Description00BlockNr.
MSBPlain01DESEncryption10TripleDESEncryption11RFUDataneedstobedecryptedwiththeKENCtogettheplaintextdata.
10.
3.
6Update(CardCommand)ExceptfortheCLAbyte'84',andadditionalformattingofP1describedbelow,thesyntaxfortheUpdatecommandinsecuredmodeisidenticalwiththecommanddescribedin8.
2.
6-Update(CardCommand).
P1FormattingforSecuredModeb7b6b5–b0Description00BlockNr.
MSBPlain01DESEncryption10TripleDESEncryption11RFUDataisencryptedwithKENCbeforestoringitonthecard.
10.
3.
7GetKeySlotInfo(ReaderCommand)ExceptfortheCLAbyte'84',thesyntaxfor7.
3.
7GetKeySlotInfoinsecuredmodeisidenticaltothecommanddescribedin8.
2.
3-GetKeySlotInfo(ReaderCommand).
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page53of102January201510.
3.
8UpdateCardKeyTheUpdateCardKeycommandisusedtochangeKCorKD.
CommandSyntaxCLA'84'INS'24'P1'00':NewkeyforKD(application1)'01':NewkeyforKC(application2)othervalues:RFUP2Keynumberwherenewkeyisstored.
Lc'00':emptyDataFieldemptyLeemptyResponseSyntaxDataFieldemptySW1SW2statuswordasdescribedbelow'90''00'Success'65''81'Memoryfailure(unsuccessfulwriting)'69''81''86'CommandincompatibleCommandnotallowed'6A''81'FunctionnotsupportedReferencesection5.
2.
1-CardAccessthroughSCardCLICCTransmitforadditionalstatuswordscommontoalliCLASSaccessfunctions.
ThesequencesforusingUpdateCardKeycommandareasfollows:3.
1.
Ifthedesiredchangeofthekeyisnotinpage0,thepagehastobeselectedbyaSelectPagecommand.
4.
2.
Loadtransport/oldkeybyLoadKeycommand.
5.
3.
Authenticatethecardwiththeoldkey(keynumberasusedforLoadKeyinstep2).
6.
4.
LoadnewkeybyLoadKeycommand.
7.
5.
NowsendtheUpdateCardKeycommandwithspecificP2(NewKeynumberasloadedinstep4).
Note:OnlyupdateKD(application1)afterauthenticationwithKD,andonlyupdateKC(application2)afterauthenticationwithKC.
CAUTION:Donotwritedirectlytoaddress3,4whereKCandKDarestored,thiswilldestroythekeys.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page54of10210.
4CommunicationatSecuredModeEstablishContextConnectCardSelectPageAuthenticateApplicationYesRead/UpdateNoDisconnectCardYesNo12356894StartSessionEndSession10ReleaseContextLoadKeyYes117NoSameApplicationFurtherRead/UpdateSamePageOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page55of102January201510.
5SessionatSecuredModeAPDUsExampleKCUR='A0A1A2A3A4A5A6A7A8A9AAABACADAEAF',Read-onlysessionHostReader1.
StartSessionCLAINSP1P2LcOMNIKEYProprietaryInputDatagram(senttoreader)CLEAR'84''72''00''00''18''1422''9D2B''08''4A895F20C2D30B5E''800000''9E5052819C5A8D3C'HDH(Rnd)RDH(Rnd)LcINSRnd8(INSData)PaddingSignatureDHMAC'FD274CE840FA9AD139E4FC2923653A88743CB5986DB4F7A0'OMNIKEYProprietaryInputdatagram(senttoreader)ENCIPHEREDSignature=DESEn{(A0A1A2A3A4A5A6A7),(14229D2B084A895F20C2D30B5E800000)}=8A8D430D608714FE9E5052819C5A8D3C9E5052819C5A8D3C(lasteightbytesofDESencryption)Enciphereddatagram=3-DESEn{(A0A1A2A3A4A5A6A7A8A9AAABACADAEAF),(14229D2B084A895F20C2D30B5E8000009E5052819C5A8D3C)}=FD274CE840FA9AD139E4FC2923653A88743CB5986DB4F7A0(24byteinputdatagram)SessionKey(KS)=Rnd8+MAC=4A895F20C2D30B5E9E5052819C5A8D3COMNIKEYProprietaryOutputDatagram(receivedfromreader)SW1SW2A04B84A4DE515FD8A9D40DFFE703FBF19000'EBDD'E00C00800000E367401E2DA8FACB~HDHRDH(Rnd)LcRPaddingSignatureDHMAC3-DESDec{(4A895F20C2D30B5E9E5052819C5A8D3C),(A04B84A4DE515FD8A9D40DFFE703FBF1)}=EBDDE00C00800000E367401E2DA8FACBSignature=DESEn{(4A895F20C2D30B5E),(EBDDE00C00800000)}=E367401E2DA8FACBNote:ApublicsourcelibrarytoaccomplishallsecurityprotocolsintroducedinthesecuredcommunicationmodeisavailablefromOMNIKEYuponrequest.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page56of1022.
AuthenticateHIDApplicationCLAINSP1P2LcOMNIKEYProprietarySendDatagram8488002110B3F11FF300800000B50318C9E871191AHDH(Rnd)~RDHLcINSPaddingSignatureDHMACB5FD83E756CA03DE54FBEA5546E8867DProprietaryDataSignature=DESEn{(4A895F20C2D30B5E),(B3F11FF300800000)}=B50318C9E871191AProprietaryData=3-DESEn{(4A895F20C2D30B5E9E5052819C5A8D3C),(B3F11FF300800000B50318C9E871191A)}=B5FD83E756CA03DE54FBEA5546E8867DOMNIKEYProprietaryResponseDatagramSW1SW278A10C4FCC7EBC2C516354A56C4C781890004C0E7D5500800000D2D0B0B4E34EBDBE~HDHRDH(Rnd)LcRPaddingSignatureDHMAC3-DESDec{(4A895F20C2D30B5E9E5052819C5A8D3C),(78A10C4FCC7EBC2C516354A56C4C7818)}=4C0E7D5500800000D2D0B0B4E34EBDBESignature=DESEn{(4A895F20C2D30B5E),(4C0E7D5500800000)}=D2D0B0B4E34EBDBENote:ApublicsourcelibrarytoaccomplishallsecurityprotocolsintroducedinthesecuredcommunicationmodeisavailablefromOMNIKEYuponrequest.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page57of102January20153.
ReadBlock6CLAINSP1P2LcOMNIKEYProprietarySendDatagramLe84B0000610676282AA00800000F63AB82BED09B03908HDH(Rnd)~RDHLcINSPaddingSignatureDHMAC2FABB8F0533E742383F4FE9045142859ProprietaryDataSignature=DESEn{(4A895F20C2D30B5E),(676282AA00800000)}=F63AB82BED09B039ProprietaryData=3-DESEn{(4A895F20C2D30B5E9E5052819C5A8D3C),(676282AA00800000F63AB82BED09B039)}=2FABB8F0533E742383F4FE9045142859OMNIKEYProprietaryResponseDatagramSW1SW2AA401E3D849B881044FF4D847977D9070C589338C097F1639000989D2A9408000000000000E4148000003101DDB971C922FF~HDHRDH(Rnd)LcRResponseDataPaddingSignatureDHMAC3-DESDec{(4A895F20C2D30B5E9E5052819C5A8D3C),(AA401E3D849B881044FF4D847977D9070C589338C097F163)}=989D2A9408000000000000E4148000003101DDB971C922FFSignature=DESEn{(4A895F20C2D30B5E),(989D2A9408000000000000E414800000)}=1CDF21DCA31BABDB3101DDB971C922FF=3101DDB971C922FF(last8-byteblock)Note:ApublicsourcelibrarytoaccomplishallsecurityprotocolsintroducedinthesecuredcommunicationmodeisavailablefromOMNIKEYuponrequest.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page58of10211ReadingISO1569311.
1ProductsThisdocumentdescribesthecommandsforISO15693supportofOMNIKEYContactlessSmartCardreader.
Applicablereadersare:OMNIKEY5321USBOMNIKEY6321USBOMNIKEY5321CLOMNIKEY5321CROMNIKEY5421Applicabledriversandoperatingsystem:MSWindowsDriversVersionfrom1.
2.
0.
6.
11.
2TagsThefollowingtagsandfunctionsarecoveredbythisdocumentiCODE(seethefollowingtable)LRI64SLCMontalbanoTechnologyTexasInstrumentsTag-it1Infineon(MY-D,MY-Dlight)2AllISO15693-3compliantTagswithsupportforfunctionsmarkedasoptional.
(IncludetagfunctionsInventory,StayQuiet…etc.
)SupportforICODEtagsCardTypeChipTypeSupportICODE1SL2ICS3001UID,(NotISO15693Part3compliant)ICODESLISL2ICS20FullICODEEPCSL2ICS10NotsupportedICODEUIDSL2ICS11NotsupportedICODEUID-TOPSL2ICS12NotsupportedICODESLI-S/SLI-SHCSL2ICS53/ICS54Fullsupport.
ExceptionisGetSecurityStatus,whichisnotsupportedbythecard.
Forfurtherinformationseethedatasheet[iCODESL2].
1Tag-itStandardandProdoonlysupportREADBINARY,UPDATEBINARY,GETDATAPICCmemoryandLOCK,ApplicableatMSWindowsDriversVersion1.
2.
0.
142ApplicableatMSWindowsDriversVersion1.
2.
0.
14OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page59of102January201511.
3Commands11.
3.
1GetDataThisGetDatacommandwillretrieveinformationabouttheinsertedcommanddependingontheinsertedcard.
Itcanbeusedforkindofcontactlesscards.
GETDATACommandAPDUCommandClassINSP1P2LcDataInLeGetData0xFF0x30XX0x00--XXP1/P2denotationP1P2Description0x000x00RFU0x010x00RFU0x020x00AFIofaISO15693cardisreturnedifsupported0x030x00DSFIDofaISO15693cardisreturnedifsupported0x040x00PICCmemorysizeisreturnedifsupported0x050x00ICreferenceisreturnedifsupported0x060x00EASsequence(onlyforI-CODESLIcards)isreturned,Note:EASsequenceisabitstreamwhichissentLSBfirst!
!
!
GETDATACommandOutputDataOutData+SW1SW2Le=0x00,thismeans:ReturnfulllengthofthedataSW1SW2ExamplesSW1SW2MeaningWarning'62''82'EndofdatareachedbeforeLebytes(Leisgreaterthandatalength).
Error'6A''81'Functionnotsupported'6C''xx'Wronglength(wrongnumberLe;'XX'encodestheexactnumber)ifLeislessthantheavailableUIDlength)OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page60of10211.
3.
2PutDataUsethiscommandtowritesysteminformationtoacontactlesscard.
PutDataCommandAPDUCommandClassINSP1P2LcDataInLePutData0xFF0x300x000x013+NSeetable-PutDatabytesByte1Byte2Byte3Byte4.
.
nVersion0x01Flag1Flag2DataPutDataFlagdenotationforversion0x01Flag1Flag20x000x00RFU0x010x00RFU0x020x00AFIofaISO15693cardiswrittenifsupported0x030x00DSFIDofaISO15693cardiswrittenifsupported0x040x00RFU0x050x00RFU0x060x00EASbitiswritten(forI-CodeSLI)cards.
Datafieldconsistsofonebyte(bit0isthenewvalueoftheEASbit)30x000x01Stayquiet(thePICCdoesnotansweranymoreanyresponse),currentlynotsupportedThefollowingtableintroducesexamplesofSW1SW2andtheirmeaning.
PutdataCommandErrorCodesSW1SW2MeaningWarning'62''82'Blockorfieldislocked'63''00'NoinformationisgivenError'64''00'Executionerror4'6A''81'Functionnotsupported'69''82'Securitystatusnotsatisfied'86'Commandnotallowed,noISO15693-3chip3EASissupportedbyMY-D;EASmustbeenabledinAFIbyte(bit2)!
4ThechipdoesnotsupporttheoptionalISO15693-3commandtype.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page61of102January201511.
3.
3LockUsethiscommandtolockthememoryareaofacontactlesscard.
5LockAPDUCommandClassINSP1P2LcDataInLeLock0xFF0x300x000x023+NSeetable-LockdatabytesByte1Byte2Byte3Byte4.
.
nVersion0x01Flag1Flag2DataLockFlagdenotationforversion0x01Flags1Flags2Data1Data20x000x00Datafieldcontainsin2bytestheblocknumberAddress(MSB)Address(LSB)0x010x00RFU--0x020x00AFIofaISO15693cardislockedifsupported--0x030x00DSFIDofaISO15693cardislockedifsupported--0x040x00RFU--0x050x00RFU--0x060x00EASbit(onlyforI-CODESLIcards)islocked--ThefollowingtableintroducesSWISW2examples.
LockCommandErrorCodesSW1SW2MeaningWarning'62''82'Blockorfieldalreadylocked'63''00'NoinformationisgivenError'6A''81'Functionnotsupported'69''82'Securitystatusnotsatisfied'86'Commandnotallowed,noISO15693-3chip5CommandisnotsupportedbyMY-Dlight;tosetandgetsecurityyoucanusethegenericcommand.
ReferencetheInfineonMY-DlightspecificationandOK5x21_ISO15693_GenericCardCommands.
docOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page62of10211.
3.
4GetSecurityStatusUsethiscommandtoretrievethesecuritystatusofsomememoryareaofacontactlesscard.
6GetSecurityStatusCommandAPDUCommandClassINSP1P2LcDataInLeGetSecurityStatus0xFF0x300x000x033+NSeetableXXGetSecurityStatusdatabytesByte1Byte2Byte3Byte4.
.
nVersion0x01Flag1Flag2DataGetSecurityStatusFlagdenotationforversion0x01Flag1Flag2Data1Data20x000x00BlockAddress(MSB)Address(LSB)0x010x00RFU--0x020x00AFI(onlysupportedforMY-D,notMY-Dlight)--0x030x00DSFID(currentlynotsupported)--0x040x00RFU--0x050x00RFU--0x060x00EAS(notsupportedbyICODE-SLI)--Lecodesthenumberofbytesforwhichthesecuritystatusshouldberetrieved.
6CommandisnotsupportedbyMY-Dlight;tosetandgetsecurity,usethegenericcommand.
ReferencetheInfineonMY-DlightspecificationandOK5x21_ISO15693_GenericCardCommands.
docOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page63of102January2015Foreachaddress/blocknumber/pagenumber,retrievedisonebytewiththesecuritystatus.
ICODESLIData1,Data2containstheblocknumber(0–27).
Eachblockhas4bytes.
LRI64Data1,Data2containstheblocknumber(0–14).
Eachblockhas1byte.
SLCMontalbanoTechnologyData1,Data2containstheblocknumber(0–63).
Eachblockhas8bytes.
MIFARE1kData1,Data2containstheblocknumber(0-((16*4)–1))Note:MIFARE1khas16sectors.
Eachsectorhas4blocks.
Eachblockhas16bytes.
(GetSecurityStatuscurrentlynotsupported)MIFARE4kData1,Data2containstheblocknumber(0-((32*4+16*4)–1))Note:MIFARE4khas32sectorswhichhave4blocksand16sectorswhichhave16blocks.
Eachblockhas16bytes.
(GetSecurityStatuscurrentlynotsupported)MIFAREUltralightData1,Data2containsthepagenumber(0–15).
Eachpagehas4bytes.
(GetSecurityStatuscurrentlynotsupported)MIFAREMiniData1,Data2containstheblocknumber(0-((5*4)–1))Note:MIFAREMinihas5sectors.
Eachsectorhas4blocks.
Eachblockhas16bytes.
(GetSecurityStatuscurrentlynotsupported)MY-DData1,Data2containstheblocknumber.
(SRF55V10P:0–247,SRF55V02P:0–55)Eachblockhas4bytes.
Thefollowingdescribesthesecuritystatusbyte.
TypeofcardB7B6B5B4B3B2B1B0ISO15693-3compliantchipxxxxxxxWriteaccessbitMIFARE1KxxxxxC1C2C3MIFARE4KxxxxxC1C2C3MIFAREUltralightxxxxxxxLockbitMIFAREMinixxxxxC1C2C3X….
.
nomeaningThefollowingtabledescribesexamplesofSW1SW2andtheirdescription:GetSecurityStatusErrorCodesSW1SW2DescriptionWarning'63''00'NoinformationisgivenError'64''00'Executionerror7'6A''81'Functionnotsupported'69''82'Securitystatusnotsatisfied'86'Commandnotallowed,noISO15693-3chip7ThechipdoesnotsupporttheoptionalISO15693-3commandtype.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page64of10211.
3.
5ReadBinaryCommandIftheLefieldcontainsonlybytessetto'00',thenallthebytesuntiltheendofthefileshallbereadwithinthelimitof256forashortLefieldor65536foranextendedLefield8.
ReadBinaryCommandAPDUCommandClassINSP1P2LcDatainLeReadBinary0xFF0xB0AddressMSBAddressLSB--XXReadBinaryCommandOutputDataOutData+SW1SW2ReadBinaryCommandErrorCodesSW1SW2MeaningWarning'62''81'Partofreturneddatamaybecorrupted.
'82'Endoffilereachedbeforereadingexpectednumberofbytes.
Error'69''81'Commandincompatible.
'82'Securitystatusnotsatisfied.
'86'Commandnotallowed.
'6A''81'Functionnotsupported.
'82'Filenotfound/Addressedblockorbytedoesnotexist.
'6C''XX'Wronglength(wrongnumberLe;'XX'istheexactnumber).
Lemustbeamultipleoftheblocksize!
8CurrentlyareextendedAPDU'sonlysupportedforTexasInstrumentsTag-itandInfineonMY-D.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page65of102January201511.
3.
6UpdateBinaryCommandTheLcfieldcontainsthelengthofthefieldDatainfield.
ForashortLcfieldthedatalengthis1=3lpOutBufferEmptynOutBufferSize>=0lpBytesReturned0Table2:SummaryofSIGNALCommandsCommandValueDescriptionPAYPASS_SIGNAL0x20CompletePayPassAudioandVisualSequencePAYPASS_SIGNAL_MAINLED0x21ControlofMainLEDPAYPASS_SIGNAL_ADDLED0x22ControlofadditionalPayPassLED2-4ACOUSTIC_SIGNAL_BEEPER_ON0x10ControlofPayPassAudioToneONACOUSTIC_SIGNAL_BEEPER_OFF0x11ControlofPayPassAudioToneOFFOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page68of10212.
2.
1SIGNALCommand–PayPassSignalThiscommandclonesthePayPassAudioandVisualSequencefortheeventCardreadcompletesuccessful,accordingtoMasterCardPayPassTerminalImplementationGuide.
Table3:ParameterforSIGNALCommand–PayPassSignalParameterDescriptionlpInBufferCommandParam1Param2RFU20loudness----nInBufferSize>=2lpOutBufferEmptynOutBufferSize>=0lpBytesReturned012.
2.
2SIGNALCommand–PayPassSignalMAINLEDThereadermainLED(red/greenbicolor)isbydefaultundercontrolofthefirmwareanddriver.
IncasesofMasterCardPayPassterminalimplementation,anapplicationcontrolofthisLEDisrequired.
WiththiscommandtheapplicationassumestheLEDcontrol.
Table4:ParameterforSIGNALCommand–PayPassSignalMAINLEDParameterDescriptionlpInBufferCommandParam1Param2Param3RFU2100–CCIDESCcommand01–USBPipeControlLEDstatus00–bydefault03–applicationcontrolled--nInBufferSize>=4lpOutBufferEmptynOutBufferSize>=0lpBytesReturned0ForLEDcontrol,beforereceivingthePICCanswer,theapplicationmustuseParam1=01as,USBPipeControlCommand.
Param2iscodedas000000xx(bit2…7isRFU).
Table5-SummaryofParam2LEDstatusValueDescriptionBit01bicolorgreenLEDon0bicolorgreenLEDoffBit11bicolorredLEDon0bicolorredLEDoffFordetails,seethecodeexampleinAppendixA.
7.
12PayPassSignalMAINLED.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page69of102January201512.
2.
3SIGNALCommand–PayPassSignalAdditionalLEDsForthestatusofthecontactlesspaymentapplicationtheMasterCardPayPassterminalimplementationrequiresthreeadditionalLEDsforvisualindication.
Forexamplethecontactlessapplicationprocesswascompletedsuccessfully.
ThesethreeLEDsareexclusivefortheapplication.
DriverandfirmwaredonotusethesethreeadditionalLEDs.
Table6-ParameterforSIGNALCommand–PayPassSignalAdditionalLEDsParameterDescriptionlpInBufferCommandParam1Param2Param3RFU2200–CCIDESCcommand01–USBPipeControlLEDstatus----nInBufferSize>=3lpOutBufferEmptynOutBufferSize>=0lpBytesReturned0Param2iscodedas00000xxx(bit3…7isRFU)SummaryofParam2LEDstatusValueDescriptionBit01greenLED2on0greenLED2offBit11greenLED3on0greenLED3offBit21greenLED4on0greenLED4offFordetailsseethecodeexampleinAppendixA.
7.
13PayPassSignalAdditionalLEDs.
12.
2.
4SIGNALCommand–PayPassSignalToneNocommandparametersarerequired.
Thecommandcode0x10(ACOUSTIC_SIGNAL_BEEPER_ON)turnonthebuzzerandthecommandcode0x11(ACOUSTIC_SIGNAL_BEEPER_OFF)turnoffthebuzzer.
SeetheTable8-SummaryofSIGNALCommands.
Fordetails,seeAppendixA.
7.
14PayPassSignalTone.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page70of10212.
3Switch-overtheOperatingModeTheOMNIKEY5321PAYrequirestheEMVCoLevel1PCDprocessing.
Afterthedriverisinstalled,thePCD(ProximityCouplingDevice)startsinPAYmodebydefault.
AlsousethereaderinstandardISOmode.
FordynamicallychangingbetweenRFID-ISOandEMVCoL1mode,thedriversupportsanIO-Control,describedinthischapter.
SeealsothecodeexampleinAppendixA.
7.
11SetRFIDoperatingmode.
Note:TheoperatingvolumeisoptimizedforEMVCoL1.
ThisisnotcompliantwiththerequirementsofISO/ICAO.
ParameterforIO-ControlSetRFIDOperationModeSCardControlParameterDescriptiondwControlCodeCM_IOCTL_SET_OPERATION_MODElpInBuffer+0bOperationMode0x10OPERATION_MODE_RFID_ISO0x11OPERATION_MODE_RFID_PAYPASSnInBufferSize>=1lpOutBufferEmptynOutBufferSize>=0lpBytesReturned0IfthereaderisswitchedtoISOmode,usethecompletefunctionalityofastandardOMNIKEYContactlessSmartCardreader.
Note:CurrentlytheEMVCotypeapprovalisconfinedtothefirmwareversion1.
75.
ThisfirmwareversiondoesnotsupportthereadandwriteoperationsofiCLASScards.
ForastaticusageinISOmodeswitchthereaderbehaviorwiththefollowingregistryentry:[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CardInterface]ContactlessDefault=dword:00000000OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page71of102January201513DriverConfigurationviaProxFormat13.
1OverviewTheOMNIKEYreaderdrivercanbeconfiguredforawiderangeofHIDPROXcardformatsbothstandardandcustom,allowingthecardreadersystemtoprocessanyWiegandrawbitstream.
Driversettingscontrolhowrawdataisbeingtranslatedtodatafieldssuchasfacilitycode(FAC)andcardnumber(CN)thataremeaningfulwithinthescopeofphysicalaccesscontrolsystems(PACS).
ThischapterdescribestheProxFormatsettingavailabletocontroltheOMNIKEYreaderdriver.
ThisdocumentalsodescribeshowthesystemcanbeconfiguredtoreturneitherPACSfacilitycodeandcardnumberorjustrawWieganddata.
13.
2ATRFormatTheOMNIKEY5x25PROXreaderreturnsPROXcarddatainananswertoreset(ATR)commonlyusedinPC/SC-basedsmartcardsystems.
ForHIDPROXcards,thefirstbyteoftheATRisalways3Bhex.
ItisfollowedbyabytethatindicatesinitsLSBnibblehowmanyPROXdatabyteswillfollow.
Thethirdbyteholdsthecard'sProxFormat.
13.
2.
1ATRExampleThefollowingATRwasgeneratedbyacardthatreturnedtheWiegandrawdata00022564hex=100010010101100100bin.
ATR=3B050000022564|historicalbytes|5historicalbytesfollowing(LSbnibble)Historicalbytes0000022564||*carddata*||PROXformat(here0,meaningWiegandraw)Thesamecard,withProxFormatsettoH10301wouldreturnATR=3B06010001004786hex–acardwithFAC=1andCN=4786.
DescribedlaterinthisguideishowtoparseandtranslaterawdatatodatafieldsaccordingtotheapplicablePROXFormat.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page72of10213.
3AvailableProxFormatSettingsInadditiontoHIDPROXstandardcardformatssuchasH10301,H10302,H10304,H10320andCorp1000therearehundredsofproprietaryformats.
Thismeans,thatthesamebitstreamcanbeinterpretedinmanydifferentwaysusingProxFormatsettingsshownbelow.
Table7:ProxFormatSettingsProxFormatValueHexCardformatDatacontentWindowsLinux/MacOSNokeyWiegandRaw-Yes(default)1No00WiegandRaw-YesYes01H1030126bit(FAC+CN)YesNo02H1030237bit(CN)YesNo04H1030437bit(FAC+CN)YesNo14H1032032bitclock/datacardYesNo64Corp100035bit(CIC+CN)YesNoFEAUTOAutomaticmodeYesYes(default)2FF3CUSTOMCustomerdefinedYesYes1DuringdriverinstallationonWindows-basedsystems,noProxFormatkeyisset.
ThedriverinterpretsthisasifProxFormatweresettozeroi.
e.
theATRreturnsWiegandrawdata.
2ProxFormatsettingsarenotpartofthedriverinstallationonsystemsrunningLinux/MacOS.
ThedriverinterpretsthisasifProxFormatweresettozeroFEhex(automaticmode)3SettingProxFormattoCUSTOMrequiresadditionalregistrykeysCostomProxFormat.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page73of102January201513.
3.
1ProxFormatSettingsonSystemsRunningWindowsBydefault,theOMNIKEYreadersystemreturnsrawWieganddata.
ThisdefaultbehaviorcanbechangedusingtheProxFormatWindowsregistryentry.
NotethatitrequiresadministratorrightstoinstallandconfiguretheOMNIKEYPROXreaderdriverandPROXcardregistrysettings.
TheProxFormatregistryentryresidesinthefollowingregistrypath:[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan]Figure9:ProxFormatRegistryEntry13.
3.
2ProxFormatSettingsonSystemsRunningLinuxandMacOSXBydefault,LinuxandMacOSX-basedsystemsareconfiguredtoautomaticPROXcarddetectionmode.
Driverconfigurationsettingsarereadfromafilenamedcmrfid.
iniresidingin/etc/directory.
TheINIfilecontainssectionsandentriessimilartotheWindowsregistrysettings.
Examples:Contentsoffilecmrfid.
initosetProxFormattoAUTO[ProximityOptions]ProxFormat=254Contentsoffilecmrfid.
initosetProxFormattoCUSTOM[ProximityOptions]ProxFormat=255[CustomProxFormat-A]StartBit=14BitLength=10[CustomProxFormat-B]StartBit=1BitLength=13OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page74of10214ProxFormatSettings14.
1WiegandRawDataModeProxFormat=0Thismodegivesyouthegreatestflexibility.
Thisisimportantinsystemswithoutawell-knowncardpopulationi.
e.
wherethecardformatcanvaryorevenisunknown.
Havingthisflexibilitycomesatapricethough,anyparsingthatotherwiseisdonebythedriverwouldhavetobedonebythehoistapplication.
14.
2StandardFormatModesH10301,H10302,H10304,H10320andCorporate1000arestandardcardformatssupportedviadedicatedProxFormatsettingaccordingtothefollowingtable.
CARDProxFormatSetting(hexformat)ATRFORMATFAC/CICCNH10301AAAABBBBBB013B0601AAAABBBBBBH10302-BBBBBBBBBBBB023B0702BBBBBBBBBBBBH10304AAAAABBBBBB043B07040AAAAABBBBBBH10320-BBBBBBBB143B0514BBBBBBBBCorp1kAAAABBBBBBBB643B0764AAAABBBBBBBBExample:SettingProxFormatto'01'instructsthedrivertointerprettheseriesofbitsreceivedfromaPROXcardasHIDH10301formattedPROXdata.
TherightmostsixBCDformatteddigitsofthehistoricalbyteblockrepresentthecardnumberCN.
Thecardnumbercanalsobefoundengravedonthecard.
WithProxFormatsetto'01',acardwithFAC=0001andCN=000061wouldreturnanATRof'3B06010001000061'.
TIP:Ifyoudonotknowwhetheryouhaveastandardorcustomformattedcard,setProxFormattohexFE(AUTO).
Thenpresentthecard.
Ifthereadercandetectastandardcardformat,itwillreturnitsrespectiveProxFormatvalueinthethirdATRbyte.
Thisisaquickwaytofindouttheformatofthemostpopularcards.
14.
3AutomaticModeProxFormat=FEhex=254decInAUTOmode,thedrivertriestoparsethebitstreamandmatchitwithaknownformat.
ThismodeisonlyrecommendedforthefollowingcardformatsH10301,H10302,H10320andCorporate1000Note:thatautomaticmodeisrestrictedtothecardformatslistedabove.
H10304isnotpartofthislistbecausethereadersystemcan'tdistinguishH10302cardsfromH10304cards.
Theyareboth37bitformats.
TheonlydifferencebetweenthetwoformatsisthatH10304formattedcardscontainafacilitycodewhereasH10302cardsdonot.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page75of102January201514.
4CustomFormatModeProxFormatsettoFFhex=255dec.
ThismoderequiresadditionalCustomProxFormatsettings.
Thismodeallowsyoutoconfigurethecardsystemforanystandardorcustomizedcardformat.
14.
4.
1CustomProxFormatSettingsInadditiontosettingProxFormatto255dec,CustomProxFormatsettingsmustbeset.
ThistellstheOMNIKEYPROXreaderdriverwheretofindmeaningfuldatafieldswithintherawWiegandbitsequence.
Therawbit-data-streamcanbesplitintoupto15severaldata-fields.
Eachdatafieldislabeledwithaletter(A,B…etc.
).
EachdatafieldisdefinedbyitsStartBitandBitLength.
DatafieldsmayreflectacardnumberCNorafacilitycodeFAC.
TheStartBitentryspecifiesthepositioninthebit-data-stream,startingwiththeleastsignificantbit(LSb)–that'sallthewaytotheright.
Example:00000100bin…bit0=0,bit1=0,bit2=1,….
WhenevercustomProxFormatisused,therehavetobeadditionalsettingstodefinestartbitsandthenumberofbitsfortherequiredcustomformat.
ForanHIDPROXH10301formattedcard,youwouldneedthefollowingadditionalentriestogetitsFACandCNwithProxFormatsetto255.
Theseentriestellthedriverwheretostartandhowmanybitstointerpretasdatafieldforanygivensection.
WindowsRegistry:[HKLM\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]StartBit=dword00000011BitLength=dword:00000008[HKLM\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]StartBit=dword00000001BitLength=dword:00000010Linux/MaxOSXinifile:[CustomProxFormat-A]StartBit=17BitLength=8[CustomProxFormat-B]StartBit=1BitLength=16OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page76of102ThefollowingsectionsshowCustomProxFormatentriesforsomestandardPROXcardformatsincludingtherawdataandresultingparsedandinterpreteddatafieldsforfacilitycodeandcardnumber.
14.
5Example:H10301PROXCardThefollowingexampledemonstrateshowtoextractthefacilitycodeFAC=1andcardnumberCN=12345fromaH10301formatted26bitPROXcard.
Withitstwoparitybitsthiscardcanhold24informationbits.
14.
5.
1StandardFormatThestandardformatH10301issupportedviaProxFormat=1and254(AUTO)14.
5.
2WiegandRawDataProxFormat=0ATR:3B050002026073hexHistoricalBytes:02026073hex=00000010000000100110000001110011bin000000PaaaaaaaabbbbbbbbbbbbbbbbP00000010000000100110000001110011PParityBitaFacilityCode(FAC)bitsbCardNumber(CN)bitsFAC=00000001bin=0001dec(4digits,definedbyH10301format)CN=0011000000111001bin=012345dec(6digits,definedbyH10301format)14.
5.
3CustomProxFormatSettingsProxFormat=255WindowsCustomProxFormatSettings:[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]StartBit=dword:00000011BitLength=dword:00000008[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]StartBit=dword:00000001BitLength=dword:00000010Linux,MacOSXCustomProxFormatSettings:[CustomProxFormat-A]StartBit=17BitLength=8[CustomProxFormat-B]StartBit=1BitLength=1614.
5.
4ATRsofaH10301CardH10301PROXcardFAC=1,CN=12345ProxFormat=0(RAW)3B050002026073ProxFormat=1(H10301)3B06010001012345ProxFormat=254(AUTO)3B06010001012345ProxFormat=255(CUSTOM)CustomProxFormat\A:StartBit/Length=17/8CustomProxFormat\B:StartBit/Length=1/163B06FF0001012345OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page77of102January201514.
6Example:H10302PROXCardThefollowingexampledemonstrateshowtoextractthecardnumberCN=1fromaH10302formatted37bitPROXcard.
Thistypeofcardhasnofacilitycodeavailable.
Withitstwoparitybitsthiscardcanhold35informationbits.
14.
6.
1StandardFormatThestandardformatH10302issupportedviaProxFormat=2and254(AUTO)14.
6.
2WiegandRawDataProxFormat=0ATR:3B06000000000002hexHistoricalBytes:0000000002hex=0000000000000000000000000000000000010binPaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaP0000000000000000000000000000000000010PParityBitaCardNumber(CN)bitsCN=00000000000000000000000000000000001bin=00000000001dec(11digits,definedbyH10302format)FAC=N/A14.
6.
3CustomProxFormatSettingsProxFormat=255WindowsCustomProxFormatSettings:[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]StartBit=dword:00000001BitLength=dword:00000023Linux,MacOSXCustomProxFormatSettings:[CustomProxFormat-A]StartBit=1BitLength=3514.
6.
4ATRsofaH10302CardH10302PROXcardCN=00000000001ProxFormat=0(RAW)3B06000000000002ProxFormat=2(H10302)3B0702000000000001ProxFormat=254(AUTO)3B0702000000000001ProxFormat=255(CUSTOM)CustomProxFormat\A:StartBit/Length=1/353B07FF000000000001OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page78of10214.
7Example:H10304PROXCardThisexampledemonstrateshowtoextractthefacilitycodeFAC=65535andcardnumberCN=524287fromaH10304formatted37bitPROXcard.
Withitstwoparitybitsthiscardcanhold35informationbits.
14.
7.
1StandardFormatThestandardformatH10304issupportedviaProxFormat=4.
DonotuseAUTOduetoambiguousresultswhenusedwithother37bitformats.
14.
7.
2WiegandRawDataProxFormat=0ATR:3B06000FFFFFFFFFhexHistoricalBytes:0FFFFFFFFFhex=0111111111111111111111111111111111111binPaaaaaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbP0111111111111111111111111111111111111PParityBitaFacilityCodebits(FAC)bCardNumberbits(CN)FAC=1111111111111111bin=65535dec(4digits,definedbyH10304format)CN=1111111111111111111bin=524287dec(6digits,definedbyH10304format)14.
7.
3CustomProxFormatSettingsProxFormat=255WindowsCustomProxFormatSettings:[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]StartBit=dword:00000014BitLength=dword:00000010[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]StartBit=dword:00000001BitLength=dword:00000013Linux,MacOSXCustomProxFormatSettings:[CustomProxFormat-A]StartBit=20BitLength=16[CustomProxFormat-B]StartBit=1BitLength=1914.
7.
4ATRsofaH10304CardH10301PROXcardFAC=1,CN=12345ProxFormat=0(RAW)3B06000FFFFFFFFFProxFormat=4(H10304)3B0704065535524287ProxFormat=255(CUSTOM)CustomProxFormat\A:StartBit/Length=20/16CustomProxFormat\B:StartBit/Length=1/193B07FF065535524287OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page79of102January201514.
8Example:Corp1000PROXCardThefollowingexampledemonstrateshowtoextractthecustomerIDcodeCIC=4096andcardnumberCN=2fromaCorp1000formatted35bitPROXcard.
Duetothreeparitybitsthiscardformatholds32informationbits.
14.
8.
1StandardFormatThestandardformatCorp1000issupportedviaProxFormat=100or254(AUTO)14.
8.
2WiegandRawDataProxFormat=0ATR:3B060003FFE00005hexHistoricalBytes:03FFE00005hex=01111111111111000000000000000000101binPPaaaaaaaaaaaabbbbbbbbbbbbbbbbbbbbP01111111111111000000000000000000101PParityBitaFacilityCode(FAC)bitsbCardNumber(CN)bitsCIC=111111111111bin=4095dec(4digits,definedbyCorp1000format)CN=00000000000000000010bin=00000002dec(8digits,definedbyCorp1000format)14.
8.
3CustomProxFormatSettingsProxFormat=255[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\A]StartBit=dword:00000015BitLength=dword:0000000C[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\CardMan\CustomProxFormat\B]StartBit=dword:00000001BitLength=dword:00000014Linux,MacOSXCustomProxFormatSettings:[CustomProxFormat-A]StartBit=21BitLength=12[CustomProxFormat-B]StartBit=1BitLength=2014.
8.
4ATRsofaCorp1000CardCorp1000PROXcardCIC=4095,CN=2ProxFormat=0(RAW)3B060003FFE00005ProxFormat=100(Corp1000)3B0764409500000002ProxFormat=254(AUTO)3B0764409500000002ProxFormat=255(CUSTOM)CustomProxFormat\A:StartBit/Length=21/12CustomProxFormat\B:StartBit/Length=1/203B07FF409500000002WindowsCustomProxFormatSettings:OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page80of102Appendix:AApplicationProgrammingThefollowingC++sampleprojectispartofthesynchronousAPIwhichcanbedownloadedfromourwebsiteatwww.
hidglobal.
com/omnikey.
Ifyouchoosethedefaultinstallationsettings,samplecodeisfoundin:c:\ProgramFiles\HIDGlobal\Sync-API\Samples\contactlessdemovc.
SamplecodeforVisualBasicisalsoavailableandfoundin:c:\ProgramFiles\Samples\contactlessdemovb.
ThesampleusestheOMNIKEYsynchronousAPIanddemonstrateshowtoselectareader,connectacard,andaccesseitheraMIFAREoriCLASScard.
A.
1OverviewFromtheConnectedReaderlist(top-leftcorner),selectthereader.
Thelistcontainsallreadersavailabletothesmartcardresourcemanager.
Whenacardisinserted,displayedaretheATR,UIDandCardNamefields.
FromtheReaderRelatedFunctionframe,selectthefunctionswithorwithoutacardintheRFfield.
OnlyusetheMIFAREFunctionsusingSyncAPIframewhenaMIFAREcardisinthefield.
UsetheISO7816/iCLASS/PCSC2.
01frameforAPDUexchangewithaCPUcard(asynchronouscard)inthefield.
Eachprocessedcommandproducesoutputintheoutputlog.
ClearthelogwiththeRefreshOutputScreenbutton.
ThereturnstatusofthelastexecutedfunctionisshownintheLastOperationStatusframe.
ClosetheapplicationwiththeExitbutton.
Figure10:SampleProgramScreenOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page81of102January2015A.
2ReaderRelatedFunctionsReaderrelatedfunctionsdonotrequireacardinthefield.
TostoreaMIFAREkey,completethefollowing:Defineakeynumbertodeterminewheretostorethekey.
Selectplainorsecuredasthemodeofthekeytransmission.
Forsecuredtransmissions,usetransmissionkeynumber0x80or0x81.
EnterthekeyinhexstringformattothetextfieldMIFAREKey.
Forplaintransmissionsentera6byte,12hexdigitvalue(nospaces).
Forsecuredtransmissionenteran8bytevalue.
ClickontheWriteMIFAREKeytoReaderbuttontoloadthekeytoreadermemory.
A.
3MIFAREFunctionsUsingSynchronousAPIBeforeusingtheMIFAREFunctionsusingSyncAPI,authenticatethecard.
(MIFAREUltraLightdoesnotneedauthentication).
Toauthenticatetoablockofthecardcompletethefollowing:InthefieldBlockNr,entertheauthenticationblocknumber.
InthefieldAccessOptionchoosetosupplyakeynumberorplainkey.
InthefieldAuthenticationModechooseModeAorB.
PresstheAuthenticatebutton.
Uponsuccessfulauthentication,youcanreadandwritedatablocksandusetheincrementanddecrementfunctions.
A.
4PC/SC2.
01EnteranAPDUaccordingtoPC/SC2.
01toaccessstoragecardssuchasMIFAREcardsdirectlywithoutusingtheOMNIKEYproprietarysynchronousAPI.
A.
5ISO7816-APDUEnteranAPDUforyourCPU(asynchronous)cardandsendtheAPDUthesamewayasanISO7816contactcard.
A.
6iCLASSStandardModePresentaniCLASScardtothereaderRFfield,andsendAPDUsdirectlytothecard,seeSection9StandardCommunicationwithiCLASSCard.
Thisisaneasywayofexperimentingwiththeavailablefunctions.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page82of102A.
7CodeExamplesThissectionlistscodingexamplesforaPC/SC2.
01compliantimplementation.
A.
7.
1GettingtheCardUID(PC/SC2.
01)ThefollowingfunctionretrievestheuniquecardID(UID)currentlyconnectedtothecardthroughtheairinterface.
UsetheUIDasthecardserialnumber.
TheUIDisavailableforeveryISO14443A/BorISO15693compliantcards.
ItdoesnotmatterwhetherthecardisaCPUorstoragecard.
ThismakesGetUIDtheidealcandidateforHelloCardtypeapplications.
Ifyoudonothaveaccesstoapplicationkeys,theUIDservesasavaluableidentifierallowingcardlookuponabackenddatabase.
BOOLEANGetUID(UCHAR*UID,int&sizeofUID){ucByteSend[0]=0xFF;//CLAucByteSend[1]=0xCA;//INSucByteSend[2]=0x00;//P1ucByteSend[3]=0x00;//P2ucByteSend[4]=0x00;//LeulnByteSend=5;printf(\nRetrievingtheUID.
SCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,ucByteReceive,&dwRecvLength);if(SCard_Status!
=SCARD_S_SUCCESS){printf(\nProbleminSCardTransmit,Errorcode=0x%04X,SCard_Status);returnFALSE;}if(ucByteReceive[dwRecvLength-2]!
=0x90||ucByteReceive[dwRecvLength-1]!
=0x00){printf(\nWrongreturncode:%02X%02X,ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);returnFALSE;}sizeofUID=dwRecvLength-2;memcpy(UID,ucByteReceive,sizeofUID);returnTRUE;}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page83of102January2015A.
7.
2LoadingaMIFAREKey(PC/SC2.
01)ThefollowingcodeloadsaMIFAREkeytothereader.
Thekeyisstoredinnon-volatilememory.
Onceloaded,itremainsavailablethroughoutthereadersession.
BOOLEANLoadKey(UCHARucKeyNr,UCHAR*ucKey,UCHARucKeyLength){ucByteSend[0]=0xFF;//CLAucByteSend[1]=0x82;//INSucByteSend[2]=0x20;//P1cardkey,plaintransmission,non-volatilememoryucByteSend[3]=ucKeyNr;//P2keynumberforMIFAREcouldbe0x00to0x31)ucByteSend[4]=ucKeyLength;//Lcmemcpy(ucByteSend+5,ucKey,ucKeyLength);ulnByteSend=5+ucKeyLength;printf(\nLoadingKeytothereader.
SCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,ucByteReceive,&dwRecvLength);if(SCard_Status!
=SCARD_S_SUCCESS){printf(\nProbleminSCardTransmit,Errorcode=0x%04X,SCard_Status);returnFALSE;}if(ucByteReceive[dwRecvLength-2]!
=0x90||ucByteReceive[dwRecvLength-1]!
=0x00){printf(\nWrongreturncode:%02X%02X,ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);returnFALSE;}returnTRUE;}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page84of102A.
7.
3MIFARE1K/4KAuthenticate(PC/SC2.
01)ThefollowingcodedemonstrateshowtoauthenticateaMIFAREcard.
BOOLEANAuthenticate(UCHARBlockNr,UCHARucKeyNr,UCHARucKeyType){ucByteSend[0]=0xFF;//CLAucByteSend[1]=0x88;//INSucByteSend[2]=0x00;//P1,MIFAREBlockNumberMSB,forMIFAREitisalways0x00ucByteSend[3]=BlockNr;//MIFAREBlockNumberLSBucByteSend[4]=ucKeyType;//P3ucByteSend[5]=ucKeyNr;ulnByteSend=6;printf(\nAuthenticatingSCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,ucByteReceive,&dwRecvLength);if(SCard_Status!
=SCARD_S_SUCCESS){printf(\nProbleminSCardTransmit,Errorcode=0x%04X,SCard_Status);returnFALSE;}if(ucByteReceive[dwRecvLength-2]!
=0x90||ucByteReceive[dwRecvLength-1]!
=0x00){printf(\nWrongreturncode:%02X%02X,ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);returnFALSE;}returnTRUE;}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page85of102January2015A.
7.
4MIFARE1K/4KWrite(PC/SC2.
01)BOOLEANUpdateBinary(UCHARBlockNr,UCHAR*ucDataToWrite,UCHARucDataLenght){ucByteSend[0]=0xFF;//CLAucByteSend[1]=0xD6;//INSucByteSend[2]=0x00;//P1,MIFAREBlockNumberMSB,forMIFAREitisalways0x00ucByteSend[3]=BlockNr;//MIFAREBlockNumberLSBucByteSend[4]=ucDataLenght;memcpy(ucByteSend+5,ucDataToWrite,ucDataLenght);ulnByteSend=5+ucDataLenght;printf(\nUpdatingBlockSCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,ucByteReceive,&dwRecvLength);if(SCard_Status!
=SCARD_S_SUCCESS){printf(\nProbleminSCardTransmit,Errorcode=0x%04X,SCard_Status);returnFALSE;}if(ucByteReceive[dwRecvLength-2]!
=0x90||ucByteReceive[dwRecvLength-1]!
=0x00){printf(\nWrongreturncode:%02X%02X,ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);returnFALSE;}returnTRUE;}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page86of102A.
7.
5MIFARE1K/4KRead(PC/SC2.
01)BOOLEANReadBinary(UCHARBlockNr,UCHAR*ucDataRead,UCHAR&ucDataLenght){ucByteSend[0]=0xFF;//CLAucByteSend[1]=0xB0;//INSucByteSend[2]=0x00;//P1,MIFAREBlockNumberMSB,forMIFAREitisalways0x00ucByteSend[3]=BlockNr;//MIFAREBlockNumberLSBucByteSend[4]=0x10;//LeulnByteSend=5;dwRecvLength=255;printf(\nReadingBlockSCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,ucByteReceive,&dwRecvLength);if(SCard_Status!
=SCARD_S_SUCCESS){printf(\nProbleminSCardTransmit,Errorcode=0x%04X,SCard_Status);returnFALSE;}if(ucByteReceive[dwRecvLength-2]!
=0x90||ucByteReceive[dwRecvLength-1]!
=0x00){printf(\nWrongreturncode:%02X%02X,ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);returnFALSE;}ucDataLenght=(unsignedchar)dwRecvLength-2;memcpy(ucDataRead,ucByteReceive,ucDataLenght);returnTRUE;}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page87of102January2015A.
7.
6MIFARE1K/4KIncrement(OMNIKEYProprietaryAPI)BOOLEANIncrement(UCHARBlockNr,UCHAR*ucDataTobeIncremented,UCHARucDataLenght){ucByteSend[0]=0xFF;//CLAucByteSend[1]=0xD4;//INSucByteSend[2]=0x00;//P1,MIFAREBlockNumberMSB,forMIFAREitisalways0x00ucByteSend[3]=BlockNr;//MIFAREBlockNumberLSBucByteSend[4]=ucDataLenght;memcpy(ucByteSend+5,ucDataTobeIncremented,ucDataLenght);ulnByteSend=5+ucDataLenght;printf(\nIncrementingBlockSCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,ucByteReceive,&dwRecvLength);if(SCard_Status!
=SCARD_S_SUCCESS){printf(\nProbleminSCardTransmit,Errorcode=0x%04X,SCard_Status);returnFALSE;}if(ucByteReceive[dwRecvLength-2]!
=0x90||ucByteReceive[dwRecvLength-1]!
=0x00){printf(\nWrongreturncode:%02X%02X,ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);returnFALSE;}returnTRUE;}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page88of102A.
7.
7MIFARE1K/4KDecrement(OMNIKEYProprietaryAPI)BOOLEANDecrement(UCHARBlockNr,UCHAR*ucDataTobeDecremented,UCHARucDataLenght){ucByteSend[0]=0xFF;//CLAucByteSend[1]=0xD8;//INSucByteSend[2]=0x00;//P1,MIFAREBlockNumberMSB,forMIFAREitisalways0x00ucByteSend[3]=BlockNr;//MIFAREBlockNumberLSBucByteSend[4]=ucDataLenght;memcpy(ucByteSend+5,ucDataTobeDecremented,ucDataLenght);ulnByteSend=5+ucDataLenght;printf(\nDecrementingBlockSCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,ucByteSend,ulnByteSend,NULL,ucByteReceive,&dwRecvLength);if(SCard_Status!
=SCARD_S_SUCCESS){printf(\nProbleminSCardTransmit,Errorcode=0x%04X,SCard_Status);returnFALSE;}if(ucByteReceive[dwRecvLength-2]!
=0x90||ucByteReceive[dwRecvLength-1]!
=0x00){printf(\nWrongreturncode:%02X%02X,ucByteReceive[dwRecvLength-2],ucByteReceive[dwRecvLength-1]);returnFALSE;}returnTRUE;}A.
7.
8MIFAREEmulationMode(OMNIKEYProprietaryAPI)WiththefollowingcodeswitchtheMIFAREEmulationModeonandoff.
#defineCM_IOCTL_SET_RFID_CONTROL_FLAGSSCARD_CTL_CODE(3213)DWORDdwActiveProtocol;//DWORDdwControlFlag=0xFFFFFFFF//OnDWORDdwControlFlag=0x00000004//On//DWORDdwControlFlag=0x00000000//OffBYTEInBuffer[16];BYTEOutBuffer[16];DWORDdwInBufferSize;DWORDdwOutBufferSize;DWORDdwBytesReturned;DWORD*Mask=(DWORD*)InBuffer;DWORD*Value=(DWORD*)InBuffer+1;DWORDdwControlCode=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;OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page89of102January2015SCard_Status=SCardControl(hCard,dwControlCode,(LPCVOID)InBuffer,dwInBufferSize,(LPVOID)OutBuffer,dwOutBufferSize,&dwBytesReturned);if(SCard_Status==SCARD_S_SUCCESS){if(dwControlFlag)sprintf(szText,MIFARE\t);elsesprintf(szText,T=CL\t);}else{sprintf(szText,IOCntrolerror\r);}//ThecardisdisconnectedafterchangingtheMIFAREemulationmodedo{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.
9iCLASSSelectPage(OMNIKEYProprietaryAPI)Thefollowingcodeselectspage0x01ofan8x2KSiCLASScardandreturnsthecardserialnumber.
//Selectpage0x02ofa8x2KSiCLASScardUCHARucDataSend[7]={0};ULONGulNoOfDataSend=7;UCHARucReceivedData[64]={0};ULONGulNoOfDataReceived=64;ucDataSend[0]=0x80//CLA,standardmodeucDataSend[1]=0xA6//INSucDataSend[2]=0x01//P1ucDataSend[3]=0x04//P2,returncardserialnumberucDataSend[4]=0x01//LcucDataSend[5]=0x01//PagenumberucDataSend[6]=0x08//LeSCard_Status=SCardCLICCTransmit(hCard,ucDataSend,ulNoOfDataSend,ucReceivedData,&ulNoOfDataReceived);if(SCard_Status!
=SCARD_S_SUCCESS){printf(ErrorinSCardCLICCTransmit,witherrorcode%8X,SCard_Status);exit(-1);}OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page90of102A.
7.
10EMVCoContactlessLevel2TransactionsThefollowingcodeexampleshowsatypicalOMNIKEY5321PAYtransactionloop.
SCARDCONTEXThContext;SCARDHANDLEhCard;SCARD_READERSTATEsReaderState;CHAR*szReaderName;DWORDdwShareMode;DWORDdwPreferredProtocols;DWORDdwActiveProtocols;UCHARucByteSend[256];DWORDdwNByteSend;UCHARabByteReceive[256];DWORDdwRecvLength;DWORDSCard_Status;UCHARabSelectPPSE[20]={0x00,0xA4,0x04,0x00,//CLA,INS,.
.
0x0E,//Lc0x32,0x50,0x41,0x59,0x2E,0x53,0x59,//Datafield0x53,0x2E,0x44,0x44,0x46,0x30,0x31,0x00};//Le//TODO:CodeforPAYapplicationdo{//waitforcarddo{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){//Cardpresent,Collisiondetected//TODO:CodeforPAYapplication//waitforremovecarddo{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);OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page91of102January2015continue;}//TODO:CodeforPAYapplication//ConnectcarddwShareMode=SCARD_SHARE_SHARED;dwPreferredProtocols=SCARD_PROTOCOL_T1;SCard_Status=SCardConnect(hContext,szReaderName,dwShareMode,dwPreferredProtocols,&hCard,&dwActiveProtocols);//TODO:CodeforPAYapplicationmemcpy(abByteSend,abSelectPPSE,20);dwNByteSend=20;do{dwRecvLength=256;SCard_Status=SCardTransmit(hCard,SCARD_PCI_T1,abByteSend,dwNByteSend,NULL,abByteReceive,&dwRecvLength);//TODO:CodeforPAYapplication}while(/*TODO:CodeforPAYapplication*/);//nowdisconnectthecardSCard_Status=SCardDisconnect(hCard,SCARD_UNPOWER_CARD);//TODO:CodeforPAYapplication//waitforremovecarddo{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:CodeforPAYapplication}while(/*TODO:CodeforPAYapplication*/);//TODO:CodeforPAYapplicationOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page92of102A.
7.
11SetRFIDoperatingmodeThefollowingcodeexampleshowssettingtheoperatingmode:#defineCM_IOCTL_SET_OPERATION_MODESCARD_CTL_CODE(3107)#defineOPERATION_MODE_RFID_ISO0x10#defineOPERATION_MODE_RFID_PAYPASS0x11BYTEInBuffer[4];BYTEOutBuffer[4];DWORDdwInBufferSize;DWORDdwOutBufferSize;DWORDdwBytesReturned;DWORDdwControlCode=CM_IOCTL_SET_OPERATION_MODE;memset(InBuffer,0x00,sizeof(InBuffer));memset(OutBuffer,0x00,sizeof(OutBuffer));*InBuffer=OPERATION_MODE_RFID_PAYPASSdwInBufferSize=1;dwOutBufferSize=0;dwBytesReturned=0;SCard_Status=SCardControl(hCard,dwControlCode,(LPCVOID)InBuffer,dwInBufferSize,(LPVOID)OutBuffer,dwOutBufferSize,&dwBytesReturned);OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page93of102January2015A.
7.
12PayPassSignalMAINLEDThefollowingcodeexampleshowsanapplicationusingthereadermainLED.
#defineCM_IOCTL_SIGNALSCARD_CTL_CODE(3058)#definePAYPASS_SIGNAL_MAINLED0x21BYTEInBuffer[4];BYTEOutBuffer[4];DWORDdwInBufferSize;DWORDdwOutBufferSize;DWORDdwBytesReturned;DWORDdwControlCode;BYTEbUSBMode=0x01;//USBPipeControlBYTEbReaderLEDs=0x02;//redLEDonBYTEbLEDMode=0x03;//applicationcontrolled//TODO:CodeforPAYapplicationmemset(InBuffer,0x00,sizeof(InBuffer));memset(OutBuffer,0x00,sizeof(OutBuffer));dwControlCode=CM_IOCTL_SIGNAL;InBuffer[0]=PAYPASS_SIGNAL_MAINLED;InBuffer[1]=bUSBMode;InBuffer[2]=(bReaderLEDs)&0x03;InBuffer[3]=bLEDMode;dwInBufferSize=4;dwOutBufferSize=0;dwBytesReturned=0;SCard_Status=SCardControl(hCard,dwControlCode,(LPCVOID)InBuffer,dwInBufferSize,(LPVOID)OutBuffer,dwOutBufferSize,&dwBytesReturned);if(SCard_Status!
=SCARD_S_SUCCESS){//TODO:CodeforPAYapplication}//TODO:CodeforPAYapplicationOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page94of102A.
7.
13PayPassSignalAdditionalLEDsThefollowingcodeexampleshowsanapplicationusingthethreeadditionalLEDs.
#defineCM_IOCTL_SIGNALSCARD_CTL_CODE(3058)#definePAYPASS_SIGNAL_ADDLED0x22BYTEInBuffer[4];BYTEOutBuffer[4];DWORDdwInBufferSize;DWORDdwOutBufferSize;DWORDdwBytesReturned;DWORDdwControlCode;BYTEbUSBMode=0x01;//USBPipeControlBYTEbReaderLEDs=0x1C;//alladditionalgreenLEDsonmemset(InBuffer,0x00,sizeof(InBuffer));memset(OutBuffer,0x00,sizeof(OutBuffer));dwControlCode=CM_IOCTL_SIGNAL;InBuffer[0]=PAYPASS_SIGNAL_ADDLED;InBuffer[1]=bUSBMode;InBuffer[2]=(bReaderLEDs>>2)&0x07;dwInBufferSize=3;dwOutBufferSize=0;dwBytesReturned=0;SCard_Status=SCardControl(hCard,dwControlCode,(LPCVOID)InBuffer,dwInBufferSize,(LPVOID)OutBuffer,dwOutBufferSize,&dwBytesReturned);if(SCard_Status!
=SCARD_S_SUCCESS){//TODO:CodeforPAYapplication}//TODO:CodeforPAYapplicationOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page95of102January2015A.
7.
14PayPassSignalToneThefollowingcodeexampleshowsanapplicationusingthebuzzer.
#defineCM_IOCTL_SIGNALSCARD_CTL_CODE(3058)#defineACOUSTIC_SIGNAL_BEEPER_ON0x10#defineACOUSTIC_SIGNAL_BEEPER_OFF0x11BYTEInBuffer[4];BYTEOutBuffer[4];DWORDdwInBufferSize;DWORDdwOutBufferSize;DWORDdwBytesReturned;DWORDdwControlCode;memset(InBuffer,0x00,sizeof(InBuffer));memset(OutBuffer,0x00,sizeof(OutBuffer));dwControlCode=CM_IOCTL_SIGNAL;InBuffer[0]=ACOUSTIC_SIGNAL_BEEPER_ON;dwInBufferSize=1;dwOutBufferSize=0;dwBytesReturned=0;SCard_Status=SCardControl(hCard,dwControlCode,(LPCVOID)InBuffer,dwInBufferSize,(LPVOID)OutBuffer,dwOutBufferSize,&dwBytesReturned);//TODO:CodeforPAYapplicationmemset(InBuffer,0x00,sizeof(InBuffer));memset(OutBuffer,0x00,sizeof(OutBuffer));dwControlCode=CM_IOCTL_SIGNAL;InBuffer[0]=ACOUSTIC_SIGNAL_BEEPER_OFF;dwInBufferSize=1;dwOutBufferSize=0;dwBytesReturned=0;SCard_Status=SCardControl(hCard,dwControlCode,(LPCVOID)InBuffer,dwInBufferSize,(LPVOID)OutBuffer,dwOutBufferSize,&dwBytesReturned);//TODO:CodeforPAYapplicationOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page96of102Appendix:BAccessingiCLASSMemoryThefollowingdescribesthefreezonesoftwotypicaliCLASSmemorylayouts.
MemoryLayoutShownisthememorylayoutofaniCLASS2KS,iCLASS16KSorpage0ofaniCLASS8x2KScard.
BlockNumberBlockDescription(blocksizeeightbytes)'00'cardserialnumber'01'configurationblock'02'e-Purse'03'Kd(so-calleddebitkey,keyforapplication1)'04'Kc(so-calledcreditkey,keyforApplication2)'05'applicationissuerarea'06'HIDapplication….
'12''13'FreezonesiniCLASS2KS,iCLASS16KSorpage0ofiCLASS8x2KS….
'1F'(2KS)'FF'(16KS)ShownisthememorylayoutofaniCLASS8x2KSonpages1to7.
BlockSize:8bytes'00'cardserialnumber'01'configurationblock'02'e-Purse'03'Kd(so-calleddebitkey,keyforapplication1)'04'Kc(so-calledcreditkey,keyforApplication2)'05'applicationissuerarea'06'application1(freezonesiniCLASS8x2KSotherthanpage0)….
'xx''xx'+1application2(freezonesiniCLASS8x2KSotherthanpage0)….
'1F'OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page97of102January2015Appendix:CApplication2-AssigningSpaceBydefault,iCLASScardshavetheapplicationlimitsettothelastbyteofitsrespectivememoryarea.
Thismeansthecompletememoryareaisreservedforapplication1andthesizeofapplication2issettozero.
Theapplicationlimitcanbesettoadifferentblocknumbertosupportanadditionalapplication.
Todothis,thepage'sconfigurationblockmustbeoverwritten.
1.
Selectthepageyouwanttoconfigure.
2.
AuthenticatewiththeselectedpageKd.
3.
Read8bytesfromblock0x01–theconfigurationblock.
4.
Replacethefirstbytewiththeblocknumber'xx'ofthenewapplicationlimit.
5.
Leavetheremainingbytesoftheconfigurationblockunchangedandwriteall8bytesbacktotheconfigurationblock0x01.
6.
Removethecard.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page98of102Appendix:DiCLASSRead/WriteMemory-2KS,16KSor8x2KSpage01.
Insertcard.
2.
Connecttocard.
3.
Forsecuredmode:StartSession.
4.
AuthenticatewithKMC0,(P1=0x01,P2=0x23).
IfthekeyisnotaniCLASSdefaultkey,thenewkeyhastobeloadedasKIAMCorKVAK,andintheauthenticatecommandthekeynumberofKIAMCorKVAKmustbeused.
5.
Read/writeanyblock(blocknumber0x13to0x1Ffor2KSand0xFFfor16KS).
6.
Forsecuredmode:EndSession.
7.
Disconnectfromcard.
8.
Removecard.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page99of102January2015Appendix:EiCLASS8x2KSCard-Pages1to7Read/WriteMemory1.
Insertcard.
2.
Connecttocard.
3.
Forsecuredmode:StartSession.
4.
SelectpageN(N=1to7).
5.
AuthenticatewithKMDN/KMCN(P1=0x00forKMDN,or0x01forKMCN,P2=KMDN,/KMCN(SeeSection8.
1KeyNumberingScheme).
6.
IfthekeyisotherthaniCLASSdefaultkey,thenewkeyhastobeloadedasKIAMCorKVAK,andintheauthenticatecommandthekeynumberofKIAMCorKVAKmustbeused.
7.
Read/writeanyblock(blocknumber0x13to0x1Ffor2KSand0xFFfor16KS).
8.
Forsecuredmode:EndSession.
9.
Disconnectcard.
10.
Removecard.
OMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4January2015Page100of102Appendix:FTermsandAbbreviationsThefollowinglistsabbreviationsusedthroughoutthisdocument.
CSNRCardSerialNumberHDHHostDataHeaderINSDataInstructionSpecificDataKCURCustomerReadKeyKCUWCustomerWriteKeyKDOKMOMNIKEYDiversifiedMasterKeyKENCCardDataEncryptionKeyKIAMCKeyforApplication2atpage0KMCNPageNApplication2'sMasterKeyofiCLASScardKMDCHIDMasterKeyCurrentKMDNPageNApplication1'sMasterKeyofiCLASScardKMDNB1PageNApplication1'sonBook1MasterKeyofiCLASScardKMDOHIDMasterKeyOldKMTDPicoPassMasterTransportkeyforapplication1KMTCPicoPassMasterTransportkeyforapplication2KOKMOMNIKEYMasterKeyKSSessionKeyKVAKAnyVolatileApplicationMasterKeyLcINSInstructionspecificdata(INSData)length.
LcRCardResponsedatalengthPCDProximityCouplingDevicePICCProximityICCardPPSEProximityPaymentSystemEnvironmentRDHReaderDataHeaderRSNRReaderSerialNumberOMNIKEYContactlessSmartCardReadersDevelopersGuide,5321-903,Rev.
B.
4Page101of102January2015Appendix:GReferences[DESFIRE]MIFAREDESFireDataSheetshttp://www.
nxp.
com/documents/short_data_sheet/MF3ICDX21_41_81_SDS.
pdf[EMVCo]EuropayMastercardVisaCorporationhttp://www.
emvco.
com/approvals.
aspxid=86[ICLASSD]iCLASScardspecificationsfromHID.
[iCODESL2]ICODESL2DataSheethttp://www.
nxp.
com/acrobat_download/other/identification/SL113730.
pdf[ISO7816-4]InformationTechnologyIdentificationCardsIntegratedCircuit(s)CardswithContacts,Part4:Inter-industryCommandsforInterchange[LRI64]STMicroelectronicsdatasheetforLRI64[MIFARE]MIFAREDataSheetshttp://www.
nxp.
com/acrobat_download2/other/identification/M001053_MF1ICS50_rev5_3.
pdf[MSDNLIB]MicrosoftDeveloperNetworkLibrary;http://msdn.
microsoft.
com/library/[PCSC_2.
01]PC/SCWorkgroupSpecifications2.
01http://www.
pcscworkgroup.
com/[PICO2KS]PICOTAGandPICOCRYPTsecured2KSdatasheetfromtheInsideContactless[PICO16KS]PICOTAGandPICOCRYPTsecured16KSdatasheetfromtheInsideContactlesshidglobal.
com