Initialization

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

gpiInitializeDisplay 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 DEVICE realizes this services, the GPI will dynamically manage the current line / column that is(are) used.

gpiMain

Platform

dev_main

May be used to initialize any parameters inside HAL. Use this call at the start-up of the system.

gpiInitialize

Platform

dev_initialize

gpiCleanUp

Platform

dev_cleanup

May be used to clean any structures inside HAL between two transaction.

gpiRelease

Platform

dev_release

For example, use this primitive to free up memory. Use this call at the shut-down of the system.

gpiGetInterfaceVersionNumber

Platform

dev_interface_version

dev_get_version

Provide intertace and implementation versions.

gpiReset

Platform

dev_reset

Reset the device. Mandatory for VCAS testing.

gpiInitializeDisplay

SPED

dev_lcd_get_line_count

dev_lcd_get_column_count

dev_str_load_table

See above.

gpiInitPolling

CAD

dev_pcd_initialize

Platform specific. Enable any initialization related to a reader in order to enable contactless cards detection. Call this primitive from the payment application.

gpiInitializeHSM (***)

HSM

N/A

Set KEY, REVOCATED, and EXCEPTION files references. This primitives shall be called once before system’s operation cycle so it can managed EMV certificate.s, and black list. These features have been developed to comply to L2 test procedures but may be adapted to a specific L3 context

gpiGetTerminalIdentification

Platform

dev_get_identification

Map to EMVCo’s 9F1C.

gpiGetSerialNumber

CAD

dev_get_serial_number

Map to EMVCo’s 9F1E.

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

Card Interfaces

gpiSetTechnoToDetect

CAD

dev_get_polling_technologies

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

It calculates the list of technologies to poll on. by setting CADCtx.mTechnoToDetect accordingly.

dev_get_polling_technologies shall return all supported technologies.

This call shall be perform prior to gpiPolling and gpiTechnoPolling.

gpiSetTechnoToDetect(TECHNO_MAGSTRIPE | TECHNO_CONTACT); // Techno to poll on

gpiPolling

CAD

Initiate a gpiTechnoPolling for given timeout in seconds.

gpiError are in:

• clcEMV_CARD

• clcNO_ERROR

• clc_COLLISION

• polTIMEOUT

• scrINTERRUPTED

• scrCARD_INSERTED

• msrCARD_SWIPED

• clcOTHER_CARd

• scrSYSTEM_ERROR

This call may be perfomed from outside AgnosEP. If a subsequent call to enpExecutePaymentTransaction is required, the payment application shall avoid a double tap. Call enpSkipPollingOnNextStartB.

gpiTechnoPolling

CAD

Perform a polling on technologies previously set.

gpiError are in:

• clcEMV_CARD

• scrCARD_INSERTED

• msrCARD_SWIPED

• keyNO_ERROR

• clcOTHER_CARD

gpiPowerOn

CAD

gpiGetPolledType

CAD

gpiExchangeAPDU

CAD

Send / Receive an APDU Command / Response

gpiGetLastExchangedAPDU

CAD

N/A

Provide last APDU command/response

gpiRemovalProcedure

CAD

As per EMVCo standard

gpiCardSwiped

CAD

If a card is swiped, return msrCARD_SWIPED

gpiCardInserted

CAD

If a card is inserted, retunr scrCARD_INSERTED

gpiGetCardStatus

CAD

gpiReadMagstripe

CAD

Provide all card’s tracks after a swipe

gpiPowerOff

CAD

dev_pcd_set_field

dev_ifd_power

Power off the interface corresponding to the transaction in progress and set internal GPI/CAD status to false

gpiPowerOffAllDevices

CAD

dev_ifd_power_off

dev_pcd_set_field

dev_msr_reset

Switch off all interfaces and set all internal GPI/CAD transaction status to false

gpiResetContactless

CAD

gpiSetContactlessTransactionInProgress

CAD

N/A

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

gpiSetContactTransactionInProgress

CAD

N/A

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

gpiSetSwipeTransactionInProgress

CAD

N/A

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

IsSetContactlessTransactionInProgress

CAD

N/A

--

IsSetContactTransactionInProgress

CAD

N/A

--

IsSwipeTransactionInProgress

CAD

N/A

--

List Management

PINPAD Management

gpiPINEnter

SPED

gpiPINVerifyPlaintext

SPED

gpiPINVerifyCiphered

SPED

Log

gpiInitializeLogger

Platform

gpiReleaseLogger

Platform

gpiLog

Platform

Profiling

Profiling may be used for differential timing analysis. Absolute measurement is difficult because logging (or time stamping) takes CPU time. However, this mechanism allows to measure:

• The time spent between the beginning of the polling and an EMV card detection

• The time spent between an APDU command and an APDU response (L1 processing window)

• The time spent between an APDU response and an APDU command (L2 processing window)

However, time stampng is performed in RAM (generic implementation. see log.c) if available RAM allows it

gpiGetTimeStamp (***)

Platform

N/A

Profile CAD/gpiExchangeAPDU is the only GPI service thart is profiled. Each APDU command/reponse time is measyred in order to discriminate the time spent in L1 and L2

Overload this primitive directly in GPI/Platform to log whereever it is possible (generic implementation logs in RAM)

Generic implementation uses clock_gettime (see log.c). Replace this function with appropriate primitive available on the platform

gpiSwithOnTimeStamp

Platform

N/A

Activate time stamp

gpiSwithOffTimeStamp

Platform

N/A

Deactivate time stamp

gpiDumpTimeStamp (***)

Platform

N/A

Dump time stamps whereever possible