PINPAD API

API Overview

The calling sequence is open>show_text/get_serial_number >close or open>select_key>calculate_pin_block/calculate_mac/encrypt_string>close

open

int pinpad_open()

Open the PINPad device. This operation should be used before other operations.

Returns
int	The result code, >= 0, success; <0 error code.

close

int pinpad_close()

Close the PINPad device. The open and close apis are pair operations. If you don’t want to use this device, you should call the close api to release this device.

Returns
int	The result code, >= 0, success; <0 error code.

show_text

int pinpad_show_text(int nLineIndex, char* strText, int nLength, int nFlagSound)

Show text in the specified line.

Parameters
nLineIndex	int: Line number to display, 0 or 1
strText	char*: Text to show, String.getBytes()
nLength	int: Text length, the length maxsize is 14
nFlagSound	int: Not used

Returns
int	The result code, >= 0, success; <0 error code.

update_user_key

int pinpad_update_user_key(int nMasterKeyID, int nUserKeyID, unsigned char* pCipherNewUserKey, int nCipherNewUserKeyLength)

Update the user key. You should check the cipher user key by yourself through the specified master key and check value obtained from the server or other. The algorithm which using to encrypt user key is from select_key, but if not calling select key before update, the default algorithm is 3DES.

Parameters
nMasterKeyID	int: Master key id
nUserKeyID	int: User key id, 0-PIN key; 1-MAC key; 2-Data key
pCipherNewUserKey	unsigned char*: New user key in cipher text
nCipherNewUserKeyLength	int: Length of new user key

Returns
int	The result code, >= 0, success; <0 error code.

update_user_key_with_check

int pinpad_update_user_key_with_check(int nMasterKeyID, int nUserKeyID, unsigned char *pCipherNewUserKey, int nCipherNewUserKeyLength, int nKeyUsge, unsigned char *pCheckValue, int nCheckValueLen)

Update the user key with check value. You don’t need to check the cipher user key by yourself. The algorithm which using to encrypt user key is from select_key, but if not calling select key before update, the default algorithm is 3DES.

Parameters
nMasterKeyID	int: Master key id
nUserKeyID	int: User key id
pCipherNewUserKey	unsigned char*: New user key in cipher text
nCipherNewUserKeyLength	int: Length of new user key
nKeyUsge	int: Key type. 0-PIN key; 1-MAC key; 2-Data key
pCheckValue	unsigned char*: Check value of user key
nCheckValueLen	int: Length of new user keyLength of check value, 4 bytes in general

Returns
int	The result code, >= 0, success; <0 error code.

set_pin_length

int pinpad_set_pin_length(int nLength, int nFlag)

Set the max or min length of PIN. When you call the calculate_pin_block api, the number you can input is no more than the max length. The min length should be >=4, the max length should be <=12

Parameters
nLength	int: PIN length
nFlag	int: Flag, 0-min length; 1-max length

Returns
int	The result code, >= 0, success; <0 error code.

get_serial_number

int pinpad_get_serial_number(unsigned char* pData,unsigned int nBufferLength)

Get serial number from the PINPad.

Parameters
pData	unsigned char*: Serial number buffer
nBufferLength	unsigned int: Length of buffer

Returns
int	The result code, >= 0, success, length of serial number; <0 error code.

select_key

int pinpad_select_key(int nKeyType, int nMasterKeyID, int nUserKeyID, int nAlgorith)

Select the key before calculate pinblock, calculate MAC and encrypt data.

If the keyType is MASTER-SESSION PAIR:

• If the device is external PINPad, the user key id is 0-1.
• If the terminal device is a Q1 or Q2, the user key id is 0-2. 0 is for PIN key, 1 is for MAC key, 2 is for DATA key.
• If called before update user key, the user key is encrypted using the algorithm which defined by nAlgorith parameter.

If the keyType is TDUKPT:

• Keep the user key id as 0, not used.
• Set the mater key id to 0-2. The value is same with the index when you inject dukpt key. There are 3 groups of dukpt key, in every group, the driver generate PIN/MAC/DATA key automatically, don’t need to set again.

Parameters
nKeyType	int: 1 : TDUKPT, 2 : MASTER-SESSION PAIR
nMasterKeyID	int: Master key id, 0-9 when nKeyType is master-session; Master key id, 0,1,2 when nKeyType is TDUKPT
nUserKeyID	int: User key id, used when nKeyType is master-session.
nAlgorith	int: 1:3DES;2:SM4;3:AES

Returns
int	The result code, >= 0, success; <0 error code.

calculate_pin_block

int pinpad_calculate_pin_block(unsigned char* pASCIICardNumber, int nCardNumberLength, unsigned char* pPinBlockBuffer, int nPinBlockBufferLength, int nTimeout_MS, int nFlagSound)

Calculate the PIN block of the inputted PIN.

You should call select_key at first. The user key should be a PIN key whose id is 0 in general.

The length of card number is normally 13-19.

The max waiting time for PIN input is 60s, and the two PIN input time span is 10s, otherwise this API will return error code.

Parameters
pASCIICardNumber	unsigned char*: Card number in ASCII format
nCardNumberLength	int: Length of card number
pPinBlockBuffer	unsigned char*: buffer for saving PIN block
nPinBlockBufferLength	int: Length of buffer
nTimeout_MS	int: Timeout waiting for user input in milliseconds. If it is less than 0, then wait forever.
nFlagSound	int: Not used

Returns
int	The result code, >= 0, success, length of pin block; <0 error code.

calculate_mac

int pinpad_calculate_mac(unsigned char* pData, int nDataLength, int nMACFlag, unsigned char* pMACOutBuffer, int nMACOutBufferLength)

Calculate the MAC.

The user key should be a MAC key whose id is 1 in general.

Parameters
pData	unsigned char*： data
nDataLength	int： Data length
nMACFlag	int： 0:X99, 1: ECB,2:SE919,3:UnionPayECB
pMACOutBuffer	unsigned char*： MAC data buffer
nMACOutBufferLength	int： Length of MAC data buffer

Returns
int	The result code, >= 0, success, length of MAC; <0 error code.

encrypt_string

int pinpad_encrypt_string(unsigned char* pPlainText, int nTextLength, unsigned char* pCipherTextBuffer, int nCipherTextBufferLength)

Encrypt string.

The user key should be a data key whose id is 2 in general. The default Mode is ECB/NoPadding.

Parameters
pPlainText	unsigned char*： Plain text
nTextLength	int： Length of plain text
pCipherTextBuffer	unsigned char*： buffer for saving cipher text
nCipherTextBufferLength	int： Length of buffer

Returns
int	The result code, >= 0, success, length of the encrypted data; <0 error code.

update_cipher_master_key

int pinpad_update_cipher_master_key(int nMasterKeyID,unsigned char* pCipherMasterKey, int nCipherMasterKeyLen,unsigned char *pCheckValue, int nCheckValueLen)

Update master key, the master key must be ciphered by transport key.

Parameters
nMasterKeyID	int： Master key index
pCipherMasterKey	unsigned char*： Length of plain text
nCipherMasterKeyLen	int： Length of ciphered master key
pCheckValue	unsigned char*： Check value
nCheckValueLen	int： Length of check value

Returns
int	The result code, >= 0, success; <0 error code.

update_user_key_with_check_E

int pinpad_update_user_key_with_check_E(int nMasterKeyID, int nUserKeyID,unsigned char *pCipherNewUserKey, int nCipherNewUserKeyLength,int nKeyUsge, unsigned char *pCheckValue, int nCheckValueLen,int algoCheckValue)

Update the user key with check value.

You can set the the algorithm of check. The algorithm which using to encrypt user key is from select_key, but if not calling select key before update, the default algorithm is 3DES.

Parameters
nMasterKeyID	int： Master key index
nUserKeyID	int： User key id
pCipherNewUserKey	unsigned char*： New user key in cipher text
nCipherNewUserKeyLength	int： Length of new user key
nKeyUsge	int： Key type. 0-PIN key; 1-MAC key; 2—Data key
pCheckValue	unsigned char*： Check value of user key
nCheckValueLen	int： Length of check value, 4 bytes in general
algoCheckValue	int： ALGO_CHECK_VALUE:0-- ALGO_CHECK_VALUE_DEFAULT;1-- ALGO_CHECK_VALUE_SE919

Returns
int	The result code, >= 0, success; <0 error code.

update_cipher_master_key_E

int pinpad_update_cipher_master_key_E (int nMasterKeyID,unsigned char *pCipherMasterKey, int nCipherMasterKeyLen,unsigned char *pCheckValue, int nCheckValueLen,int algoCheckValue)

Update master key, the master key must be ciphered by transport key, and use the selected algorithm of check .

Parameters
nMasterKeyID	int： Master key index
pCipherMasterKey	unsigned char*： Ciphered master key
nCipherMasterKeyLen	int： Length of ciphered master key
pCheckValue	unsigned char*： Check value
nCheckValueLen	int： Length of check value
algoCheckValue	int： 0-ALGO_CHECK_VALUE_DEFAULT; 1-ALGO_CHECK_VALUE_SE919

Returns
int	The result code, >= 0, success; <0 error code.

encrypt_string_with_mode

int pinpad_encrypt_string_with_mode(unsigned char* pPlainText, int nTextLength, unsigned char* pCipherTextBuffer, int nCipherTextBufferLength, unsigned int nMode, unsigned char* pIV, unsigned int nIVLen)

Encrypt string.

Parameters
pPlainText	unsigned char*： Plain text
nTextLength	int： Length of plain text
pCipherTextBuffer	unsigned char*： buffer for saving cipher text, for dukpt encrypt, the buffer data structure is: cipher data + KSN + counter.
nCipherTextBufferLength	int： Length of buffer
nMode	int： Cipher mode: 0-PINPAD_ENCRYPT_STRING_MODE_EBC; 1-PINPAD_ENCRYPT_STRING_MODE_CBC; 2-PINPAD_ENCRYPT_STRING_MODE_CFB; 3-PINPAD_ENCRYPT_STRING_MODE_OFB; Use NoPadding.
pIV	unsigned char*： initial vector, only for CBC, CFB, OFB mode, if without IV, set Null.
nIVLen	int： length of IV, must be equal to block length according to the algorithm, if withoout IV, set 0.

Returns
int	The result code, >= 0, success, length of encrypted data; <0 error code.