Getting Started: ZYMKEY4i with NVIDIA JETSON

Using ZYMKEY4i with Nvidia Jetson - Xavier NX and Nano

ZYMKEY4i is the fourth generation of the Zymbit security module designed to work with single board computers like the NVIDIA Jetson. The ZYMKEY supports the Xavier NX and the Nano. It connects to the GPIO header of the Jetson and uses the I2C bus and GPIO-4 to communicate with the Jetson CPU via an encrypted channel.

ZYMKEY 4i can also be used with other other single board computers, including the Raspberry Pi. Click here for Getting Started with ZYMKEY4i for Raspberry Pi.


SETUP STEPS

STEP_DESCRIPTION NOTES AND / OR CHECKPOINT
0 Hardware & Connections What plugs into where.
1 Battery Install The battery is required to maintain the Real Time Clock and the perimeter detect circuits when the host power is removed. See this chart for more information.
2 Hardware Install Blue LED will blink rapidly to indicate Zymkey is connected correctly but not yet configured.
3 Configure I2C Bus The Jetson runs Tegra, based on Ubuntu. The I2C Bus is enabled by default. No additional configuration is necessary.
4 Software Install & API Blue LED will blink once every three seconds to indicate Zymkey is connected and configured.
5 Developer Mode DEVELOPER MODE- bindings are temporary, Zymkey can be moved to different SBC hosts and SD Cards.
6 Production Mode PRODUCTION MODE- binding is permanent! Zymkey can NOT be moved to different SBC hosts or SD Cards. Transition to Production Mode by cutting Lock Tab.

SCOPE

In this Getting Started Guide we describe how to install your Zymkey 4i to an Nvidia Jetson running Tegra (Ubuntu 18.04).

Learn about Linux OS support for Zymkey.


0.HARDWARE & CONNECTORS


1. BATTERY INSTALLATION (Recommended)

Your Zymkey 4i can be fitted with a 3V CR1025 coincell battery that is used to maintain operation of the real-time-clock (RTC) and tamper detect features in the event that main power (from the GPIO header) is lost.

If you choose not to fit a battery, then these important security features will not function in the event main power is removed.

Battery installation is highly recommended if your device is vulnerable to physical access !

Use a high quality 3V CR1025 coincell battery such as the Panasonic - CR-1025EL, LITHIUM MANGANESE DIOXIDE.

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


2. HARDWARE INSTALLATION

Power down your Jetson first!

IMPORTANT: Installing your hardware correctly is important to avoid destroying your Jetson 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 LED and battery holder 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 misaligned, this could cause damage to the Zymkey and/or your Jetson. 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 other GPIO 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.
Learn more>

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


Power On, Confirm Operation

Finally, power up the Jetson and you will see a blue led blinking rapidly and consistently (5 blinks per second)

zymkey-LED-flashing-10-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.


3. CONFIGURE THE I2C BUS

For the Jetson the Operating System - Tegra - is based on Ubuntu. The I2C bus is enabled by default. There are no additional steps required.

The default I2C address for Zymkey is 0x30.

Next install the Zymkey interface software (ZKIFC) onto your SBC.


4. SOFTWARE PACKAGE INSTALLATION & API

Login to your Jetson

NOTE: Your Zymkey will require a number of packages to be installed from the Canonical and Zymbit 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

The Zymbit install process uses curl which is not included with Tegra (Ubuntu 18.04) by default. Install curl:

sudo apt install curl

Download and install the necessary Zymbit services onto your SBC.

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

Zymkey supports two operating modes:

  1. Developer Mode: bindings are temporary, zymkey can be moved to different Jetson hosts and SD Cards.
  2. Production Mode: binding is permanent! zymkey can NOT be moved to different Jetson hosts or SD cards.

5. DEVELOPER MODE (temporary binding)

When the software installation has completed, it will reboot your Jetson. After the reboot has completed, the Jetson will perform an operation that will temporarily bind the Zymkey to your Jetson. Once the Zymkey is bound to the host, the Zymkey’s blue LED should blink slowly - once every 3 seconds - to indicate that the binding is complete.

zymkey-LED-1-pulse-per-three--seconds

Zymkey operational, temporary binding to host (Zymkey in Developer Mode)

At this point, your Zymkey is now in Developer Mode, the binding is temporary and the Zymkey can be moved to another host and the binding process repeated.


6. 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 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 Jetson and it is impossible to move or bind your Zymkey to another host. There are no factory resets, master keys 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. Bionic to Focal).** 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.

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 Jetson (powered off)
  3. Turn on the Jetson
  4. Install and bind the Zymkey and Jetson
  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 Jetson.
  2. Do not remove the battery.
  3. Remove the Zymkey from the Jetson.
  4. Now Cut the Lock Tab
  5. Replace the Zymkey onto the Jetson and power on.
  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 Jetson and Zymkey. Removing the Cut-2-Lock tab can be done in situ, or by removing the Zymkey from the SBC. 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.



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:

----------

Hi, is there a performance hit when using encryption on sd card.

Is encryption done by passing data through the key, or does zymkey load an application to encrypt/decrypt on Nano CPU

Hi, can I use this device to encrypt a micro sd card on Jetson Nano with Jetpack 4.4.1?

Yes, encrypting the SD card on the Nano at 4.4.1 is supported.

1 Like

And what about jetpack 4.5.1?

Encryption with Jetpack 4.5.1 is currently not supported. Someone from our customer support team will be in touch to discuss your needs.

Okay, thanks. I’m good for now but if I need more help I won’t hesitate contacting you!

I need some help Bob.
After running the script:
curl -G https://s3.amazonaws.com/zk-sw-repo/mk_encr_sd_rfs.sh | sudo bash

My Jetson Nano enters a boot loop state where the NVIDIA screen shows on and off infinitely.

What can I do?

This can happen if you downgrade from 4.5.1 to 4.4.1 by just loading a new image from the SD card. 4.5.1 moves the bootloader area. Instead of loading from an SD card image, you need to load 4.4.1 from the NVIDIA SDK Manager Method. I’ll follow up with you directly through support.

After flashing the jetson with the SDK manager it seems to be working fine.
Thanks!

Hi there,

I have executed the installation script successfully (zkifc service is active and running also) but zymkey keeps blinding rapidly and consistently and example scripts don’t work (AttributeError: ‘NoneType’ object has no attribute ‘sign’)

Any suggestion?

Thanks

Mikel