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 exec2ption related to UI services used by card processing:

• gpiSwitchLED for LED #2

• gpiDisplayMessageByID for ID = PROCESSING

gpiGetString

SPED

dev_str_get_string_by_reference

gpiDisplayMessage

SPED

dev_lcd_put_string

Display a string at X and Y coordinates. gpiInitializeDisplay shall be called ahead for a proper lines/colums management

gpiDisplayMessageByID

SPED

dev_str_get_string_by_reference

Display a string from the string table indexed by ID

gpiSwitchLED

SPED

Swith on/off a LED. LED#2 is called duruing contactless card processing. LED#2 maybe display along with LED#3 if performance concerns.

Example:

uint16_t dev_led_switch(unit8_t led_id, uint8_t state, unit8_t color)
{
  if (LED_ID_2 == led_id)
  {
    return DEV_NO_ERROR;
  }
  else if (LED_ID_3 == led_id)
  {
    // Display LEDS #2 and #3
    // ...
  }
  // ...
}

gpiAdvancedDisplay

SPED

gpiAdvancedDisplayAsOutcome

SPED

gpiSetPollingMessage

SPED

N/A

Set the message (up to three lines) to be displayed at AgnosEP’s polling time

gpiDisplayPollingMessage

SPED

dev_lcd_put_string

Display the message (up to three lines) - 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

gpiRSAComputation

HSM

dev_hsm_rsa_computation

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

gpiShaInit

HSM

dev_hsm_sha_init

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

gpiShaUpdate

HSM

dev_hsm_sha_update

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

gpiShaFinal

HSM

dev_hsm_sha_final

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

gpiGetChecksum

HSM

dev_hsm_get_checksum

See gpihsm.h. Provide the checksum corresponding to each L2 CT/CL kernel

gpiGetRandomNumber

HSM

dev_hsm_get_random_number

See gpihsm.h.. Generate a random are between 0 and 255

gpiGetEMVCertificate (***)

HSM

dev_file_open

dev_file_read

dev_file_close

gpiGetEMVCRL (***)

HSM

dev_file_open

dev_file_read

dev_file_close

gpiFindPANFromEFL (***)

HSM

dev_file_open

dev_file_read

dev_file_close

xgpiApplicationBasedDES

xGPI

xgpiAES128CBCEncrypt

xGPI

File Management

Files are used to support the persistent model. However, using 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”

REVOCATED Files:

• “CRL”

EXCEPTION Files:

• “EFL”

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