This Getting Started Guide applies to Zymkey 4i products only.
Zymkey 4i replaces 3i and 2i products.
If you would like to upgrade your application from 3i or 2i products Contact Zymbit for assistance.
Zymkey 4i is backward compatible with Zymkey 3i.
Zymkey 4i - Security Module for Raspberry Pi
Zymkey 4i is version four of Zymkey, designed to interface to an I2C bus. It’s interface connector complies to the Raspberry Pi GPIO header, but it can also be used with other I2C configurations.
In this Getting Started guide we describe how to install your Zymkey 4i to a Raspberry Pi running Rasbian Stretch.
If you are using Arch or other mainstream Linux distributions, Contact Zymbit to learn how to integrate Zymkey into your application.
HARDWARE & CONNECTORS
(full version shown)
If your Zymkey 4i shipped without a battery, then you should install it now. The battery is a 3V CR1025 and used to support the Real Time Clock (RTC) and tamper detect features. Details on how the RTC is set to NTP can be found here.
Use a good battery! We recommend using a high quality coin cell battery such as the Panasonic - CR-1025EL, LITHIUM MANGANESE DIOXIDE
IMPORTANT: Note the correct polarity with +ve facing upwards!!
Power down your Raspberry Pi first!
IMPORTANT: Installing your hardware correctly is important to avoid destroying your Pi 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 battery 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 missaligned, 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 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.
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.
Option: Using Zymkey with another Pi Plate fitted.
Power On, Confirm Operation
Finally, power up the pi and you will see a blue led blinking rapidly and consistently (5 blinks per second)
Zymkey 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.)
Configure the I2C Bus:
Here we are going to configure the state of the I2C bus to “ON”.
- Log in to your pi and run
- Select Interfacing Options -> I2C ->
Would you like the ARM I2C interface to be enabled? select (Yes), enter, enter
- Arrow Right to Finish
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.
SOFTWARE PACKAGE INSTALLATION & API
For a bare raspbian system, first login to your pi.
NOTE: Your Zymkey 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
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.
Zymkey 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 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:
- Developer Mode: bindings are temporary, zymkey can be moved to different Pi hosts and SD Cards
- Production Mode: binding is permanent! zymkey can NOT be moved to different Pi hosts or SD cards
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 Zymkey to your pi. Once the Zymkey is bound to the pi, 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 in Developer Mode, the binding is temporary and the Zymkey can be moved to another Pi and the binding process repeated.
Zymkey operational, temporary binding to host (Zymkey in Developer Mode)
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 Zymkey 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 Zymkey will be locked to the specific host Pi and it is impossible to move or bind your Zymkey 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 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.
Process for Moving from Developer Mode to Production Mode
With Zymkey in Developer Mode (Lock Tab in Place)
Do not cut the Lock Tab yet!
- Install the battery on Zymkey
- Place Zymkey onto the Pi (with power down on the pi)
- Turn on the Pi
- Install and bind the Zymkey and Pi
- Set Perimeter Event Actions to “none” or “notify only”
- Create your LUKS encrypted volume
- Install your applications into your encrypted volume
- Confirm your system and applications work fully as you intend
When you are ready to move Zymkey to Production Mode,
Do not cut the Lock Tab yet!
- Turn off the power to the Pi.
- Do not remove the battery.
- Remove the zymkey from the Pi
- Now Cut the Lock Tab
- Replace the Zymkey onto the Pi and turn on power to the Pi
- Close your perimeter circuit(s) (enclosure lid)
- Clear Perimeter Detect Events
- Get Perimeter Detect Info to confirm prior events are cleared and the perimeter is closed.
- 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”
- Your system is now armed.
IMPORTANT: first power down your Pi and Zymkey. Removing the Cut-2-Lock tab can be done in situ, or by removing the Zymkey from the Pi. 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.
Cut using sharp diagonal cutter pliers
Cut along guide notches
Finished cut should be flush to edge.
Once you have successfully cut the lock tab and have rebooted your system, the blink pattern will change to 3 rapid blinks once every 3 seconds to indicate that Zymkey has bound to the host in production mode.
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: