HSM Primitives
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