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.

Latest STABLE Platform and OS Support

Full Bootware 1.3.2 Support

Bootware Not Supported

NOTICE: Changes from the Pi foundation to the Pi5/CM5 firmware are incompatible with Bootware. Symptom is Bootware Updates cannot access USB Endpoints to get images. You won’t see the problem with the 11/19 release. The 11/19 release can be downloaded from here: Pi5 Raspberry Pi OS Lite 64-bit 2024-11-19

Contact support for PiZero 2W.

October 2026 Details

Zymbit Driver Package 2.0

The installation of the Zymbit Driver Package 2.0 is a migration, not a routine update. It moves devices from the heterogeneous, distribution-specific legacy APT repositories to a common new APT repository, renames and splits several packages. Running apt upgrade on a device still using zk-sw-repo will not move it to 2.0.

Before you upgrade a device:

• Check that it runs a supported distribution.
• On devices set up with install_zk_sw.sh, back up /var/lib/zymbit.
• Plan to rebuild applications built against the old Zymkey API libraries.

Then follow the install steps below.

What’s New?

Zymbit Driver Package 2.0 makes Zymbit software install and update like any other package on your system: one signed apt repository, production ZYMKEY5 support, and Ubuntu 26.04 LTS out of the box.

• Install and update with with a unified apt process. 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.
• 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.
• Production-ready ZYMKEY5. Production ZYMKEY5 adapters now identify as zymkey5, replacing the pre-production hsm6 name. Zymbit Driver Package 2.0 is required for adapters identifying as zymkey5, and is backwards compatible with adapters identifying as hsm6.
• Ready for Ubuntu 26.04 LTS. zkifc supports the new GPIO character-device interface that replaces sysfs GPIO in Ubuntu 24.04, so you can move your fleet to the latest LTS.
• 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.

Supported Distributions

Zymbit Driver Package 2.0 supports 64-bit ARM (arm64/aarch64) only. 32-bit ARM (armhf) packages are no longer built. If you are using an older distribution, we recommend you stick with the existing legacy packages.

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.0 Versions

All packages now come from one common, signed repository, https://zk-repo.s3.amazonaws.com/debian/ (suite stable), shared by every supported distribution. Zymbit Driver Package 2.0 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 works the same for new installs and for devices already using zk-sw-repo.

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_1.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 by default. 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.

• 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.