Getting Started with ZYMKEY 4i



This Getting Started Guide applies to Zymkey 4i products only.

Zymkey 4i replaces 3i and 2i products.

Refer to Zymkey 3i and Zymkey 2i Getting Started Guides if you are using these 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

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.


(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.)

Power Quality

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

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 Zymkey. Next install the Zymkey interface software (ZKIFC) onto your Pi.


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
  • pip

Download and install the necessary Zymbit services onto your Pi.
curl -G | 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.

  1. First, let’s uninstall your current version of OpenSSL.

    sudo apt-get remove openssl
    sudo apt-get remove curl rpi-update libcurl3
  2. 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 jessie main contrib non-free rpi
    Press ctrl-O then ctrl-M to save.

  3. Now update your repo info.

    sudo apt-get update
  4. At this point you can reinstall OpenSS and CURL.

    sudo apt-get install openssl
    sudo apt-get install curl rpi-update libcurl3
  5. If everything was done correctly, your OpenSSL version should be 1.0.1t. You can check it with this command:

    openssl version
  6. Next we will change you back to the Raspbian Stretch repos. Change /etc/apt/sources.list back to stretch.

  7. 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.)

Manual Cut-2-Lock

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



The API documents are available here:

for Python:

for C++:

for C:

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:
python /usr/local/share/zymkey/examples/
python /usr/local/share/zymkey/examples/

Please read the Zymkey community pages for documentation on:


Getting Started with Zymkey USB
AWS IoT - TLS Client Certificate Authentication using Zymkey 4i
LUKS Encrypt Your Root File System on Raspberry Pi



Verifying Zymkey Signatures against Public Key on AWS and other Devices

Probably best to just leave “jessie” where “stretch” was until they upgrade the software to support Openssl. Many packages rely on Openssl, and I’ve had nothing but issues trying to work around this.

I cannot install Jessie on my PI at all, which is what I’d love to do at this point.