Amadis

GPI API

Owned by Olivier Chauvineau (Unlicensed)
Last updated: Mar 29, 2021
7 min read

 

GPI provides a wide set of primitives through the API level called Service Abstraction Level (SAL). This SAL layer encapsulates Agnos' HAL corresponding to the DEVICE layer. Integrating a new platform means overloading DEVICE behavior, i.e. coding into HAL. However, some GPI primitives may be overloaded depending on L3 needs:

  • gpiInitializeHSM (*): overload it to modify file references (not required for L2 TA)

  • gpiEMVGetCertificate (*): overload it to modify public keys look-up (not required for L2 TA)

  • gpiGetEMVCRL (*): overload it to modify revocated certificates look-up (not required for L2 TA)

  • gpiFindPANfromEFL (*): overload it to modify exception file parsing (not required for L2 TA)

 

The purpose of that page is to show the mapping between GPI and DEVICE functions.

 

Compilation Options

All these options are declared in GPI/Platform module, in the file gpi_agnos_framework_globals.h.

Options

Comments

_ADAPTER_

RFU

_AGNOSCL_

Enable code related to contacless card processing

_AGNOSCPL_

Enable code related to EMV transaction completion

_AGNOSFMSG_

Enable code related to financial messages management

_AGNOSISR_

Enable code related to issuer script update

_AGNOSK_

Enable code related to EMVCo contact card processing

_AGNOSTRACE_

Enable code to log, and timestamp events

_AUTOMATION_

Enable code to use Atmos (test automation). It is related to RAW file format management and to API service provided by ACE and AtmosStubee. This option is reserved for Amadis development teams

DATA_EXCHANGE_

Enable code related to data exchange (contactless only)

_DUAL_POLLING_

Enable code related to polling on dual technologies. Else, contact only

 

Initialization

All these primitives shall be subject to unit tests before any functional runs. This set of primitives must be integrated in priority. Please refer to file headers to get most up to date primitives signatures.

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.

Primitives

Module

Device Mapping

Comment

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.

 

Core

All these primitives shall be subject to unit tests before any functional runs. This set of primitives must be integrated in priority. Please refer to file headers to get most up to date primitives signatures.

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

 

Primitives

Module

Device Mapping

Comments

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

 

Primitives

Module

Device Mapping

Comments

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.

 

Primitives

Module

Device Mapping

Comments

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

 

Primitives

Module

Device Mapping

Comments

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”

Primitives

Module

Device Mapping

Comments

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 Processing

 

Card Interfaces

 

Primitives

Module

Device Mapping

Comment

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

GPI proposes a mechanism to manage list displays, scrolling, and selection

Primitives

Module

Device Mapping

Comment

 

 

 

 

String Table

 

 

 

GPI proposes a mechanism to map string identifier and language code to actual strings

Primitives

Module

Device Mapping

Comment

 

 

 

 

PINPAD Management

 

Primitives

Module

Device Mapping

Comment

gpiPINEnter

SPED

 

 

gpiPINVerifyPlaintext

SPED

 

 

gpiPINVerifyCiphered

SPED

 

 

Log and Profiling

 

Log

 

GPI proposes a logging mechanism that suits to profiling. It is important to enable _AGNOSTRACE_ at compilation time to get this feature (for qualification and TA only)

Primitives

Module

Device Mapping

Comment

gpiInitializeLogger

Platform

N/A

Open logging whereever it takes place:

  • logger: outstream used to log any events

  • logBuffer: static buffer to log into

  • level: log level

    • 0: mute all logs

    • 1: log only gpi

    • 2: log only Agnos EMV engine

    • 3: log only AgnosMW and payment event

    • 4: log only errors from any level in 1, 2, 3

    • 5: log all

    • 6: log APDU offline

    • 7: time stamp

  • timeStamp: static buffer to timestamp into

  • maxLengthTimeStamp: timeStamp's size

  • apduLogger: outstream used to log APDU

  • differedAPDUResp: flag to indicate that APDU response are logged asynchroneously (Mastercard TA)

gpiReleaseLogger

Platform

N/A

Close logging whereever it took place

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

Primitives

Module

Device Mapping

Comment

gpiGetTimeStamp

Platform

N/A

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

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