ATM Pin encryption using 3DES

Introduction

Most modern ATM’s use a Triple Des algorithm to encrypt the pin and send it to a host server for processing. Once the host system receives the pin, it does a translation of the pin from one encryption key to another, and sends it to a bank. In this post I will attempt to explain the process and how it is done in the real world.

Overview of the Triple Data Encryption Standard

What we all call Triple DES is EDE (encrypt, decrypt, encrypt). The way that it works is that you take three 56-bit keys, and encrypt with K1, decrypt with K2 and encrypt with K3. There are two-key and three-key versions. Think of the two-key version as merely one where K1=K3. Note that if K1=K2=K3, then Triple DES is really Single DES.

Triple DES was created back when DES was getting a bit weaker than people were comfortable with. As a result, they wanted an easy way to get more strength. In a system dependent on DES, making a composite function out of multiple DESes is likely to be easier than bolting in a new cipher and sidesteps the political issue of arguing that the new cipher is better than DES.

As it turns out, when you compose a cipher into a new one, you can’t use a double enciphering. There is a class of attacks called meet-in-the-middle attacks, in which you encrypt from one end, decrypt from the other, and start looking for collisions (things that give you the same answer). With sufficient memory, Double DES (or any other cipher) would only be twice as strong as the base cipher — or one bit more in strength.

There’s more to it. If the cipher forms a group, then encrypting twice with two keys is equivalent to encrypting once with some key. Now, it’s not trivial to know what that other key is, but it means that a brute-force attack would find that third key as it tried all possible single-keys. So if the cipher’s a group, then multiple-ciphering is merely a waste of time.

Applying this encryption in Python is trivial as there are plenty of tested libraries that can provide the functionality like pyDes and Crypto :

import os
from Crypto.Cipher import DES3

def encrypt_file(in_filename, out_filename, chunk_size, key, iv):
    des3 = DES3.new(key, DES3.MODE_CFB, iv)

    with open(in_filename, 'r') as in_file:
        with open(out_filename, 'w') as out_file:
            while True:
                chunk = in_file.read(chunk_size)
                if len(chunk) == 0:
                    break
                elif len(chunk) % 16 != 0:
                    chunk += ' ' * (16 - len(chunk) % 16)
                out_file.write(des3.encrypt(chunk))

def decrypt_file(in_filename, out_filename, chunk_size, key, iv):
    des3 = DES3.new(key, DES3.MODE_CFB, iv)

    with open(in_filename, 'r') as in_file:
        with open(out_filename, 'w') as out_file:
            while True:
                chunk = in_file.read(chunk_size)
                if len(chunk) == 0:
                    break
                out_file.write(des3.decrypt(chunk))

 

ATM Internals and how they calculate the keys

When you have an ATM, you typically need to provide it with a set of encryption keys from your host, or HSM. These keys are clear text keys and it’s not encrypted in any way. Your host will link them to your terminal number, and when the ATM encrypts the pin; the host will know what keys are used so it can decrypt / translate them to the bank. The clear keys are never stored by the host, only the LMK encrypted keys.

Lets assume your host provides the following keys to you as the ‘ATM Encryption Key’ :

Clear component A: 67C4 A719 1ADA FD08 6432 CE0D D638 4AB
Key check value: 20D40B
Clear component B: 8A89 6D4C 4625 5E2A 1A75 2002 07A7 D35E
Key check value: 4EC801
Combined Check Value: 2B547D

Now typically you would enter the clear components into the ATM, as Encryption keys, and the ATM will combine them (Basically XOR Them) and derive the check value. If the check value match, then all is good.

What happens at your host end is the following:

Your host will also combine the keys and encrypt them under the LMK (Local Master Key). It will then use this key to encrypt all other keys that are sent to the ATM.

Now the ATM have a Terminal Master Key that it can use to decrypt all keys that are sent to it from the host.

ATM Configuration Request (Key Exchange)

Now when an ATM starts up, the first thing it does it send a configuration request to the host. This request is to get the Third key used in Triple DES.  The Host will generate a random Terminal Pin Key and encrypt it under the Terminal Master Key (TMK). Since the ATM has the Terminal Master Key, it can decrypt the encrypted TPK, and use all 3 Keys now for the Triple DES operations. (it actually uses 2)

The Host would generally execute the A0 Thales command to get this key. He would store the key in the key database to do the decryption / translation later.

 

Pin Encryption / Decryption

When a ATM gets ready to transmit a transaction it does the 3DES operation on the Pin only. the cypher text is now transmitted to the host. The host never knows the pin code, and only does a translation of the pin from the terminal keys to the bank keys.

The Host will have the following:

(ZPK) Zone Pin Key – from the Bank during Host to Bank Key exchange

(TPK) Terminal Pin Key – from Terminal using Terminal Configuration Request

(PAN) Account Number –  from Transaction transmitted.

With these values, the Host can translate the pin using a HSM, below is an example of the D4 Command.

 Res = KeyGenerator.TranslatePIN_TDES(TerminalPINKey=self.Crypto["TPK_LMK"], PINEncryptionKey=self.HostKeys["ZPK_LMK"], PINBlock=self.iso.getBit(52), AccountNumber=track2["PAN"][-13:-1])

def get_commandTPKPinBlock(self, TerminalPINKey, PINEncryptionKey, PINBlock, AccountNumber):

 command_code = 'D4'
 KTP = TerminalPINKey
 KPE = PINEncryptionKey
 PinBlock = PINBlock
 PAN = AccountNumber


 message = command_code
 message += KTP
 message += KPE
 message += PinBlock
 message += PAN
 return message
#transmit to HSM

The transaction can now be transmitted to the acquiring bank with the translated pin for processing.

Sometimes the ATM requires a Message Authentication Code, this will be covered in another post.

easy as pie

 

 

Implementing AS2805 Part 6 Host to Host Encryption using a Thales 9000 and Python

Introduction

The AS2805.6 Standard specifies communication security between two nodes during a financial transaction. These nodes needs to have a specific set of encryption algorithms, and needs to follow a specific process.

The specification is not very clear on what exactly needs to happen, so I intend to clarify the exact steps, with the HSM functions. Now in order to do this I will assume you have a Thales 9000 HSM, as well as you need to know how to properly operate it. All commands defined are in the 1270A547-015 Australian Standards LIC003 v2.3a.pdf Manual provided by Thales when purchasing the device.

Source Code

a Copy of this Manual can be found  here  [Thales 9000 Australian Standards LIC003 v2.3a]

a Copy of my AS2805  parser is located here

a Copy of my Thales commands class is located here

a Full version of a AS2805 Interchange Node is located here

KEK Process (Level 1)

For this process:

  1. you need to go to your HSM and generate 2 Clear components, you then need to form a KEKs key from these components. This can be done using the UI of the HSM manger, or with the FK console command.
  2. Store the KEKs formed from the clear components in your switch database.
  3. Your connecting node / host will then provide you with a set of clear components, you need to generate a key again, but in this case a KEKr
  4. You need to provide you host with your key components you generated in Step 1,so they can generate their corresponding KEKs.

Now you have a KEKr and a KEKs in your database as well as your host read,  for Level2

Session and MAC key Initialisation (Level 2)

This Level has 2 separate steps, the first step (Logon) validating the KEKr and KEKs so that both nodes know that the correct keys are being used. The second step (Key Exchange) is to create temporary keys that are changed every 60 minutes or 256 transactions.

Logon Process

 

During the logon process your HSM will need to generate 2 things:

  1. a Random Number (RN)
  2. an Inverted Random Number (~RN)

These numbers will be returned encrypted under the KEKr and KEKs, and you will need to validate them, this is also called end of proof point validation.

The Logon process is a 2 step process outlined in the image below.

Logon_process
Step 1

When you connect to your host you will receive a logon request, bit number 48 will be populated with a KRs from the host that you will need to validate with your KEKr.

Generating a KEKr Validation Response you would need your KRs received in this request, and you KEKr that you generated from your host components.

E2 Command Definition: To receive a random key (KRs) encrypted under a variant of a double length Key Encrypting Key (KEKr), compute from KRs another value, denoted KRr and encrypt it under another variant of the KEKr

Your HSM command will look as follows: >HEADE2{KEKr}{KRs} and you output will generate a KEKr. Your response to the host will need to include this value in bit number 48.

Step 2

You now need to send the host a logon request with bit 48 set with your KRs

E0 Command Definition:To generate a random key (KRs) and encrypt it with a variant of a double length Key Encrypting Key (KEKs). In addition, KRs is inverted (to form KRr) and the result encrypted with another variant of the KEKs.

Your HSM command will look as follows: >HEADE0{KEKs} and the output will generate a KRs.  Your host will validate this request, and return with a response.

Once both steps are complete, both you and the host has been validated that you are using the same keys.

An Example of this process is outlined below in Python:

 

 def __signon__Part1__(self):
 self.log.info("====Sign-On Process Started ====")
 self.__setState('signing_on')
 cur = self.con_switch.cursor(MySQLdb.cursors.DictCursor)

 try:
 self.log.info("Waiting for 0800 Request")
 self.s.settimeout(20.0)
 length_indicator = self.s.recv(2)
 if length_indicator == '':
 self.log.critical('Received a blank length indicator from switch... might be a disconnect')
 self.__setState("blank_response")
 else:
 size = struct.unpack('!H', length_indicator)[0]
 payload = self.s.recv(size)
 payload = ByteUtils.ByteToHex(payload)
 d = datetime.now()
 self.log.info(" Getting Sign-On Request 0800 = [%s]" % payload)
 if payload == '':
 self.log.critical('Received a blank response from switch... might be a disconnect')
 self.__setState("blank_response")
 else:
 iso_ans = AS2805(debug=False)
 iso_ans.setIsoContent(payload)


 self.__storeISOMessage(iso_ans, {"date_time_received": d.strftime("%Y-%m-%d %H:%M:%S")})
 if iso_ans.getMTI() == '0800':
 if iso_ans.getBit(70) == '001':
 #log.info("Logon Started with KEKr = %s, KEKs = %s" % ( self.KEKr, self.KEKs))
 KRs = iso_ans.getBit(48)
 #log.info("KRs %s Received from Host" % (KRs))
 #print "Generating a E0 Command with KEKr=%s, and KRs=%s" % (self.KEKr, KRs)
 self.ValidationResponse = KeyGenerator.Generate_KEKr_Validation_Response(KEKr=self.KEKr, KRs=KRs)
 #print self.ValidationResponse

 if self.ValidationResponse["ErrorCode"] == '00':
 #log.info("KRs Validation Response %s generated" % (self.ValidationResponse["KRr"]))
 d = datetime.now()
 iso_resp = AS2805(debug=False)
 iso_resp.setMTI('0810')
 iso_resp.setBit(7, d.strftime("%m%d%H%M%S"))
 iso_resp.setBit(11, iso_ans.getBit(11))
 iso_resp.setBit(33, self.Switch_IIN)
 iso_resp.setBit(39, '303')
 iso_resp.setBit(48, self.ValidationResponse["KRr"])
 iso_resp.setBit(70, '0001')
 iso_resp.setBit(100, self.Switch_IIN)

 iso_send = iso_resp.getNetworkISO()
 iso_send_hex = ByteUtils.HexToByte(iso_send[2:])
 self.log.info("Sending Sign-On Response 0810 [%s]" % ReadableAscii(iso_send))
 self.__send_message(iso_send_hex)
 self.__storeISOMessage(iso_resp, {"date_time_sent": d.strftime("%Y-%m-%d %H:%M:%S")})
 self.__setState('signed_on')
 else:
 self.log.error("0810 KRr Response Code = %s, Login Failed" % (self.ValidationResponse["ErrorCode"],))
 #TODO: Send Decline to the Partner

 else:
 self.log.error("Could not login with 0810")



 except InvalidAS2805, ii:
 self.log.error(ii)
 except socket.error as e:
 pass
 self.log.debug("nothing from host [%s]" % (e))
 except:
 #self.__signoff()
 self.log.exception("signon_failed")
 self.__setState("singon_failed")
 finally:
 cur.close()

 def __signon_Part2__(self):

 try:
 self.s.settimeout(20.0)
 self.ValidationRequest = KeyGenerator.Generate_KEKs_Validation_Request(KEKs=self.KEKs)
 d = datetime.now()
 iso_resp = AS2805(debug=False)
 iso_resp.setMTI('0800')
 iso_resp.setBit(7, d.strftime("%m%d%H%M%S"))
 iso_resp.setBit(11, self.__getNextStanNo())
 iso_resp.setBit(33, self.HostIIN)
 iso_resp.setBit(48, self.ValidationRequest["KRs"])
 iso_resp.setBit(70, '001')
 iso_resp.setBit(100, self.HostIIN)
 iso_send = iso_resp.getNetworkISO()
 iso_send_hex = ByteUtils.HexToByte(iso_send[2:])

 self.log.info("Sending Sign-On Request 0800 [%s]" % ReadableAscii(iso_send))
 self.__send_message(iso_send_hex)
 self.__storeISOMessage(iso_resp, {"date_time_sent": d.strftime("%Y-%m-%d %H:%M:%S")})

 self.log.info("Waiting for 0810 Response")
 a = self.s.recv(8192)
 payload = ByteUtils.ByteToHex(a[2:])
 d = datetime.now()
 self.log.info(" Getting Sign-On Response 0810 = [%s]" % payload)
 iso_ans = AS2805(debug=False)
 iso_ans.setIsoContent(payload)
 self.log.debug(iso_ans.dumpFields())
 self.__storeISOMessage(iso_ans, {"date_time_received": d.strftime("%Y-%m-%d %H:%M:%S")})
 if iso_ans.getBit(39) == '3030':
 self.log.info("====Sign-On Sequence Completed Successfully====")
 self.__setState("signed_on_dual")
 else:
 #self.__signoff()
 self.log.error("Could not login with 0800")
 self.__setState("singon_failed")
 except InvalidAS2805, ii:
 self.log.info(ii)
 except socket.error as e:
 self.log.info("nothing from host [%s]" % (e))
 except:
 #self.__signoff()
 self.log.exception("signon_failed")
 self.__setState("singon_failed")

 

Key Exchange (Level 2)

In the Key Exchange process, you will generate session keys for your node as well as MAC keys. Now when generating these keys, you need to remember that they need to be the same type as you partner node. (simply ask your processor for a trace if you want to confirm)

So right after a successful logon, you would need to wait for a key exchange request, (0820 with field 30 as 303) this key exchange request will have  a ZAK and a ZPK in field 48, these are encrypted under the KEKr generated on your host from their components. You would need to translate these keys using your KEKr under your LMK and generate check values for verification.

The command will look like follows: >HEADOK{KEKr}21H{ZPK}1H{ZAK}0H11111111111111111111111111111111

These keys are known as your: RECEIVE KEYS

Where the KEKr is the KEKr generated from your components, ZPK and ZAK is the ZPK and ZAK received. This will output the following:

def Translate_a_Set_of_Zone_Keys(KEKr, ZPK, ZAK, ZEK):
 response = KeyClass.execute_Translate_a_Set_of_Zone_Keys(KEKr, ZPK, ZAK, ZEK)
 #print response
 TranslatedZoneKeys = {}
 TranslatedZoneKeys["Header"] = response[2:6]
 TranslatedZoneKeys["ResponseCode"] = response[6:8]
 TranslatedZoneKeys["ErrorCode"] = response[8:10]
 if TranslatedZoneKeys["ErrorCode"] == '00':
 TranslatedZoneKeys["KCV Processing Flag"] = response[10:11]
 TranslatedZoneKeys["ZPK(LMK)"] = response[11:44]
 TranslatedZoneKeys["ZPK Check Value"] = response[44:50]
 TranslatedZoneKeys["ZAK(LMK)"] = response[50:83]
 TranslatedZoneKeys["ZAK Check Value"] = response[83:89]
 TranslatedZoneKeys["ZEK(LMK)"] = response[89:122]
 TranslatedZoneKeys["ZEK Check Value"] = response[122:128]
 return TranslatedZoneKeys

In other words, you need to generate the same keys, but under your LMK and store them in your key database

Now whenever you get a request from your host with a mac you can validate the mac using the ZAK(LMK), and when you get encrypted values from your host you can translate the values using the ZPK(LMK)

So, when you respond to the key exchange process you put the check values in field 40. Your host will validate the check values, and then wait for you to send a request using your KEKs.

Here is an implementation using Python:

def __key_exchange_listen(self):
 self.log.info("===== Key Exchange process Started =======")
 self.s.settimeout(20.0)
 length_indicator = self.s.recv(2)
 if length_indicator == '':
 self.log.critical('Received a blank length indicator from switch... might be a disconnect')
 self.__setState("blank_response")
 else:
 size = struct.unpack('!H', length_indicator)[0]
 payload = self.s.recv(size)
 payload = ByteUtils.ByteToHex(payload)
 d = datetime.now()
 self.log.info(" Receiving Key Exchange Request = [%s]" % payload)
 if payload == '':
 self.log.critical('Received a blank response from switch... might be a disconnect')
 self.__setState("blank_response")
 else:
 iso_ans = AS2805(debug=False)
 iso_ans.setIsoContent("%s" % (payload))
 self.log.debug(iso_ans.dumpFields())

 self.__storeISOMessage(iso_ans, {"date_time_received": d.strftime("%Y-%m-%d %H:%M:%S")})
 if iso_ans.getMTI() == '0820' and iso_ans.getBit(70) == '0101':
 Value = iso_ans.getBit(48)
 self.ZAK = Value[:32]
 self.ZPK = Value[32:]

 self.node_number = iso_ans.getBit(53)
 log.info("Recieve Keys under ZMK : ZAK= %s, ZPK = %s" % (self.ZAK, self.ZPK ))

 self.ZoneKeySet2 = KeyGenerator.Translate_a_Set_of_Zone_Keys(self.KEKr,ZPK=self.ZPK, ZAK=self.ZAK, ZEK='11111111111111111111111111111111')
 cur = self.con_switch.cursor(MySQLdb.cursors.DictCursor)
 sql = """UPDATE sessions_as2805 set
 ZPK_LMK = '%s',
 ZPK_ZMK = '%s',
 ZPK_Check ='%s',
 ZAK_LMK = '%s' ,
 ZAK_ZMK = '%s',
 ZAK_Check = '%s',
 ZEK_LMK = '%s',
 ZEK_Check = '%s',
 keyset_number = '%s'
 WHERE host_id = '%s' and keyset_description = 'Recieve' """ %\
 (
 self.ZoneKeySet2["ZPK(LMK)"],
 self.ZPK,
 self.ZoneKeySet2["ZPK Check Value"],
 self.ZoneKeySet2["ZAK(LMK)"],
 self.ZAK,
 self.ZoneKeySet2["ZAK Check Value"],
 self.ZoneKeySet2["ZEK(LMK)"],
 self.ZoneKeySet2["ZEK Check Value"],
 self.node_number,
 self.host_id)
 log.info("Recieve Keys under LMK : ZAK= %s, ZAK Check Value: %s ZPK = %s, ZPK Check Value: %s" % (self.ZoneKeySet2["ZAK(LMK)"], self.ZoneKeySet2["ZAK Check Value"], self.ZoneKeySet2["ZPK(LMK)"], self.ZoneKeySet2["ZPK Check Value"]))
 cur.execute(sql)
 self.log.debug("Records=%s" % (cur.rowcount,))
 iso_req = AS2805(debug=False)
 iso_req.setMTI('0830')
 iso_req.setBit(7, iso_ans.getBit(7))
 iso_req.setBit(11, iso_ans.getBit(11))
 iso_req.setBit(33, iso_ans.getBit(33))
 iso_req.setBit(39, '303')
 iso_req.setBit(48, self.ZoneKeySet2["ZAK Check Value"] + self.ZoneKeySet2["ZPK Check Value"])
 iso_req.setBit(53, iso_ans.getBit(53))
 iso_req.setBit(70, iso_ans.getBit(70))
 iso_req.setBit(100, iso_ans.getBit(100))
 self.__storeISOMessage(iso_req, {"date_time_sent": d.strftime("%Y-%m-%d %H:%M:%S")})
 try:

 iso_send = iso_req.getNetworkISO()
 iso_send_hex = ByteUtils.HexToByte(iso_send[2:])

 self.log.debug(iso_req.dumpFields())
 self.log.info("Sending Key Exchange Response = [%s]" % ReadableAscii(iso_send))
 self.__send_message(iso_send_hex)
 self.node_number = iso_ans.getBit(53)
 except:
 self.log.exception("key_exchange_failed")
 self.__setState('key_exchange_failed')

 finally:
 cur.close()

 

These Keys are known as your SEND KEYS

So when you send a key exchange request you would need to generate a set of zone keys, this command on your HSM would look like this;

>HEADOI{KEKs};HU;1

Where the KEKs is the KEKs that you generated from your components, and your output will be the following:

def Generate_a_Set_of_Zone_Keys(KEKs):
 response = KeyClass.execute_get_a_Set_of_Zone_Keys(KEKs)
 #print response
 ZoneKeys = {}
 ZoneKeys["Header"] = response[2:6]
 ZoneKeys["ResponseCode"] = response[6:8]
 ZoneKeys["ErrorCode"] = response[8:10]
 if ZoneKeys["ErrorCode"] == '00':
 ZoneKeys["ZPK(LMK)"] = response[10:43]
 ZoneKeys["ZPK(ZMK)"] = response[43:76]
 ZoneKeys["ZPK Check Value"] = response[76:82]
 ZoneKeys["ZAK(LMK)"] = response[82:115]
 ZoneKeys["ZAK(ZMK)"] = response[115:148]
 ZoneKeys["ZAK Check Value"] = response[148:154]
 ZoneKeys["ZEK(LMK)"] = response[154:187]
 ZoneKeys["ZEK(ZMK)"] = response[187:220]
 ZoneKeys["ZEK Check Value"] = response[220:226]
 return ZoneKeys

Now when sending your  0820 request, you need to set field 40 as ZAK(ZMK) + ZPK(ZMK). Your host will do a Validation request (same as you did in step 1) and send you the check values. you need to compare this to the check values generated by your OI command, and if they match then you have successfully exchanged keys.

Below is an implementation using Python:

 

 def __keyExchange__(self):
 self.__setState("key_exchange")

 self.__key_exchange_listen()


 cur = self.con_switch.cursor(MySQLdb.cursors.DictCursor)
 d = datetime.now()
 self.ZoneKeySet1 = {}
 self.ZoneKeySet2 = {}
 self.ZoneKeySet1 = KeyGenerator.Generate_a_Set_of_Zone_Keys(self.KEKs)


 iso_req = AS2805(debug=False)
 iso_req.setMTI('0820')
 iso_req.setBit(7, d.strftime("%m%d%H%M%S"))
 iso_req.setBit(11, self.__getNextStan())
 iso_req.setBit(33, self.HostIIN)
 iso_req.setBit(48, self.ZoneKeySet1["ZAK(ZMK)"][1:] + self.ZoneKeySet1["ZPK(ZMK)"][1:])
 iso_req.setBit(53, self.node_number)
 iso_req.setBit(70, '101')
 iso_req.setBit(100, self.SwitchLink_IIN)
 self.__storeISOMessage(iso_req, {"date_time_sent": d.strftime("%Y-%m-%d %H:%M:%S")})
 log.info("Send Keys under LMK : ZAK= %s, ZAK Check Value: %s ZPK = %s, ZPK Check Value: %s" % (self.ZoneKeySet1["ZAK(LMK)"], self.ZoneKeySet1["ZAK Check Value"], self.ZoneKeySet1["ZPK(LMK)"], self.ZoneKeySet1["ZPK Check Value"]))

 try:

 # send the Send Keys
 iso_send = iso_req.getNetworkISO()
 iso_send_hex = ByteUtils.HexToByte(iso_send[2:])

 self.log.debug(iso_req.dumpFields())
 self.log.info("Sending Key Exchange Request = [%s]" % ReadableAscii(iso_send))
 self.__send_message(iso_send_hex)

 self.s.settimeout(20.0)
 length_indicator = self.s.recv(2)
 if length_indicator == '':
 self.log.critical('Received a blank length indicator from switch... might be a disconnect')
 self.__setState("blank_response")
 else:
 size = struct.unpack('!H', length_indicator)[0]
 payload = self.s.recv(size)
 payload = ByteUtils.ByteToHex(payload)
 d = datetime.now()
 self.log.info(" Receiving Key Exchange Response = [%s]" % payload)
 if payload == '':
 self.log.critical('Received a blank response from switch... might be a disconnect')
 self.__setState("blank_response")
 else:
 iso_ans = AS2805(debug=False)
 iso_ans.setIsoContent(payload)
 self.log.debug(iso_ans.dumpFields())
 self.__storeISOMessage(iso_ans, {"date_time_received": d.strftime("%Y-%m-%d %H:%M:%S")})

 if iso_ans.getMTI() == '0830':
 if iso_ans.getBit(39) == '3030':

 Value = iso_ans.getBit(48)
 self.KMACs_KVC = Value[:6]
 self.KPEs_KVC = Value[6:]
 #self.log.info("KMACs_KVC = %s, KPEs_KVC = %s" % (self.KMACs_KVC, self.KPEs_KVC))
 if self.KMACs_KVC == self.ZoneKeySet1["ZAK Check Value"] and self.KPEs_KVC == self.ZoneKeySet1["ZPK Check Value"]:
 self.log.info("0820 Key Exchange successful: Check Values Match, ZAK Check Value= %s , ZPK Check Value = %s" % (self.ZoneKeySet1["ZAK Check Value"], self.ZoneKeySet1["ZPK Check Value"]))
 sql = """UPDATE sessions_as2805
 SET
 ZPK_LMK = '%s',
 ZPK_ZMK = '%s',
 ZPK_Check= '%s' ,
 ZAK_LMK= '%s',
 ZAK_ZMK = '%s',
 ZAK_Check ='%s',
 ZEK_LMK = '%s' ,
 ZEK_ZMK = '%s',
 ZEK_Check = '%s',
 keyset_number = '%s'
 WHERE host_id = '%s' and keyset_description = 'Send' """%\
 ( self.ZoneKeySet1["ZPK(LMK)"],
 self.ZoneKeySet1["ZPK(ZMK)"],
 self.ZoneKeySet1["ZPK Check Value"],
 self.ZoneKeySet1["ZAK(LMK)"],
 self.ZoneKeySet1["ZAK(ZMK)"],
 self.ZoneKeySet1["ZAK Check Value"],
 self.ZoneKeySet1["ZEK(LMK)"],
 self.ZoneKeySet1["ZEK(ZMK)"],
 self.ZoneKeySet1["ZEK Check Value"],
 self.node_number,
 self.host_id)

 cur.execute(sql)
 self.log.debug("Records=%s" % (cur.rowcount,))
 self.__setState("key_exchanged")

 self.__setState('session_key_ok')
 self.log.info("==== Key Exchange Sequence Completed Successfully====")
 self.last_key_exchange = datetime.now()

 else:
 self.log.error("Generate_a_Set_of_Zone_Keys: KVC Check Failed!!")
 else:
 self.log.error("0820 Response Code = %s, Key Exchange Failed" % (iso_ans.getBit(39)))
 except InvalidAS2805, ii:
 self.log.error(ii)
 self.s.close()
 self.s = None
 self.__setState("session_key_fail")
 except:
 self.log.exception("key_exchange_failed")
 self.__setState('key_exchange_failed')

 

Now that keys have successfully been exchanged, you can start submitting transactions.

When sending transactions encrypt data (pin / field) Send Keys, and when receiving data translate / decrypt using your receive keys, Generate MAC using Send MAC and Verify using Receive MAC.

  • TAK – Your key to generate and verify MACs
  • TEK – Your key to encrypt data and decrypt / translate

This concludes the implementation of Node to Node interfaces using AS2805 Standards.

Easy as Pie!

Typical Cryptography in AS2805 Explained

Key Management conforms to AS 2805 part 6.1.

KEK Establishment

Each interchange node contains an Interchange Send Key Encrypting Key (KEKs) and an Interchange Receive Key Encrypting Key (KEKr). The Interchange Send KEK is the same key as the Interchange Receive KEK in the partnering node, similarly the Interchange Receive KEK is the same as the Interchange Send KEK in the partnering node.

The Interchange Key Encrypting Keys are used to encipher and decipher the session keys when they are transmitted between the nodes and in the proof of end points process.

Interchange Key Encrypting Keys is statistically unique and shall be changed, at a minimum, once every two years.

 

Node A Node B
KEKs = KEKr
KEkr = KEKs

Session Keys

Each node keeps four sets of session keys, two send sets and two receive sets.

Each set of session keys consists of two keys, MAC Key, PIN Protect Key. Each session key is 128-bits long and stored in a secure manner.

The send session key sets are generated by the sending node and numbered “1” or “2”. The send session key sets are then forwarded to the receiving node to be used as the receive session key sets.

The receive session key sets are received in a 0820 Network Management Advice message with bit ‘070’ equal to 101 from the sending node. The set number of either “1” or “2” contained in bit 53 indicates the receive session key set used by the receiving node to verify the MAC, decipher the data and translate or verify the PIN.

One set of send session keys is used at a time and all Transactions sent from the sending node will generate the MAC and encipher the PIN, if present, using the MAC Generator Key and PIN Protect Key, respectively, from the same send session key set. The send session key set used is indicated by bit 53 (contains “1” or “2”) in each message. Session Keys must be statistically unique and replaced, at a minimum, once every hour or on every 256 Transactions, whichever occurs first.

 

 

Node A Node B
Send Session Keys Set 1 Receive Session Keys Set 1
MAC Key (KMACs1) = MAC Verification Key (KMACr1)
PIN Protect Key (KPEs1) = PIN Protect Key (KPEr1)
Send Session Keys Set 2 Receive Session Keys Set 2
MAC Key (KMACs2) = MAC Verification Key (KMACr2)
PIN Protect Key (KPEs2) = PIN Protect Key (KPEr2)
Receive Session Keys Set 1 Send Session Keys Set 1
MAC Verification Key (KMACr1) = MAC Key (KMACs1)
PIN Protect Key (KPEr1) = PIN Protect Key (KPEs1)
Receive Session Keys Set 2 Send Session Keys Set 2
MAC Verification Key (KMACr2) = MAC Key (KMACs2)
PIN Protect Key (KPEr2) = PIN Protect Key (KPEs2)

 

When enciphered for transmission, each session key type will use a unique variant of the Key Enciphering Key in accordance with AS 2805 part 6.1 request response (logon) from the other before starting any other message exchange. When ready to logon, a party should attempt to logon and continue to attempt to logon until a successful response has been received. Upon receipt of an unsolicited logon (i.e. receiving a logon message when in an assumed logged on state) or a message with a response code indicating an irrecoverable error, a party should send an immediate logoff message and attempts to logon should be made as soon as possible. All logon response messages should be inspected to ensure that the response code indicates a successful logon

Changing Session keys

While one set of send session keys is being used, the other send session key set is randomly generated by the sending node and their KVCs generated, the keys are then enciphered under the Interchange Send KEK and transmitted to the receiving node in a 0820 Network Management Advice message.

When a 0820 message is received by the receiving node, the session keys are deciphered using the Interchange Receive KEK. These deciphered keys are set up as the set of receive keys specified by the set number contained in bit 53 of the 0820 message. The Key Verification Codes (KVCs) are calculated by the receiving node and transmitted to the sending node in bit 48 of the 0830 message.

When the 0830 Network Management Advice response message is received at the node initiating the key change, the KVCs contained in the 0830 message are validated. If the KVCs are correct, the new send session key set can be used immediately. If the KVCs are invalid, new send session key set must be generated and the whole process is repeated.

 

Sign off

Either node may terminate the transmission of financial messages by sending a Sign Off Advice. A Sign Off is accomplished by the transmission of a 0820 Network Management Advice Message with a NMIC (Bit 70) equal to ‘002’.

 

Key change during normal processing

A session key change can occur at any time; each node independently initiates the change of their send keys. The sender will advise their sending session keys to the receiver using a 0820 Network Management Advice message with a NMIC equal to ‘101’ indicating key change. Once a valid response (0830 message) is received and the KVCs confirmed, the new keys can be used.

Thales 9000 with AS2805 Interchange & RSA EFTPOS Commands.

Interchange Cryptographic Keys 

Interchange keys are used to protect financial transactions initiated at Acquirer eftpos / ATM Terminals while in transit to the Issuer institution. Interchange keys may be either:

(a) PIN encrypting keys – used to protect the customer PIN from the point of origin to the point of authorisation. PIN encrypting keys are a specific instance of session keys;

(b) Session keys – used to secure, validate and protect the financial message. Session keys can be further qualified into those used in the terminal to Acquirer environment (terminal session keys) or on node to node links (interchange session keys);

(c) Key Encrypting Keys (KEK) – used to protect other keys (e.g. session keys) during exchange; or

(d) Transport Keys – used to protect keys (e.g. KEKs) during transport to the partner institution.

Cryptographic Algorithms 

DEA3 and DEA2 are the only approved algorithms for the protection of interchange information (full details of these algorithms may be found in the Australian standard AS 2805 part 5).

DEA3 keys are 128 bits in length (effectively 112 bits) and are generally referred to as triple DES or 3DES keys (the corresponding encryption algorithm is specified in AS 2805 part 5.4). Triple DES may also be acceptably implemented using a key length of 192 bits (effectively 168 bits).

DEA3 with a key length of 128 bits and DEA2 with key lengths equal to, or greater than 2048 bits are the minimum acceptable requirements for the effective protection of interchange information at the time of the issuance of this document.

In accordance with AS 2805 part 3, DEA3 must be used for PIN encipherment.

 Interchange Links 

For all Interchange Links, Issuers and Acquirers must ensure that:

(a) Security for Transactions processed over that Interchange Link complies with AS2805 Part 6;

(b) Message formats comply with AS2805 Part 2;

(c) Security of transactions from terminal to Acquirer and from Acquirer to Issuer complies with AS2805 Part 6;

(d) PIN security and encryption complies with AS2805 Parts 3 and 5.4;

(e) Key management practices comply with AS2805 Part 6.1;

In each case and as more particularly set out in Part 8:

(a) Message Authentication must apply to all Interchange Links;

(b) The Message Authentication Code (MAC) must be calculated using, as a minimum, a DEA 3 (128-bit) key, Triple DES and an algorithm conforming to AS2805 Part 4; and

(c) all interchange PIN and MAC cryptographic functions must be performed within a Tamper-responsive SCM

The Actual process using an Thales 9000 HSM (CECS Approved)

Now what we are clear on the actual requirements of CECS and APCA, lets  attempt to do this using  a Thales 9000.

Generate a Sponsor RSA key pair

This command is the first step as would be required to do this for all terminal commands.

  • This is done my using the HSM EI host Command, from the HSM base manual.
    • The input is the length of the RSA key set required,  and the length go the public key modulus.
  • The Public Key Verification Code should now be generated. This is done using the HSM H2 Command from the Australian Standards Support Manual.

The Public Key and the PVC are sent to your Interchange Partner via different paths, as per their direction. (lets call this OUR-Key and OUR-PVC)

Your Interchange partner will now do the same process and provide you with a Public Key and a PVC. (lets call this THEIR-Key and THEIR-PVC)

When we receive this Public Key from our Interchange Partner, the following should happen:

  • The PVC for the Key should be generated using the HSM H2 Command from the Australian Standards Support Manual.
  • The MAC for the Key should be generated using the HSM EO command from the HSM Base Manual.

We now have public keys exchanged and have them ready for use!!

Our Database should be looking like this:

|OUR-Key|OUR-PVC|THEIR-Key|THEIR-PVC|THEIR-MAC|GEN-PVC|

Now we have the Public keys exchanged and ready for use, we can generate our KEKs & send to Interchange Partner, and receive our KEKr from Interchange Partner;

  • To send our KEKs we will use the H4 command from the Australian Standards support manual.
  • To receive our KEKr we will use the H6 command from the Australian Standards support manual.

Once these are decrypted and stored in our key database we can generate and exchange our session MAC and PIN keys.

    • To generate and store our send keys we use the OI command from the Australian Standards support manual.
    • To receive and store our receive keys we use the OK command from the Australian Standards support manual.

Now we have all the keys in place we can start to process transactions.

    • To generate the MAC on a message there are a number of commands available, however as we are using the AS2805 standards we always recommend our customers use the C2 command from the Australian Standards support manual. This provides all the options required for the Australian environment.

Similarly to verify the MAC on a message there are a number of commands available, however as we are using the AS2805 standards we always recommend our customers use the C4 command from the Australian Standards support manual. This provides all the options required for the Australian environment.

Terminal Commands

Terminal Manufacturer will be injecting into the PINpads their Manufacturer Public Key. The MPK will be transmitted to SPONSOR securely. The MPK validity should be checked by verifying the PVC, this is achieved by generating a Public Key Verification Code This is done using the H2 command from the Australian Standards support manual. And the two values compared.

  • We also need to generate a PPASN, this is achieved using the AS2805 PK command.
  • The host will now send the SPK to the PINpad, the PINpad will now generate the KI (also known as KTI), and send to the host. This is recovered using the AS2805 host H8 command, which also returns the KCA, the KCA is encrypted under the LMK and the KTI.
  • Now we have the MPK and have verified it is genuine, we now need to generate a MAC for the Public Key, this is achieved using the Host EO command, this is used in subsequent processing. Note: this command is only available when the HSM is in Authorised State. We can now recover the PINpad Public from the MSK. This is achieved using the AS2805 H0 host command.
  • KCA is now used to create the TMK1 and TMK2 (also known as KEK1 & KEK2). These are generated using the C0 command.
  • Now we have the TMK’s in place we can use the TMK update commands.

Updating the Keys

  • When updating only TMK1 the AS2805 OU command is used.
  • When updating both TMK1 and TMK2 then the OW command is used.

Now we have the TMK’s in place and able to be updated, we can generate the Session Keys to be used for the PIN, MAC & optional encryption keys if required.

This is achieved using the AS2805 PI command. The PI command will generate the PIN, MAC, and optional Encryption keys.

  • Now we can have the session keys in place we can Decrypt the data, verify the MAC & verify the pin. The decrypt data & verify MAC steps depend on how it has been handled by the terminal. Has the terminal done the MAC first then encrypted the required data or has the terminal encrypted the data & then done the MAC. We have assumed that the Encrypt was done first.
  • Verify the MAC’s on the transactions from the terminal using the AS2805 C4.
  • Once the MAC has been verified we can then decrypt the required data with the AS2805 host command PW.
  • Now we have the required decrypted data you will need to either verify the PIN or Translate the PIN, to translate the PIN assuming the transaction is a debit card transaction. This is achieved using the AS2805 PO host command. To verify the PIN will use one of the following F0 or F2.

If you have translated the PIN we can form the message and generate a MAC for the message to be sent to Interchange Partner, this is achieved using the C2 command as detailed above in the Interchange messages.

The biggest problem we see with this are around the KEKs & KEKr is people get them around the wrong way. Your KEKs becomes the remote KEKr & vice versa. The AS2805 commands are designed to swap them over automatically. 

The other gotcha is we split the terminal side & the interchange side of the HSM, TMK (terminal master key) is like a KEK (ZMK (Zone master key)) but used on the terminal side of the network where a ZMK (KEKs & KEKr) is used for interchange side of the network.

 easy as Pie!

Thales Key Exchange Examples and Troubleshooting

Judging from the searches done to locate this blog, it’s clear many of us share the following opinion: although Thales (formerly RACAL) is a market leader with its 7000 and 8000 series of HSM devices, their documentation falls painfully short in two areas: there are NO COMMAND EXAMPLES (!!!) in the manuals (an appalling omission); and the troubleshooting assistance is also distressingly thin. As a result, we had to lean heavily on our local Thales distributor for guidance on how commands really get pieced together. And, man, is it ever esoteric….see my earlier posts regarding the ‘KSN Descriptor’ for evidence of that. Moreover, our distributor provided us with some outstanding troubleshooting support to get us through the all important FA/FB key exhange. So, I’ll post our experience here in hopes that others can benefit from it.

The FA/FB is the command exchange to “Translate a ZPK from ZMK to LMK Encryption.” We had this working internally with some simulated stuff, but once we tried this command ‘for real’ with our Debit/EBT gateway partner , we consistently received parity errors back from our Thales 8000 HSM (i.e., the FB returned with some result code != 0).

There are three possible issues / resolution paths to explore in these situations:

Your switching partner has employed an Atalla HSM and you’ve not taken it into account. When a Thales/RACAL HSM ‘talks’ to an Atalla, your box commands must specify an Atalla Variant.

Your switching partner didn’t specify a Key Scheme in its ZPK creation, and the default is X9.17 (‘X’). If you specify the RACAL Scheme (‘U’) in your ‘FA’ and the ZPK under ZMK provided to the box was created via the X9.17 scheme, you’ll get a parity error.

You created the ZMK cryptogram internally using one key scheme and now are trying to employ it in the FA command specifying (inadvertantly) the other variant scheme.

You want to try to resolve each of these in turn.

The “test solution” path for Item #1 is as follows…

Let’s assume your FA command is constructed like so:

FAU2D775BFD****************FABE0D7CU6C0FDE16D22FF2D95273E3741AF4E187

[NOTE: I’ve obscured the ZMK Cryptogram here for blogging purposes only. The actual value is a 32-position hexidecimal string.]

If you discover that the other side is using an Atalla, you need to specify an “Atalla Variant,” which you do by specifying a ‘1’ at the end of the ‘FA’ command string:

FAU2D775BFD****************FABE0D7CU6C0FDE16D22FF2D95273E3741AF4E1871

The “test solution” path for Item #2 is as follows…

We find some endpoint partners have no idea which Key Scheme (X9.17 or Racal Native) they employed to create their keys. So, you may have to experiment. This FA command string says that the ZMK and ZPK were created using the RACAL native scheme (‘U’):

FAU2D775BFD****************FABE0D7CU6C0FDE16D22FF2D95273E3741AF4E187

To specify that the ZPK was created using the X9.17 scheme, you’d do the following:

FAU2D775BFD****************FABE0D7CX6C0FDE16D22FF2D95273E3741AF4E187

The “test solution” path for Item #3 is as follows…

When you created your ZMK (probably during a key ceremony involving a reconstitution of key parts provided by your endpoint gateway), you specify (or otherwise let default) your ZMK Key Scheme. Again, this can be either the RACAL Native Scheme (‘U’) or X9.17 (‘X’). [I believe the default is X9.17.] For example, if you created the ZMK using the ‘X’ approach, and then submitted an ‘FA’ command that looks like this:

FAU2D775BFD****************FABE0D7CU6C0FDE16D22FF2D95273E3741AF4E187

…it’s gonna fail. You absolutely must maintain consistency from the creation of the ZMK cryptogram through its subsequent usage. So, the command would change to look like this:

FAX2D775BFD****************FABE0D7CU6C0FDE16D22FF2D95273E3741AF4E187

[NOTE: I’m not advocating ‘X’ over ‘U’ here…just showing you an example. In a recent concluded project, we assumed the incoming ZPK was of the RACAL native variety, but it arrived from the remote partner as created under the X9.17 scheme. Thing is, the gateway team had no idea they had done that and could not articulate the difference. So, be prepared to experiment with every permutation of what I’ve described herein before ‘unlocking’ the solution.]

Testing DUKPT

As an acquirer, you can validate that your PIN translation command is working correctly even if you haven’t yet established connectivity to your Debit/EBT endpoint (or if you’ve established connectivity but don’t yet have your test key parts).

Typically when we’re pressed into this situation, this is what we do if we’re working with the Key-Up II HSM from Ian Donnelly Systems (‘IDS’):

For simplicity’s sake, we use a weak double-length key part.

We enter it as a single part (again, at this point, we want to keep things simple).
Typically, we use 0123456789ABCDEFFEDCBA9876543210.

We take the Cryptogram obtained out of that exercise and we use that as our Key Exchange Key (“KEK”) input.

Now, in my reading of the Thales manuals, performing this exercise with the Thales device is quite a bit more complicated.

[I’ll use Thales language here so we’re all on the same page…]

GOAL: What you need to test PIN translation is a ZPK encrypted under your LMK. [Refer to my previous post for details on the CI/CJ PIN transalation request/response.]

Note specifically where I describe “PIN Length” on the CJ command output I say:

“Although this field is not used to build the 0200 message formatted for the processor gateway, a value like ‘04’ or ‘05’ here is a pretty good indication that the translation occurred successfully.”

So, we can validate the workability of this command without a working endpoint or ‘real’ key parts from them, but – in order to do so – we need to construct a valid ZPK under LMK cryptogram. This value will allow you to create a completely valid CI command, assuming that:

You’ve got one or more valid BDK cryptograms loaded in your encryption database.

You can generate PIN-enabled Debit purchases from a test point-of-sale location.

You have addressibility from your test server to the Thales.

STEPS: My reading of the Thales manual is that you’ll need to execute the following steps (this is sort of ugly – numbers refer to specific sections in the Operations and Installation manual):

6.1 to create at least two 32-positions ZMK components (or, alternatively, 6.3 if you want to use components of your own chosing).

6.4 to get a 32-position ZMK under LMK.

7.1 to generate random ZPK (uses 6.4 ZMK under LMK output as input here) and encrypt under ZMK and LMK. The goal is that second cryptogram that comes back, the one oddly named “ZPK encrypted for bank” in the Thales document. That’s the ZPK under the LMK that you need for your tests.

Obtaining this information should allow you to validate the critical part of your encryption infrastructure prior to getting connectivity to your Debit/EBT gateway partner. Of course, once formal inter-system testing is established you still need to transport the encrypted PIN block in an 0200 request to your endpoint. But doing the exercise I describe above here first will allow you to eliminate any self-doubt you may have about your internal PIN translation activities prior to getting an external party involved in the testing

Parsing AS2505/8583 Messages

Foreword

Previously I briefly touched on the AS2805 standards, and now I have an implementation of the parsing of these messages

The full code of this post is available here : https://github.com/Arthurvdmerwe/AS2805_Python_Implementation

I have a C# implementation of this as well here:

https://github.com/Arthurvdmerwe/AS2805

The code is thanks to the following author: http://www.vulcanno.com.br/python/ISO8583.html

He has a brilliant implementation of all the structures of the 8583 format, which goes hand in hand with AS2805

First off, the AS2805 standard includes a range of specifications, from Key handling settlement. This is not a post to explain all the details, as the key and settlement handling is a processor specific implementation.

AS2805 is extremely similar to the ISO8583 specification, and most of it can be taken directly out of this specification.

AS2805 Financial transaction card originated messages — Interchange message specifications is the International Organization for Standardization standard for systems that exchange electronic transactions made by cardholders using payment cards. It has three parts:

  • Part 1: Messages, data elements and code values
  • Part 2: Application and registration procedures for Institution Identification Codes (IIC)
  • Part 3: Maintenance procedures for messages, data elements and code values

Introduction

A card-based transaction typically travels from a transaction acquiring device, such as a point-of-sale terminal or an automated teller machine (ATM), through a series of networks, to a card issuing system for authorization against the card holder’s account. The transaction data contains information derived from the card (e.g., the account number), the terminal (e.g., the merchant number), the transaction (e.g., the amount), together with other data which may be generated dynamically or added by intervening systems. The card issuing system will either authorize or decline the transaction and generate a response message which must be delivered back to the terminal within a predefined time period.

AS2805 defines a message format and a communication flow so that different systems can exchange these transaction requests and responses. The vast majority of transactions made at ATMs use AS2805 at some point in the communication chain, as do transactions made when a customer uses a card to make a payment in a store (EFTPOS). In particular, both the MasterCard andVisa networks base their authorization communications on the ISO 8583 standard, as do many other institutions and networks. AS2805 has no routing information, so is sometimes used with aTPDU header.

Cardholder-originated transactions include purchase, withdrawal, deposit, refund, reversal, balance inquiry, payments and inter-account transfers. AS2805 also defines system-to-system messages for secure key exchanges, reconciliation of totals, and other administrative purposes.

Although AS2805 defines a common standard, it is not typically used directly by systems or networks. It defines many standard fields (data elements) which remain the same in all systems or networks, and leaves a few additional fields for passing network specific details. These fields are used by each network to adapt the standard for its own use with custom fields and custom usages.

The placements of fields in different versions of the standard varies;

An AS2805 message is made of the following parts:

  • Message type indicator (MTI)
  • One or more bitmaps, indicating which data elements are present
  • Data elements, the fields of the message

 

Message type indicator

This is a 4 digit numeric field which classifies the high level function of the message. A message type indicator includes the ISO 8583 version, the Message Class, the Message Function and the Message Origin, each described briefly in the following sections. The following example (MTI 0110) lists what each digit indicates:

  0xxx -> version of AS2805 
  x1xx -> class of the Message (Authorization Message)
  xx1x -> function of the Message (Request Response)
  xxx0 -> who began the communication (Acquirer)

AS2805 version

Position one of the MTI specifies the versions of the AS2805 standard which is being used to transmit the message.

Position Meaning
0xxx ISO 8583-1:1987 version
1xxx ISO 8583-2:1993 version
2xxx ISO 8583-1:2003 version
3xxx Reserved for ISO use
4xxx Reserved for ISO use
5xxx Reserved for ISO use
6xxx Reserved for ISO use
7xxx Reserved for ISO use
8xxx Reserved for National use
9xxx Reserved for Private use

Message class

Position two of the MTI specifies the overall purpose of the message.

Position Meaning Usage
x1xx Authorization Message Determine if funds are available, get an approval but do not post to account for reconciliation, Dual Message System (DMS), awaits file exchange for posting to account
x2xx Financial Messages Determine if funds are available, get an approval and post directly to the account, Single Message System (SMS), no file exchange after this
x3xx File Actions Message Used for hot-card, TMS and other exchanges
x4xx Reversal Message Reverses the action of a previous authorization
x5xx Reconciliation Message Transmits settlement information message
x6xx Administrative Message Transmits administrative advice. Often used for failure messages (e.g. message reject or failure to apply)
x7xx Fee Collection Messages
x8xx Network Management Message Used for secure key exchange, logon, echo test and other network functions
x9xx Reserved by ISO

Message function

Position three of the MTI specifies the message function which defines how the message should flow within the system. Requests are end-to-end messages (e.g., from acquirer to issuer and back with timeouts and automatic reversals in place), while advices are point-to-point messages (e.g., from terminal to acquirer, from acquirer to network, from network to issuer, with transmission guaranteed over each link, but not necessarily immediately).

Position Meaning
xx0x Request
xx1x Request Response
xx2x Advice
xx3x Advice Response
xx4x Notification
xx8x Response acknowledgment
xx9x Negative acknowledgment

Message origin

Position four of the MTI defines the location of the message source within the payment chain.

Position Meaning
xxx0 Acquirer
xxx1 Acquirer Repeat
xxx2 Issuer
xxx3 Issuer Repeat
xxx4 Other
xxx5 Other Repeat

Examples

Bearing each of the above four positions in mind, an MTI will completely specify what a message should do, and how it is to be transmitted around the network. Unfortunately, not all AS2805 implementations interpret the meaning of an MTI in the same way. However, a few MTIs are relatively standard:

MTI Meaning Usage
0100 Authorization request Request from a point-of-sale terminal for authorization for a cardholder purchase
0110 Issuer Response Issuer response to a point-of-sale terminal for authorization for a cardholder purchase
0120 Authorization Advice When the Point of Sale device breaks down and you have to sign a voucher
0121 Authorisation Advice Repeat If the advice times out
0130 Issuer Response to Authorization Advice Confirmation of receipt of authorization advice
0200 Acquirer Financial Request Request for funds, typically from an ATM or pinned point-of-sale device
0210 Issuer Response to Financial Request Issuer response to request for funds
0220 Acquirer Financial Advice e.g. Checkout at a hotel. Used to complete transaction initiated with authorization request
0221 Acquirer Financial Advice repeat If the advice times out
0230 Issuer Response to Financial Advice Confirmation of receipt of financial advice
0400 Acquirer Reversal Request Reverses a transaction
0420 Acquirer Reversal Advice Advises that a reversal has taken place
0421 Acquirer Reversal Advice Repeat Message If the reversal times out
0430 Issuer Reversal Response Confirmation of receipt of reversal advice
0800 Network Management Request Echo test, logon, log off etc.
0810 Network Management Response Echo test, logon, log off etc.
0820 Network Management Advice Keychange

Bitmaps

Within AS2805, a bitmap is a field or subfield within a message which indicates which other data elements or data element subfields may be present elsewhere in a message.

A message will contain at least one bitmap, called the Primary Bitmap which indicates which of Data Elements 1 to 64 are present. A secondary bitmap may also be present, generally as data element one and indicates which of data elements 65 to 128 are present. Similarly, a tertiary, or third, bitmap can be used to indicate the presence or absence of fields 129 to 192, although these data elements are rarely used.

The bitmap may be transmitted as 8 bytes of binary data, or as 16 hexadecimal characters 0-9, A-F in the ASCII or EBCDIC character sets.

A field is present only when the specific bit in the bitmap is true. For example, byte ’82x is binary ‘1000 0010’ which means fields 1 and 7 are present in the message and fields 2, 3, 4, 5, 6, and 8 are not present.

Examples —–

Bitmap Defines presence of
4210001102C04804 Fields 2, 7, 12, 28, 32, 39, 41, 42, 50, 53, 62
7234054128C28805 Fields 2, 3, 4, 7, 11, 12, 14, 22, 24, 26, 32, 35, 37, 41, 42, 47, 49, 53, 62, 64
8000000000000001 Fields 1, 64
0000000000000003
(secondary bitmap)		 Fields 127, 128

Explanation of Bitmap (8 BYTE Primary Bitmap = 64 Bit) field 4210001102C04804
BYTE1 : 01000010 = 42x (counting from the left, the second and seventh bits are 1, indicating that fields 2 and 7 are present)
BYTE2 : 00010000 = 10x (field 12 is present)
BYTE3 : 00000000 = 00x (no fields present)
BYTE4 : 00010001 = 11x (fields 28 and 32 are present)
BYTE5 : 00000010 = 02x (field 39 is present)
BYTE6 : 11000000 = C0x (fields 41 and 42 are present)
BYTE7 : 01001000 = 48x (fields 50 and 53 are present)
BYTE8 : 00000100 = 04x (field 62 is present)

0________10________20________30________40________50________60__64
1234567890123456789012345678901234567890123456789012345678901234  n-th bit
0100001000010000000000000001000100000010110000000100100000000100  bit map

Fields present in the above variable length message record:
2-7-12-28-32-39-41-42-50-53-62

Data elements

Data elements are the individual fields carrying the transaction information. There are up to 128 data elements specified in the original AS2805 standard, and up to 192 data elements in later releases.

While each data element has a specified meaning and format, the standard also includes some general purpose data elements and system- or country-specific data elements which vary enormously in use and form from implementation to implementation.

Each data element is described in a standard format which defines the permitted content of the field (numeric, binary, etc.) and the field length (variable or fixed), according to the following table:

Abbreviation Meaning
a Alpha, including blanks
n Numeric values only
s Special characters only
an Alphanumeric
as Alpha & special characters only
ns Numeric and special characters only
ans Alphabetic, numeric and special characters.
b Binary data
z Tracks 2 and 3 code set as defined in ISO/IEC 7813 and ISO/IEC 4909 respectively
. or .. or … variable field length indicator, each . indicating a digit.
x or xx or xxx fixed length of field or maximum length in the case of variable length fields.

Additionally, each field may be either fixed or variable length. If variable, the length of the field will be preceded by a length indicator.

Type Meaning
Fixed no field length used
LLVAR or (..xx) Where LL < 100, means two leading digits LL specify the field length of field VAR
LLLVAR or (…xxx) Where LLL < 1000, means three leading digits LLL specify the field length of field VAR
LL and LLL are hex or ASCII. A VAR field can be compressed or ASCII depending of the data element type. LL can be 1 or 2 bytes. For example, if compressed as one hex byte, ’27x means there are 27 VAR bytes to follow. If ASCII, the two bytes ’32x, ’37x mean there are 27 bytes to follow. 3 digit field length LLL uses 2 bytes with a leading ‘0’ nibble if compressed, or 3 bytes if ASCII. The format of a VAR data element depends on the data element type. If numeric it will be compressed, e.g. 87456 will be represented by 3 hex bytes ‘087456x. If ASCII then one byte for each digit or character is used, e.g. ’38x, ’37x, ’34x, ’35x, ’36x.
AS2805-defined data elements
Data element Type Usage
1 b 64 Bit map (b 128 if secondary is present and b 192 if tertiary is present)
2 n ..19 Primary account number (PAN)
3 n 6 Processing code
4 n 12 Amount, transaction
5 n 12 Amount, settlement
6 n 12 Amount, cardholder billing
7 n 10 Transmission date & time
8 n 8 Amount, cardholder billing fee
9 n 8 Conversion rate, settlement
10 n 8 Conversion rate, cardholder billing
11 n 6 Systems trace audit number
12 n 6 Time, local transaction (hhmmss)
13 n 4 Date, local transaction (MMDD)
14 n 4 Date, expiration
15 n 4 Date, settlement
16 n 4 Date, conversion
17 n 4 Date, capture
18 n 4 Merchant type
19 n 3 Acquiring institution country code
20 n 3 PAN extended, country code
21 n 3 Forwarding institution. country code
22 n 3 Point of service entry mode
23 n 3 Application PAN number
24 n 3 Function code (ISO 8583:1993)/Network International identifier (NII)
25 n 2 Point of service condition code
26 n 2 Point of service capture code
27 n 1 Authorizing identification response length
28 n 8 Amount, transaction fee
29 n 8 Amount, settlement fee
30 n 8 Amount, transaction processing fee
31 n 8 Amount, settlement processing fee
32 n ..11 Acquiring institution identification code
33 n ..11 Forwarding institution identification code
34 n ..28 Primary account number, extended
35 z ..37 Track 2 data
36 n …104 Track 3 data
37 an 12 Retrieval reference number
38 an 6 Authorization identification response
39 an 2 Response code
40 an 3 Service restriction code
41 ans 16 Card acceptor terminal identification
42 ans 15 Card acceptor identification code
43 ans 40 Card acceptor name/location (1-23 address 24-36 city 37-38 state 39-40 country)
44 an ..25 Additional response data
45 an ..76 Track 1 data
46 an …999 Additional data – ISO
47 an …999 Additional data – national
48 an …999 Additional data – private
49 an 3 Currency code, transaction
50 an 3 Currency code, settlement
51 an 3 Currency code, cardholder billing
52 b 64 Personal identification number data
53 n 18 Security related control information
54 an …120 Additional amounts
55 ans …999 Reserved ISO
56 ans …999 Reserved ISO
57 ans …999 Reserved national
58 ans …999 Reserved national
59 ans …999 Reserved for national use
60 an .7 Advice/reason code (private reserved)
61 ans …999 Reserved private
62 ans …999 Reserved private
63 ans …999 Reserved private
64 b 16 Message authentication code (MAC)
65 b 64 *Bit indicator of tertiary bitmap only*, tertiary bitmap data follows secondary in message stream.
66 n 1 Settlement code
67 n 2 Extended payment code
68 n 3 Receiving institution country code
69 n 3 Settlement institution country code
70 n 3 Network management information code
71 n 4 Message number
72 ans …999 Data record (ISO 8583:1993)/n 4 Message number, last(?)
73 n 6 Date, action
74 n 10 Credits, number
75 n 10 Credits, reversal number
76 n 10 Debits, number
77 n 10 Debits, reversal number
78 n 10 Transfer number
79 n 10 Transfer, reversal number
80 n 10 Inquiries number
81 n 10 Authorizations, number
82 n 12 Credits, processing fee amount
83 n 12 Credits, transaction fee amount
84 n 12 Debits, processing fee amount
85 n 12 Debits, transaction fee amount
86 n 15 Credits, amount
87 n 15 Credits, reversal amount
88 n 15 Debits, amount
89 n 15 Debits, reversal amount
90 n 42 Original data elements
91 an 1 File update code
92 n 2 File security code
93 n 5 Response indicator
94 an 7 Service indicator
95 an 42 Replacement amounts
96 an 8 Message security code
97 n 16 Amount, net settlement
98 ans 25 Payee
99 n ..11 Settlement institution identification code
100 n ..11 Receiving institution identification code
101 ans 17 File name
102 ans ..28 Account identification 1
103 ans ..28 Account identification 2
104 ans …100 Transaction description
105 ans …999 Reserved for ISO use
106 ans …999 Reserved for ISO use
107 ans …999 Reserved for ISO use
108 ans …999 Reserved for ISO use
109 ans …999 Reserved for ISO use
110 ans …999 Reserved for ISO use
111 ans …999 Reserved for ISO use
112 ans …999 Reserved for national use
113 n ..11 Authorizing agent institution id code
114 ans …999 Reserved for national use
115 ans …999 Reserved for national use
116 ans …999 Reserved for national use
117 ans …999 Reserved for national use
118 ans …999 Reserved for national use
119 ans …999 Reserved for national use
120 ans …999 Reserved for private use
121 ans …999 Reserved for private use
122 ans …999 Reserved for private use
123 ans …999 Reserved for private use
124 ans …255 Info text
125 ans ..50 Network management information
126 ans …999 Issuer trace id
127 ans …999 Reserved for private use
128 b 16 Message authentication code 


Implementation and understanding the Code


The first step to understanding the packing and unpacking of the message fields would be to create a class that describes then entire structure.


First we create a class and create a dictionary that describes the message formats:


 #2805 contants
 _DEF = {}
 # Every _DEF has:
 # _DEF[N] = [X, Y, Z, W, K]
 # N = bitnumber
 # X = smallStr representation of the bit meanning
 # Y = large str representation
 # Z = length indicator of the bit (F, LL, LLL, LLLL, LLLLL, LLLLLL)
 # W = size of the information that N need to has
 # K = type os values a, an, ans, n, xn, b
 _DEF[1] = ['BM', 'Bit Map Extended', 'F', 8, 'b']
 _DEF[2] = ['2', 'Primary Account Number (PAN)', 'LL', 19, 'n']
 _DEF[3] = ['3', 'Processing Code', 'F', 6, 'n']
 _DEF[4] = ['4', 'Amount Transaction', 'F', 12, 'n']
 _DEF[5] = ['5', 'Amount Settlement', 'F', 12, 'n']
 _DEF[7] = ['7', 'Transmission Date and Time', 'F', 10, 'n']
 _DEF[9] = ['9', 'Conversion Rate, Settlement', 'F', 8, 'n']
 _DEF[10] = ['10', 'Conversion Rate, Cardholder Billing', 'F', 8, 'n']
 _DEF[11] = ['11', 'Systems Trace Audit Number', 'F', 6, 'n']
 _DEF[12] = ['12', 'Time, Local Transaction', 'F', 6, 'n']
 _DEF[13] = ['13', 'Date, Local Transaction', 'F', 4, 'n']
 _DEF[14] = ['14', 'Date, Expiration', 'F', 4, 'n']
 _DEF[15] = ['15', 'Date, Settlement', 'F', 4, 'n']
 _DEF[16] = ['16', 'Date, Conversion', 'F', 4, 'n']
 _DEF[18] = ['18', 'Merchant Type', 'F', 4, 'n']
 _DEF[22] = ['22', 'POS Entry Mode', 'F', 3, 'n']
 _DEF[23] = ['23', 'Card Sequence Number', 'F', 3, 'n']
 _DEF[25] = ['25', 'POS Condition Code', 'F', 2, 'n']
 _DEF[28] = ['28', 'Amount, Transaction Fee', 'F', 9, 'xn']
 _DEF[32] = ['32', 'Acquiring Institution ID Code', 'LL', 11, 'n']
 _DEF[33] = ['33', 'Forwarding Institution ID Code', 'LL', 11, 'n']
 _DEF[35] = ['35', 'Track 2 Data', 'LL', 37, 'an']
 _DEF[37] = ['37', 'Retrieval Reference Number', 'F', 12, 'an']
 _DEF[38] = ['38', 'Authorization ID Response', 'F', 6, 'an']
 _DEF[39] = ['39', 'Response Code', 'F', 2, 'an']
 _DEF[41] = ['41', 'Card Acceptor Terminal ID', 'F', 8, 'ans']
 _DEF[42] = ['42', 'Card Acceptor ID Code', 'F', 15, 'ans']
 _DEF[43] = ['43', 'Card Acceptor Name Location', 'F', 40, 'asn']
 _DEF[44] = ['44', 'Additional Response Data', 'LL', 25, 'ans']
 _DEF[47] = ['47', 'Additional Data National', 'LLL', 999, 'ans']
 _DEF[48] = ['48', 'Additional Data Private', 'LLL', 999, 'ans']
 _DEF[49] = ['49', 'Currency Code, Transaction', 'F', 3, 'n']
 _DEF[50] = ['50', 'Currency Code, Settlement', 'F', 3, 'n']
 _DEF[51] = ['51', 'Currency Code, Billing', 'F', 3, 'n']
 _DEF[52] = ['52', 'PIN Data', 'F', 8, 'b']
 _DEF[53] = ['53', 'Security Related Control Information', 'F', 48, 'b']
 _DEF[55] = ['55', 'ICC Data', 'LLL', 999, 'b']
 _DEF[57] = ['57', 'Amount Cash', 'F', 12, 'n']
 _DEF[58] = ['58', 'Ledger Balance', 'F', 12, 'n']
 _DEF[59] = ['59', 'Account Balance', 'F', 12, 'n']
 _DEF[64] = ['64', 'Message Authentication Code', 'F', 8, 'b']
 _DEF[66] = ['66', 'Settlement Code', 'F', 1, 'n']
 _DEF[70] = ['70', 'Network Management Information Code', 'F', 3, 'n']
 _DEF[74] = ['74', 'Credits, Number', 'F', 10, 'n']
 _DEF[75] = ['75', 'Credits, Reversal Number', 'F', 10, 'n']
 _DEF[76] = ['76', 'Debits, Number', 'F', 10, 'n']
 _DEF[77] = ['77', 'Debits, Reversal Number', 'F', 10, 'n']
 _DEF[78] = ['78', 'Transfer, Number', 'F', 10, 'n']
 _DEF[79] = ['79', 'Transfer, Reversal Number', 'F', 10, 'n']
 _DEF[80] = ['80', 'Inquiries, Number', 'F', 10, 'n']
 _DEF[81] = ['81', 'Authorizations, Number', 'F', 10, 'n']
 _DEF[83] = ['83', 'Credits, Transaction Fee Amount', 'F', 12, 'n']
 _DEF[85] = ['85', 'Debits, Transaction Fee Amount', 'F', 12, 'n']
 _DEF[86] = ['86', 'Credits, Amount', 'F', 16, 'n']
 _DEF[87] = ['87', 'Credits, Reversal Amount', 'F', 16, 'n']
 _DEF[88] = ['88', 'Debits, Amount', 'F', 16, 'n']
 _DEF[89] = ['89', 'Debits, Reversal Amount', 'F', 16, 'n']
 _DEF[90] = ['90', 'Original Data Elements', 'F', 42, 'n']
 _DEF[97] = ['97', 'Amount, Net Settlement', 'F', 17, 'xn']
 _DEF[99] = ['99', 'Settlement Institution ID Code', 'LL', 11, 'n']
 _DEF[100] = ['100', 'Receiving Institution ID Code', 'LL', 11, 'n']
 _DEF[112] = ['112', 'Key Management Data', 'LLL', 999, 'b']
 _DEF[118] = ['118', 'Cash Total Number', 'LLL', 10, 'n']
 _DEF[119] = ['119', 'Cash Total Amount', 'LLL', 10, 'n']
 _DEF[128] = ['128', 'MAC Extended', 'F', 8, 'b']


To write this structure should not be that difficult and should come directly out of the specification provided my your institution.


As for the infamous bitmaps we are going to describe a structure for them as well, with an array to track the bit positions.


 #Attributes
 # Bits to be set 00000000 -> _BIT_POSITION_1 ... _BIT_POSITION_8
 _BIT_POSITION_1 = 128 # 10 00 00 00
 _BIT_POSITION_2 = 64 # 01 00 00 00
 _BIT_POSITION_3 = 32 # 00 10 00 00
 _BIT_POSITION_4 = 16 # 00 01 00 00
 _BIT_POSITION_5 = 8 # 00 00 10 00
 _BIT_POSITION_6 = 4 # 00 00 01 00
 _BIT_POSITION_7 = 2 # 00 00 00 10
 _BIT_POSITION_8 = 1 # 00 00 00 01

 #Array to translate bit to position
 _TMP = [0, _BIT_POSITION_8, _BIT_POSITION_1, _BIT_POSITION_2, _BIT_POSITION_3, _BIT_POSITION_4, _BIT_POSITION_5,
 _BIT_POSITION_6, _BIT_POSITION_7]
 _EMPTY_VALUE = 0


Now we simply add a heap of helper functions from  http://www.vulcanno.com.br/python/ISO8583.html to fill and decode the data structure.


I have created a client and a server as part of the source code, so you can test your own implementation of the AS2805 protocol


Simple as pie!


 


 

	


	





	

		
Dynamic Key Exchange Models
	


	
	

		
Dynamic Key Exchange Models






I’ve had a number of people ask me recently about how to implement Dynamic Key Exchange models.  Specifically, I’m talking here about ISO8583-based financial payment gateways.  This post pertains to situations where you’re acting either as the Card Issuer (in which case you’re receiving payment transaction requests from the gateway) or the transaction acquirer (in which case you’re sending payment transaction requests to the gateway in order that they route it for appropriate authorization decisioning).


There’s some terminology to square away first:


Local Master Key (‘LMK’) – This is the key you store in the HSM in order to encrypt and do software-based storage of the current Working Keys (and Base Derivation Keys if you’re using DUKPT).  Also called the Master File Key (‘MFK’)


Zone PIN Key (‘ZPK’) – The ZPK is what’s used to encrypt the PIN blocks that traverse the wires between institutions.  Also referred to as the ‘Working Key.’  This is the key that the Dynamic Key Exchange is acting upon.  You’re obligated to change the Working Key at agreed-upon intervals (I typically advocate every 12 hours).


Zone Master Key (‘ZMK’) –  Think of the ZMK as the key transportation vehicle.  It’s the key that the two parties use to encrypt and exchange new ZPKs.  This key is established via a key ceremony.  You keep a copy of the ZMK encrypted under the LMK in a file somewhere (you’ll see how it’s used here further down this post).  Also called the Key Exchange Key (‘KEK’).


    

  1. From the moment you start planning discussions with the gateway, establish RIGHT AWAY that you want field-by-field level specifics of how the Dynamic Key Exchange is to be performed.  It’ll be within the context of some  Network Message Exchange (e.g., 0800/0810), but that’s not granular enough – you need to know the thing down to the field-content level.
    2. 

  2. Scour the documentation you’ve been provided to see if those details are in there.  I’ve done two different gateway projects recently, and in both cases the Key Exchange details were notably absent from the doc.  But, that doc exists somewhere within the gateway institution.  Track it down.  Get your hands on it.
    3. 

  3. Knowledge of the Key Exchange model is – by design – not widespread throughout the gateway provider’s project personnel.  Insist on getting their expert in on at least one of the planning calls.  Make note of this person’s name and contact details.  Establish that information channel.  This is a critically important point to your success.
    4. 



At a high level, there are two models:


    

  • You request a new ZPK from the gateway, and they provide it in the response.  [I call this the ‘Pull‘ model (for obvious reasons – you pull the key from them).]
    • 

  • The gateway sends you a new ZPK and you respond with a message indicating success or failure.  [This, by contrast is the ‘Push‘ model.]
    • 



Your implementation will be one of those.


Now, I’ll provide two examples, one push, one pull.


The sequence of events is:


    

  1. The gateway sends us a new ZPK (under ZMK) in an 0800 (MTI) Network Request.
    2. 

  2. We obtain the ZMK (under LMK) from our files.
    3. 

  3. We use the cryptograms from Steps 1 and 2 to create the appropriate command to the Key-Up (here, a ’12’)
    4. 

  4. We get the response from the Key-Up (the ’13’) and validate that the Check Digits match those provided by the Issuer.
    5. 

  5. Assuming the check in Step 4 is okay, we store the result (the ZPK under LMK) as the new Working Key.
    6. 

  6. We send an 0810 (MTI) Network Response back to the Issuer (Note that Field 39 on our response is ’00’ – indicating success).
    7. 



There’s so much detail here worthy of comment.  I’ll touch on a few things (these are the types of detail you want to bring to the surface in your reviews):


    

  • This gateway uses ‘162’ in Field 70 to tip to us that it’s a Key Exchange in play.
    • 

  • Note how we have to pluck the incoming cryptogram out of the esoteric morass of Field 123.
    • 

  • We have to construct an equally cryptic Field 123 on our response.
    • 



 


Here is the pull model:


    

  1. We request a new key from the Gateway in an 0800.
    2. 

  2. The new key (ZPK under ZMK) comes back in an 0810.
    3. 

  3. We fire off an ‘FA’ to the Thales 8000.
    4. 

  4. We get the ‘FB’ back and validate the check digits.
    5. 

  5. If okay, we store the result (the ZPK under LMK) as the new Working Key.
    6. 



Now, since we’re the initiator here we have to have a way to determine when to trigger the exchange request.  We do that through a channel Logon Manager.


You get the idea, I hope!  Nail down all those details in order to maximize your chances of success.  Otherwise, feel free to beat your head against a wall, because that’s what will happen if you don’t get this information.





	


	





	

		
Doing PIN Translation with DUKPT
	


	
	

		
On PIN-enabled Debit/EBT transactions sent in from an acquirer’s point-of-sale location, your payment switch application must perform a PIN translation, typically transforming an incoming DUKPT PIN block from the POS device-initiated request into a outgoing Triple DES-encrypted PIN block that makes use of an established Zone PIN Key (“ZPK”) which would have been previously established via a dynamic key exchange with your Debit/EBT gateway provider.




[The remainder of this example assumes you’re using a Thales (formerly Racal) Hardware Security Module (“HSM”)….] Using strict Thales parlance, this variant of a PIN translation request is a request to “translate a PIN from *BDK encryption to interchange key encryption.”  This topic is covered in Section 27.2 (page 2-185) of the Thales reference document entitled “Host Security Module RG7000 Programmer’s Manual” (Thales reference number 1270A514 Issue 5). The CI/CJ exchange should be handled as follows: — CI — Message header – You can use as you see fit. Value is echoed back in CJ.  Note that the length is constant and must be configured in HSM by administrator. Command code – CI BDK – The Base Derivation Key “in play” for this transaction.  In my installations we’ve set this up as follows…


    

  • Selected the “1A + 32H” option, where the ‘1A’ value should be set to ‘U’
    • 

  • Configured such that the first six positions of the KSN represent the “key name” of the BDK injected into the PIN Pad at the transaction origination point (an acquirer can use a number of BDKs in their terminal population).
    • 



ZPK – Your current ZPK Cryptogram (obtained dynamically via a key exchange with your Debit/EBT  gateway partner) and stored under your Local Master Key (“LMK”).  In my installations, we’ve used the “1A + 32H” option, where the ‘1A’ value should be set to ‘U’. KSN Descriptor – This value is a bit esoteric and refers directly to the make-up of the KSN which follows.  So to understand the descriptor, it’s first necessary to talk a bit about the KSN (the next field in the CI command layout).  Here’s a typical KSN implementation where the acquirer has chosen a 16-position scheme:


    

  • Positions 1 – 6: The name of the BDK injected into this device
    • 

  • Positions 7 – 11:  The device ID
    • 

  • Positions 12 – 16: The transaction counter
    • 



[Note that the KSN implementation has to be in synch between the PIN pad and your host-side implementations in order for this to work.] The ‘rules’ for a KSN construction are as follows (reading from left to right in the KSN): a. The ‘base derivation key identifier,’ which is mandatory and five to nine (Hex) positions in length. b. A ‘sub-key identifier,’ which Thales says is ‘optional’ but in practice is ‘reserved for future use’ (and therefore always set to zero). c. A ‘device identifier’ (mandatory), which is two to five Hex digits in length. d. A ‘transaction counter’ (mandatory) which essentially is the part “left over”. So, in the example here, the client with a 6, 0, 5, 5 implementation. With this information in hand, the KSN Descriptor (a three-position value) is better described as XYZ, where: X = base derivation key identifier length Y = sub-key identifier key length (will be zero) Z = device identifier length So, in this context, the ‘605’ submitted in my example is better visualized. ‘605’ says that the 16-digit KSN consists of a 6-position BDK ID, a 0-position sub-key, a 5-position device ID, **AND** (what’s remaining basically) a 5-position transaction counter. [NOTE: Remember that this post applies *specifically* to the Thales/RACAL implementation of PIN translation] Now, with this informatation in hand, we can introduce the next field, the KSN itself… KSN – Using the layout from the descriptor, a typical KSN at this acquirer might be 123456000A8001D4 where: ‘123456’ is the BDK indentifier; ‘000A8’ is the Device ID; and ‘001D4’ is the transaction counter. The BDK name embedded in a particular KSN string must find a match within your BDK cryptogram list (which you need to keep loaded into your payment switch’s encryption database).  If a match is not found in the encryption database, then set your Internal Result Code to “Invalid BDK” and end the transaction.  If found, the value you retrieve goes into the BDK field (as described above). Source encrypted block – The PIN block plucked from the POS device request (this is a 16H value; no ‘1A’ indicator is required). Destination PIN block – In my installations, we typically use ANSI format, so we set this to ‘01’ to signify ANSI format code Account Number – Right-most 12 positions of the PAN excluding the check digit Typically, that is the END of the required CI request message (remainder of the fields in the Thales spec are not mandatory). — CJ —  Message header – Echoed back from CI usage. Response code – CJ Error Code – Only ‘00’ should be accepted as an exchange that “worked.” PIN length – Although this field is not used to build the 0200 message formatted for your Debit/EBT gateway, a value like ‘04’ or ‘05’ here are a pretty good indication that the translation occurred successfully. Encrypted PIN – The PIN block that will be used to build the 0200 message formatted for your Debit/EBT gateway (this is a 16H value; no ‘1A’ indicator is required). Destination PIN block – Echoed back from the device as ’01’ format code Typically, that is the END of the response message (remainder of list in the vendor spec would only be present if they were provided in the CI command request)