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.
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.
- For Ubuntu 20.04 LTS (Focal) or Ubuntu 22.04 LTS (Jammy), install the appropriate release package
- For Fedora 36, Fedora 37 or Fedora 38, 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, theDukpt
application can be made available in Launchpad via a symlink usingln -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
- C11 compiler such as GCC or Clang
- CMake
- DUKPT libraries require MbedTLS (preferred), or OpenSSL
dukpt-tool
will be built by default and requiresargp
(either via Glibc, a system-provided standalone or a downloaded implementation; see MacOS / Windows). Use theBUILD_DUKPT_TOOL
option to prevent DUKPT tool from being built and avoid the dependency onargp
.dukpt-tool
can optionally use tr31 if available at build-time (either install a release build or usetr31_DIR
to find a local build)dukpt-ui
can optionally be built if both Qt5 and tr31 are available at build-time. If either are not available,dukpt-ui
will not be built. Use theBUILD_DUKPT_UI
option to ensure thatdukpt-ui
will be built.- Doxygen can optionally be used to generate API documentation if it is available; see Documentation
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:
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.
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
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
.
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
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
Note that it may also be necessary to use the Qt5_DIR
option to specify the
Qt installation to be used. If the Qt installation does not provide universal
binaries, it will not be possible to build dukpt-ui
as a universal binary.
On MacOS, a bundle can also be built using the BUILD_MACOSX_BUNDLE
option and
packaged as a DMG installer. Assuming tr31_DIR
and Qt5_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
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
- Implement transaction-originating algorithms (ANSI X9.24-3:2017, 6.5)
- Test on various ARM architectures
Copyright (c) 2021, 2022, 2023 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.