Amadis

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

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.

Core

All these primitives shall be subject to unit tests before any functional runs.

Please refer to file headers to get most up to date primitives signatures.

Primitives

Module

Device Mapping

Comments

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

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

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

Primitives

Module

Device Mapping

Comment

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

dev_get_serial_number

Map to EMVCo’s 9F1E

Card Processing

Primitives

Module

Device Mapping

Comment

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

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

--

PIN Management

Primitives

Module

Comment

PIN Management

gpiPINEnter

SPED

Log and Profiling

Primitives

Module

Comment

Log

gpiLog

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

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

Activate time stamp

gpiSwithOffTimeStamp

Platform

Deactivate time stamp

gpiDuTimeStamp

Platform

Dump time stamps whereever possible

  • No labels