C++ API Documentation

C++ interface to Zymkey Application Utilities Library.

Introduction

C++ interface to Zymkey Application Utilities Library.

This file contains the C API to the the Zymkey Application Utilities library. 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.

Typedefs

typedef std::vector<uint8_t>byteArray

Typedef for a simple unsigned bytes container.

typedef std::vector<int>intArray

Typedef for a simple integer container.

Structs

struct accelData

#include <zkAppUtilsClass.h>

Structure typedef used for retrieval of accelerometer data.

double x

double y

double z

int tapDirX

int tapDirY

int tapDirZ

Classes

class recoveryStrategyBaseType

zkAppUtilsClass.h

Class used for retrieval of recovery mnemonic for Bip32 wallet.

Subclassed by

Public Functions

recoveryStrategyBaseType ( const std::string & key_variant = "")

~recoveryStrategyBaseType ()

inline ZK_RECOVERY_STRATEGYgetRecoveryStrategy ()const

inline voidsetVariant ( const std::string & key_variant)

inline std::stringgetVariant ()const

inline virtual std::stringgetPassPhrase ()const

class recoveryStrategyBIP39

zkAppUtilsClass.h

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 ( const std::string & passphrase = "", const std::string & key_variant = "")

~recoveryStrategyBIP39 ()

inline voidsetPassPhrase ( const std::string & passphrase)

inline virtual std::stringgetPassPhrase ()const

Private Members

std::string passPhrase

class recoveryStrategySLIP39

Public Functions

recoveryStrategySLIP39 ( int group_count, int group_threshold, int iteration_exponent, const std::string & passphrase = "", const std::string & key_variant = "")

~recoveryStrategySLIP39 ()

inline voidsetPassPhrase ( const std::string & passphrase)

inline virtual std::stringgetPassPhrase ()const

inline voidsetGroupCount ( int group_count)

inline intgetGroupCount ()const

inline voidsetGroupThreshold ( int group_threshold)

inline intgetGroupThreshold ()const

inline voidsetIterationExponent ( int iteration_exponent)

inline intgetIterationExponent ()const

Private Members

int groupCount

int groupThreshold

int iterationExponent

std::string passPhrase

class zkClass

zkAppUtilsClass.h

The main class.

Zymkey Context

zkClass ()

Constructor: a Zymkey context is opened.

Exceptions
  • zkAppUtilsException upon error

virtual ~zkClass ()

Destructor: the Zymkey context is closed.

Random Number Generation

void createRandDataFile ( std::string & dst_filename, int rdata_sz)

Write random data to a file.

Parameters
  • dst_filename —

    A string containing the absolute path to the file where random data is written.

  • rdata_sz —

    The number of random bytes to generate.

Exceptions
  • zkAppUtilsException upon error

:: *getRandBytes ( int rdata_sz)

Generate a block of random data.

Parameters
  • rdata_sz —

    The number of random bytes to generate.

Exceptions
  • zkAppUtilsException upon error
Returns

A pointer to container with the random bytes.

Lock Data

void 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 —

    Absolute path to source plaintext file.

  • dst_ct_filename —

    Absolute path to destination file which will contain locked data object.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error

void lockData ( const zkAppUtils::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 —

    Unsigned byte container which holds source plaintext data.

  • dst_ct_filename —

    Absolute path to destination file which will contain locked data object.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error

:: *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 —

    Absolute path to source plaintext file.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error
Returns

Byte container with locked data.

:: *lockData ( const zkAppUtils::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 —

    Unsigned byte container which holds source plaintext data.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error
Returns

Byte container with locked data.

Unlock Data

void 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 —

    Absolute path to source file which contains locked data object.

  • dst_pt_filename —

    Absolute path to destination file which will contain unlocked plaintext data.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error

void unlockData ( const zkAppUtils::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 —

    Unsigned byte container which holds locked data object.

  • dst_pt_filename —

    Absolute path to destination file which will contain unlocked plaintext data.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error

:: *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 —

    Absolute path to source file which contains locked data object.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error
Returns

Byte container with plaintext data.

:: *unlockData ( const zkAppUtils::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_data —

    Unsigned byte container which holds locked data object.

  • use_shared_key —

    Determines whether one-way or shared key is used for locking. Default = false.

Exceptions
  • zkAppUtilsException upon error
Returns

Byte container with plaintext data.

ECDSA

:: *genECDSASigFromDigest ( zkAppUtils::byteArray & digest, int slot = 0)

Generate a signature from a data digest using the Zymkey’s private key.

Parameters
  • digest —

    Currently, this should be a SHA256 digest.

  • slot —

    The key slot to use for verification.

Exceptions
  • zkAppUtilsException upon error
Returns

Byte container with binary signature.

:: *genECDSASigFromDigest ( zkAppUtils::byteArray & digest, uint8_t & recovery_id, int slot = 0)

Generate a signature from a data digest using the Zymkey’s private key.

Parameters
  • digest —

    Currently, this should be a SHA256 digest.

  • slot —

    The key slot to use for verification.

  • recovery_id —

    [Output]Returns recovery id value needed for ethereum key recovery.

Exceptions
  • zkAppUtilsException upon error
Returns

Byte container with binary signature.

bool verifyECDSASigFromDigest ( zkAppUtils::byteArray & digest, zkAppUtils::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 —

    Currently, this should be a SHA256 digest.

  • sig —

    The signature to verify.

  • pub_key_slot —

    The key slot to use for verification.

  • pub_key_is_foreign —

    If false, the normal key store is referenced. Otherwise, the foreign public key store is referenced.

  • pub_key_is_foreign —

    If false, the normal key store is referenced. Otherwise, the foreign public key store is referenced.

Returns

true = signature verification passed, false = signature verification failed.

ECDH and KDF

:: *doRawECDH ( int slot, zkAppUtils::byteArray & peer_pubkey)

Perform a raw ECDH operation. (Supported Devices: HSM6, Secure Compute Module).

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 —

    The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.

  • peer_pubkey —

    The peer public key.

Returns

Byte container with pre master secret.

:: *doRawECDHWithIntPeerPubkey ( int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign)

Perform a raw ECDH operation. (Supported Devices: HSM6, Secure Compute Module).

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 —

    The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.

  • peer_pubkey_slot —

    The peer public key slot where the peer public key is to be found.

  • peer_pubkey_slot_is_foreign —

    If true, the peer public key slot is found in the foreign public keyring.

Returns

Byte container with pre master secret.

:: *doECDHAndKDF ( ZK_ECDH_KDF_TYPE kdf_type, int slot, zkAppUtils::byteArray & peer_pubkey, zkAppUtils::byteArray & salt, zkAppUtils::byteArray & info, int num_iterations, int derived_key_sz)

Perform an ECDH operation plus Key Derivation Function. (Supported Devices: HSM6, Secure Compute Module).

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
  • slot —

    The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.

  • peer_pubkey —

    The peer public key.

  • salt —

    The salt to use for the selected KDF.

  • info —

    The info field to use for RFC 5869. Ignored for PBKDF2.

  • num_iterations —

    Number of iterations to carry out (PBKDF only).

  • derived_key_sz —

    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

Byte container with pre master secret.

:: *doECDHAndKDFWithIntPeerPubkey ( ZK_ECDH_KDF_TYPE kdf_type, int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign, zkAppUtils::byteArray & salt, zkAppUtils::byteArray & info, int num_iterations, int derived_key_sz)

Perform an ECDH operation plus Key Derivation Function. (Supported Devices: HSM6, Secure Compute Module).

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
  • slot —

    The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.

  • peer_pubkey_slot —

    The peer public key slot where the peer public key is to be found.

  • peer_pubkey_slot_is_foreign —

    If true, the peer public key slot is found in the foreign public keyring.

  • salt —

    The salt to use for the selected KDF.

  • info —

    The info field to use for RFC 5869. Ignored for PBKDF2.

  • num_iterations —

    Number of iterations to carry out (PBKDF only).

  • derived_key_sz —

    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

Byte container with pre master secret.

Key Management

void 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 —

    Absolute location where the PEM formatted file is to be stored.

  • slot —

    Reserved for future use.

Exceptions
  • zkAppUtilsException upon error

void 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 —

    Filename where PEM formatted public key is to be stored.

  • pubkey_slot —

    The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.

  • slot_is_foreign —

    If true, designates the pubkey slot to come from the foreign keystore. (Supported Devices: HSM6, Secure Compute Module).

Exceptions
  • zkAppUtilsException upon error

:: *getECDSAPubKey ( int slot = 0)

[DEPRECATED] Use exportPubKey. Get a container of bytes which contains the ECDSA public key.

Parameters
  • slot —

    Reserved for future use.

Exceptions
  • zkAppUtilsException upon error
Returns

Byte container with binary public key.

:: *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 —

    The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.

  • slot_is_foreign —

    If true, designates the pubkey slot to come from the foreign keystore. (Supported Devices: HSM6, Secure Compute Module).

Exceptions
  • zkAppUtilsException upon error

* getAllocSlotsList ( bool foreign_key_pool)

Get the list of allocated keys. (Supported Devices: HSM6, Secure Compute Module).

This function returns a list of all allocated key slots.

Parameters
  • foreign_key_pool —

    (input) if true, retrieve allocation list of the foreign keys.

Returns

Array of the allocated keys.

int storeForeignPubKey ( ZK_EC_KEY_TYPE pk_type, zkAppUtils::byteArray & pk)

Store a new foreign public key in Zymkey. (Supported Devices: HSM6, Secure Compute Module).

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 —

    The type of the public key. {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}.

  • pk —

    Public key to store.

Exceptions
  • zkAppUtilsException upon error
Returns

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

void disablePubKeyExport ( int pubkey_slot, bool slot_is_foreign = false)

Prevent a public key from being exported to the host. (Supported Devices: HSM6, Secure Compute Module).

This function prevents the public key at the specified slot from being exported to the host using the API zkExportPubKey.

Parameters
  • pubkey_slot —

    The key slot to disable pubkey export on.

  • slot_is_foreign —

    The slot parameter refers to a slot in the foreign keyring.

Exceptions
  • zkAppUtilsException upon error

int genKeyPair ( ZK_EC_KEY_TYPE type)

Generate a new persistent key pair. (Supported Devices: HSM6, Secure Compute Module).

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 —

    The type of key to generate (ZK_EC_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}.

Exceptions
  • zkAppUtilsException upon error
Returns

Allocated slot number if successful, less than 0 for failure.

void genEphemeralKeyPair ( ZK_EC_KEY_TYPE type)

Generate an ephemeral key pair. (Supported Devices: HSM6, Secure Compute Module).

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 —

    The type of key to generate (ZK_EC_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}.

Exceptions
  • zkAppUtilsException upon error

void removeKey ( int slot, bool slot_is_foreign = false)

Remove a key pair or a foreign public key. (Supported Devices: HSM6, Secure Compute Module).

This function deletes a key pair or a foreign public key from persistent storage.

Parameters
  • slot —

    The slot.

  • slot_is_foreign —

    The slot parameter refers to a slot in the foreign keyring.

Exceptions
  • zkAppUtilsException upon error

void invalidateEphemeralKey ()

Invalidate the ephemeral key. (Supported Devices: HSM6, Secure Compute Module).

This function invalidates the ephemeral key.

Exceptions
  • zkAppUtilsException upon error

Digital Wallet (BIP32/39/44)

int genWalletMasterSeed ( ZK_EC_KEY_TYPE type, std::string & wallet_name, const zkAppUtils::recoveryStrategyBaseType & recovery_strategy zkAppUtils::recoveryStrategyBaseType = , const zkAppUtils::byteArray & master_generator_key zkAppUtils::byteArray = )

Generate a BIP32 master seed to start a new blockchain wallet. (Supported Devices: HSM6, Secure Compute Module).

This function generates a new blockchain master seed for creating a new wallet per BIP32.

Parameters
  • 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 —

    An ASCII string which contains the name of the wallet.

  • mnemonics(output) —

    Allocated mnemonics if it was asked for, based on recovery strategy used.

  • master_generator_key —

    The master generator key used to help generate the master seed (bip32). Defaults to empty string.

  • recovery_strategy —

    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.

Returns

The slot the master seed was allocated to.

int genWalletMasterSeed ( ZK_EC_KEY_TYPE type, std::string & wallet_name, const zkAppUtils::recoveryStrategyBIP39 & recovery_strategy, std::string * mnemonic_str, const zkAppUtils::byteArray & master_generator_key zkAppUtils::byteArray = )

int genWalletMasterSeed ( ZK_EC_KEY_TYPE type, std::string & wallet_name, const zkAppUtils::recoveryStrategySLIP39 & recovery_strategy, const zkAppUtils::byteArray & master_generator_key zkAppUtils::byteArray = )

int setGenSLIP39GroupInfo ( int group_index, int member_count, int member_threshold)

Set the active SLIP39 group and the amount of members needed. (Supported Devices: HSM6, Secure Compute Module).

This function configures the active group to generate the number of shards requested for the active group.

Parameters
  • group_index —

    The index of the group to generate shards from. Index starts at 0.

  • member_count —

    The total amount of member shards in this group to generate.

  • member_threshold —

    The number of member shards needed to recreate this group in recovery.

Returns

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

int addGenSLIP39Member ( std::string passphrase, std::string * mnemonic_str)

Generate a new SLIP39 member shard. (Supported Devices: HSM6, Secure Compute Module).

This function generates a new SLIP39 member shard. The shard can optionally have a password attached to it.

Parameters
  • passphrase —

    Password for the shard. Can be empty string.

  • mnemonic_str —

    (output) The mnemonic sentence of the shard.

Returns

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

int cancelSLIP39Session ()

Cancels the current active SLIP39 session (Supported Devices: HSM6, Secure Compute Module).

This function cancels open active SLIP39 sessions. For both generation and restore SLIP39 sessions.

Returns

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

int genOverSightWallet ( ZK_EC_KEY_TYPE type, zkAppUtils::byteArray & public_key, zkAppUtils::byteArray & chain_code, std::string & node_address, std::string & wallet_name, std::string & variant)

Generate a oversight wallet from the last hardened node of a wallet node address (Supported Devices: HSM6, Secure Compute Module).

This function generates a new oversight wallet and are used to generate public keys in a deterministic way.

Parameters
  • 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 —

    The public_key of the last hardened node of the address.

  • chain_code —

    The chain_code of the last hardened node of the address.

  • node_address —

    The node_address being derived from.

  • wallet_name —

    An ASCII string which contains the name of the wallet.

  • variant —

    The key type variant to generate. Currently only “cardano” for ed25519 is supported.

Returns

The slot the oversight wallet was allocated to.

int genWalletChildKey ( int parent_key_slot, uint32_t index, bool is_hardened, bool return_chain_code, zkAppUtils::byteArray * chain_code)

Generate child key from a parent key in a wallet (Supported Devices: HSM6, Secure Compute Module).

This function generates a new child key descendent from a specified parent key in a wallet.

Parameters
  • parent_key_slot —

    The parent key slot to base the child key derivation on.

  • index —

    The index of the child seed. This determines the node address as well as the outcome of the key generation.

  • is_hardened —

    If true, a hardened key is generated.

  • return_chain_code —

    If true, exports the chain code. Must be exported from a hardened node.

  • (output) —

    Allocated chain_code if it was asked for.

Exceptions
  • zkAppUtilsException upon error
Returns

Allocated slot number if successful, less than 0 for failure.

int restoreWalletMasterSeedFromMnemonic ( ZK_EC_KEY_TYPE type, std::string & wallet_name, zkAppUtils::byteArray & master_generator_key, zkAppUtils::recoveryStrategyBIP39 & recovery_strategy, std::string & mnemonic_str)

Restore a master seed from a BIP39 mnemonic and a master generator key. (Supported Devices: HSM6, Secure Compute Module).

This function restores a wallet master seed from a supplied BIP39 mnemonic string and a master generator key.

Parameters
  • type —

    The type of key to generate (ZK_KEY_TYPE). {ZK_NISTP256, ZK_SECP256R1 = ZK_NISTP256, ZK_SECP256K1}.

  • wallet_name —

    An ASCII string which contains the name of the wallet.

  • master_generator_key —

    The master generator key used to help generate the master seed.

  • recovery_strategy —

    The recovery strategy used. Contains the passphrases and key variant to recover from.

  • mnemonic_str —

    The mnemonic sentence to recover the master seed with. (Not used for SLIP39).

Exceptions
  • zkAppUtilsException upon error
Returns

Allocated slot number if successful, less than 0 for failure.

int restoreWalletMasterSeedFromMnemonic ( ZK_EC_KEY_TYPE type, std::string & wallet_name, zkAppUtils::byteArray & master_generator_key, zkAppUtils::recoveryStrategySLIP39 & recovery_strategy)

int addRestoreSLIP39Mnemonic ( std::string passphrase, std::string mnemonic_sentence)

Feed a SLIP39 shard to restore a master seed (Supported Devices: HSM6, Secure Compute Module).

This function will feed a shard to the module until the conditions are met and a master seed is generated.

Parameters
  • passphrase —

    The passphrase that was attached to the shard.

  • mnemonic_sentence —

    (output) The twenty-four word sentence mnemonic shard.

Returns

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

int getWalletNodeAddrFromKeySlot ( int slot, std::string * out_node_addr, std::string * out_wallet_name = NULL)

Derive the node address from a key slot number. (Supported Devices: HSM6, Secure Compute Module).

This function derives a node address from an input key slot number.

Parameters
  • slot —

    (input) A key slot number that is part of a digital wallet.

  • out_node_addr —

    (output) A pointer to a string which will contain the node address in ASCII.

  • wallet_name —

    (output) A pointer to a string which will contain the wallet name in ASCII. If NULL, this parameter will not be retrieved.

Exceptions
  • zkAppUtilsException upon error
Returns

The master seed key slot.

int getWalletKeySlotFromNodeAddr ( std::string & node_addr, std::string & wallet_name, int master_seed_slot)

Derive the slot address from a node address. (Supported Devices: HSM6, Secure Compute Module).

This function returns the slot number associated with a given node address.

Parameters
  • node_addr —

    (input) A pointer which contains the node address in ASCII.

  • wallet_name —

    (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 —

    (input) The master seed slot. Can be used to specify the wallet identity instead of the wallet name.

Exceptions
  • zkAppUtilsException upon error
Returns

The associated key slot.

LED Control

void ledOff ()

Turn LED off.

Exceptions
  • zkAppUtilsException upon error

void ledOn ()

Turn LED on.

Exceptions
  • zkAppUtilsException upon error

void 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 —

    Number of milliseconds that the LED will be on during a flash cycle.

  • off_ms —

    Number of milliseconds that the LED will be off during a flash cycle.

  • num_flashes —

    Number of flash cycles to execute. 0 = infinite.

Exceptions
  • zkAppUtilsException upon error

Administrative

void setI2CAddr ( int addr)

Sets the i2c address (i2c versions only). Used in case of i2c bus device address conflict.

Parameters
  • addr —

    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.

Exceptions
  • zkAppUtilsException upon error

Time

uint32_t 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 —

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

Exceptions
  • zkAppUtilsException upon error
Returns

The time in seconds from the epoch (Jan. 1, 1970).

Accelerometer

void 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 —

    Sensitivity expressed in percentage. 0% = off, 100% = maximum.

  • axis —

    X, Y, Z or all (default).

Exceptions
  • zkAppUtilsException upon error

void 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 —

    (input) The maximum amount of time in milliseconds to wait for a tap event to arrive.

Exceptions
  • zkAppUtilsTimeoutException upon timeout or zkAppUtilsException upon other errors

void getAccelerometerData ( zkAppUtils::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 —

    (output) The current accelerometer data and tap information.

Exceptions
  • zkAppUtilsException upon error

Binding Management

void lockBinding ()

Set soft binding lock.

This function locks the binding for a specific HSM. This API is only valid for HSM series products.

Exceptions
  • zkAppUtilsException upon error

void 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 —

    (output) Binary value which expresses the current binding lock state. is_bound (output) Binary value which expresses the current bind state.

Exceptions
  • zkAppUtilsException upon error

Perimeter Detect

void 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 —

    (input) The channel (0 or 1) that the action flags will be applied to.

  • action_flags —

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

    • Notify (ZK_PERIMETER_EVENT_ACTION_NOTIFY).
    • Self-destruct (ZK_PERIMETER_EVENT_ACTION_SELF_DESTRUCT).
Exceptions
  • zkAppUtilsException upon error

void setDigitalPerimeterDetectLPPeriod ( int lp_period)

Set the low power period (Supported Devices: HSM6, Secure Compute Module).

This function sets low power period on the digital perimeter detect.

Parameters
  • lp_period —

    (input) low power period in microseconds.

Exceptions
  • zkAppUtilsException upon error
Returns

void.

void setDigitalPerimeterDetectLPMaxBits ( int max_num_bits)

Set the low power max number of bits (Supported Devices: HSM6, Secure Compute Module).

This function sets low power max number of bits on the digital perimeter detect.

Parameters
  • max_num_bits —

    (input) max number of bits.

Exceptions
  • zkAppUtilsException upon error
Returns

void.

void setDigitalPerimeterDetectDelays ( int min_delay_ns, int max_delay_ns)

Set the delays (Supported Devices: HSM6, Secure Compute Module).

This function sets delays on the digital perimeter detect.

Parameters
  • min_delay_ns —

    (input) minimum delay in nanoseconds.

  • max_delay_ns —

    (input) maximum delay in nanoseconds.

Exceptions
  • zkAppUtilsException upon error
Returns

void.

void 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 —

    (input) The maximum amount of time in milliseconds to wait for a perimeter event to arrive.

Exceptions
  • zkAppUtilsException upon error

void 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
  • timestamps_sec —

    (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 —

    (output) The number of timestamps in the returned array.

Exceptions
  • zkAppUtilsException upon error

void clearPerimeterDetectEvents ()

Clear perimeter detect info.

This function clears all perimeter detect info and rearms all perimeter detect channels.

Exceptions
  • zkAppUtilsException upon error

std::string * getModelNumberString ()

Get Zymkey model number.

This function retrieves the model number of the zymkey referred to in a specified context.

Exceptions
  • zkAppUtilsException upon error
Returns

A pointer to a string containing the Zymkey model number.

std::string * getFirmwareVersionString ()

Get Zymkey firmware version.

This function retrieves the firmware version of the zymkey referred to in a specified context.

Exceptions
  • zkAppUtilsException upon error
Returns

A pointer to a string containing the Zymkey firmware version.

std::string * getSerialNumberString ()

Get Zymkey serial number.

This function retrieves the serial number of the zymkey referred to in a specified context.

Exceptions
  • zkAppUtilsException upon error
Returns

A pointer to a string containing the Zymkey serial number.

Module Info

float getCPUTemp ()

Get the CPU Temp. (Supported Devices: HSM6, Secure Compute Module).

This function gets the current HSM CPU temp.

Exceptions
  • zkAppUtilsException upon error
Returns

The CPU temp as a float.

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

Exceptions
  • zkAppUtilsException upon error
Returns

The CPU temp as a float.

float getRTCDrift ()

Get the RTC drift. (Supported Devices: HSM6, Secure Compute Module).

This function gets the current RTC drift.

Exceptions
  • zkAppUtilsException upon error
Returns

The RTC drift as a float.

float getBatteryVoltage ()

Get the battery voltage(Supported Devices: HSM6, Secure Compute Module).

This function gets the current battery voltage.

Exceptions
  • zkAppUtilsException upon error
Returns

the battery voltage as a float.

Battery Voltage Monitor

void setBatteryVoltageAction ( ZK_THRESHOLD_ACTION_TYPE action)

Set battery voltage threshold action. (Supported Devices: HSM6, Secure Compute Module).

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 —

    (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).
Exceptions
  • zkAppUtilsException upon error

void setBatteryVoltageThreshold ( float threshold)

Sets the battery voltage threshold. (Supported Devices: HSM6, Secure Compute Module).

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 —

    (input) The threshold in Volts.

Exceptions
  • zkAppUtilsException upon error

CPU Temperature Monitor

void setCPUTempAction ( ZK_THRESHOLD_ACTION_TYPE action)

Set HSM CPU temperature threshold action. (Supported Devices: HSM6, Secure Compute Module).

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 —

    (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).
Exceptions
  • zkAppUtilsException upon error

void setCPULowTempThreshold ( float threshold)

Sets the HSM CPU low temperature threshold. (Supported Devices: HSM6, Secure Compute Module).

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 —

    (input) The threshold in celsius.

Exceptions
  • zkAppUtilsException upon error

void setCPUHighTempThreshold ( float threshold)

Sets the HSM CPU high temperature threshold. (Supported Devices: HSM6, Secure Compute Module).

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 —

    (input) The threshold in celsius.

Returns

0 for success, less than 0 for failure.

void setSupervisedBootPolicy ( int policy_id)

Sets the Supervised boot policy. (Supported Devices: Secure Compute Module).

This function specifies the action to take when Supervised boot event triggers based on a file change.

Parameters
  • policy_id —

    (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

0 for success, less than 0 for failure.

void addOrUpdateSupervisedBootFile ( std::string file_path, int slot = 15)

Update file manifest for Supervised boot to check. (Supported Devices: Secure Compute Module).

This function adds or updates files to be checked by Supervised boot.

Parameters
  • file_path —

    (input) The file to be signed and checked by Supervised boot.

  • slot —

    (input) The slot to sign the file with. Defaults to 15, if no slot 15, defaults to 0.

Returns

0 for success, less than 0 for failure.

void removeSupervisedBootFile ( std::string file_path)

Remove a file from file manifest for Supervised boot to check. (Supported Devices: Secure Compute Module).

This function removes a file to be checked by Supervised boot.

Parameters
  • file_path —

    (input) The file to be removed from the Supervised boot manifest.

Returns

0 for success, less than 0 for failure.

std::string * getSupervisedBootFileManifest ()

Get file manifest for Supervised boot to check. (Supported Devices: Secure Compute Module).

This function gets the list of files to be checked by Supervised boot.

Parameters
  • manifest —

    (output) The file manifest that is checked by Supervised boot.

Returns

a string for the list of files in the manifest.

Private Members

zkCTX zkContext