terminal.h Header file More...
Go to the source code of this file.
Classes | |
struct | TLV |
struct | RECORD |
struct | FCITemplate |
struct | FCIList |
struct | RECORDList |
struct | AFL |
struct | APPINFO |
struct | GENERATE_AC_PARAMS |
Enumerations | |
enum | CARD_PDO { PDO_ATC = 0x36, PDO_LAST_ATC = 0x13, PDO_PIN_TRY_COUNTER = 0x17, PDO_LOG_FORMAT = 0x4F } |
enum | AC_REQ_TYPE { AC_REQ_AAC = 0, AC_REQ_ARQC = 0x80, AC_REQ_TC = 0x40 } |
Functions | |
RAPDU * | TerminalSendT0Command (CAPDU *cmd, uint8_t inverse_convention, uint8_t TC1) |
This function sends a T=0 command from the terminal to the ICC. | |
FCITemplate * | ApplicationSelection (uint8_t convention, uint8_t TC1) |
Starts the application selection process. | |
APPINFO * | InitializeTransaction (uint8_t convention, uint8_t TC1, const FCITemplate *fci) |
Initialize a transaction by sending GET PROCESSING OPTS command. | |
RECORD * | GetTransactionData (uint8_t convention, uint8_t TC1, const APPINFO *appInfo, ByteArray *offlineAuthData) |
Retrieves all the Data Objects from the card. | |
FCITemplate * | SelectFromAID (uint8_t convention, uint8_t TC1) |
Selects application based on AID list. | |
FCITemplate * | SelectFromPSE (uint8_t convention, uint8_t TC1, uint8_t sfiPSE) |
Selects application based on PSE. | |
uint8_t | VerifyPlaintextPIN (uint8_t convention, uint8_t TC1, const ByteArray *pin) |
Checks if the specified PIN is accepted by the card. | |
RAPDU * | SendGenerateAC (uint8_t convention, uint8_t TC1, AC_REQ_TYPE acType, const TLV *cdol, const GENERATE_AC_PARAMS *params) |
Send a GENERATE AC request with the specified amounts. | |
RAPDU * | SignDynamicData (uint8_t convention, uint8_t TC1, const ByteArray *data) |
Sign the Dynamic Application Data using INTERNAL AUTHENTICATE. | |
uint8_t | GetSFIFromSELECT (const RAPDU *response) |
Returns the SFI value from the response to a SELECT command. | |
TLV * | GetPDOLFromFCI (const FCITemplate *fci) |
Returns the PDOL TLV from a FCI. | |
TLV * | GetPDOL (const FCITemplate *fci) |
Returns a PDOL TLV from a FCI or a default one. | |
ByteArray * | GetDataObject (uint8_t convention, uint8_t TC1, CARD_PDO pdo) |
Return the specified primitive data object from the card. | |
const TLV * | GetTLVFromRECORD (RECORD *rec, uint8_t tag1, uint8_t tag2) |
Returns a TLV from a RECORD based on its tag. | |
uint8_t | AmountPositionInCDOLRecord (const RECORD *record) |
Get the position of the Authorized Amount value inside CDOL1 if exists. | |
FCITemplate * | ParseFCI (const uint8_t *data, uint8_t lenData) |
Parse a FCI Template object from a data stream. | |
TLV * | ParseTLV (const uint8_t *data, uint8_t lenData, uint8_t includeValue) |
Parse a TLV object from a data stream. | |
TLV * | CopyTLV (const TLV *data) |
Makes a copy of a TLV. | |
RECORD * | ParseRECORD (const uint8_t *data, uint8_t lenData) |
Parse a record from a stream of data. | |
uint8_t | AddRECORD (RECORD *dest, const RECORD *src) |
Adds the contents of a record at the end of another one. | |
RECORD * | ParseManyTLV (const uint8_t *data, uint8_t lenData) |
Parses a data stream containing many TLV objects. | |
uint8_t | ParsePSD (RECORDList *rlist, const uint8_t *data, uint8_t lenData) |
Extract the available applications from a Payment System Directory. | |
APPINFO * | ParseApplicationInfo (const uint8_t *data, uint8_t len) |
Returns the AIP and AFL List from the response of GET PROCESSING OPTS. | |
ByteArray * | SerializeTLV (const TLV *tlv) |
Get a stream of bytes representing a TLV. | |
void | FreeTLV (TLV *data) |
Eliberates the memory used by a TLV structure. | |
void | FreeRECORD (RECORD *data) |
Eliberates the memory used by a RECORD structure. | |
void | FreeRECORDList (RECORDList *data) |
Eliberates the memory used by a RECORDList structure. | |
void | FreeFCITemplate (FCITemplate *data) |
Eliberates the memory used by a FCITemplate structure. | |
void | FreeFCIList (FCIList *data) |
Eliberates the memory used by a FCIList structure. | |
void | FreeAPPINFO (APPINFO *data) |
Eliberates the memory used by an APPINFO structure. |
terminal.h Header file
Contains definitions of functions used by a terminal application
Copyright (C) 2010 Omar Choudary (osc22@cam.ac.uk)
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.
Definition in file terminal.h.
enum AC_REQ_TYPE |
Enum defining the types of GENERATE AC requests available
Definition at line 42 of file terminal.h.
enum CARD_PDO |
Enum defining the different primitive data objects retrieved using the GET DATA command
Definition at line 32 of file terminal.h.
Adds the contents of a record at the end of another one.
This method copies the contents of the RECORD src after the existing contents of the RECORD dest.
dest | the RECORD in which the new data from src will be appended | |
src | the RECORD containing the data to be copied on dest |
Definition at line 1244 of file terminal.c.
uint8_t AmountPositionInCDOLRecord | ( | const RECORD * | record | ) |
Get the position of the Authorized Amount value inside CDOL1 if exists.
This function parses a RECORD structure and searches for the CDOL1 tag. If found, it searches for the position of the Authorized Amount value inside the CDOL1. This function is used in applications like FilterGenerateAC to determine in which place is sent the amount of a transaction
record | RECORD structure to be parsed |
Definition at line 1351 of file terminal.c.
FCITemplate* ApplicationSelection | ( | uint8_t | convention, | |
uint8_t | TC1 | |||
) |
Starts the application selection process.
This function handles the application selection process, where the first choice is the PSE selection and then a list of AIDs. See EMV 4.2 book 1, page 143.
convention | parameter from ATR | |
TC1 | parameter from ATR |
Definition at line 198 of file terminal.c.
Makes a copy of a TLV.
This function copies the contents of a TLV into a new TLV structure
data | the TLV to be copied |
Definition at line 1174 of file terminal.c.
void FreeAPPINFO | ( | APPINFO * | data | ) |
Eliberates the memory used by an APPINFO structure.
Eliberates the memory used by an APPINFO structure
data | the APPINFO structure to be erased |
Definition at line 1544 of file terminal.c.
void FreeFCIList | ( | FCIList * | data | ) |
Eliberates the memory used by a FCIList structure.
Eliberates the memory used by a FCIList structure
data | the FCIList structure to be erased |
Definition at line 1521 of file terminal.c.
void FreeFCITemplate | ( | FCITemplate * | data | ) |
Eliberates the memory used by a FCITemplate structure.
Eliberates the memory used by a FCITemplate structure
data | the FCITemplate structure to be erased |
Definition at line 1501 of file terminal.c.
void FreeRECORD | ( | RECORD * | data | ) |
Eliberates the memory used by a RECORD structure.
Eliberates the memory used by a RECORD structure
data | the RECORD structure to be erased |
Definition at line 1453 of file terminal.c.
void FreeRECORDList | ( | RECORDList * | data | ) |
Eliberates the memory used by a RECORDList structure.
Eliberates the memory used by a RECORDList structure
data | the RECORDList structure to be erased |
Definition at line 1478 of file terminal.c.
void FreeTLV | ( | TLV * | data | ) |
Eliberates the memory used by a TLV structure.
Eliberates the memory used by a TLV structure
data | the TLV structure to be erased |
Definition at line 1436 of file terminal.c.
Return the specified primitive data object from the card.
This function returns the specified primitive data object (see enum CARD_PDO) from the card using the GET DATA command.
convention | parameter from ATR | |
TC1 | parameter from ATR | |
pdo | the kind of data object you want to retrieve (see CARD_PDO) |
Definition at line 1007 of file terminal.c.
TLV* GetPDOL | ( | const FCITemplate * | fci | ) |
Returns a PDOL TLV from a FCI or a default one.
This method returns a TLV object containing a PDOL from either a FCI Template if the PDOL is available or makes a default one if the FCI Template is NULL or does not contain a PDOL. This method returns the tag as given in the FCI Template (usually '9F38'). In order to use it for GET_PROCESSING_OPTS you need to change to tag to '83'.
fci | FCI Template containing or not a PDOL. If NULL then a default PDOL will be returned |
Definition at line 976 of file terminal.c.
TLV* GetPDOLFromFCI | ( | const FCITemplate * | fci | ) |
Returns the PDOL TLV from a FCI.
Returns the PDOL object (TLV) from a FCI such as the one returned in application selection
fci | FCI Template to search for the PDOL |
Definition at line 943 of file terminal.c.
uint8_t GetSFIFromSELECT | ( | const RAPDU * | response | ) |
Returns the SFI value from the response to a SELECT command.
Parses the SFI value of the main directory (PSE) from the response of the first SELECT command (app selection)
response | RAPDU containing the response to a SELECT command |
Definition at line 921 of file terminal.c.
Returns a TLV from a RECORD based on its tag.
This method can be used to find a TLV within a RECORD structure.
rec | the RECORD structure to be searched for the TLV | |
tag1 | the first (or only) tag of the interested TLV | |
tag2 | the second tag of the interested TLV. This is to be used only in cases where the TLV we are looking for has a 2-byte tag. If the tag is only 1 byte then put 0 here. |
Definition at line 1277 of file terminal.c.
RECORD* GetTransactionData | ( | uint8_t | convention, | |
uint8_t | TC1, | |||
const APPINFO * | appInfo, | |||
ByteArray * | offlineAuthData | |||
) |
Retrieves all the Data Objects from the card.
This method retrieves all the Data Objects (TLVs) from the card as specified in the APPINFO structure, using READ RECORD commands. If the pointer to a ByteArray structure is non NULL then the offline authentication data is stored at that location
convention | parameter from ATR | |
TC1 | parameter from ATR | |
appInfo | the APPINFO structure that specifies which files to read | |
offlineAuthData | array of bytes representing the offline authentication data. The user should send an empty but initialized ByteArray if this data is required. This method will ignore any previous contents. |
Definition at line 285 of file terminal.c.
APPINFO* InitializeTransaction | ( | uint8_t | convention, | |
uint8_t | TC1, | |||
const FCITemplate * | fci | |||
) |
Initialize a transaction by sending GET PROCESSING OPTS command.
This function initiates a transaction by sending a GET PROCESSING OPTS command to the card. The caller is responsible for eliberating the memory used by the returned APPINFO.
convention | parameter from ATR | |
TC1 | parameter from ATR | |
fci | the FCI Template returned in application selection |
Definition at line 241 of file terminal.c.
APPINFO* ParseApplicationInfo | ( | const uint8_t * | data, | |
uint8_t | len | |||
) |
Returns the AIP and AFL List from the response of GET PROCESSING OPTS.
This method parses a stream of data corresponding to the response of GET PROCESSING OPTS command, and returns an APPINFO structure containing the AIP and AFL list.
data | the stream to be parsed | |
len | the length of the data to be parsed |
Definition at line 807 of file terminal.c.
FCITemplate* ParseFCI | ( | const uint8_t * | data, | |
uint8_t | lenData | |||
) |
Parse a FCI Template object from a data stream.
This function parses a stream of data and returns a FCI Template if the data is valid
data | stream of bytes to be parsed | |
lenData | total length in bytes of data |
Definition at line 1058 of file terminal.c.
RECORD* ParseManyTLV | ( | const uint8_t * | data, | |
uint8_t | lenData | |||
) |
Parses a data stream containing many TLV objects.
This method parses a stream of data containing several concatenated TLV objects and fills a RECORD structure
data | the stream to be parsed | |
lenData | the length of the data to be parsed |
Definition at line 1304 of file terminal.c.
uint8_t ParsePSD | ( | RECORDList * | rlist, | |
const uint8_t * | data, | |||
uint8_t | lenData | |||
) |
Extract the available applications from a Payment System Directory.
This method parses a stream of data corresponding to a Payment System Directory (such as the response to a READ RECORD command on the PSE) and adds it to an existing RECORDList structure containing the available applications as RECORD objects. The current implementation only handles a PSD wihtout directories. That means that it will parse only elements of type ADF, but none of type DDF
rlist | RECORDList structure used to store retrieved ADFs. This structure should be initialized before being passed to this method, which will only allocate memory for new records on the list and update the count | |
data | the stream to be parsed | |
lenData | the length of the data to be parsed |
Definition at line 764 of file terminal.c.
RECORD* ParseRECORD | ( | const uint8_t * | data, | |
uint8_t | lenData | |||
) |
Parse a record from a stream of data.
This method parses a stream of data representing a constructed BER-TLV, such as the response to a READ RECORD command, and fills a RECORD structure
data | the stream to be parsed | |
lenData | the length of the data to be parsed |
Definition at line 1214 of file terminal.c.
TLV* ParseTLV | ( | const uint8_t * | data, | |
uint8_t | lenData, | |||
uint8_t | includeValue | |||
) |
Parse a TLV object from a data stream.
This function parses a stream of data and returns a TLV object if the data contains a valid BER-TLV object
data | stream of bytes to be parsed | |
lenData | total length in bytes of data | |
includeValue | if this parameter is 0 then only the tag and length of the TLV are parsed (useful for Data Object Lists). If this parameter is non-zero then also the value of the TLV is returned |
Definition at line 1126 of file terminal.c.
FCITemplate* SelectFromAID | ( | uint8_t | convention, | |
uint8_t | TC1 | |||
) |
Selects application based on AID list.
This function handles the application selection by AID. For the moment it automatically selects the first available application, based on the bAIDList configuration, but this could be improved by actually storing a list of available applications and allowing the user to choose.
convention | parameter from ATR | |
TC1 | parameter from ATR |
Definition at line 399 of file terminal.c.
FCITemplate* SelectFromPSE | ( | uint8_t | convention, | |
uint8_t | TC1, | |||
uint8_t | sfiPSE | |||
) |
Selects application based on PSE.
This function handles the application selection by PSE.
convention | parameter from ATR | |
TC1 | parameter from ATR | |
sfiPSE | the SFI of the PSE as returned from an initial SELECT command |
Definition at line 446 of file terminal.c.
RAPDU* SendGenerateAC | ( | uint8_t | convention, | |
uint8_t | TC1, | |||
AC_REQ_TYPE | acType, | |||
const TLV * | cdol, | |||
const GENERATE_AC_PARAMS * | params | |||
) |
Send a GENERATE AC request with the specified amounts.
This function sends a GENERATE AC command to the card with the specified amount and request (ARQC, AAC or TC) Eny of the amount parameters can be sent as NULL in which case that field will be filled with zeros
convention | parameter from ATR | |
TC1 | parameter from ATR | |
cdol | the CDOL data object read from the card | |
acType | the type of Applicatio Cryptogram (AC) requested (see AC_REQ_TYPE) | |
params | a GENERATE_AC_PARAMS structure containing the data to be sent in the GENERATE AC command. This structure is mandatory for this command, even if some of the fields are unused. |
Definition at line 562 of file terminal.c.
Get a stream of bytes representing a TLV.
This method converts a TLV object into a stream of bytes, copying the contents of the TLV into the ByteArray. The caller is responsible for eliberating the memory used by the ByteArray returned.
tlv | TLV object to serialize |
Definition at line 1397 of file terminal.c.
Sign the Dynamic Application Data using INTERNAL AUTHENTICATE.
This function is used to make the card sign the Dynamic Application Data using the INTERNAL AUTHENTICATE command. This data is composed of some ICC-resident data and the data passed to this methdo.
convention | parameter from ATR | |
TC1 | parameter from ATR | |
data | ByteArray structure containing the data that shall be passed to the INTERNAL AUTHENTICATE command |
Definition at line 732 of file terminal.c.
This function sends a T=0 command from the terminal to the ICC.
This function handles the process of sending a command for the protocol T=0, including the intermediate GET_RESPONSE for the different command classes. Because of the recursivity of this method, it introduces an initial delay of 16 ICC ETUs to allow the card to be ready for a new command
cmd | Command APDU to be sent | |
inverse_convention | different than 0 if inverse convention is to be used | |
TC1 | byte returned in the ATR |
Definition at line 79 of file terminal.c.
uint8_t VerifyPlaintextPIN | ( | uint8_t | convention, | |
uint8_t | TC1, | |||
const ByteArray * | pin | |||
) |
Checks if the specified PIN is accepted by the card.
This function tests if the specified PIN is accepted by the card using the VERIFY command
convention | parameter from ATR | |
TC1 | parameter from ATR | |
pin | the PIN as a ByteArray having the structure required by the VERIFY command. The data in the ByteArray will be copied as it is on the VERIFY payload |
Definition at line 520 of file terminal.c.