Page Comparison

...

Code Block

language	c

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

ola_ contactless.h

Code Block

// NAME.......  ola_contactless.h
// PURPOSE....  Level 2 Abstraction Layer for contactless
//              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_CONTACTLESS_H
#define OLA_CONTACTLESS_H

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

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

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

#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;

// Outcome definition based on EMV Co Books A and B
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
{
	cvmcNone,
	cvmcNoCvm,
	cvmcSignature,
	cvmcOnlinePin,
	cvmcConfirmationCodeVerified
} 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;

// User Interface Request definition based on EMV Co Books A and B
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;

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

// Erase all AID and DRL supported from configuration
void ola_contactless_flush_aid_supported(void);

// Add one AID supported to configuration.
// Must be called before ola_contactless_preprocess()
// Input parameters:
//   aid 		: AID, max 16 bytes
//   aidLength	: length of the AID
//   kernelId   : on one byte, identifies the kernel to be used when selected later (useful for Carte Bancaire)
//   tlv		: 
//   tlvLength  : 
// Return
//   OLA_CONTACTLESS_OK
//   OLA_CONTACTLESS_MAX_REACHED
//   OLA_CONTACTLESS_PARAMETER_ERROR
tOLAError ola_contactless_add_aid_supported(
        const uint8_t *aid,
        uint8_t aidLength,
        int partial,
        uint8_t kernelId,
        const uint8_t *tlv,
        uint16_t tlvLength
);

// Add one DRL (Dynamic Reader Limit) supported to configuration.
// Input parameters:
//   programId		: Program ID, max 16 bytes (one byte for XPressPay)
//   programIdLength	: length of the Program ID
//   transactionLimit : contactless transaction limit, 6 bytes BCD
//                (NULL pointer if there is no value)
//   floorLimit : contactless floor limit,       6 bytes BCD
//                (NULL pointer if there is no value)
//   CVMLimit   : contactless CVM limit,         6 bytes BCD
//                (NULL pointer if there is no value)
//   statusCheck: for PayWave only: allow status check; 0 is false, else is true
//   isZeroAllowed  : for PayWave only: allow zero amount;  0 is false, else is true
//   kernelId   : on one byte, identifies the kernel using the DRL; it can be 3 (PayWave) or 4 (XPressPay)
// Return
//   OLA_CONTACTLESS_OK
//   OLA_CONTACTLESS_MAX_REACHED
//   OLA_CONTACTLESS_PARAMETER_ERROR
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
);

// Commit added AID and DRL supported in configuration
void ola_contactless_commit_supported_aids(void);

// 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
// Return
//   OLA_CONTACTLESS_OK
// 	 OLA_CONTACTLESS_NO_CANDIDATE
//   OLA_CONTACTLESS_CARD_ERROR
uint16_t ola_contactless_build_candidate_list(
        uint8_t *nb_candidates
);

// Get a tag from a candidate in the candidate list
// Must be called after ola_contactless_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_CONTACTLESS_OK
//   OLA_CONTACTLESS_MISSING_DATA: the tag is not present
//   OLA_CONTACTLESS_PARAMETER_ERROR
uint16_t ola_contactless_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 occurrence in candidate list, value must be from 1 to nb_candidates
// Output parameter:
//   kernelId   : the kernel Id that will be activated for this candidate
// Return
//   OLA_CONTACTLESS_OK
//   OLA_CONTACTLESS_PARAMETER_ERROR
//   OLA_CONTACTLESS_BLOCKED
//   OLA_CONTACTLESS_CARD_ERROR
tOLAError ola_contactless_final_select_candidate(
        uint8_t candidate,
        uint8_t *kernelId
);

// Get the preference language for the card holder. It's the first match between the
// card preferred languages list and terminal languages supported, or, when this match
// does not occur, the first occurrence of terminal languages supported
// Output parameter:
//   language		: preference language in ISO 639-1 format (two ASCII character)
// Return
//   OLA_CONTACTLESS_OK
tOLAError ola_contactless_get_card_preferred_language(
        char *language
);

// Perform preprocessing
// Return
//   OLA_EMV_OK : at least on scheme can be used with contactless technology
//   OLA_CONTACTLESS_USE_CONTACT
//   OLA_EMV_PARAMETER_ERROR
tOLAError ola_contactless_preprocess(void);

// Perform the Contactless transaction after the AID is selected and configured
// (First step is building the PDOL and sending the GPO command)
// Output parameter:
//   contactlessEntryMode : EMV_CL_MODE or MAG_CL_MODE
// Return
//   OLA_CONTACTLESS_GO_ONLINE
//   OLA_CONTACTLESS_OFFLINE_APPROVAL
//   OLA_CONTACTLESS_OFFLINE_DENIAL
//   OLA_CONTACTLESS_SEE_PHONE
//   OLA_CONTACTLESS_USE_CONTACT
//   OLA_CONTACTLESS_USE_OTHER_CARD
//   OLA_CONTACTLESS_CONDITIONS_NOT_SATISFIED
//   OLA_CONTACTLESS_NO_RESPONSE
//   OLA_CONTACTLESS_CARD_ERROR
tOLAError ola_contactless_do_transaction(
        uint8_t *contactlessEntryMode
);

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

// Get the outcome from the Contactless transaction context
// Values based on EMV Co Book A Annex B (standards outcomes)
// or as specified elsewhere in Book B (for entry point outcome)
// or in Books C (specifics for different schemes)
// Output parameter:
//   outcome	: outcome parameter structure
// Return
//   OLA_CONTACTLESS_OK
//   OLA_CONTACTLESS_ERROR
tOLAError ola_contactless_get_outcome(
        tOlaOutcomeParameter *outcome
);

// Get the UI request on outcome from the Contactless transaction context
// Output parameter:
//   uiRequest	: UI request parameter structure
// Return
//   OLA_CONTACTLESS_OK
//   OLA_CONTACTLESS_ERROR
tOLAError ola_contactless_get_UI_request_upon_outcome(
        tOlaUIRequest *uiRequest
);

// Get the UI request on restart from the contactless transaction context
// Output parameter:
//   uiRequest	: UI request parameter structure
// Return
//   OLA_CONTACTLESS_OK
//   OLA_CONTACTLESS_ERROR
tOLAError ola_contactless_get_UI_request_restart(
        tOlaUIRequest *uiRequest
);

#endif /* OLA_CONTACTLESS_H */

Versions Compared

Old Version 5

New Version 6

Key

ola_ contactless.h