Zymbit Documentation

Welcome to Zymbit’s Documentation Site! Here, you will find all the resources you need to learn about and to use all Zymbit hardware and software.

Zymbit Driver Package platform and OS support

Zymbit Driver Package 2.x

Driver Package 1.x (legacy) only

32-bit operating systems are supported by Driver Package 1.x only. If you have a 32-bit requirement, contact Zymbit support at support@zymbit.com.

Contact support@zymbit.com for PiZero 2W.

For Bootware support, see Bootware.

November 2026 Details

Zymbit Driver Package 2.0.x Release Notes

What’s New?

Zymbit Driver Package 2.x includes the following:

• Install and update with apt. Add the Zymbit repository once, and every Zymbit package installs and stays current through standard apt commands, alongside the rest of your system. No more install_zk_sw.sh script.
• Production-ready ZYMKEY5. Production ZYMKEY5 modules now identify as zymkey5, replacing the pre-production hsm6 name. Zymbit Driver Package 2.x is required for modules identifying as zymkey5 and is backwards compatible with modules identifying as hsm6.
• Ready for Ubuntu 26.04 LTS. Adds support for Ubuntu 26.04 LTS, so you can move your fleet to the latest LTS.
• Install only what you need. The Zymkey app utilities API is split into separate runtime, development and Python packages. Production devices need no longer install development headers and utilities.
• Python API as a native package. python3-zku installs with apt like everything else and automatically replaces the old pip package.
• Build your apps the standard way. Native libraries now install to standard multiarch-aware locations with versioned names, and ship with pkg-config and CMake helpers. Applications built against the old libraries need a rebuild; see Known issues.

Moving from ZYMKEY4 to ZYMKEY5

ZYMKEY5 is a significant upgrade to the cryptographic and physical protection capabilities of the ZYMKEY4, bringing in the 500-slot wallet and many new features while keeping the same 10-pin plug-in form factor. Zymbit is no longer able to produce ZYMKEY4 due to part obsolescence. If you have been using ZYMKEY4 in production, please migrate to ZYMKEY5.

In many cases, ZYMKEY5 is a drop-in upgrade for existing ZYMKEY4 designs. However, there are a few differences to keep in mind:

• ZYMKEY5 includes the full hardware wallet. BIP32, SLIP39 and 500+ key slots are supported. Hardware protection features include 2 cryptographically encoded perimeter loops, accurate coin cell battery measurement and temperature monitoring. ZYMKEY5 features are now aligned with the HSM series products and the Secure Edge Nodes. All software APIs supported on ZYMKEY4 are supported on ZYMKEY5.
• ZYMKEY5 no longer has the built-in battery holder. Instead, there is a standard Pi 5 battery connector (SM02B-SRSS-TB on the PCB), so an external battery of suitable size and capacity may be used. Rechargeable battery support is available for OEM customers. Do not use a standard Pi rechargeable battery on a standard ZYMKEY5. Zymbit recommends 2032 lithium coin cells with suitable connectors and wiring. The ZYMKEY5 Developer Kit includes the battery holder.
• ZYMKEY5 does not have the accelerometer. For applications requiring an accelerometer, please use a suitable, generally available I2C module. The accelerometer was removed because it consumes too much power to be usable while running on the coin cell battery, and cannot maintain a consistent speed while ZYMKEY5 is busy with a longer compute task. Other Zymbit modules and nodes retain the accelerometer (HSM60, SEN-505).
• ZYMKEY5 uses the new 12-pin I/O connector (SM12B-SURS-TF on the PCB), which is now standard on all Zymbit products. It replaces the older mini-USB connector for the perimeter loops and adds lines including the LED outputs and the bulk battery monitor. Zymbit is beta testing the additional I/O features; please contact us if your application can benefit. Zymbit now offers a breakout cable and boards to aid with hardware integration.
• ZYMKEY5 does not use the breakable tab for production mode. This is now done via a software command; see the production mode doc page.

Supported Distributions

Zymbit Driver Package 2.x supports 64-bit ARM (arm64/aarch64) only. 32-bit ARM (armhf) packages are no longer built as standard, due to incompatibilities with older versions of system libraries. If you have a 32-bit requirement, contact Zymbit support at support@zymbit.com; case-by-case support may be available.

Ubuntu 22.04 (jammy) and Debian 11 (bullseye) are no longer supported because the packages require glibc 2.36 or newer. Devices on 22.04 should stay on the zk-sw-repo packages or upgrade to Ubuntu 24.04. Devices on bullseye should stay on the zk-sw-repo packages or upgrade to Debian 12 (bookworm).

Zymbit Driver Package 2.x Versions

All packages now come from one signed repository, https://zk-repo.s3.amazonaws.com/debian/ (suite stable), shared by every supported distribution. Zymbit Driver Package 2.x names this set of packages as a whole. Each package keeps its own version number, listed below. Previous versions are the newest from the legacy zk-sw-repo repository.

What’s new

Install and Upgrade

Installing the zymbit-repo package switches a device to the new repository; after that, every Zymbit package installs and updates through APT.

This process works the same for new installs and for devices already using zk-sw-repo. The new installer package is aware of the old driver and will generally behave correctly. However, if the system install has been customized, or the distribution is non-standard, the standard procedure may not upgrade properly.

Always test and check to make sure the upgrade is working as intended. See above for how to back up and preserve critical system information to avoid LUKS key loss.

1. Pull down the installation package, zymbit-repo. The -J option tells curl to automatically save the file under the version name reported by the download server; e.g.: zymbit-repo_2.0-1_all.deb:

   curl -fsSLOJ https://zk-repo.s3.amazonaws.com/zymbit-repo.deb
   

2. Install the repository package. This will configure APT sources and import Zymbit’s GPG signing key. By default, it installs without asking anything and leaves beta updates off. Removing this package later will remove Zymbit’s repository from APT and clear the GPG key from the system’s trusted keyring but will leave behind any other Zymbit packages that have been installed on the system. Those must be removed explicitly.

   sudo apt install ./zymbit-repo_*_all.deb
   

   The beta-updates question is asked only at debconf priority medium or lower. To be asked, install with:

   sudo DEBIAN_PRIORITY=medium apt install ./zymbit-repo_*_all.deb
   

   To opt in without a prompt, for example in unattended installs, set the answer before installing:

   sudo debconf-set-selections <<< "zymbit-repo zymbit-repo/enable-beta-updates boolean true"
   

   To change the answer later, run sudo dpkg-reconfigure zymbit-repo, which always asks.

   This adds /etc/apt/sources.list.d/zymbit.sources and the Zymbit signing key, and removes the old zk-sw-repo entry from /etc/apt/sources.list.d/zymbit.list.

3. Refresh the package lists:

   sudo apt update
   

4. In order to communicate with the Zymkey, the host’s I2C interface must be enabled. On Ubuntu, this is the case out of the box. On Debian (Raspberry Pi OS), this can be done via the following command:

   sudo raspi-config nonint do_i2c 0
   sudo reboot
   

5. Install the packages needed for the intended use case. Necessary dependencies from Zymbit and the OS distribution will be automatically installed. On a device previously configured via the legacy install_zk_sw.sh, backup /var/lib/zymbit before proceeding. New devices, or devices that do not have this file, do not need to take any action.

   1. For base functionality of the Zymkey, including disk encryption, install the following packages, then reboot.

      sudo apt install zkifc zksaapps
      

   2. To use the Zymkey’s OpenSSL engine backend and SoftHSM, run

      sudo apt install zkifc libzymkeyssl zkpkcs11
      

   3. To use the python bindings, run

      sudo apt install zkifc python3-zku
      

   4. To run programs linked against Zymbit’s zkapputils library, run

      sudo apt install zkifc libzkapputils
      # OPTIONAL: to make use of the C++ API, run
      # sudo apt install zkifc libzkapputils-c++
      

   5. To build programs using libzkapputils, install the -dev variants of the above libzkapputils packages. Container and/or cross-compilation environments will likely need to skip the automatic installation of zkifc, which fails without access to a Pi’s hardware I2C bus.

      sudo apt install zkifc libzkapputils[-c++]-dev
      # to skip zkifc installation, run
      sudo apt install --no-install-recommends libzkapputils[-c++]-dev
      

The new packages replace the old ones themselves: when applicable, apt removes libzk and zkapputilslib as part of the install and python3-zku removes the zku package installed with pip.

Known issues

• Applications built against zkapputilslib must be rebuilt. The old libraries had unversioned names (libzk_app_utils.so, libzkAppUtilsClassCPP.so). Rebuild against the new packages. See the C and C++ API docs for instructions on using the CMake and pkg-config helpers.
• Update PKCS#11 configurations that name old paths. Configurations that load the PKCS#11 module from /usr/lib/libzk_pkcs11.so must point to the new names in /usr/lib/aarch64-linux-gnu/libzk_pkcs11.so. (zk_pkcs11-util does this automatically.)
• Back up your PKCS#11 configuration before upgrading. The token directory stays at /var/lib/zymbit/zk_pkcs11/tokens/, so existing tokens carry over. As a precaution, keep a copy of /etc/zk_pkcs11.conf and your tokens before upgrading.
• libzymkeyssl. Only supports OpenSSL ENGINE using the EC_KEY_METHOD interface; runs on OpenSSL 3.0 through 3.x. Not supported on OpenSSL 4.0. Support for 3.5 LTS runs to 2030.

Previous release notes are in Troubleshooting.