Quickstart - HSM4
The HSM4 is a ‘snap in’ security module designed for easy integration within a secure manufacturing environment. All connections are through a single, 30 pin connector that is hidden underneath the module. It is designed specifically to work with Raspberry Pi embedded applications. A PiZero HAT (Hardware Attached on Top) adapter is available for easy integration to the standard GPIO pins of the Pi.
Raspberry PI OS Bookworm updated the kernel to version 6.6.y in March 2024. The kernel no longer overrides an upstream kernel decision to force the base number of the main GPIO controller to be global GPIO 0. If the WAKE_PIN number is not set, the ZYMKEY will not bind. You will see 5 flashes per second continuously.For RPI4, RPI5, and CM4 platforms, you will need to set the WAKE_PIN in the following manner:
Determine the numbering for GPIO4 by examining /sys/kernel/debug/gpio for the number associated with GPIO4, then set an environment variable in the Zymbit environment variable file:
sudo su
wake_pin=`grep GPIO4 /sys/kernel/debug/gpio | sed -r 's/[^0-9]*([0-9]*).*/\1/'`
echo "wake_pin=$wake_pin" # sanity check value is set
echo "ZK_GPIO_WAKE_PIN=$wake_pin" > /var/lib/zymbit/zkenv.conf
systemctl restart zkifc
As of 6.6.20, the numbering is: RPI4=516 RPI5=575 CM4=516
In this Getting Started guide we describe how to install your HSM to a Raspberry Pi running Raspbian or Ubuntu. The installation process is the same for both of these Linux distributions.
Summary of Setup Steps
- Installing the Hardware
- Install the HSM on the PiZero HAT. Install the battery on the HAT. Connect the HAT to the host single-board computer.
- Establish an I2C connection
- Enable the I2C bus on the host device in order to be able to communicate with the HSM.
- Install the client software
- These utilities provided by Zymbit are necessary to interact with the hardware module.
- Test the installation
- Your HSM is now temporarily bound to your SBC and ready for use in developer mode.
Installing the hardware
HSM to PiZero HAT
Fit your HSM onto the PiZero HAT (Hardware Attached on Top). The connector plugs into the pins on the board.
Battery Installation
To maintain the real-time clock (RTC) and tamper detection features in the event of power loss, your PiZero HAT can be fitted with a 3V CR2032 coincell. This battery should last 3-5 years. We recommend using a high quality one like this.
Primary Battery Holder (Recommended)
IMPORTANT: Note the correct polarity with +ve facing upwards !!
Optional Battery Connector (Alternative)
Caution: Ensure you select the right connector type– Molex 51021-0200-B (1.25mm Pitch). You can purchase the battery here.
Battery should look like this:
Mating component specifications:
Plug wired CR2032 battery into optional battery connector, located below.
Install Pi HAT with HSM (and battery)
Installing your hardware correctly is important to avoid destroying your SBC or PiHAT. Be sure to follow the instructions below carefully. In particular:
- Pay close attention to the images below to ensure the SBC’s GPIO pins are properly aligned with the HAT’s header.
- Ensure that your Raspberry Pi is powered down before proceeding.
- Ensure that the coincell battery (if installed) is installed with the positive side (marked with
+
) facing upward.
Before installing
Power off your Raspberry Pi to ensure that neither the SBC or the PiHAT are damaged.
Attach hardware
Follow the below pictures to position the PiHAT onto your SBC. The HSM and battery should be facing the Raspberry Pi and concealed from view.
Be sure all the GPIO pins are aligned and have a respective slot. If misaligned, this could cause damage to the HSM, PiHAT, and/or your host device. Once aligned properly, press firmly down onto the header. Your PiHAT should fit relatively snug.
Power on and confirm operation
Power up the Pi and you will see a blue LED blinking rapidly and consistently (5 blinks per second). This indicates the HSM is operational but not configured.
If the blue LED blinks erratically, or not at all, then there is an installation error and you should check your connections.
Establish an I2C connection
For Raspian-based operating systems, you must configure the state of the I2C.
- Log in to your Raspberry Pi and run
sudo raspi-config
. - Navigate to Interfacing Options -> I2C -> Would you like the ARM I2C interface to be enabled?
- Select yes, and confirm this choice.
Your I2C bus is now configured and ready to talk to the HSM. The default I2C address for the HSM is 0x30.
Your I2C bus is now on and ready to talk to the HSM.
The default mode for the cpu scaling governor is ondemand. There have been some issues with the interaction between the HSM and the I2C bus, when the governor is set to ondemand. We highly recommend to switching the governor to performance to get the most out of the HSM.
Install the client software
Login to your host device and follow these steps to install the HSM’s client software.
As of March 2023, Raspberry PI OS 32-bit images install the 64-bit kernel along with the 32-bit root filesystem. This does not allow our installation script to work. In order to properly install on an 32-bit system, edit /boot/config.txt
and add the following line to the bottom of the file, then reboot.
arm_64bit=0
The HSM will require a number of packages to be installed from the Raspbian and Zymbit apt
repositories. The following setup script will be install a number of files and software packages on your system, including:
- Zymbit
.service
files located in the/etc/systemd/system
directory pip
Ensure that curl
is installed on your host:
sudo apt install curl
Download and install the necessary Zymbit services onto your device.
curl -G https://s3.amazonaws.com/zk-sw-repo/install_zk_sw.sh | sudo bash
Test the installation
When the software installation has completed, the script will automatically reboot your device. After the reboot has completed, the Pi will perform an operation that will temporarily bind the HSM to your SBC. Once the HSM is bound to the SBC, the HSM’s blue LED should blink slowly–once every 3 seconds–to indicate that the binding is complete.
The quickest way to get started is to see the HSM’s various features at work by running these test scripts that were installed with the client software:
python3 /usr/local/share/zymkey/examples/zk_app_utils_test.py
python3 /usr/local/share/zymkey/examples/zk_crypto_test.py
The example scripts are missing in focal and bullseye distributions. You can get the example scripts from here:
Now you’re ready to start developing with HSM and Raspberry Pi. When it’s time to deploy your project, read our guide on enabling Production Mode: