openemv / dukpt

ANSI X9.24 DUKPT libraries and tools

DUKPT libraries and tools

This project is an implementation of the ANSI X9.24-3:2017 standard for both TDES and AES Derived Unique Key Per Transaction (DUKPT) key management. Given that most uses of this standard involve dedicated security hardware, this implementation is mostly for validation and debugging purposes.

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.

Features

Currently these libraries only implement the host (direct) key derivations for TDES and AES DUKPT. In addition to key derivation, these libraries also implement the usage of the various working keys to ensure that the derivation data used for the working key derivation match the usage of the derived working key.

Installation

• For Ubuntu 20.04 LTS (Focal), 22.04 LTS (Jammy), or 24.04 LTS (Noble) install the appropriate release package
• For Fedora 39 or Fedora 40, install the appropriate release package
• For Gentoo, use the OpenEMV overlay, set the keywords and useflags as needed, and install using emerge --verbose --ask dukpt
• For MacOS with Homebrew, use the OpenEMV tap and install using brew install openemv/tap/dukpt. After installation, the Dukpt application can be made available in Launchpad via a symlink using ln -s $(brew --prefix dukpt)/Dukpt.app /Applications/.
• For Windows, use MSYS2 and follow the build instructions below
• For other platforms, architectures or configurations, follow the build instructions below

Dependencies

• C11 compiler such as GCC or Clang
• CMake
• DUKPT libraries require MbedTLS (preferred), or OpenSSL
• dukpt-tool will be built by default and requires argp (either via Glibc, a system-provided standalone or a downloaded implementation; see MacOS / Windows). Use the BUILD_DUKPT_TOOL option to prevent DUKPT tool from being built and avoid the dependency on argp.
• dukpt-tool can optionally use tr31 if available at build-time (either install a release build or use tr31_DIR to find a local build)
• dukpt-ui can optionally be built if Qt (see Qt for details) as well as tr31 are available at build-time. If either are not available, dukpt-ui will not be built. Use the BUILD_DUKPT_UI option to ensure that dukpt-ui 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 dukpt-tool
• NSIS can optionally be used to generate a Windows installer for this project

This project also makes use of sub-projects that can either be provided as git submodules using git clone --recurse-submodules, or provided as CMake targets by a parent project:

• OpenEMV common crypto abstraction
• OpenEMV PIN block library

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

Qt

This project supports Qt 5.12.x, Qt 5.15.x, Qt 6.5.x and Qt 6.6.x (although it may be possible to use other versions of Qt) when building the dukpt-ui 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 dukpt-ui as a universal binary for MacOS.

MacOS / Windows

On platforms such as MacOS or Windows where static linking is desirable and dependencies such as MbedTLS or argp may be unavailable, the FETCH_MBEDTLS and FETCH_ARGP options 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_MBEDTLS=YES -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 tr31_DIR and QT_DIR are already appropriately set, this is an example of how a self-contained, static, native bundle and isntaller can be built from scratch for MacOS:

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

Usage

The available command line options of the dukpt-tool application can be displayed using:

dukpt-tool --help

To derive an initial key, specify the base derivation key using the --bdk option, specify the initial key serial number using the --ksn option, and use the --derive-ik option. For example (using test data examples from ANSI X9.24-1:2009 Annex A.4 or ANSI X9.24-3:2017 Annex C.5):

dukpt-tool --bdk 0123456789ABCDEFFEDCBA9876543210 --ksn FFFF9876543210E00000 --derive-ik

To advance a key serial number, specify it using the --ksn option and use the --advance-ksn option. For example (using test data examples from ANSI X9.24-1:2009 Annex A.4 or ANSI X9.24-3:2017 Annex C.5):

dukpt-tool --ksn=FFFF9876543210EFFC00 --advance-ksn

To decrypt a TDES transaction request, specify the relevant key using either the --bdk or --ik options, specify the key serial number using the --ksn option, and specify the provide the encrypted transaction request using the --decrypt-request option. For example (using test data examples from ANSI X9.24-1:2009 Annex A.4 or ANSI X9.24-3:2017 Annex C.5):

dukpt-tool --bdk 0123456789ABCDEFFEDCBA9876543210 --ksn FFFF9876543210E00002 --decrypt-request A2B4E70F846E63D68775B7215EB4563DFD3037244C61CC13

To output raw bytes instead of hex digits to stdout, add the --output-raw option. This can then be piped to another tool. For example (using test data examples from ANSI X9.24-1:2009 Annex A.4 or ANSI X9.24-3:2017 Annex C.5):

dukpt-tool --bdk 0123456789ABCDEFFEDCBA9876543210 --ksn FFFF9876543210E00002 --decrypt-request A2B4E70F846E63D68775B7215EB4563DFD3037244C61CC13 --output-raw | strings

To output a key block (and if tr31 support was enabled at build-time), specify the Key Block Protection Key (KBPK) using the --output-tr31 option and the desired key block format version using the --output-tr31-format-version option. In addition, a few optional header blocks can also be added using options such as --output-tr31-with-ksn and others. For example:

dukpt-tool --bdk 0123456789ABCDEFFEDCBA9876543210 --ksn FFFF9876543210E00000 --derive-ik --output-tr31 1D22BF32387C600AD97F9B97A51311AC --output-tr31-format-version B --output-tr31-with-ksn --output-tr31-with-kc --output-tr31-with-kp --output-tr31-with-ts

Roadmap

• Test on various ARM architectures

License

Copyright 2021-2024 Leon Lynch.

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

dukpt's Issues

invalid pinblock format 4

I possibly found a bug in pinblock format 4 generation.

First command is to show the transaction key that will be used to encrypt the pin. In this case, the transaction key is the same as the ik because ksn is zero (for simplicity).
Second command is to encipher the pin using pinblock format 4, using the derived transaction key (11111111111111111111111111111111).

# ./dukpt-tool --mode=AES --key-type=AES128 --ik=11111111111111111111111111111111 --ksn=000000000000000000000000 --derive-txn-key 
11111111111111111111111111111111
# ./dukpt-tool --mode=AES --key-type=AES128 --ik=11111111111111111111111111111111 --ksn=000000000000000000000000 --pan=1234123412341234 --pinblock-format=4 --encrypt-pin=1234
A5345078DE652954CAFE125E9495D8F5

Then when trying to decipher the generated pinblock using python psec library, I encounter an error related to control field :

>>> from psec.pinblock import decipher_pinblock_iso_4
>>> decipher_pinblock_iso_4(key=bytes.fromhex("11111111111111111111111111111111"), pin_block=bytes.fromhex("A5345078DE652954CAFE125E9495D8F5"), pan="1234123412341234")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/python3.10/site-packages/psec/pinblock.py", line 625, in decipher_pinblock_iso_4
    return decode_pin_field_iso_4(pin_field)
  File "/python3.10/site-packages/psec/pinblock.py", line 555, in decode_pin_field_iso_4
    raise ValueError(
ValueError: PIN block is not ISO format 4: control field `B`

EDIT: The transaction key is actually not the key used for pin encryption. (It is a pin encryption key, which is derived from the transaction key)