Getting Started with ZYMKEY 4i

#1

SCOPE

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

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)


BATTERY INSTALLATION

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!!


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


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 supports two operating modes:

  1. Developer Mode: bindings are temporary, zymkey can be moved to different Pi hosts and SD Cards
  2. Production Mode: binding is permanent ! zymket 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 upgrade your Linux distribution.** 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 !

  1. Install the battery on Zymkey
  2. Place Zymkey onto the Pi (with power down on the pi)
  3. Turn on the Pi
  4. Install and bind the Zymkey and Pi
  5. Set Perimeter Event Actions to “none” or “notify only”
  6. Create your LUKS encrypted volume
  7. Install your applications into your encrypted volume
  8. 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 !

  1. Turn off the power to the Pi.
  2. Do not remove the battery.
  3. Remove the zymkey from the Pi
  4. Now Cut the Lock Tab
  5. Replace the Zymkey onto the Pi and turn on power to the Pi
  6. Close your perimeter circuit(s) (enclosure lid)
  7. Clear Perimeter Detect Events
  8. Get Perimeter Detect Info to confirm prior events are cleared and the perimeter is closed.
  9. 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”
  10. Your system is now armed.

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


PERIMETER DETECT

Refer to Using Perimeter Detect


API DOCUMENTATION

API’s are available for Python, C, C++
Go to API Documents >


APPLICATION EXAMPLES

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:


TROUBLESHOOTING FAQ


AWS IoT - TLS Client Certificate Authentication using Zymkey 4i
Getting Started with Zymkey USB
Encrypting Your Root File System on Raspberry Pi - using LUKS & dm-crypt
Zymkey as TPM
unlisted #2
listed #3
pinned globally #4
Verifying Zymkey Signatures against Public Key on AWS and other Devices
#6

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.

#7

Hello,

When running the install_zk_sw.sh script over a previous install, the create_zk_crypt_vol symlink fails to get recreated because it already exists. Can you implement a check in the script to delete and recreate it?

:~ $ curl -G https:// s3.amazonaws. com/zk-sw-repo/install_zk_sw.sh | sudo bash
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 1716 100 1716 0 0 6286 0 --:–:-- --:–:-- --:–:-- 6308
Installing prerequisites…Searching for pip
Best match: pip 9.0.1
Processing pip-9.0.1-py2.7.egg
pip 9.0.1 is already the active version in easy-install.pth
Installing pip script to /usr/local/bin
Installing pip2.7 script to /usr/local/bin
Installing pip2 script to /usr/local/bin
Using /usr/local/lib/python2.7/dist-packages/pip-9.0.1-py2.7.egg
Processing dependencies for pip
Finished processing dependencies for pip
Requirement already satisfied: inotify in /usr/local/lib/python2.7/dist-packages
You are using pip version 9.0.1, however version 9.0.3 is available.
You should consider upgrading via the ‘pip install --upgrade pip’ command.
Requirement already satisfied: pycurl in /usr/lib/python2.7/dist-packages
You are using pip version 9.0.1, however version 9.0.3 is available.
You should consider upgrading via the ‘pip install --upgrade pip’ command.
Requirement already satisfied: progress in /usr/local/lib/python2.7/dist-packages
You are using pip version 9.0.1, however version 9.0.3 is available.
You should consider upgrading via the ‘pip install --upgrade pip’ command.
Requirement already satisfied: python-gnupg in /usr/local/lib/python2.7/dist-packages
You are using pip version 9.0.1, however version 9.0.3 is available.
You should consider upgrading via the ‘pip install --upgrade pip’ command.
done.
Importing Zymbit Packages gpg key… done.
Installing /etc/apt/sources.list.d/zymbit.list…done…Updating now.
Installing Zymkey Packages…ln: failed to create symbolic link ‘/usr/local/bin/create_zk_crypt_vol’: File exists
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 11491 100 11491 0 0 37781 0 --:–:-- --:–:-- --:–:-- 37799
Rebooting now…

#8

trying to install the i4 on RPi 3 stretch 9.4, after the installation is finished I reboot the system and the module’s LED turns off and I get the following error -
[FAILED] Failed to start Restore System Clock from Zymkey.
See ‘systemctl status zkbootrtc.service’ for details.

#9

Does this happen on each reboot? How’s your power supply? Make sure that you have a power supply that is capable of putting out at least 2.5A.

Check out
Power Quality - How it Impacts Software & System Reliability

#10

In Developer mode, are there any steps I can take to test that my Zymkey is doing what i expect it to do before moving it to production mode?

1 Like
#11

Before you move to production mode we recommend you develop your applicaition, using the Zymbit API functions as needed.

For example, if you planning on encrypting your file system using LUKS then build that first, before you lock into production mode.

If your Zymkey is working in developer mode, it will work in production mode.

#12

Thanks Phil. I have performed the “encrypt using LUKS” and seem to have that working. I am noticing issues booting after a power cycle however. Sometimes it will take me 3 or more power cycles to get my Pi to boot up. Once it does boot, everything seems fine. Is this something you have seen/heard of before or is my issue unrelated to the Zymkey?

#13

smbrandnojr
There is a high probability your issue is related to power supply quality: Zymkey monitors the power rails and if they don’t come up cleanly (after a power cycle) then it will remain locked. If you have other items plugged into your pi (USB devices, display, or GPIO attached devices), these can put additional stress on the power supply at power up.

Suggested paths forward :

  1. read this, and be sure to look for the power thunderbolt which is a sure sign of an overloaded power supply. Power Quality - How it Impacts Software & System Reliability
  2. try rebooting without power cycling.
  3. increase the capacity of your power supply.
#14

Hi,

I have specific needs and would like to made an iso with a raspbian distrib and many libraries already installed. I would like to proceed to an offline setup of all the zymkey libraries and just launch a last script to proceed to the zymkey module setup.

How could I do that? I can find all theese informations on your aws repository:

apt-repo-jessie/conf/distributions
apt-repo-jessie/db/checksums.db
apt-repo-jessie/db/contents.cache.db
apt-repo-jessie/db/packages.db
apt-repo-jessie/db/references.db
apt-repo-jessie/db/release.caches.db
apt-repo-jessie/db/version
apt-repo-jessie/dists/jessie/InRelease
apt-repo-jessie/dists/jessie/Release
apt-repo-jessie/dists/jessie/Release.gpg
apt-repo-jessie/dists/jessie/main/binary-arm64/Packages
apt-repo-jessie/dists/jessie/main/binary-arm64/Packages.gz
apt-repo-jessie/dists/jessie/main/binary-arm64/Release
apt-repo-jessie/dists/jessie/main/binary-armhf/Packages
apt-repo-jessie/dists/jessie/main/binary-armhf/Packages.gz
apt-repo-jessie/dists/jessie/main/binary-armhf/Release
apt-repo-jessie/pool/main/libz/libzk/libzk_1.1-11_armhf.deb
apt-repo-jessie/pool/main/libz/libzymkeyssl/libzymkeyssl_1.0-5_armhf.deb
apt-repo-jessie/pool/main/libz/libzymkeyssl/libzymkeyssl_1.0-7_armhf.deb
apt-repo-jessie/pool/main/z/zkapputilslib/zkapputilslib_1.1-7_armhf.deb
apt-repo-jessie/pool/main/z/zkapputilslib/zkapputilslib_1.1-8_armhf.deb
apt-repo-jessie/pool/main/z/zkbootrtc/zkbootrtc_1.1-10_armhf.deb
apt-repo-jessie/pool/main/z/zkifc/zkifc_1.2-14_armhf.deb
apt-repo-jessie/pool/main/z/zkifc/zkifc_1.2-15_armhf.deb
apt-repo-jessie/pool/main/z/zksaapps/zksaapps_1.0-8_armhf.deb
apt-zymkey-pubkey.gpg
conv_edev_boot.tar.gz
conv_edev_boot.tar.gz.sig
conv_edev_rfs.tar.gz
conv_edev_rfs.tar.gz.sig
create_zk_crypt_vol
install_zk_sw-beaglebone.sh
install_zk_sw.sh
luks.gpg
mk_encr_ext_rfs.sh
mk_encr_sd_rfs-beaglebone.sh
mk_encr_sd_rfs.sh
zkAppUtilsClass.cpp.pdf
zk_app_utils.c.pdf
zk_app_utils.py.pdf
zk_prep_encr

Should I download all of this and setup the .deb one by one? What is the last step to do to setup the zymkey module after having setup the libraries needed?

Thx by advance :grin:

#15

Hi! any answer? thx :wink:

#16

hi :frowning:
i have same problem…i go to production mode by Manual Cut-2-Lock and my raspberry do not start!!!
why?

#17

Hi this is my 2 deployment with raspberry pi raspbian Jessie (Linux pi 4.9.35+ #1014 Fri Jun 30 14:34:49 BST 2017 armv6l GNU/Linux).
After I issue the command “curl -G https://s3.amazonaws.com/zk-sw-repo/install_zk_sw.sh | sudo bash” and manually reboots still the zymkey not binding. blue led blinks fast not slow as i blink in 3 seconds.
Then I tried “sudo apt-get update” and at the last part this echo came out…
“W: GPG error: https://zk-sw-repo.s3.amazonaws.com jessie InRelease: The following signatures couldn’t be verified because the public key is not available: NO_PUBKEY CD71D52EB867632F”

Please help …thanks

#18

Now I re-install with raspbian stretch and did the same procedure and it did not bind on the first reboot and finally after the 3rd reboot the blue led start blinking slowly. So I started to do LUKS procedure with “curl -G https://s3.amazonaws.com/zk-sw-repo/mk_encr_sd_rfs.sh | sudo bash”.
But it said sda is not there. So I checked and the external 64GB sd card is installed on sdb / sdb1. so I issued the command “curl -G https://s3.amazonaws.com/zk-sw-repo/mk_encr_sd_rfs.sh | sudo bash -s – -x /dev/sdb” and process went well and rebooted after 1.5 hours.
After rebooting blue led still blinking fast seems not bound. And do a sudo service zkifc stop and start and started to blink slow.
Then I reboot without the zymkey and reboots. It supposed not to boot is that correct?
Then I reboot the RPI with the zymkey but this time without the external sd card that the luks process temporarily put the root folder and then it does not boot as mentioned the sda or sdb not accessible. then when plugged the sd card while boot process is on going it continued to boot up until the rpi login?

#19

I re-download the stretch and re-installed to sd card and tried again.
It is know working fine. Not sure what happen there. But all download and raspbian installation went well. If you got any idea what happen I will be happy to know.
But right now it zymkey binding and LUKs are working well.

#20

Hi

I have big troubles, now:

  • I am working on a pi 0, with stretch distrib
  • one of my zymkey seems to be break, it flash like this: 5 blink quite slow, and a lot of speed blinks, and again 5 slow, etc.
  • on the same raspberry, same power source, another zymkey works perfectly well; each has their proper cell coin

I am becoming crazy right now. The same problem happened few month ago so I have another zymkey breaks… Maybe I made a mistake but for the price I hope I can have an answer about this.

Why can I do?? How can I check if the device is really “ok”? Is there a procedure to erase it?

By the way, you still didn’t answer to me about an offline enrolment procedure (above): should I unpackage all the .deb one by one.

I was fan of your product but now I am becoming more and more mistrustful and don’t want to try things by my own to do not break a new devices…

Thx for the (quick I hope) answer.

#21

Hi ,
Here are some suggestions for help us try and debug your issues:

  • Can you confirm that the ‘problem zymkey’ is not locked (tab cut).
  • If not locked, you can check if the device is working by getting accellerometer data. Read the data and tap the device, you should be able to read force and direction attributes.
  • There is no ‘erase’ on the device. If not locked, it will bind to each new host it sees.
  • If you have a third zymkey spare, then perhaps you can test that too, so at least narrow down the potential problem (to a specific zymkey, or something is the system).