Getting Started with ZYMKEY 3i


#1

SCOPE

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

Zymkey 3i replaces 2i products.

Zymkey 3i is NOT compatible with Zymkey 2i.

Zymkey 3i is version three 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 3i 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 3i - Feature Upgrades

Zymkey 3i offers a more streamlined Device ID and Authentication process that does NOT use Zymbit cloud services. This makes connections to third party cloud based data and authentication services, much easier to develop and manage in the field.

Zymkey 3i is shipped to you in ‘Developer Mode’ and that can easily moved from one Pi to another. When your application is ready to ship into the field, it can be locked into Production Mode for additional security. More details below.


HARDWARE & CONNECTORS


BATTERY INSTALLATION

If your zymkey_3i shipped without a battery, then you should install it now. The battery is a 3V CR1025.
and used to support the RTC. Details on how the RTC is set to NTP can be found here.

(If you ordered zymkey_3i__lite, these devices do not require a battery).

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

HARDWARE INSTALLATION

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 with battery facing upwards. Be sure your Zymkey 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 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: 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 toggle the state of the I2C bus to “ON” - “OFF” - “ON”. This provides a reliable known ON state for the I2C bus.

  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. Select Interfacing Options -> I2C ->
    Would you like the ARM I2C interface to be enabled ? select (No), enter, enter

  4. Select Interfacing Options -> I2C ->
    Would you like the ARM I2C interface to be enabled ? select (Yes), enter, enter

  5. Arrow Right to Finish

  6. Now reboot your Pi.

Your I2C bus is now configured and ready to talk to the Zymkey. Next install the Zymkey interface software (ZKIFC) onto you 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
  • 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.

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 !

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

You will require a locking dongle to perform this function. If you do not have a locking dongle, see later instructions on how to make your own.

To make the binding permanent, power down the pi and physically install the Zymkey locking dongle to the OEM connector. After the pi is rebooted, the blue LED should blink rapidly 3 times every 3 seconds which indicates that the binding is permanent. The locking dongle can now be removed.


API DOCUMENTATION & APPLICATIONS

API

The API documents are available here:

for Python:

https://s3.amazonaws.com/zk-sw-repo/zk_app_utils.py.pdf

for C++:

https://s3.amazonaws.com/zk-sw-repo/zkAppUtilsClass.cpp.pdf

for C:

https://s3.amazonaws.com/zk-sw-repo/zk_app_utils.c.pdf

Or you can find them on your Pi after software installation at /usr/share/zymkey/doc/

Writing Applications

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 Zymkey community pages for documentation on:


OTHER

Making Your Own Locking Dongle

If your Zymkey did not ship with a locking dongle, you can easily make your own from a new connector or an old microUSB cable. A simple wire link is require between pins 3 and 4.


TROUBLESHOOTING FAQ



OpenSSL: Apache Setup, Generating CSR
#2

#6

#7

It is important that python-dev is installed, otherwise the installation will fail with

" fatal error: Python.h: No such file or directory"


#9

#11

#12

Actually, I am using the Raspbian Jessie image from April and have not had any troubles in my testing. apt-cache rdepends python-dev shows that python should bring in python-dev automatically. Perhaps with older images this was an issue? In any case, I have amended our installation script to bring it in. Thanks for posting that.


#13

#14

Using the Real Time Clock (RTC) on Zymkey
#15