terminal.h File Reference

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

RAPDUTerminalSendT0Command (CAPDU *cmd, uint8_t inverse_convention, uint8_t TC1)
 This function sends a T=0 command from the terminal to the ICC.
FCITemplateApplicationSelection (uint8_t convention, uint8_t TC1)
 Starts the application selection process.
APPINFOInitializeTransaction (uint8_t convention, uint8_t TC1, const FCITemplate *fci)
 Initialize a transaction by sending GET PROCESSING OPTS command.
RECORDGetTransactionData (uint8_t convention, uint8_t TC1, const APPINFO *appInfo, ByteArray *offlineAuthData)
 Retrieves all the Data Objects from the card.
FCITemplateSelectFromAID (uint8_t convention, uint8_t TC1)
 Selects application based on AID list.
FCITemplateSelectFromPSE (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.
RAPDUSendGenerateAC (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.
RAPDUSignDynamicData (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.
TLVGetPDOLFromFCI (const FCITemplate *fci)
 Returns the PDOL TLV from a FCI.
TLVGetPDOL (const FCITemplate *fci)
 Returns a PDOL TLV from a FCI or a default one.
ByteArrayGetDataObject (uint8_t convention, uint8_t TC1, CARD_PDO pdo)
 Return the specified primitive data object from the card.
const TLVGetTLVFromRECORD (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.
FCITemplateParseFCI (const uint8_t *data, uint8_t lenData)
 Parse a FCI Template object from a data stream.
TLVParseTLV (const uint8_t *data, uint8_t lenData, uint8_t includeValue)
 Parse a TLV object from a data stream.
TLVCopyTLV (const TLV *data)
 Makes a copy of a TLV.
RECORDParseRECORD (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.
RECORDParseManyTLV (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.
APPINFOParseApplicationInfo (const uint8_t *data, uint8_t len)
 Returns the AIP and AFL List from the response of GET PROCESSING OPTS.
ByteArraySerializeTLV (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.

Detailed Description

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.


Enumeration Type Documentation

Enum defining the types of GENERATE AC requests available

Enumerator:
AC_REQ_AAC 
AC_REQ_ARQC 
AC_REQ_TC 

Definition at line 42 of file terminal.h.

enum CARD_PDO

Enum defining the different primitive data objects retrieved using the GET DATA command

Enumerator:
PDO_ATC 
PDO_LAST_ATC 
PDO_PIN_TRY_COUNTER 
PDO_LOG_FORMAT 

Definition at line 32 of file terminal.h.


Function Documentation

uint8_t AddRECORD ( RECORD dest,
const RECORD src 
)

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.

Parameters:
dest the RECORD in which the new data from src will be appended
src the RECORD containing the data to be copied on dest
Returns:
0 if successful, non-zero otherwise This function allocates the necessary memory for the extra data needed in the dest RECORD object. If there is not sufficient memory (indicated by a non-zero return value) then the contents of this RECORD will be truncated or NULL.

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

Parameters:
record RECORD structure to be parsed
Returns:
the position (starting at 1) of the Authorized Amount value inside CDOL1 if found, 0 if unsuccessful

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.

Parameters:
convention parameter from ATR
TC1 parameter from ATR
Returns:
the FCI Template resulted from application selection or NULL if there is an error. The caller is responsible for eliberating the memory used by the FCI Template.

Definition at line 198 of file terminal.c.

TLV* CopyTLV ( const TLV data  ) 

Makes a copy of a TLV.

This function copies the contents of a TLV into a new TLV structure

Parameters:
data the TLV to be copied
Returns:
the new TLV object or NULL if there is an error. This function allocates the necessary memory for the TLV object. It is the caller responsability to free that memory after use.

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

Parameters:
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

Parameters:
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

Parameters:
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

Parameters:
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

Parameters:
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

Parameters:
data the TLV structure to be erased

Definition at line 1436 of file terminal.c.

ByteArray* GetDataObject ( uint8_t  convention,
uint8_t  TC1,
CARD_PDO  pdo 
)

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.

Parameters:
convention parameter from ATR
TC1 parameter from ATR
pdo the kind of data object you want to retrieve (see CARD_PDO)
Returns:
a ByteArray structure containing the data retrieved or NULL if no data is available or there is an error. The caller is responsible to release the memory used by the ByteArray structure

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'.

Parameters:
fci FCI Template containing or not a PDOL. If NULL then a default PDOL will be returned
Returns:
TLV object contianing a PDOL
See also:
GetPDOLFromFCI

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

Parameters:
fci FCI Template to search for the PDOL
Returns:
a pointer to the TLV representing the PDOL or NULL if the PDOL was not found or an error ocurred

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)

Parameters:
response RAPDU containing the response to a SELECT command
Returns:
SFI value or 0 if error

Definition at line 921 of file terminal.c.

const 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.

Parameters:
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.
Returns:
a const pointer to the TLV within the RECORD structure or NULL if the TLV cannot be found or some error occurs

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

Parameters:
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.
Returns:
a RECORD structure containing all the data objects read or NULL if there are no objects to read or an error ocurrs

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.

Parameters:
convention parameter from ATR
TC1 parameter from ATR
fci the FCI Template returned in application selection
Returns:
an APPINFO cotnaining the AIP and AFL or NULL if an error ocurrs

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.

Parameters:
data the stream to be parsed
len the length of the data to be parsed
Returns:
APPINFO structure containing the AIP and AFL List This function allocates the necessary memory for the APPINFO object. It is the caller responsability to free that memory after use. If the method is not successful it will return NULL.

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

Parameters:
data stream of bytes to be parsed
lenData total length in bytes of data
Returns:
the parsed FCITemplate object. This function allocates the necessary memory for the FCITemplate object. It is the caller responsability to free that memory after use.

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

Parameters:
data the stream to be parsed
lenData the length of the data to be parsed
Returns:
RECORD structure containing the TLV objects parsed This function allocates the necessary memory for the RECORD object. It is the caller responsability to free that memory after use. If the method is not successful it will return NULL.

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

Parameters:
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
Returns:
zero if success, non-zero otherwise This function allocates the necessary memory for the RECORDList object. It is the caller responsability to free that memory after use. If the method is not successful it will return NULL.

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

Parameters:
data the stream to be parsed
lenData the length of the data to be parsed
Returns:
RECORD structure containing the TLV objects parsed This function allocates the necessary memory for the RECORD object. It is the caller responsability to free that memory after use. If the method is not successful it will return NULL.

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

Parameters:
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
Returns:
the parsed TLV object. This function allocates the necessary memory for the TLV object. It is the caller responsability to free that memory after use.

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.

Parameters:
convention parameter from ATR
TC1 parameter from ATR
Returns:
the FCI Template resulted from application selection or NULL if there is an error. The caller is responsible for eliberating the memory used by the FCI Template.
See also:
ApplicationSelection

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.

Parameters:
convention parameter from ATR
TC1 parameter from ATR
sfiPSE the SFI of the PSE as returned from an initial SELECT command
Returns:
the FCI Template resulted from application selection or NULL if there is an error. The caller is responsible for eliberating the memory used by the FCI Template.
See also:
ApplicationSelection

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

Parameters:
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.
Returns:
the response APDU given by the card or NULL if an error ocurred. The caller is responsible for eliberating this memory.

Definition at line 562 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.

Parameters:
tlv TLV object to serialize
Returns:
the stream of bytes representing the TLV

Definition at line 1397 of file terminal.c.

RAPDU* SignDynamicData ( uint8_t  convention,
uint8_t  TC1,
const ByteArray data 
)

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.

Parameters:
convention parameter from ATR
TC1 parameter from ATR
data ByteArray structure containing the data that shall be passed to the INTERNAL AUTHENTICATE command
Returns:
the response APDU given by the card or NULL if an error ocurred. The caller is responsible for eliberating this memory.

Definition at line 732 of file terminal.c.

RAPDU* TerminalSendT0Command ( CAPDU cmd,
uint8_t  inverse_convention,
uint8_t  TC1 
)

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

Parameters:
cmd Command APDU to be sent
inverse_convention different than 0 if inverse convention is to be used
TC1 byte returned in the ATR
Returns:
the RAPDU created from the card reply, or NULL if a response APDU cannot be constructed

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

Parameters:
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
Returns:
0 if the PIN is correct, non-zero otherwise or if an error ocurred

Definition at line 520 of file terminal.c.

 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines

Generated on Mon Dec 20 16:40:31 2010 for The Smart Card Detective (SCD) by  doxygen 1.6.1