github.com/spensercai/nfc_apdu_runner/tools/ResponseDecoder

APDU Response Decoder

[!CAUTION] All functions of ResponseDecoder have been migrated to the 'nard' sub command of 'nfc_analysis_platform', and ResponsDecoder will be removed in subsequent versions.

中文

APDU Response Decoder is a tool for parsing and displaying .apdures files generated by the Flipper Zero NFC APDU Runner application.

Features

• Support for loading .apdures files from local storage
• Support for loading .apdures files directly from Flipper Zero devices (via SD card mounting or serial communication)
• Support for custom decoding format templates
• TLV (Tag-Length-Value) data parsing capabilities
• Hex to decimal conversion and mathematical operations
• Automatic error detection and reporting for failed APDU commands
• Beautiful colored output

Installation

Install Dependencies

go get go.bug.st/serial
go get go.bug.st/serial/enumerator
go get github.com/spf13/cobra
go get github.com/fatih/color

Build

go build -o response_decoder

Usage

Basic Commands

Usage:
  response_decoder [flags]
  response_decoder [command]

Available Commands:
  help        Help about any command
  tlv         Parse TLV data and extract values for specified tags

Flags:
      --decode-format string   Path to format template file (.apdufmt)
  -d, --device                 Connect to Flipper Zero device
  -f, --file string            Path to .apdures file
      --format-dir string      Directory containing format template files (default "./format")
  -h, --help                   help for response_decoder
  -p, --port string            Specify serial port for Flipper Zero (optional)
  -s, --serial                 Use serial communication with Flipper Zero (requires -d)
      --debug                  Enable debug mode to show error messages

Load from Local File

To parse an APDU response file from your local storage:

./response_decoder -f path/to/file.apdures

Load from Flipper Zero Device (SD Card Mount)

To load and parse an APDU response file directly from your Flipper Zero device using SD card mounting:

./response_decoder -d

This will automatically detect your Flipper Zero device's mount point and list available .apdures files for you to select.

Load from Flipper Zero Device (Serial Communication)

To load and parse an APDU response file directly from your Flipper Zero device using serial communication:

./response_decoder -d -s

If you need to specify a serial port (useful when you have multiple devices connected):

./response_decoder -d -s -p /dev/tty.usbmodem123456

Use Custom Decoding Format

To use a specific format template for decoding:

./response_decoder -f file.apdures --decode-format path/to/format.apdufmt

If you don't specify a format file, the program will list all available .apdufmt files in the format directory and prompt you to select one.

TLV Data Parsing

The tool includes a dedicated TLV parser that can be used independently:

./response_decoder tlv --hex 6F198407A0000000031010A50E500A4D617374657243617264

To extract specific tags:

./response_decoder tlv --hex 6F198407A0000000031010A50E500A4D617374657243617264 --tag 84,50

To specify data type for better display:

./response_decoder tlv --hex 6F198407A0000000031010A50E500A4D617374657243617264 --tag 50 --type ascii

Decoding Format Templates

A decoding format template is a text file that defines how to parse and display APDU response data. The first line of the template file is the format name, and subsequent lines are decoding rules.

For example, a PBOC format template:

PBOC
Card Number: {hex(O[1][10:18])}
Name: {hex(O[2][10:20], "utf-8")}
Balance: {h2d(O[3][10:18])/100.00} Yuan
Valid Until: 20{O[4][10:12]}-{O[4][12:14]}
Transaction Record: {hex(O[5][10:30])}

Template Syntax

• I[n]: The nth input command
• O[n]: The nth output response
• O[n][start:end]: Slice of the nth output response from start to end position
• hex(data): Convert a hexadecimal string to readable text
• hex(data, "utf-8"): Convert a hexadecimal string to text using UTF-8 encoding
• h2d(data): Convert a hexadecimal string to decimal number
• O[n]TAG(tag): Extract the value of the specified TLV tag from the nth output response
• O[n]TAG(tag, "encoding"): Extract the value of the specified TLV tag from the nth output response and convert it to text using the specified encoding
• O[n]TAG(tag)[start:end]: Extract the value of the specified TLV tag and then slice it
• Mathematical operations: +, -, *, / (e.g., {h2d(O[1][4:8]) + h2d(O[2][4:8])})

Advanced Features

Hex to Decimal Conversion

The h2d() function converts hexadecimal values to decimal numbers:

Balance: {h2d(O[1][4:12])} (in cents)
Balance: {h2d(O[1][4:12])/100.00} Yuan (formatted)

Mathematical Operations

You can perform basic mathematical operations within the template expressions:

Total: {h2d(O[1][4:8]) + h2d(O[2][4:8])}
Average: {(h2d(O[1][4:8]) + h2d(O[2][4:8]) + h2d(O[3][4:8])) / 3}

Slicing Function Results

You can apply slicing to the results of functions:

Card Number Part: {O[1]TAG(5A)[0:8]}
Decimal Value Prefix: {h2d(O[1][4:12])[0:4]}

Error Handling

The tool automatically detects error responses (non-9000 status codes) and handles them appropriately:

• When an output has a non-success status code (not 9000, 9100, or 9200), any template expression referencing that output will return an empty string
• Error information is collected during parsing but not displayed by default
• To view error information, use the --debug flag when running the command
• In debug mode, error messages are displayed at the end of the output, including the output index, status code, and a description of the error (e.g., "Output[2]: Error code 6A82 - File not found")

TLV Parsing

This tool supports parsing TLV (Tag-Length-Value) data structures commonly used in EMV and other smart cards. The TLV parsing functionality allows you to extract values for specific tags directly from APDU responses without manually calculating offsets.

Supported encoding types:

• utf-8: UTF-8 encoding
• ascii: ASCII encoding
• numeric: Numeric encoding (such as BCD code)

TLV Template Example

EMV format template:

EMV Card Information
Card Number: {O[1]TAG(5A), "numeric"}
Cardholder Name: {O[2]TAG(5F20), "utf-8"}
Expiration Date: {O[2]TAG(5F24), "numeric"}
Currency Code: {O[3]TAG(9F42)}
Balance: {h2d(O[3]TAG(9F79))/100.00}
Transaction Log: {O[4]TAG(9F4D)}
Application Label: {O[0]TAG(50), "ascii"}

Examples

Example 1: Parsing a Local File with Default Format

./response_decoder -f ./responses/visa_card.apdures

Example 2: Parsing a File from Flipper Zero with Custom Format

./response_decoder -d -s --decode-format ./format/EMV.apdufmt

Example 3: Parsing TLV Data

./response_decoder tlv --hex 6F1A8407A0000000031010A50F500A4D617374657243617264870101 --tag 50,84 --type ascii

Example 4: Using Mathematical Operations

Format template example:

Card Analysis
Balance (Yuan): {h2d(O[1]TAG(9F79))/100.00}
Last Transaction: {h2d(O[2]TAG(9F02))/100.00}
Remaining Balance: {h2d(O[1]TAG(9F79))/100.00 - h2d(O[2]TAG(9F02))/100.00}

License

GNU General Public License v3.0 (GPL-3.0)