Amadis

GPI HSM Primitives

Owned by Seyhmus Cacina (Unlicensed)
Last updated: Jan 04, 2021 by Olivier Chauvineau (Unlicensed)
8 min read
1 gpiCLIPCheckPANInCertificate | 2 gpiFindPANFromEFL | 3 gpiGetEMVCertificate | 4 gpiGetEMVCRL | 5 gpiGetChecksum | 6 gpiGetRandomNumber | 7 gpiInitializeHSM | 8 gpiSECUREDPANMatched | 9 gpiSECUREDPrefixPANMatched | 10 gpiSECUREDShaUpdateOnCertificateData | 11 gpiSECUREDShaUpdateOnData | 12 gpiSECUREDShaUpdateOnDOL | 13 gpiSECUREDShaUpdateOnTLV | 14 gpiSREDGetCDOLOffset | 15 gpiSREDGetPKLength | 16 gpiSREDIsPKPANValid | 17 gpiSREDIsPKPresent | 18 gpiSREDSetCDOLOffset

 

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