API _Version _Revision | Description |
---|---|
_OLA _version 2.1.6 _revision 23819 | Open L2 API interface is an abstraction of the card processing (alias L2), for EMV contact and EMV contactless system. It is based on a simple set of primitives to ease L2 integration onto a payment application (alias L3). That set of primitives supports Nexo Fast’s structures and dynamics. What is not covered by OLA interface is:
|
ola | ||
---|---|---|
See ola.h | ||
| #include "ola_tags_dictionary.h" #include "ola_emv.h" /// Generic EMV API #include "ola_publickey.h" /// Generic Public Key configuration API #include "ola_contactless.h" /// Generic Contacless Processing API #include "ola_contact.h" /// Generic Contact Processing API | -- |
| #define OLA_API_VERSION "2.1.6" | Current OLA version. |
| typedef void (*logf_function)(char* str); | Callback definition used by L2 stack to trace its execution. That logging function is defined above OLA API (for example, by the L3) and called from OLA implementation or below. |
| const char *ola_get_api_version(void); | Gets OLA Interface version. |
| const char *ola_get_implementation_version(void); | Get OLA Implementation version. Whereas OLA Interface is independant for any L2, its implementation depends on underlying SDK. For example, if using Agnos Framework, possible implementations could be AGF 3.5.x, or AGF 3.3.x. Today, other available implementations are on AMP, Castles, and PAX terminals. |
| tOLAError ola_initialize_at_start_up(uint8_t *tlv, uint16_t tlvLength); | Set specific internal states related to a given OLA implementation. For example, if using Agnos Framework, the TLV is a serialization of the following structure: typedef struct { /** Path to all configuration files (must end with '/') */ uint8_t path[MAX_PATH_LENGTH]; // DF01 /** CAKeys full path file name - */ uint8_t cakeys[MAX_PATH_LENGTH]; // DF02 /** CRL full path file name */ uint8_t crl[MAX_PATH_LENGTH]; // DF03 /** EFL full path file name */ uint8_t efl[MAX_PATH_LENGTH]; // DF04 /** PCSC readers full path file name (.ini) */ uint8_t pcsc[MAX_PATH_LENGTH]; // DF05 /** Languages full path file name (.ini) */ uint8_t lang[MAX_PATH_LENGTH]; // DF06 /** * Runtime parameters * * Byte 1 - DEFAULT TXN TYPE (tag 9C) * Byte 2 - LEGACY SELECTION BITMAP * | bit 8 7 6 5 4 3 2 1 * | x Legacy ZIP * | x Legacy PayPass * | x Legacy Amex * | x Legacy JCB * | x Legacy CUP * | x Legacy DPAS * | x Legacy Visa * | - RFU * Byte 3 - STACK PARAMETER BITMAP 1/2 * | bit 8 7 6 5 4 3 2 1 * | x Contactless - AlwaysReceipt * | x Agnos - CL * | x Contactless - TransactionLooping * | x Contactless - KeyIn * | x Contactless - Signal * | x Callback - DE * | x Agnos - APDULog * | x Agnos - UIDisplay * Byte 4 - STACK PARAMETER BITMAP 2/2 * | bit 8 7 6 5 4 3 2 1 * | x Agnos - Replay * | x Agnos - IDMessageDisplay * | x Agnos - TagDump * | x Contactless - DigitalSignal * | - RFU * | - RFU * | - RFU * | - RFU * Byte 5 - POLLING TIMEOUT (s) * Byte 6 - TRACE DEPTH (0 to 6) * Byte 7 - DEFAULT LANGUAGE */ uint8_t params[RUNTIME_PARAM_LENGTH]; // DF07 /** Trace level */ uint8_t trace_level; // DF08 } tAgnosIni; |
| void ola_set_trace_function(logf_function fct); | Set logging callback. |
ola_emv | ||
---|---|---|
See ola_emv.h | ||
| #include <stdint.h> | |
| typedef enum { OLA_OK, OLA_CARD_MUTE, OLA_CARD_BLOCKED, OLA_MAX_REACHED, OLA_NO_CANDIDATE, OLA_CONTACT_NEW_SELECTION, OLA_CONTACT_SELECTION_ERROR, OLA_CONDITIONS_NOT_SATISFIED, OLA_ACCEPTED, OLA_NOT_ACCEPTED, OLA_OFFLINE_ACCEPTED, OLA_OFFLINE_DECLINED, OLA_GO_ONLINE, OLA_DECLINED, OLA_MISSING_DATA, OLA_PINPAD_ERROR, OLA_PARAM_ERROR, OLA_NOT_IMPLEMENTED, OLA_ERROR, OLA_CARD_ERROR, OLA_CANCEL, OLA_PUBLIC_KEY_OK, OLA_PUBLIC_KEY_MISSING, OLA_PUBLIC_KEY_MAX_REACHED, OLA_PUBLIC_KEY_END, OLA_PUBLIC_KEY_ERROR, OLA_CARD_REMOVED } tOLAError; | |
| typedef enum { cvmNone, cvmNoCvm, cvmSignature, cvmOnlinePin, cvmOnlinePin_Signature, cvmOfflinePinPlaintext, cvmOfflinePinPlaintext_Signature, cvmOfflinePinCiphered, cvmOfflinePinCiphered_Signature } tOlaEMVCoCVM; | |
| tOLAError ola_emv_set_tag( uint32_t tag, uint8_t *value, uint16_t length ); | |
| tOLAError ola_emv_get_tag( uint32_t tag, uint8_t *value, uint16_t *length ); | |
| tOLAError ola_emv_get_cvm_results( tOlaEMVCoCVM *cvm ); |
ola_contact | ||
---|---|---|
See ola_contact.h | ||
| #include "ola_emv.h" #include <stdint.h> | |
| typedef enum { metUndef = 0, metFull, metExtractPAN, metUnknown } tOlaModeContactTransaction; | |
| void ola_contact_flush_aid_supported(void); | |
| tOLAError ola_contact_answer_to_reset(const char* reader); | |
| tOLAError ola_contact_add_aid_supported( const uint8_t *aid, uint8_t aidLength, int partial ); | |
| tOLAError ola_contact_build_candidate_list( uint8_t *nb_candidates, int *pse ); | |
| tOLAError ola_contact_get_tag_from_candidate( uint8_t candidate, uint32_t tag, uint8_t *value, uint16_t *length ); | |
| tOLAError ola_contact_final_select_candidate(uint8_t candidate); | |
| tOLAError ola_contact_initiate_transaction( tOlaModeContactTransaction mode ); | |
| tOLAError ola_contact_complete_transaction( const uint8_t *authorResponseCode, const uint8_t *issuerAuthenticationData, uint8_t issuerAuthenticationData_length ); | |
| void ola_contact_clean(void); |
ola_contactless | ||
---|---|---|
See ola_contactless.h | ||
| #include "ola_emv.h" #include <stdint.h> | |
| #define OLA_KERNEL_ID_MASTERCARD 2 #define OLA_KERNEL_ID_VISA 3 #define OLA_KERNEL_ID_AMEX 4 #define OLA_KERNEL_ID_JCB 5 #define OLA_KERNEL_ID_DISCOVER 6 #define OLA_KERNEL_ID_CUP 7 #define OLA_MSD_ID_APPROVED 0x03 #define OLA_MSD_ID_NOT_AUTHORISED 0x07 #define OLA_MSD_ID_PLEASE_INSERT_OR_SWIPE_CARD 0x18 #define OLA_MSD_ID_AUTHORISING_PLEASE_WAIT 0x1B #define OLA_MSD_ID_INSERT_SWIPE_OR_TRY_ANOTHER_CARD 0x1C #define OLA_MSD_ID_SEE_PHONE_FOR_INSTRUCTIONS 0x20 | |
| typedef enum { ctsNone, ctsPreprocess, ctsBuildCandidate, ctsFinalSelect, ctsActivate } tOlaContactlessTransactionStep; | |
| typedef enum { outcNone, outcSelectNext, outcTryAgain, outcApproved, outcDeclined, outcOnlineRequest, outcTryAnotherInterface, outcEndApplication } tOlaOutcome; | |
| typedef enum { spNoStart, spStartA, spStartB, spStartC, spStartD, } tOlaStartPoint; | |
| typedef enum { ordNone, ordEmv, ordAny } tOlaOnlineResponseData; | |
| typedef enum { aipNone, aipContactChip, aipMagneticStripe } tOlaAlternateInterfacePreference; | |
| typedef enum { cvmclNone, cvmclNoCvm, cvmclSignature, cvmclOnlinePin, cvmclConfirmationCodeVerified } tOlaCVMethodContactless; | |
| typedef enum { staNone, staNotReady, staIdle, staReadyToRead, staProcessing, staCardReadSuccessfully, staProcessingError } tOlaStatus; | |
| typedef enum { vqNone, vqAmount, vqBalance } tOlaValueQualifier; | |
| typedef struct { tOlaOutcome outCome; tOlaStartPoint startingPoint; tOlaOnlineResponseData onlineResponseData; tOlaCVMethodContactless cvm; int UIReqOnOutcomePresent; int UIReqOnRestartPresent; int receipt; int dataRecordPresent; int discretionaryDataPresent; tOlaAlternateInterfacePreference alternateInterfacePreference; uint32_t fieldOffReq; uint32_t removalTimeout; } tOlaOutcomeParameter; | |
| typedef struct { uint8_t messageIdentifier; tOlaStatus status; uint32_t holdTime; uint8_t languagePreference[8]; // List of languages, ISO 639-1 representation tOlaValueQualifier valueQualifier; uint8_t value[6]; // BCD uint8_t currencyCode[2]; // Numeric ISO 4217 } tOlaUIRequest; | |
| void ola_contactless_flush_aid_supported(void); | |
| tOLAError ola_contactless_add_aid_supported( const uint8_t *aid, uint8_t aidLength, int partial, uint8_t kernelId, uint8_t *tlv, uint16_t tlvLength ); | |
| uint16_t ola_contactless_add_drl_supported( const uint8_t *programId, uint8_t programIdLength, const uint8_t *transactionLimit, const uint8_t *floorLimit, const uint8_t *CVMLimit, int statusCheck, int isZeroAllowed, uint8_t kernelId ); | |
| void ola_contactless_commit_supported_aids(void); | |
| uint16_t ola_contactless_build_candidate_list( uint8_t *nb_candidates ); | |
| uint16_t ola_contactless_get_tag_from_candidate( uint8_t candidate, uint32_t tag, uint8_t *value, uint16_t *length ); | |
| tOLAError ola_contactless_final_select_candidate( uint8_t candidate, uint8_t *kernelId ); | |
| tOLAError ola_contactless_get_card_preferred_language( char *language ); | |
| tOLAError ola_contactless_preprocess(void); | |
| tOLAError ola_contactless_do_transaction(void); | |
| void ola_contactless_clean(void); | |
| tOLAError ola_contactless_get_outcome( tOlaOutcomeParameter *outcome ); | |
| tOLAError ola_contactless_get_UI_request_upon_outcome( tOlaUIRequest *uiRequest ); | |
| tOLAError ola_contactless_get_UI_request_restart( tOlaUIRequest *uiRequest ); |
ola_publickey | ||
---|---|---|
See ola_publickey.h | ||
| #include "ola.h" #include <stdint.h> | |
| typedef struct { uint8_t rid[5]; uint8_t idx[1]; uint8_t modulusLen; uint8_t modulusValue[248]; uint8_t exponentLen; uint8_t exponentValue[3]; uint8_t expirDate[3]; } tOlaPubKey; | |
| void ola_pubkey_flush(void); | |
| tOLAError ola_pubkey_add( const tOlaPubKey *key, const uint8_t *checksum ); | |
| tOLAError ola_pubkey_find( tOlaPubKey *key, uint8_t *checksum ); | |
| tOLAError ola_pubkey_get_next_id( uint8_t *idx, uint8_t *rid, int start ); | |
| tOLAError ola_pubkey_commit(void); |
ola_terminal | ||
---|---|---|
See ola_terminal.h | ||
| N/A | This module is not available from OLA 2.x version |
ola_tags_dictionary | ||
---|---|---|
See ola_tags_dictionary.h | ||
| #define TAG_TAC_DEFAULT 0xDF1E #define TAG_TAC_DENIAL 0xDF1F #define TAG_TAC_ONLINE 0xDF20 #define TAG_READER_CONTACTLESS_FLOOR_LIMIT_PREPROCESSING 0xDF09 #define TAG_READER_CONTACTLESS_FLOOR_LIMIT 0xDF8123 // Be careful, tag managed as 9F1B by Nexo! #define TAG_READER_CONTACTLESS_TRANSACTION_LIMIT_NO_DEVICE_CVM_PREPROCESSING 0xDF08 #define TAG_READER_CONTACTLESS_TRANSACTION_LIMIT_NO_DEVICE_CVM 0xDF8124 #define TAG_READER_CONTACTLESS_CVM_REQUIRED_LIMIT_PREPROCESSING 0xDF0B #define TAG_READER_CONTACTLESS_CVM_REQUIRED_LIMIT 0xDF8126 #define TAG_THRESHOLD_VALUE_FOR_BIASED_RANDOM_SELECTION 0xDF21 #define TAG_MAXIMUM_TARGET_PERCENTAGE_FOR_BIASED_RANDOM_SELECTION 0xDF1C #define TAG_TARGET_PERCENTAGE_FOR_RANDOM_SELECTION 0xDF1D #define TAG_MESSAGE_HOLD_TIME 0xDF812D // Contact #define TAG_APPLICATION_PROFILE_SETTINGS 0xDF27 #define TAG_DEFAULT_DYNAMIC_DATA_AUTHENTICATION_DATA_OBJECT_LIST 0xDF8F1A #define TAG_DEFAULT_TRANSACTION_CERTIFICATE_DATA_OBJECT_LIST 0xDF8F08 // Kernel 2 #define TAG_BALANCE_READ_AFTER_GEN_AC 0xDF8105 #define TAG_BALANCE_READ_BEFORE_GEN_AC 0xDF8104 #define TAG_CARD_DATA_INPUT_CAPABILITIES 0xDF8117 #define TAG_CVM_CAPABILITY_CVM_REQUIRED 0xDF8118 #define TAG_CVM_CAPABILITY_NO_CVM_REQUIRED 0xDF8119 #define TAG_DEFAULT_UDOL 0xDF811A #define TAG_KERNEL_2_CONFIGURATION 0xDF811B #define TAG_MAX_LIFETIME_TORN_TRANSACTION 0xDF811C #define TAG_MAX_NUMBER_TORN_TRANSACTION 0xDF811D #define TAG_MAGSTRIPE_CVM_CAPABILITY_CVM_REQUIRED 0xDF811E #define TAG_SECURITY_CAPABILITIES 0xDF811F #define TAG_READER_CONTACTLESS_TRANSACTION_LIMIT_DEVICE_CVM 0xDF8125 #define TAG_MAGSTRIPE_CVM_CAPABILITY_NO_CVM_REQUIRED 0xDF812C #define TAG_HOLD_TIME_VALUE 0xDF8130 #define TAG_MIN_RELAY_RESISTANCE_GRACE_PERIOD 0xDF8132 #define TAG_MAX_RELAY_RESISTANCE_GRACE_PERIOD 0xDF8133 #define TAG_RELAY_RESISTANCE_ACCURACY_THRESHOLD 0xDF8136 #define TAG_RELAY_RESISTANCE_TRANSMISSION_TIME_MISMATCH_THRESHOLD 0xDF8137 |
ola_implem | ||
---|---|---|
See ola_implem.h | ||
| #include "ola.h" | |
| typedef struct { void (*flush_aid_supported)(void); tOLAError (*answer_to_reset)(const char* reader); tOLAError (*add_aid_supported)(const uint8_t *aid, uint8_t aidLength, int partial); tOLAError (*build_candidate_list)(uint8_t *nb_candidates, int *pse); tOLAError (*get_tag_from_candidate)(uint8_t candidate, uint32_t tag, uint8_t *value, uint16_t *length); tOLAError (*final_select_candidate)(uint8_t candidate); tOLAError (*initiate_transaction)(tOlaModeContactTransaction mode); tOLAError (*complete_transaction)( const uint8_t *authorResponseCode, const uint8_t *issuerAuthenticationData, uint8_t issuerAuthenticationData_length); void (*clean)(void); } ola_contact_implem_t; | |
| typedef struct { void (*flush_aid_supported)(void); tOLAError (*add_aid_supported)( const uint8_t *aid, uint8_t aidLength, int partial, uint8_t kernelId, const uint8_t *tlv, uint16_t tlvLength); uint16_t (*add_drl_supported)( const uint8_t *programId, uint8_t programIdLength, const uint8_t *transactionLimit, const uint8_t *floorLimit, const uint8_t *CVMLimit, int statusCheck, int isZeroAllowed, uint8_t kernelId); void (*commit_supported_aids)(void); uint16_t (*build_candidate_list)(uint8_t *nb_candidates); uint16_t (*get_tag_from_candidate)(uint8_t candidate, uint32_t tag, uint8_t *value, uint16_t *length); tOLAError (*final_select_candidate)(uint8_t candidate, uint8_t *kernelId); tOLAError (*get_card_preferred_language)(char *language); tOLAError (*preprocess)(void); tOLAError (*do_transaction)(void); void (*clean)(void); tOLAError (*get_outcome)(tOlaOutcomeParameter *outcome); tOLAError (*get_UI_request_upon_outcome)(tOlaUIRequest *uiRequest); tOLAError (*get_UI_request_restart)(tOlaUIRequest *uiRequest); } ola_contactless_implem_t; | |
| typedef struct { tOLAError (*set_tag)(uint32_t tag, uint8_t *value, uint16_t length); tOLAError (*get_tag)(uint32_t tag, uint8_t *value, uint16_t *length); tOLAError (*get_cvm_results)(tOlaEMVCoCVM *cvm); } ola_emv_implem_t; | |
| typedef struct { void (*flush)(void); tOLAError (*add)(const tOlaPubKey *key, const uint8_t *checksum); tOLAError (*find)(tOlaPubKey *key, uint8_t *checksum); tOLAError (*get_next_id)(uint8_t *idx, uint8_t *rid, int start); tOLAError (*commit)(void); } ola_publickey_implem_t; | |
| typedef struct { ola_contact_implem_t contact; ola_contactless_implem_t contactless; ola_emv_implem_t emv; ola_publickey_implem_t publickey; } ola_implem_t; |