Below is the uncorrected machine-read text of this chapter, intended to provide our own search engines and external engines with highly rich, chapter-representative searchable text of each book. Because it is UNCORRECTED material, please consider the following text as a useful but insufficient proxy for the authoritative book pages.
92 A P P E N D I X A The API proposed under this work is intended to standardize the implementation aspects associated with contactless smartcards as a fare media for mass transit applications. A.1 API Functions This section describes the functions that will be provided by the API and the associated param- eters, return values, and pre/post conditions for each function. Table A-1 presents the API-provided CloseReader function used to close an open interface to a particular contactless smartcard reader. Table A-2 describes the API-provided GetDriverCap function used to return information about the driver capabilities for the API-compliant driver. This would include information about the API version supported and any support for optional API instructions. Table A-3 describes the API-provided GetPCDProp function used to retrieve a list of proper- ties associated with the actual hardware reader defined by a particular reader ID. This command serves as a configuration interrogation utility. Table A-4 describes the API-provided GetPCDStatus function used to retrieve the current status of the PCD. This command can be used to verify the current condition of a particular reader. Table A-5 describes the API-provided OpenReader function used to initialize and open an interface to a particular contactless smartcard reader. Table A-6 describes the API-provided Poll function used to instruct the reader to initiate prob- ing of the field for contactless card(s). The behavior of the Poll will be defined by the options defined in the xPICC parameter. Table A-7 describes the API-provided RetrieveFirmware function used to extract currently installed firmware from a reader supporting this type of download. It is intended to function as a standard firmware extraction utility for retrieving an image to be used in a potential restoration. Table A-8 describes the API-provided SendFirmware function used to send an updated firmware to a reader supporting this type of upload. It is intended to function as a standard firmware mounting utility. Table A-9 describes the API-provided SetPCDProp function used to set attributes associated with the actual hardware reader defined by a particular interface ID in PCDProp. This command serves as a configuration-setting utility. Set of Functionality for a Standard API
Set of Functionality for a Standard API 93 Table A-1. TCRPAPI: CloseReader. Table A-2. TCRPAPI: GetDriverCap. Table A-3. TCRPAPI: GetPCDProp. Table A-4. TCRPAPI: GetPCDStatus. Syntax int CloseReader ( PCD* xPCD ); Data Type Field Name Description PCD* xPCD Pointer to the PCD structure 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) The function returns 0 if successful. Otherwise, it returns 2008. Syntax int GetDriverCap (DriverCap* xCap); Data Type Field Name Description DriverCap* xCap Pointer to the DriverCap structure 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) Function returns 0 if successful. Otherwise, returns 2008. Syntax int GetPCDProp (PCDProp* xPCDprop); Data Type Field Name Description PCDProp* xPCDProp Pointer to the PCDProp structure 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) Reader properties and attributes will be set to PCDProp structure if the function execution is successful. Syntax int GetPCDStatus (PCD* xPCD); Data Type Field Name Description PCD* xPCD Pointer to PCD structure 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) Outgoing command status is set to nPCDstatus of PCD structure will be set to current status of a reader. The information shall indicate the type of reader, its communication type, and target reader identification number.
94 Smartcard Interoperability Issues for the Transit Industry Table A-7. TCRPAPI: RetrieveFirmware. Table A-5. TCRPAPI: OPENREADER. Table A-6. TCRPAPI: Poll. Syntax int OpenReader (PCD* xPCD); Data Type Field Name Description PCD* xPCD Pointer to PCD structure 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) The function returns 0 if successful. Otherwise, it returns 2008. Device Identifier will be assigned in PCD structure if successful. (It will be assigned to zero if device identifier is not supported.) Syntax int Poll (PICC* xPICC, PCD xPCD); Data Type Field Name Description PICC* xPICC Pointer to the PICC structure PCD xPCD PCD structure 0 Successful execution 2008 Failed execution 2002 Timeout Return Value 2088 No precise diagnosis Precondition The OpenReader function should be executed successfullyprior to Poll function. Return Code(s) If there is no card in the field, nPICCTYPE is set to 0x00 in PICC structure. If a card is found in the field, its serial number is assigned to the byte array of nPICCUid and the length of the serial number is assigned to nPICCUidLen in PICC structure. If the card in the field is ISO 14443-4 compliant, bISOPart4 is set to true in PICC structure. Syntax int RetrieveFirmware (Firmware* xFirm int nID); Data Type Field Name Description Firmware* xFirm Pointer to Firmware structure int nID Interface ID of the communication target. 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) Function returns 0 if successful. Otherwise, it returns 2008.
Set of Functionality for a Standard API 95 Table A-10 describes the API-provided TransmitToCard function used to instruct the reader to send a block of data to the card and retrieves a response frame if there is a response from the card before a specified timeout, which is configured in the Response_Frame structure. Table A-8. TCRPAPI: SendFirmware. Table A-10. TCRPAPI: TransmitToCard. Table A-9. TCRPAPI: SetPCDProp. Syntax int SendFirmware (Firmware* xFirm int nID); Data Type Field Name Description Firmware* xFirm Pointer to Firmware structure int nID Interface ID of the communication target. 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) Function returns 0 if successful. Otherwise, it returns 2008. Syntax int SetPCDProp (PCDProp xPCDprop); Data Type Field Name Description PCDProp xPCDProp PCDProp structure 0 Successful execution Return Value 2008 Failed execution Precondition None Return Code(s) Function returns 0 if successful. Otherwise, it returns 2008. Syntax int TransmitToCard ( Command_Frame xCommandFrame, Response_Frame* xResponseFrame, BYTE nPICCType, PCD xPCD); Data Type Field Name Description Command_Frame xCommandFrame Command_Frame structure for outgoing command frame to the card. Response_Frame* xResponseFrame Pointer to the Response_Frame structure for the incoming response frame from the card. BYTE nPICCType Type of card PCD xPCD PCD structure 0 Successful execution 2008 Failed execution 2002 Timeout Return Value 2088 No precise diagnosis Precondition OpendReader and Poll functions should be executed successfully prior to TransmitToCard function. Return Code(s) Outgoing command status is set to nPCDstatus of the Response_Frame structure. Incoming response frame from the card is set to the byte array baReceiveFrame and the length of the response frame is set to nActualLength in the Response_Frame structure.
96 Smartcard Interoperability Issues for the Transit Industry A.2 API Structures This section defines the data structures used as parameters by the functions. Table A-11 defines the Command_Frame structure that contains the outgoing command frame to the card and its length. Table A-12 defines the DriverCap structure, which contains the supported API version num- ber and information about any support for optional API instructions. Table A-13 defines the Firmware structure that contains the size, revision level, intended check- sum, and actual binary image to be transferred to the target reader. Table A-14 defines the PCD structure, which contains interface information about the con- tactless smartcard reader. Table A-15 defines the PCDProp structure that contains the particular properties and attrib- utes of the associated reader with respect to smartcard communication. It includes the number of SAM slots, the modulation types supported, and options to define the antenna strength, pro- tocols, and target reader identification number. Table A-16 defines the PICC Structure that contains the options to define behavior of the polling. Table A-17 defines the POLLPICCTYPE structure that contains an options defined type of card to be polled from the reader. Table A-18 defines the Response_Frame structure that contains incoming response data from the card and the options to define timeout delay to retrieve the response frame. Table A-11. Command_Frame structure. Table A-12. DriverCap structure. Parameters List of members Data Type Field Name Description short nLength Length of the command frame BYTE* baSendFrame Outgoing command data frame Remark: Outgoing command data (baSendFrame) must be terminated by 0x00. If the raw command length is 2, a null terminator shall be appended and the length of the command frame in this structure will be 3. For example: the raw command is {0x5F, 0x02}. The data in baSendFrame of this structure would be set to {0x5F, 0x02, 0x00}, and the value of nLength would be set to 3. Parameters List of members Data Type Field Name Description BYTE nVersion Supported TCRP API version char* cOptional Supported optional API instructions
Set of Functionality for a Standard API 97 Table A-13. Firmware structure. Table A-14. PCD structure. Table A-15. PCDProp structure. Parameters List of members Data Type Field Name Description WORD nRevisionLevel Revision level number of the firmware unsigned long int nSize Number of bytes of the firmware content unsigned char* cImage Firmware content WORD nCheckSum CRC of the firmware content Parameters List of members Data Type Field Name Description BYTE nDevice Target reader to be initialized. BYTE nID Interface ID for identification of communication target. This provides for multi reader operation under a single host BYTE nCommType Communication Type, Serial = 0x01, USB = 0x02 BYTE nComPort COM port number BYTE nPCDstatus PCD operational status 0: good 1: out of service char* cUsbName USB device name Parameters List of members Data Type Field Name Description BYTE nDevice Target reader identification number int nAntennaStrength Options to set the readerâs antenna strength char* cProtocol Options to set the readerâs protocol mode BYTE nSAM Number of SAM slots in the reader char* cModType Reader Modulation Type
98 Smartcard Interoperability Issues for the Transit Industry Table A-16. PICC structure. Table A-17. POLLPICCTYPE structure. Table A-18. Response_Frame structure. Parameters List of members Data Type Field Name Description POLLPICCTYPE xPICCTYPE Type of card to poll BYTE nPICCsToSearch Number of card to search BYTE nTimeout Timeout delay for polling short nSessionID Session ID for communication to the card BYTE nPICCUid[256] Card Serial Number int nPICCUidLen Length of serial number BYTE nPICCTYPE Type of card found, 0x01 = Mifare Ultralight 0x02 = Mifare DESFire Remark: Future version will have more card types. bool bISOPart4 ISO 7816 part-4 compliant Parameters List of members Data Type Field Name Description bool ISOA TYPE A card bool ISOB TYPE B card bool MifareClassic Phillips Mifare Classic 1K card bool MifareUltralight Phillips Mifare Ultralight card bool Jewel Jewel card bool MV4000 MV 4K card Parameters List of members Data Type Field Name Description short nExpectedLength Expected length of the response frame short nActualLength Actual length of the response frame BYTE baReceiveFrame[256] Incoming response data frame int nPCDStatus Outgoing command status short nNumIterations Number of iteration to check the response frame from the card short nIterationTimeout Timeout delay of each iteration
A.3 Example (OpenReader, CloseReader, Poll, TransmitToCard): int retValue; BYTE piccType = 0x02; PCD reader; reader.nCommType = 0x01; reader.nComPort = 0x03; retValue = OpenReader(&reader); if(retValue == 0) { PICC card; card.xPICCType.ISOA = true; card.xPICCType.ISOB = true; card.xPICCType.MifareClassic = false; card.xPICCType.MifareUltralight = false; card.xPICCType.Jewel = false; card.xPICCType.MV4000 = false; card.nPICCsToSearch = 0; card.bISOPart4 = false; retValue = Poll(&card, reader); if(retValue == 0 && card.nPICCTYPE != 0x00) { BYTE acutalCommand[3] = {0x5F, 0x02, 0x00}; Command_Frame commandStruct; Response_Frame responseStruct; commandStruct.baSendFrame = actual Command; commandStruct.nLength = 3; responseStruct.nNumIterations = 2; responseStruct.nIterationTimeout = 100; response.nExpectedLength = 1; retValue = TransmitToCard(command Struct, &response Struct, piccType, reader); } } CloseReader(reader); Set of Functionality for a Standard API 99
