Table of Contents |
---|
...
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. |
...
Primitives | ModuleInitialization | Device Mapping | Comment | 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:
As soon as DEVICE realizes this services, the GPI will dynamically manage the current line / column that is(are) used. | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Primitives | Platform | dev_main | May be used to initialize any parameters inside HAL. Use this call at the start-up of the system.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. |
...
Primitives | Module | Device MappingComments | ||||||
---|---|---|---|---|---|---|---|---|
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:
| ||||||||
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:
| ||||||
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:
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:
DRL files:
UPDATE CONDITIONS files:
KEY files:
REVOCATED Files:
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 | Card Interfaces|||||
---|---|---|---|---|---|---|---|---|
gpiSetTechnoToDetect | CAD | dev_get_polling_technologies | Set the type of technologies to be detected during a polling. Technologies to detect are in:
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.
| |||||
gpiPolling | CAD | Initiate a gpiTechnoPolling for given timeout in seconds. gpiError are in:
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:
| ||||||
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
Primitives | Module | Device Mapping | Comment
---|
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 | PINPAD Management|
---|---|---|---|---|
gpiPINEnter | SPED | |||
gpiPINVerifyPlaintext | SPED | |||
gpiPINVerifyCiphered | SPED |
Log and Profiling |
...
Primitives | Module | Device Mapping | Comment||||
---|---|---|---|---|---|---|
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:
| |||
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:
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 |