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 void *zkCTX

typedef enum ZK_EC_KEY_TYPEZK_EC_KEY_TYPE

Supported key types.

typedef enum ZK_RECOVERY_STRATEGYZK_RECOVERY_STRATEGY

Supported recovery strategies.

typedef enum ZK_ECDH_KDF_TYPEZK_ECDH_KDF_TYPE

Supported ECDH key derivation function types.

typedef enum ZK_ACCEL_AXIS_TYPEZK_ACCEL_AXIS_TYPE

Accelerometer axis enum, used to set tap sensitivity.

typedef enum ZK_THRESHOLD_ACTION_TYPEZK_THRESHOLD_ACTION_TYPE

Possible actions for threshold monitor functions.

typedef struct zkAccelAxisDataTypezkAccelAxisDataType

zkGetAccelerometer data output.

Structs

struct zkAccelAxisDataType

#include <zk_app_utils.h>

zkGetAccelerometer data output.

double g

the axis reading in units of g-force.

int tapDirection

the direction of the force along the axis which caused a tap event: -1 = negative +1 = positive 0 = did not cause a tap event.

Enums

enum ZK_EC_KEY_TYPE

Supported key types.

enumerator ZK_NISTP256
enumerator ZK_SECP256R1
enumerator ZK_SECP256K1
enumerator ZK_ED25519
enumerator ZK_X25519

enum ZK_RECOVERY_STRATEGY

Supported recovery strategies.

enumerator ZK_NONE
enumerator ZK_BIP39
enumerator ZK_SLIP39

enum ZK_ECDH_KDF_TYPE

Supported ECDH key derivation function types.

enumerator ZK_KDF_RFC5869_SHA256
enumerator ZK_KDF_RFC5869_SHA512
enumerator ZK_KDF_PBKDF2_SHA256
enumerator ZK_KDF_PBKDF2_SHA512

enum ZK_ACCEL_AXIS_TYPE

Accelerometer axis enum, used to set tap sensitivity.

enumerator ZK_ACCEL_AXIS_X
enumerator ZK_ACCEL_AXIS_Y
enumerator ZK_ACCEL_AXIS_Z
enumerator ZK_ACCEL_AXIS_ALL

enum ZK_THRESHOLD_ACTION_TYPE

Possible actions for threshold monitor functions.

enumerator ZK_ACTION_NONE
enumerator ZK_ACTION_SELF_DESTRUCT
enumerator ZK_ACTION_SLEEP

Functions

Zymkey Context

int zkOpen ( zkCTX * ctx)

Open a Zymkey context.

Parameters

  • ctx

    (output) returns a pointer to a Zymkey context.

Returns

0 for success, less than 0 for failure.

int zkClose ( zkCTX ctx)

Close a Zymkey context.

Parameters

  • ctx

    (input) The Zymkey context to close.

Returns

0 for success, less than 0 for failure.

Random Number Generation

int zkCreateRandDataFile ( zkCTX ctx, const char * dst_filename, int rdata_sz)

Fill a file with random numbers.

Parameters

  • ctx

    (input) Zymkey context.

  • dst_filename

    (input) Absolute path name for the destination file.

  • rdata_sz

    (input) The number of random bytes to generate.

Returns

0 for success, less than 0 for failure.

int zkGetRandBytes ( zkCTX ctx, uint8_t ** rdata, int rdata_sz)

Get an array of random bytes.

Parameters

  • ctx

    (input) Zymkey context.

  • rdata

    (input) Pointer to a pointer of bytes.

  • rdata_sz

    (input) The number of random bytes to generate.

Returns

0 for success, less than 0 for failure.

Lock Data

int zkLockDataF2F ( zkCTX ctx, const char * src_pt_filename, const char * dst_ct_filename, bool use_shared_key)

Lock up source (plaintext) data from a file and store the results (ciphertext) in a destination file.

This function encrypts and signs a block of plaintext data from a file and stores the result in a destination file.

Parameters

  • ctx

    (input) Zymkey context.

  • src_pt_filename

    (input) The absolute path to the file where the source (plaintext) data is located.

  • dst_ct_filename

    (input) The absolute path to the file where the destination (ciphertext) data should be deposited.

  • use_shared_key

    (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

0 for success, less than 0 for failure.

int zkLockDataB2F ( zkCTX ctx, const uint8_t * src_pt, int src_pt_sz, const char * dst_ct_filename, bool use_shared_key)

Lock up source (plaintext) data from a byte array and store the results (ciphertext) in a destination file.

This function encrypts and signs a block of binary plaintext data and stores the result in a destination file.

Parameters

  • ctx

    (input) Zymkey context.

  • src_pt

    (input) Binary plaintext source byte array.

  • src_pt_sz

    (input) Size of plaintext source data.

  • dst_ct_filename

    (input) The absolute path to the file where the destination (ciphertext) data should be deposited.

  • use_shared_key

    (input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

0 for success, less than 0 for failure.

int zkLockDataF2B ( zkCTX ctx, const char * src_pt_filename, uint8_t ** dst_ct, int * dst_ct_sz, bool use_shared_key)

Lock up source (plaintext) data from a file and store the results (ciphertext) in a destination byte array.

This function encrypts and signs a block of plaintext data from a file and stores the result in a binary byte array.

Parameters

  • ctx

    (input) Zymkey context.

  • src_pt_filename

    (input) The absolute path to the file where the source (plaintext) data is located.

  • dst_ct

    (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.

  • dst_ct_sz

    (output) A pointer to an integer which contains the size of the destination array.

  • use_shared_key

    (input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

0 for success, less than 0 for failure.

int zkLockDataB2B ( zkCTX ctx, const uint8_t * src_pt, int src_pt_sz, uint8_t ** dst_ct, int * dst_ct_sz, bool use_shared_key)

Lock up source (plaintext) data from a byte array and store the results (ciphertext) in a destination byte array.

This function encrypts and signs a block of plaintext data and stores the result in a binary byte array.

Parameters

  • ctx

    (input) Zymkey context.

  • src_pt

    (input) Binary plaintext source byte array.

  • src_pt_sz

    (input) Size of plaintext source data.

  • dst_ct

    (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.

  • dst_ct_sz

    (output) A pointer to an integer which contains the size of the destination array.

  • use_shared_key

    (input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

0 for success, less than 0 for failure.

Unlock Data

int zkUnlockDataF2F ( zkCTX ctx, const char * src_ct_filename, const char * dst_pt_filename, bool use_shared_key)

Unlock source (ciphertext) data from a file and store the results (plaintext) in a destination file.

This function verifies a locked object signature and decrypts the associated ciphertext data.

Parameters

  • ctx

    (input) Zymkey context.

  • src_ct_filename

    (input) The absolute path to the file where the source (ciphertext) data is located.

  • dst_pt_filename

    (input) The absolute path to the file where the destination (plaintext) data should be deposited.

  • use_shared_key

    (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

0 for success, less than 0 for failure.

int zkUnlockDataB2F ( zkCTX ctx, const uint8_t * src_ct, int src_ct_sz, const char * dst_pt_filename, bool use_shared_key)

Unlock source (ciphertext) data from a byte array and store the results (plaintext) in a destination file.

This function verifies a locked object signature and decrypts the associated ciphertext data.

Parameters

  • ctx

    (input) Zymkey context.

  • src_ct

    (input) Binary ciphertext source byte array.

  • src_ct_sz

    (input) Size of ciphertext source data.

  • dst_pt_filename

    (input) The absolute path to the file where the destination (plaintext) data should be deposited.

  • use_shared_key

    (input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

0 for success, less than 0 for failure.

int zkUnlockDataF2B ( zkCTX ctx, const char * src_ct_filename, uint8_t ** dst_pt, int * dst_pt_sz, bool use_shared_key)

Unlock source (ciphertext) data from a file and store the results (plaintext) in a destination byte array.

This function verifies a locked object signature and decrypts the associated ciphertext data.

Parameters

  • ctx

    (input) Zymkey context.

  • src_ct_filename

    (input) The absolute path to the file where the source (ciphertext) data is located.

  • dst_pt

    (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.

  • dst_pt_sz

    (output) A pointer to an integer which contains the size of the destination array.

  • use_shared_key

    (input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

0 for success, less than 0 for failure.

int zkUnlockDataB2B ( zkCTX ctx, const uint8_t * src_ct, int src_ct_sz, uint8_t ** dst_pt, int * dst_pt_sz, bool use_shared_key)

Unlock source (ciphertext) data from a byte array and store the results (plaintext) in a destination byte array.

This function verifies a locked object signature and decrypts the associated ciphertext data.

Parameters

  • ctx

    (input) Zymkey context.

  • src_ct

    (input) Binary ciphertext source byte array.

  • src_ct_sz

    (input) Size of ciphertext source data.

  • dst_pt

    (output) A pointer to a pointer to an array of unsigned bytes created by this function. This pointer must be freed by the application when no longer needed.

  • dst_pt_sz

    (output) A pointer to an integer which contains the size of the destination array.

  • use_shared_key

    (input) Specifies if shared key is to be used. See zkLockDataF2F.

Returns

0 for success, less than 0 for failure.

ECDSA

int zkGenECDSASigFromDigest ( zkCTX ctx, const uint8_t * digest, int slot, uint8_t ** sig, int * sig_sz)

Generate a signature using the Zymkey’s ECDSA private key.

Parameters

  • ctx

    (input) Zymkey context.

  • digest

    (input) This parameter contains the digest of the data that will be used to generate the signature.

  • slot

    (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.

  • sig

    (output) A pointer to a pointer to an array of unsigned bytes which contains the generated signature. This pointer is created by this function and must be freed by the application when no longer needed.

  • sig_sz

    (output) A pointer to an integer which contains the size of the signature.

Returns

0 for success, less than 0 for failure.

int zkGenECDSASigFromDigestWithRecID ( zkCTX ctx, const uint8_t * digest, int slot, uint8_t ** sig, int * sig_sz, uint8_t * recovery_id)

Generate a signature using the Zymkey’s ECDSA private key.

Parameters

  • ctx

    (input) Zymkey context.

  • digest

    (input) This parameter contains the digest of the data that will be used to generate the signature.

  • slot

    (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.

  • sig

    (output) A pointer to a pointer to an array of unsigned bytes which contains the generated signature. This pointer is created by this function and must be freed by the application when no longer needed.

  • sig_sz

    (output) A pointer to an integer which contains the size of the signature.

  • recovery_id

    (output) Returns recovery id value needed for ethereum key recovery.

Returns

0 for success, less than 0 for failure.

int zkVerifyECDSASigFromDigest ( zkCTX ctx, const uint8_t * digest, int pubkey_slot, const uint8_t * sig, int sig_sz)

Verify a signature using one of the Zymkey’s public keys.

Verify a signature using an internal public key from the Zymkey private/public key store.

Parameters

  • ctx

    (input) Zymkey context.

  • digest

    (input) This parameter contains the digest of the data that will be used to generate the signature.

  • pubkey_slot

    (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.

  • sig

    (input) Array of bytes which contains the signature.

  • sig_sz

    (input) Size of signature.

Returns

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

int zkVerifyECDSASigFromDigestWithForeignKeySlot ( zkCTX ctx, const uint8_t * digest, int pubkey_slot, const uint8_t * sig, int sig_sz)

Verify a signature using one of the Zymkey’s foreign public keys.

Verify a signature using a public key from the Zymkey foreign key store.

Parameters

  • ctx

    (input) Zymkey context.

  • digest

    (input) This parameter contains the digest of the data that will be used to generate the signature.

  • pubkey_slot

    (input) The key slot to generate a signature from. This parameter is only valid for Zymkey models 4i and beyond.

  • sig

    (input) Array of bytes which contains the signature.

  • sig_sz

    (input) Size of signature.

Returns

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

ECDH and KDF

int zkDoRawECDH ( zkCTX ctx, int slot, const uint8_t * peer_pubkey, int peer_pubkey_sz, uint8_t ** pre_master_secret)

Perform a raw ECDH operation. (model >= HSM6).

Perform an ECDH operation with no Key Derivation Function (KDF). The raw pre-master secret is returned in the response. The peer public key is presented in the call.

Parameters

  • ctx

    (input) Zymkey context.

  • slot

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

  • peer_pubkey

    (input) The peer public key.

  • peer_pubkey_sz

    (input) Size of the peer public key.

  • pre_master_secret

    (output) returned pointer to the pre-master secret.

Returns

0 for success, less than 0 for general failure.

int zkDoRawECDHWithIntPeerPubkey ( zkCTX ctx, int slot, int peer_pubkey_slot, bool peer_pubkey_slot_is_foreign, uint8_t ** pre_master_secret)

Perform a raw ECDH operation. (model >= HSM6).

Perform an ECDH operation with no Key Derivation Function (KDF). The raw pre-master secret is returned in the response. The peer public key is referenced from the zymkey internal key store.

Parameters

  • ctx

    (input) Zymkey context.

  • slot

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

  • peer_pubkey_slot

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

  • peer_pubkey_slot_is_foreign

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

  • pre_master_secret

    (output) returned pointer to the pre-master secret.

Returns

0 for success, less than 0 for general failure.

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)

Perform an ECDH operation plus Key Derivation Function. (model >= HSM6).

Perform an ECDH operation with Key Derivation Function (KDF). The derived key is returned in the response. The peer public key is presented in the call.

Parameters

  • ctx

    (input) Zymkey context.

  • slot

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

  • peer_pubkey

    (input) The peer public key.

  • peer_pubkey_sz

    (input) Size of the peer public key.

  • salt

    (input) The salt to use for the selected KDF.

  • salt_sz

    (input) The salt size. Must be less than or equal to 128 bytes.

  • info

    (input) The info field to use for RFC 5869. Ignored for PBKDF2.

  • info_sz

    (input) The size of the info parameter. Must be less than or equal to 128 bytes.

  • num_iterations

    (input) Number of iterations to carry out (PBKDF only).

  • derived_key_sz

    (input) The desired number of bytes to return for the KDF. For RFC 5869, this value must be less than 8160 bytes (SHA256) or 16320 (SHA512).

  • derived_key

    (output) returned pointer to the derived key.

Returns

0 for success, less than 0 for general failure.

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)

Perform an ECDH operation plus Key Derivation Function. (model >= HSM6).

Perform an ECDH operation with Key Derivation Function (KDF). The derived key is returned in the response. The peer public key is referenced from the zymkey internal key store.

Parameters

  • ctx

    (input) Zymkey context.

  • slot

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

  • peer_pubkey_slot

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

  • peer_pubkey_slot_is_foreign

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

  • salt

    (input) The salt to use for the selected KDF.

  • salt_sz

    (input) The salt size. Must be less than or equal to 128 bytes.

  • info

    (input) The info field to use for RFC 5869. Ignored for PBKDF2.

  • info_sz

    (input) The size of the info parameter. Must be less than or equal to 128 bytes.

  • num_iterations

    (input) Number of iterations to carry out (PBKDF only).

  • derived_key_sz

    (input) The desired number of bytes to return for the KDF. For RFC 5869, this value must be less than 8160 bytes (SHA256) or 16320 (SHA512).

  • derived_key

    (output) returned pointer to the derived key.

Returns

0 for success, less than 0 for general failure.

Key Management

int zkSaveECDSAPubKey2File ( zkCTX ctx, const char * filename, int slot)

[DEPRECATED] Use zkExportPubKey2File. Store the public key to a host file in PEM format.

This function is useful for generating Certificate Signing Requests (CSR).

Parameters

  • ctx

    (input) Zymkey context.

  • filename

    (input) Filename where PEM formatted public key is to be stored.

  • slot

    (input) The key slot to retrieve. Only valid for model 4i and above.

Returns

0 for success, less than 0 for failure.

int zkExportPubKey2File ( zkCTX ctx, const char * filename, int pubkey_slot, bool slot_is_foreign)

Store the public key to a host file in PEM format.

This function is useful for generating Certificate Signing Requests (CSR).

Parameters

  • ctx

    (input) Zymkey context.

  • filename

    (input) Filename where PEM formatted public key is to be stored.

  • pubkey_slot

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

  • slot_is_foreign

    (input) If true, designates the pubkey slot to come from the foreign keystore. (model >= HSM6).

Returns

0 for success, less than 0 for failure.

int zkGetECDSAPubKey ( zkCTX ctx, uint8_t ** pk, int * pk_sz, int slot)

[DEPRECATED] Use zkExportPubKey. Gets the public key and stores in a byte array created by this function.

Parameters

  • ctx

    (input) Zymkey context.

  • pk

    (output) Pointer to a pointer created by this function which contains the public key.

  • pk_sz

    (output) Pointer to an integer which contains the size of the public key.

  • slot

    (input) The key slot to retrieve. Only valid for model 4i and above.

Returns

0 for success, less than 0 for failure.

int zkExportPubKey ( zkCTX ctx, uint8_t ** pk, int * pk_sz, int pubkey_slot, bool slot_is_foreign)

Gets the public key and stores in a byte array created by this function.

Parameters

  • ctx

    (input) Zymkey context.

  • pk

    (output) Pointer to a pointer created by this function which contains the public key.

  • pk_sz

    (output) Pointer to an integer which contains the size of the public key.

  • pubkey_slot

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

  • slot_is_foreign

    (input) If true, designates the pubkey slot to come from the foreign keystore (model >= HSM6).

Returns

0 for success, less than 0 for failure.

int zkGetAllocSlotsList ( zkCTX ctx, bool is_foreign, int * max_num_keys, int ** alloc_key_list, int * alloc_key_list_sz)

Get the list of allocated keys (model >= HSM6).

This function returns a list of all allocated key slots.

Parameters

  • ctx

    (input) Zymkey context.

  • is_foreign

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

  • max_num_keys

    (input) retrieves the key pool size.

  • alloc_key_list

    (output) a pointer to an array of integers provided by this function to the caller.

  • alloc_key_list_sz

    (output) a pointer to an integer which contains the size of the returned key list.

Returns

0 if successful, less than 0 for failure.

int zkStoreForeignPubKey ( zkCTX ctx, ZK_EC_KEY_TYPE pk_type, uint8_t * pk, int pk_sz)

Store a new foreign public key in Zymkey. (model >= HSM6).

This function stores a new foreign public key in the Zymkey public key ring. This public key can be used for signature verification in use cases where it is desirable to hide the public key.

Parameters

  • ctx

    (input) Zymkey context.

  • pk_type

    (input) The type of the public key.

  • pk

    (input) Pointer to the public key to store.

  • pk_sz

    (input) The public key size.

Returns

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

int zkDisablePubKeyExport ( zkCTX ctx, int pubkey_slot, bool slot_is_foreign)

Prevent a public key from being exported to the host. (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • pubkey_slot

    (input) The key slot to disable pubkey export on.

  • slot_is_foreign

    (input) The slot parameter refers to a slot in the foreign keyring.

Returns

0 for success, less than 0 for failure.

int zkGenKeyPair ( zkCTX ctx, ZK_EC_KEY_TYPE type)

Generate a new persistent key pair. (model >= HSM6).

This function generates a new key pair of the specified type and store it persistently. This key pair cannot be used as part of the zymkey’s digital wallet operations.

Parameters

  • ctx

    (input) Zymkey context.

  • type

    (input) The type of key to generate (ZK_EC_KEY_TYPE).

Returns

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

int zkGenEphemeralKeyPair ( zkCTX ctx, ZK_EC_KEY_TYPE type)

Generate an ephemeral key pair. (model >= HSM6).

This function generates an ephemeral key pair of the specified type. Ephemeral key pairs are useful when performing ECDH for time-of-flight encryption. Only one ephemeral key slot is available and is not persistent between reboots.

Parameters

  • ctx

    (input) Zymkey context.

  • type

    (input) The type of key to generate (ZK_EC_KEY_TYPE).

Returns

0 if successful, less than 0 for failure.

int zkRemoveKey ( zkCTX ctx, int slot, bool slot_is_foreign)

Remove a key pair or a foreign public key. (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • slot

    (input) The slot.

  • slot_is_foreign

    (input) The slot parameter refers to a slot in the foreign keyring.

Returns

0 if successful, less than 0 for failure.

int zkInvalidateEphemeralKey ( zkCTX ctx)

Invalidate the ephemeral key. (model >= HSM6).

This function invalidates the ephemeral key.

Parameters

  • ctx

    (input) Zymkey context.

Returns

0 for success, less than 0 for failure.

Digital Wallet (BIP32/39/44)

int zkGenWalletMasterSeed ( zkCTX ctx, ZK_EC_KEY_TYPE type, const char * wallet_name, const uint8_t * master_generator_key, int master_generator_key_size, const char * bip39_passphrase, char ** bip39_mnemonic)

Generate master seed to start a new blockchain wallet. (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • type

    (input) The type of key to generate (ZK_EC_KEY_TYPE).

  • wallet_name

    (input) An ASCII string which contains the name of the wallet.

  • master_generator_key

    (input) The master generator key used to help generate the master seed. Can be empty string.

  • master_generator_key_size

    (input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.

  • bip39_passphrase

    (input) The passphrase to generate a different bip39_mnemonic. Can be empty string.

  • bip39_mnemonic

    (output) A pointer to the bip39 mnemonic sentence. If NULL, the master seed is generated per BIP32. Otherwise, the master seed is generated per BIP39 and the mnemonic sentence is returned in this parameter. The string is null terminated and encoded in UTF-8 NFKD from the BIP39 Enlish dictionary.

Returns

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

int zkGenWalletChildKey ( zkCTX ctx, int parent_key_slot, uint32_t index, bool is_hardened)

Generate child key from a parent key in a blockchain wallet . (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • parent_key_slot

    (input) The parent key slot to base the child key derivation on.

  • index

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

  • is_hardened

    (input) If true, a hardened key is generated.

Returns

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

int zkRestoreWalletMasterSeedFromMnemonic ( zkCTX ctx, ZK_EC_KEY_TYPE type, const char * wallet_name, const uint8_t * master_generator_key, int master_generator_key_size, const char * bip39_passphrase, char * bip39_mnemonic)

Restore a master seed from a BIP39 mnemonic and a master generator key. (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • type

    (input) The type of key to generate (ZK_KEY_TYPE).

  • wallet_name

    (input) An ASCII string which contains the name of the wallet.

  • master_generator_key

    (input) The master generator key used to help generate the master seed.

  • master_generator_key_size

    (input) The size of the master generator key. If 0, no master generator key is used in the formulation of the master seed.

  • bip39_passphrase

    (input) The passphrase used to generate the bip39_mnemonic.

  • bip39_mnemonic

    (input) The bip39_mnemonic string, null terminated and UTF-8 NFKD encoded from the BIP39 English dictionary.

Returns

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

int zkGetWalletNodeAddrFromKeySlot ( zkCTX ctx, int slot, char ** node_addr, char ** wallet_name, int * master_seed_slot)

Derive the node address from a key slot number. (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • slot

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

  • node_addr

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

  • wallet_name

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

  • master_seed_slot

    (output) A pointer to an integer which will contain the master seed key slot. If NULL, this parameter will not be retrieved.

Returns

0 if successful, less than 0 for failure.

int zkGetWalletKeySlotFromNodeAddr ( zkCTX ctx, const char * node_addr, const char * wallet_name, int master_seed_slot, int * slot)

Derive the slot address from a node address. (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

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

  • slot

    (output) A pointer to an integer which contains the associated key slot.

Returns

0 if successful, less than 0 for failure.

Perimeter Detect

int zkSetPerimeterEventAction ( zkCTX ctx, int channel, uint32_t action_flags)

Set perimeter breach action.

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

  • Notify host.
  • Zymkey self-destruct.

Parameters

  • 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).

Returns

0 for success, less than 0 for failure.

int zkSetDigitalPerimeterDetectLPPeriod ( zkCTX ctx, int lp_period)

Set the low power period (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • lp_period

    (input) low power period in microseconds.

Returns

0 if successful, less than 0 for failure.

int zkSetDigitalPerimeterDetectLPMaxBits ( zkCTX ctx, int max_num_bits)

Set the low power max number of bits (model >= HSM6).

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

Parameters

  • ctx

    (input) Zymkey context.

  • max_num_bits

    (input) max number of bits.

Returns

0 if successful, less than 0 for failure.

int zkSetDigitalPerimeterDetectDelays ( zkCTX ctx, int min_delay_ns, int max_delay_ns)

Set the delays (model >= HSM6).

This function sets delays on the digital perimeter detect.

Parameters

  • ctx

    (input) Zymkey context.

  • min_delay_ns

    (input) minimum delay in nanoseconds.

  • max_delay_ns

    (input) maximum delay in nanoseconds.

Returns

0 if successful, less than 0 for failure.

int zkWaitForPerimeterEvent ( zkCTX ctx, uint32_t timeout_ms)

Wait for a perimeter breach event to be detected.

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

Parameters

  • timeout_ms

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

Returns

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

int zkGetPerimeterDetectInfo ( zkCTX ctx, uint32_t ** timestamps_sec, int * num_timestamps)

Get current perimeter detect info.

This function gets the timestamp of the first perimeter detect event for the given channel.

Parameters

  • timestamps_sec

    (output) The timestamps for when any breach occurred. The index in this array corresponds to the channel number used by zkSetPerimeterEventAction. A 0 value means no breach has occurred on this channel. This array is allocated by this routine and so it must be freed by the caller.

  • num_timestamps

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

Returns

0 for success, less than 0 for failure.

int zkClearPerimeterDetectEvents ( zkCTX ctx)

Clear perimeter detect events.

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

Returns

0 for success, less than 0 for failure.

LED Control

int zkLEDOff ( zkCTX ctx)

Turns the LED off.

Parameters

  • ctx

    (input) Zymkey context.

Returns

0 for success, less than 0 for failure.

int zkLEDOn ( zkCTX ctx)

Turns the LED on.

Parameters

  • ctx

    (input) Zymkey context.

Returns

0 for success, less than 0 for failure.

int zkLEDFlash ( zkCTX ctx, uint32_t on_ms, uint32_t off_ms, uint32_t num_flashes)

Flashes the LED.

Parameters

  • ctx

    (input) Zymkey context.

  • on_ms

    (input) The amount of time, in milliseconds, that the LED will stay on during a flash cycle.

  • off_ms

    (input) The amount of time, in milliseconds, that the LED will stay off during a flash cycle.

  • num_flashes

    (input) The number of on/off flash cycles to complete. If this parameter is 0, then the LED will flash indefinitely.

Returns

0 for success, less than 0 for failure.

Administrative Ops

int zkSetI2CAddr ( zkCTX ctx, int addr)

Sets the i2c address of the Zymkey (i2c versions only).

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

Parameters

  • addr

    (input) The i2c address that the Zymkey will set itself to.

Returns

0 for success, less than 0 for failure.

Time

int zkGetTime ( zkCTX ctx, uint32_t * epoch_time_sec, bool precise_time)

Get current GMT time.

This function is called to get the time directly from a Zymkey’s Real Time Clock (RTC).

Parameters

  • epoch_time_sec

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

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

Returns

0 for success, less than 0 for failure.

Accelerometer

int zkSetTapSensitivity ( zkCTX ctx, int axis, float pct)

Sets the sensitivity of tap operations.

This method permits setting the sensitivity of the tap detection feature. Each axis may be individually configured or all at once.

Parameters

  • axis

    (input) The axis to configure. This parameter should contain one of the values in the enum typedef ACCEL_AXIS_TYPE.

  • pct

    (input) The sensitivity expressed as percentage.

Returns

0 for success, less than 0 for failure.

int zkWaitForTap ( zkCTX ctx, uint32_t timeout_ms)

Wait for a tap event to be detected.

This function is called in order to wait for a tap event to occur. This function blocks the calling thread unless called with a timeout of zero.

Parameters

  • timeout_ms

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

Returns

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

int zkGetAccelerometerData ( zkCTX ctx, zkAccelAxisDataType * x, zkAccelAxisDataType * y, zkAccelAxisDataType * z)

Get current accelerometer data and tap info.

This function gets the most recent accelerometer data in units of g forces plus the tap direction per axis.

Parameters

  • x

    (output) x axis accelerometer information y (output) y axis accelerometer information z (output) z axis accelerometer information.

Returns

0 for success, less than 0 for failure.

Binding Management

int zkLockBinding ( zkCTX ctx)

Set soft binding lock.

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

Returns

0 for success, less than 0 for failure.

int zkGetCurrentBindingInfo ( zkCTX ctx, bool * binding_is_locked, bool * is_bound)

Get current binding info.

This function gets the current binding lock state as well as the current binding state. This API is only valid for devices in the HSM family.

Parameters

  • binding_is_locked

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

Returns

0 for success, less than 0 for failure.

Module Info

int zkGetModelNumberString ( zkCTX ctx, char ** model_str)

Get Zymkey model number.

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

Parameters

  • ctx

    (input) Zymkey context which was created with zkOpen.

  • model_str

    (output) A double pointer to the model string. This function allocates this string. It is the caller’s responsibility to free it.

Returns

0 for success, less than 0 for failure.

int zkGetFirmwareVersionString ( zkCTX ctx, char ** fw_ver_str)

Get Zymkey firmware version.

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

Parameters

  • ctx

    (input) Zymkey context which was created with zkOpen.

  • version_str

    (output) A double pointer to the firmware version string. This function allocates this string. It is the caller’s responsibility to free it.

Returns

0 for success, less than 0 for failure.

int zkGetSerialNumberString ( zkCTX ctx, char ** serial_num_str)

Get Zymkey serial number.

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

Parameters

  • ctx

    (input) Zymkey context which was created with zkOpen.

  • serial_num_str

    (output) A double pointer to the serial number string. This function allocates this string. It is the caller’s responsibility to free it.

Returns

0 for success, less than 0 for failure.

int zkGetCPUTemp ( zkCTX ctx, float * cpu_temp)

Get current HSM CPU temperature. (model >= HSM6).

This function gets the current HSM CPU temp.

Parameters

  • cpu_temp

    (output) The temperature in celsius of the CPU.

Returns

0 for success, less than 0 for failure.

int zkGetRTCDrift ( zkCTX ctx, float * rtc_drift)

Get current RTC drift. (model >= HSM6).

This function is called to get the current RTC drift.

Parameters

  • rtc_drift

    (output) The RTC drift.

Returns

0 for success, less than 0 for failure.

int zkGetBatteryVoltage ( zkCTX ctx, float * batt_voltage)

Get the battery voltage (model >= HSM6).

This function gets the current battery voltage.

Parameters

  • ctx

    (input) Zymkey context.

  • battV

    (output) The current battery voltage value.

Returns

0 if successful, less than 0 for failure.

Battery Voltage Monitor

int zkSetBatteryVoltageAction ( zkCTX ctx, int action)

Set battery voltage threshold action. (model >= HSM6).

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

Returns

0 for success, less than 0 for failure.

int zkSetBatteryVoltageThreshold ( zkCTX ctx, float threshold)

Sets the battery voltage threshold. (model >= HSM6).

This function sets the threshold at which if the battery voltage falls bellow, the action set by zkSetBatteryVoltageAction will be carried out. The recommended threshold is 2.3V. If this function isn’t called 2.3V is assumed by default. Threshold must be below 2.5V.

Parameters

  • threshold

    (input) The threshold in Volts.

Returns

0 for success, less than 0 for failure.

CPU Temperature Monitor

int zkSetCPUTempAction ( zkCTX ctx, int action)

Set HSM CPU temperature threshold action. (model >= HSM6).

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

Returns

0 for success, less than 0 for failure.

int zkSetCPULowTempThreshold ( zkCTX ctx, float threshold)

Sets the HSM CPU low temperature threshold. (model >= HSM6).

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.

Returns

0 for success, less than 0 for failure.

int zkSetCPUHighTempThreshold ( zkCTX ctx, float threshold)

Sets the HSM CPU high temperature threshold. (model >= HSM6).

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.