Getting Started: HSM4 for RASPBERRY PI

HSM4. The Security Module for Linux Computers.

HSM4 is designed for higher volume embedded applications where cost, tightly integrated security and optimized design are important.


HSM4 has all the great features of ZYMKEY4, but packaged in Zymbit’s HSM (Hardware Security Module) format. The smaller dimensions of both HSM4 and HSM6, as well as the new form, single connector, and external battery are designed for the Raspberry Pi.

HSM4 is code compatible with ZYMKEY4. It connects to the GPIO header of the Pi and uses the I2C bus and GPIO-4 to communicate with the Pi CPU via an encrypted channel.

HSM4 can also be used with other I2C configurations, including the Nvidia Jetson Nano.

For more information on pinout, size, and features: Learn more>


USING HSM4 WITH ZYMBIT DEVELOPER HAT FOR RPi

HSM4 is designed to be embedded directly into OEM products, or with Zymbit motherboards, and developer boards.

Here we describe how to get started with HSM4 using a Zymbit developer HAT for Raspberry Pi.

KEY COMPONENTS

PiZero HAT: HSM to PiZero HAT (Hardware Attached on Top); PiZero HAT works with the Raspberry Pi Zero, 3, 3b+, and 4.
Optional Battery Connector: Alternate option to hold battery. Battery maintains real-time-clock (RTC) and tamper detect features with or without power.
LED: The LED is used as a checkpoint to indicate your progress in HSM configuration. As you follow this getting started guide, there are various blinking patterns to indicate if you have correctly completed a step.
HSM4: Zymbit’s Hardware Security Module 4; HSM4 has the software and features of the Zymkey4 in Zymbit’s HSM form.
Perimeter Header: Connect your perimeter circuits here using discrete wires; see “Perimeter Detect” section at the bottom of this post for the pinout.
Perimeter Flexible Printed Circuit: Connect your perimeter circuits here using a standard or custom flexible printed circuit; see “Perimeter Detect” section at the bottom of this post for the pinout.
GPIO Connector: Connects PiZero HAT to Raspberry Pi; only uses the first 10 pins. See Step 3: Install Pi HAT onto Raspberry Pi for the pinout.
Battery Holder: Primary option to hold battery. CR2032 battery maintains real-time-clock (RTC) and tamper detect features with or without power.


ELECTROMECHANICAL SPECIFICATIONS

HSM Connector - Hirose Header DF40HC(3.5)-30DS-0.4V(51)

Mating Connector - Hirose Receptacle DF40C-30DP-0.4V(51)

Note: The four larger corner pads of the mating connector are mounting pads. This is why it seems to have 34 pins, but only the middle 30 are used.


SUMMARY OF STEPS

Description Notes and/or Checkpoint
1 Install HSM4 on a Pi HAT Fit HSM4 to HAT before installing battery or attaching HSM4 to Pi.
2 Install Battery The battery is required to maintain the Real Time Clock and the perimeter detect circuits when the host power is removed. See this chart for more information.
3 Install Pi HAT onto Raspberry Pi Blue LED will blink rapidly to indicate HSM4 is connected correctly but not yet configured.
4 Configure the I2C Bus The I2C Bus must be enabled. For Raspbian OS, the I2C Bus is disabled by default. For Ubuntu, the I2C Bus is enabled by default.
5 Install Software Package & API Blue LED will blink once every three seconds to indicate HSM4 is connected and configured.
6 Developer Mode DEVELOPER MODE- bindings are temporary, HSM4 can be moved to different Pi hosts and SD Cards.
7 Production Mode PRODUCTION MODE- binding is permanent! HSM4 can NOT be moved to different Pi hosts or SD Cards. Transition to Production Mode by installing new software API.

SCOPE

In this Getting Started Guide we describe how to install your HSM4 to a Raspberry Pi running Raspbian or Ubuntu. The installation process is the same for both of these Linux distributions.

Learn about Linux OS support for HSM4.


1. INSTALL HSM4 ON A PI HAT

Fit your HSM4 onto the HSM to PiZero HAT (Hardware Attached on Top). The HSM to PiZero HAT will work on the Raspberry Pi 3 and Raspberry Pi 4.


2. INSTALL BATTERY (Recommended)

Recommended: Primary Battery Holder

Your HSM to PiZero HAT can be fitted with a 3V CR2032 coincell battery that is used to maintain operation of the real-time-clock (RTC) and tamper detect features in the event that main power (from the GPIO header) is lost. This battery should last 3-5 years.

If you choose not to fit a battery, then these important security features will not function in the event main power is removed.

Battery installation is highly recommended if your device is vulnerable to physical access!

Use a high quality 3V CR2032 coincell battery such as the PANASONIC - CR2032, LITHIUM COIN CELL BATTERY.

IMPORTANT: Note the correct polarity with +ve facing upwards !!

Alternative: Optional Battery Connector

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.


3. INSTALL PI HAT ONTO RASPBERRY PI

Power down your Raspberry Pi first!

IMPORTANT: Installing your hardware correctly is important to avoid destroying your Pi or HSM4.
Be sure to follow the images below to ensure the pins are correctly aligned with the HSM header. Note: the HAT and HSM should be facing downwards towards the Raspberry Pi.

Fit the PiHAT with battery holder and HSM4 facing inwards, toward the Raspberry Pi. Be sure the connector is properly aligned with all of the GPIO pins and press firmly down onto the header. If misaligned, this could cause damage to the HSM4, PiHAT, and/or your Raspberry Pi. Your PiHAT should fit relatively snug and maintain a tight interference fit around the pins.

PiHAT occupies all pins on the GPIO header. It can also be used with Pi Plate devices attached, or other i2c devices attached. See options later for correct address range and use of IO pins.

Using an alternative GPIO pin

The default configuration uses GPIO4. This can be reconfigured to use another GPIO of your choice.
Learn more>

Using an alternative I2C address

The default I2C address for HSM4 is 0x30. If this conflicts with another device in your system, you can reconfigure the HSM4 to use another address of your choice.
Learn more>


Power On, Confirm Operation

Finally, power up the Pi and you will see a blue LED blinking rapidly and consistently (5 blinks per second)

HSM4 operational, but not configured

HSM4-LED-5times-per-second

(If the blue LED blinks erratically, or not at all, then there is an installation error and you should check your connections.)

Power Quality

Learn why power quality matters to the reliable and secure operation of your system and HSM.


4. CONFIGURE THE I2C BUS

Here we are going to configure the state of the I2C bus to “ON”.

  1. Log in to your pi and run sudo raspi-config
  2. Select Interfacing Options -> I2C ->
    Would you like the ARM I2C interface to be enabled? select (Yes), enter, enter
  3. Arrow Right to Finish

Your I2C bus is now configured and ready to talk to the HSM4. Next install the HSM4 interface software (ZKIFC) onto your Pi.

The default I2C address for HSM4 is 0x30.


5. INSTALL SOFTWARE PACKAGE & API

For a bare Raspbian system, first login to your Pi.

NOTE: Your HSM4 will require a number of packages to be installed from the Raspberry Pi and Zymbit apt repositories. The following setup script will be installing a number of files and software packages on your system:

  • Zymbit .service files located in the /etc/systemd/system directory
  • pip

Download and install the necessary Zymbit services onto your Pi.
curl -G https://s3.amazonaws.com/zk-sw-repo/install_zk_sw.sh | sudo bash
(grab a cup of coffee because this will take between 4 and 20 minutes).

Binding, Device ID and Authentication.

Good security begins with assigning each device a unique and unalterable identity (Device ID), that is used to authenticate subsequent interactions with the device.

HSM4 generates a unique Device ID by measuring certain attributes of the specific host Raspberry Pi (Measurement), and then combining that Measurement with the unique ID of a specific HSM4. The combination process uses a cryptographic function and this process is generally termed “binding”. On completion of a binding process, then HSM4 is said to be “bound” to the Pi.

HSM4 supports two operating modes:

  1. Developer Mode: bindings are temporary, HSM4 can be moved to different Pi hosts and SD Cards
  2. Production Mode: binding is permanent! HSM4 can NOT be moved to different Pi hosts or SD cards

6. DEVELOPER MODE (temporary binding)

When the software installation has completed, reboot your Pi. After the reboot has completed, the Pi will perform an operation that will temporarily bind the HSM4 to your Pi. Once the HSM4 is bound to the Pi, the HSM4’s blue LED should blink slowly - once every 3 seconds - to indicate that the binding is complete.

At this point, your HSM4 is in Developer Mode, the binding is temporary and the HSM4 can be moved to another Pi and the binding process repeated.

HSM4 operational, temporary binding to host (HSM4 in Developer Mode)

HSM4-LED-every-3-seconds


7. PRODUCTION MODE (permanent binding)

When you have completed all your development work and you are ready to deploy your system into the field we recommend that you permanently bind your HSM4 to a ‘specific host Pi and SD card’.

WARNING: THIS BINDING PROCESS IS PERMANENT AND CANNOT BE REVERSED. PAY ATTENTION TO THE FOLLOWING:

  • Your specific HSM4 will be locked to the specific host Pi and it is impossible to move or bind your HSM4 to another Pi. There are no factory resets, masterkeys or other forms of recovery.

  • If you are using the perimeter_detect features, then the sequence in which you arm, disarm is very important. Be sure to follow the process steps below.

  • Once you have locked your HSM4 into production mode, Zymbit cannot guarantee its operation if you subsequently do a major distribution upgrade (e.g. Raspbian Jessie to Stretch). **Contact Zymbit for more information.

  • If you decide that you are not ready for permanent binding then leave it in developer mode, but beware this makes it easier for a bad actor to replace the host with a rogue hardware.

Moving from Developer Mode to Production Mode

For HSM units, the binding is locked using a software API command. (This is unlike the Zymkey 4i, which is locked by physically cutting the lock tab.):

Ensure you have completed the following steps before moving to Production Mode:

  1. Install the battery onto HAT and install HSM onto HAT
  2. Place HAT onto the Pi (with power down on the Pi)
  3. Turn on the Pi (LED: 5 blinks per second)
  4. Configure the I2C bus
  5. Install HSM interface software package (LED: 1 blink every 3 seconds)
  6. Set Perimeter Event Actions to “none” or “notify only”
  7. Create your LUKS encrypted volume
  8. Install your applications into your encrypted volume
  9. Confirm your system and applications work fully as you intend

When you are ready to move HSM4 to Production Mode:

  1. Turn off the power to the Pi
  2. Do not remove the battery
  3. Call the API function to transition to Production Mode
  • C: zkLockBinding
  • C++: zkClass::lockBinding
  • Python: zymkey.client.lock_binding
  1. Replace the HSM4 onto the Pi and turn on power to the Pi
  2. Close your perimeter circuit(s) (enclosure lid)
  3. Clear Perimeter Detect Events
  4. Get Perimeter Detect Info to confirm prior events are cleared and the perimeter is closed.
  5. If the Perimeter Detect Event returns clear, then you can ‘arm your system’ as you require by setting Set Perimeter Event Actions to “none”, “notify” or “selfdestruct”
  6. Your system is now armed.

Please see Zymbit software documentation for further details.

Once you have successfully moved to Production Mode and rebooted your system, the LED blink pattern will change to 3 rapid blinks once every 3 seconds to indicate that HSM4 has bound to the host in production mode.

HSM4-LED-3times-every-3-seconds



PERIMETER DETECT

Refer to Using Perimeter Detect

Perimeter HDR (Header) Pinout

Perimeter FPC (Flexible Printed Circuit) Pinout


API DOCUMENTATION

API’s are available for Python, C, C++
Go to API Documents >


APPLICATION EXAMPLES

The quickest way to get started is to see the various methods at work by running these scripts:
python /usr/local/share/zymkey/examples/zk_app_utils_test.py
python /usr/local/share/zymkey/examples/zk_crypto_test.py

Please read the Zymbit community pages for documentation on: