Page Comparison

The following matrix presents for each GPI module all the primitives that may be implemented. The following convention for the integration is:

[O]: Optional. This primitive may be implemented if targeted platform requires it
[C]: Conditional. The primitive may be implemented if system ICS supports corresponding feature
[M]: Mandatory. The primitive must be implemented
[V]: Virtualized service. The primitive may be connected onto Agnos Automation
[K]: SDKable service. The primitive may be connected onto ACE client

Depending on the implementation, some GPI primitives from the list below have to be implemented. Use admNOT_IMPLEMENTED GPI error for those that are not supported.

Implementation

Primitive

Integration

Comments

Platform

gpi.c

gpiCleanUp

[O]

Implement this primitive to perform platform specific house keeping actions.
Any kind of cleanup operations may be performed at this time (depending on Level3 and platform’s design)

platform.c

gpiCloseLibrary

[O]

Implement this primitive to manage payment applications dynamic loading.
This primitive allows supporting dynamic library loading (.so or .dll)

log.c

gpiDumpTimeStamp

[O]

Implement this primitive to support time stamping.
No porting required. If supported, this primitive may be used as is

platform.c

gpiFileClose

[M]

Implement this primitive to close a file or to emulate file closing (if no file system).
This primitive allows closing a file corresponding to an ifp

platform.c

gpiFileDelete

[M]

Implement this primitive to delete a file or to emulate file deleting (if no file system).
This primitive allows deleting a file from its name. Important: if no file system, don’t forget to manage seek cursor at each delete operation

platform.c

gpiFileGetSize

[M]

Implement this primitive to size a file or to emulate file sizing (if no file system).
This primitive allows a calling component to know whether or not a file exists or has been previously initialized

platform.c

gpiFileOpen

[M]

Implement this primitive to open a file or to emulate file opening (if no file system).
The concept of file is used to store TERMINAL, PROCESSING, ENTRY_POINT, CAKeys, CRL, EFL related data. Depending on the platform, this primitive is used to open a file or a corresponding flash memory space. In any case, opening a file provides a handler to calling component to support subsequent read/write/close operations. If no file system, filename shall be used to tag flash memory area corresponding to each file type (TERMINAL, PROCESSING, etc…)

platform.c

gpiFileRead

[M]

Implement this primitive to read a file or to emulate file reading (if no file system).
This primitive allows reading a file corresponding to an ifp. If no file system, don’t forget to manage seek cursor at each read operation

platform.c

gpiFileRename

[O]

RFU

platform.c

gpiFileWrite

[M]

Implement this primitive to write a file or to emulate file writing (if no file system).
This primitive allows writing a file corresponding to an ifp. If no file system, don’t forget to manage seek cursor at each write operation and the actual size

rtc.c

gpiFreeTimer

[C]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

sharedram.c

gpiGetDataObjectRAM

[C]

Implement this primitive if CL card processing configurations are supported.
This primitive allows data manager to fetch RAM to store CL combinations

rtc.c

gpiGetDate

[M]

Implement this primitive to get platform’s date.
A proper date management is crucial to perform payment transaction because it is used during different stages like ODA, TRM, torn management, etc… Be careful with the format: use toNumeric primitive from gpiutils.h to convert date from binary to numeric format (i.e. to convert 0x0C to 0x12). If not implemented, date can be fetched from Sales System at payment trigger time

sharedram.c

gpiGetFreeRAM

[O]

Implement this primitive to return applicative RAM used during EMV transactions to store any proprietary data.
This primitive provides an address to be used before, during, or after a transaction. This memory chunk is transient and may be used across all the Level3 and GPI

gpi.c

gpiGetInterfaceVersionNumber

[M]

Implement this primitive to get GPI version.
This primitive is delivered with the current GPI version provided along with the product license. No porting required. It may be overloaded or modified for specific purpose. Note that the current version may be used as reference for TA certification versioning

rtc.c

gpiGetLastAllocated

[C]

Implement this primitive if C-2/Mastercard is supported.
No porting required. If supported, this primitive may be used as is

platform.c

gpiGetLibraryFunction

[O]

Implement this primitive to manage payment applications dynamic loading.
This primitive allows supporting dynamic library loading.(.so or .dll)

rtc.c

gpiGetMaxTimer

[C]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

sharedram.c

gpiGetPrivateScratchPAD

[C]

Implement this primitive to manage private RAM allocation if C-2/Mastercard, C-5/JCB, or C-7/CUP is supported.
This primitive must be implemented even if private RAM is designed to support payment application processing. Typically, a private scratch pad is used to store torn transaction. Set *ram to NULL (if torn not supported) or provide RAM address and size to calling module. The slot indicates who calls (see AgnosDB and agnosdatabase.h for slot definitions)

sharedram.c

gpiGetRAMForTags

[M]

Implement this primitive to return applicative RAM used during EMV transactions to store card/terminal EMV tags.
This primitive provides EMV tags’ starting address to be used during a transaction. This address is reserved to Agnos kernels

sharedram.c

gpiGetRAMForUnknownTags

[M]

Implement this primitive to return applicative RAM used during EMV transactions to store card/terminal unknown tags.
This primitive provides unknown EMV tags’ starting address to be used during a transaction. This address is reserved to Agnos kernels

platform.c

gpiGetTerminalIdentification

[C]

Implement this primitive to manage terminal’s identifier (contact only).
This primitive allows initializing tag 9F1C

rtc.c

gpiGetTime

[M]

Implement this primitive to get platform’s time.
A proper time management is crucial to perform payment transaction because it is used during different stages like card polling, torn management, etc… Be careful with the format: use toNumeric primitive from gpiutils.h to convert time from binary to numeric format (i.e. 0x17 to 0x23). If not implemented, time can be fetched from Sales System at trigger time (if a timeout management is required on the device (CL polling, key entry, card insertion, etc…), an internal timer shall be used if no RTC available)

rtc.c

gpiGetTimer

[C]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

rtc.c

gpiGetTimerState

[C]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

log.c

gpiGetTimeStamp

[O]

Implement this primitive to support time stamping.
No porting required. If supported, this primitive may be used as is

rtc.c

gpiGetTimerTime

[C][V]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

sharedram.c

gpiGetTotalRAM

[M]

Implement this primitive to return all the applicative RAM used during EMV transactions.
Since version 3.0, Agnos Framework provides a mutualized RAM mechanism to optimize memory usage. Minimum requirements are:
→ Storage for EMV tags exchanged during a transaction: 11.5 kbytes
→ Storage for unknown tags exchanged during a transaction: 2.5 kbytes
→ Storage for free RAM: depends on platform capabilities

gpi.c

gpiInitialize

[O]

Implement this primitive to initialize platform specific states.
For example, this primitive can be used to perform initialization related to a log file at a specific period of time of the life’s system. Any other kind of initialization may be performed at this time (depending on L3 and platform’s design)

log.c

gpiInitializeLogger

[O]

Implement this primitive to support on device logging.
No porting required. If supported, this primitive may be used as is

log.c

gpiInitializeRemoteLogger

[O]

RFU

log.c

gpilog

[O]

Implement this primitive to support on device logging.
No porting required. If supported, this primitive may be used as is

log.c

gpiLogAddFileLogger

[O]

Implement this primitive to support on device logging.
No porting required. If supported, this primitive may be used as is

log.c

gpiLogAddTCPFileLogger

[O]

RFU

log.c

gpiLogData

[O]

Implement this primitive to support on device logging.
No porting required. If supported, this primitive may be used as is

log.c

gpiLogf

[O]

Implement this primitive to support on device logging.
No porting required. If supported, this primitive may be used as is

log.c

gpiLogSpecific

[O]

Implement this primitive to support on device logging.
No porting required. If supported, this primitive may be used as is

gpi.c

gpiMain

[O]

Implement this primitive to initialize platform specific states.
This primitive allows a calling component to use an argument count and an argument vector like in a regular C/C++ program

platform.c

gpiMemCpy

[M]

Implement this primitive to specialize memcpy.
Default implementation follows C standard

platform.c

gpiMemCmp

[M]

Implement this primitive to specialize memcmp.
Default implementation follows C standard

platform.c

gpiMemSet

[M]

Implement this primitive to specialize memset.
Default implementation follows C standard

platform.c

gpiOpenLibrary

[O]

Implement this primitive to manage payment applications dynamic loading.
This primitive allows supporting dynamic library loading (.so or .dll)

gpi.c

gpiRelease

[O]

Implement this primitive to release platform specific states.
For example, this primitive can be used to perform release related to a log file at a specific period of time of the life’s system. Any other kind of release may be performed at this time (depending level3 and platform’s design)

log.c

gpiReleaseLogger

[O]

Implement this primitive to support on device logging.
No porting required. If supported, this primitive may be used as is

rtc.c

gpiResetTimers

[C]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

rtc.c

gpiRestartTimer

[C]

Implement this primitive if C-2/Mastercard is supported.
No porting required. If supported, this primitive may be used as is

rtc.c

gpiSetDateTime

[O]

Implement this primitive to set platform’s date/time.
This primitives allows to set data and time from an external system. It may become mandatory for CT L2 certification to set device's date/time from ACE (depending on device)

platform.c

gpiSleep

[M]

Implement this primitive to suspend terminal’s operations.
This primitive allows suspending the transaction flow when a message is displayed on the screen or when it is required by a specification like PayPass. It is widely used in the framework to pace card processing UI related steps

rtc.c

gpiStartTimer

[C]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

platform.c

gpiStrCpy

[M]

Implement this primitive to specialize strcpy.
Default implementation follows C standard

platform.c

gpiStrCmp

[M]

Implement this primitive to specialize strcmp.
Default implementation follows C standard

platform.c

gpiStrLen

[M]

Implement this primitive to specialize strlen.
Default implementation follows C standard

platform.c

gpiStrNCpy

[M]

Implement this primitive to specialize strncpy.
Default implementation follows C standard

rtc.c

gpiStopTimer

[C]

Implement this primitive if C-2/Mastercard is supported.
This primitive is used for DS/DE and RRP processing

log.c

gpiSwitchOffTimeStamp

[O]

Implement this primitive to support time stamping.
No porting required. If supported, this primitive may be used as is

log.c

gpiSwitchOnTimeStamp

[O]

Implement this primitive to support time stamping.
No porting required. If supported, this primitive may be used as is

utils.c

bcdToDecimal

[M]

No porting required. This primitive shall be used as is

utils.c

hexToNumeric

[M]

No porting required. This primitive shall be used as is

utils.c

toBinary

[M]

No porting required. This primitive shall be used as is

utils.c

toByte

[M]

No porting required. This primitive shall be used as is

utils.c

toNumeric

[M]

No porting required. This primitive shall be used as is

utils.c

toWord

[M]

No porting required. This primitive shall be used as is

CAD

cad.c

gpiCardInserted

[C]

Implement this primitive if dual interface (CT and CL) is supported.
This primitive allows to know if a contact card was inserted during a contactless transaction. It may be used for other purposes to support contact processing

mag.c

gpiCardSwiped

[C]

Implement this primitive if magstripe interface is supported.
This primitive allows to know if a card was swiped

cad.c

gpiExchangeAPDU

[M][V]

Implement this primitive to support APDU exchanges in contact and contactless modes.
This primitive allows data exchange with CT and CL cards. If CL/AMEX 3.0 is supported be careful to keep the following provided in the example:

Code Block

if(gContactlessTransactionInProgress) {
// get ptc is filtered in contactless because offline plain text is not supported
if((CLA==0x80) && (INS==0xCA) && (P1==0x9F) && (P2==0x17)) return scrINTERRUPTED;
}

If level1 supports two different APDU exchange services for CT and CL technologies then use a GPI internal state at the gpiPolling time because Agnos doesn't discriminate CT vs CL APDU exchanges

cad.c

gpiGetCardStatus

[C]

Implement this primitive if CT and magstripe interfaces are supported.
This primitive allows to know if a card is mute in order to go to a fallback to magstripe

mag.c

gpiGetLastErrorStatus

[O]

RFU

cad.c

gpiGetLastExchangedAPDU

[C]

Implement this primitive if C-2/Mastercard, C-5/JCB, C-6/D-PAS, or PURE is supported.
This primitives allows to fetch last APDU exchange from a Level2 processing. No porting required. This primitive shall be used as is

cad.c

gpiGetSerialNumber

[M]

Implement this primitive to manage terminal’s serial number (contact and contactless).
This primitive allows initializing tag 9F1E

cad.c

gpiInitPolling

[O]

Implement this primitive if contactless is supported.
This primitive allows a specific antenna initialization if required

cad.c

gpiPolling

[C]

Implement this primitive if contactless is supported.
This primitive is used by Agnos Framework to detect a CL card. It may be used by Level3 in the scope of transportation projects to avoid double tap

cad.c

gpiPowerOff

[M]

Implement this primitive to switch off a card interface.
This primitive is used in CT and CL modes

cad.c

gpiPowerOffAllDevices

[O]

Implement this primitive to switch off all card interfaces at the same time.
This primitive allows full power off of all coupling hardware

cad.c

gpiPowerOn

[C]

Implement this primitive to switch on a CT card interface.
This primitive is used in CT mode only

mag.c

gpiReadMagstripe

[C]

Implement this primitive if magstripe is supported.
This primitive allows to read up to 3 tracks

cad.c

gpiRemovalProcedure

[C]

Implement this primitive if NFC is supported.
This primitive is mandatory to implement card removal procedure. However, depending on the project type, it may not be deployed to prevent late acceptance system disposition (transportation gates). See Antenna Management section

cad.c

gpiResetContactless

[C]

Implement this primitive if NFC is supported.
This primitive allows the entry point the reset the antenna

cad.c

gpiSetContactlessTransactionInProgress

[C]

Implement this primitive to avoid double tap if payment CL cards processing is supported along with non payment CL cards.
This primitive is used to prevent AgnosEP to initiate a gpiPolling when triggering a transaction. It may be used in specific contexts such as transportation, loyalty programs management. No porting required. This primitive shall be used as is

cad.c

gpiSetTechnoToDetect

[C]

Implement this primitive if NFC is supported along with another technology.
This primitive sets the technologies to be detected during a subsequent polling (fallback from CL to CT or magstripe)

cad.c

gpiTechnoPolling

[C]

Implement this primitive if contact is supported.
This primitive polls on contact and/or magstripe. It is also used to detected that a card has been removed. It is not required on a pure contactless system because gpiPolling supports that feature (note that gpiTechnoPolling could also be used like a private primitive called by gpiPolling)

HSM

sred.c

gpiCLIPCheckPANInCertificate

[O]

Implement this primitive if CLIPPING is supported

cacertificates.c

gpiFindPANFromEFL

[C]

Implement this primitive if exception file list is supported.
This primitive allows to fetch a PAN (along with a PSN) from a black list

cacertificates.c

gpiGetEMVCertificate

[C]

Implement this primitive if ODA is supported.
This primitive is used to fetch the CA Public Key based on a RID and an index. This primitive is called from L2’s ODA module.See code example and CAKeys to learn CAKeys file structure

cacertificates.c

gpiGetEMVCRL

[C]

Implement this primitive if ODA is supported.
This primitive is used to detect revocated CA Public Key based on a RID, an index, and a serial number. This primitive is called from L2’s ODA module. See GPI code example and CRL to learn CRL file structure

checksum.c

gpiGetChecksum

[M]

This primitive alllows Level2 to fecth a unique identifier for versionning control during TA.
Level2 identification method is up to integrator

rand.c

gpiGetRandomNumber

[M]

This primitive is provided by GPI/HSM in standard. It might be wired to a hardware service.
Important: randomness may be tested during Level2 TA

hsm.c

gpiInitializeHSM

[C]

Implement this primitive if ODA is supported.
This primitive is used to initialize file names storing CA public keys (CertificateFilesName), and revocated CA Public Keys (CertificatesRevocationListFilesName). If there is no file system supported, it may not be implemented. In most of the cases, ExceptionFileName is out of the scope of kernels certifications: excepted for Discover because this feature is mandatory

rsa.c

gpiRSAcomputation

[C]

This primitive is provided by GPI/HSM in standard. It might be wired to a hardware service if a crypto processor if available.
Important: software RSA computation costs around 13ms. Some CL specifications may integrate public key chain verification within the performance time frames measurement. Hence, wiring the RSA might become mandatory depending on the device and crypto-processor

sred.c

gpiSECUREDPANMatched

[O]