Introduction

OLA stands for Open L2 API. It is a programmable interface normalize card processing (L2) services required by a payment application (L3).

Important: this interface has been desgined from a Nexo Fast perspective. OLA is a global initiative aiming to cover a missing key element in the payment ecosystem: the EMV L2 API. However, OLA is generic enough to support any kind of payment dynamic. beyond Nexo implementation

Principles

Interacting with a L2 stack is based a simple principles:

Set pre-conditions
Initiate transaction
Eventuall, complete transaction
Get post-conditions

There are different interfaces defined to support that sequence.

Hypothesis: a payment application (L3) controls the polling of the technologies, implements a specific region EMV application .selection mechanism (if needed), and owns the configuration (fetched from its TMS). Card processing (L2) is global, and only depends on an ICS that is aligned on merchant’s requirements. Consequently:

A payment application detects whether a contact or contactless application will be triggerred
A payment application implements the logic to select a final application based on OLA services
A payment application configures the EMV parameters based on the final selection

Interfaces

Interface	Description
ola.h	This interface presents different administrative services
ola_emv.h	This interface presents common services required to support contact and contactless card processing
ola_publickey.h	This interface allows a payment application to intialize a L2 stack with a set of public keys required to execute an EMV transaction flow (contact and contactless)
ola_contact.h	This interface is meant to support contact transaction flow
ola_contactless.h	This interface is meant to support contactless transaction flow
ola_tags_dictionary.h	This header lists all the tags that are specific to Nexo Fast and consequently subject to a translation for further indexation in the L2 stack

API

ola.h

#ifndef _OLA_H_
#define _OLA_H_

#ifdef __cplusplus
extern "C" {
#endif

//---------------------------------------------------------
//			Includes
//---------------------------------------------------------

#include "ola_tags_dictionary.h" /// Generic Public Key configuration API
#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

//---------------------------------------------------------
//			Definitions
//---------------------------------------------------------

typedef void (*logf_function)(char* str);

//---------------------------------------------------------
//			Primitives
//---------------------------------------------------------

/// Version of the OLA API
/// No compatiblity guarantees are made between different versions
#define OLA_API_VERSION "2.1.1"

/**
 * @brief Get the current version of the OLA Api
 * @return Pointer to a string representation of the API version
 */
const char *ola_get_api_version(void);

/**
 * @brief Get the current version of the OLA Implementation
 * @return Pointer to a string representation of the API implementation
 */
const char *ola_get_implementation_version(void);

/**
 * @brief Initialize OLA implementation. Need to include xxx_ola_adapter.h to interface to proprietary_data's type
 * @return OLA error
 */
tOLAError ola_initialize_implementation(const uint8_t *tlv, uint16_t tlvLength);

/**
 * @brief Set a trace function
 */
void ola_set_trace_function(logf_function fct);

#ifdef __cplusplus
}
#endif

#endif

ola_emv.h

// NAME.......  ola_emv.h
// PURPOSE....  Level 2 Abstraction Layer for EMV primitives
//              to be used by the external world (Level 3 application)
// PROJECT....  Arkos Payment Solution
// REFERENCES.	--
//
//
// Copyright 2005-2019 - 9164-4187 QUEBEC INC (AMADIS), All Rights Reserved
//

#ifndef OLA_EMV_H
#define OLA_EMV_H

//---------------------------------------------------------
//			Includes
//---------------------------------------------------------

#include <stdint.h>

//---------------------------------------------------------
//			Definitions
//---------------------------------------------------------

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_NOT_IMPLEMENTED,
	OLA_PUBLIC_KEY_ERROR
} tOLAError;

//---------------------------------------------------------
//			Primitives
//---------------------------------------------------------

// Set a tag in L2 stack
// Input parameter:
//   tag
//   value
//   length
// Return
//   OLA_EMV_OK
//   OLA_EMV_PARAM_ERROR
tOLAError ola_emv_set_tag(
	uint32_t tag,
    uint8_t *value,
    uint16_t length
);

// Get a tag from L2 stack
// Input parameter:
//   tag
// Output parameter:
//   value		: buffer to copy the value of the tag
//   length 	: the length of the value
// Return
//   OLA_EMV_OK
//   OLA_EMV_MISSING_DATA: the tag is not present
//   OLA_EMV_PARAM_ERROR
tOLAError ola_emv_get_tag(
	uint32_t tag,
    uint8_t *value,
    uint16_t *length
);

#endif /* OLA_EMV_H */

ola_contact.h

// NAME.......  ola_contact.h
// PURPOSE....  Level 2 Abstraction Layer for EMV contact
//              to be used by the external world (Level 3 application)
// PROJECT....  Arkos Payment Solution
// REFERENCES.	--
//
//
// Copyright 2005-2019 - 9164-4187 QUEBEC INC (AMADIS), All Rights Reserved
//

#ifndef OLA_CONTACT_H
#define OLA_CONTACT_H

//---------------------------------------------------------
//			Includes
//---------------------------------------------------------

#include "ola_emv.h"
#include <stdint.h>

//---------------------------------------------------------
//			Definitions
//---------------------------------------------------------

typedef enum
{
    metUndef = 0,
    metFull,
    metExtractPAN,
    metUnknown
} tOlaModeContactTransaction;

typedef enum
{
    cvmeNone,
    cvmeNoCvm,
    cvmeSignature,
    cvmeOnlinePin,
    cvmeOnlinePin_Signature,
    cvmeOfflinePinPlaintext,
    cvmeOfflinePinPlaintext_Signature,
    cvmeOfflinePinCiphered,
    cvmeOfflinePinCiphered_Signature
} tOlaCvmContact;

// Callback definitions
typedef int (*ola_get_plaintext_pin_fn)(uint8_t *iccRespOut);

typedef int (*ola_get_cipher_pin_fn)(void *rsaPinKeyIn, uint8_t *iccRespOut);

typedef uint16_t (*ola_get_risk_management_info_fn)(uint8_t *lastAmnt, int *cardInExceptionList);

//---------------------------------------------------------
//			Primitives
//---------------------------------------------------------

//////////////////////////////////////
///// Callback setting functions /////
//////////////////////////////////////

// OLA calls this L3 function during CVM step when it is time to get Offline Plaintext PIN
// The Level 3 must use PAX Prolin OS functions to implement PIN capture.
// Output parameters:
//   iccRespOut: last parameter of OsPedVerifyPlainPin() function
// Return
//   the return code of OsPedVerifyPlainPin() function
void ola_contact_set_get_plaintext_pin_callback(
		const ola_get_plaintext_pin_fn callback
);

// OLA calls this L3 function during CVM step when it is time to get Offline Encrypted PIN
// The Level 3 must use PAX Prolin OS functions to implement PIN capture.
// Input parameter:
//   rsaPinKeyIn: structure containing the public key used
// Output parameters:
//   iccRespOut: last parameter of OsPedVerifyCipherPin() function
// Return
//   the return code of OsPedVerifyCipherPin() function
void ola_contact_set_get_cipher_pin_callback(
		const ola_get_cipher_pin_fn callback
);

// OLA calls this L3 function before Terminal Risk Management step
// The Level 3 must use appropriate means to retrieve the sensitive data PAN
// (for comparison in batch and negative list)
// Output parameters:
//	 lastAmnt: tells the amount of the last transaction approved in batch
//             for the PAN and PAN sequence number, 6 bytes in BCD format
//	 cardOnExceptionList: tells if PAN and PAN sequence number have been found
//             in the exception list: 0 is false, else is true
// Return
//   OLA_EMV_OK
//   OLA_EMV_ERROR
void ola_contact_set_get_risk_management_info_callback(
		const ola_get_risk_management_info_fn callback
);

/////////////////////////////
///// Regular functions /////
/////////////////////////////

// Erase all AID supported from configuration
void ola_contact_flush_aid_supported(void);

// Get the ATR from the chip card inserted.
// Return
//   OLA_OK
//   OLA_CARD_MUTE
tOLAError ola_contact_answer_to_reset(const char* reader);

// Add one AID supported to configuration.
// Must be called before ola_emv_build_candidate_list()
// Input parameters:
//   aid 		: AID, max 16 bytes
//   aidLength	: length of the AID
//   partial    : allow partial selection with this AID when building candidate list; 0 is false, else is true
// Return
//   OLA_OK
//   OLA_MAX_REACHED
//   OLA_PARAM_ERROR
tOLAError  ola_contact_add_aid_supported(
		const uint8_t *aid,
	    uint8_t aidLength,
		int partial
);

// Build the candidate list of common AID between the card and the configuration,
// in order of priority.
// Output parameter:
//   nb_candidates 	: tell how many candidates are in the list
//   pse            : tell if pse has been used; 0 is false, 1 is true
// Return
//   OLA_OK
// 	 OLA_NO_CANDIDATE
//   OLA_CARD_REMOVED
tOLAError ola_contact_build_candidate_list(
		uint8_t *nb_candidates,
	    int *pse
);

// Get a tag from a candidate in the candidate list
// Must be called after ola_emv_build_candidate_list()
// Input parameter:
//   candidate 	: an occurrence in candidate list, value must be from 1 to nb_candidates
//   tag
// Output parameter:
//   value		: buffer to copy the value of the tag
//   length 	: the length of the value
// Return
//   OLA_OK
//   OLA_MISSING_DATA: the tag is not present
//   OLA_PARAM_ERROR
tOLAError ola_contact_get_tag_from_candidate(
		uint8_t candidate,
	    uint32_t tag,
		uint8_t *value,
	    uint16_t *length
);

// Send the final select to the card for a candidate in the candidate list
// Input parameter:
//   candidate 	: an occurence in candidate list, value must be from 1 to nb_candidates
// Return
//   OLA_OK
//   OLA_PARAM_ERROR
//   OLA_BLOCKED
//   OLA_CARD_ERROR
tOLAError ola_contact_final_select_candidate(
		uint8_t candidate
);

// Initiate the EMV transaction after the AID is selected and configured
// (First step is building the PDOL and sending the GPO command)
// Input parameter:
//   mode       : when value is metExtractPAN, ola_emv_init_transaction() will stop after READ RECORDS
//                step (and will end card dialog in sending GENAC with AAC)
// Return
//   OLA_GO_ONLINE
//   OLA_OFFLINE_APPROVAL
//   OLA_OFFLINE_DENIAL
//   OLA_CONDITIONS_NOT_SATISFIED
//   OLA_CARD_REMOVED
//   OLA_CARD_ERROR
tOLAError ola_contact_initiate_transaction(
		tOlaModeContactTransaction mode
);

// Complete EMV transaction after going online (or trying and being unable).
// If there is any EMV script from the issuer, ola_emv_set_tag() with tag 71 or 72
// must be used before calling this function.
// Input parameter:
//   authorResponseCode			: two ASCII bytes (as tag 8A)
//							  (NULL pointer when unable to go online)
//   issuerAuthenticationData 	: buffer with the value received (as tag 91)
//                            (NULL pointer if there is no value received)
//   issuerAuthenticationData_length		: from 8 to 16
//                            (0 if there is no value received)
// Return
//  OLA_ACCEPTED
//  OLA_DECLINED
//  OLA_NOT_ACCEPTED
//  OLA_ERROR
//	OLA_PARAM_ERROR
tOLAError ola_contact_complete_transaction(
		const uint8_t *authorResponseCode,
	    const uint8_t *issuerAuthenticationData,
	    uint8_t issuerAuthenticationData_length
);

// Release all internal states
void  ola_contact_clean(void);

#endif /* OLA_CONTACT_H */

Amadis

OLA API