C API Documentation
Generated from zkapputilslib version 1.2.2-1 (commit a547582).
This file contains the C API to the the Zymkey Application Utilities library, libzk_app_utils. Systems intending to run such applications require that the libzkapputils package be installed.
This API facilitates writing user space applications which use Zymkey to perform cryptographic operations, such as:
- Signing of payloads using ECDSA
- Verification of payloads that were signed using Zymkey
- Exporting the public key that matches Zymkey’s private key
- “Locking” and “unlocking” data objects
- Generating random data Additionally, there are functions for changing the i2c address (i2c units only), setting tap sensitivity and controlling the LED.
Developers wishing to build applications which utilize the libzk_app_utils library should additionally install the libzkapputils-dev package, which contains the necessary development files for the Zymkey’s C library. To install this package on a system that does not need to run the applications (e.g. a Docker container or when cross compiling on a foreign architecture), use apt install --no-install-recommends libzkapputils-dev. This will prevent apt from installing the Zymkey’s zkifc driver daemon.
Usage:
#include <zymkey/zk_app_utils.h>
To add zkAppUtils as a dependency of a CMake-based project, add the following lines to your project’s CMakeLists.txt file:
find_package(zkAppUtils REQUIRED)
target_link_libraries(${target_name} zkAppUtils::zk_app_utils)
Projects may alternatively import the library dependency via pkg-config:
CFLAGS="$(pkg-config --cflags zkapputils)"
LDFLAGS="$(pkg-config --libs zkapputils)"
Zymkey Context
zkOpen
function
int zkOpen(zkCTX *ctx)Parameters
ctxzkCTX *- (output) returns a pointer to a Zymkey context.
Returns
- int
- 0 for success, less than 0 for failure.
zkClose
function
int zkClose(zkCTX ctx)Parameters
ctxzkCTX- (input) The Zymkey context to close
Returns
- int
- 0 for success, less than 0 for failure.
zkEnableSelfRestart
function
int zkEnableSelfRestart(zkCTX ctx, bool enabled, int waitSec, int maxNumRestart)Parameters
ctxzkCTX- (input) Zymkey context.
enabledbool- (input) Enable/disable.
waitSecint- (input) Time in seconds to wait before attempting restart.
maxNumRestartint- (input) Maximum number of restarts to attempt.
Returns
- int
- 0 for success, less than 0 for failure.
Random Number Generation
zkCreateRandDataFile
function
int zkCreateRandDataFile(zkCTX ctx, const char *dst_filename, int rdata_sz)Parameters
ctxzkCTX- (input) Zymkey context.
dst_filenameconst char *- (input) Absolute path name for the destination file.
rdata_szint- (input) The number of random bytes to generate.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetRandBytes
function
int zkGetRandBytes(zkCTX ctx, uint8_t **rdata, int rdata_sz)Parameters
ctxzkCTX- (input) Zymkey context.
rdatauint8_t **- (input) Pointer to a pointer of bytes.
rdata_szint- (input) The number of random bytes to generate.
Returns
- int
- 0 for success, less than 0 for failure.
Lock Data
zkLockDataF2F
function
int zkLockDataF2F(zkCTX ctx, const char *src_pt_filename, const char *dst_ct_filename, bool use_shared_key)The zymkey has two keys that can be used for locking/unlocking operations, designated as ‘shared’ and ‘one-way’.
- The one-way key is meant to lock up data only on the local host computer. Data encrypted using this key cannot be exported and deciphered anywhere else.
- The shared key is meant for publishing data to other sources that have the capability to generate the shared key, such as the Zymbit cloud server.
Parameters
ctxzkCTX- (input) Zymkey context.
src_pt_filenameconst char *- (input) The absolute path to the file where the source (plaintext) data is located.
dst_ct_filenameconst char *- (input) The absolute path to the file where the destination (ciphertext) data should be deposited.
use_shared_keybool- (input) This parameter specifies which key will be used to used to lock the data up. A value of ‘false’ specifies that the Zymkey will use the one-way key whereas ’true’ specifies that the shared key will be used. Specify ’true’ for publishing data to another that has the shared key (e.g. Zymbit cloud) and ‘False’ when the data is meant to reside exclusively withing the host computer.
Returns
- int
- 0 for success, less than 0 for failure.
zkLockDataB2F
function
int zkLockDataB2F(zkCTX ctx, const uint8_t *src_pt, int src_pt_sz, const char *dst_ct_filename, bool use_shared_key)Parameters
ctxzkCTX- (input) Zymkey context.
src_ptconst uint8_t *- (input) Binary plaintext source byte array.
src_pt_szint- (input) Size of plaintext source data.
dst_ct_filenameconst char *- (input) The absolute path to the file where the destination (ciphertext) data should be deposited.
use_shared_keybool- (input) Specifies if shared key is to be used. See zkLockDataF2F.
Returns
- int
- 0 for success, less than 0 for failure.
zkLockDataF2B
function
int zkLockDataF2B(zkCTX ctx, const char *src_pt_filename, uint8_t **dst_ct, int *dst_ct_sz, bool use_shared_key)Parameters
ctxzkCTX- (input) Zymkey context.
src_pt_filenameconst char *- (input) The absolute path to the file where the source (plaintext) data is located.
dst_ctuint8_t **- (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_ct_szint *- (output) A pointer to an integer which contains the size of the destination array.
use_shared_keybool- (input) Specifies if shared key is to be used. See zkLockDataF2F.
Returns
- int
- 0 for success, less than 0 for failure.
zkLockDataB2B
function
int zkLockDataB2B(zkCTX ctx, const uint8_t *src_pt, int src_pt_sz, uint8_t **dst_ct, int *dst_ct_sz, bool use_shared_key)Parameters
ctxzkCTX- (input) Zymkey context.
src_ptconst uint8_t *- (input) Binary plaintext source byte array.
src_pt_szint- (input) Size of plaintext source data.
dst_ctuint8_t **- (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_ct_szint *- (output) A pointer to an integer which contains the size of the destination array.
use_shared_keybool- (input) Specifies if shared key is to be used. See zkLockDataF2F.
Returns
- int
- 0 for success, less than 0 for failure.
Unlock Data
zkUnlockDataF2F
function
int zkUnlockDataF2F(zkCTX ctx, const char *src_ct_filename, const char *dst_pt_filename, bool use_shared_key)Parameters
ctxzkCTX- (input) Zymkey context.
src_ct_filenameconst char *- (input) The absolute path to the file where the source (ciphertext) data is located.
dst_pt_filenameconst char *- (input) The absolute path to the file where the destination (plaintext) data should be deposited.
use_shared_keybool- (input) This parameter specifies which key will be used to used to lock the data up. A value of ‘false’ specifies that the Zymkey will use the one-way key whereas ’true’ specifies that the shared key will be used. Specify ’true’ for publishing data to another that has the shared key (e.g. Zymbit cloud) and ‘False’ when the data is meant to reside exclusively withing the host computer.
Returns
- int
- 0 for success, less than 0 for failure.
zkUnlockDataB2F
function
int zkUnlockDataB2F(zkCTX ctx, const uint8_t *src_ct, int src_ct_sz, const char *dst_pt_filename, bool use_shared_key)Parameters
ctxzkCTX- (input) Zymkey context.
src_ctconst uint8_t *- (input) Binary ciphertext source byte array.
src_ct_szint- (input) Size of ciphertext source data.
dst_pt_filenameconst char *- (input) The absolute path to the file where the destination (plaintext) data should be deposited.
use_shared_keybool- (input) Specifies if shared key is to be used. See zkLockDataF2F.
Returns
- int
- 0 for success, less than 0 for failure.
zkUnlockDataF2B
function
int zkUnlockDataF2B(zkCTX ctx, const char *src_ct_filename, uint8_t **dst_pt, int *dst_pt_sz, bool use_shared_key)Parameters
ctxzkCTX- (input) Zymkey context.
src_ct_filenameconst char *- (input) The absolute path to the file where the source (ciphertext) data is located.
dst_ptuint8_t **- (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_pt_szint *- (output) A pointer to an integer which contains the size of the destination array.
use_shared_keybool- (input) Specifies if shared key is to be used. See zkLockDataF2F.
Returns
- int
- 0 for success, less than 0 for failure.
zkUnlockDataB2B
function
int zkUnlockDataB2B(zkCTX ctx, const uint8_t *src_ct, int src_ct_sz, uint8_t **dst_pt, int *dst_pt_sz, bool use_shared_key)Parameters
ctxzkCTX- (input) Zymkey context.
src_ctconst uint8_t *- (input) Binary ciphertext source byte array.
src_ct_szint- (input) Size of ciphertext source data.
dst_ptuint8_t **- (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.
dst_pt_szint *- (output) A pointer to an integer which contains the size of the destination array.
use_shared_keybool- (input) Specifies if shared key is to be used. See zkLockDataF2F.
Returns
- int
- 0 for success, less than 0 for failure.
ECDSA
zkGenECDSASigFromDigest
function
int zkGenECDSASigFromDigest(zkCTX ctx, const uint8_t *digest, int slot, uint8_t **sig, int *sig_sz)Parameters
ctxzkCTX- (input) Zymkey context.
digestconst uint8_t *- (input) This parameter contains the digest of the data that will be used to generate the signature.
slotint- (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
siguint8_t **- (output) A pointer to a pointer to an array of unsigned bytes which contains the generated signature. This pointer is created by this function and must be freed by the application when no longer needed.
sig_szint *- (output) A pointer to an integer which contains the size of the signature.
Returns
- int
- 0 for success, less than 0 for failure.
zkGenECDSASigFromDigestWithRecID
function
int zkGenECDSASigFromDigestWithRecID(zkCTX ctx, const uint8_t *digest, int slot, uint8_t **sig, int *sig_sz, uint8_t *recovery_id)Parameters
ctxzkCTX- (input) Zymkey context.
digestconst uint8_t *- (input) This parameter contains the digest of the data that will be used to generate the signature.
slotint- (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
siguint8_t **- (output) A pointer to a pointer to an array of unsigned bytes which contains the generated signature. This pointer is created by this function and must be freed by the application when no longer needed.
sig_szint *- (output) A pointer to an integer which contains the size of the signature.
recovery_iduint8_t *- (output) Returns recovery id value needed for ethereum key recovery.
Returns
- int
- 0 for success, less than 0 for failure.
zkVerifyECDSASigFromDigest
function
int zkVerifyECDSASigFromDigest(zkCTX ctx, const uint8_t *digest, int pubkey_slot, const uint8_t *sig, int sig_sz)Parameters
ctxzkCTX- (input) Zymkey context.
digestconst uint8_t *- (input) This parameter contains the digest of the data that will be used to generate the signature.
pubkey_slotint- (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
sigconst uint8_t *- (input) Array of bytes which contains the signature.
sig_szint- (input) Size of signature.
Returns
- int
- 0 for signature verification failed, 1 for signature verification passed, less than 0 for general failure.
zkVerifyECDSASigFromDigestWithForeignKeySlot
function
int zkVerifyECDSASigFromDigestWithForeignKeySlot(zkCTX ctx, const uint8_t *digest, int pubkey_slot, const uint8_t *sig, int sig_sz)Parameters
ctxzkCTX- (input) Zymkey context.
digestconst uint8_t *- (input) This parameter contains the digest of the data that will be used to generate the signature.
pubkey_slotint- (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.
sigconst uint8_t *- (input) Array of bytes which contains the signature.
sig_szint- (input) Size of signature.
Returns
- int
- 0 for signature verification failed, 1 for signature verification passed, less than 0 for general failure.
ECDH and KDF
zkDoRawECDH
function
int zkDoRawECDH(zkCTX ctx, int slot, const uint8_t *peer_pubkey, int peer_pubkey_sz, uint8_t **pre_master_secret)Parameters
ctxzkCTX- (input) Zymkey context.
slotint- (input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkeyconst uint8_t *- (input) The peer public key.
peer_pubkey_szint- (input) Size of the peer public key.
pre_master_secretuint8_t **- (output) returned pointer to the pre-master secret
Returns
- int
- 0 for success, less than 0 for general failure.
zkDoRawECDHWithIntPeerPubkey
function
int zkDoRawECDHWithIntPeerPubkey(zkCTX ctx, int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign, uint8_t **pre_master_secret)Parameters
ctxzkCTX- (input) Zymkey context.
slotint- (input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey_slotint- (input) The peer public key slot where the peer public key is to be found.
peer_pubkey_slot_is_foreignbool- (input) If true, the peer public key slot is found in the foreign public keyring.
pre_master_secretuint8_t **- (output) returned pointer to the pre-master secret
Returns
- int
- 0 for success, less than 0 for general failure.
zkDoECDHAndKDF
function
int zkDoECDHAndKDF(zkCTX ctx, ZK_ECDH_KDF_TYPE kdf_type, int slot, const uint8_t *peer_pubkey, int peer_pubkey_sz, const uint8_t *salt, int salt_sz, const uint8_t *info, int info_sz, int num_iterations, int derived_key_sz, uint8_t **derived_key)Parameters
ctxzkCTX- (input) Zymkey context.
kdf_typeZK_ECDH_KDF_TYPE- (input) The key derivation function to use (ZK_ECDH_KDF_TYPE).
slotint- (input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkeyconst uint8_t *- (input) The peer public key.
peer_pubkey_szint- (input) Size of the peer public key.
saltconst uint8_t *- (input) The salt to use for the selected KDF.
salt_szint- (input) The salt size. Must be less than or equal to 128 bytes.
infoconst uint8_t *- (input) The info field to use for RFC 5869. Ignored for PBKDF2.
info_szint- (input) The size of the info parameter. Must be less than or equal to 128 bytes.
num_iterationsint- (input) Number of iterations to carry out (PBKDF only)
derived_key_szint- (input) The desired number of bytes to return for the KDF. For RFC 5869, this value must be less than 8160 bytes (SHA256) or 16320 (SHA512).
derived_keyuint8_t **- (output) returned pointer to the derived key.
Returns
- int
- 0 for success, less than 0 for general failure.
zkDoECDHAndKDFWithIntPeerPubkey
function
int zkDoECDHAndKDFWithIntPeerPubkey(zkCTX ctx, ZK_ECDH_KDF_TYPE kdf_type, int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign, const uint8_t *salt, int salt_sz, const uint8_t *info, int info_sz, int num_iterations, int derived_key_sz, uint8_t **derived_key)Parameters
ctxzkCTX- (input) Zymkey context.
kdf_typeZK_ECDH_KDF_TYPE- (input) The key derivation function to use (ZK_ECDH_KDF_TYPE).
slotint- (input) The key slot to use for the local key. If this parameter is -1, the ephemeral key is used.
peer_pubkey_slotint- (input) The peer public key slot where the peer public key is to be found.
peer_pubkey_slot_is_foreignbool- (input) If true, the peer public key slot is found in the foreign public keyring.
saltconst uint8_t *- (input) The salt to use for the selected KDF.
salt_szint- (input) The salt size. Must be less than or equal to 128 bytes.
infoconst uint8_t *- (input) The info field to use for RFC 5869. Ignored for PBKDF2.
info_szint- (input) The size of the info parameter. Must be less than or equal to 128 bytes.
num_iterationsint- (input) Number of iterations to carry out (PBKDF only)
derived_key_szint- (input) The desired number of bytes to return for the KDF. For RFC 5869, this value must be less than 8160 bytes (SHA256) or 16320 (SHA512).
derived_keyuint8_t **- (output) returned pointer to the derived key.
Returns
- int
- 0 for success, less than 0 for general failure.
Key Management
zkSaveECDSAPubKey2File
function
int zkSaveECDSAPubKey2File(zkCTX ctx, const char *filename, int slot)Parameters
ctxzkCTX- (input) Zymkey context.
filenameconst char *- (input) Filename where PEM formatted public key is to be stored.
slotint- (input) The key slot to retrieve. Only valid for model 4i and above.
Returns
- int
- 0 for success, less than 0 for failure.
zkExportPubKey2File
function
int zkExportPubKey2File(zkCTX ctx, const char *filename, int pubkey_slot, bool slot_is_foreign)Parameters
ctxzkCTX- (input) Zymkey context.
filenameconst char *- (input) Filename where PEM formatted public key is to be stored.
pubkey_slotint- (input) The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.
slot_is_foreignbool- (input) If true, designates the pubkey slot to come from the foreign keystore. (Supported Devices: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module)
Returns
- int
- 0 for success, less than 0 for failure.
zkGetECDSAPubKey
function
int zkGetECDSAPubKey(zkCTX ctx, uint8_t **pk, int *pk_sz, int slot)Parameters
ctxzkCTX- (input) Zymkey context.
pkuint8_t **- (output) Pointer to a pointer created by this function which contains the public key.
pk_szint *- (output) Pointer to an integer which contains the size of the public key.
slotint- (input) The key slot to retrieve. Only valid for model 4i and above.
Returns
- int
- 0 for success, less than 0 for failure.
zkExportPubKey
function
int zkExportPubKey(zkCTX ctx, uint8_t **pk, int *pk_sz, int pubkey_slot, bool slot_is_foreign)Parameters
ctxzkCTX- (input) Zymkey context.
pkuint8_t **- (output) Pointer to a pointer created by this function which contains the public key.
pk_szint *- (output) Pointer to an integer which contains the size of the public key.
pubkey_slotint- (input) The key slot to retrieve. Zymkey and HSM4 have slots 0, 1, and 2.
slot_is_foreignbool- (input) If true, designates the pubkey slot to come from the foreign keystore (Supported Devices: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module).
Returns
- int
- 0 for success, less than 0 for failure.
zkGetAllocSlotsList
function
int zkGetAllocSlotsList(zkCTX ctx, bool is_foreign, int *max_num_keys, int **alloc_key_list, int *alloc_key_list_sz)Parameters
ctxzkCTX- (input) Zymkey context.
is_foreignbool- (input) if true, retrieve allocation list of the foreign keys
max_num_keysint *- (input) retrieves the key pool size
alloc_key_listint **- (output) a pointer to an array of integers provided by this function to the caller
alloc_key_list_szint *- (output) a pointer to an integer which contains the size of the returned key list
Returns
- int
- 0 if successful, less than 0 for failure.
zkStoreForeignPubKey
function
int zkStoreForeignPubKey(zkCTX ctx, ZK_EC_KEY_TYPE pk_type, uint8_t *pk, int pk_sz)Parameters
ctxzkCTX- (input) Zymkey context.
pk_typeZK_EC_KEY_TYPE- (input) The type of the public key.
pkuint8_t *- (input) Pointer to the public key to store.
pk_szint- (input) The public key size.
Returns
- int
- allocated slot number in foreign key store, less than 0 for failure.
zkDisablePubKeyExport
function
int zkDisablePubKeyExport(zkCTX ctx, int pubkey_slot, bool slot_is_foreign)Parameters
ctxzkCTX- (input) Zymkey context.
pubkey_slotint- (input) The key slot to disable pubkey export on.
slot_is_foreignbool- (input) The slot parameter refers to a slot in the foreign keyring.
Returns
- int
- 0 for success, less than 0 for failure.
zkGenKeyPair
function
int zkGenKeyPair(zkCTX ctx, ZK_EC_KEY_TYPE type)Parameters
ctxzkCTX- (input) Zymkey context.
typeZK_EC_KEY_TYPE- (input) The type of key to generate (ZK_EC_KEY_TYPE).
Returns
- int
- allocated slot number if successful, less than 0 for failure.
zkGenEphemeralKeyPair
function
int zkGenEphemeralKeyPair(zkCTX ctx, ZK_EC_KEY_TYPE type)Parameters
ctxzkCTX- (input) Zymkey context.
typeZK_EC_KEY_TYPE- (input) The type of key to generate (ZK_EC_KEY_TYPE).
Returns
- int
- 0 if successful, less than 0 for failure.
zkRemoveKey
function
int zkRemoveKey(zkCTX ctx, int slot, bool slot_is_foreign)Parameters
ctxzkCTX- (input) Zymkey context.
slotint- (input) The slot
slot_is_foreignbool- (input) The slot parameter refers to a slot in the foreign keyring.
Returns
- int
- 0 if successful, less than 0 for failure.
zkInvalidateEphemeralKey
function
int zkInvalidateEphemeralKey(zkCTX ctx)Parameters
ctxzkCTX- (input) Zymkey context.
Returns
- int
- 0 for success, less than 0 for failure.
Digital Wallet (BIP32/39/44)
zkGenWalletMasterSeedWithBIP39
function
int zkGenWalletMasterSeedWithBIP39(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, const char *passphrase, char **mnemonic)Parameters
ctxzkCTX- (input) Zymkey context.
typeZK_EC_KEY_TYPE- (input) The type of key to generate (ZK_EC_KEY_TYPE).
variantconst char *- (input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_nameconst char *- (input) An ASCII string which contains the name of the wallet.
master_generator_keyconst uint8_t *- (input) The master generator key used to help generate the master seed. Can be empty string.
master_generator_key_sizeint- (input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
passphraseconst char *- (input) The passphrase to generate a different BIP39_mnemonic. Can be empty string.
mnemonicchar **- (output) A pointer to the mnemonic sentence. If NULL, the master seed is generated per BIP32. Otherwise, the master seed is generated per recovery strategy and the mnemonic sentence is returned in this parameter. The string is null terminated and encoded in UTF-8 NFKD from the English dictionary.
Returns
- int
- allocated slot number if successful, less than 0 for failure.
zkGenWalletMasterSeedWithSLIP39
function
int zkGenWalletMasterSeedWithSLIP39(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, int group_count, int group_threshold, int group_iteration_exponent, const char *master_passphrase)Parameters
ctxzkCTX- (input) Zymkey context.
typeZK_EC_KEY_TYPE- (input) The type of key to generate (ZK_EC_KEY_TYPE).
variantconst char *- (input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_nameconst char *- (input) An ASCII string which contains the name of the wallet.
master_generator_keyconst uint8_t *- (input) The master generator key used to help generate the master seed. Can be empty string.
master_generator_key_sizeint- (input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
group_countint- (input) The total count of groups(shards) to split into.
group_thresholdint- (input) The count of groups(shards) needed to restore the master seed.
group_iteration_exponentint- (input) The iteration of exponent of SLIP39.
master_passphraseconst char *- (input) The master passphrase used for slip 39 recovery process.
Returns
- int
- 0 if successful on opening a SLIP39 session, less than 0 for failure.
zkSetSLIP39GroupInfo
function
int zkSetSLIP39GroupInfo(zkCTX ctx, int group_index, int member_count, int member_threshold)Parameters
ctxzkCTX- (input) Zymkey context.
group_indexint- (input) The index of the group to generate shards from. Index starts at 0.
member_countint- (input) The total amount of member shards in this group to generate.
member_thresholdint- (input) The number of member shards needed to recreate this group in recovery.
Returns
- int
- 0 if successful on configuring the active group, less than 0 for failure.
zkAddSLIP39MemberPassword
function
int zkAddSLIP39MemberPassword(zkCTX ctx, const char *passhrase, char **mnemonic_sentence)Parameters
ctxzkCTX- (input) Zymkey context.
passhraseconst char *- (input) Password for the shard. Can be empty string.
mnemonic_sentencechar **- (output) The mnemonic sentence of the shard.
Returns
- int
- 0 if successful on opening a SLIP39 session, less than 0 or if more data is required, or, on the final call, for failure.
zkCancelSLIP39Session
function
int zkCancelSLIP39Session(zkCTX ctx)Parameters
ctxzkCTX- (input) Zymkey context.
Returns
- int
- 0 if successful on aborting a SLIP39 session, less than 0 for failure.
zkGenOversightWallet
function
int zkGenOversightWallet(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const uint8_t *pub_key, const uint8_t *chain_code, const char *node_addr, const char *wallet_name)Parameters
ctxzkCTX- (input) Zymkey context.
typeZK_EC_KEY_TYPE- (input) The type of key to generate (ZK_EC_KEY_TYPE).
variantconst char *- (input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
pub_keyconst uint8_t *- (input) The public key to create the oversight wallet from. Should come from a hardened node in a node tree.
chain_codeconst uint8_t *- (input) The chain code of the public key being used to create the oversight wallet.
node_addrconst char *- (input) The node address index of the public key being used.
wallet_nameconst char *- (input) The name of the oversight wallet being created.
Returns
- int
- allocated slot number if successful, less than 0 for failure.
zkGenWalletChildKey
function
int zkGenWalletChildKey(zkCTX ctx, int parent_key_slot, uint32_t index, bool is_hardened, bool return_chain_code, uint8_t **chain_code)Parameters
ctxzkCTX- (input) Zymkey context.
parent_key_slotint- (input) The parent key slot to base the child key derivation on.
indexuint32_t- (input) The index of the child seed. This determines the node address as well as the outcome of the key generation.
is_hardenedbool- (input) If true, a hardened key is generated.
return_chain_codebool- (input) If true, returns the chain code of the public key that was just generated. Has to be a hardened node as well.
chain_codeuint8_t **- (output) the chain code of the public key
Returns
- int
- allocated slot number if successful, less than 0 for failure.
zkRestoreWalletMasterSeedFromBIP39Mnemonic
function
int zkRestoreWalletMasterSeedFromBIP39Mnemonic(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, const char *BIP39_passphrase, char *BIP39_mnemonic)Parameters
ctxzkCTX- (input) Zymkey context.
typeZK_EC_KEY_TYPE- (input) The type of key to generate (ZK_KEY_TYPE).
variantconst char *- (input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_nameconst char *- (input) An ASCII string which contains the name of the wallet.
master_generator_keyconst uint8_t *- (input) The master generator key used to help generate the master seed.
master_generator_key_sizeint- (input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
BIP39_passphraseconst char *- (input) The passphrase used to generate the BIP39_mnemonic.
BIP39_mnemonicchar *- (input) The BIP39_mnemonic string, null terminated and UTF-8 NFKD encoded from the BIP39 English dictionary.
Returns
- int
- allocated slot number if successful, less than 0 for failure.
zkRestoreWalletMasterSeedFromSLIP39
function
int zkRestoreWalletMasterSeedFromSLIP39(zkCTX ctx, ZK_EC_KEY_TYPE type, const char *variant, const char *wallet_name, const uint8_t *master_generator_key, int master_generator_key_size, const char *SLIP39_passphrase)Parameters
ctxzkCTX- (input) Zymkey context.
typeZK_EC_KEY_TYPE- (input) The type of key to generate (ZK_KEY_TYPE).
variantconst char *- (input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.
wallet_nameconst char *- (input) An ASCII string which contains the name of the wallet.
master_generator_keyconst uint8_t *- (input) The master generator key used to help generate the master seed.
master_generator_key_sizeint- (input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.
SLIP39_passphraseconst char *- (input) The master passphrase.
Returns
- int
- allocated slot number if successful, less than 0 for failure.
zkAddRestoreSLIP39Mnemonic
function
int zkAddRestoreSLIP39Mnemonic(zkCTX ctx, const char *passphrase, const char *mnemonic_sentence)Parameters
ctxzkCTX- (input) Zymkey context.
passphraseconst char *- (input) The passphrase that was attached to the shard.
mnemonic_sentenceconst char *- (input) The twenty-four word sentence mnemonic shard.
Returns
- int
- allocated slot number when all shards required are fed in, less than 0 for no change.
zkGetWalletNodeAddrFromKeySlot
function
int zkGetWalletNodeAddrFromKeySlot(zkCTX ctx, int slot, char **node_addr, char **wallet_name, int *master_seed_slot)Parameters
ctxzkCTX- (input) Zymkey context.
slotint- (input) A key slot number that is part of a digital wallet.
node_addrchar **- (output) A pointer to a pointer which will contain the node address in ASCII.
wallet_namechar **- (output) A pointer to a pointer which will contain the wallet name in ASCII. If NULL, this parameter will not be retrieved.
master_seed_slotint *- (output) A pointer to an integer which will contain the master seed key slot. If NULL, this parameter will not be retrieved.
Returns
- int
- 0 if successful, less than 0 for failure.
zkGetWalletKeySlotFromNodeAddr
function
int zkGetWalletKeySlotFromNodeAddr(zkCTX ctx, const char *node_addr, const char *wallet_name, int master_seed_slot, int *slot)Parameters
ctxzkCTX- (input) Zymkey context.
node_addrconst char *- (input) A pointer which contains the node address in ASCII.
wallet_nameconst char *- (input) A pointer which contains the wallet name in ASCII, used to identify the wallet identity. If desired, this parameter can be NULL and the master_seed_slot parameter can be specified instead.
master_seed_slotint- (input) The master seed slot. Can be used to specify the wallet identity instead of the wallet name.
slotint *- (output) A pointer to an integer which contains the associated key slot.
Returns
- int
- 0 if successful, less than 0 for failure.
Perimeter Detect
zkSetPerimeterEventAction
function
int zkSetPerimeterEventAction(zkCTX ctx, int channel, uint32_t action_flags)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
ctxzkCTX- (input) Zymkey context.
channelint- (input) The channel (0 or 1) that the action flags will be applied to.
action_flagsuint32_t(input) The actions to apply to the perimeter event channel:
- Notify (ZK_PERIMETER_EVENT_ACTION_NOTIFY)
- Self-destruct (ZK_PERIMETER_EVENT_ACTION_SELF_DESTRUCT)
Returns
- int
- 0 for success, less than 0 for failure.
zkSetDigitalPerimeterDetectLPPeriod
function
int zkSetDigitalPerimeterDetectLPPeriod(zkCTX ctx, int lp_period)Parameters
ctxzkCTX- (input) Zymkey context.
lp_periodint- (input) low power period in microseconds
Returns
- int
- 0 if successful, less than 0 for failure.
zkSetDigitalPerimeterDetectLPMaxBits
function
int zkSetDigitalPerimeterDetectLPMaxBits(zkCTX ctx, int max_num_bits)Parameters
ctxzkCTX- (input) Zymkey context.
max_num_bitsint- (input) max number of bits
Returns
- int
- 0 if successful, less than 0 for failure.
zkSetDigitalPerimeterDetectDelays
function
int zkSetDigitalPerimeterDetectDelays(zkCTX ctx, int min_delay_ns, int max_delay_ns)Parameters
ctxzkCTX- (input) Zymkey context.
min_delay_nsint- (input) minimum delay in nanoseconds
max_delay_nsint- (input) maximum delay in nanoseconds
Returns
- int
- 0 if successful, less than 0 for failure.
zkWaitForPerimeterEvent
function
int zkWaitForPerimeterEvent(zkCTX ctx, uint32_t timeout_ms)Parameters
ctxzkCTX- (input) Zymkey context.
timeout_msuint32_t- (input) The maximum amount of time in milliseconds to wait for a perimeter event to arrive.
Returns
- int
- 0 for success, less than 0 for failure, -ETIMEDOUT when no perimeter events detected within the specified timeout
zkGetPerimeterDetectInfo
function
int zkGetPerimeterDetectInfo(zkCTX ctx, uint32_t **timestamps_sec, int *num_timestamps)Parameters
ctxzkCTX- (input) Zymkey context.
timestamps_secuint32_t **- (output) The timestamps for when any breach occurred. The index in this array corresponds to the channel number used by zkSetPerimeterEventAction. A 0 value means no breach has occurred on this channel. This array is allocated by this routine and so it must be freed by the caller.
num_timestampsint *- (output) The number of timestamps in the returned array
Returns
- int
- 0 for success, less than 0 for failure.
zkClearPerimeterDetectEvents
function
int zkClearPerimeterDetectEvents(zkCTX ctx)Parameters
ctxzkCTX
Returns
- int
- 0 for success, less than 0 for failure.
LED Control
zkLEDOff
function
int zkLEDOff(zkCTX ctx)Parameters
ctxzkCTX- (input) Zymkey context.
Returns
- int
- 0 for success, less than 0 for failure.
zkLEDOn
function
int zkLEDOn(zkCTX ctx)Parameters
ctxzkCTX- (input) Zymkey context.
Returns
- int
- 0 for success, less than 0 for failure.
zkLEDFlash
function
int zkLEDFlash(zkCTX ctx, uint32_t on_ms, uint32_t off_ms, uint32_t num_flashes)Parameters
ctxzkCTX- (input) Zymkey context.
on_msuint32_t- (input) The amount of time, in milliseconds, that the LED will stay on during a flash cycle.
off_msuint32_t- (input) The amount of time, in milliseconds, that the LED will stay off during a flash cycle.
num_flashesuint32_t- (input) The number of on/off flash cycles to complete. If this parameter is 0, then the LED will flash indefinitely.
Returns
- int
- 0 for success, less than 0 for failure.
Administrative Ops
zkSetI2CAddr
function
int zkSetI2CAddr(zkCTX ctx, int addr)Parameters
ctxzkCTX- (input) Zymkey context.
addrint- (input) The i2c address that the Zymkey will set itself to.
Returns
- int
- 0 for success, less than 0 for failure.
Time
zkGetTime
function
int zkGetTime(zkCTX ctx, uint32_t *epoch_time_sec, bool precise_time)Parameters
ctxzkCTX- (input) Zymkey context.
epoch_time_secuint32_t *- (output) The time in seconds from the epoch (Jan. 1, 1970).
precise_timebool- (input) If true, this API returns the time after the next second falls. This means that the caller could be blocked up to one second. If false, the API returns immediately with the current time reading.
Returns
- int
- 0 for success, less than 0 for failure.
Accelerometer
zkSetTapSensitivity
function
int zkSetTapSensitivity(zkCTX ctx, int axis, float pct)Parameters
ctxzkCTX- (input) Zymkey context.
axisint- (input) The axis to configure. This parameter should contain one of the values in the enum typedef ACCEL_AXIS_TYPE.
pctfloat(input) The sensitivity expressed as percentage.
- 0% = Shut down: Tap detection should not occur along the axis.
- 100% = Maximum sensitivity.
Returns
- int
- 0 for success, less than 0 for failure.
zkWaitForTap
function
int zkWaitForTap(zkCTX ctx, uint32_t timeout_ms)Parameters
ctxzkCTX- (input) Zymkey context.
timeout_msuint32_t- (input) The maximum amount of time in milliseconds to wait for a tap event to arrive.
Returns
- int
- 0 for success, less than 0 for failure, -ETIMEDOUT when no tap events detected within the specified timeout
zkGetAccelerometerData
function
int zkGetAccelerometerData(zkCTX ctx, zkAccelAxisDataType *x, zkAccelAxisDataType *y, zkAccelAxisDataType *z)Parameters
ctxzkCTX- (input) Zymkey context.
xzkAccelAxisDataType *- (output) x axis accelerometer information
yzkAccelAxisDataType *- (output) y axis accelerometer information
zzkAccelAxisDataType *- (output) z axis accelerometer information
Returns
- int
- 0 for success, less than 0 for failure.
Binding Management
zkLockBinding
function
int zkLockBinding(zkCTX ctx)Parameters
ctxzkCTX
Returns
- int
- 0 for success, less than 0 for failure.
zkGetCurrentBindingInfo
function
int zkGetCurrentBindingInfo(zkCTX ctx, bool *binding_is_locked, bool *is_bound)Parameters
ctxzkCTX- (input) Zymkey context.
binding_is_lockedbool *- (output) Binary value which expresses the current binding lock state.
is_boundbool *- (output) Binary value which expresses the current bind state.
Returns
- int
- 0 for success, less than 0 for failure.
Module Info
zkGetModelNumberString
function
int zkGetModelNumberString(zkCTX ctx, char **model_str)Parameters
ctxzkCTX- (input) Zymkey context which was created with zkOpen
model_strchar **- (output) A double pointer to the model string. This function allocates this string. It is the caller’s responsibility to free it.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetFirmwareVersionString
function
int zkGetFirmwareVersionString(zkCTX ctx, char **fw_ver_str)Parameters
ctxzkCTX- (input) Zymkey context which was created with zkOpen
fw_ver_strchar **- (output) A double pointer to the firmware version string. This function allocates this string. It is the caller’s responsibility to free it.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetSerialNumberString
function
int zkGetSerialNumberString(zkCTX ctx, char **serial_num_str)Parameters
ctxzkCTX- (input) Zymkey context which was created with zkOpen
serial_num_strchar **- (output) A double pointer to the serial number string. This function allocates this string. It is the caller’s responsibility to free it.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetCPUTemp
function
int zkGetCPUTemp(zkCTX ctx, float *cpu_temp)Parameters
ctxzkCTX- (input) Zymkey context.
cpu_tempfloat *- (output) The temperature in celsius of the CPU.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetAUXTemp
function
int zkGetAUXTemp(zkCTX ctx, int index, float *aux_temp)Parameters
ctxzkCTX- (input) Zymkey context.
indexint- (input) Index for which aux temp to be polled.
aux_tempfloat *- (output) The temperature in celsius.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetRTCDrift
function
int zkGetRTCDrift(zkCTX ctx, float *rtc_drift)Parameters
ctxzkCTX- (input) Zymkey context.
rtc_driftfloat *- (output) The RTC drift.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetBatteryVoltage
function
int zkGetBatteryVoltage(zkCTX ctx, float *batt_voltage)Parameters
ctxzkCTX- (input) Zymkey context.
batt_voltagefloat *- (output) The current battery voltage value
Returns
- int
- 0 if successful, less than 0 for failure.
Battery Voltage Monitor
zkSetBatteryVoltageAction
function
int zkSetBatteryVoltageAction(zkCTX ctx, int action)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
ctxzkCTX- (input) Zymkey context.
actionint(input) The action to apply, specify one of the ZK_THRESHOLD_ACTION_TYPE:
- Do nothing (ZK_ACTION_NONE)
- Sleep (ZK_ACTION_SLEEP)
- Self-destruct (ZK_ACTION_SELF_DESTRUCT)
Returns
- int
- 0 for success, less than 0 for failure.
zkSetBatteryVoltageThreshold
function
int zkSetBatteryVoltageThreshold(zkCTX ctx, float threshold)Parameters
ctxzkCTX- (input) Zymkey context.
thresholdfloat- (input) The threshold in Volts.
Returns
- int
- 0 for success, less than 0 for failure.
CPU Temperature Monitor
zkSetCPUTempAction
function
int zkSetCPUTempAction(zkCTX ctx, int action)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
ctxzkCTX- (input) Zymkey context.
actionint(input) The action to apply, used it’s named constant from ZK_THRESHOLD_ACTION_TYPE:
- Do nothing (ZK_ACTION_NONE)
- Self-destruct (ZK_ACTION_SELF_DESTRUCT)
Returns
- int
- 0 for success, less than 0 for failure.
zkSetCPULowTempThreshold
function
int zkSetCPULowTempThreshold(zkCTX ctx, float threshold)Parameters
ctxzkCTX- (input) Zymkey context.
thresholdfloat- (input) The threshold in celsius.
Returns
- int
- 0 for success, less than 0 for failure.
zkSetCPUHighTempThreshold
function
int zkSetCPUHighTempThreshold(zkCTX ctx, float threshold)Parameters
ctxzkCTX- (input) Zymkey context.
thresholdfloat- (input) The threshold in celsius.
Returns
- int
- 0 for success, less than 0 for failure.
zkSetSupervisedBootPolicy
function
int zkSetSupervisedBootPolicy(zkCTX ctx, int policy_id)Parameters
ctxzkCTX- (input) Zymkey context.
policy_idint(input) The actions to apply to the Supervised boot process:
- 0 Do Nothing (ZK_SUPBOOT_FAIL_NO_ACTION)
- 1 Self-Destruct (ZK_SUPBOOT_FAIL_DESTROY)
- 2 Hold Chip in Reset (ZK_SUPBOOT_FAIL_HOLD_RESET)
Returns
- int
- 0 for success, less than 0 for failure.
zkAddOrUpdateSupervisedBootFile
function
int zkAddOrUpdateSupervisedBootFile(zkCTX ctx, const char *file_path, int slot)Parameters
ctxzkCTX- (input) Zymkey context.
file_pathconst char *- (input) The file to be signed and checked by Supervised boot.
slotint- (input) The slot to sign the file with.
Returns
- int
- 0 for success, less than 0 for failure.
zkRemoveSupervisedBootFile
function
int zkRemoveSupervisedBootFile(zkCTX ctx, const char *file_path)Parameters
ctxzkCTX- (input) Zymkey context.
file_pathconst char *- (input) The file to be removed from the Supervised boot manifest.
Returns
- int
- 0 for success, less than 0 for failure.
zkGetSupervisedBootFileManifest
function
int zkGetSupervisedBootFileManifest(zkCTX ctx, char **manifest)Parameters
ctxzkCTX- (input) Zymkey context.
manifestchar **- (output) The file manifest that is checked by Supervised boot.
Returns
- int
- 0 for success, less than 0 for failure.
Defines
ZK_PERIMETER_EVENT_ACTION_NOTIFY
macro
#define ZK_PERIMETER_EVENT_ACTION_NOTIFY (1 << 0)ZK_PERIMETER_EVENT_ACTION_SELF_DESTRUCT
macro
#define ZK_PERIMETER_EVENT_ACTION_SELF_DESTRUCT (1 << 1)Enums
ZK_EC_KEY_TYPE
enum
enum ZK_EC_KEY_TYPE| Value | Description |
|---|---|
ZK_NISTP256 | |
ZK_SECP256R1 = ZK_NISTP256 | |
ZK_SECP256K1 | |
ZK_ED25519 | |
ZK_X25519 |
ZK_RECOVERY_STRATEGY
enum
enum ZK_RECOVERY_STRATEGY| Value | Description |
|---|---|
ZK_NONE | |
ZK_BIP39 | |
ZK_SLIP39 |
ZK_ECDH_KDF_TYPE
enum
enum ZK_ECDH_KDF_TYPE| Value | Description |
|---|---|
ZK_KDF_RFC5869_SHA256 | |
ZK_KDF_RFC5869_SHA512 | |
ZK_KDF_PBKDF2_SHA256 | |
ZK_KDF_PBKDF2_SHA512 |
ZK_ACCEL_AXIS_TYPE
enum
enum ZK_ACCEL_AXIS_TYPE| Value | Description |
|---|---|
ZK_ACCEL_AXIS_X | |
ZK_ACCEL_AXIS_Y | |
ZK_ACCEL_AXIS_Z | |
ZK_ACCEL_AXIS_ALL |
ZK_THRESHOLD_ACTION_TYPE
enum
enum ZK_THRESHOLD_ACTION_TYPE| Value | Description |
|---|---|
ZK_ACTION_NONE | |
ZK_ACTION_SELF_DESTRUCT | |
ZK_ACTION_SLEEP |
Typedefs
zkCTX
typedef
typedef void* zkCTXZK_EC_KEY_TYPE
typedef
typedef enum ZK_EC_KEY_TYPE ZK_EC_KEY_TYPEZK_RECOVERY_STRATEGY
typedef
typedef enum ZK_RECOVERY_STRATEGY ZK_RECOVERY_STRATEGYZK_ECDH_KDF_TYPE
typedef
typedef enum ZK_ECDH_KDF_TYPE ZK_ECDH_KDF_TYPEZK_ACCEL_AXIS_TYPE
typedef
typedef enum ZK_ACCEL_AXIS_TYPE ZK_ACCEL_AXIS_TYPEZK_THRESHOLD_ACTION_TYPE
typedef
typedef enum ZK_THRESHOLD_ACTION_TYPE ZK_THRESHOLD_ACTION_TYPEzkAccelAxisDataType
typedef
typedef struct zkAccelAxisDataType zkAccelAxisDataTypeStructs
zkAccelAxisDataType
struct
Public Members
g
variable
double zkAccelAxisDataType::gtapDirection
variable
int zkAccelAxisDataType::tapDirection