binaryfoo / emv-bertlv Goto Github PK

View Code? Open in Web Editor NEW

151.0 18.0 61.0 934 KB

Deciphering EMV data encoded in the not so basic "basic encoding rules".

License: MIT License

Java 43.84% Kotlin 55.87% Groovy 0.29%

emv visa amex mastercard

emv-bertlv's Introduction

What is this thing?

A library for deciphering BER TLV data used in EMV (chip card transactions).

You might be wondering what some of the strange characters on a credit card receipt mean. Or you might be trying to achieve certification with Visa, Mastercard or Amex (perhaps even UnionPay).

The tests provide some idea of what kind of data this code can decipher. The EMVCo website has the full (1000+ page) specs. Add to that the Visa, Mastercard and Amex documents.

How might I use it?

In a couple of ways:

As a library in a java (or other JVM language) project doing wonderful things with chip card data.
On the web in a little tool. The code for this tool lives in another repo.
As a command line tool.

From Maven or Gradle

Dependency Information (available from Maven Central):

    <dependency>
        <groupId>io.github.binaryfoo</groupId>
        <artifactId>emv-bertlv</artifactId>
        <version>0.1.8</version>
    </dependency>

To get started decoding call decode() on RootDecoder.

Command Line

The library can be used as an executable jar:

Download the latest jar
Run using java -jar emv-bertlv-x.y.z-shaded.jar

This will dump out some (hopefully) somewhat helpful help output:

Usage Main <decode-type> <value> [<tag-set>]
  <decode-type> is one of
    95: TVR
    9B: TSI
    82: AIP
    8E: CVM List
    9F34: CVM Results
    9F6C: CTQ
    9F66: TTQ
    dol: DOL
    filled-dol: Filled DOL
    constructed: TLV Data
    apdu-sequence: APDUs
    bit-string: Bits
  <value> is the hex string or '-' for standard input
  <tag-set> is one of [EMV, qVSDC, MSD, Amex] defaults to EMV

For example to decode the Terminal Verification Results:

java -jar emv-bertlv-x.y.z-shaded.jar 95 ffffffffff

Or say you have a file containing a set of APDUs encoded as hex strings:

cat apdus.txt | java -jar emv-bertlv-x.y.z-shaded.jar apdu-sequence -

Domain Knowledge

Visa's chip terms explained document is a good list.

Eftlab's knowledge base.

Alternative Tools

Eftlab's BP-Tools

Emvlab's tlvtool

emv-bertlv's People

Contributors

Stargazers

Watchers

emv-bertlv's Issues

ClassnotFoundException CryptogramInformationDecoder

Hi!, i´m getting this error when i´m trying to decode ( using the "decode" method in RootDecoder class ). This seems to be an issue of ofuscation apparently.

It is possibly a bug ?.

           `Caused by: java.lang.ClassNotFoundException: io.github.binaryfoo.decoders.CryptogramInformationDecoder
                                                                                                	at java.lang.Class.classForName(Native Method)
                                                                                                	at java.lang.Class.forName(Class.java:454)
                                                                                                	at java.lang.Class.forName(Class.java:379)
                                                                                                	at io.github.binaryfoo.TagMetaData$Companion.load(TagMetaData.kt:86)
                                                                                                	at io.github.binaryfoo.TagMetaData.load(Unknown Source:2)
                                                                                                	at io.github.binaryfoo.EmvTags.<clinit>(EmvTags.java:9)
                                                                                                	at io.github.binaryfoo.RootDecoder.<clinit>(RootDecoder.kt:40) 
                                                                                                	at com.geopagos.cps.others.tlv.TlvHelper.getTlvs(Unknown Source:5) 
                                                                                                	at com.geopagos.reader.magicpos.wrapper.MagicPosServiceAdapter$magicPosCallback$1.processNfcTradeResult(MagicPosServiceAdapter.kt:772) 
                                                                                                	at com.geopagos.reader.magicpos.wrapper.MagicPosServiceAdapter$magicPosCallback$1.onDoPollCardResult(MagicPosServiceAdapter.kt:579) 
                                                                                                	at com.magicpos.xpos.MPOSService$31.run(MPOSService.java:7457) 
                                                                                                	at android.os.Handler.handleCallback(Handler.java:978) 
                                                                                                	at android.os.Handler.dispatchMessage(Handler.java:104) 
                                                                                                	at android.os.Looper.loopOnce(Looper.java:238) 
                                                                                                	at android.os.Looper.loop(Looper.java:357) 
                                                                                                	at android.app.ActivityThread.main(ActivityThread.java:8098) 
                                                                                                	at java.lang.reflect.Method.invoke(Native Method) 
                                                                                                	at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:548) 
                                                                                                	at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:1026) 
                                                                                                Caused by: java.lang.ClassNotFoundException: Didn't find class "io.github.binaryfoo.decoders.CryptogramInformationDecoder" on path: DexPathList[[zip file "/data/app/~~PPOTaQP2cMfkagmY4r_CEQ==/`

SnakeYml 2.0 incompatibility

Because SnakeYaml due to https://www.cve.org/CVERecord?id=CVE-2022-1471 has been updated and in version 2.0 does not support class Constructor with an empty constructor, it's not possible to update SnakeYaml to 2.0 version.
Trying to update SnakeYaml in a project using emv library results with error:

Exception in thread "main" java.lang.NoSuchMethodError: org.yaml.snakeyaml.constructor.Constructor: method 'void <init>()' not found
	at io.github.binaryfoo.TagMetaData$Companion.load(TagMetaData.kt:70)
	at io.github.binaryfoo.TagMetaData.load(TagMetaData.kt)
	at io.github.binaryfoo.EmvTags.<clinit>(EmvTags.java:9)
	at org.test.EmvTagsChecker.main(EmvTagsChecker.java:8)

Kotlin compiler version out of date

I don't know if I am at the right place but I'm trying to use your fabulous project but I'm stuck with a compiler error.

For example, in DecodedData.class I have this message when I try to open file :

// This class file was compiled with different version of Kotlin compiler and can't be decompiled.
//
// Current compiler ABI version is 1.0.1
// File ABI version is 0.19.0

I'm working on IntelliJ.

Have you got any idea to solve this issue ?

Library has Kotlin runtime bundled into it

If I use the jar in an Android Studio project I have the following issue:

...app/libs/emv-bertlv-0.1.7-shaded.jar: Library has Kotlin runtime bundled into it

It's a compile error because the jar it has the runtime libs of kotlin.

"Please note that you should not include kotlin-runtime and kotlin-stdlib jars with your plugin because Kotlin guarantees backward- and forward- binary compatibility."

http://www.jetbrains.org/intellij/sdk/docs/tutorials/kotlin.html

I hope you can fix it or provide a version without the dependency (an not executable version), and thank you so much for the amazing lib.

snakeyaml version is out of date

The deprecated Loader and Dumper are gone in snakeyaml 1.16. Play framework depends on snakeyaml 1.16. Time to clean up.

Cannot parse an empty data source

In the scenario where the data source is empty the library crashes throwing Method java.lang.IndexOutOfBoundsException exception.

Code used to test this:

assertNull(BerTlv.parse("".toByteArray()))

I think this can be easily fixed by this change in the BerTlv.java class:

@JvmStatic
fun parse(data: ByteArray): BerTlv {
      if (data.isNotEmpty()) {
        return parseList(ByteBuffer.wrap(data), true)[0]
    } else {
        null
    }
}

NullPointerException thrown when unpacking data

Trying to decode the following TLV string, cloned from a working chip card, a NPE is thrown. Parsing the same data using BP-TOOLS EMV tool seems to handle it fine, as does splitting the original string up into two separate substrings (and updating the length bytes).

"709157134761739001010119D22122011143804400000F5F201A5541542041544D2F5465737420436172642030352020202020205F300202019F1F183131343338303434303030303030303030303030303030309F080200969F4401028C159F02069F03069F1A0295055F2A029A039C019F37048D178A029F02069F03069F1A0295055F2A029A039C019F37049F49039F3704"

Fails with:
raw=[Error] decoded=[Failed parsing TLV with tag 70: Bad length: -1878982400 < 0. Read 8 of 17 (0x91) bytes used to encode length of TLV.] indexes=[0,147]