Amadis

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

gpiCLIPCheckPANInCertificate

Description

Check actual PAN (tag 5A) with the one provided within the certificate. This function is called during ICC public key (ODA/contact and contactless) and ICC PIN public key (CVM/contact) verifications.

gpiCLIP* group of functions relies on a platform's secured module filtering sensible EMV data (i.e. tag 56, tag 57, and tag 5A) from APDU exchanges. This secured module parses R-APDU during read record sequence so that this set of data is not compromised at application level. Example:

  • CLIP(45191234567812) = 45190000000012

Consequently, L2 processing requires specific primitives to support specific control. This is the purpose of gpiCLIP* functions set.

Pre-Condition(s)

CLIIPING mode is on.
A PAN - EMV tag 5A - has been previously stored by a clipping module (from an APDU exchange).

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiCLIPCheckPANInCertificate (unsigned short tagCertificate, unsigned char offset, const unsigned char* certificate, unsigned char certificateLength);

Parameters

unsigned short tagCertificate: in // EMV Tag certificate in process
unsigned char offset: in // PAN offset within certificate
unsigned char* certificate: in // Certificate in clear
unsigned char certificateLength: in // Certificate's length

Returned Values

tGPIError: cryNO_ERROR // PAN matches
tGPIError: cryERROR // PAN doesn't match

Example

N/A

gpiFindPANFromEFL

Description

Look for a PAN and a PSN from a configuration file.

Pre-Condition(s)

An EFL file must be defined.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiFindPANfromEFL (unsigned char* pan, unsigned char panLen, unsigned char* psn);

Parameters

unsigned char* pan: in // PAN
unsigned char panLen: in // PAN length
unsigned char* psn: in // PAN sequence number

Returned Values

tGPIError: cryFOUND
tGPIError: cryNOT_FOUND

Example

N/A

gpiGetEMVCertificate

Description

Get a payment network's public key from a configuration file.

Pre-Condition(s)

A CAKeys file must be defined.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiGetEMVCertificate (unsigned char* rid, unsigned char index, tEMVPubKey* key);

Parameters

unsigned char* rid: in // RID on 5 bytes
unsigned char index: in // Key index fetched from ICC
tEMVPubKey* key: out // Public key issued by the CA

Returned Values

tGPIError: cryNO_ERROR // Normal case of execution
tGPIError: cryNOT_FOUND

Example

N/A

gpiGetEMVCRL

Description

Look for a revocated certificate from a configuration file.

Pre-Condition(s)

A CRL file must be defined.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiGetEMVCRL (unsigned char* rid, unsigned char index, unsigned char* sn);

Parameters

unsigned char* rid: in // RID on 5 bytes
unsigned char index: in // Key index fetched from ICC
unsigned char* sn: out // Serial number on 3 bytes

Returned Values

tGPIError: cryFOUND // Certificate revocated
tGPIError: cryNOT_FOUND // Certificate not revocated

Example

N/A

gpiGetChecksum

Description

Calculate a checksum corresponding to a CL kernel or the CT kernel.

Pre-Condition(s)

A kernel must be present on the platform.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiGetChecksum (unsigned char component, char* checksum);

Parameters

unsigned char component: in // Kernel identifier where:
// EMVCo contact
//#define STANDARD			0x00
// EMVCo Cx
//#define C1				0x01
//#define MASTERCARD_PAYPASS		0x02
//#define VISA_PAYWAVE			0x03
//#define AMEX_EXPRESSPAY		0x04
//#define JCB_JSPEEDY			0x05
//#define DISCOVER_DPAS			0x06
//#define CUP_QUICKPASS			0x07
//#define DISCOVER_ZIP			0x0C
//#define INTERAC_FLASH			0x41
//#define PAYMENTS_AUSTRALIA_EFTPOS	0x42
//#define GEMALTO_PURE			0x43
 
char* checksum: out // Calculated 20 byte long checksum

Returned Values

tGPIError: cryNO_ERROR // Normal case of execution

Example

N/A

gpiGetRandomNumber

Description

Calculate a random number within a range.

Pre-Condition(s)

A seed is set.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiGetRandomNumber (unsigned int* random, unsigned int limit);

Parameters

unsigned int* random: out // Random number
unsigned int limit // Max random number value (RNG range)

Returned Values

tGPIError: adnNO_ERROR // Normal case of execution

Example

#include "gpihsm.h"
 
tByte i, Random[3];
 
// 0. Set random vector
for(i=0;i<3;i++) {
   gpiGetRandomNumber(&un,255);
   Random[i]=un;
}
 
// 1. Digest of ICC Data and random vector
gpiShaInit();
gpiShaUpdate(Random,3);
gpiShaFinal(hash);
 
// 2. Store Unpredictable Number (9F37)
if(TAG_EXIST(DATABASE,_9F37))
   agiRemoveTag(ctx, _9F37);
 
agiCreateTagWith(ctx,_9F37,4,hash+10);

gpiInitializeHSM

Description

Initialize files related to crypto-processing.

Pre-Condition(s)

N/A

Post-Condition(s)

GPI HSM crypto file names have been set (i.e. specific to any given hardware platform).

Signature

Prototype

tGPIError gpiInitializeHSM (const char* CertificateFilesName, const char* CertificatesRevocationListFileName, const char* ExceptionFileName);

Parameters

const char* CertificateFilesName: in // a.k.a CAKeys
const char* CertificatesRevocationListFileName: in // a.k.a CRL
const char* ExceptionFileName: in // a.k.a EFL

Returned Values

tGPIError: cryNO_ERROR // Normal case of execution

Example

N/A

gpiSECUREDPANMatched

Description

Compare actual PAN (tag 5A) with actual track2 equivalent data (tag 57) from the R-APDU. This function is called by C3/Visa CL kernel (if CLIPPING or SRED mode are on).

gpiSECURED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests.

Pre-Condition(s)

CLIPPING or SRED mode are on.
A PAN and a track2 equivalent data have been previously stored by a clipping or sred module (from an APDU exchange).

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiSECUREDPANMatched (void);

Parameters

void

Returned Values

tGPIError: cryNO_ERROR // PAN and track2 equivalent data match
tGPIError: cryERROR // PAN and track2 equivalent data don't match

Example

N/A

gpiSECUREDPrefixPANMatched

Description

Compare PAN's prefix with actual PAN (tag 5A) from the R-APDU.

gpiSECURED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests.

Pre-Condition(s)

CLIPPING or SRED mode are on.
A PAN has been previously stored by a clipping or sred module (from an APDU exchange).

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiSECUREDPrefixPANMatched (unsigned short tagCertificate, unsigned char offset, const unsigned char* certificate, unsigned char certificateLength);

Parameters

unsigned char tagCertificate: in // Certificate's tag to be used
unsigned char offset: in // Data to be used for matching
const unsigned char certificate: in // Data to be used
unsigned char certificateLength: in // Data length to be used

Returned Values

tGPIError: cryNO_ERROR // PAN and PAN's prefix match
tGPIError: cryERROR // PAN and PAN's prefix don't match

Example

N/A

gpiSECUREDShaUpdateOnCertificateData

Description

Perform a SHA update from data within a certificate (previously verified) at a specific offset for a given length.

gpiSECURED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests.

Pre-Condition(s)

CLIPPING or SRED mode are on.

Post-Condition(s)

SHA has been updated.

Signature

Prototype

tGPIError gpiSECUREDShaUpdateOnCertificateData (unsigned short tagCertificate, unsigned char offset, unsigned char length);

Parameters

unsigned char tagCertificate: in // Certificate's tag to be used for SHA update
unsigned char offset: in // Data to be used for SHA update
unsigned char length: in // Data length to be used for SHA update

Returned Values

void

Example

N/A

gpiSECUREDShaUpdateOnData

Description

Perform a SHA update from raw data for a given length.

gpiSECURED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests.

Pre-Condition(s)

CLIPPING or SRED mode are on.

Post-Condition(s)

SHA has been updated.

Signature

Prototype

tGPIError gpiSECUREDShaUpdateOnData (const unsigned char* data, unsigned char length);

Parameters

unsigned char* data: in // Data to be used for SHA update
unsigned char length: in // Data length to be used for SHA update

Returned Values

void

Example

N/A

gpiSECUREDShaUpdateOnDOL

Description

Perform a SHA update from DOL's data for a given length.

gpiSECURED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests.

Pre-Condition(s)

CLIPPING or SRED mode are on.

Post-Condition(s)

SHA has been updated.

Signature

Prototype

tGPIError gpiSECUREDShaUpdateOnDOL (unsigned short tagDOL, const unsigned char* data, unsigned char length);

Parameters

unsigned short tagDOL: in // DOL to update (9F38, 8C, or 8D)
unsigned char* data: in // Data to be used for SHA update
unsigned char length: in // Data length to be used for SHA update

Returned Values

void

Example

N/A

gpiSECUREDShaUpdateOnTLV

Description

Perform a SHA update from TLV data for a given length. Some TLV might be clipped. Hence, a preprocessing of the TLV string is required to fill it with actual values.

gpiSECURED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests.

Pre-Condition(s)

CLIPPING or SRED mode is on.

Post-Condition(s)

SHA has been updated.

Signature

Prototype

tGPIError gpiSECUREDShaUpdateOnTLV (const unsigned char* tlv, unsigned char tlvLength);

Parameters

unsigned char* tlv: in // TLV string to be used for SHA update
unsigned char tlvLength: in // TLV string length to be used for SHA update

Returned Values

void

Example

N/A

gpiSREDGetCDOLOffset

Description

Get offsets and lengths related to sensible tags (56, 57, and 5A) that are stored by the SRED secured module. This function may be called right before sending a GenAC (depending on how the SRED module manages CDOLs).

gpiSRED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests.

Pre-Condition(s)

CLIPPING or SRED mode is on.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiSREDGetCDOLOffset (unsigned char* _56Length, unsigned char* _56Offset, unsigned char* _57Length, unsigned char* _57Offset, unsigned char* _5aLength, unsigned char* _5aOffset);

Parameters

unsigned char* _56Length: out // Tag 56 length as described in CDOL1 or CDOL2
unsigned char* _56Offset: out // Tag 56 position in CDOL1 or CDOL2
unsigned char* _57Length: out // Tag 57 length as described in CDOL1 or CDOL2
unsigned char* _57Offset: out // Tag 57 position in CDOL1 or CDOL2
unsigned char* _5aLength: out // Tag 5A length as described in CDOL1 or CDOL2
unsigned char* _5aOffset: out // Tag 5A position in CDOL1 or CDOL2

Returned Values

tGPIError: cryNO_ERROR // Normal case of execution

Example

N/A

gpiSREDGetPKLength

Description

Get public key length (90, 9F46, or 9F2D).

gpiSRED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests. This secured module parses R-APDU during read record sequence so that this set of data is not compromised at application level.

Pre-Condition(s)

SRED mode is on.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiSREDGetPKLength (unsigned char tagCertificate, unsigned char* length);

Parameters

unsigned char tagCertificate: in // Public key's tag, either 90 (Issuer), 9F46 (ICC), or 9F2D (PIN)
unsigned char* length: out // Public key length

Returned Values

tGPIError: cryNO_ERROR // Normal case of execution

Example

N/A

gpiSREDIsPKPANValid

Description

Validate PAN (tag 5A) within ICC public key in SRED module (9F2D or 9F46).

gpiSRED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests. This secured module parses R-APDU during read record sequence so that this set of data is not compromised at application level.

Pre-Condition(s)

SRED mode is on.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiSREDIsPKPANValid (unsigned char tagCertificate, unsigned char offset);

Parameters

unsigned char tagCertificate: in // ICC public key's tag, either 9F2D (PIN) or 9F46 (ICC)
unsigned char offset: in // PAN offset within certificate

Returned Values

tGPIError: cryNO_ERROR // PAN matches with PAN inside certificate
tGPIError: cryERROR // PAN doesn't match with PAN inside certificate

Example

N/A

gpiSREDIsPKPresent

Description

Indicate whether public key is present in SRED module (90, 9F2D, or 9F46).

gpiSRED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests. This secured module parses R-APDU during read record sequence so that this set of data is not compromised at application level.

Pre-Condition(s)

SRED mode is on.

Post-Condition(s)

N/A

Signature

Prototype

tGPIError gpiSREDIsPKPresent (unsigned char tagCertificate);

Parameters

unsigned char tagCertificate: in // Public key's tag, either 90 (Issuer), 9F2D (PIN) or 9F46 (ICC)

Returned Values

tGPIError: cryFOUND // Public key found
tGPIError: cryNOT_FOUND // Public key not found

Example

N/A

gpiSREDSetCDOLOffset

Description

Set offsets and lengths related to sensible tags (56, 57, and 5A) that are stored by the SRED secured module. This function is called right before a GenAC, i.e. at a build CDOLx time.

gpiSRED* group of functions relies on a platform's secured module filtering, storing, and processing sensible EMV data (i.e. tag 56, tag 57, tag 5A, tag 90, tag 9F2D, and tag 9F46) from APDU exchanges and L2 requests. This secured module parses R-APDU during read record sequence so that this set of data is not compromised at application level.

Pre-Condition(s)

SRED mode is on.

Post-Condition(s)

Sensible EMV tags offset and length with the CDOL to be used at GenAC time are initialized.

Signature

Prototype

tGPIError gpiSREDSetCDOLOffset (unsigned char _56Length, unsigned char _56Offset, unsigned char _57Length, unsigned char _57Offset, unsigned char _5aLength, unsigned char _5aOffset);

Parameters

unsigned char _56Length: in // Tag 56 length as described in CDOL1 or CDOL2
unsigned char _56Offset: in // Tag 56 position in CDOL1 or CDOL2
unsigned char _57Length: in // Tag 57 length as described in CDOL1 or CDOL2
unsigned char _57Offset: in // Tag 57 position in CDOL1 or CDOL2
unsigned char _5aLength: in // Tag 5A length as described in CDOL1 or CDOL2
unsigned char _5aOffset: in // Tag 5A position in CDOL1 or CDOL2

Returned Values

tGPIError: cryNO_ERROR // Normal case of execution

Example

N/A

  • No labels