User Interface

UI primitives are limited to a few set of mandatory functions (here below). EMV processing doesn’t require sophisticated displays. However, a minimum set of functions is required to provide a feedback to the cardholder and the merchants.

Even if card processing components don’t use UI services (see exceptions however), these primitives are important to implement early in the integration process in order to be able to trace when debugging the system.

There are two execption related to UI services used by card processing:

• gpiSwitchLED for LED #2

• gpiDisplayMessageByID for ID = PROCESSING

gpiGetString

SPED

dev_lcd_put_string

gpiDisplayMessage

SPED

dev_str_get_string_by_reference

gpiDisplayMessageByID

SPED

dev_str_get_string_by_reference

Display a string from the string table indexed by ID

gpiSwitchLED

SPED

gpiAdvancedDisplay

SPED

gpiAdvancedDisplayAsOutcome

SPED

gpiSetPollingMessage

SPED

Set the message to be displayed at AgnosEP’s polling time

gpiDisplayPollingMessage

SPED

Display the message - at AgnosEP’s polling time - that has been set from gpiSetPollingMessage

Memory

Platform/Memory primitives are used to optimize the memory allocation for card processing. Hence, no dynamic allocation is performed within the framework. There a 6 different king of RAM memory slots:

DEV_TOTAL_RAM (0x01): DEV_TAGS_RAM + DEV_UNKNOWN_TAGS_RAM + DEV_UNKNOWN_TAGS_RAM

DEV_TAGS_RAM (0x02): all tags supporting the card processing coming from device configuration or the card

DEV_UNKNOWN_TAGS_RAM (0x03): any tags coming out from the card and not supported by AgnosDB

DEV_FREE_RAM (0x04): extra RAM to support any king of processing beyond AGF if shared RAM used beyond AGF

DEV_SLOT_RAM (0x05): private RAM to store data to support a proprietary processing such as torn mechanism. As of tofay, C2/MCW and C5/JCB requires these pads.

DEV_DO_RAM (0x06): all tags corresponding to the CL combination in progress. This RAM space is used to load ENTRY POINT data (for a given transaction type) in order to prepare entry point confugration data specific to the transaction in progress.

Recommended sizes:

DEV_TAGS_RAM = 11500 bytes

DEV_UNKNOWN_TAGS_RAM = 2500 bytes

DEV_FREE_RAM = 3000 bytes

DEV_SLOT_RAM = 17100 bytes

DEV_DO_RAM = 10000 bytes

gpiGetTotalRAM

Platform

dev_get_shared_ram_size

dev_get_shared_ram

Provide a pointer and the corresponding available size

gpiGetRAMForTags

Platform

dev_get_shared_ram_size

dev_get_shared_ram

Provide a pointer and the corresponding available sizev

gpiGetRAMForUnknownTags

Platform

dev_get_shared_ram_size

dev_get_shared_ram

Provide a pointer and the corresponding available size

gpiGetFreeRAM

Platform

dev_get_shared_ram_size

dev_get_shared_ram

Provide a pointer and the corresponding available size

gpiGetPrivateScratchPAD

Platform

dev_get_shared_ram_size

dev_get_shared_ram

Provide a pointer and the corresponding available size

gpiGetDataObjectRAM

Platform

dev_get_shared_ram_size

dev_get_shared_ram

Provide a pointer and the corresponding available size

gpiMemCpy

Platform

dev_mem_copy

Standard C . See <string.h>

gpiMemCmp

Platform

dev_mem_cmp

Standard C . See <string.h>

gpiMemSet

Platform

dev_mem_set

Standard C . See <string.h>

gpiStrCpy

Platform

dev_str_copy

Standard C . See <string.h>

gpiStrNCpy

Platform

dev_str_n_copy

Standard C . See <string.h>

gpiStrCmp

Platform

dev_str_cmp

Standard C . See <string.h>

gpiStrLen

Platform

dev_str_len

Standard C . See <string.h>

RTC

Timers

Timers are used for two purposes:

• RRP (MCW)

• Profiling (optionaly)

typedef enum
{
  tsNONE,
  tsRUNNING,
  tsSTOPPED,
  tsTIMEOUT
} tTimerState;

typedef struct
{
  uint32_t mSecond;
  uint32_t mMicrosecond;
} tTimeValue;

typedef struct
{
  tTimerState mState;
  tTimeValue mStart;
  tTimeValue mStop;
  uint32_t mTimeout_second;
  uint32_t mTimeout_microsecond;
  uint32_t mElapsed_second;
  uint32_t mElapsed_second;
} tTimer;

Becareful, timers rely on dev_rtc_get_accurate_time_of_day implementation.

gpiGetDate

Platform

dev_rtc_get_date

gpiGetTime

Platform

dev_rtc_get_time

gpiSetDateTime

Platform

dev_rtc_set_date

dev_rtc_set_time

gpiResetTimers

Platform

N/A

Free up and reset all the timers

gpiGetMaxTimer

Platform

N/A

Maximum number of timers is set by default to 3 in the GPI (see rtc.c)

gpiGetTimer

Platform

N/A

Provide a free timer for further processing

gpiStartTimer

Platform

dev_rtc_get_accurate_time_of_day

gpiRestartTimer

Platform

dev_rtc_get_accurate_time_of_day

gpiStopTimer

Platform

dev_rtc_get_accurate_time_of_day

gpiGetTimerTime

Platform

dev_rtc_get_accurate_time_of_day

gpiGetTimerState

Platform

N/A

gpiFreeTimer

Platform

N/A

Reset a specific timer

gpiGetLastAllocated

Platform

N/A

Return the very last timer that was used

gpiSleep

Platform

dev_rtc_sleep

HSM

• xgpiAES128CBCEncrypt

• xgpiApplicationBasedDES

gpiRSAComputation

HSM

See gpihsm.h. This primitive is used from inside EMV core engine for ODA

gpiShaInit

HSM

See gpihsm.h. This primitive may ne used to calculate any SHA-1 based signatures

gpiShaUpdate

HSM

See gpihsm.h. This primitive may ne used to calculate any SHA-1 based signatures

gpiShaFinal

HSM

See gpihsm.h. This primitive may ne used to calculate any SHA-1 based signatures

gpiGetChecksum

HSM

Provide the checksum corresponding to each L2 CT/CL kernel

gpiGetRandomNumber

HSM

gpiGetEMVCertificate

HSM

gpiGetEMVCRL

HSM

File Management

Files are used to support the persistent model. However, a file system is not requirement, and a dedicated flash memory management may be implemented instead.

CONFIGURATION files:

• “TERMINAL”

• “PROCESSING”

• “ENTRY POINT”

DRL files:

• “DRL_VISA”

• “DRL_AMEX”

UPDATE CONDITIONS files:

• “UC_C2”

• “UC_C3”

• “UC_C4”

• “UC_C5”

• “UC_C7”

• “UC_EFTPOS”

• “UC_Flash”

• “UC_PURE”

KEY files:

• “CAKeys”

• “CRL”

gpiFileOpen

Platform

dev_file_open

Open a file. Provide a handler that can be used further for read/write/close operations

gpiFileClose

Platform

dev_file_close

Close a file

gpiFileRead

Platform

dev_file_read

Read from a file

gpiFileWrite

Platform

dev_file_write

Write in a file

gpiFileDelete

Platform

dev_file_delete

Delete a file

gpiFileRename

Platform

dev_file_rename

Rename a file

gpiFileGetSize

Platform

dev_file_get_size

Provide file’s size

Initialization

Among all initiaization features, gpiInitialize display is the most important as it enables hte UI services to work properly and these services are very useful at the early stage of the integration.

gpiInitialize relies on 3 Device services:

• dev_lcd_get_line_count: this simply provides the number of available lines on the display

• dev_lcd_get_column_count: this simply provides the number of available columns on the display

• dev_str_load_table: this creates the mapping between the string identifiers, the languages and the actual strings to be displayed.

As soon as the Device realizes this services, the GPI will dynamically manage the current line / column that is(are) used

gpiMain

Platform

GPI specific. May be used to initialize any parameters inside HAL and SAL

gpiInitialize

Platform

Platform specific. Enable any initialization related to the plaftorm

gpiInitializeDisplay

SPED

dev_lcd_get_line_count

dev_lcd_get_column_count

dev_str_load_table

gpiInitPolling

CAD

Platform specific. Enable any initialization realted to the contactless reader

gpiInitializeHSM

HSM

Platform specific. Enable any initialization related to the platform’s crypto

gpiGetTerminalIdentification

Platform

dev_get_identification

Map to EMVCo’s 9F1C

gpiGetSerialNumber

CAD

Map to EMVCo’s 9F1E

Card Interfaces

gpiSetTechnoToDetect

CAD

Set the type of technologies to be detected during a polling:

Technologies to detect are in:

• TECHNO_CL_ANY

• TECHNO_CL_TYPE_EMV

• TECHNO_MANUAL

• TECHNO_CONTACT

• TECHNO_MAGSTRIPE

gpiTechnoPolling

CAD

Perform a polling on technologies previously set.

gpiError are in:

• clcEMV_CARD

• scrCARD_INSERTED

• msrCARD_SWIPED

• keyNO_ERROR

• clcOTHER_CARD

gpiPowerOn

CAD

gpiPolling

CAD

Poll for a contactless card. Its implementation depends on the platform. It leverages on L1 API to detect a card, to detect a collision, and to activate a card.

gpiError are in:

• clcNO_ERROR

• clcEMV_CARD

• clc_COLLISION

• polTIMEOUT

• scrINTERRUPTED

• scrCARD_INSERTED

• msrCARD_SWIPED

• clcOTHER_CARd

• scrSYSTEM_ERROR

gpiGetPolledType

CAD

gpiExchangeAPDU

CAD

Send / Receive an APDU Command / Response

gpiGetLastExchangedAPDU

CAD

Provide last APDU command/response

gpiRemovalProcedure

CAD

As per EMVCo standard

gpiCardSwiped

CAD

If a card is swiped, return msrCARD_SWIPED

gpiCardInsterted

CAD

If a card is inserted, retunr scrCARD_INSERTED

gpiGetCardStatus

CAD

gpiReadMagstripe

CAD

Provide all card’s tracks after a swipe

gpiPowerOff

CAD

gpiPowerOffAllDevices

CAD

Swirch off all devices

gpiResetContactless

CAD

Reset antenna

gpiSetContactlessTransactionInProgress

CAD

Indicates that a contactless transaction is in progress. This setting is managed by GPI during the polling sequence

gpiSetContactTransactionInProgress

CAD

Indicates that a contact transaction is in progress. This setting is managed by GPI during the polling sequence

gpiSetSwipeTransactionInProgress

CAD

Indicates that a swipe transaction is in progress. This setting is managed by GPI during the polling sequence

IsSetContactlessTransactionInProgress

CAD

--

IsSetContactTransactionInProgress

CAD

--

IsSwipeTransactionInProgress

CAD

--

PIN Management

gpiPINEnter

SPED