The Smart Card Detective (SCD)
|
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 |
Defines | |
#define | MAX_EXCHANGES 50 |
Maximum number of command-response pairs recorded when logging. | |
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, log_struct_t *logger) |
This function sends a T=0 command from the terminal to the ICC. | |
FCITemplate * | ApplicationSelection (uint8_t convention, uint8_t TC1, const ByteArray *aid, uint8_t autoselect, log_struct_t *logger) |
Starts the application selection process. | |
APPINFO * | InitializeTransaction (uint8_t convention, uint8_t TC1, const FCITemplate *fci, log_struct_t *logger) |
Initialize a transaction by sending GET PROCESSING OPTS command. | |
RECORD * | GetTransactionData (uint8_t convention, uint8_t TC1, const APPINFO *appInfo, ByteArray *offlineAuthData, log_struct_t *logger) |
Retrieves all the Data Objects from the card. | |
FCITemplate * | SelectFromAID (uint8_t convention, uint8_t TC1, const ByteArray *aid, log_struct_t *logger) |
Selects application based on AID list. | |
FCITemplate * | SelectFromPSE (uint8_t convention, uint8_t TC1, uint8_t sfiPSE, uint8_t autoselect, log_struct_t *logger) |
Selects application based on PSE. | |
uint8_t | VerifyPlaintextPIN (uint8_t convention, uint8_t TC1, const ByteArray *pin, log_struct_t *logger) |
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, log_struct_t *logger) |
Send a GENERATE AC request with the specified amounts. | |
RAPDU * | SignDynamicData (uint8_t convention, uint8_t TC1, const ByteArray *data, log_struct_t *logger) |
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, log_struct_t *logger) |
Return the specified primitive data object from the card. | |
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. | |
Variables | |
CRP * | transactionData [MAX_EXCHANGES] |
uint8_t | nTransactions |
uint8_t | nCounter |
terminal.h Header file
Contains definitions of functions used by a terminal application
Copyright (C) 2012 Omar Choudary (omar.choudary@cl.cam.ac.uk)
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Definition in file terminal.h.
#define MAX_EXCHANGES 50 |
Maximum number of command-response pairs recorded when logging.
Definition at line 37 of file terminal.h.
enum AC_REQ_TYPE |
Enum defining the types of GENERATE AC requests available
Definition at line 62 of file terminal.h.
enum CARD_PDO |
Enum defining the different primitive data objects retrieved using the GET DATA command
Definition at line 52 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 1439 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 1546 of file terminal.c.
FCITemplate* ApplicationSelection | ( | uint8_t | convention, |
uint8_t | TC1, | ||
const ByteArray * | aid, | ||
uint8_t | autoselect, | ||
log_struct_t * | logger | ||
) |
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 |
aid | the AID of the desired application; pass NULL to use existing list |
autoselect | just used for the case of PSE selection: use zero to enable user selection, non-zero to automatically select the first available application |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 248 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 1369 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 1739 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 1716 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 1696 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 1648 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 1673 of file terminal.c.
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 1631 of file terminal.c.
ByteArray* GetDataObject | ( | uint8_t | convention, |
uint8_t | TC1, | ||
CARD_PDO | pdo, | ||
log_struct_t * | logger | ||
) |
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) |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 1194 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 1162 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 1129 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 1107 of file terminal.c.
TLV* GetTLVFromRECORD | ( | RECORD * | rec, |
uint8_t | tag1, | ||
uint8_t | tag2 | ||
) |
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 1472 of file terminal.c.
RECORD* GetTransactionData | ( | uint8_t | convention, |
uint8_t | TC1, | ||
const APPINFO * | appInfo, | ||
ByteArray * | offlineAuthData, | ||
log_struct_t * | logger | ||
) |
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. |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 353 of file terminal.c.
APPINFO* InitializeTransaction | ( | uint8_t | convention, |
uint8_t | TC1, | ||
const FCITemplate * | fci, | ||
log_struct_t * | logger | ||
) |
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 |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 301 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 993 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 1253 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 1499 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 950 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 1409 of file terminal.c.
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 1321 of file terminal.c.
FCITemplate* SelectFromAID | ( | uint8_t | convention, |
uint8_t | TC1, | ||
const ByteArray * | aid, | ||
log_struct_t * | logger | ||
) |
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 |
aid | if given will be used as Application ID (AID), else use predefined list. This parameter remains untouched |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 477 of file terminal.c.
FCITemplate* SelectFromPSE | ( | uint8_t | convention, |
uint8_t | TC1, | ||
uint8_t | sfiPSE, | ||
uint8_t | autoselect, | ||
log_struct_t * | logger | ||
) |
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 |
autoselect | if non-zero the first application will be used, else the user will select from a menu (LCD needed). |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 558 of file terminal.c.
RAPDU* SendGenerateAC | ( | uint8_t | convention, |
uint8_t | TC1, | ||
AC_REQ_TYPE | acType, | ||
const TLV * | cdol, | ||
const GENERATE_AC_PARAMS * | params, | ||
log_struct_t * | logger | ||
) |
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) Any 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. |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 717 of file terminal.c.
ByteArray* SerializeTLV | ( | const TLV * | tlv | ) |
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 1592 of file terminal.c.
RAPDU* SignDynamicData | ( | uint8_t | convention, |
uint8_t | TC1, | ||
const ByteArray * | data, | ||
log_struct_t * | logger | ||
) |
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 |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 914 of file terminal.c.
RAPDU* TerminalSendT0Command | ( | CAPDU * | cmd, |
uint8_t | inverse_convention, | ||
uint8_t | TC1, | ||
log_struct_t * | logger | ||
) |
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 |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 92 of file terminal.c.
uint8_t VerifyPlaintextPIN | ( | uint8_t | convention, |
uint8_t | TC1, | ||
const ByteArray * | pin, | ||
log_struct_t * | logger | ||
) |
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 |
logger | a pointer to a log structure or NULL if no log is desired |
Definition at line 666 of file terminal.c.
uint8_t nTransactions |