> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/adk_programming_interfaces/pg_vss_documentation/vss_documentation.md). # VeriShield Security Scripts (VSS) ## VeriShield Security Scripts (VSS) ## Introduction ### Purpose This document is to describe VeriShield Security Scripts (VSS), a system that provides security modules with enough flexibility to support different key management schemes, such as triple-DES for master and session keys, offline PIN verifications, Australian AS2806 part 6, Canadian Interac, Semp/4B, and APACS40. This document applies to security modules that implement VSS in programmable and non-programmable devices. ### Organization This guide is organized as follows: * [General Overview](#sec_vss_overview). Provides an overview of the VeriShield Security Scripts. * [Write a Security Script](#sec_vss_write). Describes the principles, keywords, instructions and macrocommands used to create a Security Script. * [Macro Command Execution](#sec_vss_macro_command_execution). Explains how the macro scripts of PINpads and terminals are executed. * [Tools](#sec_vss_tools). Discusses the tools such as the Script Processor, Signing Tool and the Key Loading tools used in PINpads and terminals. * [VSS Key Installation APIs](#sec_vss_loading_apis). Describes the APIs available to install VSS keys. * [Appendix A: OP Code Table](#sec_vss_appendix_a), Displays the opcode table,which identifies the opcode value for all the keywords that might generate an execution error. * [Appendix B: VSS Troubleshooting Guide](#sec_vss_appendix_b). Describes frequent VSS issues and how to resolve them To learn more about the VeriShield Security Scripts please refer to the following documents and their associated Verifone Part Numbers (VPN): \*\[Ref 3] - SPRD - SC552 Croatia - Revision 1.3 VDN 06199 - PINpad 1000 Plus -- Technical Specification Document VDN 15299 - Generic Personalization I for Mars V1 - Technical Specifications VDN 15471 - Most Commonly Used PIN Blocks VDN 19322 - Secure Macros for PEDguard Internal PINpad \* ## Overview In the default configurations, the most Verifone PINpads and terminals support only two key management schemes: DUKPT and Master/Session. The two schemes meet the needs of most of the customers and as they are hard-coded, customizing the security module is not required. For customers who need more flexibility, the VeriShield Security Script mechanism provides support for: Different key management schemes. * Different PIN block formats such as PVV, CVV IBM3624. * Additional key space. * Different encryption algorithms such as triple-DES, AES, RSA. All the information is written in a Security Script file (ASCII) using a VSS extension. This script is processed by a PC tool and converted into a downloadable binary file with a VSO extension. The download is protected by the VeriShield File Authentication (FA) module. Therefore, the Security Script file should be downloaded along with its signature file generated by the VeriShield File Signature Tool (FST). ![Figure 1 Security Script Process](/files/V6E8mb0tWTkjHcSPv5hq) The certificate used for FA must have VeriShield Security Scripts enabled for the GID in which the script is loaded. VeriShield Security Scripts have a special flag in the certificate for each GID. So, if a sponsor certificate is loaded and a secure script is to be loaded, it can only go into a GID permitting script. Writing the script does not require any specific development environment besides the script processor tool. Application development teams will develop the scripts. The Sponsor of the PINpad will have the responsibility of auditing and signing the Security Script. Two documents should always come along with a Security Script. The first one is the support document for the security audit. The second one is the user's manual for the application developers. Up to eight, 64 for VSS v5.0 and higher, 96 for VSS v8.0 and higher, 192 for VSS v9.0 and higher Security Scripts can be installed in the target unit at the same time. Each script defines its independent key space and whether or not those keys can be loaded using the generic key loading functions `iPS_LoadMasterClearKey()` and `iPS_LoadMasterEncKey()`. When using those generic functions, the loading of keys in the clear must be done in a unique session, because all the keys loaded in the previous session are erased. If the generic functions are not used, then the Security Script must define specific macro commands dedicated to the key loading. The Security Script commands are based on the concept called SMCL (Security Module Control Language) used in SC5xx PINpad in Sweden, Germany, Poland, etc. The idea is to have flexibility inside the security module without compromising the security. The PINpad provides a small interpreter that is used to: * Handle the key derivation process for a transaction. * Handle the key exchange process (store a key after decrypting it with another key). * Handle the PIN encryption process to account for different algorithms. * Provide enough support to handle specific key management schemes. The main difference with the SMCL is that the Security Script commands are protected by VeriShield instead of the secure commands, as we know them in the SC5xx PINpads. In PINpads and terminals, the whole set of commands are signed and downloaded into the PINpad before deployment, whereas SMCL commands are individually signed and sent to the security module at the time of execution. Each Security Script macro command is a group of elementary operations that cannot be executed individually for security reasons. A chaining mechanism can be used to force the execution of the macros in a pre-defined sequence. This can be useful to ensure the key separation and key hierarchy, for instance, enforcing successive derivations of a key before usage or preventing key misusage when a same block can hold different type of keys(MAC key, PIN key, PVV key, etc.). Generally, the macros will perform operations at a level high enough that no chaining should be necessary. ## Write a Security Script This section describes the principles, keywords, instructions and macro commands used to create a Security Script. ### Principle The Security Script is written using a predefined set of keywords that will be processed by the PC tool. The script contains three sections: * The configuration section that contains the identifier and the name of the script and optional restrictions on some of the generic key management functions of the PINpad/terminal API. For instance, the script can disable the default Master/ Session mode or DUKPT modes in order to implement a specific key management scheme that must not co-exist with the default ones. * The block definition that section defines the number of 8-byte blocks required for the Security Script to run. It also indicates which of those can be loaded using the default master key loading functions. The actual allocation in memory occurs when the script is downloaded in the PINpad. You can also specify a default value for each block (default key or default password). The value is written in the block right after the block allocation in memory during the script loading process.

Since the script file is not encrypted, there are serious security concerns: This feature is provided to anticipate specific requests but should not be used.

* The macro definition section contains the macro command implementation. The Security Script macro commands provide high-level functionality by executing a sequence of low-level sensitive cryptographic operations. At the macro command level, the functionality must be high enough that any misuse of a command does not compromise the security of the system or the customer's PIN. The macro commands can be chained using the mechanism inherited from the SC5xx PINpads' secure commands. Here is a description of the memory available and accessible using the VSS: * 255 8-byte locations for key/password/data storage * working registers (A, B0, B1) (8-byte long) * 1 current key location (CK) used for DES/AES computations (32-byte long) * 1 initialization vector for DES/AES operations in CBC mode (16-byte long) * 1 single byte index register (X) * 1 521-byte communication buffer (CB) * 1 521-byte working buffer (W) used for RSA computations * 1 20-byte SHA-1 buffer for storage purpose ![Figure 2 General Overview of the Security Script Engine](/files/iVDD95t2IyJkEZmao6yh) ![Figure 3 Additional OP Codes for RSA and SHA Support](/files/E3FskOpPnWbrKoQe2cE7) Register A is the center of the cryptographic engine. Only A (and W for RSA/SHA operations) can exchange data with the communication buffer, block locations and temporary registers B0 and B1. All logical operations and algorithm computations are performed on A. X is a single byte index register used as a pointer on a block location. B0 and B1 are used for storing temporary values. Registers A, B0, B1, CK and X are erased at the end of each macro execution. If a current key needs to be retained, then it must be stored into a block location. The Initialization vector (IV) is retained between the two macro executions. ### List of Keywords Here is the list of keywords and commands available for writing a script. | | | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Mnemonic | Description | | SUBDEV ID |

Script Identifier, i.e.
sub-device number (0 to 7) or
(0 to 63) in VSS version 5.0 and higher or
(0 to 95) in VSS version 8.0 and higher or
(0 to 191) in VSS version 9.0 and higher.
The macro commands defined in this script will be executed by calling the ExecuteScript(id,...) function.

| | SCRIPT name | Script Name must be 8 ASCII char long. This name will then be returned by the GetScriptStatus() function. | | PP1000\_OFF | Ignored. | | MS\_OFF | Disable default Master/Session support functions (GP1-like). Used in SC 5000. Ignored in Vx terminals. | | DUKPT\_OFF | Disable default DUKPT support functions. Used in SC 5000. Ignored in Vx terminals. | : Table 1 Configuration Section | | | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Mnemonic | Description | | DEF\_BLK | Allocate total Nb blocks when loading the script. Only the blocks. | | totalNb | From `#0` to `#(loadableNb-1)` can be loaded using the default key. | | loadableNb | Loading functions. | | RETAIN\_BLK | Does not erase the block values when upgrading a script. For v6.0 and higher- can also use fixed retain block value of ASCII Hex value of the name of the previous script. This requires. | | code | Presentation of a code=DES \[KLK xor (NAME\|NAME)]\(NAME) where NAME is the name of the previous script (see keyword SCRIPT). | | LD\_BLK index | Load a default value into the block `#index` when installing the script. | | value | In the unit. | : Table 2 Key Definition Section *** Mnemonic Description \*\*Entry point & initial tests\*\* MACRO number Define a macro command (entry point) SID curr next err Define the State Identifiers used for the chaining mechanism (current to be tested, next if execution is successful and error if execution fails) LENGTH nb Test the length of the input data received in the communication buffer (CB) \*\*Input/Output operations\*\* GETA offset Copy 8 byte from CB+offset into A \*OP codes labeled (v2.0+) are only available in version 2.0 of the VSS interpreterand higher. OP codes labeled (v4.0+) are only available in version 4.0 of the VSS interpreterand higher.\* GETA\_HA\_TO\_BIN offset (v2.0) Copy 16 bytes from CB+offset, convert from Hex ASCII ('0'-'9', 'A'-'F', 'a'-'f') to Binary and put 8 bytes into A SENDA offset Copy A into CB+offset SENDA\_BIN\_TO\_HA offset (v2.0+) Copy A, convert from Binary to Hex ASCII ('0'-'9', 'A'-'F'), and put 16 bytes into CB+offset GETX offset Copy 1 byte from address CB+offset into index register X GETX\_HA\_TO\_BIN offset (v2.0+) Copy 2 bytes from address CB+offset, convert from Hex ASCII ('0'-'9', 'A'-'F', 'a'-'f') to Binary, and put 1 byte into index register X SENDX offset Copy index register X at address CB+offset SENDX\_BIN\_TO\_HA offset (v2.0+) Copy index register X, convert from Binary to Hex ASCII ('0'-'9', 'A'-'F'), and put 2 bytes into CB+offset \*\*Index Register Handling\*\* INCX Increment index register X DECX Decrement index register X ADDXI value Add immediate value to index register X LDXI value Load index register X with an immediate value MOV\_A\_X Copy the first byte of register A into index register X MOV\_X\_A Copy the content of index register X into first byte of register A TSTXI min max Verify that X is in the range \\\[min..max\\], exit on error if it fails TSTXI\_BOR min max Label (v2.0+) Verify that X is in the range \\\[min..max\\], branch to Label if out of range \*\*8-bytes register handling\*\* CLRA Clear register A to all 0x00 SETA Set register A to all 0xFF RNDA Get a random number into A LDAI value Load A with an 8-byte immediate value (mask, variant...) MOV\_A\_B0 Copy A -\\> B0 MOV\_A\_B1 Copy A -\\> B1 MOV\_B0\_A Copy B0 -\\> A MOV\_B1\_A Copy B1 -\\> A MOV\_A\_IV Copy A -\\> IV (Set A as IV) MOV\_IV\_A Copy IV -\\> A (Get the IV into A) CLRIV Clear the Initialization Vector (Copy 0 -\\> IV) SELECTA Select A as current key (Copy A -\\> CK) SELECT index Select key \`#index\` as current key (Copy key \`#index\` -\\> CK) \*OP codes labeled (v2.0+) are only available in version 2.0 of the VSS interpreter and higher. OP codes labeled (v4.0+) are only available in version 4.0 of the VSS interpreter and higher.\* SELECTX Select key pointed by register X as current key (Copy key \`#\*X\` -\\> CK) \*\*Block handling (storage)\*\* STA index Copy A -\\> Slot \`#index\` STAX Copy the content of register A into the slot pointed by register X LDA index Copy Slot \`#index\` -\\> A LDAX Copy the content of slot pointed by register X into register A DELETE from to Invalidate Slots from \`#from\` to \`#to\` DELETEX Invalidate the Slot pointed by register X \*\*Logical operations\*\* XORA\_By XOR A with B0/1, result in A ANDA\_By AND A with B0/1, result in A ORA\_By OR A with B0/1, result in A LSLA nb Logical shift left A (nb bits) LSRA nb Logical shift right A (nb bits) COMA Complement A INCA Increment register A DECA Decrement register A ADJ\_EVEN Adjust the parity of every byte in register A to be even. ADJ\_ODD Adjust the parity of every byte in register A to be odd. CHK\_EVEN Check that the parity of every byte in register A is even, exit on error if it fails CHK\_EVEN\_BNE Label (v2.0+) Check that the parity of every byte in register A is even, if not, branch to Label CHK\_ODD Check that the parity of every byte in register A is odd, exit on error if it fails CHK\_ODD\_BNO Label (v2.0+) Check that the parity of every byte in register A is odd, if not, branch to Label \*\*Comparisons\*\* CMPA\_By Compare A with register B0/1, exit on error if it fails CMPA\_By\_BEQ Label (v2.0+) Compare A with register B0/1, if A = By, branch to Label CMPA\_By\_BNE Label (v2.0+) Compare A with register B0/1, if A != By, branch to Label CMPA\_By\_BGT Label (v2.0+) Unsigned compare A with register B0/1, if A \\> By, branch to Label CMPA\_By\_BLT Label (v2.0+) Unsigned compare A with register B0/1, if A \\< By, branch to Label \*OP codes labeled (v2.0+) are only available in version 2.0 of the VSS interpreter and higher. OP codes labeled (v4.0+) are only available in version 4.0 of the VSS interpreter and higher.\* CMPA\_By\_BGE Label (v2.0+) Unsigned compare A with register B0/1, if A \\>= By, branch to Label CMPA\_By\_BLE Label (v2.0+) Unsigned compare A with register B0/1, if A \\<= By, branch to Label CMPA index Compare A with Slot \`#index\`, exit on error if it fails CMPA\_BEQ index Label (v2.0+) Compare A with Slot \`#index\`, if A = Slot \`#index\`, branch to Label CMPA\_BNE index Label (v2.0+) Compare A with Slot \`#index\`, if A != Slot \`#index\`, branch to Label CMPA\_BGT index Label (v2.0+) Unsigned compare A with Slot \`#index\`, if A \\> Slot \`#index\`, branch to Label CMPA\_BLT index Label (v2.0+) Unsigned compare A with Slot \`#index\`, if A \\< Slot \`#index\`, branch to Label CMPA\_BGE index Label (v2.0+) Unsigned compare A with Slot \`#index\`, if A \\>= Slot \`#index\`, branch to Label CMPA\_BLE index Label (v2.0+) Unsigned compare A with Slot \`#index\`, if A \\<= Slot \`#index\`, branch to Label CMPAX Compare A with Slot pointed by register X, exit on error if it fails CMPAX\_BEQ Label (v2.0+) Compare A with Slot pointed by register X, if A = Slot pointed by register X, branch to Label CMPAX\_BNE Label (v2.0+) Compare A with Slot pointed by register X, if A != Slot pointed by register X, branch to Label CMPAX\_BGT Label (v2.0+) Unsigned compare A with Slot pointed by register X, if A \\> Slot pointed by register X, branch to Label CMPAX\_BLT Label (v2.0+) Unsigned compare A with Slot pointed by register X, if A \\< Slot pointed by register X, branch to Label CMPAX\_BGE Label (v2.0+) Unsigned compare A with Slot pointed by register X, if A \\>= Slot pointed by register X, branch to Label CMPAX\_BLE Label (v2.0+) Unsigned compare A with Slot pointed by register X, if A \\<= Slot pointed by register X, branch to Label BRA Label (v2.0+) Branch to Label \*\*DES/AES operations\*\* ALGO\_name Select the algorithm for the following computations.\ ALGO\_name can take the values DES56, DES112, DES168, AES128, AES192, AES256. EECB Encrypt (ECB) A with CK, result in A DECB Decrypt (ECB) A with CK, result in A ECBC Encrypt (CBC) A with CK, result in A DCBC Decrypt (CBC) A with CK result in A EECB\_CB offset length (v6.0+) Encrypt ECB, communication buffer starting at offset for length. EECB\_CB\_X offset (v6.0+) Encrypt ECB, communication buffer starting at offset for length in X. DECB\_CB offset length (v6.0+) Decrypt ECB, communication buffer starting at offset for length. DECB\_CB\_X offset (v6.0+) Decrypt ECB, communication buffer starting at offset for length in X. ECBC\_CB offset length (v6.0+) Encrypt CBC, communication buffer starting at offset for length. ECBC\_CB\_X offset (v6.0+) Encrypt CBC, communication buffer starting at offset for length in X. DCBC\_CB offset length (v6.0+) Decrypt CBC, communication buffer starting at offset for length. DCBC\_CB\_X offset (v6.0+) Decrypt CBC, communication buffer starting at offset for length in X. ```

Must clear IV before starting encryption/decryption for CBC.
Length must be a multiple of 8 bytes for DES and 16 bytes for AES, so data must be padded.
Must select algorithm and then key before execution of OP code.
Result in communication buffer.

``` \*\*PIN handling commands\*\* \*OP codes labeled (v2.0+) are only available in version 2.0 of the VSS interpreter and higher. OP codes labeled (v4.0+) are only available in version 4.0 of the VSS interpreter and higher.\* GETPINNB Get the number of PIN digits into the first (left) byte of A GETPIN0 Get PIN into A (from the left) - 1 nibble per digit GETPIN1 Get PIN into A (from the right) - 1 nibble per digit GETPIN2 Get PIN into A in ASCII - 1 byte at a time GETPIN3 Get PIN into A in "Smart card" format DECIM0 Decimalization type 0 (PVV & PAC Shell type) DECIM1 Decimalization type 1 (IBM3624Offset type) DECIM2 Decimalization type 2 (CCV type) OFFSET0 Offset function type 0 (A -B0 mod 10 -\\> A) OFFSET1 Offset function type 1 (CCV type 1) OFFSET2 Offset function type 2 (CCV type 2) \*\*SHA/RSA Operations\*\* CMPSHA Compare 20 bytes from W with SHA register CMPSHA\_BEQ Label (v2.0+) Compare 20 bytes from W with SHA register, if W = SHA, branch to Label CMPSHA\_BNE Label (v2.0+) Compare 20 bytes from W with SHA register, if W != SHA, branch to Label CMPSHA256 (v6.0+) Compare 32 bytes from W with SHA register CMPSHA256\_BEQ Label (v6.0+) Compare 32 bytes from W with SHA register, if W = SHA, branch to Label CMPSHA256\_BNE Label (v6.0+) Compare 32 bytes from W with SHA register, if W != SHA, branch to Label GETW offset len Copy len bytes from CB+offset into W GETW\_HA\_TO\_BIN offset len (v2.0+) Copy len (must be even) bytes from CB+offset, convert from Hex ASCII ('0'-'9', 'A'-'F', 'a'-'f') to Binary, and put len/2 bytes into W MOV\_A\_W Copy 8 bytes from A into W MOV\_W\_A Copy 8 bytes from W into A register RNDW (v2.0+) Fill W with random data RSACOMP Perform RSA computation on data in working buffer (W), result in working buffer (W) SELRSA index Select an RSA key for the next computation (0 to 3) SELRSAX Select the RSA key pointed by the content of register X. SENDW offset len Copy len bytes from W into CB+offset SENDW\_BIN\_TO\_HA offset len (v2.0+) Copy len bytes from W, convert from Binary to Hex ASCII (' '9', 'A'-'F'), and put len\\\*2 bytes into CB+offset SHA256INIT (v6.0+) Initialize SHA context for upcoming computation SHA256TERM (v6.0+) Get SHA result into W SHA256UPDATE len (v6.0+) Compute (SHA) len bytes from W SHAINIT Initialize SHA context for upcoming computation SHATERM Get SHA result into W SHAUPDATE len Compute (SHA) len bytes from W STRSA index Copy RSA key from W into slot \`#index\` (0 to 3) STRSAX Copy RSA key from W into the slot pointed by the content of register X (0 to 3) STSHA Copy 20 bytes from W into SHA register STSHA256 (v6.0+) Copy 32 bytes from W into SHA register \*OP codes labeled (v2.0+) are only available in version 2.0 of the VSS interpreter and higher. OP codes labeled (v4.0+) are only available in version 4.0 of the VSS interpreter and higher.\* \*\*DUKPT Commands\*\* INIT\_1DES\_DUKPT (v4.0+) Initialize Single DES DUKPT IKSN is the first 10 bytes of the CB IK is in register B0 INIT\_3DES\_DUKPT (v4.0+) Initialize Triple DES DUKPT IKSN is the first 10 bytes of the CB IKL is in register B0 IKR is in register B1 DELETE\_DUKPT\_KEY (v4.0+) Delete the DUKPT key GET\_DUKPT\_KEY (v4.0+) Get type/status, the KSN and the DUKPT FK Type/Status is in register X KSN is the first 10 bytes of the CB FK (1DES) or FKL (3DES) is in register B0 FKR (3DES) is in register B1 The OS will derive the next FK \*\*MAC Operations\*\* \*Added VSS op codes to MAC data in the VSS communication buffer.\* ALGO\_MAC00 (v6.0+) ISO 9797-1 MAC Algorithm 1 -- 56 Bits\ K is a single length key (VSS K1) ALGO\_MAC10 (v6.0+) ISO 9797-1 MAC Algorithm 1 -- 112 Bits\ K is a double length key (VSS K1 and K2) ALGO\_MAC20 (v6.0+) ISO 9797-1 MAC Algorithm 2 -- 112 Bits\ K is a single length key (VSS K1)\ K''' is a single length key (VSS K2) ALGO\_MAC20\_LAST (v6.0+) When the last block is MACed, do last block processing\ Can MAC, 1 or more blocks. ALGO\_MAC30 (v6.0+) ISO 9797-1 MAC Algorithm 3 -- 112 Bits\ K is a single length key (VSS K1)\ K' is a single length key (VSS K2) ALGO\_MAC30\_LAST (v6.0+) When the last block is MACed, do last block processing\ Can MAC, 1 or more blocks. ALGO\_MAC40 (v6.0+) Middle block processing ALGO\_MAC40\_FIRST (v6.0+) ISO 9797-1 MAC Algorithm 4 -- 112 Bits\ When the first block is MACed, do first block processing\ Can MAC, 1 or more blocks.\ K is a single length key (VSS K1)\ K'' is a single length key (VSS K1 XOR 0xF0F0F0F0F0F0F0F0)\ K' is a single length key (VSS K2) ALGO\_MAC40\_LAST (v6.0+) When the last block is MACed, do last block processing\ Can MAC, 1 or more blocks ALGO\_MAC50 (v6.0+) ISO 9797-1 MAC Algorithm 5 -- 56 Bits\ K1 is a single length key (VSS K1)\ K2 is a single length key (VSS K1 XOR 0xF0F0F0F0F0F0F0F0) ALGO\_MAC50\_LAST (v6.0+) When the last block is MACed, do last block processing\ Can MAC, 1 or more blocks ALGO\_MAC60 (v6.0+) ISO 9797-1 MAC Algorithm 5 -- 112 Bits\ K1 is a double length key (VSS K1 and K2)\ K2 is a double length key (VSS K1 XOR 0xF0F0F0F0F0F0F0F0)\ (VSS K2 XOR 0xF0F0F0F0F0F0F0F0) ALGO\_MAC60\_LAST (v6.0+) When the last block is MACed, do last block processing\ Can MAC, 1 or more blocks MAC\_CB offset length (v6.0+) MAC the data in the communication buffer starting at offset for length MAC\_CB\_X offset (v6.0+) MAC the data in the communication buffer starting at offset for length in X\ Must set or clear IV before start of MAC\ Must select algorithm and then key before execution of OP code\ Length must be a multiple of 8 bytes, so data must be padded\ Result in IV, all 8 bytes, data not truncated \*\*Padding Commands\*\* OAEP Encode message M in register W, result EM in register W (v7.0+) Decode message EM in register W, result M in register W CB - optional label L Register X - Encode/Decode Register A - OAEP options and lengths \*\*Exit Commands\*\* EOM length End of Macro - Delete register A, B0, B1, CK and X - Send to terminal length bytes of CB ERR\_RET length (v2.0+) Error Return from Macro - Delete register A, B0, B1, CK and X - Send to terminal length bytes of CB. This command will also have a non-zero return value (E\_VS\_ERR\_RET). This OP code can be used for returning custom errors or for debugging. The macro can place error or debug data in the CB to be returned to the application \*OP codes labeled (v2.0+) are only available in version 2.0 of the VSS interpreter and higher. OP codes labeled (v4.0+) are only available in version 4.0 of the VSS interpreter and higher.\* \------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ : Table 3 Macro Definition Section A macro performs some of the following actions: * Check the length of the data field received into the communication buffer using the LENGTH command * Copy the input data into the register A and index register X using GETA and GETAX commands * Perform logical and cryptographic operations on the working registers * Perform comparisons using CMPA commands * Copy the result into a block location using STA or into the communication buffer using the SENDA command * Erase the working registers and transmit the response packet using the EOM command ### Detailed Description of Keywords This section provides the description of the keywords used in the security scripts. #### Configuration Instructions | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SUBDEV id (Script number (Sub-Device Number), range is \[0..7]) | | Parameters |

id

\[0..63] in VSS version 5.0+

\[0..95] in VSS version 8.0+

\[0..191] in VSS version 9.0+

| | Operation |

VSS devices can have up to 8 scripts.

64 in VSS version 5.0+

96 in VSS version 8.0+

192 in VSS version 9.0+
This keyword defines in which of those 8 locations the script will be loaded.

64 in VSS version 5.0+

96 in VSS version 8.0+

192 in VSS version 9.0+
The script number is also used at execution time to select the script to execute from.

| | Comments | Macro commands defined in this file will be accessed using the `ExecuteScript()` function with the value id as first argument. | : Table 4 SUBDEV | | | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | Format | SCRIPT name (Identifier). Must be 8 ASCII characters. Should be unique per script (should contain a version number) | | Parameters | name | | Operation | This keyword is used to identify a script | : Table 5 SCRIPT | | | | --------- | -------------- | | Format | PP1000\_OFF | | Operation | None - Ignored | : Table 6 PP1000\_OFF | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | MS\_OFF | | Operation | This keyword disables Master/Session support. If at least one of the scripts loaded in the unit contains this keyword, the number of PIN and MAC M/S Master Keys is set to zero and the API functions are disabled (will return an error code). Used in SC 5000. Ignored in Vx terminals | : Table 7 MS\_OFF | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | DUKPT\_OFF | | Operation | This keyword disables all the DUKPT support. If at least one of the scripts loaded in the unit contains this keyword, the DUKPT keys are erased and the related API functions are disabled (return an error code). Used in SC 5000. Ignored in Vx terminals | : Table 8 DUKPT\_OFF #### Key Definition Instructions | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format |

DEF\_BLK total loadable Total number of 8-byte block that will be allocated.
total Range \[0..255]
loadable Number of blocks that will be loadable using the generic key loading functions. Range \[0..total]

| | Operation |

This keyword is used to define the block area.
Total blocks will be allocated at the time the script is installed in the unit. Out of those blocks only blocks #0 to #loadable-1 will be loadable using the generic API functions LoadMasterClearKey() and LoadMasterEncKey(). If loadable is greater than total, then the script loading will fail.

| : Table 9 DEF\_BLK | | | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | RETAIN\_BLK code | | | | Parameters | code (8-byte cryptogram) | | | | Operation |

This keyword is used to indicate that this script will use the same block definition as the script previously installed in the same slot and that the values in the blocks must be retained.
A code must be presented in order to authorize this operation.
The code is the result of the following computation that is based on KLK and the name of the previous script under KLK.
CODE = TDES \[KLK xor (NAME | NAME)]\(NAME) where:

NAME is the 8-character name of the script to be replaced

(NAME | NAME) is the concatenation of two NAMEs to form a 16-byte value that will be exclusive-or'd with KLK to form the double-length encryption key

CODE is the result of the triple-DES encryption of NAME under this key

Both scripts must use the same Sub-device number (SUBDEV id)

| | Example |

NAME = "A40\_V100" = 4134305F56313030
KLK = "0000000800000002" = 30303030303030383030303030303032
NAME | NAME = "A40\_V100A40\_V100" = 4134305F563130304134305F56313030
KEY = KLK XOR (NAME | NAME) = 7104006F660100087104006F66010002
CODE = TDES[KEY](https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/adk_programming_interfaces/pg_vss_documentation/NAME) = 3BD985379859818C
For v6.0 and higher - can also use fixed retain block value of ASCII Hex value of the name of the previous script.
Example:
Previous script name "A40\_V100" = 4134305F56313030

| : Table 10 RETAIN\_BLK | | | | ---------- | --------------------------------------------------------------------------------------------------------------------- | | Format | LD\_BLK index value | | Parameters |

index (Block location)
value (8-byte value to be loaded in the block)

| | Operation | This keyword is used to load a default value into the block `#index` at the time the script is installed in the unit. | : Table 11 LD\_BLK #### Macro Command Instructions | | | | ---------- | ---------------------------------------------------------- | | Format | ADDXI value | | Parameters | Value (One byte value) | | Operation | The immediate value is added to the single-byte register X | : Table 12 ADDXI | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

ADJ\_EVEN
ADJ\_ODD

| | Operation | Adjust the parity of each byte in the register A by changing the least significant bit (rightmost) of the byte. ADJ\_EVEN ensures there are even number of bits set to 1 in each byte. ADJ\_ODD ensures there are odd number of bits set to 1 in each byte | | Comments |

In versions 3.13 and earlier of the SC 5000 RAM OS, those two instructions do not work correctly: If one byte in the 8-byte buffer has the correct parity, then the remaining bytes in the buffer (on the right) will not get their parity adjusted. A temporary workaround in the script is to alternate 8 ADJ\_ODD and ADJ\_EVEN OP codes to make sure that the entire 8-byte buffer gets adjusted. For instance, in the script:
ADJ\_EVEN
should be replaced by
ADJ\_ODD
ADJ\_EVEN
ADJ\_ODD
ADJ\_EVEN
ADJ\_ODD
ADJ\_EVEN
ADJ\_ODD
ADJ\_EVEN

| : Table 13 ADJ\_EVEN / ADJ\_ODD | | | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

ALGO\_DES56
ALGO\_DES112
ALGO\_DES168
ALGO\_AES128
ALGO\_AES192

| | Parameters |

This instruction sets the algorithm and key length for the upcoming instructions in the same macro command.
ALGO\_DES56: simple DEA with simple-length key
ALGO\_DES112: triple-DEA with double-length key
ALGO\_DES168: triple-DEA with triple-length key
ALGO\_AES128: AES (Rijndael) with 128-bit key (128-bit data block)
ALGO\_AES192: AES (Rijndael) with 192-bit key (128-bit data block)
ALGO\_AES256: AES (Rijndael) with 256-bit key (128-bit data block)
This setting has an effect on the following instructions:
SELECT, SELECTA, EECB, DECB, ECBC, DCBC, MOV\_A\_IV, MOV\_IV\_A

| | Operation | The algorithm is reset to simple-DES (ALGO\_DES56) at the beginning of every macro command, this means, the setting is not retained between two macro command calls | : Table 14 ALGO\_DES56 / ALGO\_DES112 / ALGO\_DES168 / ALGO\_AES128 / ALGO\_AES192 / ALGO\_AES256 | | | | ---------- | --------------------------------------------------------------------------------- | | Format | ALGO\_MAC00 | | Parameters |

ISO 9797-1 MAC Algorithm 1 -- 56 Bits
K is a single length key (VSS K1)

| | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 15 ALGO\_MAC00 (v6.0+) | | | | ---------- | ----------------------------------------------------------------------------------------- | | Format | ALGO\_MAC10 | | Parameters |

ISO 9797-1 MAC Algorithm 1 -- 112 Bits
K is a double length key (VSS K1 and K2)

| | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 16 ALGO\_MAC10 (v6.0+) | | | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | | Format | ALGO\_MAC20 | | Parameters |

ISO 9797-1 MAC Algorithm 2 -- 112 Bits
K is a single length key (VSS K1)
K''' is a single length key (VSS K2)

| | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 17 ALGO\_MAC20 (v6.0+) | | | | ---------- | -------------------------------------------------------------------------------- | | Format | ALGO\_MAC20\_LAST | | Parameters | When the last block is MACed, do last block processing Can MAC, 1 or more blocks | | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 18 ALGO\_MAC20\_LAST (v6.0+) | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------ | | Format | ALGO\_MAC30 | | Parameters |

ISO 9797-1 MAC Algorithm 3 -- 112 Bits
K is a single length key (VSS K1)
K' is a single length key (VSS K2)

| | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 19 ALGO\_MAC30 (v6.0+) | | | | ---------- | -------------------------------------------------------------------------------- | | Format | ALGO\_MAC30\_LAST | | Parameters | When the last block is MACed, do last block processing Can MAC, 1 or more blocks | | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 20 ALGO\_MAC30\_LAST (v6.0+) | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | ALGO\_MAC40\_FIRST | | Parameters |

ISO 9797-1 MAC Algorithm 4 -- 112 Bits
When the first block is MACed, do first block processing
Can MAC, 1 or more blocks
K is a single length key (VSS K1)
K'' is a single length key (VSS K1 XOR 0xF0F0F0F0F0F0F0F0)
K' is a single length key (VSS K2)

| | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 21 ALGO\_MAC40\_FIRST (v6.0+) | | | | ---------- | ------------------------------------------------------------------------------- | | Format | ALGO\_MAC40 | | Parameters | Middle block processing | | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 22 ALGO\_MAC40 (v6.0+) | | | | ---------- | -------------------------------------------------------------------------------- | | Format | ALGO\_MAC40\_LAST | | Parameters | When the last block is MACed, do last block processing Can MAC, 1 or more blocks | | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 23 ALGO\_MAC40\_LAST (v6.0+) | | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Format | ALGO\_MAC50 | | Parameters |

ISO 9797-1 MAC Algorithm 5 -- 56 Bits
K1 is a single length key (VSS K1)
K2 is a single length key (VSS K1 XOR 0xF0F0F0F0F0F0F0F0)

| | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 24 ALGO\_MAC50 (v6.0+) | | | | ---------- | -------------------------------------------------------------------------------- | | Format | ALGO\_MAC50\_LAST | | Parameters | When the last block is MACed, do last block processing Can MAC, 1 or more blocks | | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 25 ALGO\_MAC50\_LAST (v6.0+) | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | ALGO\_MAC60 | | Parameters |

ISO 9797-1 MAC Algorithm 5 -- 112 Bits
K1 is a double length key (VSS K1 and K2)
K2 is a double length key (VSS K1 XOR 0xF0F0F0F0F0F0F0F0)
(VSS K2 XOR 0xF0F0F0F0F0F0F0F0)

| | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 26 ALGO\_MAC60 (v6.0+) | | | | ---------- | -------------------------------------------------------------------------------- | | Format | ALGO\_MAC60\_LAST | | Parameters | When the last block is MACed, do last block processing Can MAC, 1 or more blocks | | Comments | This OP code is available only in version 6.0 of the VSS interpreter and higher | : Table 27 ALGO\_MAC60\_LAST (v6.0+) | | | | ---------- | -------------------------------------------------------------------------------- | | Format | BRA Label | | Parameters | Label (The Label to branch to) | | Operation | A branch is taken to the Label | | Comments | This OP code is available only in version 2.0 of the VSS interpreter and higher. | : Table 28 BRA | | | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format |

CHK\_EVEN
CHK\_ODD

| | Optional |

Check the parity of each byte in register A. If one byte is not of the expected parity, then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).
CHK\_EVEN verifies that each byte has even number of bits set to 1.
CHK\_ODD verifies that each byte has odd number of bits set to 1.

| : Table 29 CHK\_EVEN / CHK\_ODD | | | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

CHK\_EVEN\_BNE Label
CHK\_ODD\_BNO Label

| | Parameters | Label - The Label to branch to. | | Operation |

Check the parity of each byte in register A. If one byte is not of the expected parity, (Even - even number of bits set to 1, Odd - odd number of bits set to 1), then the macro command execution branches to the Label, otherwise the next OP Code is executed.
CHK\_EVEN\_BNE if all bytes are not even parity, branch to Label
CHK\_ODD\_BNO if all bytes are not odd parity, branch to Label

| | Comments | These OP codes are available only in version 2.0 of the VSS interpreter and higher. | : Table 30 CHK\_EVEN\_BNE / CHK\_ODD\_BNO | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format |

CLRA
SETA
RNDA

| | Parameters | The instructions fill the register A with 00h (CLRA), FFh (SETA) or random bytes (RNDA). | | Operation | Even though the same operation can be accomplished using LDAI, it is recommended to use CLRA and SETA because they are coded on one byte instead of nine for LDAI. | : Table 31 CLRA/SETA/RNDA | | | | --------- | -------------------------------------------------------------------------------------- | | Format | CLRIV | | Operation | The content of the Initialization Vectors (IV-0 and IV-1) is cleared (filled with 00h) | : Table 32 CLRIV | | | | --------- | ---------------------------------------------------------- | | Format | COMA | | Operation | Each byte of register A is complemented (one's complement) | : Table 33 COMA | | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | CMPA index | | Parameters | index (block location) | | Operation |

Compare the content of register A with the content of the block #index.
If the comparison fails, the macro command execution stops, and an error is returned (see Appendix A: OP Code Table)

| : Table 34 CMPA | | | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

CMPA\_BEQ index Label
CMPA\_BNE index Label
CMPA\_BGT index Label
CMPA\_BLT index Label
CMPA\_BGE index Label
CMPA\_BLE index Label

| | Parameters |

index (block location)
Label (Label to branch to)

| | Operation |

Unsigned compare the content of register A with the content of the block #index.
If the comparison is true, a branch is made to Label, otherwise the next OP Code is executed.
CMPA\_BEQ if A = block #index, branch to Label
CMPA\_BNE if A != block #index, branch to Label
CMPA\_BGT if A > block #index, branch to Label
CMPA\_BLT if A < block #index, branch to Label
CMPA\_BGE if A >= block #index, branch to Label
CMPA\_BLE if A <= block #index, branch to Label

| | Comments | These OP codes are only available in version 2.0 of the VSS interpreter and higher. | : Table 35 CMPA\_BEQ / CMPA\_BNE / CMPA\_BGT / CMPA\_BLT / CMPA\_BGE / CMPA\_BLE | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

CMPA\_B0
CMPA\_B1

| | Operation |

Compare the content of the register A with the content of the register B0 (CMPA\_B0) or B1 (CMPA\_B1).
If the comparison fails, then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 36 CMPA\_B0/CMPA\_B1 | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

CMPA\_B0\_BEQ Label
CMPA\_B0\_BNE Label
CMPA\_B0\_BGT Label
CMPA\_B0\_BLT Label
CMPA\_B0\_BGE Label
CMPA\_B0\_BLE Label
CMPA\_B1\_BEQ Label
CMPA\_B1\_BNE Label
CMPA\_B1\_BGT Label
CMPA\_B1\_BLT Label
CMPA\_B1\_BGE Label
CMPA\_B1\_BLE Label

| | Parameter | Label (Label to branch to) | | Operation |

Unsigned compare the content of register A with the content of B0 or B1. If the comparison is true, a branch is made to Label, otherwise the next OP Code is executed.
CMPA\_B0\_BEQ if A = B0, branch to Label
CMPA\_B0\_BNE if A != B0, branch to Label
CMPA\_B0\_BGT if A > B0, branch to Label
CMPA\_B0\_BLT if A < B0, branch to Label
CMPA\_B0\_BGE if A >= B0, branch to Label
CMPA\_B0\_BLE if A <= B0, branch to Label
CMPA\_B1\_BEQ if A = B1, branch to Label
CMPA\_B1\_BNE if A != B1, branch to Label
CMPA\_B1\_BGT if A > B1, branch to Label
CMPA\_B1\_BLT if A < B1, branch to Label
CMPA\_B1\_BGE if A >= B1, branch to Label
CMPA\_B1\_BLE if A <= B1, branch to Label

| | Comments | These OP codes are only available in version 2.0 of the VSS interpreter and higher. | : Table 37 CMPA\_B0\_BEQ / CMPA\_B0\_BNE / CMPA\_B0\_BGT / CMPA\_B0\_BLT / CMPA\_B0\_BGE / CMPA\_B0\_BLE / CMPA\_B1\_BEQ / CMPA\_B1\_BNE / CMPA\_B1\_BGT / CMPA\_B1\_BLT / CMPA\_B1\_BGE / CMPA\_B1\_BLE | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | CMPAX | | Parameter | none | | Operation |

Compare the register A with the block pointed by the content of register X.
If the comparison fails, then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 38 CMPAX | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

CMPAX\_BEQ Label
CMPAX\_BNE Label
CMPAX\_BGT Label
CMPAX\_BLT Label
CMPAX\_BGE Label
CMPAX\_BLE Label

| | Parameter | Label (Label to branch to) | | Operation |

Unsigned compare the content of register A with the content of the block, pointed to by the content of register X. If the comparison is true, then a branch is made to Label, otherwise the next Op Code is executed.
CMPAX\_BEQ if A = block pointed to by register X, branch to Label
CMPAX\_BNE if A != block pointed to by register X, branch to Label
CMPAX\_BGT if A > block pointed to by register X, branch to Label
CMPAX\_BLT if A < block pointed to by register X, branch to Label
CMPAX\_BGE if A >= block pointed to by register X, branch to Label
CMPAX\_BLE if A <= block pointed to by register X, branch to Label

| | Comments | These OP codes are only available in version 2.0 of the VSS interpreter and higher. | : Table 39 CMPAX\_BEQ / CMPAX\_BNE / CMPAX\_BGT / CMPAX\_BLT / CMPAX\_BGE / CMPAX\_BLE | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | CMPSHA / CMPSHA256 | | Operation |

Compare the content of the SHA register with the first 20 bytes of SHA and 32 bytes of SHA256 of register W.
If the comparison fails, then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| | Comments | CMPSHA256 OP code is only available in version 6.0 of the VSS interpreter and higher. | : Table 40 CMPSHA / CMPSHA256 | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

CMPSHA\_BEQ Label
CMPSHA\_BNE Label
CMPSHA256\_BEQ Label
CMPSHA256\_BNE Label

| | Parameters | Label (Label to branch to) | | Operation |

Compare the content of the SHA register with the first 20 bytes of SHA and 32 bytes of SHA256 of register W. If the comparison is true, a branch is made to Label, otherwise the next Op Code is executed.
CMPSHA\_BEQ / CMPSHA256\_BEQ if W = SHA, branch to Label
CMPSHA\_BNE / CMPSHA256\_BNE if W != SHA, branch to Label.

| | Comments |

CMPSHA\_BEQ / CMPSHA\_BNE OP codes are only available in version 2.0 of the VSS interpreter and higher.
CMPSHA256\_BEQ / CMPSHA256\_BNE OP codes are only available in version 6.0 of the VSS interpreter and higher.

| : Table 41 CMPSHA\_BEQ / CMPSHA\_BNE/CMPSHA256\_BEQ / CMPSHA256\_BNE | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | DECIM0 | | Operation |

This function decimalizes the content of register A using the PVV and PAC Shell formats:
From left to right, take only the digits (nibbles) =< 9.
Then take the digits > 9 and apply mod 10.
For PVV only the 4 first bytes must be kept, For PAC Shell only the first 3 bytes. This is not done by this instruction.
Refer to VDN 15471 for Description of the algorithms.

| | Example |

Reg A Before: FE A1 26 D4 E4 89 66 6F
Reg A After: 12 64 48 96 66 54 03 45

| : Table 42 DECIM0 (PVV & PAC Shell Formats) | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | DECIMI | | Operation |

This function decimalizes the content of register A using the IBM3624 with offset format:
The decimalization table must be in register B0.
Refer to VDN 15471 for Description of the IBM3624 algorithm.

| | Example |

Reg B0 (dec. table) 85 05 32 01 39 24 16 74
Reg A Before: CA EC A9 73 22 EE FF D0
Reg A After: 12 71 29 15 00 77 44 68

| : Table 43 DECIM1 (IBM3624 Format) | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | DECIM2 | | Operation |

This function decimalizes the content of register A using the CCV format:
Apply mod 10 on each nibble.
Refer to VDN 15471 for Description of the CCV algorithm.

| | Example |

Reg A Before: FE A1 26 D4 E4 89 66 6F
Reg A After: 54 01 26 34 44 89 66 65

| : Table 44 DECIM2 (CCV Format) | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | DELETE index\_from index\_to | | Parameters |

index\_fromfirst block location to be deleted.
index\_tolast block location to be deleted.

| | Operation |

This instruction deletes all the blocks from block #index\_from to block #index\_to. The deletion is done by writing a fixed value in the block and marking it as not loaded. If index\_from is greater than index\_to or if one index is out-ofrange, then macro command execution stops, and an error is returned (see Appendix A: OP Code Table).
Use index\_to = index\_from, to delete one block only.

| : Table 45 DELETE | | | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | DELETEX | | Parameters | none | | Operation |

This instruction deletes the block pointed by the content of register X.
The deletion is done by writing a random value in the block and marking it as not loaded.

| : Table 46 DELETEX | | | | ---------- | ----------------------------------------------------------------------------------- | | Format | DELETE\_DUKPT\_KEY | | Parameters | none | | Operation | This instruction deletes the DUKPT Key. | | Comments | These OP codes are only available in version 4.0 of the VSS interpreter and higher. | : Table 47 DELETE\_DUKPT\_KEY | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

ECBC
DCBC

| | Operation |

Perform an encryption (ECBC) or decryption (DCBC) in CBC mode.
If the algorithm selected is DES, then the computation is performed on the register A with result in A (IV-0 for intermediate result).
If the algorithm selected is AES, then the computation is performed on register A and B0 with result in A and B0 (B0 is used for the second part of the data, IV-0 and IV-1 for intermediate result).
This instruction uses the current key registers CK differently depending on the selected algorithm:
\ ALGO\_DES56 uses CK-0 only
ALGO\_DES112, ALGO\_AES128 uses CK-0 and CK-1
ALGO\_DES168, ALGO\_AES192 uses CK-0, CK-1 and CK-2
ALGO\_AES256 uses CK-0, CK-1, CK-2 and CK-3

| : Table 48 ECBC / DCBC | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format |

ECBC\_CB offset length
DCBC\_CB offset length

| | Operation |

Perform an encryption (ECBC\_CB) or decryption (DCBC\_CB) in CBC mode on the data in the communication buffer starting at offset for length.
Result in communication buffer. The data is replaced.
Must select algorithm and then key before execution of the OP code.
Length must be a multiple of 8 bytes for DES and 16 bytes for AES, so data must be padded.
Must set or clear IV before starting encryption/decryption.

| | Comment | These OP codes are only available in version 6.0 of the VSS interpreter and higher. | : Table 49 ECBC\_CB / DCBC\_CB | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

Format ECBC\_CB\_X offset
DCBC\_CB\_X offset

| | Operation |

Perform an encryption (ECBC\_CB\_X) or decryption (DCBC\_CB\_X) in CBC mode on the data in the communication buffer starting at offset for length in X.
Result in communication buffer. The data is replaced.
Must select algorithm and then key before execution of the OP code.
Length must be a multiple of 8 bytes for DES and 16 bytes for AES, so data must be padded.
Must set or clear IV before starting encryption/decryption.

| | Comment | These OP codes are only available in version 6.0 of the VSS interpreter and higher. | : Table 50 ECBC\_CB\_X / DCBC\_CB\_X | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

EECB
DECB

| | Operation |

Perform an encryption (EECB) or decryption (DECB) in ECB mode.
If the algorithm selected is DES then the computation is performed on register A with result in A.
If the algorithm selected is AES, then the computation is performed on register A and B0 with result in A and B0 (B0 is used for the second part of the data).
This instruction uses the current key registers CK differently depending on the selected algorithm:
ALGO\_DES56uses CK-0 only
ALGO\_DES112, ALGO\_AES128uses CK-0 and CK-1
ALGO\_DES168, ALGO\_AES192uses CK-0, CK-1 and CK-2
ALGO\_AES256uses CK-0, CK-1, CK-2 and CK-3
This instruction does not use the Initialization Vector.

| : Table 51 EECB / DECB | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

EECB\_CB offset length
DECB\_CB offset length

| | Operation |

Perform an encryption (EECB\_CB) or decryption (DECB\_CB) in ECB mode on the data in the communication buffer starting at offset for length.
Result in communication buffer. The data is replaced.
Must select algorithm and then key before execution of the OP code.
Length must be a multiple of 8 bytes for DES and 16 bytes for AES, so data must be padded.
These instructions do not use the IV.

| | Comment | These OP codes are only available in version 6.0 of the VSS interpreter and higher. | : Table 52 EECB\_CB / DECB\_CB | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

EECB\_CB\_X offset
DECB\_CB\_X offset

| | Operation |

Perform an encryption (EECB\_CB\_X) or decryption (DECB\_CB\_X) in ECB mode on the data in the communication buffer starting at offset for length in X.
Result in communication buffer. The data is replaced.
Must select algorithm and then key before execution of the OP code.
Length must be a multiple of 8 bytes for DES and 16 bytes for AES, so data must be padded.
These instructions do not use the IV.

| | Comment | These OP codes are only available in version 6.0 of the VSS interpreter and higher. | : Table 53 EECB\_CB\_X / DECB\_CB\_X | | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | EOM length | | Parameters | length (Number of bytes to be returned) | | Operation |

End of Macro.
This keyword terminates the OP Code string and instructs the interpreter to return length bytes from the communication buffer in the response packet.

| : Table 54 EOM | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | ERR\_RET length | | Parameters | length (Number of bytes to be returned) | | Operation |

Error Return from Macro.
This command will have a non-zero return value (E\_VS\_ERR\_RET). It can be used for returning custom errors or for debugging. The macro can place error or debug data in the CB to be returned to the application.
This keyword terminates the OP code string and instructs the interpreter to return length bytes from the communication buffer in the response packet.

| | Comment | This OP code is only available in version 2.0 of the VSS interpreter and higher. | : Table 55 ERR\_RET | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GET\_DUKPT\_KEY | | Operation |

Get the Type/Status, the Key Serial Number (KSN), and the DUKPT Future Key (FK)
The Type/Status is in register X.
X = 0 – Single DES DUKPT Key
X = 1 – Triple DES DUKPT Key
X = 2 – DUKPT Not Initialized
X = 3 – DUKPT Key Exhaustion – End of Life
The Key Serial Number (KSN) is the first 10 bytes (0-9) of the communication buffer.
The Future Key:
Single DES DUKPT Key:
Future Key (FK) is in B0.
Triple DES DUKPT Key:
Future Key Left (FKL) is in B0.
Future Key Right (FKR) is in B1.
The OS will derive the next Future Key (FK).

| | Comment | This OP code is only available in version 4.0 of the VSS interpreter and higher. | : Table 56 GET\_DUKPT\_KEY | | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GETA offset | | Parameters | offset (offset in the communication buffer) | | Operation |

End of Macro.
This keyword terminates the OP code string and instructs the interpreter to return length bytes from the communication buffer in the response packet.

| : Table 57 GETA | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | GETA\_HA\_TO\_BIN offset | | Parameters | offset (offset in the communication buffer) | | Operation |

16 bytes from the position offset in the communication buffer are converted from Hex ASCII ('0'-'9', 'A'-'F', 'a'-'f') to Binary and the 8 Binary bytes are copied into register A.
At the beginning of the macro command the communication buffer contains only the data field of the incoming command.

| | Comment | This OP code is only available in version 2.0 of the VSS interpreter and higher. | : Table 58 GETA\_HA\_TO\_BIN | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GETPINNB | | Operation | After the PIN entry session is finished, this instruction can be used to transfer the number of PIN digits entered into the first (leftmost) byte of the register A. | | Example |

Entered PIN: 1234
Reg A Before: aa bb cc dd ee ff gg hh
Reg A After: 04 bb cc dd ee ff gg hh

| : Table 59 GETPINNB | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GETPINO | | Operation | After the PIN entry session is finished, this instruction can be used to transfer the PIN digits into the register A, one nibble per digit starting at the leftmost position. After this operation the PIN is deleted from the keyboard buffer. | | Example |

Entered PIN: 1234
Reg A Before: aa bb cc dd ee ff gg hh
Reg A After: 12 34 aa bb cc dd ee ff

| : Table 60 GETPINO (one nibble per digit, starting from the left) | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | GETPIN1 | | Operation | After the PIN entry session is finished, this instruction can be used to transfer the PIN digits into the register A, one nibble per digit starting at the rightmost position. After this operation the PIN is deleted from the keyboard buffer. | | Example |

Entered PIN: 1234
Reg A Before: aa bb cc dd ee ff gg hh
Reg A After: cc dd ee ff gg hh 12 34

| : Table 61 GETPIN1 (One nibble per digit, starting from the right) | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | GETPIN2 | | Operation |

After the PIN entry session is finished, this instruction can be used to transfer the PIN into the register A one byte (digit) at a time. The content of the register A is shifted to the right before the transfer. The digit transferred to A is then deleted from the keyboard buffer.
If no PIN digit is left in the keyboard buffer, then the command is ignored and the register A is not shifted.

| | Example |

Entered PIN: 1234
Reg A Before: aa bb cc dd ee ff gg hh
Reg A After 1st call: 34 aa bb cc dd ee ff gg
Reg A After 2nd call: 33 34 aa bb cc dd ee ff
Reg A After 3rd call: 32 33 34 aa bb cc dd ee
Reg A After 4th call: 31 32 33 34 aa bb cc dd

| : Table 62 GETPIN2 (One byte per digit and per call, starting from the right) | | | | --------- | --------------------------------------------------------------------------------------------------------- | | Format | GETPIN3 | | Operation | The Pin is transferred into the register A as 2 times the 4 ASCII bytes of the pin. | | Example |

Entered PIN: 1234
Reg A Before: aa bb cc dd ee ff gg hh
Reg A After: 31 32 33 34 31 32 33 34

| : Table 63 GETPIN3 ("Smart Card" format) | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GETW offset length | | Parameters |

offset (offset in the communication buffer)
length (number of bytes)

| | Example | length bytes from the position offset in the communication buffer is copied in register W. At the beginning of the macro command the communication buffer contains only the data field of the incoming command. | : Table 64 GETW | | | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GETW\_HA\_TO\_BIN offset length | | Parameters |

offset (offset in the communication buffer)
length (number of bytes - must be even)

| | Example |

length bytes from the position offset in the communication buffer are converted from Hex ASCII ('0'-'9', 'A'-'F', 'a'-'f') to Binary and length/2 Binary bytes are copied into W.
At the beginning of the macro command the communication buffer contains only the data field of the incoming command.

| | Comments | This OP code is only available in version 2.0 of the VSS interpreter and higher. | : Table 65 GETW\_HA\_TO\_BIN | | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GETX offset | | Parameters | offset (offset is the communication buffer) | | Example |

One byte from the position offset in the communication buffer is copied into register X.
At the beginning of the macro command the communication buffer contains only the data field of the incoming command.

| : Table 66 GETX | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | GETX\_HA\_TO\_BIN offset | | Parameters | offset (offset is the communication buffer) | | Example |

2 bytes from the position offset in the communication buffer are converted from Hex ASCII ('0'-'9', 'A'-'F', 'a'-'f') to Binary and the 1 Binary byte is copied into register X.
At the beginning of the macro command the communication buffer contains only the data field of the incoming command.

| | Comments | This OP code is only available in version 2.0 of the VSS interpreter and higher. | : Table 67 GETX\_HA\_TO\_BIN | | | | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | Format |

INCA
DECA

| | Operation | The content of Register A is incremented (INCA) or decremented (DECA). The Register A is considered as a 64 bit unsigned integer. | : Table 68 INCA / DECA | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------- | | Format |

INCX
DECX

| | Operation | The content of Register X is incremented (INCX) or decremented (DECX). The Register X is considered as a 8-bit unsigned integer. | : Table 69 INCX / DECX | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | INIT\_1DES\_DUKPT | | Operation |

Initialize Triple DES DUKPT.

The Initial Key Serial Number (IKSN) is the first.

10 bytes (0-9) of the communication buffer.

The Initial Key (IK) is in B0.

| | Comments | This OP code is only available in version 4.0 of the VSS interpreter and higher. | : Table 70 INIT\_1DES\_DUKPT | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | INIT\_3DES\_DUKPT | | Operation |

Initialize Triple DES DUKPT.

The Initial Key Serial Number (IKSN) is the first.

10 bytes (0-9) of the communication buffer.

The Initial Key Left (IKL) is in B0.

The Initial Key Right (IKR) is in B

| | Comments | This OP code is only available in version 4.0 of the VSS interpreter and higher. | : Table 71 INIT\_3DES\_DUKPT | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | LDAX | | Parameters | index (block location) | | Operation | If the content of the block `#index` is valid (present), then it is copied into register A. If the block is invalid (not been loaded or corrupted), then the macro command execution stops and an error is returned (see [Appendix A: OP Code Table](#sec_vss_appendix_a)). | : Table 72 LDA | | | | ---------- | --------------------------------------------------------- | | Format | LDAI value | | Parameters | value (8-byte immediate value) | | Operation | The 8-byte immediate value is copied into the register A. | : Table 73 LDAI | | | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | LAD index | | Parameters | none | | Operation | If the block pointed by the content of register X is valid (present), then it is copied into register A. If the block is invalid (not been loaded or corrupted), then the macro command execution stops, and an error is returned (see [Appendix A: OP Code Table](#sec_vss_appendix_a)). | : Table 74 LDAX | | | | ---------- | -------------------------------------------------------------- | | Format | LDXI value | | Parameters | One-byte value | | Operation | The immediate value is copied into the single-byte register X. | : Table 75 LDXI | | | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | LENGTH number | | Parameters | number (Number of bytes expected) | | Operation |

This instruction verifies the number of data bytes received in the macro command call.
If the length of the data field does not match the number of bytes expected, then the command is not executed and E\_VS\_BAD\_LENGTH error is returned.

| | Comments | This instruction can be used only after MACRO or SID instructions, E\_VS\_BAD\_CHAINING is returned otherwise. | : Table 76 LENGTH | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

LSLA number
LSRA number

| | Parameters | number (Number of bits to be shifted) | | Operation |

The content of the register A is shifted by number bits to the left (LSLA) or to the right (LSRA).
Incoming bits from the left (LSLA) or from the right (LSRA) are 0.

| : Table 77 LSLA / LSRA | | | | ---------- | ---------------------------------------------------------------------------------- | | Format | MACRO index | | Parameters | index (Macro command index (command number). Range is \[10h..FFh]) | | Operation | This keyword defines the macro command index that will be used to call this macro. | | Comments | Commands from 00h to 0Fh are reserved, so the first available value is 10h. | : Table 78 MACRO index | | | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | MAC\_CB offset length | | Operation | MAC the data in the communication buffer starting at offset for length. | | Comments |

Must set or clear IV before the start of MAC.
Must select algorithm and then key before execution of OP code.
Length must be a multiple of 8 bytes, so data must be padded.
Result in IV, all 8 bytes, data is not truncated.
This OP code is only available in version 6.0 of the VSS interpreter and higher.

| : Table 79 MAC\_CB offset length | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | MAC\_CB\_X offset | | Operation | MAC the data in the communication buffer starting at offset for length in X. | | Comments |

Must set or clear IV before the start of MAC.
Must select algorithm and then key before the execution of OP code.
Length must be a multiple of 8 bytes, so data must be padded.
Result in IV, all 8 bytes, data not truncated.
This OP code is only available in version 6.0 of the VSS interpreter and higher.

| : Table 80 MAC\_CB\_X offset | | | | --------- | --------------------------------------------------------------- | | Format |

MOV\_A\_B0
MOV\_A\_B1

| | Operation | The content of register A is copied into the register B0 or B1. | | Comments | Content of register A is not modified by this instruction. | : Table 81 MOV\_A\_B0 / MOV\_A\_B1 | | | | --------- | -------------------------------------------------------------------------------- | | Format | MOV\_A\_IV | | Operation | Set A as IV. The content of register A is copied into the Initialization Vector. | | Comments | Content of register A is not modified by this instruction. | : Table 82 MOV\_A\_IV | | | | --------- | ------------------------------------------------------------------------------------------------------- | | Format | MOV\_A\_W | | Operation | The content of register A is copied into register W. Only the first 8 bytes of register W are modified. | | Comments | Content of register A is not modified by this instruction. | : Table 83 MOV\_A\_W | | | | --------- | ----------------------------------------------------------------------- | | Format | MOV\_A\_X | | Operation | The first byte of register A is copied into the single-byte register X. | | Comments | Content of register A is not modified by this instruction. | : Table 84 MOV\_A\_X | | | | --------- | ------------------------------------------------------------------ | | Format |

MOV\_B0\_A
MOV\_B1\_A

| | Operation | The content of register B0 or B1 is copied into register A. | | Comments | Content of register B0 and B1 is not modified by this instruction. | : Table 85 MOV\_B0\_A / MOV\_B1\_A | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | MOV\_IV\_A | | Operation |

Get IV into A.
If ALGO\_DES56 (default) is selected, then the Initialization Vector 0 (IV-0) is copied into the register A. Otherwise, the Initialization Vector 0 (IV-0) is copied into the register A and the Initialization Vector 1 (IV-1) is copied into the register B0.

| | Comments | The behavior of this instruction depends on the selected algorithm. | : Table 86 MOV\_IV\_A | | | | --------- | ----------------------------------------------------------- | | Format | MOV\_IW\_A | | Operation | The first 8 bytes of register W are copied into register A. | : Table 87 MOV\_IW\_A | | | | --------- | ----------------------------------------------------------------------- | | Format | MOV\_X\_A | | Operation | The single-byte register X is copied into the first byte of register A. | : Table 88 MOV\_X\_A \[TABLE] : Table 89 OAEP | | | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | Format | OFFSET0 | | Operation |

Performs the following operation on each nibble of register A (Register B0 contains the value to be subtracted):
A <- (A-B0) mod 10

| | Example |

Reg B: 12 34 00 00 00 50 00 09
Reg A Before: 99 99 00 00 00 60 00 01
Reg A After: 87 65 00 00 00 10 00 02

| : Table 90 OFFSET0 (A-B0 mod 10) | | | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Format | OFFSET1 | | Operation |

Performs the following operation on each nibble of register A (Register B0 contains the value to be added):
A <- (A+B0) mod 10

| | Example |

Reg B: 12 34 00 00 00 50 00 09
Reg A Before: 99 99 00 00 00 60 00 01
Reg A After: 01 23 00 00 00 10 00 90

| : Table 91 OFFSET1 (CCV type 1) | | | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | OFFSET2 (CCV type 2) | | Operation |

Performs the following operation on each 4-digit pieces of register A (Register B0 contains the value to be added):
A <- (A+B0) mod 10000

| | Example |

Reg B: 12 34 00 00 00 50 00 09
Reg A Before: 99 99 00 00 00 60 00 01
Reg A After: 12 33 00 00 01 10 01 00

| : Table 92 OFFSET2 (CCV type 2) | | | | --------- | ------------------------------------------------------------------------------- | | Format | RNDW | | Operation | This instruction fills W with random bytes. | | Comments | This OP code is only available in version 2.0 of the VSS interpreter of higher. | : Table 93 RNDW | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | RSACOMP | | Operation |

Performs an RSA computation on the data in register W, then using the RSA key currently selected. Result is in register W. The size of the data being processed from the register W is equal to the size of the modulus of the RSA key selected. This OP code has the following limitations:

The size of the modulus for the SC 5000 must be at least 8 bytes, multiple of 4 bytes. For other devices, see the programmer reference manual.

For the EMV key slots the maximum size of the modulus is 252 bytes and the maximum size of the exponent is 3 bytes.

If those limitations are not respected or if an RSA key slot has not been selected, then the macro execution stops, and an error code is returned (see Appendix A: OP Code Table).

| : Table 94 RSACOMP | | | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SELECT index | | Parameters | index (Key block number. Must be in the range defined by keyword DEF\_BLK.) | | Operation |

If ALGO\_DES56t key register CK-0 is used. If ALGO\_DES112 or ALGO\_AES128 is selected, then the content of key blocks #index and #index+1 are copied into current key registers CK-0 and CK-1.
If ALGO\_DES168 or ALGO\_AES192 is selected, then the content of key blocks #index, #index+1 and #index+2 are copied into current key registers CK- 0, CK-1 and CK-2.
If ALGO\_AES256 is selected, then the content of key blocks #index, #index+1, #index+2 and #index+3 are copied into current key registers CK-0, CK-1, CK-2 and CK-3.

| | Comments | If index is out of range or the key(s) is (are) not present in the block(s), an error is returned (see [Appendix A: OP Code Table](#sec_vss_appendix_a)). | : Table 95 SELECT | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SELECT index | | Operation |

If ALGO\_DES56 (default) is selected, then the content of register A is copied into current key register CK-0.
If ALGO\_DES112 or ALGO\_AES128 is selected, then the content of register A and B0 are copied into current key registers CK- 0 and CK-1.
If ALGO\_DES168 or ALGO\_AES192 is selected, then the content of register A, B0 and B1 are copied into current key registers CK-0, CK-1 and CK-2.
If ALGO\_AES256 is selected, this instruction does nothing: In that case, each part of the key must be into key slots and then transferred into CK-n using the SELECT command.

| : Table 96 SELECTA | | | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SELECTX | | Operation |

If ALGO\_DES56 (default) is selected, then the content of the block pointed by register X is copied into current key register CK-0.
If ALGO\_DES112 or ALGO\_AES128 is selected, the content of the block pointed by register X plus the next block are copied into current key registers CK-0 and CK-1.
If ALGO\_DES168 or ALGO\_AES192 is selected, the content of the block pointed by register X plus the next two blocks are copied into current key registers CK-0, CK-1 and CK-2.
If ALGO\_AES256 is selected, then the content of the block pointed by register X plus the next three blocks are copied into current key registers CK-0, CK-1, CK-2 and CK-3.

| : Table 97 SELECTX | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | SELRSA | | Parameters | index (RSA key slot number, Range \[0..5]) | | Operation |

Select the key in RSA key slot #index for the next RSA computation.
If the index is out of range, then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 98 SELRSA | | | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Parameters | none | | Operation |

Select the key in the slot pointer by register X for the next RSA computation.
If the index value in register X is out of range (>5) or the key is not present, the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 99 SELRSAX | | | | ---------- | --------------------------------------------------------------------------------------------------- | | Format | SENDA offset | | Parameters | offset (position in the communication buffer) | | Operation | The 8 bytes of register A are copied into the communication buffer starting at the position offset. | : Table 100 SENDA | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

SENDA\_BIN\_TO\_HA offset
length (number of bytes)

| | Parameters | offset (position in the communication buffer) | | Operation | length bytes from W are converted from Binary to Hex ASCII ('0'-'9', 'A'-'F') and length\*2 bytes are copied into the communication buffer starting at the position offset. | | Comments | This OP code is only available in version 2.0 of the VSS interpreter and higher. | : Table 101 SENDA\_BIN\_TO\_HA | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SELRAX | | Parameters | none | | Operation |

Select the key in the slot pointer by register X for the next RSA computation.
If the index value in register X is out of range (>5) or the key is not present, then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 102 SENDW | | | | ---------- | ----------------------------------------------------------------------------------------- | | Format | SENDX offset | | Parameters | offset (position in the communication buffer) | | Operation | The content of register X is copied into the communication buffer at the position offset. | : Table 103 SENDX | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SENDX\_BIN\_TO\_HA offset | | Parameters | offset (position in the communication buffer) | | Operation | 1 byte from register X is converted from Binary to Hex ASCII ('0'-'9', 'A'-'F') and the 2 bytes are copied into the communication buffer starting at the position offset. | | Comments | This OP code is only available in version 2.0 of the VSS interpreter and higher. | : Table 104 SENDX\_BIN\_TO\_HA | | | | --------- | ------------------------------------------------------------------------------------------- | | Format | SHAINIT / SHA256INIT | | Operation | This instruction initiates the SHA-1 / SHA-256 computation. It initializes the SHA context. | | Comments | SHA256INIT OP code is only available in version 6.0 of the VSS interpreter and higher. | : Table 105 SHAINIT / SHA256INIT | | | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SHATERM / SHA256TERM | | Operation | This instruction finalizes the SHA-1 / SHA-256 computation with the remaining data and padding. The 20-byte SHA or the 32-byte SHA256 result is copied into register W. | | Comments | SHA256TERM OP code is only available in version 6.0 of the VSS interpreter and higher. | : Table 106 SHATERM / SHA256TERM | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | SHAUPDATE / SHA256UPDATE | | Parameters | length (Number of bytes to process) | | Operation | Update SHA-1 / SHA-256 with length bytes from register W. | | Comments |

The SHA-1 / SHA-256 is byte-oriented and does not handle bit streams.
SHA256UPDATE OP code is only available in version 6.0 of the VSS interpreter and higher.

| : Table 107 SHAUPDATE / SHA256UPDATE | | | | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | SID current next error | | Parameters |

current (Value of the Current State Identifier (CSID))
next (Value of the Next State Identifier (NSID))
error (Value of the Error State Identifier (ESID))

| | Operation |

The instruction first verifies that the internal State Identifier (SID) matches the current value (CSID).
If not, meaning this macro cannot be called at that point, an E\_VS\_BAD\_CHAINING error is returned (the internal SID is not modified.)
If the values match, then the macro command is executed.
If the execution fails (ExecuteScript() return code > 0), then the internal SID is set to the error value (ESID).
If the execution is successful, then the internal SID is set to the next value (NSID).

| | Comments |

This instruction must be used at the beginning of a macro, right after a MACRO or LENGTH keyword.
If the ExecuteScript() function ends due to an error other than an execution error (negative error code) then the SID is not modified.

| : Table 108 SID | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | STA index | | Parameters | index | | Operation |

The content of register A is copied into block #index. The block is then marked as valid.
If the index is out of range, then the macro execution stops, and an error code is returned (see Appendix A: OP Code Table).

| : Table 109 STA | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | STAX | | Parameters | none | | Operation |

The content of register A is copied into the block pointed by the content of register X. The block is then marked as valid.
If the value in register X is out of range, then the macro execution stops, and an error code is returned (see Appendix A: OP Code Table).

| : Table 110 STAX | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | STRSA index | | Parameters | index (RSA key location, Range \[0..5]) | | Operation |

The RSA key in register W is copied into the key slot #index. Key slots #0 through #3 are the EMV key slots shared with the EMV module. Those shared key slots have the following limitations:

Size of exponent limited to 3 bytes

Size of modulus limited to 252 bytes

Key slots #4 and #5 are two additional key slots that allow private key computations up to 2048 bits (256 bytes) on versions older than 9.1 and up to 4096 bits (512 bytes) starting with VSS version 9.1. The contents of register W needs to be formatted as follows:
RSA 2048-and EMV keys:

byte #0: Key type - EMV value or 0 for RSA-2048

byte #1..5: RID (relevant for EMV keys only)

byte #6: Key index (relevant for EMV keys only)

byte #7: Modulus length (use value 0 for 2048-bit modulus)

byte #8: Exponent length (use value 0 for 2048-bit private exponent)

byte #9..x: Modulus

byte #(9+x)..y: Exponent

RSA-4096 and RSA-3072 keys:

byte #0: Key type, 1 for 4096-bit keys

byte #1..5: RID (relevant for EMV keys only)

byte #6: Key index (relevant for EMV keys only)

byte #7: Modulus length byte 1

byte #8: Modulus length byte 2

byte #9: Exponent length byte 1

byte #10: Exponent length byte 2

byte #11..x: Modulus

byte #(11+x)..y: Exponent

For 4096-bit and 3072-bit keys modulus and exponent length should be passed as a two byte big endian value (see Script examples). If the index is out of range, then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 111 STRSA | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Format | STRSAX | | Parameters | none | | Operation |

The RSA key in register W is copied into the key slot pointed by register X. Refer to instruction STRSA for details.
If the index value in register Xis out of range (<5), then the macro command execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 112 STRSAX | | | | --------- | --------------------------------------------------------------------------------------------------------- | | Format | STSHA / STSHA256 | | Operation | The first 20 bytes of SHA or the first 32 bytes of SHA256 of register W are copied into the SHA register. | | Comments | STSHA256 OP code is only available in version 6.0 of the VSS interpreter and higher. | : Table 113 STSHA / STSHA256 | | | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | TSTXI min max | | Parameters |

min (minimum acceptable value)
max (maximum acceptable value)

| | Operation |

This instruction verifies the value contained in the index register X.
If the value is in the range \[min..max], nothing is done and the next instruction is processed.
If not in the range, then the macro execution stops, and an error is returned (see Appendix A: OP Code Table).

| : Table 114 TSTXI | | | | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format | TSTXI\_BOR min max Label | | Parameters |

min (minimum acceptable value)
max (maximum acceptable value)
Label (Label to branch to)

| | Operation |

This instruction verifies the value contained in the index register X.
If the value is in the range \[min..max], nothing is done, and the next instruction is processed.
If out of range, then a branch is made to Label.

| | Comments | This OP code is only available in version 2.0 of the VSS interpreter and higher. | : Table 115 TSTXI\_BOR | | | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Format |

XORA\_B0
XORA\_B1
ANDA\_B0
ANDA\_B1
ORA\_B0
ORA\_B1

| | Operation | Those instructions perform logical operations on register A using data in register B0 or B1. Result in register A. Content of register B0 or B1 is not modified by those instructions. | : Table 116 XORA\_B0 / XORA\_B1 / ANDA\_B0 / ANDA\_B1 / ORA\_B0 / ORA\_B1 #### Restrictions Following are the rules that should be followed while writing the script: * The script must start with the keywords SCRIPT and SUBDEV. * Then must follow the block definition section with the keywords DEF\_BLK or RETAIN\_BLK, but not both. * Some blocks may then be loaded with values using the keyword LD\_BLK. * The restrictions keywords (MS\_OFF and DUKPT\_OFF) are optional and can be used right before the block definition. * The macro definition section is optional. We can imagine a script used only to disable the PP1000 mode. Such a script would be 4 line long: * SCRIPT TEST0001 * SUBDEV 7 * PP1000\_OFF * DEF\_BLK 0 0 * Each macro definition must start with MACRO and end with EOM. * The keywords LENGTH and SID are optional and if used must be placed right after the keyword MACRO. * The low-level instruction keywords can only be used inside a macro. * The script file must end after the block definition section or after EOM. * Comments must start with '//'. The tool ignores all following characters in the line. * Blank lines are ignored. They do not generate an error. * By default, values are assumed to be decimal. 0x?? and ??h notations may be used to specify hexadecimal values, and ??b for binary values. Therefore, all the following notations are equivalent: 18, 0x012, 00000012h, 010010b, 12h. * The format of branching instructions: BRA LABEL LABEL: Branching can only be done to labels within the macros containing the branch instruction. Labels only need to be unique within a macro. #### Chaining Mechanism The chaining mechanism enforces the execution of the macro commands in a predefined order. Technically, this is done using an internal variable called the State IDentifier (SID). The SID is a 2-byte value indicating the number of the next command. All other macro commands will be rejected. Three values are stored along with each macro: * The Current State Identifier (CSID). It should match with the internal SID when the macro is executed. * The Next Command Identifier (NSID). It will be the new value of the internal SID after a successful execution of the macro. The NSID of the current command must equal the CSID of the following command. * The Error State Identifier (ESID). It will be the new value of the internal SID if an error occurs during the execution of the macro. Following are some rules that apply to the chaining mechanism: * The internal SID is reset to 0000h at start-up. * The CSID must be equal to the NSID of the previous command. * Several commands may have the same CSID. * Several commands may have the same NSID. * Commands that have CSID = FFFFh may be executed any time. * Commands that have NSID = FFFFh permit the execution of any next command. * A command should not have CSID = NSID because this opens the way for building new commands. In most of the cases the macro commands will perform high-level operations and will not need any chaining. They will ideally start and finish with the same SID (equals to 0), that is the order of execution is not important. If the SID values are not specified in the macro definition, then by default, no chaining is enforced for 0000h. #### Audit It is the responsibility of the authority signing the macros (the Sponsor) to verify that a sufficient security level is reached. The audit will be performed on the script file but only the downloadable file will be signed. It means that the script processing and the signing must be performed by the same person using genuine tools to prevent file switching. #### Script Examples **IBM 3624 with offset offline PIN verification** The following script defines two additional blocks to store the double-length PVK. The key is loaded using the generic key loading functions. * Set `#00h / Key#00h` -> PVKL * Set `#00h / Key#01h` -> PVKR The Security Script also implements a single macro command for the PIN verification. Script Example for IBM 3624 with offset offline PIN verification: ```cpp // // SUBDEV 00h // Script Identifier (Sub-device #) SCRIPT PVV0001 // Name for the IBM3624 Security Script // // DEF_BLK 2 2 // Define 2 8-byte blocks for PVK storage. PVK is loaded // using the default key loading functions. // // MACRO 10h // IBM3624OFFSET offline PIN verification LENGTH 24 // 8-byte PAN + 8-byte Decimalization Table + // 8-byte RRV|000000000000 GETA 08h // copy the decimalization table into A MOV_A_B0 // then into B0 GETA 00h // copy the PAN into A SELECT 00h // select PVKL EECB // ECB DES encryption, result into A SELECT 01h // select PVKR DECB // ECB DES decryption, result into A SELECT 00h // select PVKL EECB // ECB DES encryption, result into A DECIM1 // perform the decimalization of A using the table B0 MOV_A_B0 // store the 8-byte result into B0 LDAI FFFF000000000000 ANDA_B0 // keep only the first 4 digits MOV_A_B0 // store “true PIN” into B0 CLRA GETPIN0 // get PIN digits into A OFFSET0 // subtract the “true PIN” from the customer PIN MOV_A_B0 // store CRV into B0 GETA 10h // copy RRV into A CMPA_B0 // compare CRV and RRV, exit on error if different EOM 00h // return no data but the status=0 (successful execution) // ``` **PVV offline PIN verification** Let's assume we have a macro command to load the PVK (simple or double length) in blocks `#00` and `#01`. Here are the macros performing the PIN verification using the simple and double length keys: ```cpp // MACRO 13h // PVV offline PIN verification (simple DES) LENGTH 10 // 2 NULL bytes + 6-Byte PAN|PVKI + 2-byte PVV GETA 00h // copy the 0000|PAN|PVKI into A GETPIN1 // get PIN digits into A (from the right) SELECT 00h // select PVKL EECB // ECB DES encryption, result into A DECIM0 // perform the decimalization of A (PVV algorithm) MOV_A_B0 // store PCV into B0 GETA 08h // copy PVV into A CMPA_B0 // compare PCV and PVV, exit on error if different EOM 00h // return no data but the status=0 (successful execution) // // MACRO 14h // PVV offline PIN verification (triple DES) LENGTH 10 // 2 NULL bytes + 6-Byte PAN|PVKI + 2-byte PVV GETA 00h // copy the 0000|PAN|PVKI into A GETPIN1 // get PIN digits into A (from the right) SELECT 00h // select PVKL EECB // ECB DES encryption, result into A SELECT 01h // select PVKR DECB // ECB DES decryption, result into A SELECT 00h // select PVKL EECB // ECB DES encryption, result into A DECIM0 // perform the decimalization of A (PVV algorithm) MOV_A_B0 // store PCV into B0 GETA 08h // copy PVV into A CMPA_B0 // compare PCV and PVV, exit on error if different EOM 00h // return no data but the status=0 (successful execution) // ``` **PAC Shell offline PIN verification** We will assume the PAC Key location is block `#02`. Here is the macro for the PIN verification: ```cpp // MACRO 15h // PAC SHELL offline PIN verification LENGTH 24 // 8-byte PAN|0000 + 8-byte PinOffset|000000000000 + CLRA // 8-byte refPAC|0000000000000 GETPIN0 // get PIN digits into A (from the left) MOV_A_B0 // store customer PIN into B0 GETA 08h // copy PinOffset|000000000000 into A OFFSET0 // subtract the customer PIN from the PIN offset LSRA 30h // right justify the “derived PIN” and pad with 0 MOV_A_B0 // store the “derived PIN” into B0 GETA 00h // copy PAN|0000 into A ORA_B0 // concatenate PAN and the “derived PIN” SELECT 02h // select PAC KEY EECB // ECB DES encryption, result into A DECIM0 // perform the decimalization of A (PAC shell algo) MOV_A_B0 // store calcPAC into B0 GETA 10h // copy referencePAC into A CMPA_B0 // compare PACs, exit on error if different EOM 00h // return no data but the status=0 (successful execution) // ``` {% hint style="info" %} * in this example the selection functions have to be implemented in the terminal. Only the selected fields are sent to the PINpad instead of the full Track 2 data. {% endhint %} **CCV Shell offline PIN verification** Assuming the Cross-Domain Key is in the block `#03`, here is the macro for the PIN verification. Actually, this macro needs to be duplicated two more times in order to support all three types of the offset functions. Only the OFFSETx line will change. ```cpp // // MACRO 16h // CCV offline PIN verification (offset type 0) LENGTH 0018h // 8-byte IKCfields + 8-byte PinOffset|000000000000 GETA 00h // copy selected card data (I, K and C fields) into A SELECT 03h // select Cross Domain Key EECB // ECB DES encryption, result into A DECIM2 // perform the decimalization of A (CCV algorithm) MOV_A_B0 // store the “derived PIN” into B0 GETA 08h // copy PinOffset|000000000000 into A OFFSET0 // subtract the “derived PIN” from the PIN offset MOV_A_B0 // store the calculated PIN into B0 CLRA GETPIN0 // get PIN digits into A (from the left) CMPA_B0 // compare PINs, exit on error if different EOM 00h // return no data but the status=0 (successful execution) // // ``` **Interac Scheme for Canada** This example has been moved to a specific document: VeriShield Security Script for CIBC version 1.0. **APACS40 for Poland** The analysis below is based on the SPRD of SC552 CROATIA that is compliant with the APACS40 standard. The Security Script implementation given here is intended to demonstrate the capability to support the APACS40 requirements and should not be considered as the exact final command flow. *1 - Key injection with mutual authentication.* Assumption: MLK is loaded in blocks `#00` and `#01` and we can load any key from block `#00` to `#04` (MLKL,MLKR, SK, SRKL, SRKR). We will use two macros and chain them together. ```cpp // // MACRO 10h // Authentication step 1 SID 0000h 2568h 0000h // set SID to 2568 on successful completion LENGTH 0008h // 8-byte random from the host (RNDh) GETA 00h // copy the random into A SELECT 00h // select MLKL EECB // ECB DES encryption, result into A SELECT 01h // select MLKR DECB // ECB DES decryption, result into A SELECT 00h // select MLKL EECB // ECB DES encryption, result into A LSRA 28h // LSLA 28h // keep only the first 3 bytes SENDA 00 // copy the result into the communication buffer RNDA // generate a random into A (RNDs) SENDA 03h // copy RNDs into the communication buffer MOV_A_IV // save A into IV (IV content is retained after EOM) EOM 0Bh // return 11 bytes (3RESs + RNDs) The host verifies the cryptogram computed by the PINpad. The host sends a cryptogram based on the PINpad’s random number MACRO 11h // Authentication step 2 + Key loading SID 2568h 0000h 0000h // executable only if SID is 2568 LENGTH 000Ch // 3-byte cryptogram (3RESh) + Key Index + 8-byte CMKEY GETX 03h // copy the Key Index into Index Register X TSTXI 00h 04h // verify that the Key Index is in the range [20..24] MOV_IV_A // retrieve RNDs from IV CLRIV // clear IV SELECT 00h // select MLKL EECB // ECB DES encryption, result into A SELECT 01h // select MLKR DECB // ECB DES decryption, result into A SELECT 00h // select MLKL EECB // ECB DES encryption, result into A LSRA 28h // LSLA 28h // keep only the first 3 bytes MOV_A_B0 // save the computed value into B0 for comparison GETA 00h // copy 3RESs into A LSRA 28h // keep only the LSLA 28h // first 3 bytes CMPA_B0 // compare the cryptograms, exit if it fails GETA 04h // copy CMKEY into A SELECT 00h // select MLKL DECB // ECB DES decryption, result into A SELECT 01h // select MLKR EECB // ECB DES encryption, result into A SELECT 00h // select MLKL DECB // ECB DES decryption, result into A STAX // store MKEY into the location pointed by X EOM 00h // the end - nothing to return ``` *2 - Derivation of the transaction keys:* Assumption: Transaction Key Register (TKR) is in block `#05`, PIN KEY in block `#06` and MAC KEY in block `#07`. ```cpp // // MACRO 12h // Key Derivation LENGTH 0020h // 4 8-byte fields: B|A, A|B, A|C and B|D LDAI B5E37FC5D4F7A393 // this is the fixed value Y MOV_A_B1 // store value Y into B1 LDA 05h // copy TKR into A XORA_B1 // XOR TKR with value Y MOV_A_B1 // store the derived TKR into B1 SELECTA // and also select it for the next computation LDAI A5C7B2828476A829 // this is the fixed value X MOV_A_B0 // store value X into B0 GETA 00h // copy field B|A into A XORA_B0 // and XOR it with value X MOV_A_B0 // save the result of the XOR into B0 EECB // ECB DES encryption, result into A XORA_B0 // XOR it with the input data - End of the OWF STA 07h // This is MAC KEY, store it in block #07 // LDAI A5C7B2828476A829 // this is the fixed value X MOV_A_B0 // store value X into B0 GETA 08h // copy field A|B into A XORA_B0 / and XOR it with value X MOV_A_B0 // save the result of the XOR into B0 EECB // ECB DES encryption, result into A XORA_B0 // XOR it with the input data - End of the OWF XORA_B1 // XOR KEYVAL with value Y MOV_A_B0 // store result into B0 // GETA 10h // copy field A|C into A XORA_B1 // and XOR it with value Y SELECTA // and select it for the next computation LDAI A5C7B2828476A829 // this is the fixed value X MOV_A_B1 // store value X into B1 GETA 18h // copy field B|D into A XORA_B1 // and XOR it with value X MOV_A_B1 // save the result of the XOR into B1 EECB // ECB DES encryption, result into A XORA_B1 // XOR it with the input data - End of the OWF MOV_A_B1 // this is CARD KEY, store it into B1 // MOV_B0_A // retrieve the result of KEYVAL XOR Y SELECTA // and select it for the next computation LDAI A5C7B2828476A829 // this is the fixed value X XORA_B1 // XOR value X with CARD KEY MOV_A_B1 // save the result of the XOR into B1 EECB // ECB DES encryption, result into A XORA_B1 // XOR it with the input data - End of the OWF STA 06h // This is PIN KEY, store it in block #06 EOM 00h // the end - nothing to return ``` **RSA computation** The macro `#10h` loads the RSA key in key slot `#4`. The macro `#11h` selects the key `#4` and performs the RSA computation. The two macros are chained. The format of the input buffer for the macro `#10h` must be as follows: **2048-bit keys:** * byte 0: Key type, 0 or EMV value * bytes 1..6: Don't care * byte 7: modulus length in bytes (use 0 for 2048-bit modulus) * byte 8: exponent length in bytes (use 0 for 2048-bit private exponent) * bytes 9..x: the modulus. x = 9+modulus length -1 * byte x+1..y:: the exponent. y = 9+modulus length+exponent length-1 **4096-bit and 3072-bit keys:** * byte 0: Key type, 1 * bytes 1..6: Don't care * byte 7: modulus length byte 1 (02 for 512 bytes) * byte 8: modulus length byte 2 (00 for 512 bytes) * byte 9: exponent length byte 1 * byte 10: exponent length byte 2 * bytes 11..x: the modulus. x = 11+modulus length -1 * byte x+1..y:: the exponent. y = 11+modulus length+exponent length-1 The size of the modulus for the SC 5000 must be at least 8 bytes, multiple of 4 bytes. It can be left-padded with zeros if needed. For other devices, see the programmer reference manual. ```cpp // // CONFIGURATION SECTION // SUBDEV 03h // Script Identifier (Script Slot #3) SCRIPT RsaTest1 // Identifier for this test script// // // KEY DEFINITION SECTION // DEF_BLK 0 0 // no block defined // // // MACRO COMMAND DEFINITION SECTION // MACRO 10h SID 0 5692h 0 GETW 0 521 STRSA 4 EOM 0 // // MACRO 11h SID 5692h 0 0 SELRSA 4 GETW 0 256 RSACOMP SENDW 0 256 EOM 256 // // ``` **Branching macro example** ```cpp // // CONFIGURATION SECTION // SUBDEV 00h // Script Identifier (Sub-device #0) SCRIPT Tst0v2op // Identifier for Test part 0 version 2 OP codes Security Script PP1000_OFF // PP1000 commands are disabled MS_OFF // Default M/S commands are disabled DUKPT_OFF // Default DUKPT commands are disabled // // // KEY DEFINITION SECTION // DEF_BLK 28h 0 // Define 40 (28h) 8-byte blocks. None of them can be loaded // using the default key loading commands. CIBC uses a // specific key loading scheme. // LD_BLK 27h 0123456789ABCDEF // Not a secret value. Flag used to indicate // whether the password has been loaded or not. // Right after the script loading, block #27h // is the only valid block. // // MACRO COMMAND DEFINITION SECTION // MACRO 16 // Test BRA LENGTH 0 LDAI 4252412000000000 // "BRA " SENDA 0 LDAI 5041535300000000 // "PASS" BRA PASS LDAI 2A4641494C2A0000 // "*FAIL*" PASS: SENDA 4 // Put PASS/FAIL in Comm Buffer EOM 128 // Return Results // // MACRO 17 // Test CMPA_BEQ index label LENGTH 0 LDAI 4946203D54414B45 // "IF =TAKE" SENDA 0 LDAI 204252414E434820 // " BRANCH " SENDA 8 LDAI 123456781234FF78 STA 0 CMPA_BEQ 0 PASS LDAI 2A4641494C2A0D0A // "*FAIL*\r\n" BRA FAIL PASS: LDAI 5041535320200D0A // "PASS \r\n" FAIL: SENDA 16 // Put PASS/FAIL in Comm Buffer LDAI 4946203E20204E4F // "IF > NO" SENDA 24 LDAI 204252414E434820 // " BRANCH " SENDA 32 LDAI 123456781234FF79 CMPA_BEQ 0 FAIL1 LDAI 5041535320200D0A // "PASS \r\n" BRA PASS1 FAIL1: LDAI 2A4641494C2A0D0A // "*FAIL*\r\n" PASS1: SENDA 40 // Put PASS/FAIL in Comm Buffer LDAI 4946203C20204E4F // "IF < NO" SENDA 48 LDAI 204252414E434820 // " BRANCH " SENDA 56 LDAI 123456781234FE77 CMPA_BEQ 0 FAIL2 LDAI 5041535300000000 // "PASS" BRA PASS2 FAIL2: LDAI 2A4641494C2A0000 // "*FAIL*" PASS2: SENDA 64 // Put PASS/FAIL in Comm Buffer EOM 128 // Return Results // // ``` ### Loading VSS keys in X9SWKB format **Source code for complete solution (VSS scripts + test code) can be found** [**here**](https://bitbucket.verifone.com:8443/projects/ADVTOOLS/repos/poc-vss-x9swkb/browse) #### Introduction This document provides code samples to implement secure key block unwrapping using the X9SWKB format according to ANSI X9.143-2021 Interoperable Secure Key Exchange Key Block Specification for VOS1/VOS2 platforms using VSS macros. The main use case will be unwrapping session keys conveyed in key block form e.g., for PIN, data, or MAC, using a pre-loaded KBPK. It can be also used to load other KBPKs (or update the same), or KEKs. Samples of both TDEA and AES key derivation binding methods are provided. Legacy key variant methods are not provided as they are not allowed by PCI requirements. The code samples for the key unwrapping process include VSS macros and open side code as the processing need to be split between these two processing elements. The code samples are not complete, i.e., that the application developer can use the samples as starting point and need to complete and tailor according to the specific needs. #### Loading KBPK key This sample demonstrates KBPK loading in plaintext format. However, there are several ways available to perform KBPK loading: * VRK and VRKv2 key loading * Self-update of the KBPK using X9SWKB * Under VSS\_KLK in case if only used as KBPK and for 2TDEA key block binding * Plaintext key injection using customer specific injection protocol #### Implementation details This sample implementation includes the following steps: 1. KBPK key loading in plaintext 2. KBH loading 3. Loading RCVD\_MAC 4. KBEK and KBAK key derivation 5. Confidential data decryption with plaintext data returned to user space (optional) 6. MAC calculation 7. MAC verification 8. 2TDEA Working Key (Session Key) loading into VSS slots or DUKPT Initial Key loading into VSS slots 9. Further operations with the loaded keys - Working Key decryption with the Master Key, PIN encryption sample macros for TDEA DUKPT, key loading into AES DUKPT engine for AES DUKPT key #### Implementation details * The implementation doesn't include block parsing and verification. This must be done by the developer and can be done in user space * The implementation doesn't include proper key obfuscation padding handling (while it's present in the key data). This can be done in user space * On key block confidential data decryption, instead of returning plaintext data from VSS to user space it's possible to save data in VSS slots directly to not expose the data. The corresponding VSS macros (ALGO\_CBC\_DECRYPT\_ITER and LOAD\_SK\_KEY\_KB) must be adjusted by the developer in this case. * This implementation acquires the plaintext SK by decrypting the loaded WK with MK provided in plaintext. Same as KBPK, MK can also be loaded via VRK, VSS\_KLK or custom scheme. As for usage, plaintext key returned to the user space can be used for further injection of the key into AESDUKPT engine. If the unwrapped key stays in the VSS plain it can be used for encryption (PIN, data or MAC) using VSS macros. * This implementation doesn't provide macro for obtaining KBH to user space, but it can be easily achieved via VSS + API call * The script samples are made for following key derivation algorithms: * 2TDEA * 3TDEA * AES-128 * AES-256 * The above implementations can be used as a guide to implement DEA and AES-192 * The data storage for keys, KBH, KBPK and MAC use pre-allocated VSS script slots * The script developer must know the sizes of the KBPK, KBH, keys, MAC to be able to designate enough data blocks * All data is processed in 8 byte blocks (VSS slots) #### TDEA Key Derivation Binding (ID 'B') VSS Script sources: [2TDEA](https://bitbucket.verifone.com:8443/projects/ADVTOOLS/repos/poc-vss-x9swkb/browse/scripts/vss_x9swkb_2tdea.vss) [3TDEA](https://bitbucket.verifone.com:8443/projects/ADVTOOLS/repos/poc-vss-x9swkb/browse/scripts/vss_x9swkb_3tdea.vss) **KBPK loading** KBPK is loaded in plaintext using the data loading function: ```cpp std::vector kbpk_key = { 0xDD, 0x75, 0x15, 0xF2, 0xBF, 0xC1, 0x7F, 0x85, 0xCE, 0x48, 0xF3, 0xCA, 0x25, 0xCB, 0x21, 0xF6 }; /* Loading KBPK */ ret = loadData(TDEA2_SCRIPT_ID, kbpk_key, KBPK_FIRST_SLOT, kbpk_key.size() / DATABLOCK_SIZE); CHECK_EQUAL(0, ret); ``` **KBH loading** KBH is loaded into dedicated VSS slots using the data loading function: ```cpp static std::string key1_x9swkb = "B0096P0TE00E0000" "94B420079CC80BA3461F86FE26EFC4A38C6B0A146BF1B0BE0D3277F17A3AD514" "6EED7B727B8A248E"; std::string key1_kbh = key1_x9swkb.substr(0, 16); std::vector key1_kbh_bytes = hexToBytes(key1_kbh); /* Loading KBH */ ret = loadData(TDEA2_SCRIPT_ID, key1_kbh_bytes, KBH1_FIRST_SLOT, key1_kbh_bytes.size() / DATABLOCK_SIZE); CHECK_EQUAL(0, ret); ``` **RCVD\_MAC loading** ```cpp std::string key1_mac = key1_x9swkb.substr(80, 16); std::vector key1_mac_bytes = hexToBytes(key1_mac); /* Loading RCVD_MAC */ ret = loadData(TDEA2_SCRIPT_ID, key1_mac_bytes, RCVD_MAC_FIRST_SLOT, key1_mac_bytes.size() / DATABLOCK_SIZE); CHECK_EQUAL(0, ret); ``` **KBEK and KBAK key derivation** KBEK and KBAK are derived in the VSS via macro. The API call for the derivation doesn't need any input or output data parameters: ```cpp /* Derive KBEK and KBAK from KBPK */ ret = iPS_ExecuteScript(TDEA2_SCRIPT_ID, TDEA2_DERIVE_KBAK_KBEK, 0, NULL, 0, NULL, NULL); CHECK_EQUAL(0, ret); ``` **Confidential data decryption** This process performs the iterative decryption of the confidential data of the secure key block in CBC mode using the MAC as IV. Before decryption IV is set to MAC value loaded in previous step. ```cpp /* Set MAC as IV for decryption */ ret = iPS_ExecuteScript(TDEA2_SCRIPT_ID, TDEA_CBC_SET_MAC_AS_IV, 0, NULL, 0, NULL, NULL); CHECK_EQUAL(0, ret); /* Decrypt data iteratively */ std::vector key1_dec_bytes; ret = decryptData(TDEA2_SCRIPT_ID, TDEA2_CMAC_ITER, TDEA_BLOCK_SIZE, key1_key_bytes, key1_dec_bytes); CHECK_EQUAL(0, ret); ``` **MAC verification** MAC verification is done in two parts: first is iterative MAC calculation on n - 1 data blocks, then the last block is passed into another macro for MAC finalizing and comparison with RCVD\_MAC. ```cpp /* Verify MAC iteratively */ std::vector mac_input_bytes; mac_input_bytes.insert( mac_input_bytes.end(), key1_kbh_bytes.begin(), key1_kbh_bytes.end()); mac_input_bytes.insert( mac_input_bytes.end(), key1_dec_bytes.begin(), key1_dec_bytes.end()); /* For TDEA CMAC IV is used as a temporary buffer */ ret = iPS_ExecuteScript(TDEA2_SCRIPT_ID, IV_CLEAR, 0, NULL, 0, NULL, NULL); CHECK_EQUAL(0, ret); ret = verifyMAC(TDEA2_SCRIPT_ID, TDEA2_CMAC_ITER, TDEA2_CMAC_CMP, TDEA_BLOCK_SIZE, mac_input_bytes); CHECK_EQUAL(0, ret); ``` **2TDEA Working Key (Session Key) loading into VSS slots** ```cpp /* Load WK from decrypted confidential part to VSS */ ret = iPS_ExecuteScript(TDEA2_SCRIPT_ID, LOAD_SK_KEY_KB, key1_dec_bytes.size(), key1_dec_bytes.data(), 0, NULL, NULL); CHECK_EQUAL(0, ret); ``` **Working Key decryption with the plaintext Master Key** ```cpp /* Get SK by decrypting WK with MK */ std::vector session_key(2 * TDEA_BLOCK_SIZE); unsigned short out_size = 0; ret = iPS_ExecuteScript(TDEA2_SCRIPT_ID, TDEA2_ECB_WK_DECRYPT, master_key.size(), master_key.data(), session_key.size(), &out_size, session_key.data()); CHECK_EQUAL(0, ret); ``` #### AES Key Derivation Binding (ID 'D') VSS Script sources: [AES-128](https://bitbucket.verifone.com:8443/projects/ADVTOOLS/repos/poc-vss-x9swkb/browse/scripts/vss_x9swkb_aes128.vss) [AES-256](https://bitbucket.verifone.com:8443/projects/ADVTOOLS/repos/poc-vss-x9swkb/browse/scripts/vss_x9swkb_aes256.vss) **KBPK loading** KBPK is loaded in plaintext using the data loading function: ```cpp std::vector kbpk_key = { 0xDD, 0x75, 0x15, 0xF2, 0xBF, 0xC1, 0x7F, 0x85, 0xCE, 0x48, 0xF3, 0xCA, 0x25, 0xCB, 0x21, 0xF6 }; /* Loading KBPK */ ret = loadData(AES128_SCRIPT_ID, kbpk_key, KBPK_FIRST_SLOT, kbpk_key.size() / DATABLOCK_SIZE); CHECK_EQUAL(0, ret); ``` **KBH loading** KBH is loaded into dedicated VSS slots using the data loading function: ```cpp static std::string key2_x9swkb = "D0160K0AE00N0200LB0BAES_KEYPB050" "3F89491AE7D048A64361CB2A500FA35CBA0DD6D1368A0CA4F8D9C8E136A69DFEA19EECFF9F83699257A21066EEA5502E" "F5BA53A8C756450F5CA47505C17D15D8"; std::string key2_kbh = key2_x9swkb.substr(0, 32); std::vector key2_kbh_bytes = hexToBytes(key2_kbh); /* Loading KBH */ ret = loadData(AES128_SCRIPT_ID, key2_kbh_bytes, KBH2_FIRST_SLOT, key2_kbh_bytes.size() / DATABLOCK_SIZE); CHECK_EQUAL(0, ret); ``` **RCVD\_MAC loading** ```cpp std::string key2_mac = key2_x9swkb.substr(80, 16); std::vector key2_mac_bytes = hexToBytes(key2_mac); /* Loading RCVD_MAC */ ret = loadData(TDEA2_SCRIPT_ID, key2_mac_bytes, RCVD_MAC_FIRST_SLOT, key2_mac_bytes.size() / DATABLOCK_SIZE); CHECK_EQUAL(0, ret); ``` **KBEK and KBAK key derivation** KBEK and KBAK are derived in the VSS via macro. The API call for the derivation doesn't need any input or output data parameters: ```cpp /* Derive KBEK and KBAK from KBPK */ ret = iPS_ExecuteScript(AES128_SCRIPT_ID, AES128_DERIVE_KBAK_KBEK, 0, NULL, 0, NULL, NULL); CHECK_EQUAL(0, ret); ``` **Confidential data decryption** This process performs the iterative decryption of the confidential data of the secure key block in CBC mode using the MAC as IV. Before decryption IV is set to MAC value loaded in previous step. ```cpp /* Set MAC as IV for decryption */ ret = iPS_ExecuteScript(AES128_SCRIPT_ID, AES_CBC_SET_MAC_AS_IV, 0, NULL, 0, NULL, NULL); CHECK_EQUAL(0, ret); /* Decrypt data iteratively */ std::vector key2_dec_bytes; ret = decryptData(AES128_SCRIPT_ID, AES128_CBC_DECRYPT_ITER, AES_BLOCK_SIZE, key2_key_bytes, key2_dec_bytes); CHECK_EQUAL(0, ret); ``` **MAC verification** MAC verification is done in two parts: first is iterative MAC calculation on n - 1 data blocks, then the last block is passed into another macro for MAC finalizing and comparison with RCVD\_MAC. ```cpp /* Verify MAC iteratively */ std::vector mac_input_bytes; mac_input_bytes.insert( mac_input_bytes.end(), key2_kbh_bytes.begin(), key2_kbh_bytes.end()); mac_input_bytes.insert( mac_input_bytes.end(), key2_dec_bytes.begin(), key2_dec_bytes.end()); ret = verifyMAC(AES128_SCRIPT_ID, AES128_CMAC_ITER, AES128_CMAC_CMP, AES_BLOCK_SIZE, mac_input_bytes); CHECK_EQUAL(0, ret); ``` **2TDEA Working Key (Session Key) loading into VSS slots** ```cpp /* Load WK from decrypted confidential part to VSS */ ret = iPS_ExecuteScript(AES128_SCRIPT_ID, LOAD_SK_KEY_KB, key2_dec_bytes.size(), key2_dec_bytes.data(), 0, NULL, NULL); CHECK_EQUAL(0, ret); ``` **Working Key decryption with the plaintext Master Key** ```cpp /* Get SK by decrypting WK with MK */ std::vector session_key(2 * TDEA_BLOCK_SIZE); unsigned short out_size = 0; ret = iPS_ExecuteScript(AES128_SCRIPT_ID, TDEA2_ECB_WK_DECRYPT, master_key.size(), master_key.data(), session_key.size(), &out_size, session_key.data()); CHECK_EQUAL(0, ret); ``` #### TDEA DUKPT key loading VSS Script source: [2TDEA DUKPT](https://bitbucket.verifone.com:8443/projects/ADVTOOLS/repos/poc-vss-x9swkb/browse/scripts/vss_x9swkb_dukpt_2tdea.vss) **Key unwrapping** In this example, AES-128 Key Derivation Binding is used, so the key is unwrapped in the way described in the [AES Key Derivation Binding](#aes_deriv) section. KSN must be parced from KBH. ```cpp static std::string tdea2_dukpt_x9swkb = "D0192B1TX00N0500KS1800604B120F9292800000KP1001D77F007724KC0C0057C409TS1320241008034229ZPB0900000" "7FD21FD44DBD73E8D50C7E7B7BC6D943BCA428E15607D128491D633B9E6323CF" "FFA45C04269AC320969D21731B9978FD" std::string tdea2_kbh = tdea2_x9swkb.substr(0, 96); std::string ksn = tdea2_kbh.substr(20, 20); std::vector ksn_bytes = hexToBytes(ksn); ``` **KSN and key loading into VSS** To load KSN, it should be passed into VSS via the VSS API from dedicated KBH field. Key loading is performed by passing the decrypted confidential data to VSS macro. ```cpp /* Load IK from decrypted confidential part to VSS */ ret = iPS_ExecuteScript(TDEA2_DUKPT_SCRIPT_ID, LOAD_IK_KEY_KB, tdea2_dec_bytes.size(), tdea2_dec_bytes.data(), 0, NULL, NULL); CHECK_EQUAL(0, ret); /* Load KSN */ ret = iPS_ExecuteScript(TDEA2_DUKPT_SCRIPT_ID, TDEA2_DUKPT_LOAD_KSN, ksn_bytes.size(), ksn_bytes.data(), 0, NULL, NULL); CHECK_EQUAL(0, ret); ``` **Next Key generation** Next Key and KSN are generated by one call, KSN is returned by the API. It should be saved for next generation iteration. ```cpp /* Generate next key */ unsigned char returned_ksn[KSN_LENGTH] = {0}; unsigned short outlen; ret = iPS_ExecuteScript(TDEA2_DUKPT_SCRIPT_ID, TDEA2_DUKPT_GEN_KEYS, 0, NULL, KSN_LENGTH, &outlen, ksn); CHECK_EQUAL(0, ret); CHECK_EQUAL(KSN_LENGTH, outlen); ``` **MAC calculation** For MAC calculation, common functions can be used with corresponding scripts. ```cpp std::string msg = "0123456789ABCDEFFEDCBA9876543210"; std::vector msg_bytes = hexToBytes(msg); std::vector msg_input_bytes; msg_input_bytes.insert( msg_input_bytes.end(), msg_bytes.begin(), msg_bytes.end()); ret = verifyMAC(TDEA2_DUKPT_SCRIPT_ID, TDEA2_DUKPT_MAC_TDEA_REQUEST, TDEA2_DUKPT_MAC_3TDEA_REQUEST, TDEA_BLOCK_SIZE, msg_input_bytes); CHECK_EQUAL(0, ret); ``` Data and PIN encryption Data encryption should be performed iteratively, in the same manner as MAC calculation. See 2TDEA\_DUKPT\_ENCRYPT\_DATA\_REQ and 2TDEA\_DUKPT\_ENCRYPT\_DATA\_RESP macros. PIN encryption has a dedicated macro for that ```cpp unsigned char buffer[KEY_SLOT_SIZE + KSN_LENGTH]; unsigned char epb[MAX_PIN_LENGTH], pin[MAX_PIN_LENGTH]; unsigned short outlen = 0; /* Arguments for PIN entry on VATS device */ int iStatus = PIN_IDLE; char enter_key[1] = {VATS_KEY_ENTER}; PINPARAMETER pinparam; PINRESULT result; /* Perform PIN entry on VATS device */ memset(&pinparam, 0, sizeof(pinparam)); /* Set the values of PINPARAMETER vector */ pinparam.ucMin = 4; pinparam.ucMax = 8; pinparam.ucEchoChar = '*'; pinparam.ucDefChar = 0; pinparam.ucOption = 0; ret = iPS_SelectPINAlgo(VSS_PIN); if (!ret) { iPS_CancelPIN(); ret = iPS_SetPINParameter(&pinparam); VFLOG_INFO("%s: Request PIN entry\n", __func__); if (!ret) { ret = iPS_RequestPINEntry(0, NULL); } } if (!ret) { for(int i = 0; i < (int)strlen(test_pin); i++) { /* Adding artificial delay of 250ms to allow process key, and imitating real pin entry.*/ usleep(250000); VATS_InjectKeys(&test_pin[i], 1); VFLOG_INFO("PIN Digit Entered: %c \n", test_pin[i]); } /* Delay before pin "enter" key. */ usleep(250000); VATS_InjectKeys(enter_key, 1); while(iStatus != PIN_DONE) ret = iPS_GetPINResponse(&iStatus, &result); } CHECK_EQUAL(0, ret); if (ret == 0) { VFLOG_INFO("%s: PIN Entered successfully!\n", __func__); memset(buffer, 0, sizeof(buffer)); outlen = (strlen(pan) - 1) / 2 + (strlen(pan) - 1) % 2; SVC_DSP_2_HEX (pan, &buffer[DATA_BLOCK_SIZE - outlen], outlen); outlen = 0; /* * PIN Encryption (ANS X9.8). * When PIN entry is complete, put 8 bytes of account data in epb. */ ret = iPS_ExecuteScript(TDEA2_DUKPT_SCRIPT_ID, 2TDEA_DUKPT_ENCRYPT_PIN, sizeof(pan), buffer, MAX_PIN_LENGTH, &outlen, epb); CHECK_EQUAL(0, ret); /* if EPB returned correctly, check if it can be decrypted with dukInitKey & current KSN */ if (ret == 0) { CHECK_EQUAL(MAX_PIN_LENGTH, outlen); VFLOG_INFO("%s: EPB verified okay!\n", __func__); print_hex("EPB", epb, outlen); memset(buffer, 0, sizeof(buffer)); ret = duk_decrypt_pin(epb, ksn, pin); CHECK_EQUAL(0, ret); if (ret == 0) { VFLOG_INFO("%s: EPB decrypted successfully!\n", __func__); CHECK_EQUAL(0, memcmp(test_pin, pin, strlen(test_pin))); VFLOG_INFO("%s: Decrypted PIN verified successfully!\n", __func__); } else { VFLOG_INFO("%s: EPB decryption failed!\n", __func__); } } else { VFLOG_INFO("%s: EPB verification failed!\n", __func__); } } else { VFLOG_INFO("%s: PIN entry failed!\n", __func__); } ``` #### AES DUKPT key loading VSS Script source: [AES-128 DUKPT](https://bitbucket.verifone.com:8443/projects/ADVTOOLS/repos/poc-vss-x9swkb/browse/scripts/vss_x9swkb_aes128_dukpt.vss) **Key unwrapping** In this example, AES-128 Key Derivation Binding is used, so the key is unwrapped in the way described in the [AES Key Derivation Binding](#aes_deriv) section **Key loading into VSS** VSS does not support AES DUKPT. Therefore, the key can be unwrapped but further operations are impossible. After unwrapping, key loading is performed by passing the decrypted confidential data to VSS macro. The VSS macro returns the key to user side so it can be passed into AES DUKPT engine. ```cpp /* Load IK from decrypted confidential part to VSS */ unsigned char returned_initial_key[AES_BLOCK_SIZE] = {0}; unsigned short outlen; ret = iPS_ExecuteScript(AES128_DUKPT_SCRIPT_ID, LOAD_IK_KEY_KB, aes128_dec_bytes.size(), aes128_dec_bytes.data(), AES_BLOCK_SIZE, &outlen, returned_initial_key); CHECK_EQUAL(0, ret); /* Load initial key into vfiSec AES DUKPT engine */ unsigned int flags = 0; // Define your flags here err = vfiSec_load_aesdukpt_initial_key(returned_initial_key, AES_BLOCK_SIZE, iksn.data(), 1, "Test_AES_DUKPT", aes128_kbh.data(), aes128_kbh.size(), flags); ``` #### Common functions This is a common function that allows loading data iteratively into VSS slots. Each VSS API call consists of 1 byte of slot index and 8 bytes of data. This can be used for plaintext KBPK, KBH and received MAC loading. ```cpp int loadData(int scriptId, std::vector & data, int firstSlot, int blockCount) { std::vector::iterator it = data.begin(); int ret = 0; for (int i = 0; i < blockCount; i++) { std::vector block(DATABLOCK_SIZE); block.assign(it, it + DATABLOCK_SIZE); block.insert(block.begin(), firstSlot + i); ret = iPS_ExecuteScript(scriptId, LOAD_DATA_ITERATION, block.size(), block.data(), 0, NULL, NULL); if (ret) break; it += DATABLOCK_SIZE; } return ret; } ``` This is a common function that performs data decryption iteratively. The data block size depends on the algorithm. Before data decryption, macro that sets MAC as IV should be called. ```cpp int decryptData(int scriptId, int macroId, int blockSize, std::vector & data, std::vector & outData) { std::vector::iterator it = data.begin(); int ret = 0; for (unsigned int i = 0; i < data.size() / blockSize; i++) { std::vector enc_block(blockSize); std::vector dec_block(blockSize); unsigned short out_size = 0; enc_block.assign(it, it + blockSize); ret = iPS_ExecuteScript(scriptId, macroId, blockSize, enc_block.data(), blockSize, &out_size, dec_block.data()); if (ret != 0 || out_size != blockSize) break; outData.insert( outData.end(), dec_block.begin(), dec_block.end()); it += blockSize; } return ret; } ``` This function is used for MAC calculation verification iteratively and verifies MAC on the last step. The data block size depends on the algorithm. Both calculation and verification macro IDs must be provided. ```cpp int verifyMAC(int scriptId, int iterMacroId, int cmpMacroId, int blockSize, std::vector & data) { int ret = 0; std::vector::iterator it = data.begin(); std::vector block(blockSize); for (unsigned int i = 0; i < (data.size() / blockSize) - 1; i++) { block.assign(it, it + blockSize); ret = iPS_ExecuteScript(scriptId, iterMacroId, blockSize, block.data(), 0, NULL, NULL); if (ret) break; it += blockSize; } if (ret != 0) ret = iPS_ExecuteScript(scriptId, cmpMacroId, blockSize, block.data(), 0, NULL, NULL); return ret; } ``` #### Script with several keys Since key and data storage is hardcoded, one script can contain several keys encrypted with the same KBPK, stored in the predefined slots, i.e: | Key type | Slots | Description | | -------- | ------- | -------------------------------------- | | KBPK | 0 - 3 | From 8 (TDEA) to 32 (AES256) bytes max | | KEY1 KBH | 4 - 15 | 96 bytes max for KBHs with opt blocks | | KEY1 | 16 - 23 | From 8 (TDEA) to 64 (HMAC) bytes max | | KEY2 KBH | 24 - 35 | 96 bytes max for KBHs with opt blocks | | KEY2 | 36 - 43 | From 8 (TDEA) to 64 (HMAC) bytes max | ## Macro Command Execution ### Security Script File Download The file generated by the script-processing tool has a .VSO extension that is recognized by the unit as a VeriShield Security Script file. The .VSO file must be downloaded along with its signature file (P7S) into the unit using the Zontalk protocol. Script files must be signed using signer certificates that have specific "xV" attributes authorizing them to sign scripts. For instance, to load a script in group 13, the file must be signed with a certificate that has the "13V" attribute. Else the authentication will fail. There is a slight difference between the SC 5000 PINpads and Vx terminals regarding the downloads and install process. #### In the SC 5000 PINpads Upon successful authentication by the VeriShield File Authentication module, the script file is automatically installed in the PINpad. It is checked for validity and consistency. If everything is coherent, then the macro commands are stored in the security module and the space for the keys defined in the script are allocated. The script file is then deleted from the file system irrespective of the loading, whether successful or not. Three API functions are available to access the VeriShield Security Scripts from a SC 5000 application: `iPS_GetScriptStatus()` `iPS_ExecuteScript()` `iPS_DeleteScript()` {% hint style="info" %} Please refer to VDN22425 - SC 5000 API for description of those functions. {% endhint %} #### In the Vx Terminals Upon successful authentication by the VeriShield File Authentication module, the script file is not automatically installed in the PINpad. The terminal application must install the script using the `iPS_InstallScript()` function. During the install process the file is checked for validity and consistency. If everything is coherent, then the script is validated and the space for the keys defined in the script are allocated. The script file is not deleted from the file system and should not be deleted or replaced because it would invalidate the script. This difference with the SC 5000 is partly because Vx terminals should support back-to-back downloads. Four API functions are available to access the VeriShield Security Scripts from a Vx application: `iPS_InstallScript()` -- This function installs a script file in the unit. `iPS_GetScriptStatus()` `iPS_ExecuteScript()` `iPS_UninstallScript()` -- This function uninstalls the script but does not delete the script file. #### PIN Sessions In order to perform a PIN session using a macro command, the `iPS_SelectPINAlgo()` API function has to be called with the PinFormat parameter equal to 0Bh. In such a case, once the PIN entry is completed, the PIN is stored into a specific buffer inside the security module. The PIN is then retrieve by the "PIN processing" macro using the GETPINx commands. The PIN is not be accessible at the application level. From the PINpad application the sequence looks like the following: * Setup parameters for the upcoming PIN session: `iPS_PINParameters(…);` * Select PIN algorithm with parameter 0Bh (Store PIN internally for postprocessing by a VeriShield Security Script macro command: `iPS_SelectPINAlgo(0x0B);` * Request PIN Entry: `iPS_RequestPINEntry(0, 0);` * do {Get PIN Response: `iPS_GetPINResponse(…);` } while (not done) * Execute the custom "PIN processing" macro `iPS_ExecuteScript(Script#, Macro#, …);` #### Security Script Library A terminal library could be developed along with each VeriShield Security Script. If this library has the same API as the related SCxxx library, it would ease the application conversion when switching from an SCxxx to another device. ## Tools ### Script Processor (VSS Compiler) The script processor tool takes ASCII script file as an input and generates a binary file to be downloaded into the unit. It also generates a report file (.LOG) containing the results of the last execution. If errors are found, then they are listed in the report file for debugging purposes. If the execution is successful, then some information is reported (number of macros and blocks, code size,...). The engineering version of the VeriShield Security Script Processor Tool is a Win32 console application. The name of the executable is VSSCONV.EXE. The name of the input ASCII file must be passed as parameter. /verbatim C:>VSSCONV libtest VeriShield Security Script Tool version 9.0 - PSVSSv90 - 20200204 Copyright (c) 2001-2020, Verifone, Inc. libtest - 0 error(s). Execution ended normally. /endverbatim After the execution, a report file (.LOG) is generated. /verbatim VeriShield Security Script Tool version 9.0 - PSVSSv90 - 20200204 Copyright (c) 2001-2020, Verifone, Inc. libtest - 0 error(s). Tool Identifier (Max Op Code Version Used): PSVSSv2 Tool Version: 9.0 Script Identifier: 00 hex (00 decimal) Script Name: Tst0v2op PP1000 compatible commands are disabled. Default Master/Session functions are disabled. Default DUKPT functions are disabled. Number of Macros: 2 (2h) Macro Code Size: 237 (EDh) bytes Total number of blocks: 40 (28h) of which 0 (0h) can be loaded using the default key loading functions. Number of pre-loaded blocks: 1 (1h) Execution ended normally. /endverbatim {% hint style="info" %} Before using/loading scripts on ADK upgrade, make sure the appropriate VSSConv verson is used and scripts are re-compiled. Ignoring that requirement may lead to unexpected failures on different stages of loading/processing scripts. {% endhint %} Below is a table of VSSConv/ADK and feature mapping: | VSSConv version | ADK version | Number of 'usr' scripts supported | Number of 'sys' scripts supported | RSA-4096 | | ----------------------- | ---------------- | --------------------------------- | --------------------------------- | ------------- | | VSSConv 6.0, VSSConv7.0 | ADK 4.4, ADK 4.6 | 64 | Not supported | Not supported | | VSSConv 8.0 | ADK 4.7 | 96 | Not supported | Not supported | | VSSConv 9.0 | ADK 4.8 | 96 | 96 | Not supported | | VSSConv 9.1 | ADK 4.8 | 96 | 96 | Supported | ### Signing Tool "VeriShield File Signing Tool" will be used to sign the VeriShield Security Script Object file (.VSO) like every other file to be downloaded into the unit. The only difference is that the Security Script Object files (.VSO) must be signed with certificates that have script signing capabilities. Because of the sensitive nature of the security script files compared to applications, it is required to have distinct certificate attributes for script signing capability and for application/data signing capability. This way it is possible to generate smart cards that have only application signing capability for instance. Like we have attributes "1","2",''3",''4",''5",''6",''7",''9",''10",''11",''12",''13",''14",''15" for applications, we have specific attributes for security scripts. In the SC5000 the script signing attributes for the 15 groups are: "1V","2V",''3V",''4V",''5V",''6V",''7V",''9V",''10V",''11V",''12V",''13V",''14V",''15V" In the Vx terminal the script signing attributes for the 15 groups are: "A",''B",''C",''D",''E",''F",''G",''H",''I",''J",''K",''L",''M",''N",''O" For instance, to load a script in group 13, the file must be signed with a certificate that has the "13V" attribute (for SC 5000) or the "M" attribute (for Vx terminals). If not, even though the signing process seems to work, the authentication in the unit will fail. #### In The SC 5000 PINpad The VeriShield Security Script Object files (.VSO) must be downloaded into the SC 5000 PINpads as code files (option.-e with DDL.EXE or option -i with DL.EXE). example: /verbatim ddl.exe -eLibTest.vso LibTest.vso.p7s /endverbatim ### Key Loading Tool SecureKIT is the Key Loading solution of Verifone. The current version 2.1 of SecureKIT supports a limited set of existing Verifone devices and in most of the cases it cannot be used to load keys defined by a VeriShield Security Script. The next version of SecureKIT should provide a generic interface for key loading. Being programmable devices, SC 5000 and Vx terminals will easily adapt to it at the application level. The application might be different for each customization, (i.e. for each VeriShield Security Script) in order to interface SecureKIT communication packet into customer-specific key loading macro defined in their script. ## VSS Key Installation APIs There are APIs available that allow loading VSS keys encrypted with: * AuthEx key * Custom Asymmetric Key loaded on the device via VRKv2 {% hint style="warning" %} Both of these APIs are vulnerable to the Padding Oracle attack. Use at your own risk. {% endhint %} In both cases, the encryption keys must be installed on the device. ### VSS key encrypted with AuthEx To load the VSS key encrypted with AuthEx key, the following API is available: ```cpp int rsaAuthexVssKeyInstall(int encryption_format, int data_length, unsigned char *encrypted_key, int key_size, unsigned char vss_script_num, unsigned char vss_key_slot); ``` ### VSS key encrypted with Custom Asymmetric key To load the VSS key encrypted with Custom Asymmetric key, the following API is available: ```cpp int customAsymmKeyVssKeyInstall(unsigned char *encrypted_key, int key_size, unsigned char vss_script_num, unsigned char vss_key_slot, const char * custom_key_filen); ``` ## Appendix A: OP Code Table The table below indicates the OP Code value for all the keywords that might generate an execution error. This is the value returned by the `iPS_ExecuteScript()` function when the OP code execution fails. | | | | | ------------------ | --- | --- | | OP Code | Dec | Hex | | EOM | 3 | 03 | | GETA | 4 | 04 | | SENDA | 5 | 05 | | GETX | 6 | 06 | | SENDX | 7 | 07 | | GETW | 8 | 08 | | SENDW | 9 | 09 | | TSTXI | 15 | 0F | | LSLA | 28 | 1C | | LSRA | 29 | 1D | | CMPA\_B0 | 40 | 28 | | CMPA\_B1 | 41 | 29 | | CMPA | 42 | 2A | | CMPAX | 43 | 2B | | SELECT | 45 | 2D | | SELECTX | 47 | 2F | | DELETE | 48 | 30 | | DELETEX | 49 | 31 | | STA | 50 | 32 | | STAX | 51 | 33 | | LDA | 52 | 34 | | LDAX | 53 | 35 | | CHK\_ODD | 56 | 38 | | CHK\_EVEN | 57 | 39 | | GETPINNB | 68 | 44 | | GETPIN0 | 69 | 45 | | GETPIN1 | 70 | 46 | | GETPIN2 | 71 | 47 | | GETPIN3 | 72 | 48 | | SELRSA | 79 | 4F | | SELRSAX | 80 | 50 | | STRSA | 81 | 51 | | STRSAX | 82 | 52 | | RSACOMP | 83 | 53 | | SHAUPDATE | 85 | 55 | | CMPSHA | 88 | 58 | | GETA\_HA\_TO\_BIN | 89 | 59 | | GETX\_HA\_TO\_BIN | 90 | 5A | | SENDA\_BIN\_TO\_HA | 91 | 5B | | SENDX\_BIN\_TO\_HA | 92 | 5C | | CMPA\_BEQ | 108 | 6C | | CMPAX\_BEQ | 109 | 6D | | CMPA\_BNE | 110 | 6E | | CMPAX\_BNE | 111 | 6F | | CMPA\_BGT | 112 | 70 | | CMPAX\_BGT | 113 | 71 | | CMPA\_BLT | 114 | 72 | | CMPAX\_BLT | 115 | 73 | | CMPA\_BGE | 116 | 74 | | CMPAX\_BGE | 117 | 75 | | CMPA\_BLE | 118 | 76 | | CMPAX\_BLE | 119 | 77 | | GETW\_HA\_TO\_BIN | 120 | 78 | | SENDW\_BIN\_TO\_HA | 121 | 79 | | ERR\_RET | 125 | 7D | | INIT\_1DES\_DUKPT | 127 | 7F | | INIT\_3DES\_DUKPT | 128 | 80 | | GET\_DUKPT\_KEY | 129 | 81 | | DELETE\_DUKPT\_KEY | 130 | 82 | | SHA256UPDATE | 132 | 84 | | CMPSHA256 | 135 | 87 | | MAC\_CB | 151 | 97 | | MAC\_CB\_X | 152 | 98 | | EECB\_CB | 153 | 99 | | EECB\_CB\_X | 154 | 9A | | DECB\_CB | 155 | 9B | | DECB\_CB\_X | 156 | 9C | | ECBC\_CB | 157 | 9D | | ECBC\_CB\_X | 158 | 9E | | DCBC\_CB | 159 | 9F | | DCBC\_CB\_X | 160 | A0 | | OAEP | 161 | A1 | : Table 1 OP Code Table ## VSS script failed to load for the script slots over 7 (VOS1) This chapter describes some common problems that occur with VSS and what are the possible reasons/solutions. ### VSS script fails to load There are several reasons why VSS script may fail on installation/loading. The reason now can be found in system logs since logging has been added with ADK 4.8. However, since proper logging is absent in earlier versions, here is a list of possible reasons for failure: | Reason | Solution/description | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | VSS script ID is incorrect |

With VSS v9.0, the maximum VSS script ID is 191 in decimal value. On VSS version 5.0 and higher, maximal script ID is 63 and on VSS version 8.0 and higher maximal script ID is 95.

Note

With ADK 4.8, user limitations are added for VSS script ID values. The slots 0 - 95 are now reserved for 'usr' users and slots 96 - 191 are reserved for 'sys' users. The script with incorrect ID range will fail to install with permission error.

| | Inorrect password is defined in script | In some cases, i.e. when using block retention, a 'password' (RETAIN\_BLK code) must be provided in the script. Make sure that password is correct. The valid password can also be the currently loaded script name. If you are loading the script with the same script ID but use different name, password should still be defined as the old (previous) script name. | | System key (KLK) is not loaded | To perform some initial operations, Key Loading Key aka System key must be present. The KLK can be loaded via *iPS\_LoadSysClearKey()* or *iPS\_LoadSysEncKey()* APIs. Make sure it is present in either clear text or encrypted format. | | Incorrect VSSConv version is used | On different ADK/OS releases different amount of VSS script slots is available. If you switch to newer ADK, **make sure you use the corresponding VSSConv version that is distributed with it and re-compile the scripts** before loading. | | Downgrade to version that does not support script IDs performed | On downgrade to older ADK versions there is possibility that certain script IDs are not supported. There is no way to downgrade and keep scripts with newer IDs on the device. Max script ID value is 63 decimal for all ADK versions older than 4.7, 95 for ADK 4.7 and 191 for ADK 4.8. Any downgrades between these versions may cause script loading problems. | ### VSS keys are wiped after the installation There are two typical cases when the VSS keys are being wiped after the new VSS script is installed: \[TABLE] ### VSS macro fails to execute This is a section mostly for the VSS API *iPS\_ExecuteScript()* usage. Since the API uses a lot of different input parameters, there are several reason why the scripts execution might fail: \[TABLE] ### VSS script package fails to install Aside from the regular Secure installer errors on package installation, there are two specific cases for the VSS packages: \[TABLE] ### VSS scripts not removed by SI The VSS packages are a special case for removal for the SI. If you want to remove the scripts, 'removevss' command should be used in the remove bundle 'remove' file **along with 'removeall' command**. If you use any of them separately, the VSS scripts will not be unregistered. Here is an example of 'remove' file that removes both binary bundle and the VSS scripts that it is using: **'removevss' example:** ```cpp removebundle bndl.vos-bin-usr removeall removevss ``` ## Acronyms Definition | Acronym | Definitions | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AES | Advanced Encryption Standard selected by NIST. | | CBC | Cipher Block Chaining mode, as defined in ANSI X3.106. | | VSS | VeriShield Security Scripts. | | DES | Data Encryption Standard, as defined in ANSI X3.92. | | DUKPT | Derived Unique Key Per Transaction Method as defined in the VISA's POS Equipment Requirement: PIN processing and Data Authentication, International Version 1.0, August 1988. | | ECB | Electronic Code Book mode, as defined in ANSI X3.106. | | MAC | Message Authentication Code, as defined in ANSI X9.19. | | PIN | Personal Identification Number. | | POS | Point-of-Sale. | | PP1000+ | Verifone's PINpad 1000 plus. | | PRD | Product Requirement Document. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/adk_programming_interfaces/pg_vss_documentation/vss_documentation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.