Amadis
GPI 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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
Example
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
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
Parameters
Returned Values
Example
N/A