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 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 Jessie.
If you are using Arch or other mainstream Linux distributions, Contact Zymbit to learn how to integrate Zymkey into your application.
Zymkey 4i Feature Upgrades
Based upon customer demand we have created two versions of Zymkey 4i.
Standard: that integrates physical security features.
Lite: that offers crypto-only services, at a lower cost.
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.
(If you ordered Zymkey 4i lite, these devices do not require a battery).
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.
Option: The default configuration uses GPIO4. This can be reconfigured to use another GPIO. Contact Zymbit for more details.
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.
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).
Using Raspbian Stretch?
For anyone using Raspbian Stretch, there are a couple of extra steps:
The Zymkey SSL engine does not currently support the newest version of OpenSSL and CURL that Raspbian Stretch uses as a repository. To use the Zymkey SSL engine, we must revert to the older versions of these two software by grabbing them from the Raspbian Jessie repositories and marking them as do not update to the Stretch versions.
Here are the steps to get straight to downgrading OpenSSL and CURL.
First, let’s uninstall your current version of OpenSSL.
sudo apt-get remove openssl sudo apt-get remove curl rpi-update libcurl3
Now we will switch to the Jessie repository to install OpenSSL 1.0.1t. Open up the repo file with this command.
sudo nano /etc/apt/sources.list
Change the word stretch to jessie. The link should look like this
deb http://mirrordirector.raspbian.org/raspbian/ jessie main contrib non-free rpi
Press ctrl-O then ctrl-M to save.
Now update your repo info.
sudo apt-get update
At this point you can reinstall OpenSS and CURL.
sudo apt-get install openssl sudo apt-get install curl rpi-update libcurl3
If everything was done correctly, your OpenSSL version should be 1.0.1t. You can check it with this command:
Next we will change you back to the Raspbian Stretch repos. Change /etc/apt/sources.list back to stretch.
Finally we will tell OpenSSL to not update past this version, re-update your repo info and then reboot.
sudo apt-mark hold openssl sudo apt-mark hold curl libcurl3 sudo apt-get update sudo reboot
If you have any other issues, feel free to let us know!
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 can be operated in two modes - Developer and Production mode.
Developer Mode (temporary binding)
Once the software installation has finished, 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, the binding is temporary and the Zymkey can be moved to another Pi and the binding process repeated.
Zymkey operational, temporary binding to host (developer mode)
Production Mode (permanently locked binding)
When you have completed all your development work and you are ready to deploy into the field you should permanently bind your Zymkey to a ‘specific’ Pi. This will lock your Zymkey into Production Mode.
IMPORTANT : this binding is permanent and cannot be reversed !
WARNING : Once you have locked your zymkey into production mode , we cannot gaurantee its operation if you subsequently upgrade your Linux distribution. Contact Zymbit for more information.
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 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.)
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.
Cut using sharp diagonal cutter pliers
Cut along guide notches
Finished cut should be flush to edge.
Refer to Using Perimeter Detect
API DOCUMENTATION & APPLICATIONS
The API documents are available here:
Or you can find them on your Pi after software installation at /usr/share/zymkey/doc/
The quickest way to get started is to see the various methods at work by running these scripts:
Please read the Zymkey community pages for documentation on: