When you have completed your development work with the Zymbit SEN or HSM and are ready to deploy your system into the field, we recommend that you permanently bind your Zymbit SEN or HSM to a specific host device and SD card.

Summary of Steps

Develop your application

• Ensure your host has all the necessary prerequisites in place to interface with the Zymbit SEN or HSM and that it will be able to run your software application.

Active Production Mode

• Permanently bind your Zymbit SEN or HSM to the host device.

Develop your application

To begin, ensure that you have followed the Getting Started guide for your Zymbit SEN or HSM carefully to install the prerequisite Zymbit Driver Package:

To reiterate, before you continue, the following steps should be complete:

• Install your Zymbit SEN or HSM hardware.
• Install a battery on the Zymbit SEN or HSM.
• Install Zymbit SEN or HSM software on the host and establish temporary binding in development mode.

After these steps have been completed, you are ready to prepare your device for permanent binding.

Prepare Perimeter Detect

The Perimeter Event Actions for your Zymbit SEN or HSM should be set to none or notify only. If your Zymbit SEN or HSM’s action mode is set to selfdestruct, you might render your Zymbit SEN or HSM useless while attempting to activate Production Mode.

To do this quickly, with the Zymbit SEN or HSM client libraries installed, you can run the following shell command to use the Python API to communicate with the Zymbit SEN or HSM and set the Perimeter Event Actions to do nothing when triggered:

python3 -c "import zymkey;
for ch in (0, 1):
    zymkey.client.set_perimeter_event_actions(ch, action_notify=False, action_self_destruct=False)
zymkey.client.clear_perimeter_detect_info()"

Prepare your application

One of the main uses of the Zymbit HSM is to protect an encrypted root filesystem. If you are using Bootware, encryption is done for you. If you intend to use your Zymbit SEN or HSM to encrypt your root file system without Bootware, you should complete that step now, using our guide. This step is highly recommended.

You should then install your application on your host SBC (in the encrypted volume, if applicable).

Test, debug, and test again

Test the functionality of your application thoroughly to ensure it is free of major defects that will prevent it from functioning properly. After the Zymbit SEN or HSM has been bound to your host SBC, especially if Perimeter Detect features are in use, it may be difficult to make significant chances to your configuration without locking youself out of the Zymbit SEN or HSM, depending on the nature of your application and its configuration.

Activate Production Mode

For all Zymbit SEN and HSM models, to go into Production Mode only requires a function call followed by a reboot. With the Zymkey4, a physical tab is cut to go into Production Mode.

See Cutting ZYMKEY4 Production Mode tab for instructions for activating Production Mode on the ZYMKEY4.

The API function lock binding puts the HSM into Production Mode. Below are three examples which check the current binding info, lock the HSM binding, then check the current binding info again. Remove the comments around the lock binding function to move to Production Mode.

// gcc example_binding.c -I /usr/include/zymkey -l zk_app_utils -o example_binding

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include "zk_app_utils.h"
#include "zk_b64.h"

void check_code(int code, char* location){
  if (code < 0)
  {
    fprintf(stderr, "FAILURE: %s - %s\n", location, strerror(code));
  }
  else if (code >= 0)
  {
    fprintf(stdout, "SUCCESS: %s - %d\n", location, code);
  }
}

void HSM_soft_bind(zkCTX zk_ctx)
{
  bool binding_is_locked = false;
  bool is_bound = false;
  int ret = zkGetCurrentBindingInfo(zk_ctx, &binding_is_locked, &is_bound);
  check_code(ret, "zkGetCurrentBindingInfo");
  printf("Binding is locked: ");
  printf(binding_is_locked ? "true" : "false");
  printf("\n");
  printf("HSM is bound: ");
  printf(is_bound ? "true" : "false");
  printf("\n\n");

  //ret = zkLockBinding(zk_ctx);
  //if(binding_is_locked && is_bound)
  //{
  //  check_code(ret, "zkLockBinding - Already Bound");
  //}
  //else
  //{
  //  check_code(ret, "zkLockBinding");
  //}
  //printf("\n");

  ret = zkGetCurrentBindingInfo(zk_ctx, &binding_is_locked, &is_bound);
  check_code(ret, "zkGetCurrentBindingInfo");
  printf("Binding is locked: ");
  printf(binding_is_locked ? "true" : "false");
  printf("\n");
  printf("HSM is bound: ");
  printf(is_bound ? "true" : "false");
  printf("\n\n");
}

int main()
{
  zkCTX zk_ctx;
  int status = zkOpen(&zk_ctx);
  check_code(status, "zkOpen");
  printf("\n\n");

  HSM_soft_bind(zk_ctx);

  status = zkClose(zk_ctx);
  check_code(status, "zkClose");
  printf("\n");

  return 0;
}

#include <stdio.h>
#include <zkAppUtilsClass.h>

using namespace std;
using namespace zkAppUtils;

void HSM_soft_bind(zkClass* zk_inst)
{
  bool binding_is_locked = false;
  bool is_bound = false;
  zk_inst->getCurrentBindingInfo(binding_is_locked, is_bound);
  printf("Binding is locked: ");
  printf(binding_is_locked ? "true" : "false");
  printf("\n");
  printf("HSM is bound: ");
  printf(is_bound ? "true" : "false");
  printf("\n");

  //zk_inst->lockBinding();
  //printf("lockBinding successful\n");

  zk_inst->getCurrentBindingInfo(binding_is_locked, is_bound);
  printf("Binding is locked: ");
  printf(binding_is_locked ? "true" : "false");
  printf("\n");
  printf("HSM is bound: ");
  printf(is_bound ? "true" : "false");
  printf("\n");
}

int main()
{
  zkClass* zk_inst;
  zk_inst = new zkClass();

  HSM_soft_bind(zk_inst);

  delete zk_inst;
  return 0;
}

import zymkey
tup = zymkey.client.get_current_binding_info()
print("HSM is bound: " + str(tup[1]))
print("Binding is locked: " + str(tup[0]))

#zymkey.client.lock_binding()

tup = zymkey.client.get_current_binding_info()
print("HSM is bound: " + str(tup[1]))
print("Binding is locked: " + str(tup[0]))

Finalize your device for deployment

After using the APIs to lock binding, reboot. The blink pattern on the Zymbit SEN or HSM will change to 3 rapid blinks once every 3 seconds to indicate that Zymbit SEN or HSM has bound to the host in Production Mode.

If you are using the Perimeter Detect features, close your perimeter circuits (for example, by closing the enclosure’s lid), and then clear any Perimeter Detect Events using the API:

python3 -c "import zymkey; idx = 0;
zymkey.client.clear_perimeter_detect_info()
for p in zymkey.client.get_perimeter_detect_info():
  if p:
    print(f'Channel {idx} has a detected breach event. Clear the Perimeter Detect Events again.')
    idx += 1
  else:
    print('No perimeter breach detected.')"

If you get a message that a breach event was detected from the above command, run it again to ensure all events have been cleared. When it confirms that no breach events have been detected, it is then safe to arm the system by setting the Perimeter Event Actions to notify or selfdestruct, if desired.

Your system is now armed and ready to be used in the field!