Table of Contents | ||||||
---|---|---|---|---|---|---|
|
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.
...
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
Code Block |
---|
tGPIError gpiCLIPCheckPANInCertificate (unsigned short tagCertificate, unsigned char offset, const unsigned char* certificate, unsigned char certificateLength); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiFindPANfromEFL (unsigned char* pan, unsigned char panLen, unsigned char* psn); |
Parameters
Code Block |
---|
unsigned char* pan: in // PAN unsigned char panLen: in // PAN length unsigned char* psn: in // PAN sequence number |
Returned Values
Code Block |
---|
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
Code Block |
---|
tGPIError gpiGetEMVCertificate (unsigned char* rid, unsigned char index, tEMVPubKey* key); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiGetEMVCRL (unsigned char* rid, unsigned char index, unsigned char* sn); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiGetChecksum (unsigned char component, char* checksum); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiGetRandomNumber (unsigned int* random, unsigned int limit); |
Parameters
Code Block |
---|
unsigned int* random: out // Random number unsigned int limit // Max random number value (RNG range) |
Returned Values
Code Block |
---|
tGPIError: adnNO_ERROR // Normal case of execution |
Example
Code Block |
---|
#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
Code Block |
---|
tGPIError gpiInitializeHSM (const char* CertificateFilesName, const char* CertificatesRevocationListFileName, const char* ExceptionFileName); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSECUREDPANMatched (void); |
Parameters
Code Block |
---|
void |
Returned Values
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSECUREDPrefixPANMatched (unsigned short tagCertificate, unsigned char offset, const unsigned char* certificate, unsigned char certificateLength); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSECUREDShaUpdateOnCertificateData (unsigned short tagCertificate, unsigned char offset, unsigned char length); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSECUREDShaUpdateOnData (const unsigned char* data, unsigned char length); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSECUREDShaUpdateOnDOL (unsigned short tagDOL, const unsigned char* data, unsigned char length); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSECUREDShaUpdateOnTLV (const unsigned char* tlv, unsigned char tlvLength); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSREDGetCDOLOffset (unsigned char* _56Length, unsigned char* _56Offset, unsigned char* _57Length, unsigned char* _57Offset, unsigned char* _5aLength, unsigned char* _5aOffset); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSREDGetPKLength (unsigned char tagCertificate, unsigned char* length); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSREDIsPKPANValid (unsigned char tagCertificate, unsigned char offset); |
Parameters
Code Block |
---|
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
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSREDIsPKPresent (unsigned char tagCertificate); |
Parameters
Code Block |
---|
unsigned char tagCertificate: in // Public key's tag, either 90 (Issuer), 9F2D (PIN) or 9F46 (ICC) |
Returned Values
Code Block |
---|
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
Code Block |
---|
tGPIError gpiSREDSetCDOLOffset (unsigned char _56Length, unsigned char _56Offset, unsigned char _57Length, unsigned char _57Offset, unsigned char _5aLength, unsigned char _5aOffset); |
Parameters
Code Block |
---|
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
Code Block |
---|
tGPIError: cryNO_ERROR // Normal case of execution |
Example
N/A