Open

Introduction

Given L2 transaction logs containing APDUs (including SELECT PPSE/PSE!), APDU Extractor produces replayable, Card.txt-formatted text files (.cardtxt), accompanying log files (.cardtxtlog) that provide insight into the execution of the application, and TLV-formatted binary Transaction Related Data (.trd) files that can be fed into ACE-Client.

Core Idea

Get input file(s).

Find a SELECT CAPDU (0X A4 …), infer file syntax used to record all CAPDUs in the log, get all CAPDUs by following syntax.

Between any two CAPDUs, find a SELECT response RAPDU (6F XX …), infer file syntax used to record all RAPDUs in the log, get all RAPDUs by following syntax.

Locate card presentments, unpredictable numbers and transaction related data (TRD) in the APDUs.

Create replayable output file(s).

Requirements

Developed using Python 3.10.0 on Windows.

Also tested briefly with 3.7.8.

There are no other dependencies.

Usage

The program provides a simple CLI, and understands four types of commands: version, help, file/folder and test.

Run “python main.py version” to get version information.

Run “python main.py help” to get help on program usage.

Open

How to Extract APDUs

The third command type, “file/folder”, denote the two modes (<MODE>) APDU Extractor can execute in. Usage information displayed in the help screen pertains mostly to these two modes.

The two arguments below are exactly the same for both modes:

<DEFAULT_TECHNO>: When the program notices the first card presentment in an input file, but is unable to determine the technology (contact/contactless), the value of this parameter is used instead. For any new presentments where technology can’t be determined, the technology of the first presentment is used.

<LOG>: The program uses Python’s “logging” module to create .cardtxtlog files that accompany .cardtxt files. When the value of this parameter is ‘2', all logs (level “logging.DEBUG” and up) are enabled. When it is ‘1’, only essential logs (level “logging.INFO” and up) are enabled. When it is '0’, no .cardtxtlog files are produced. In any case, there will be some console output like shown in “File Mode Example” and “Folder Mode Example“ images.

File/Folder Commands

File Mode

Extracts APDUs from a single input file.

<MODE> is, naturally, ‘file’.

Expects a <PATH> like C:\DevWork\apduExtractor\logs\eval_amex_ONLINE_PROC_82_evalLog.txt, in double quotes.

<EXTENSION> is required, but discarded. Just type ‘all’.

Open

File Mode Example

Folder Mode

Extracts APDUs from multiple files in a folder, doesn’t go into subfolders.

<MODE> is, naturally, ‘folder’.

Expects a <PATH> like C:\DevWork\apduExtractor\logs, in double quotes.

<EXTENSION> is used to select a subset of files in the folder. Type ‘all’ to select all files, or if files don’t have file extensions. In the screenshot below, ‘all' selects 24 files, while in the example that follows ‘.log’ selects only 3.

Test Command

It’s recommended to run this command after code modifications to check that the program still generates correct outputs given the same set of inputs.

Run “python main.py test” to have the program generate .cardtxt files from a particular set of EMV log files. (testbenches folder)

Then, the program goes on to compare its output to a list of .cardtxt files generated manually based on the aforementioned EMV logs. (references folder)

If file counts don’t match, or there are differences in file contents, the test fails.

In this case four problems might have occurred:

1. Changes in code have broken the program.

2. Reference files were incorrect and need modification.

3. Testbenches have been corrupted.

4. TestMode.FILES list in test_mode.py didn’t match the actual file system hierarchy.

In the first example below, a bogus file named “fileToBeRemoved” is placed in the references folder, but not in testbenches. Thus, the program fails to create a .cardtxt for it, and the test fails.

In the second example, that file has been removed, and the test passes.

Additional Logs

Some methods take a suppress_errors parameter. If more logs are needed, this parameter could be set to False.

Limitations

Partial Logs

The program makes the assumption that an EMV log will contain at least one SELECT PSE or PPSE (C-APDU) and a SELECT response (R-APDU). If these two aren’t present in a log file, or the lines that contain them are written in a different manner than that of the remaining APDUs, the program will not work correctly.

Single Output for Single Input

There may be multiple transactions in one test log, like AMEX logs from EVAL and EVAL+ which may contain 1 transaction each for 4 different transaction modes (EMV, Magstripe, Mobile EMV, Mobile Magstripe). For such logs, APDU Extractor will generate a single .cardtxt and write 4 at the top.

Single TRD for Multiple Transactions

The program doesn’t create different .trd files for different presentments in one log file. Thus, if TRD parameters like “Amount, Authorized” change between presentments, ACE-Client should be manually updated. The list of TRD tags that we search for are below:

"9F02", "9F03", "5F2A", "9F21", "9A", "9C"

Notes

Accompanying Log Files (.cardtxtlog)

Useful for getting alternative Unpredictable Numbers (UN).

For example, in this log, we see that there were four card presentments with different UNs in PDOLs and CDOL1’s. The last four lines show that for all of these presentments, the program chose to use the CDOL1 UN in the resulting .cardtxt.