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