C API Documentation

C interface to Zymkey Application Utilities Library.

Generated from zkapputilslib version 1.2.2-1 (commit a547582).

This file contains the C API to the the Zymkey Application Utilities library, libzk_app_utils. Systems intending to run such applications require that the libzkapputils package be installed.

This API facilitates writing user space applications which use Zymkey to perform cryptographic operations, such as:

  1. Signing of payloads using ECDSA
  2. Verification of payloads that were signed using Zymkey
  3. Exporting the public key that matches Zymkey’s private key
  4. “Locking” and “unlocking” data objects
  5. Generating random data Additionally, there are functions for changing the i2c address (i2c units only), setting tap sensitivity and controlling the LED.

Developers wishing to build applications which utilize the libzk_app_utils library should additionally install the libzkapputils-dev package, which contains the necessary development files for the Zymkey’s C library. To install this package on a system that does not need to run the applications (e.g. a Docker container or when cross compiling on a foreign architecture), use apt install --no-install-recommends libzkapputils-dev. This will prevent apt from installing the Zymkey’s zkifc driver daemon.

Usage:

#include <zymkey/zk_app_utils.h>

To add zkAppUtils as a dependency of a CMake-based project, add the following lines to your project’s CMakeLists.txt file:

find_package(zkAppUtils REQUIRED)
target_link_libraries(${target_name} zkAppUtils::zk_app_utils)

Projects may alternatively import the library dependency via pkg-config:

CFLAGS="$(pkg-config --cflags zkapputils)"
LDFLAGS="$(pkg-config --libs zkapputils)"

Zymkey Context

zkOpen function

int zkOpen(zkCTX *ctx)
Open a Zymkey context.

Parameters

ctx zkCTX *
(output) returns a pointer to a Zymkey context.

Returns

int
0 for success, less than 0 for failure.

zkClose function

int zkClose(zkCTX ctx)
Close a Zymkey context.

Parameters

ctx zkCTX
(input) The Zymkey context to close

Returns

int
0 for success, less than 0 for failure.

zkEnableSelfRestart function

int zkEnableSelfRestart(zkCTX ctx, bool enabled, int waitSec, int maxNumRestart)
Enables automatic restart of zkifc/zymbit device (in case of fatal error).

Parameters

ctx zkCTX
(input) Zymkey context.
enabled bool
(input) Enable/disable.
waitSec int
(input) Time in seconds to wait before attempting restart.
maxNumRestart int
(input) Maximum number of restarts to attempt.

Returns

int
0 for success, less than 0 for failure.

Random Number Generation

zkCreateRandDataFile function

int zkCreateRandDataFile(zkCTX ctx, const char *dst_filename, int rdata_sz)
Fill a file with random numbers.

Parameters

ctx zkCTX
(input) Zymkey context.
dst_filename const char *
(input) Absolute path name for the destination file.
rdata_sz int
(input) The number of random bytes to generate.

Returns

int
0 for success, less than 0 for failure.

zkGetRandBytes function

int zkGetRandBytes(zkCTX ctx, uint8_t **rdata, int rdata_sz)
Get an array of random bytes.

Parameters

ctx zkCTX
(input) Zymkey context.
rdata uint8_t **
(input) Pointer to a pointer of bytes.
rdata_sz int
(input) The number of random bytes to generate.

Returns

int
0 for success, less than 0 for failure.

Lock Data

zkLockDataF2F function

int zkLockDataF2F(zkCTX ctx, const char *src_pt_filename, const char *dst_ct_filename, bool use_shared_key)
Lock up source (plaintext) data from a file and store the results (ciphertext) in a destination file.
This function encrypts and signs a block of plaintext data from a file and stores the result in a destination file.
Note:

The zymkey has two keys that can be used for locking/unlocking operations, designated as ‘shared’ and ‘one-way’.

  1. The one-way key is meant to lock up data only on the local host computer. Data encrypted using this key cannot be exported and deciphered anywhere else.
  2. The shared key is meant for publishing data to other sources that have the capability to generate the shared key, such as the Zymbit cloud server.

Parameters

ctx zkCTX
(input) Zymkey context.
src_pt_filename const char *
(input) The absolute path to the file where the source (plaintext) data is located.
dst_ct_filename const char *
(input) The absolute path to the file where the destination (ciphertext) data should be deposited.
use_shared_key bool
(input) This parameter specifies which key will be used to used to lock the data up. A value of ‘false’ specifies that the Zymkey will use the one-way key whereas ’true’ specifies that the shared key will be used. Specify ’true’ for publishing data to another that has the shared key (e.g. Zymbit cloud) and ‘False’ when the data is meant to reside exclusively withing the host computer.

Returns

int
0 for success, less than 0 for failure.

zkLockDataB2F function

int zkLockDataB2F(zkCTX ctx, const uint8_t *src_pt, int src_pt_sz, const char *dst_ct_filename, bool use_shared_key)
Lock up source (plaintext) data from a byte array and store the results (ciphertext) in a destination file.
This function encrypts and signs a block of binary plaintext data and stores the result in a destination file.
Note: (See zkLockDataF2F for notes about keys)

Parameters

ctx zkCTX
(input) Zymkey context.
src_pt const uint8_t *
(input) Binary plaintext source byte array.
src_pt_sz int
(input) Size of plaintext source data.
dst_ct_filename const char *
(input) The absolute path to the file where the destination (ciphertext) data should be deposited.
use_shared_key bool
(input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

int
0 for success, less than 0 for failure.

zkLockDataF2B function

int zkLockDataF2B(zkCTX ctx, const char *src_pt_filename, uint8_t **dst_ct, int *dst_ct_sz, bool use_shared_key)
Lock up source (plaintext) data from a file and store the results (ciphertext) in a destination byte array.
This function encrypts and signs a block of plaintext data from a file and stores the result in a binary byte array.
Note: (See zkLockDataF2F for notes about keys)

Parameters

ctx zkCTX
(input) Zymkey context.
src_pt_filename const char *
(input) The absolute path to the file where the source (plaintext) data is located.
dst_ct uint8_t **
(output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_ct_sz int *
(output) A pointer to an integer which contains the size of the destination array.
use_shared_key bool
(input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

int
0 for success, less than 0 for failure.

zkLockDataB2B function

int zkLockDataB2B(zkCTX ctx, const uint8_t *src_pt, int src_pt_sz, uint8_t **dst_ct, int *dst_ct_sz, bool use_shared_key)
Lock up source (plaintext) data from a byte array and store the results (ciphertext) in a destination byte array.
This function encrypts and signs a block of plaintext data and stores the result in a binary byte array.
Note: (See zkLockDataF2F for notes about keys)

Parameters

ctx zkCTX
(input) Zymkey context.
src_pt const uint8_t *
(input) Binary plaintext source byte array.
src_pt_sz int
(input) Size of plaintext source data.
dst_ct uint8_t **
(output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_ct_sz int *
(output) A pointer to an integer which contains the size of the destination array.
use_shared_key bool
(input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

int
0 for success, less than 0 for failure.

Unlock Data

zkUnlockDataF2F function

int zkUnlockDataF2F(zkCTX ctx, const char *src_ct_filename, const char *dst_pt_filename, bool use_shared_key)
Unlock source (ciphertext) data from a file and store the results (plaintext) in a destination file.
This function verifies a locked object signature and decrypts the associated ciphertext data.
Note: (See zkLockDataF2F for notes about keys)

Parameters

ctx zkCTX
(input) Zymkey context.
src_ct_filename const char *
(input) The absolute path to the file where the source (ciphertext) data is located.
dst_pt_filename const char *
(input) The absolute path to the file where the destination (plaintext) data should be deposited.
use_shared_key bool
(input) This parameter specifies which key will be used to used to lock the data up. A value of ‘false’ specifies that the Zymkey will use the one-way key whereas ’true’ specifies that the shared key will be used. Specify ’true’ for publishing data to another that has the shared key (e.g. Zymbit cloud) and ‘False’ when the data is meant to reside exclusively withing the host computer.

Returns

int
0 for success, less than 0 for failure.

zkUnlockDataB2F function

int zkUnlockDataB2F(zkCTX ctx, const uint8_t *src_ct, int src_ct_sz, const char *dst_pt_filename, bool use_shared_key)
Unlock source (ciphertext) data from a byte array and store the results (plaintext) in a destination file.
This function verifies a locked object signature and decrypts the associated ciphertext data.
Note: (See zkLockDataF2F for notes about keys)

Parameters

ctx zkCTX
(input) Zymkey context.
src_ct const uint8_t *
(input) Binary ciphertext source byte array.
src_ct_sz int
(input) Size of ciphertext source data.
dst_pt_filename const char *
(input) The absolute path to the file where the destination (plaintext) data should be deposited.
use_shared_key bool
(input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

int
0 for success, less than 0 for failure.

zkUnlockDataF2B function

int zkUnlockDataF2B(zkCTX ctx, const char *src_ct_filename, uint8_t **dst_pt, int *dst_pt_sz, bool use_shared_key)
Unlock source (ciphertext) data from a file and store the results (plaintext) in a destination byte array.
This function verifies a locked object signature and decrypts the associated ciphertext data.
Note: (See zkLockDataF2F for notes about keys)

Parameters

ctx zkCTX
(input) Zymkey context.
src_ct_filename const char *
(input) The absolute path to the file where the source (ciphertext) data is located.
dst_pt uint8_t **
(output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_pt_sz int *
(output) A pointer to an integer which contains the size of the destination array.
use_shared_key bool
(input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

int
0 for success, less than 0 for failure.

zkUnlockDataB2B function

int zkUnlockDataB2B(zkCTX ctx, const uint8_t *src_ct, int src_ct_sz, uint8_t **dst_pt, int *dst_pt_sz, bool use_shared_key)
Unlock source (ciphertext) data from a byte array and store the results (plaintext) in a destination byte array.
This function verifies a locked object signature and decrypts the associated ciphertext data.
Note: (See zkLockDataF2F for notes about keys)

Parameters

ctx zkCTX
(input) Zymkey context.
src_ct const uint8_t *
(input) Binary ciphertext source byte array.
src_ct_sz int
(input) Size of ciphertext source data.
dst_pt uint8_t **
(output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_pt_sz int *
(output) A pointer to an integer which contains the size of the destination array.
use_shared_key bool
(input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

int
0 for success, less than 0 for failure.

ECDSA

zkGenECDSASigFromDigest function

int zkGenECDSASigFromDigest(zkCTX ctx, const uint8_t *digest, int slot, uint8_t **sig, int *sig_sz)
Generate a signature using the Zymkey’s ECDSA private key.

Parameters

ctx zkCTX
(input) Zymkey context.
digest const uint8_t *
(input) This parameter contains the digest of the data that will be used to generate the signature.
slot int
(input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
sig uint8_t **
(output) A pointer to a pointer to an array of unsigned bytes which contains the generated signature. This pointer is created by this function and must be freed by the application when no longer needed.
sig_sz int *
(output) A pointer to an integer which contains the size of the signature.

Returns

int
0 for success, less than 0 for failure.

zkGenECDSASigFromDigestWithRecID function

int zkGenECDSASigFromDigestWithRecID(zkCTX ctx, const uint8_t *digest, int slot, uint8_t **sig, int *sig_sz, uint8_t *recovery_id)
Generate a signature using the Zymkey’s ECDSA private key.

Parameters

ctx zkCTX
(input) Zymkey context.
digest const uint8_t *
(input) This parameter contains the digest of the data that will be used to generate the signature.
slot int
(input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
sig uint8_t **
(output) A pointer to a pointer to an array of unsigned bytes which contains the generated signature. This pointer is created by this function and must be freed by the application when no longer needed.
sig_sz int *
(output) A pointer to an integer which contains the size of the signature.
recovery_id uint8_t *
(output) Returns recovery id value needed for ethereum key recovery.

Returns

int
0 for success, less than 0 for failure.

zkVerifyECDSASigFromDigest function

int zkVerifyECDSASigFromDigest(zkCTX ctx, const uint8_t *digest, int pubkey_slot, const uint8_t *sig, int sig_sz)
Verify a signature using one of the Zymkey’s public keys.
Verify a signature using an internal public key from the Zymkey private/public key store.

Parameters

ctx zkCTX
(input) Zymkey context.
digest const uint8_t *
(input) This parameter contains the digest of the data that will be used to generate the signature.
pubkey_slot int
(input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
sig const uint8_t *
(input) Array of bytes which contains the signature.
sig_sz int
(input) Size of signature.

Returns

int
0 for signature verification failed, 1 for signature verification passed, less than 0 for general failure.

zkVerifyECDSASigFromDigestWithForeignKeySlot function

int zkVerifyECDSASigFromDigestWithForeignKeySlot(zkCTX ctx, const uint8_t *digest, int pubkey_slot, const uint8_t *sig, int sig_sz)
Verify a signature using one of the Zymkey’s foreign public keys.
Verify a signature using a public key from the Zymkey foreign key store.

Parameters

ctx zkCTX
(input) Zymkey context.
digest const uint8_t *
(input) This parameter contains the digest of the data that will be used to generate the signature.
pubkey_slot int
(input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
sig const uint8_t *
(input) Array of bytes which contains the signature.
sig_sz int
(input) Size of signature.

Returns

int
0 for signature verification failed, 1 for signature verification passed, less than 0 for general failure.

ECDH and KDF

zkDoRawECDH function

int zkDoRawECDH(zkCTX ctx, int slot, const uint8_t *peer_pubkey, int peer_pubkey_sz, uint8_t **pre_master_secret)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Perform a raw ECDH operation.
Perform an ECDH operation with no Key Derivation Function (KDF). The raw pre-master secret is returned in the response. The peer public key is presented in the call.

Parameters

ctx zkCTX
(input) Zymkey context.
slot int
(input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey const uint8_t *
(input) The peer public key.
peer_pubkey_sz int
(input) Size of the peer public key.
pre_master_secret uint8_t **
(output) returned pointer to the pre-master secret

Returns

int
0 for success, less than 0 for general failure.

zkDoRawECDHWithIntPeerPubkey function

int zkDoRawECDHWithIntPeerPubkey(zkCTX ctx, int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign, uint8_t **pre_master_secret)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Perform a raw ECDH operation.
Perform an ECDH operation with no Key Derivation Function (KDF). The raw pre-master secret is returned in the response. The peer public key is referenced from the zymkey internal key store.

Parameters

ctx zkCTX
(input) Zymkey context.
slot int
(input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey_slot int
(input) The peer public key slot where the peer public key is to be found.
peer_pubkey_slot_is_foreign bool
(input) If true, the peer public key slot is found in the foreign public keyring.
pre_master_secret uint8_t **
(output) returned pointer to the pre-master secret

Returns

int
0 for success, less than 0 for general failure.

zkDoECDHAndKDF function

int zkDoECDHAndKDF(zkCTX ctx, ZK_ECDH_KDF_TYPE kdf_type, int slot, const uint8_t *peer_pubkey, int peer_pubkey_sz, const uint8_t *salt, int salt_sz, const uint8_t *info, int info_sz, int num_iterations, int derived_key_sz, uint8_t **derived_key)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Perform an ECDH operation plus Key Derivation Function.
Perform an ECDH operation with Key Derivation Function (KDF). The derived key is returned in the response. The peer public key is presented in the call.

Parameters

ctx zkCTX
(input) Zymkey context.
kdf_type ZK_ECDH_KDF_TYPE
(input) The key derivation function to use (ZK_ECDH_KDF_TYPE).
slot int
(input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey const uint8_t *
(input) The peer public key.
peer_pubkey_sz int
(input) Size of the peer public key.
salt const uint8_t *
(input) The salt to use for the selected KDF.
salt_sz int
(input) The salt size. Must be less than or equal to 128 bytes.
info const uint8_t *
(input) The info field to use for RFC 5869. Ignored for PBKDF2.
info_sz int
(input) The size of the info parameter. Must be less than or equal to 128 bytes.
num_iterations int
(input) Number of iterations to carry out (PBKDF only)
derived_key_sz int
(input) The desired number of bytes to return for the KDF. For RFC 5869, this value must be less than 8160 bytes (SHA256) or 16320 (SHA512).
derived_key uint8_t **
(output) returned pointer to the derived key.

Returns

int
0 for success, less than 0 for general failure.

zkDoECDHAndKDFWithIntPeerPubkey function

int zkDoECDHAndKDFWithIntPeerPubkey(zkCTX ctx, ZK_ECDH_KDF_TYPE kdf_type, int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign, const uint8_t *salt, int salt_sz, const uint8_t *info, int info_sz, int num_iterations, int derived_key_sz, uint8_t **derived_key)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Perform an ECDH operation plus Key Derivation Function.
Perform an ECDH operation with Key Derivation Function (KDF). The derived key is returned in the response. The peer public key is referenced from the zymkey internal key store.

Parameters

ctx zkCTX
(input) Zymkey context.
kdf_type ZK_ECDH_KDF_TYPE
(input) The key derivation function to use (ZK_ECDH_KDF_TYPE).
slot int
(input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey_slot int
(input) The peer public key slot where the peer public key is to be found.
peer_pubkey_slot_is_foreign bool
(input) If true, the peer public key slot is found in the foreign public keyring.
salt const uint8_t *
(input) The salt to use for the selected KDF.
salt_sz int
(input) The salt size. Must be less than or equal to 128 bytes.
info const uint8_t *
(input) The info field to use for RFC 5869. Ignored for PBKDF2.
info_sz int
(input) The size of the info parameter. Must be less than or equal to 128 bytes.
num_iterations int
(input) Number of iterations to carry out (PBKDF only)
derived_key_sz int
(input) The desired number of bytes to return for the KDF. For RFC 5869, this value must be less than 8160 bytes (SHA256) or 16320 (SHA512).
derived_key uint8_t **
(output) returned pointer to the derived key.

Returns

int
0 for success, less than 0 for general failure.

Key Management

zkSaveECDSAPubKey2File function

int zkSaveECDSAPubKey2File(zkCTX ctx, const char *filename, int slot)
[DEPRECATED] Use zkExportPubKey2File. Store the public key to a host file in PEM format.
This function is useful for generating Certificate Signing Requests (CSR).

Parameters

ctx zkCTX
(input) Zymkey context.
filename const char *
(input) Filename where PEM formatted public key is to be stored.
slot int
(input) The key slot to retrieve. Only valid for model 4i and above.

Returns

int
0 for success, less than 0 for failure.

zkExportPubKey2File function

int zkExportPubKey2File(zkCTX ctx, const char *filename, int pubkey_slot, bool slot_is_foreign)
Store the public key to a host file in PEM format.
This function is useful for generating Certificate Signing Requests (CSR).

Parameters

ctx zkCTX
(input) Zymkey context.
filename const char *
(input) Filename where PEM formatted public key is to be stored.
pubkey_slot int
(input) The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.
slot_is_foreign bool
(input) If true, designates the pubkey slot to come from the foreign keystore. (Supported Devices: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module

Returns

int
0 for success, less than 0 for failure.

zkGetECDSAPubKey function

int zkGetECDSAPubKey(zkCTX ctx, uint8_t **pk, int *pk_sz, int slot)
[DEPRECATED] Use zkExportPubKey. Gets the public key and stores in a byte array created by this function.

Parameters

ctx zkCTX
(input) Zymkey context.
pk uint8_t **
(output) Pointer to a pointer created by this function which contains the public key.
pk_sz int *
(output) Pointer to an integer which contains the size of the public key.
slot int
(input) The key slot to retrieve. Only valid for model 4i and above.

Returns

int
0 for success, less than 0 for failure.

zkExportPubKey function

int zkExportPubKey(zkCTX ctx, uint8_t **pk, int *pk_sz, int pubkey_slot, bool slot_is_foreign)
Gets the public key and stores in a byte array created by this function.

Parameters

ctx zkCTX
(input) Zymkey context.
pk uint8_t **
(output) Pointer to a pointer created by this function which contains the public key.
pk_sz int *
(output) Pointer to an integer which contains the size of the public key.
pubkey_slot int
(input) The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.
slot_is_foreign bool
(input) If true, designates the pubkey slot to come from the foreign keystore (Supported Devices: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module).
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module

Returns

int
0 for success, less than 0 for failure.

zkGetAllocSlotsList function

int zkGetAllocSlotsList(zkCTX ctx, bool is_foreign, int *max_num_keys, int **alloc_key_list, int *alloc_key_list_sz)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get the list of allocated keys.
This function returns a list of all allocated key slots.

Parameters

ctx zkCTX
(input) Zymkey context.
is_foreign bool
(input) if true, retrieve allocation list of the foreign keys
max_num_keys int *
(input) retrieves the key pool size
alloc_key_list int **
(output) a pointer to an array of integers provided by this function to the caller
alloc_key_list_sz int *
(output) a pointer to an integer which contains the size of the returned key list

Returns

int
0 if successful, less than 0 for failure.

zkStoreForeignPubKey function

int zkStoreForeignPubKey(zkCTX ctx, ZK_EC_KEY_TYPE pk_type, uint8_t *pk, int pk_sz)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Store a new foreign public key in Zymkey.
This function stores a new foreign public key in the Zymkey public key ring. This public key can be used for signature verification in use cases where it is desirable to hide the public key.

Parameters

ctx zkCTX
(input) Zymkey context.
pk_type ZK_EC_KEY_TYPE
(input) The type of the public key.
pk uint8_t *
(input) Pointer to the public key to store.
pk_sz int
(input) The public key size.

Returns

int
allocated slot number in foreign key store, less than 0 for failure.

zkDisablePubKeyExport function

int zkDisablePubKeyExport(zkCTX ctx, int pubkey_slot, bool slot_is_foreign)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Prevent a public key from being exported to the host.
This function prevents the public key at the specified slot from being exported to the host using the API zkExportPubKey.

Parameters

ctx zkCTX
(input) Zymkey context.
pubkey_slot int
(input) The key slot to disable pubkey export on.
slot_is_foreign bool
(input) The slot parameter refers to a slot in the foreign keyring.

Returns

int
0 for success, less than 0 for failure.

zkGenKeyPair function

int zkGenKeyPair(zkCTX ctx, ZK_EC_KEY_TYPE type)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate a new persistent key pair.
This function generates a new key pair of the specified type and store it persistently. This key pair cannot be used as part of the zymkey’s digital wallet operations.

Parameters

ctx zkCTX
(input) Zymkey context.
type ZK_EC_KEY_TYPE
(input) The type of key to generate (ZK_EC_KEY_TYPE).

Returns

int
allocated slot number if successful, less than 0 for failure.

zkGenEphemeralKeyPair function

int zkGenEphemeralKeyPair(zkCTX ctx, ZK_EC_KEY_TYPE type)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate an ephemeral key pair.
This function generates an ephemeral key pair of the specified type. Ephemeral key pairs are useful when performing ECDH for time-of-flight encryption. Only one ephemeral key slot is available and is not persistent between reboots.

Parameters

ctx zkCTX
(input) Zymkey context.
type ZK_EC_KEY_TYPE
(input) The type of key to generate (ZK_EC_KEY_TYPE).

Returns

int
0 if successful, less than 0 for failure.

zkRemoveKey function

int zkRemoveKey(zkCTX ctx, int slot, bool slot_is_foreign)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Remove a key pair or a foreign public key.
This function deletes a key pair or a foreign public key from persistent storage.

Parameters

ctx zkCTX
(input) Zymkey context.
slot int
(input) The slot
slot_is_foreign bool
(input) The slot parameter refers to a slot in the foreign keyring.

Returns

int
0 if successful, less than 0 for failure.

zkInvalidateEphemeralKey function

int zkInvalidateEphemeralKey(zkCTX ctx)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Invalidate the ephemeral key.
This function invalidates the ephemeral key.

Parameters

ctx zkCTX
(input) Zymkey context.

Returns

int
0 for success, less than 0 for failure.

Digital Wallet (BIP32/39/44)

zkGenWalletMasterSeedWithBIP39 function

int zkGenWalletMasterSeedWithBIP39(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, const char *passphrase, char **mnemonic)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate master seed to start a new blockchain wallet.
This function generates a new blockchain master seed for creating a new wallet.

Parameters

ctx zkCTX
(input) Zymkey context.
type ZK_EC_KEY_TYPE
(input) The type of key to generate (ZK_EC_KEY_TYPE).
variant const char *
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_name const char *
(input) An ASCII string which contains the name of the wallet.
master_generator_key const uint8_t *
(input) The master generator key used to help generate the master seed. Can be empty string.
master_generator_key_size int
(input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
passphrase const char *
(input) The passphrase to generate a different BIP39_mnemonic. Can be empty string.
mnemonic char **
(output) A pointer to the mnemonic sentence. If NULL, the master seed is generated per BIP32. Otherwise, the master seed is generated per recovery strategy and the mnemonic sentence is returned in this parameter. The string is null terminated and encoded in UTF-8 NFKD from the English dictionary.

Returns

int
allocated slot number if successful, less than 0 for failure.

zkGenWalletMasterSeedWithSLIP39 function

int zkGenWalletMasterSeedWithSLIP39(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, int group_count, int group_threshold, int group_iteration_exponent, const char *master_passphrase)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate master seed to start a new blockchain wallet.
This function opens a session to generate a new blockchain master seed with the ability to recover from SLIP39 shards.

Parameters

ctx zkCTX
(input) Zymkey context.
type ZK_EC_KEY_TYPE
(input) The type of key to generate (ZK_EC_KEY_TYPE).
variant const char *
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_name const char *
(input) An ASCII string which contains the name of the wallet.
master_generator_key const uint8_t *
(input) The master generator key used to help generate the master seed. Can be empty string.
master_generator_key_size int
(input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
group_count int
(input) The total count of groups(shards) to split into.
group_threshold int
(input) The count of groups(shards) needed to restore the master seed.
group_iteration_exponent int
(input) The iteration of exponent of SLIP39.
master_passphrase const char *
(input) The master passphrase used for slip 39 recovery process.

Returns

int
0 if successful on opening a SLIP39 session, less than 0 for failure.

zkSetSLIP39GroupInfo function

int zkSetSLIP39GroupInfo(zkCTX ctx, int group_index, int member_count, int member_threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set the active SLIP39 group and the amount of members needed.
This function configures the active group to generate the number of shards requested for the active group.

Parameters

ctx zkCTX
(input) Zymkey context.
group_index int
(input) The index of the group to generate shards from. Index starts at 0.
member_count int
(input) The total amount of member shards in this group to generate.
member_threshold int
(input) The number of member shards needed to recreate this group in recovery.

Returns

int
0 if successful on configuring the active group, less than 0 for failure.

zkAddSLIP39MemberPassword function

int zkAddSLIP39MemberPassword(zkCTX ctx, const char *passhrase, char **mnemonic_sentence)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate a new SLIP39 member shard.
This function generates a new SLIP39 member shard. The shard can optionally have a password attached to it.

Parameters

ctx zkCTX
(input) Zymkey context.
passhrase const char *
(input) Password for the shard. Can be empty string.
mnemonic_sentence char **
(output) The mnemonic sentence of the shard.

Returns

int
0 if successful on opening a SLIP39 session, less than 0 or if more data is required, or, on the final call, for failure.

zkCancelSLIP39Session function

int zkCancelSLIP39Session(zkCTX ctx)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Cancels the current active SLIP39 session.
This function cancels open active SLIP39 sessions. For both generation and restore SLIP39 sessions.

Parameters

ctx zkCTX
(input) Zymkey context.

Returns

int
0 if successful on aborting a SLIP39 session, less than 0 for failure.

zkGenOversightWallet function

int zkGenOversightWallet(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const uint8_t *pub_key, const uint8_t *chain_code, const char *node_addr, const char *wallet_name)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate master seed to start a new blockchain wallet.
This function generates a new blockchain master seed for creating a new wallet.

Parameters

ctx zkCTX
(input) Zymkey context.
type ZK_EC_KEY_TYPE
(input) The type of key to generate (ZK_EC_KEY_TYPE).
variant const char *
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
pub_key const uint8_t *
(input) The public key to create the oversight wallet from. Should come from a hardened node in a node tree.
chain_code const uint8_t *
(input) The chain code of the public key being used to create the oversight wallet.
node_addr const char *
(input) The node address index of the public key being used.
wallet_name const char *
(input) The name of the oversight wallet being created.

Returns

int
allocated slot number if successful, less than 0 for failure.

zkGenWalletChildKey function

int zkGenWalletChildKey(zkCTX ctx, int parent_key_slot, uint32_t index, bool is_hardened, bool return_chain_code, uint8_t **chain_code)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate child key from a parent key in a blockchain wallet.
This function generates a new child key descendent from a specified parent key in a wallet.

Parameters

ctx zkCTX
(input) Zymkey context.
parent_key_slot int
(input) The parent key slot to base the child key derivation on.
index uint32_t
(input) The index of the child seed. This determines the node address as well as the outcome of the key generation.
is_hardened bool
(input) If true, a hardened key is generated.
return_chain_code bool
(input) If true, returns the chain code of the public key that was just generated. Has to be a hardened node as well.
chain_code uint8_t **
(output) the chain code of the public key

Returns

int
allocated slot number if successful, less than 0 for failure.

zkRestoreWalletMasterSeedFromBIP39Mnemonic function

int zkRestoreWalletMasterSeedFromBIP39Mnemonic(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, const char *BIP39_passphrase, char *BIP39_mnemonic)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Restore a master seed from a BIP39 mnemonic and a master generator key.
This function restores a wallet master seed from a supplied BIP39 mnemonic string and a master generator key.

Parameters

ctx zkCTX
(input) Zymkey context.
type ZK_EC_KEY_TYPE
(input) The type of key to generate (ZK_KEY_TYPE).
variant const char *
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_name const char *
(input) An ASCII string which contains the name of the wallet.
master_generator_key const uint8_t *
(input) The master generator key used to help generate the master seed.
master_generator_key_size int
(input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
BIP39_passphrase const char *
(input) The passphrase used to generate the BIP39_mnemonic.
BIP39_mnemonic char *
(input) The BIP39_mnemonic string, null terminated and UTF-8 NFKD encoded from the BIP39 English dictionary.

Returns

int
allocated slot number if successful, less than 0 for failure.

zkRestoreWalletMasterSeedFromSLIP39 function

int zkRestoreWalletMasterSeedFromSLIP39(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, const char *SLIP39_passphrase)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Open a SLIP39 restore master seed session.
This function starts a restore SLIP39 session, in order to start feeding shards into.

Parameters

ctx zkCTX
(input) Zymkey context.
type ZK_EC_KEY_TYPE
(input) The type of key to generate (ZK_KEY_TYPE).
variant const char *
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_name const char *
(input) An ASCII string which contains the name of the wallet.
master_generator_key const uint8_t *
(input) The master generator key used to help generate the master seed.
master_generator_key_size int
(input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
SLIP39_passphrase const char *
(input) The master passphrase.

Returns

int
allocated slot number if successful, less than 0 for failure.

zkAddRestoreSLIP39Mnemonic function

int zkAddRestoreSLIP39Mnemonic(zkCTX ctx, const char *passphrase, const char *mnemonic_sentence)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Feed a SLIP39 shard to restore a master seed.
This function will feed a shard to the module until the conditions are met and a master seed is generated.

Parameters

ctx zkCTX
(input) Zymkey context.
passphrase const char *
(input) The passphrase that was attached to the shard.
mnemonic_sentence const char *
(input) The twenty-four word sentence mnemonic shard.

Returns

int
allocated slot number when all shards required are fed in, less than 0 for no change.

zkGetWalletNodeAddrFromKeySlot function

int zkGetWalletNodeAddrFromKeySlot(zkCTX ctx, int slot, char **node_addr, char **wallet_name, int *master_seed_slot)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Derive the node address from a key slot number.
This function derives a node address from an input key slot number.

Parameters

ctx zkCTX
(input) Zymkey context.
slot int
(input) A key slot number that is part of a digital wallet.
node_addr char **
(output) A pointer to a pointer which will contain the node address in ASCII.
wallet_name char **
(output) A pointer to a pointer which will contain the wallet name in ASCII. If NULL, this parameter will not be retrieved.
master_seed_slot int *
(output) A pointer to an integer which will contain the master seed key slot. If NULL, this parameter will not be retrieved.

Returns

int
0 if successful, less than 0 for failure.

zkGetWalletKeySlotFromNodeAddr function

int zkGetWalletKeySlotFromNodeAddr(zkCTX ctx, const char *node_addr, const char *wallet_name, int master_seed_slot, int *slot)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Derive the slot address from a node address.
This function returns the slot number associated with a given node address.

Parameters

ctx zkCTX
(input) Zymkey context.
node_addr const char *
(input) A pointer which contains the node address in ASCII.
wallet_name const char *
(input) A pointer which contains the wallet name in ASCII, used to identify the wallet identity. If desired, this parameter can be NULL and the master_seed_slot parameter can be specified instead.
master_seed_slot int
(input) The master seed slot. Can be used to specify the wallet identity instead of the wallet name.
slot int *
(output) A pointer to an integer which contains the associated key slot.

Returns

int
0 if successful, less than 0 for failure.

Perimeter Detect

zkSetPerimeterEventAction function

int zkSetPerimeterEventAction(zkCTX ctx, int channel, uint32_t action_flags)
Set perimeter breach action.

This function specifies the action to take when a perimeter breach event occurs. The possible actions are any combination of:

  • Notify host
  • Zymkey self-destruct

Parameters

ctx zkCTX
(input) Zymkey context.
channel int
(input) The channel (0 or 1) that the action flags will be applied to.
action_flags uint32_t

(input) The actions to apply to the perimeter event channel:

  • Notify (ZK_PERIMETER_EVENT_ACTION_NOTIFY)
  • Self-destruct (ZK_PERIMETER_EVENT_ACTION_SELF_DESTRUCT)

Returns

int
0 for success, less than 0 for failure.

zkSetDigitalPerimeterDetectLPPeriod function

int zkSetDigitalPerimeterDetectLPPeriod(zkCTX ctx, int lp_period)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set the low power period.
This function sets low power period on the digital perimeter detect

Parameters

ctx zkCTX
(input) Zymkey context.
lp_period int
(input) low power period in microseconds

Returns

int
0 if successful, less than 0 for failure.

zkSetDigitalPerimeterDetectLPMaxBits function

int zkSetDigitalPerimeterDetectLPMaxBits(zkCTX ctx, int max_num_bits)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set the low power max number of bits.
This function sets low power max number of bits on the digital perimeter detect

Parameters

ctx zkCTX
(input) Zymkey context.
max_num_bits int
(input) max number of bits

Returns

int
0 if successful, less than 0 for failure.

zkSetDigitalPerimeterDetectDelays function

int zkSetDigitalPerimeterDetectDelays(zkCTX ctx, int min_delay_ns, int max_delay_ns)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set the delays.
This function sets delays on the digital perimeter detect

Parameters

ctx zkCTX
(input) Zymkey context.
min_delay_ns int
(input) minimum delay in nanoseconds
max_delay_ns int
(input) maximum delay in nanoseconds

Returns

int
0 if successful, less than 0 for failure.

zkWaitForPerimeterEvent function

int zkWaitForPerimeterEvent(zkCTX ctx, uint32_t timeout_ms)
Wait for a perimeter breach event to be detected.
This function is called in order to wait for a perimeter breach event to occur. This function blocks the calling thread unless called with a timeout of zero. Note that, in order to receive perimeter events, the zymkey must have been configured to notify the host on either or both of the perimeter detect channels via a call to “zkSetPerimeterEventAction”.

Parameters

ctx zkCTX
(input) Zymkey context.
timeout_ms uint32_t
(input) The maximum amount of time in milliseconds to wait for a perimeter event to arrive.

Returns

int
0 for success, less than 0 for failure, -ETIMEDOUT when no perimeter events detected within the specified timeout

zkGetPerimeterDetectInfo function

int zkGetPerimeterDetectInfo(zkCTX ctx, uint32_t **timestamps_sec, int *num_timestamps)
Get current perimeter detect info.
This function gets the timestamp of the first perimeter detect event for the given channel

Parameters

ctx zkCTX
(input) Zymkey context.
timestamps_sec uint32_t **
(output) The timestamps for when any breach occurred. The index in this array corresponds to the channel number used by zkSetPerimeterEventAction. A 0 value means no breach has occurred on this channel. This array is allocated by this routine and so it must be freed by the caller.
num_timestamps int *
(output) The number of timestamps in the returned array

Returns

int
0 for success, less than 0 for failure.

zkClearPerimeterDetectEvents function

int zkClearPerimeterDetectEvents(zkCTX ctx)
Clear perimeter detect events.
This function clears all perimeter detect event info and rearms all perimeter detect channels

Parameters

ctx zkCTX

Returns

int
0 for success, less than 0 for failure.

LED Control

zkLEDOff function

int zkLEDOff(zkCTX ctx)
Turns the LED off.

Parameters

ctx zkCTX
(input) Zymkey context.

Returns

int
0 for success, less than 0 for failure.

zkLEDOn function

int zkLEDOn(zkCTX ctx)
Turns the LED on.

Parameters

ctx zkCTX
(input) Zymkey context.

Returns

int
0 for success, less than 0 for failure.

zkLEDFlash function

int zkLEDFlash(zkCTX ctx, uint32_t on_ms, uint32_t off_ms, uint32_t num_flashes)
Flashes the LED.

Parameters

ctx zkCTX
(input) Zymkey context.
on_ms uint32_t
(input) The amount of time, in milliseconds, that the LED will stay on during a flash cycle.
off_ms uint32_t
(input) The amount of time, in milliseconds, that the LED will stay off during a flash cycle.
num_flashes uint32_t
(input) The number of on/off flash cycles to complete. If this parameter is 0, then the LED will flash indefinitely.

Returns

int
0 for success, less than 0 for failure.

Administrative Ops

zkSetI2CAddr function

int zkSetI2CAddr(zkCTX ctx, int addr)
Sets the i2c address of the Zymkey (i2c versions only)
This method should be called if the i2c address of the Zymkey is shared with another i2c device on the same i2c bus. The default i2c address for Zymkey units is 0x30. Currently, the address may be set in the ranges of 0x30 - 0x37 and 0x60 - 0x67. After successful completion of this command, the Zymkey will reset itself.

Parameters

ctx zkCTX
(input) Zymkey context.
addr int
(input) The i2c address that the Zymkey will set itself to.

Returns

int
0 for success, less than 0 for failure.

Time

zkGetTime function

int zkGetTime(zkCTX ctx, uint32_t *epoch_time_sec, bool precise_time)
Get current GMT time.
This function is called to get the time directly from a Zymkey’s Real Time Clock (RTC)

Parameters

ctx zkCTX
(input) Zymkey context.
epoch_time_sec uint32_t *
(output) The time in seconds from the epoch (Jan. 1, 1970).
precise_time bool
(input) If true, this API returns the time after the next second falls. This means that the caller could be blocked up to one second. If false, the API returns immediately with the current time reading.

Returns

int
0 for success, less than 0 for failure.

Accelerometer

zkSetTapSensitivity function

int zkSetTapSensitivity(zkCTX ctx, int axis, float pct)
Sets the sensitivity of tap operations.
This method permits setting the sensitivity of the tap detection feature. Each axis may be individually configured or all at once.

Parameters

ctx zkCTX
(input) Zymkey context.
axis int
(input) The axis to configure. This parameter should contain one of the values in the enum typedef ACCEL_AXIS_TYPE.
pct float

(input) The sensitivity expressed as percentage.

  1. 0% = Shut down: Tap detection should not occur along the axis.
  2. 100% = Maximum sensitivity.

Returns

int
0 for success, less than 0 for failure.

zkWaitForTap function

int zkWaitForTap(zkCTX ctx, uint32_t timeout_ms)
Wait for a tap event to be detected.
This function is called in order to wait for a tap event to occur. This function blocks the calling thread unless called with a timeout of zero.

Parameters

ctx zkCTX
(input) Zymkey context.
timeout_ms uint32_t
(input) The maximum amount of time in milliseconds to wait for a tap event to arrive.

Returns

int
0 for success, less than 0 for failure, -ETIMEDOUT when no tap events detected within the specified timeout

zkGetAccelerometerData function

int zkGetAccelerometerData(zkCTX ctx, zkAccelAxisDataType *x, zkAccelAxisDataType *y, zkAccelAxisDataType *z)
Get current accelerometer data and tap info.
This function gets the most recent accelerometer data in units of g forces plus the tap direction per axis.

Parameters

ctx zkCTX
(input) Zymkey context.
x zkAccelAxisDataType *
(output) x axis accelerometer information
y zkAccelAxisDataType *
(output) y axis accelerometer information
z zkAccelAxisDataType *
(output) z axis accelerometer information

Returns

int
0 for success, less than 0 for failure.

Binding Management

zkLockBinding function

int zkLockBinding(zkCTX ctx)
Set soft binding lock.
This function locks the binding for a specific HSM. This API is only valid for HSM series products.

Parameters

ctx zkCTX

Returns

int
0 for success, less than 0 for failure.

zkGetCurrentBindingInfo function

int zkGetCurrentBindingInfo(zkCTX ctx, bool *binding_is_locked, bool *is_bound)
Get current binding info.
This function gets the current binding lock state as well as the current binding state. This API is only valid for devices in the HSM family.

Parameters

ctx zkCTX
(input) Zymkey context.
binding_is_locked bool *
(output) Binary value which expresses the current binding lock state.
is_bound bool *
(output) Binary value which expresses the current bind state.

Returns

int
0 for success, less than 0 for failure.

Module Info

zkGetModelNumberString function

int zkGetModelNumberString(zkCTX ctx, char **model_str)
Get Zymkey model number.
This function retrieves the model number of the zymkey referred to in a specified context

Parameters

ctx zkCTX
(input) Zymkey context which was created with zkOpen
model_str char **
(output) A double pointer to the model string. This function allocates this string. It is the caller’s responsibility to free it.

Returns

int
0 for success, less than 0 for failure.

zkGetFirmwareVersionString function

int zkGetFirmwareVersionString(zkCTX ctx, char **fw_ver_str)
Get Zymkey firmware version.
This function retrieves the firmware version number of the zymkey referred to in a specified context

Parameters

ctx zkCTX
(input) Zymkey context which was created with zkOpen
fw_ver_str char **
(output) A double pointer to the firmware version string. This function allocates this string. It is the caller’s responsibility to free it.

Returns

int
0 for success, less than 0 for failure.

zkGetSerialNumberString function

int zkGetSerialNumberString(zkCTX ctx, char **serial_num_str)
Get Zymkey serial number.
This function retrieves the serial number of the zymkey referred to in a specified context

Parameters

ctx zkCTX
(input) Zymkey context which was created with zkOpen
serial_num_str char **
(output) A double pointer to the serial number string. This function allocates this string. It is the caller’s responsibility to free it.

Returns

int
0 for success, less than 0 for failure.

zkGetCPUTemp function

int zkGetCPUTemp(zkCTX ctx, float *cpu_temp)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get current HSM CPU temperature.
This function gets the current HSM CPU temp.

Parameters

ctx zkCTX
(input) Zymkey context.
cpu_temp float *
(output) The temperature in celsius of the CPU.

Returns

int
0 for success, less than 0 for failure.

zkGetAUXTemp function

int zkGetAUXTemp(zkCTX ctx, int index, float *aux_temp)
Get current AUX temperature. (Only for secure compute modules)
This function gets an aux temp. THIS FUNCTION IS FOR INTERNAL ZYMBIT USE ONLY.

Parameters

ctx zkCTX
(input) Zymkey context.
index int
(input) Index for which aux temp to be polled.
aux_temp float *
(output) The temperature in celsius.

Returns

int
0 for success, less than 0 for failure.

zkGetRTCDrift function

int zkGetRTCDrift(zkCTX ctx, float *rtc_drift)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get current RTC drift.
This function is called to get the current RTC drift.

Parameters

ctx zkCTX
(input) Zymkey context.
rtc_drift float *
(output) The RTC drift.

Returns

int
0 for success, less than 0 for failure.

zkGetBatteryVoltage function

int zkGetBatteryVoltage(zkCTX ctx, float *batt_voltage)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get the battery voltage.
This function gets the current battery voltage

Parameters

ctx zkCTX
(input) Zymkey context.
batt_voltage float *
(output) The current battery voltage value

Returns

int
0 if successful, less than 0 for failure.

Battery Voltage Monitor

zkSetBatteryVoltageAction function

int zkSetBatteryVoltageAction(zkCTX ctx, int action)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set battery voltage threshold action.

This function specifies the action to take when the battery voltage falls below the threshold set by zkSetBatteryVoltageThreshold. If this function is never called, do nothing is default. There are three actions:

  • Do nothing
  • Go to sleep until battery is replaced
  • Self-destruct

Parameters

ctx zkCTX
(input) Zymkey context.
action int

(input) The action to apply, specify one of the ZK_THRESHOLD_ACTION_TYPE:

  • Do nothing (ZK_ACTION_NONE)
  • Sleep (ZK_ACTION_SLEEP)
  • Self-destruct (ZK_ACTION_SELF_DESTRUCT)

Returns

int
0 for success, less than 0 for failure.

zkSetBatteryVoltageThreshold function

int zkSetBatteryVoltageThreshold(zkCTX ctx, float threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Sets the battery voltage threshold.
This function sets the threshold at which if the battery voltage falls bellow, the action set by zkSetBatteryVoltageAction will be carried out. The recommended threshold is 2.3V. If this function isn’t called 2.3V is assumed by default. Threshold must be below 2.5V.

Parameters

ctx zkCTX
(input) Zymkey context.
threshold float
(input) The threshold in Volts.

Returns

int
0 for success, less than 0 for failure.

CPU Temperature Monitor

zkSetCPUTempAction function

int zkSetCPUTempAction(zkCTX ctx, int action)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set HSM CPU temperature threshold action.

This function specifies the action to take when the HSM CPU temperature falls below the threshold set by zkSetCPULowTempThreshold, or rises above the threshold set by zkSetCPUHighTempThreshold. There are two actions to apply:

  • Do nothing
  • Self-destruct

Parameters

ctx zkCTX
(input) Zymkey context.
action int

(input) The action to apply, used it’s named constant from ZK_THRESHOLD_ACTION_TYPE:

  • Do nothing (ZK_ACTION_NONE)
  • Self-destruct (ZK_ACTION_SELF_DESTRUCT)

Returns

int
0 for success, less than 0 for failure.

zkSetCPULowTempThreshold function

int zkSetCPULowTempThreshold(zkCTX ctx, float threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Sets the HSM CPU low temperature threshold.
This function sets the threshold at which if the on-board HSM CPU’s tempreature falls below, the action set by zkSetCPUTempAction will be carried out. WARNING: You can lock yourself out in dev mode if you set a threshold above the CPU’s ambient temperature. The recommended setting is no more than 20C. If no threshold is set, -10 degrees celsius is set as default.

Parameters

ctx zkCTX
(input) Zymkey context.
threshold float
(input) The threshold in celsius.

Returns

int
0 for success, less than 0 for failure.

zkSetCPUHighTempThreshold function

int zkSetCPUHighTempThreshold(zkCTX ctx, float threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Sets the HSM CPU high temperature threshold.
This function sets the threshold at which if the on-board HSM CPU’s tempreature rises above, the action set by zkSetCPUTempAction will be carried out. WARNING: You can lock yourself out in dev mode if you set a threshold below the CPU’s ambient temperature. The recommended setting is no less than 40C. If no threshold is set, 65 degrees celsius is set as default.

Parameters

ctx zkCTX
(input) Zymkey context.
threshold float
(input) The threshold in celsius.

Returns

int
0 for success, less than 0 for failure.

zkSetSupervisedBootPolicy function

int zkSetSupervisedBootPolicy(zkCTX ctx, int policy_id)
Supported devices: Secure Compute Module
Sets the Supervised boot policy.
This function specifies the action to take when Supervised boot event triggers based on a file change.

Parameters

ctx zkCTX
(input) Zymkey context.
policy_id int

(input) The actions to apply to the Supervised boot process:

  • 0 Do Nothing (ZK_SUPBOOT_FAIL_NO_ACTION)
  • 1 Self-Destruct (ZK_SUPBOOT_FAIL_DESTROY)
  • 2 Hold Chip in Reset (ZK_SUPBOOT_FAIL_HOLD_RESET)

Returns

int
0 for success, less than 0 for failure.

zkAddOrUpdateSupervisedBootFile function

int zkAddOrUpdateSupervisedBootFile(zkCTX ctx, const char *file_path, int slot)
Supported devices: Secure Compute Module
Update file manifest for Supervised boot to check.
This function adds or updates files to be checked by Supervised boot.

Parameters

ctx zkCTX
(input) Zymkey context.
file_path const char *
(input) The file to be signed and checked by Supervised boot.
slot int
(input) The slot to sign the file with.

Returns

int
0 for success, less than 0 for failure.

zkRemoveSupervisedBootFile function

int zkRemoveSupervisedBootFile(zkCTX ctx, const char *file_path)
Supported devices: Secure Compute Module
Remove a file from file manifest for Supervised boot to check.
This function removes a file to be checked by Supervised boot.

Parameters

ctx zkCTX
(input) Zymkey context.
file_path const char *
(input) The file to be removed from the Supervised boot manifest.

Returns

int
0 for success, less than 0 for failure.

zkGetSupervisedBootFileManifest function

int zkGetSupervisedBootFileManifest(zkCTX ctx, char **manifest)
Supported devices: Secure Compute Module
Get file manifest for Supervised boot to check.
This function gets the list of files to be checked by Supervised boot.

Parameters

ctx zkCTX
(input) Zymkey context.
manifest char **
(output) The file manifest that is checked by Supervised boot.

Returns

int
0 for success, less than 0 for failure.

Defines

ZK_PERIMETER_EVENT_ACTION_NOTIFY macro

#define ZK_PERIMETER_EVENT_ACTION_NOTIFY (1 << 0)
Perimeter breach action flag definitions.
Notify host.

ZK_PERIMETER_EVENT_ACTION_SELF_DESTRUCT macro

#define ZK_PERIMETER_EVENT_ACTION_SELF_DESTRUCT (1 << 1)
Zymkey self-destruct.

Enums

ZK_EC_KEY_TYPE enum

enum ZK_EC_KEY_TYPE
Supported key types.
ValueDescription
ZK_NISTP256
ZK_SECP256R1 = ZK_NISTP256
ZK_SECP256K1
ZK_ED25519
ZK_X25519

ZK_RECOVERY_STRATEGY enum

enum ZK_RECOVERY_STRATEGY
Supported recovery strategies.
ValueDescription
ZK_NONE
ZK_BIP39
ZK_SLIP39

ZK_ECDH_KDF_TYPE enum

enum ZK_ECDH_KDF_TYPE
Supported ECDH key derivation function types.
ValueDescription
ZK_KDF_RFC5869_SHA256
ZK_KDF_RFC5869_SHA512
ZK_KDF_PBKDF2_SHA256
ZK_KDF_PBKDF2_SHA512

ZK_ACCEL_AXIS_TYPE enum

enum ZK_ACCEL_AXIS_TYPE
Accelerometer axis enum, used to set tap sensitivity.
ValueDescription
ZK_ACCEL_AXIS_X
ZK_ACCEL_AXIS_Y
ZK_ACCEL_AXIS_Z
ZK_ACCEL_AXIS_ALL

ZK_THRESHOLD_ACTION_TYPE enum

enum ZK_THRESHOLD_ACTION_TYPE
Possible actions for threshold monitor functions.
ValueDescription
ZK_ACTION_NONE
ZK_ACTION_SELF_DESTRUCT
ZK_ACTION_SLEEP

Typedefs

zkCTX typedef

typedef void* zkCTX
The Zymkey context, created by zkOpen and passed to every other call.

ZK_EC_KEY_TYPE typedef

typedef enum ZK_EC_KEY_TYPE ZK_EC_KEY_TYPE
Supported key types.

ZK_RECOVERY_STRATEGY typedef

typedef enum ZK_RECOVERY_STRATEGY ZK_RECOVERY_STRATEGY
Supported recovery strategies.

ZK_ECDH_KDF_TYPE typedef

typedef enum ZK_ECDH_KDF_TYPE ZK_ECDH_KDF_TYPE
Supported ECDH key derivation function types.

ZK_ACCEL_AXIS_TYPE typedef

typedef enum ZK_ACCEL_AXIS_TYPE ZK_ACCEL_AXIS_TYPE
Accelerometer axis enum, used to set tap sensitivity.

ZK_THRESHOLD_ACTION_TYPE typedef

typedef enum ZK_THRESHOLD_ACTION_TYPE ZK_THRESHOLD_ACTION_TYPE
Possible actions for threshold monitor functions.

zkAccelAxisDataType typedef

typedef struct zkAccelAxisDataType zkAccelAxisDataType
zkGetAccelerometer data output.

Structs

zkAccelAxisDataType struct

zkGetAccelerometer data output.

Public Members

g variable
double zkAccelAxisDataType::g
the axis reading in units of g-force
tapDirection variable
int zkAccelAxisDataType::tapDirection
the direction of the force along the axis which caused a tap event: -1 = negative +1 = positive 0 = did not cause a tap event