Libraries and tools for EMV ®️ card data

Note

EMV ®️ is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. This project refers to "EMV" only to indicate the specifications involved and does not imply any affiliation, endorsement or sponsorship by EMVCo in any way.

This project is a partial implementation of the EMVCo specifications for card payment terminals. It is mostly intended for validation and debugging purposes but may eventually grow into a full set of EMV kernels.

If you wish to use these libraries for a project that is not compatible with the terms of the LGPL v2.1 license, please contact the author for alternative licensing options.

Installation

• For Ubuntu 20.04 LTS (Focal), 22.04 LTS (Jammy), or 24.04 LTS (Noble) install the appropriate release package
• For Fedora 40 or Fedora 41, install the appropriate Fedora release package
• For Gentoo, use the OpenEMV overlay, set the keywords and useflags as needed, and install using emerge --verbose --ask emv-utils
• For MacOS with Homebrew, use the OpenEMV tap and install using brew install openemv/tap/emv-utils
• For Windows, use MSYS2 and follow the build instructions below
• For other platforms, architectures or configurations, follow the build instructions below

Dependencies

• C11 and C++11 compilers such as GCC or Clang
• CMake
• pkg-config
• iso-codes
• json-c
• Boost.Locale will be used by default for ISO 8859 support but is optional if a different implementation is selected; see ISO/IEC 8859 support.
• iconv can optionally be selected for ISO 8859 support; see ISO/IEC 8859 support.
• emv-decode and emv-tool will be built by default and require argp (either via Glibc, a system-provided standalone or a downloaded implementation; see MacOS / Windows). Use the BUILD_EMV_DECODE and BUILD_EMV_TOOL options to prevent emv-decode and emv-tool from being built and avoid the dependency on argp.
• emv-tool requires PC/SC, either provided by WinSCard on Windows or by PCSCLite on Linux/MacOS. Use the BUILD_EMV_TOOL option to prevent emv-tool from being built and avoid the dependency on PC/SC.
• emv-viewer can optionally be built if Qt (see Qt for details) is available at build-time. If it is not available, emv-viewer will not be built. Use the BUILD_EMV_VIEWER option to ensure that emv-viewer will be built.
• Doxygen can optionally be used to generate API documentation if it is available; see Documentation
• bash-completion can optionally be used to generate bash completion for emv-decode and emv-tool
• NSIS can optionally be used to generate a Windows installer for this project

This project also makes use of sub-projects that must be provided as git submodules using git clone --recurse-submodules:

• mcc-codes

Build

This project uses CMake and can be built using the usual CMake steps.

To generate the build system in the build directory, use:

cmake -B build

To build the project, use:

cmake --build build

Consult the CMake documentation regarding additional options that can be specified in the above steps.

Testing

The tests can be run using the test target of the generated build system.

To run the tests using CMake, do:

cmake --build build --target test

Alternatively, ctest can be used directly which also allows actions such as MemCheck to be performed or the number of jobs to be set, for example:

ctest --test-dir build -T MemCheck -j 10

Documentation

If Doxygen was found by CMake, then HTML documentation can be generated using the docs target of the generated build system.

To generate the documentation using CMake, do:

cmake --build build --target docs

Alternatively, the BUILD_DOCS option can be specified when generating the build system by adding -DBUILD_DOCS=YES.

Packaging

If the required packaging tools were found (dpkg and/or rpmbuild on Linux) by CMake, packages can be created using the package target of the generated build system.

To generate the packages using CMake, do:

cmake --build build --target package

Alternatively, cpack can be used directly from within the build directory (build in the above Build steps).

This is an example of how monolithic release packages can be built from scratch on Ubuntu or Fedora:

rm -Rf build &&
cmake -B build -DCMAKE_BUILD_TYPE="RelWithDebInfo" -DCMAKE_INSTALL_PREFIX=/usr -DBUILD_SHARED_LIBS=YES -DBUILD_DOCS=YES -DCPACK_COMPONENTS_GROUPING=ALL_COMPONENTS_IN_ONE &&
cmake --build build &&
cmake --build build --target package

ISO/IEC 8859 support

This project contains multiple ISO 8859 implementations that can be selected at build time using the CMake ISO8859_IMPL option. It allows these values:

• boost (default): Uses Boost.Locale, is supported on most platforms, is forgiving of unassigned code points, but requires C++.
• iconv: Uses iconv, is not supported on some platforms, is less forgiving of unassigned code points, but doesn't require C++.
• simple: Only supports ISO 8859-1, has no dependencies and doesn't require C++.

Qt

This project supports Qt 5.12.x, Qt 5.15.x, Qt 6.5.x and Qt 6.7.x (although it may be possible to use other versions of Qt) when building the emv-viewer application. However, on some platforms it may be necessary to use the QT_DIR option (and not the Qt5_DIR nor Qt6_DIR options) or CMAKE_PREFIX_PATH option to specify the exact Qt installation to be used. For Qt6 it may also be necessary for the Qt tools to be available in the executable PATH regardless of the QT_DIR option.

If the Qt installation does not provide universal binaries for MacOS, it will not be possible to build emv-viewer as a universal binary for MacOS.

MacOS / Windows

On platforms such as MacOS or Windows where static linking is desirable and dependencies such as argp may be unavailable, the FETCH_ARGP option can be specified when generating the build system.

In addition, MacOS universal binaries can be built by specifying the desired architectures using the CMAKE_OSX_ARCHITECTURES option.

This is an example of how a self-contained, static, universal binary can be built from scratch for MacOS:

rm -Rf build &&
cmake -B build -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64" -DCMAKE_BUILD_TYPE="RelWithDebInfo" -DFETCH_ARGP=YES &&
cmake --build build

On MacOS, a bundle can also be built using the BUILD_MACOSX_BUNDLE option and packaged as a DMG installer. Assuming QT_DIR is already appropriately set, this is an example of how a self-contained, static, native bundle and installer can be built from scratch for MacOS:

rm -Rf build &&
cmake -B build -DCMAKE_BUILD_TYPE="RelWithDebInfo" -DFETCH_ARGP=YES -DBUILD_EMV_VIEWER=YES -DBUILD_MACOSX_BUNDLE=YES &&
cmake --build build --target package

On Windows, a standalone installation that includes external dependencies can also be built using the BUILD_WIN_STANDALONE option and packaged using NSIS. Assuming QT_DIR is already appropriately set to a Qt installation that can deploy its own dependencies, this is an example of how a self-contained installer can be built for Windows:

rm -Rf build &&
cmake -B build -DCMAKE_BUILD_TYPE="RelWithDebInfo" -DBUILD_SHARED_LIBS=YES -DFETCH_ARGP=YES -DBUILD_EMV_VIEWER=YES -DBUILD_WIN_STANDALONE=YES &&
cmake --build build --target package

Usage

The available command line options of the emv-decode application can be displayed using:

emv-decode --help

To decode ISO 7816-3 Answer-To-Reset (ATR) data, use the --atr option. For example:

emv-decode --atr 3BDA18FF81B1FE751F030031F573C78A40009000B0

To decode EMV TLV data, use the --tlv option. For example:

emv-decode --tlv 701A9F390105571040123456789095D2512201197339300F82025900

To decode an EMV Data Object List (DOL), use the --dol option. For example:

emv-decode --dol 9F1A029F33039F4005

To decode an ISO 3166-1 country code, use the --country option. For example:

emv-decode --country 528

To decode an ISO 4217 currency code, use the --currency option. For example:

emv-decode --currency 978

To decode an ISO 639 language code, use the --language option. For example:

emv-decode --language fr

To decode an ISO 18245 Merchant Category Code (MCC), use the --mcc option. For example:

emv-decode --mcc 5999

To decode ISO 8859 data and print as UTF-8, use the --iso8859-x option and replace x with the desired ISO 8859 code page. For example:

emv-decode --iso8859-10 A1A2A3A4A5A6A7

The emv-decode application can also decode various other EMV structures and fields. Use the --help option to display all available options.

Roadmap

• Document emv-tool usage
• Implement high level EMV processing API
• Implement country, currency, language and MCC searching
• Implement context-specific EMV string decoding, such as ISO 8859 code pages for UTF-8 conversion and kernel-specific contactless fields
• Implement Qt plugin for EMV decoding

License

Copyright 2021-2024 Leon Lynch.

This project is licensed under the terms of the LGPL v2.1 license with the exception of emv-viewer which is licensed under the terms of the GPL v3 license. See LICENSE and LICENSE.gpl files.

This project includes mcc-codes as a git submodule and it is licensed under The Unlicense license. See LICENSE file.

Note

EMV ®️ is a registered trademark in the U.S. and other countries and an unregistered trademark elsewhere. The EMV trademark is owned by EMVCo, LLC. This project refers to "EMV" only to indicate the specifications involved and does not imply any affiliation, endorsement or sponsorship by EMVCo in any way.