DUKPT libraries and tools

<br/> <br/> <br/> <br/> <br/>

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

These libraries implement the host (direct) key derivation algorithms as well as the transaction-originating device's key derivation algorithms for both 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.

Example output

See usage for more examples.

Installation

• For Ubuntu 22.04 LTS (Jammy) or 24.04 LTS (Noble) install the appropriate Ubuntu release package
• For Fedora 42 or Fedora 43, 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 the installer or follow the build instructions below to build using MSYS2
• 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 downloaded during the build from libargp; 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.15.x, Qt 6.8.x and Qt 6.10.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 Qt5_DIR, Qt6_DIR or CMAKE_PREFIX_PATH options 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 Qt6_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 the appropriate CMake environment variables have already been set for all dependencies to be found, 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_MBEDTLS=YES -DFETCH_ARGP=YES -DBUILD_DUKPT_UI=YES -DBUILD_MACOSX_BUNDLE=YES &&
cmake --build build --target package

On Windows, a standalone installation that includes external dependencies can be built using the BUILD_WIN_STANDALONE option and packaged using NSIS. Assuming tr31_DIR is already appropriately set and QT_DIR is set to a Qt installation that can deploy its own dependencies, this is an example of how a standalone installation can be built and packaged from scratch on Windows:

rm -Rf build &&
cmake -B build -DCMAKE_BUILD_TYPE="RelWithDebInfo" -DBUILD_SHARED_LIBS=YES -DFETCH_MBEDTLS=YES -DFETCH_ARGP=YES -DBUILD_DUKPT_UI=YES -DBUILD_WIN_STANDALONE=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