ZYMKEY4i is the fourth generation of the Zymbit security module designed specifically to work with Raspberry Pi and NVIDIA Jetson. It connects to the GPIO header of the SBC and uses the I2C bus and GPIO-4 to communicate with the SBC CPU via an encrypted channel.
|Step Description||Notes and/ or Checkpoint|
|0||Hardware & Connections||What plugs into where.|
|1||Battery Install||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.|
|2||Hardware Install||Blue LED will blink rapidly to indicate Zymkey is connected correctly but not yet configured.|
|3||Configure 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.|
|4||Software Install & API||Blue LED will blink once every three seconds to indicate Zymkey is connected and configured.|
|5||Developer Mode||DEVELOPER MODE- bindings are temporary, Zymkey can be moved to different hosts and SD Cards.|
|6||Production Mode||PRODUCTION MODE- binding is permanent! Zymkey can NOT be moved to different hosts or SD Cards. Transition to Production Mode by cutting Lock Tab.|
In this Getting Started Guide we describe how to install your Zymkey 4i to a Raspberry Pi or Jetson Nano/ Xavier running Rasbian or Ubuntu. The installation process is the same for both of these Linux distributions.
Your Zymkey 4i can be fitted with a 3V CR1025 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.
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 CR1025 coincell battery such as the Panasonic - CR-1025EL, LITHIUM MANGANESE DIOXIDE.
IMPORTANT: Note the correct polarity with +ve facing upwards !!
Power down your Raspberry Pi or NVIDIA Jetson first!
IMPORTANT: Installing your hardware correctly is important to avoid destroying your SBC or Zymkey. Be sure to follow the images below to ensure the first 10 GPIO pins are correctly aligned with the Zymkey header. Note: the coin cell battery should be facing up.
Fit the Zymkey 4i with LED and battery holder facing upwards. Be sure the black connector is properly aligned with the first 10 GPIO pins and that pressed firmly down onto the header. If misaligned, this could cause damage to the Zymkey and/or your Raspberry Pi. Your Zymkey should fit relatively snug and maintain a tight interference fit around the pins.
Zymkey occupies 10 pins on the GPIO header. It can also be used with other GPIO 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 Zymkey is 0x30. If this conflicts with another device in your system, you can reconfigure the Zymkey to use another address of your choice. Learn more>
Option (RPi): Using Zymkey with another Pi Plate fitted.
Finally, power up the device and you will see a blue LED blinking rapidly and consistently (5 blinks 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 matters to the reliable and secure operation of your system and Zymkey. Learn more>
For Raspbian Operating Systems you must configure the state of the I2C bus to "ON".
For Ubuntu Operating Systems, the I2C bus is automatically configured and you may skip this step.
For Raspbian OS:
Your I2C bus is now configured and ready to talk to the Zymkey. Next install the Zymkey interface software (ZKIFC) onto your Pi.
The default I2C address for Zymkey is 0x30.
IMPORTANT: The default mode for the cpu scaling governor is ondemand. There have been some issues with the interaction between the zymkey 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 zymkey. How to set cpu governor to performance.
For the Jetson the Operating System - Tegra - is based on Ubuntu. The I2C bus is enabled by default. There are no additional steps required.
The default I2C address for Zymkey is 0x30.
Next install the Zymkey interface software (ZKIFC) onto your SBC.
Login to your host device.
NOTE: Your Zymkey will require a number of packages to be installed from the Raspberry Pi/ Canonical and Zymbit apt repositories. The following setup script will be installing a number of files and software packages on your system:
Make sure curl is installed (typically not included with Tegra [Ubuntu 18.04] by default):
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
(grab a cup of coffee because this will take between 4 and 20 minutes).
Good security begins with assigning each device a unique and unalterable identity (Device ID), that is used to authenticate subsequent interactions with the device.
Zymkey generates a unique Device ID by measuring certain attributes of the specific host Raspberry Pi/ Jetson (Measurement), and then combining that Measurement with the unique ID of a specific Zymkey. The combination process uses a cryptographic function and this process is generally termed "binding". On completion of a binding process, then Zymkey is said to be "bound" to the Pi.
Zymkey supports two operating modes:
When the software installation has completed, reboot your device. After the reboot has completed, the Pi/ Jetson will perform an operation that will temporarily bind the Zymkey to your SBC. Once the Zymkey is bound to the SBC, the Zymkey's blue LED should blink slowly - once every 3 seconds - to indicate that the binding is complete.
At this point, your Zymkey is now in Developer Mode, the binding is temporary and the Zymkey can be moved to another Pi/ Jetson and the binding process repeated.
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 Zymkey to a 'specific host device and SD card '.
WARNING: THIS BINDING PROCESS IS PERMANENT AND CANNOT BE REVERSED. PAY ATTENTION TO THE FOLLOWING:
Your specific Zymkey will be locked to the specific host device and it is impossible to move or bind your Zymkey to another device. 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 Zymkey 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.
Do not cut the Lock Tab yet!
Do not cut the Lock Tab yet!
IMPORTANT: first power down your device and Zymkey. Removing the Cut-2-Lock tab can be done in situ, or by removing the Zymkey from the SBC. Also insure that your perimeter detect actions are not set to self-destruct mode. Follow the steps outlined above, and refer to the programming api documents for more information on the operation of Perimeter Detect Events.
Refer to Using Perimeter Detect
API's are available for Python, C, C++ Go to API Documents >
The quickest way to get started is to see the various methods at work by running these scripts: