PINPAD API: Difference between revisions

From wizarPOS
No edit summary
No edit summary
Line 1: Line 1:
== Functions ==
== API Overview==
The calling sequence is [[#open|open]]>[[#show_text|show_text]]/[[#get_serial_number |get_serial_number ]]>[[#close|close ]] or [[#open|open]]>[[#select_key|select_key]]>[[#calculate_pin_block|calculate_pin_block]]/[[#calculate_mac|calculate_mac]]/[[#encrypt_string|encrypt_string]]>[[#close|close ]]
The calling sequence is [[#open|open]]>[[#show_text|show_text]]/[[#get_serial_number |get_serial_number ]]>[[#close|close ]] or [[#open|open]]>[[#select_key|select_key]]>[[#calculate_pin_block|calculate_pin_block]]/[[#calculate_mac|calculate_mac]]/[[#encrypt_string|encrypt_string]]>[[#close|close ]]
=== open ===
=== <big>open</big> ===
  int pinpad_open()
  int pinpad_open()
Open the PINPad device.
Open the PINPad device.
This operation should be used before other operations.
This operation should be used before other operations.
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}


'''Parameters'''
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].
=== <big>close</big> ===
=== close ===
   int pinpad_close()
   int pinpad_close()
Close the PINPad device.
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.
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.


'''Parameters'''
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}


'''Returns'''
The result code, >= 0, success; <0 [[Error_code|error code]].
   
   
=== show_text ===
=== <big>show_text</big> ===
   int pinpad_show_text(int nLineIndex, char* strText, int nLength, int nFlagSound)
   int pinpad_show_text(int nLineIndex, char* strText, int nLength, int nFlagSound)
Show text in the specified line.
Show text in the specified line.


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | 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
|}
{|
{|
|-
|-
| ''nLineIndex'' || int ||Line number to display, 0 or 1
|  
|-
|}
| ''strText'' || char* ||Text to show, String.getBytes()
{|class="wizarpostable"
|-
|-
| ''nLength'' || int ||Text length, the length maxsize is 14
!  scope="row" colspan="2" | Returns
|-
|-
| ''nFlagSound'' || int ||Not used
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].
 
=== <big>update_user_key</big> ===
=== update_user_key ===
   int pinpad_update_user_key(int nMasterKeyID, int nUserKeyID, unsigned char* pCipherNewUserKey, int nCipherNewUserKeyLength)
   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.
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.
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'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | 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
|}
{|
{|
|-
|-
| ''nMasterKeyID'' || int ||Master key id
|  
|}
{|class="wizarpostable"
|-
|-
| ''nUserKeyID'' || int ||User key id
!  scope="row" colspan="2" | Returns
|-
|-
| ''pCipherNewUserKey'' || unsigned char* ||New user key in cipher text
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|-
| ''nCipherNewUserKeyLength'' || int ||Length of new user key
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].
   
   
=== update_user_key_with_check ===
=== <big>update_user_key_with_check</big> ===
   int pinpad_update_user_key_with_check(int nMasterKeyID, int nUserKeyID, unsigned char *pCipherNewUserKey, int nCipherNewUserKeyLength, int nKeyUsge, unsigned char *pCheckValue, int nCheckValueLen)
   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.
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.
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'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
| nMasterKeyID || '''int:''' Master key id
|-
|-
| ''nMasterKeyID'' || int ||Master key id
| nUserKeyID || '''int:''' User key id
|-
|-
| ''nUserKeyID'' || int ||User key id
| pCipherNewUserKey || '''unsigned char*:''' New user key in cipher text
|-
|-
| ''pCipherNewUserKey'' || unsigned char* ||New user key in cipher text
| nCipherNewUserKeyLength || '''int:''' Length of new user key
|-
|-
| ''nCipherNewUserKeyLength'' || int ||Length of new user key
| nKeyUsge || '''int:''' Key type. 0--PIN key;1--MAC key;2—Data key
|-
|-
| ''nKeyUsge'' || int ||Key type. 0--PIN key;1--MAC key;2—Data key
| pCheckValue || '''unsigned char*:''' Check value of user key
|-
|-
| ''pCheckValue'' || unsigned char*||Check value of user key
| nCheckValueLen || '''int:''' Length of new user keyLength of check value, 4 bytes in general
|}
{|
|-
|-
| ''nCheckValueLen'' || int ||Length of new user keyLength of check value, 4 bytes in general
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== set_pin_length ===
=== <big>set_pin_length</big> ===
   int pinpad_set_pin_length(int nLength, int nFlag)
   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.
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.


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| nLength || '''int:''' PIN length
|-
| nFlag || '''int:''' Flag, 0--min length;1--max length
|}
{|
{|
|-
|-
| ''nLength'' || int ||PIN length
|  
|}
{|class="wizarpostable"
|-
|-
| ''nFlag'' || int ||Flag, 0--min length;1--max length
!  scope="row" colspan="2" | Returns
|-
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== get_serial_number ===
=== <big>get_serial_number</big> ===
   int pinpad_get_serial_number(unsigned char* pData,unsigned int nBufferLength)
   int pinpad_get_serial_number(unsigned char* pData,unsigned int nBufferLength)
Get serial number from the PINPad.
Get serial number from the PINPad.


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | Parameters
|-
| pData || '''unsigned char*:''' Serial number buffer
|-
| nBufferLength|| '''unsigned int:''' Length of buffer
|}
{|
{|
|-
|-
| ''pData'' || unsigned char* ||Serial number buffer
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|-
| ''nBufferLength'' || unsigned int ||Length of buffer
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== select_key ===
=== <big>select_key</big> ===
   int pinpad_select_key(int nKeyType, int nMasterKeyID, int nUserKeyID, int nAlgorith)
   int pinpad_select_key(int nKeyType, int nMasterKeyID, int nUserKeyID, int nAlgorith)
Select master key and user key before encryption operations.
Select master key and user key before encryption operations.
Line 124: Line 172:
If called before update user key, the user key is encrypted using the algorithm which defined by nAlgorith parameter.If the terminal device is a WIZARHAND_Q1 or Q2, the user key id is 0-2 when nKeyType is master-session pair.
If called before update user key, the user key is encrypted using the algorithm which defined by nAlgorith parameter.If the terminal device is a WIZARHAND_Q1 or Q2, the user key id is 0-2 when nKeyType is master-session pair.


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | 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
|}
{|
{|
|-
|-
| ''nKeyType'' || int ||1 : TDUKPT, 2 : MASTER-SESSION PAIR
|  
|}
{|class="wizarpostable"
|-
|-
| ''nMasterKeyID'' || int ||Master key id, 0-9 when nKeyType is master-session; Master key id, 0,1,2 when nKeyType is TDUKPT
!  scope="row" colspan="2" | Returns
|-
|-
| ''nUserKeyID'' || int ||User key id, used when nKeyType is master-session.
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|-
| ''nAlgorith'' || int ||1:3DES;2:SM4;3:AES
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== calculate_pin_block ===
=== <big>calculate_pin_block</big> ===
   int pinpad_calculate_pin_block(unsigned char* pASCIICardNumber, int nCardNumberLength, unsigned char* pPinBlockBuffer, int nPinBlockBufferLength, int nTimeout_MS, int nFlagSound)
   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.
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.
Line 145: Line 202:
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.
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'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
| pASCIICardNumber|| '''unsigned char*:''' Card number in ASCII format
|-
| nCardNumberLength || '''int:''' Length of card number
|-
| pPinBlockBuffer || '''unsigned char*:''' buffer for saving PIN block
|-
|-
| ''pASCIICardNumber'' || unsigned char*||Card number in ASCII format
| nPinBlockBufferLength || '''int:''' Length of buffer
|-
|-
| ''nCardNumberLength'' || int ||Length of card number
| nTimeout_MS || '''int:''' Timeout waiting for user input in milliseconds. If it is less than 0, then wait forever.
|-
|-
| ''pPinBlockBuffer'' || unsigned char*||buffer for saving PIN block
| nFlagSound || '''int:''' Not used
|}
{|
|-
|-
| ''nPinBlockBufferLength'' || int ||Length of buffer
|  
|}
{|class="wizarpostable"
|-
|-
| ''nTimeout_MS'' || int ||Timeout waiting for user input in milliseconds. If it is less than 0, then wait forever.
!  scope="row" colspan="2" | Returns
|-
|-
| ''nFlagSound'' || int ||Not used
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== calculate_mac ===
=== <big>calculate_mac</big> ===
   int pinpad_calculate_mac(unsigned char* pData, int nDataLength, int nMACFlag, unsigned char* pMACOutBuffer, int nMACOutBufferLength)
   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.
Calculate the MAC. The user key should be a MAC key whose id is 1 in general.


'''Parameters'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
| pData || '''unsigned char*：''' data
|-
|-
| ''pData'' || unsigned char*||data
| nDataLength || '''int：''' Data length
|-
|-
| ''nDataLength'' || int ||Data length
| nMACFlag || '''int：''' 0:X99, 1: ECB,2:SE919,3:UnionPayECB
|-
|-
| ''nMACFlag'' || int ||0:X99, 1: ECB,2:SE919,3:UnionPayECB
| pMACOutBuffer || '''unsigned char*：''' MAC data buffer
|-
|-
| ''pMACOutBuffer'' || unsigned char* ||MAC data buffer
| nMACOutBufferLength || '''int：''' Length of MAC data buffer
|}
{|
|-
|-
| ''nMACOutBufferLength'' || int ||Length of MAC data buffer
|  
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== encrypt_string ===
=== <big>encrypt_string</big> ===
   int pinpad_encrypt_string(unsigned char* pPlainText, int nTextLength, unsigned char* pCipherTextBuffer, int nCipherTextBufferLength)
   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.
Encrypt string. The user key should be a data key whose id is 2 in general.
The default Mode is ECB/NoPadding.
The default Mode is ECB/NoPadding.


'''Parameters'''
{|class="wizarpostable"
|-
! scope="row" colspan="2" | 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
|}
{|
{|
|-
|-
| ''pPlainText'' || unsigned char*||Plain text
|  
|-
|}
| ''nTextLength'' || int ||Length of plain text
{|class="wizarpostable"
|-
|-
| ''pCipherTextBuffer'' || unsigned char*||buffer for saving cipher text
!  scope="row" colspan="2" | Returns
|-
|-
| ''nCipherTextBufferLength'' || int ||Length of buffer
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, success; <0 [[Error_code|error code]].




=== update_cipher_master_key ===
=== <big>update_cipher_master_key</big> ===
   int pinpad_update_cipher_master_key(int nMasterKeyID,unsigned char* pCipherMasterKey, int nCipherMasterKeyLen,unsigned char *pCheckValue, int nCheckValueLen)
   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.
Update master key, the master key must be ciphered by transport key.


'''Parameters'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
|-
| ''nMasterKeyID'' || int ||Master key index
| nMasterKeyID || '''int：''' Master key index
|-
|-
| ''pCipherMasterKey'' || unsigned char* ||Length of plain text
| pCipherMasterKey || '''unsigned char*：''' Length of plain text
|-
|-
| ''nCipherMasterKeyLen'' || int ||Length of ciphered master key
| nCipherMasterKeyLen || '''int：''' Length of ciphered master key
|-
|-
| ''pCheckValue'' || int ||Check value
| pCheckValue || '''int：''' Check value
|-
|-
| ''nCheckValueLen'' || int ||Length of check value
| nCheckValueLen || '''int：''' Length of check value
|}
{|
|-
| 
|}
{|class="wizarpostable"
|-
!  scope="row" colspan="2" | Returns
|-
|  int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== update_user_key_with_check_E ===
=== <big>update_user_key_with_check_E</big> ===
   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)
   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.
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.
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'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
| nMasterKeyID || '''int：''' Master key index
|-
| nUserKeyID || '''int：''' User key id
|-
| pCipherNewUserKey || '''unsigned char*：''' New user key in cipher text
|-
|-
| ''nMasterKeyID'' || int ||Master key index
| nCipherNewUserKeyLength || '''int：''' Length of new user key
|-
|-
| ''nUserKeyID'' || int ||User key id
| nKeyUsge || '''int：''' Key type. 0--PIN key;1--MAC key;2—Data key
|-
|-
| ''pCipherNewUserKey'' || unsigned char* ||New user key in cipher text
| pCheckValue || '''unsigned char*：''' Check value of user key
|-
|-
| ''nCipherNewUserKeyLength'' || int ||Length of new user key
| nCheckValueLen || '''int：''' Length of check value, 4 bytes in general
|-
|-
| ''nKeyUsge'' || int ||Key type. 0--PIN key;1--MAC key;2—Data key
| algoCheckValue || '''int：''' ALGO_CHECK_VALUE:0-- ALGO_CHECK_VALUE_DEFAULT;1-- ALGO_CHECK_VALUE_SE919
|}
{|
|-
|-
| ''pCheckValue'' || unsigned char* ||Check value of user key
|  
|}
{|class="wizarpostable"
|-
|-
| ''nCheckValueLen'' || int ||Length of check value, 4 bytes in general
!  scope="row" colspan="2" | Returns
|-
|-
| ''algoCheckValue'' || int ||ALGO_CHECK_VALUE:0-- ALGO_CHECK_VALUE_DEFAULT;1-- ALGO_CHECK_VALUE_SE919
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== update_cipher_master_key_E ===
=== <big>update_cipher_master_key_E</big> ===
   int pinpad_update_cipher_master_key_E (int nMasterKeyID,unsigned char *pCipherMasterKey, int nCipherMasterKeyLen,unsigned char *pCheckValue, int nCheckValueLen,int algoCheckValue)
   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 .
Update master key, the master key must be ciphered by transport key, and use the selected algorithm of check .


'''Parameters'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
| nMasterKeyID || '''int：''' Master key index
|-
| pCipherMasterKey || '''unsigned char*：''' Ciphered master key
|-
| nCipherMasterKeyLen || '''int：''' Length of ciphered master key
|-
|-
| ''nMasterKeyID'' || int ||Master key index
| pCheckValue|| '''unsigned char*：''' Check value
|-
|-
| ''pCipherMasterKey'' || unsigned char* ||Ciphered master key
| nCheckValueLen || '''int：''' Length of check value
|-
|-
| ''nCipherMasterKeyLen'' || int ||Length of ciphered master key
| algoCheckValue || '''int：''' ALGO_CHECK_VALUE:0-- ALGO_CHECK_VALUE_DEFAULT;1-- ALGO_CHECK_VALUE_SE919
|}
{|
|-
|-
| ''pCheckValue'' || unsigned char* ||Check value
|  
|}
{|class="wizarpostable"
|-
|-
| ''nCheckValueLen'' || int ||Length of check value
!  scope="row" colspan="2" | Returns
|-
|-
| ''algoCheckValue'' || int ||ALGO_CHECK_VALUE:0-- ALGO_CHECK_VALUE_DEFAULT;1-- ALGO_CHECK_VALUE_SE919
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''


The result code, >= 0, success; <0 [[Error_code|error code]].


=== encrypt_string_with_mode ===
=== <big>encrypt_string_with_mode</big> ===
   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)  
   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.
Encrypt string.


'''Parameters'''
{|class="wizarpostable"
{|
|-
! scope="row" colspan="2" | Parameters
|-
| pPlainText || '''unsigned char*：''' Plain text
|-
| nTextLength || '''int：''' Length of plain text
|-
|-
| ''pPlainText'' || unsigned char* ||Plain text
| pCipherTextBuffer || '''unsigned char*：''' buffer for saving cipher text, for dukpt encrypt, the buffer data structure is: cipher data + KSN + counter.
|-
|-
| ''nTextLength'' || int ||Length of plain text
| nCipherTextBufferLength || '''int：''' Length of buffer
|-
|-
| ''pCipherTextBuffer'' || unsigned char* ||buffer for saving cipher text, for dukpt encrypt, the buffer data structure is: cipher data + KSN + counter.
| 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.
|-
|-
| ''nCipherTextBufferLength'' || int ||Length of buffer
| pIV || '''unsigned char*：''' initial vector, only for CBC, CFB, OFB mode, if without IV, set Null.
|-
|-
| ''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.
| nIVLen || '''int：''' length of IV, must be equal to block length according to the algorithm, if withoout IV, set 0.
|}
{|
|-
|-
| ''pIV'' || unsigned char* ||initial vector, only for CBC, CFB, OFB mode, if without IV, set Null.
|  
|}
{|class="wizarpostable"
|-
|-
| ''nIVLen'' || int ||length of IV, must be equal to block length according to the algorithm, if withoout IV, set 0.
!  scope="row" colspan="2" | Returns
|-
| int || The result code, >= 0, success; <0 [[Error_code|error code]].
|}
|}
'''Returns'''
The result code, >= 0, success; <0 [[Error_code|error code]].

Revision as of 09:00, 2 May 2018

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
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.

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; <0 error code.


select_key

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

Select master key and user key before encryption operations. If the device is external PINPad, the user key id is 0-1 when nKeyType is master-session pair. If called before update user key, the user key is encrypted using the algorithm which defined by nAlgorith parameter.If the terminal device is a WIZARHAND_Q1 or Q2, the user key id is 0-2 when nKeyType is master-session pair.

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; <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; <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; <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 int： 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： ALGO_CHECK_VALUE: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; <0 error code.
Retrieved from "http://sdkwiki.wizarpos.com/index.php?title=PINPAD_API&oldid=442"