C++ API Documentation

C++ interface to Zymkey Application Utilities Library.

Generated from zkapputilslib version 1.2.1-1 (commit 56b075d).

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

This class 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 libzkAppUtilsClassCPP library should additionally install the libzkapputils-c++-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 another architecture), use apt install --no-install-recommends libzkapputils-c++-dev. This will prevent apt from installing the Zymkey’s zkifc driver daemon.

Usage:

#include <zymkey/zkAppUtilsClass.h>

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

find_package(zkAppUtilsCXX REQUIRED)
target_link_libraries(${target_name} zkAppUtilsCXX::zkAppUtilsClassCPP)

Statically linking to the library is also supported within CMake by way of the zkAppUtilsCXX::zkAppUtilsClassCPP_static library target.

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

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

Typedefs

byteArray typedef

typedef std::vector<uint8_t> zkAppUtils::byteArray
Typedef for a simple unsigned bytes container.

intArray typedef

typedef std::vector<int> zkAppUtils::intArray
Typedef for a simple integer container.

Classes

zkAppUtils::commonException class

Inherits from std::exception.

Exception class derived from std::exception.

Public Functions

commonException function
zkAppUtils::commonException::commonException(std::string status)
Constructor.
Parameters
status std::string
A string which described the verbose exception
~commonException function
inline virtual zkAppUtils::commonException::~commonException()
Destructor.
what function
const char * zkAppUtils::commonException::what() const
Override of std::exception what() method.

zkAppUtils::timeoutException class

Inherits from std::exception.

Exception class derived from std::exception.

Public Functions

timeoutException function
zkAppUtils::timeoutException::timeoutException(std::string status)
Constructor.
Parameters
status std::string
A string which described the verbose exception
~timeoutException function
inline virtual zkAppUtils::timeoutException::~timeoutException()
Destructor.
what function
const char * zkAppUtils::timeoutException::what() const
Override of std::exception what() method.

zkAppUtils::recoveryStrategyBaseType class

Class used for retrieval of recovery mnemonic for Bip32 wallet.

Protected Members

recoveryStrategy variable protected
ZK_RECOVERY_STRATEGY zkAppUtils::recoveryStrategyBaseType::recoveryStrategy
The strategy: none, BIP39 or SLIP39.
variant variable protected
std::string zkAppUtils::recoveryStrategyBaseType::variant
The key variant, such as “cardano”; empty for none.

Public Functions

recoveryStrategyBaseType function
zkAppUtils::recoveryStrategyBaseType::recoveryStrategyBaseType(const std::string &key_variant="")
A strategy with no recovery mnemonic.
Parameters
key_variant const std::string & default ""
The key variant (only “cardano” is supported, for ed25519).
~recoveryStrategyBaseType function
zkAppUtils::recoveryStrategyBaseType::~recoveryStrategyBaseType()
getRecoveryStrategy function
inline ZK_RECOVERY_STRATEGY zkAppUtils::recoveryStrategyBaseType::getRecoveryStrategy() const
The recovery strategy this object represents.
setVariant function
inline void zkAppUtils::recoveryStrategyBaseType::setVariant(const std::string &key_variant)
Set the key variant.
Parameters
key_variant const std::string &
getVariant function
inline std::string zkAppUtils::recoveryStrategyBaseType::getVariant() const
The key variant.
getPassPhrase function
inline virtual std::string zkAppUtils::recoveryStrategyBaseType::getPassPhrase() const
The passphrase; empty for a strategy without one.

zkAppUtils::recoveryStrategyBIP39 class

Inherits from zkAppUtils::recoveryStrategyBaseType.

Class used for BIP39 recovery strategy. User can set b64 encoded passphrase and key variant (only “cardano” is supported for ed25519 currently) for bip32 seed generation. It can also hold the mnemonic sentence from master seed generation.

Public Functions

recoveryStrategyBIP39 function
zkAppUtils::recoveryStrategyBIP39::recoveryStrategyBIP39(const std::string &passphrase="", const std::string &key_variant="")
A BIP39 strategy.
Parameters
passphrase const std::string & default ""
Base 64 encoded passphrase; empty for none.
key_variant const std::string & default ""
The key variant (only “cardano” is supported, for ed25519).
~recoveryStrategyBIP39 function
zkAppUtils::recoveryStrategyBIP39::~recoveryStrategyBIP39()
setPassPhrase function
inline void zkAppUtils::recoveryStrategyBIP39::setPassPhrase(const std::string &passphrase)
Set the base 64 encoded passphrase.
Parameters
passphrase const std::string &
getPassPhrase function
inline std::string zkAppUtils::recoveryStrategyBIP39::getPassPhrase() const
The base 64 encoded passphrase.

zkAppUtils::recoveryStrategySLIP39 class

Inherits from zkAppUtils::recoveryStrategyBaseType.

Class used for SLIP39 recovery strategy: the group layout, iteration exponent, b64 encoded passphrase and key variant for a SLIP39 master seed session.

Public Functions

recoveryStrategySLIP39 function
zkAppUtils::recoveryStrategySLIP39::recoveryStrategySLIP39(int group_count, int group_threshold, int iteration_exponent, const std::string &passphrase="", const std::string &key_variant="")
A SLIP39 strategy.
Parameters
group_count int
Total number of groups to generate (max 14).
group_threshold int
Number of groups needed to restore the master seed.
iteration_exponent int
The higher the exponent, the more PBKDF2 hashing is done (0-5).
passphrase const std::string & default ""
Base 64 encoded passphrase; empty for none.
key_variant const std::string & default ""
The key variant (only “cardano” is supported, for ed25519).
~recoveryStrategySLIP39 function
zkAppUtils::recoveryStrategySLIP39::~recoveryStrategySLIP39()
setPassPhrase function
inline void zkAppUtils::recoveryStrategySLIP39::setPassPhrase(const std::string &passphrase)
Set the base 64 encoded passphrase.
Parameters
passphrase const std::string &
getPassPhrase function
inline std::string zkAppUtils::recoveryStrategySLIP39::getPassPhrase() const
The base 64 encoded passphrase.
setGroupCount function
inline void zkAppUtils::recoveryStrategySLIP39::setGroupCount(int group_count)
Set the total number of groups.
Parameters
group_count int
getGroupCount function
inline int zkAppUtils::recoveryStrategySLIP39::getGroupCount() const
The total number of groups.
setGroupThreshold function
inline void zkAppUtils::recoveryStrategySLIP39::setGroupThreshold(int group_threshold)
Set the number of groups needed to restore the master seed.
Parameters
group_threshold int
getGroupThreshold function
inline int zkAppUtils::recoveryStrategySLIP39::getGroupThreshold() const
The number of groups needed to restore the master seed.
setIterationExponent function
inline void zkAppUtils::recoveryStrategySLIP39::setIterationExponent(int iteration_exponent)
Set the PBKDF2 iteration exponent.
Parameters
iteration_exponent int
getIterationExponent function
inline int zkAppUtils::recoveryStrategySLIP39::getIterationExponent() const
The PBKDF2 iteration exponent.

zkAppUtils::accelData struct

Structure typedef used for retrieval of accelerometer data.

Public Members

x variable
double zkAppUtils::accelData::x
x axis reading in units of g-force
y variable
double zkAppUtils::accelData::y
y axis reading in units of g-force
z variable
double zkAppUtils::accelData::z
z axis reading in units of g-force
tapDirX variable
int zkAppUtils::accelData::tapDirX
x axis tap direction: -1 negative, +1 positive, 0 no tap
tapDirY variable
int zkAppUtils::accelData::tapDirY
y axis tap direction: -1 negative, +1 positive, 0 no tap
tapDirZ variable
int zkAppUtils::accelData::tapDirZ
z axis tap direction: -1 negative, +1 positive, 0 no tap

zkAppUtils::zkClass class

The main class.

Zymkey Context

zkClass function
zkAppUtils::zkClass::zkClass()
Constructor: a Zymkey context is opened.
Throws
zkAppUtilsException
upon error
~zkClass function
virtual zkAppUtils::zkClass::~zkClass()
Destructor: the Zymkey context is closed.

Random Number Generation

createRandDataFile function
void zkAppUtils::zkClass::createRandDataFile(std::string &dst_filename, int rdata_sz)
Write random data to a file.
Parameters
dst_filename std::string &
A string containing the absolute path to the file where random data is written
rdata_sz int
The number of random bytes to generate
Throws
zkAppUtilsException
upon error
getRandBytes function
zkAppUtils::byteArray * zkAppUtils::zkClass::getRandBytes(int rdata_sz)
Generate a block of random data.
Parameters
rdata_sz int
The number of random bytes to generate
Returns
zkAppUtils::byteArray *
A pointer to container with the random bytes
Throws
zkAppUtilsException
upon error

Lock Data

lockData function
void zkAppUtils::zkClass::lockData(const std::string &src_pt_filename, const std::string &dst_ct_filename, bool use_shared_key=false)
Locks data from a plaintext source file and stores locked data object to a destination file.
Parameters
src_pt_filename const std::string &
Absolute path to source plaintext file
dst_ct_filename const std::string &
Absolute path to destination file which will contain locked data object
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Throws
zkAppUtilsException
upon error
lockData function
void zkAppUtils::zkClass::lockData(const byteArray &src_pt_data, const std::string &dst_ct_filename, bool use_shared_key=false)
Locks data from a plaintext source byte container and stores locked data object to a destination file.
Parameters
src_pt_data const byteArray &
Unsigned byte container which holds source plaintext data
dst_ct_filename const std::string &
Absolute path to destination file which will contain locked data object
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Throws
zkAppUtilsException
upon error
lockData function
zkAppUtils::byteArray * zkAppUtils::zkClass::lockData(const std::string &src_pt_filename, bool use_shared_key=false)
Locks data from a plaintext source file and stores locked data object in a container of unsigned bytes.
Parameters
src_pt_filename const std::string &
Absolute path to source plaintext file
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Returns
zkAppUtils::byteArray *
Byte container with locked data
Throws
zkAppUtilsException
upon error
lockData function
zkAppUtils::byteArray * zkAppUtils::zkClass::lockData(const byteArray &src_pt_data, bool use_shared_key=false)
Locks data from a plaintext source byte container and stores locked data object in a container of unsigned bytes.
Parameters
src_pt_data const byteArray &
Unsigned byte container which holds source plaintext data
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Returns
zkAppUtils::byteArray *
Byte container with locked data
Throws
zkAppUtilsException
upon error

Unlock Data

unlockData function
void zkAppUtils::zkClass::unlockData(const std::string &src_ct_filename, const std::string &dst_pt_filename, bool use_shared_key=false)
Unocks a locked data object from source file and stores unlocked data object to a destination file.
Parameters
src_ct_filename const std::string &
Absolute path to source file which contains locked data object
dst_pt_filename const std::string &
Absolute path to destination file which will contain unlocked plaintext data
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Throws
zkAppUtilsException
upon error
unlockData function
void zkAppUtils::zkClass::unlockData(const byteArray &src_ct_data, const std::string &dst_pt_filename, bool use_shared_key=false)
Unlocks a locked data object contained in an unsigned byte container and stores plaintext data to a destination file.
Parameters
src_ct_data const byteArray &
Unsigned byte container which holds locked data object
dst_pt_filename const std::string &
Absolute path to destination file which will contain unlocked plaintext data
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Throws
zkAppUtilsException
upon error
unlockData function
zkAppUtils::byteArray * zkAppUtils::zkClass::unlockData(const std::string &src_ct_filename, bool use_shared_key=false)
Unlocks a locked data object from a plaintext source file and stores plaintext data in a container of unsigned bytes.
Parameters
src_ct_filename const std::string &
Absolute path to source file which contains locked data object
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Returns
zkAppUtils::byteArray *
Byte container with plaintext data
Throws
zkAppUtilsException
upon error
unlockData function
zkAppUtils::byteArray * zkAppUtils::zkClass::unlockData(const byteArray &src_ct_bytes, bool use_shared_key=false)
Unlocks a locked data object contained in an unsigned byte container and stores plaintext data in a container of unsigned bytes.
Parameters
src_ct_bytes const byteArray &
Unsigned byte container which holds locked data object
use_shared_key bool default false
Determines whether one-way or shared key is used for locking. Default = false.
Returns
zkAppUtils::byteArray *
Byte container with plaintext data
Throws
zkAppUtilsException
upon error

ECDSA

genECDSASigFromDigest function
zkAppUtils::byteArray * zkAppUtils::zkClass::genECDSASigFromDigest(byteArray &digest, int slot=0)
Generate a signature from a data digest using the Zymkey’s private key.
Parameters
digest byteArray &
Currently, this should be a SHA256 digest
slot int default 0
The key slot to use for verification.
Returns
zkAppUtils::byteArray *
Byte container with binary signature
Throws
zkAppUtilsException
upon error
genECDSASigFromDigest function
zkAppUtils::byteArray * zkAppUtils::zkClass::genECDSASigFromDigest(byteArray &digest, uint8_t &recovery_id, int slot=0)
Generate a signature from a data digest using the Zymkey’s private key.
Parameters
digest byteArray &
Currently, this should be a SHA256 digest
recovery_id uint8_t &
[Output]Returns recovery id value needed for ethereum key recovery.
slot int default 0
The key slot to use for verification.
Returns
zkAppUtils::byteArray *
Byte container with binary signature
Throws
zkAppUtilsException
upon error
verifyECDSASigFromDigest function
bool zkAppUtils::zkClass::verifyECDSASigFromDigest(byteArray &digest, byteArray &sig, int pub_key_slot=0, bool pub_key_is_foreign=false)
Verify a signature from a data digest using the Zymkey’s public key. The public key is not given as an input. Rather, the Zymkey uses its own copy of the private key. This insures that the public key that matches the private key is used.
Parameters
digest byteArray &
Currently, this should be a SHA256 digest
sig byteArray &
The signature to verify
pub_key_slot int default 0
The key slot to use for verification.
pub_key_is_foreign bool default false
If false, the normal key store is referenced. Otherwise, the foreign public key store is referenced.
Returns
bool
true = signature verification passed, false = signature verification failed

ECDH and KDF

doRawECDH function
zkAppUtils::byteArray * zkAppUtils::zkClass::doRawECDH(int slot, byteArray &peer_pubkey)
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
slot int
The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey byteArray &
The peer public key.
Returns
zkAppUtils::byteArray *
Byte container with pre master secret
doRawECDHWithIntPeerPubkey function
zkAppUtils::byteArray * zkAppUtils::zkClass::doRawECDHWithIntPeerPubkey(int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign)
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
slot int
The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey_slot int
The peer public key slot where the peer public key is to be found.
peer_pubkey_slot_is_foreign bool
If true, the peer public key slot is found in the foreign public keyring.
Returns
zkAppUtils::byteArray *
Byte container with pre master secret
doECDHAndKDF function
zkAppUtils::byteArray * zkAppUtils::zkClass::doECDHAndKDF(ZK_ECDH_KDF_TYPE kdf_type, int slot, byteArray &peer_pubkey, byteArray &salt, byteArray &info, int num_iterations, int derived_key_sz)
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
kdf_type ZK_ECDH_KDF_TYPE
The key derivation function to use (ZK_ECDH_KDF_TYPE).
slot int
The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey byteArray &
The peer public key.
salt byteArray &
The salt to use for the selected KDF.
info byteArray &
The info field to use for RFC 5869. Ignored for PBKDF2.
num_iterations int
Number of iterations to carry out (PBKDF only)
derived_key_sz int
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).
Returns
zkAppUtils::byteArray *
Byte container with pre master secret.
doECDHAndKDFWithIntPeerPubkey function
zkAppUtils::byteArray * zkAppUtils::zkClass::doECDHAndKDFWithIntPeerPubkey(ZK_ECDH_KDF_TYPE kdf_type, int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign, byteArray &salt, byteArray &info, int num_iterations, int derived_key_sz)
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
kdf_type ZK_ECDH_KDF_TYPE
The key derivation function to use (ZK_ECDH_KDF_TYPE).
slot int
The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey_slot int
The peer public key slot where the peer public key is to be found.
peer_pubkey_slot_is_foreign bool
If true, the peer public key slot is found in the foreign public keyring.
salt byteArray &
The salt to use for the selected KDF.
info byteArray &
The info field to use for RFC 5869. Ignored for PBKDF2.
num_iterations int
Number of iterations to carry out (PBKDF only)
derived_key_sz int
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).
Returns
zkAppUtils::byteArray *
Byte container with pre master secret.

Key Management

saveECDSAPubKey2File function
void zkAppUtils::zkClass::saveECDSAPubKey2File(std::string dst_filename, int slot=0)
[DEPRECATED] Use exportPubKey2File. Save the public key that matches the Zymkey’s private key into a PEM formatted file. Mainly used for Certificate Signing Request (CSR) generation.
Parameters
dst_filename std::string
Absolute location where the PEM formatted file is to be stored
slot int default 0
Reserved for future use
Throws
zkAppUtilsException
upon error
exportPubKey2File function
void zkAppUtils::zkClass::exportPubKey2File(std::string dst_filename, int pubkey_slot=0, bool slot_is_foreign=false)
Store the public key to a host file in PEM format.
This function is useful for generating Certificate Signing Requests (CSR).
Parameters
dst_filename std::string
Filename where PEM formatted public key is to be stored.
pubkey_slot int default 0
The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.
slot_is_foreign bool default false
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
Throws
zkAppUtilsException
upon error
getECDSAPubKey function
zkAppUtils::byteArray * zkAppUtils::zkClass::getECDSAPubKey(int slot=0)
[DEPRECATED] Use exportPubKey. Get a container of bytes which contains the ECDSA public key
Parameters
slot int default 0
Reserved for future use.
Returns
zkAppUtils::byteArray *
Byte container with binary public key
Throws
zkAppUtilsException
upon error
exportPubKey function
zkAppUtils::byteArray * zkAppUtils::zkClass::exportPubKey(int pubkey_slot=0, bool slot_is_foreign=0)
Gets the public key and stores in a byte array created by this function.
Parameters
pubkey_slot int default 0
The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.
slot_is_foreign bool default 0
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
Throws
zkAppUtilsException
upon error
getAllocSlotsList function
intArray * zkAppUtils::zkClass::getAllocSlotsList(bool foreign_key_pool)
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
foreign_key_pool bool
(input) if true, retrieve allocation list of the foreign keys
Returns
intArray *
Array of the allocated keys.
storeForeignPubKey function
int zkAppUtils::zkClass::storeForeignPubKey(ZK_EC_KEY_TYPE pk_type, byteArray &pk)
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
pk_type ZK_EC_KEY_TYPE
The type of the public key. {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}
pk byteArray &
Public key to store.
Returns
int
Allocated slot number in foreign key store, less than 0 for failure.
Throws
zkAppUtilsException
upon error
disablePubKeyExport function
void zkAppUtils::zkClass::disablePubKeyExport(int pubkey_slot, bool slot_is_foreign=false)
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
pubkey_slot int
The key slot to disable pubkey export on.
slot_is_foreign bool default false
The slot parameter refers to a slot in the foreign keyring.
Throws
zkAppUtilsException
upon error
genKeyPair function
int zkAppUtils::zkClass::genKeyPair(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
type ZK_EC_KEY_TYPE
The type of key to generate (ZK_EC_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}
Returns
int
Allocated slot number if successful, less than 0 for failure.
Throws
zkAppUtilsException
upon error
genEphemeralKeyPair function
void zkAppUtils::zkClass::genEphemeralKeyPair(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
type ZK_EC_KEY_TYPE
The type of key to generate (ZK_EC_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}
Throws
zkAppUtilsException
upon error
removeKey function
void zkAppUtils::zkClass::removeKey(int slot, bool slot_is_foreign=false)
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
slot int
The slot
slot_is_foreign bool default false
The slot parameter refers to a slot in the foreign keyring.
Throws
zkAppUtilsException
upon error
invalidateEphemeralKey function
void zkAppUtils::zkClass::invalidateEphemeralKey()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Invalidate the ephemeral key.
This function invalidates the ephemeral key.
Throws
zkAppUtilsException
upon error

Digital Wallet (BIP32/39/44)

genWalletMasterSeed function
int zkAppUtils::zkClass::genWalletMasterSeed(ZK_EC_KEY_TYPE type, std::string &wallet_name, const recoveryStrategyBaseType &recovery_strategy=recoveryStrategyBaseType(), const byteArray &master_generator_key=byteArray())
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate a BIP32 master seed to start a new blockchain wallet.
This function generates a new blockchain master seed for creating a new wallet per BIP32.
Parameters
type ZK_EC_KEY_TYPE
The type of key to generate (ZK_EC_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1, ZK_ED25519, ZK_X25519}
wallet_name std::string &
An ASCII string which contains the name of the wallet.
recovery_strategy const recoveryStrategyBaseType & default recoveryStrategyBaseType()
The recovery strategy object for returning BIP39 or SLIP39 (starts a SLIP39 session instead of a one shot). Also contains key variants and passphrases. Defaults to no recovery strategy.
master_generator_key const byteArray & default byteArray()
The master generator key used to help generate the master seed (bip32). Defaults to empty string
Returns
int
The slot the master seed was allocated to.
genWalletMasterSeed function
int zkAppUtils::zkClass::genWalletMasterSeed(ZK_EC_KEY_TYPE type, std::string &wallet_name, const recoveryStrategyBIP39 &recovery_strategy, std::string *mnemonic_str, const byteArray &master_generator_key=byteArray())
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate a BIP32 master seed with a BIP39 recovery mnemonic.
Parameters
type ZK_EC_KEY_TYPE
The type of key to generate (ZK_EC_KEY_TYPE).
wallet_name std::string &
An ASCII string which contains the name of the wallet.
recovery_strategy const recoveryStrategyBIP39 &
The BIP39 passphrase and key variant.
mnemonic_str std::string *
(output) The BIP39 mnemonic sentence for recovering the master seed.
master_generator_key const byteArray & default byteArray()
The master generator key used to help generate the master seed (bip32). Defaults to empty string
Returns
int
The slot the master seed was allocated to.
genWalletMasterSeed function
int zkAppUtils::zkClass::genWalletMasterSeed(ZK_EC_KEY_TYPE type, std::string &wallet_name, const recoveryStrategySLIP39 &recovery_strategy, const byteArray &master_generator_key=byteArray())
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Start a SLIP39 session to generate a BIP32 master seed.
The shards are then generated with setGenSLIP39GroupInfo and addGenSLIP39Member.
Parameters
type ZK_EC_KEY_TYPE
The type of key to generate (ZK_EC_KEY_TYPE).
wallet_name std::string &
An ASCII string which contains the name of the wallet.
recovery_strategy const recoveryStrategySLIP39 &
The SLIP39 group layout, iteration exponent, passphrase and key variant.
master_generator_key const byteArray & default byteArray()
The master generator key used to help generate the master seed (bip32). Defaults to empty string
Returns
int
0 when the SLIP39 session is open.
Throws
zkAppUtilsException
upon error
setGenSLIP39GroupInfo function
int zkAppUtils::zkClass::setGenSLIP39GroupInfo(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
group_index int
The index of the group to generate shards from. Index starts at 0.
member_count int
The total amount of member shards in this group to generate.
member_threshold int
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.
addGenSLIP39Member function
int zkAppUtils::zkClass::addGenSLIP39Member(std::string passphrase, std::string *mnemonic_str)
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
passphrase std::string
Password for the shard. Can be empty string.
mnemonic_str std::string *
(output) The mnemonic sentence of the shard.
Returns
int
0 if successful on configuring the active group, less than 0 for failure.
cancelSLIP39Session function
int zkAppUtils::zkClass::cancelSLIP39Session()
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.
Returns
int
0 if successful on configuring the active group, less than 0 for failure.
genOverSightWallet function
int zkAppUtils::zkClass::genOverSightWallet(ZK_EC_KEY_TYPE type, byteArray &public_key, byteArray &chain_code, std::string &node_address, std::string &wallet_name, std::string &variant)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate a oversight wallet from the last hardened node of a wallet node address.
This function generates a new oversight wallet and are used to generate public keys in a deterministic way.
Parameters
type ZK_EC_KEY_TYPE
The type of key to generate (ZK_EC_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1, ZK_ED25519, ZK_X25519}
public_key byteArray &
The public_key of the last hardened node of the address.
chain_code byteArray &
The chain_code of the last hardened node of the address.
node_address std::string &
The node_address being derived from.
wallet_name std::string &
An ASCII string which contains the name of the wallet.
variant std::string &
The key type variant to generate. Currently only “cardano” for ed25519 is supported.
Returns
int
The slot the oversight wallet was allocated to.
genWalletChildKey function
int zkAppUtils::zkClass::genWalletChildKey(int parent_key_slot, uint32_t index, bool is_hardened, bool return_chain_code, byteArray *chain_code)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate child key from a parent key in a wallet.
This function generates a new child key descendent from a specified parent key in a wallet.
Parameters
parent_key_slot int
The parent key slot to base the child key derivation on.
index uint32_t
The index of the child seed. This determines the node address as well as the outcome of the key generation.
is_hardened bool
If true, a hardened key is generated.
return_chain_code bool
If true, exports the chain code. Must be exported from a hardened node.
chain_code byteArray *
(output) Allocated chain_code if it was asked for.
Returns
int
Allocated slot number if successful, less than 0 for failure.
Throws
zkAppUtilsException
upon error
restoreWalletMasterSeedFromMnemonic function
int zkAppUtils::zkClass::restoreWalletMasterSeedFromMnemonic(ZK_EC_KEY_TYPE type, std::string &wallet_name, byteArray &master_generator_key, recoveryStrategyBIP39 &recovery_strategy, std::string &mnemonic_str)
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
type ZK_EC_KEY_TYPE
The type of key to generate (ZK_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}
wallet_name std::string &
An ASCII string which contains the name of the wallet.
master_generator_key byteArray &
The master generator key used to help generate the master seed.
recovery_strategy recoveryStrategyBIP39 &
The recovery strategy used. Contains the passphrases and key variant to recover from.
mnemonic_str std::string &
The mnemonic sentence to recover the master seed with. (Not used for SLIP39)
Returns
int
Allocated slot number if successful, less than 0 for failure.
Throws
zkAppUtilsException
upon error
restoreWalletMasterSeedFromMnemonic function
int zkAppUtils::zkClass::restoreWalletMasterSeedFromMnemonic(ZK_EC_KEY_TYPE type, std::string &wallet_name, byteArray &master_generator_key, recoveryStrategySLIP39 &recovery_strategy)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Start a SLIP39 session to restore a master seed.
The shards are then fed in with addRestoreSLIP39Mnemonic.
Parameters
type ZK_EC_KEY_TYPE
The type of key to restore (ZK_EC_KEY_TYPE).
wallet_name std::string &
An ASCII string which contains the name of the wallet.
master_generator_key byteArray &
The master generator key used to help generate the master seed.
recovery_strategy recoveryStrategySLIP39 &
The SLIP39 passphrase and key variant to recover from.
Returns
int
The result of opening the session; less than 0 for failure.
addRestoreSLIP39Mnemonic function
int zkAppUtils::zkClass::addRestoreSLIP39Mnemonic(std::string passphrase, std::string 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
passphrase std::string
The passphrase that was attached to the shard.
mnemonic_sentence std::string
(output) 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.
getWalletNodeAddrFromKeySlot function
int zkAppUtils::zkClass::getWalletNodeAddrFromKeySlot(int slot, std::string *out_node_addr, std::string *out_wallet_name=NULL)
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
slot int
(input) A key slot number that is part of a digital wallet.
out_node_addr std::string *
(output) A pointer to a string which will contain the node address in ASCII.
out_wallet_name std::string * default NULL
(output) A pointer to a string which will contain the wallet name in ASCII. If NULL, this parameter will not be retrieved.
Returns
int
The master seed key slot.
Throws
zkAppUtilsException
upon error
getWalletKeySlotFromNodeAddr function
int zkAppUtils::zkClass::getWalletKeySlotFromNodeAddr(std::string &node_addr, std::string &wallet_name, int master_seed_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
node_addr std::string &
(input) A pointer which contains the node address in ASCII.
wallet_name std::string &
(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.
Returns
int
The associated key slot.
Throws
zkAppUtilsException
upon error

LED Control

ledOff function
void zkAppUtils::zkClass::ledOff()
Turn LED off.
Throws
zkAppUtilsException
upon error
ledOn function
void zkAppUtils::zkClass::ledOn()
Turn LED on.
Throws
zkAppUtilsException
upon error
ledFlash function
void zkAppUtils::zkClass::ledFlash(uint32_t on_ms, uint32_t off_ms=0, uint32_t num_flashes=0)
Flash LED a certain number of times.
Parameters
on_ms uint32_t
Number of milliseconds that the LED will be on during a flash cycle
off_ms uint32_t default 0
Number of milliseconds that the LED will be off during a flash cycle
num_flashes uint32_t default 0
Number of flash cycles to execute. 0 = infinite.
Throws
zkAppUtilsException
upon error

Administrative

setI2CAddr function
void zkAppUtils::zkClass::setI2CAddr(int addr)
Sets the i2c address (i2c versions only). Used in case of i2c bus device address conflict.
Parameters
addr int
The i2c address to set. Upon successful change, the Zymkey will reset itself. However, if the address is the same as the current setting, the Zymkey will not reset. Valid address ranges are 0x30 - 0x37 and 0x60 - 0x67.
Throws
zkAppUtilsException
upon error

Time

getTime function
uint32_t zkAppUtils::zkClass::getTime(bool precise_time=false)
Get current GMT time.
This method is called to get the time directly from a Zymkey’s Real Time Clock (RTC)
Parameters
precise_time bool default false
(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
uint32_t
The time in seconds from the epoch (Jan. 1, 1970).
Throws
zkAppUtilsException
upon error

Accelerometer

setTapSensitivity function
void zkAppUtils::zkClass::setTapSensitivity(float pct, ZK_ACCEL_AXIS_TYPE axis=ZK_ACCEL_AXIS_ALL)
Sets the sensitivity of the tap detection as a percentage for an individual axis or all axes.
Parameters
pct float
Sensitivity expressed in percentage. 0% = off, 100% = maximum.
axis ZK_ACCEL_AXIS_TYPE default ZK_ACCEL_AXIS_ALL
X, Y, Z or all (default).
Throws
zkAppUtilsException
upon error
waitForTap function
void zkAppUtils::zkClass::waitForTap(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
timeout_ms uint32_t
(input) The maximum amount of time in milliseconds to wait for a tap event to arrive.
Throws
zkAppUtilsTimeoutException
upon timeout or zkAppUtilsException upon other errors
getAccelerometerData function
void zkAppUtils::zkClass::getAccelerometerData(accelData &accel_data)
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. Array index 0 = x 1 = y 2 = z
Parameters
accel_data accelData &
(output) The current accelerometer data and tap information
Throws
zkAppUtilsException
upon error

Binding Management

lockBinding function
void zkAppUtils::zkClass::lockBinding()
Set soft binding lock.
This function locks the binding for a specific HSM. This API is only valid for HSM series products.
Throws
zkAppUtilsException
upon error
getCurrentBindingInfo function
void zkAppUtils::zkClass::getCurrentBindingInfo(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
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.
Throws
zkAppUtilsException
upon error

Perimeter Detect

setPerimeterEventAction function
void zkAppUtils::zkClass::setPerimeterEventAction(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
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)
Throws
zkAppUtilsException
upon error
setDigitalPerimeterDetectLPPeriod function
void zkAppUtils::zkClass::setDigitalPerimeterDetectLPPeriod(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
lp_period int
(input) low power period in microseconds
Returns
void
void.
Throws
zkAppUtilsException
upon error
setDigitalPerimeterDetectLPMaxBits function
void zkAppUtils::zkClass::setDigitalPerimeterDetectLPMaxBits(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
max_num_bits int
(input) max number of bits
Returns
void
void.
Throws
zkAppUtilsException
upon error
setDigitalPerimeterDetectDelays function
void zkAppUtils::zkClass::setDigitalPerimeterDetectDelays(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
min_delay_ns int
(input) minimum delay in nanoseconds
max_delay_ns int
(input) maximum delay in nanoseconds
Returns
void
void.
Throws
zkAppUtilsException
upon error
waitForPerimeterEvent function
void zkAppUtils::zkClass::waitForPerimeterEvent(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
timeout_ms uint32_t
(input) The maximum amount of time in milliseconds to wait for a perimeter event to arrive.
Throws
zkAppUtilsException
upon error
getPerimeterDetectInfo function
void zkAppUtils::zkClass::getPerimeterDetectInfo(uint32_t **timestamp_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
timestamp_sec uint32_t **
(output) The timestamps for when any events 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
Throws
zkAppUtilsException
upon error
clearPerimeterDetectEvents function
void zkAppUtils::zkClass::clearPerimeterDetectEvents()
Clear perimeter detect info.
This function clears all perimeter detect info and rearms all perimeter detect channels
Throws
zkAppUtilsException
upon error
getModelNumberString function
std::string * zkAppUtils::zkClass::getModelNumberString()
Get Zymkey model number.
This function retrieves the model number of the zymkey referred to in a specified context
Returns
std::string *
A pointer to a string containing the Zymkey model number.
Throws
zkAppUtilsException
upon error
getFirmwareVersionString function
std::string * zkAppUtils::zkClass::getFirmwareVersionString()
Get Zymkey firmware version.
This function retrieves the firmware version of the zymkey referred to in a specified context.
Returns
std::string *
A pointer to a string containing the Zymkey firmware version.
Throws
zkAppUtilsException
upon error
getSerialNumberString function
std::string * zkAppUtils::zkClass::getSerialNumberString()
Get Zymkey serial number.
This function retrieves the serial number of the zymkey referred to in a specified context.
Returns
std::string *
A pointer to a string containing the Zymkey serial number.
Throws
zkAppUtilsException
upon error

Module Info

getCPUTemp function
float zkAppUtils::zkClass::getCPUTemp()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get the CPU Temp.
This function gets the current HSM CPU temp.
Returns
float
The CPU temp as a float.
Throws
zkAppUtilsException
upon error
getAUXTemp function
float zkAppUtils::zkClass::getAUXTemp(int index=0)
Get the AUX Temp. (Secure Compute Modules Only)
This function gets the current temp of an aux processor. (defaults to 0). THIS FUNCTION IS FOR INTERNAL ZYMBIT USE ONLY.
Parameters
index int default 0
Returns
float
The CPU temp as a float.
Throws
zkAppUtilsException
upon error
getRTCDrift function
float zkAppUtils::zkClass::getRTCDrift()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get the RTC drift.
This function gets the current RTC drift.
Returns
float
The RTC drift as a float.
Throws
zkAppUtilsException
upon error
getBatteryVoltage function
float zkAppUtils::zkClass::getBatteryVoltage()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get the battery voltage.
This function gets the current battery voltage
Returns
float
the battery voltage as a float.
Throws
zkAppUtilsException
upon error

Battery Voltage Monitor

setBatteryVoltageAction function
void zkAppUtils::zkClass::setBatteryVoltageAction(ZK_THRESHOLD_ACTION_TYPE 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
action ZK_THRESHOLD_ACTION_TYPE

(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)
Throws
zkAppUtilsException
upon error
setBatteryVoltageThreshold function
void zkAppUtils::zkClass::setBatteryVoltageThreshold(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 is assumed by default. Threshold must be below 2.5V.
Parameters
threshold float
(input) The threshold in Volts.
Throws
zkAppUtilsException
upon error

CPU Temperature Monitor

setCPUTempAction function
void zkAppUtils::zkClass::setCPUTempAction(ZK_THRESHOLD_ACTION_TYPE 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
action ZK_THRESHOLD_ACTION_TYPE

(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)
Throws
zkAppUtilsException
upon error
setCPULowTempThreshold function
void zkAppUtils::zkClass::setCPULowTempThreshold(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
threshold float
(input) The threshold in celsius.
Throws
zkAppUtilsException
upon error
setCPUHighTempThreshold function
void zkAppUtils::zkClass::setCPUHighTempThreshold(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
threshold float
(input) The threshold in celsius.
Returns
void
0 for success, less than 0 for failure.
setSupervisedBootPolicy function
void zkAppUtils::zkClass::setSupervisedBootPolicy(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
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
void
0 for success, less than 0 for failure.
addOrUpdateSupervisedBootFile function
void zkAppUtils::zkClass::addOrUpdateSupervisedBootFile(std::string file_path, int slot=15)
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
file_path std::string
(input) The file to be signed and checked by Supervised boot.
slot int default 15
(input) The slot to sign the file with. Defaults to 15, if no slot 15, defaults to 0.
Returns
void
0 for success, less than 0 for failure.
removeSupervisedBootFile function
void zkAppUtils::zkClass::removeSupervisedBootFile(std::string 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
file_path std::string
(input) The file to be removed from the Supervised boot manifest.
Returns
void
0 for success, less than 0 for failure.
getSupervisedBootFileManifest function
std::string * zkAppUtils::zkClass::getSupervisedBootFileManifest()
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.
Returns
std::string *
The file manifest that is checked by Supervised boot.

Public Functions

enableSelfRestart function
void zkAppUtils::zkClass::enableSelfRestart(bool enabled, int waitSec, int maxNumRestart)
Enables automatic restart of zkifc/zymbit device (in case of fatal error).
Parameters
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.
Throws
commonException
upon error.