PIN Encryption

PIN Encryption

For offline card transactions with PIN, the PIN needs to be encrypted before transmission. EVO Payment supports both the DUKPT encryption algorithm and the national SM4 encryption algorithm.

DUKPT Encryption Rules

EVO Payment supports using the DUKPT (ANSI X9.24) encryption algorithm to encrypt PINs.

Key Usage Rules

When using the DUKPT algorithm to encrypt a PIN, you first need to generate a BDK and configure it in the EVO Payment system.

Obtain IPEK

Generate the IPEK using the BDK and KSN (EC=0).

Suppose

BDK is：0123456789ABCDEFFEDCBA9876543210
KSN is：FFFF0000000000000000
The resulting IPEK is：EFE8BA8E0216474AE09DE4DA59111A2E

Compute the PIN Block

Suppose

PIN is: 123456 Card Number is: 4217123412341234

EVO Payment uses the PIN Block format ANSI X9.8 (ISO Format 0). The computation process is as follows:

1. Remove the last digit from the card number and take the 12 digits from the second last digit forward: 712341234123
2. Pad the extracted card number with leading zeros to make 16 digits: 0000712341234123
3. Append the PIN length (two digits) to the PIN and pad with F to make 16 digits: 06123456FFFFFFFF
4. XOR 0000712341234123 with 06123456FFFFFFFF to get the PIN Block: 06124575BEDCBEDC

Step 3: Encrypt the PIN Block

Generate the PEK using the IPEK, then encrypt the PIN Block obtained in step 2.

Suppose

IPEK is: EFE8BA8E0216474AE09DE4DA59111A2E
PIN Block is: 06124575BEDCBEDC
KSN is: FFFF0000000000000003
The resulting ciphertext is: 3A13CFDF77DDB259

Place the Ciphertext in the Request Message

Set pinEncryptMethod to the encryption method used, encryptedPin to the ciphertext obtained in step 3, and keySerialNumber to the KSN of the PEK. The final message to be sent will be:

{
  "pin": {
    "encryptedPin": "3A13CFDF77DDB259",
    "keySerialNumber": "FFFF0000000000000003",
    "pinEncryptMethod": "DUKPT"
  }
}

National Encryption Rules (SM4)

EVO Payment supports using the SM4 encryption algorithm to encrypt PINs.

Key Usage Rules

When using the national algorithm to encrypt PINs, you need to generate a ZMK and configure it in the EVO Payment system. Then call the GET ZPK interface to obtain the ZPK used for encrypting the PIN.

TIP

1. Each call to the GET ZPK interface will get a new ZPK, while the previous ZPK remains valid for 1 hour. If you call the interface again to get a third ZPK, the first ZPK will still be valid for 1 hour.
2. The ZPK obtained through the GET ZPK interface is encrypted with the SM4 algorithm using ZMK and is in hex format. It needs to be decrypted before use.
3. Example of an encrypted ZPK ciphertext: f826a0355019c1fb828e57a7264ea254

Compute the PIN Block

Suppose

PIN is: 123456
Card Number is: 4217123412341234

EVO Payment uses the PIN Block format ANSI X9.8 (ISO Format 0). The computation process is as follows:

1. Remove the last digit from the card number and take the 12 digits from the second last digit forward: 712341234123
2. Pad the extracted card number with leading zeros to make 32 digits: 00000000000000000000712341234123
3. Append the PIN length (two digits) to the PIN and pad with F to make 32 digits: 06123456FFFFFFFFFFFFFFFFFFFFFFFF
4. XOR 00000000000000000000712341234123 with 06123456FFFFFFFFFFFFFFFFFFFFFFFF to get the PIN Block: 06123456FFFFFFFFFFFF8EDCBEDCBEDC

Step 2: Encrypt the PIN Block

Use the SM4 algorithm to encrypt the PIN Block obtained in step 1.

1. Encryption Algorithm: ECB
2. Padding Mode: No padding
3. Output Format: Hex

Suppose

ZPK plaintext is：0123456789abcdeffedcba9876543233

The resulting ciphertext is：74A57CEF9C4ECA1947D2507B1C3A868D

Place the Ciphertext in the Request Message

Set pinEncryptMethod to the encryption method used and encryptedPin to the ciphertext obtained in step 2. The final message to be sent will be:

{
  "pin": {
    "encryptedPin": "74A57CEF9C4ECA1947D2507B1C3A868D",
    "pinEncryptMethod": "SM4",
    "checkValue": "6hd43s"
  }
}

Order Number Rules

In a successful transaction, there are three order numbers: merchantTransID generated by the requester, evoTransID generated by EVO Payment, and pspTransID generated by the card organization.