8/1/24, 11:40 PM C API Documentation |

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_TYPE ZK_EC_KEY_TYPE

Supported key types.

typedef enum ZK_RECOVERY_STRATEGY ZK_RECOVERY_STRATEGY

Supported recovery strategies.

typedef enum ZK_ECDH_KDF_TYPE ZK_ECDH_KDF_TYPE

Supported ECDH key derivation function types.

typedef enum ZK_ACCEL_AXIS_TYPE ZK_ACCEL_AXIS_TYPE

Accelerometer axis enum, used to set tap sensitivity.

typedef enum ZK_THRESHOLD_ACTION_TYPE ZK_THRESHOLD_ACTION_TYPE

Possible actions for threshold monitor functions.

typedef struct zkAccelAxisDataType zkAccelAxisDataType

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

https://docs.zymbit.com/api/c_api/ 1/40
8/1/24, 11:40 PM C API Documentation |

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
https://docs.zymbit.com/api/c_api/ 2/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 3/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 4/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 5/40
8/1/24, 11:40 PM C API Documentation |

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
https://docs.zymbit.com/api/c_api/ 6/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 7/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 8/40
8/1/24, 11:40 PM C API Documentation |

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.
https://docs.zymbit.com/api/c_api/ 9/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 10/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 11/40
8/1/24, 11:40 PM C API Documentation |

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. (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
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. (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
https://docs.zymbit.com/api/c_api/ 12/40
8/1/24, 11:40 PM C API Documentation |

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

https://docs.zymbit.com/api/c_api/ 13/40
8/1/24, 11:40 PM C API Documentation |

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

https://docs.zymbit.com/api/c_api/ 14/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 15/40
8/1/24, 11:40 PM C API Documentation |

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. (Supported Devices: HSM6, Secure Compute
Module).

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
https://docs.zymbit.com/api/c_api/ 16/40
8/1/24, 11:40 PM C API Documentation |

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 (Supported Devices: HSM6, Secure Compute
Module).

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 (Supported Devices: HSM6, Secure Compute Module).

This function returns a list of all allocated key slots.

Parameters
ctx —
(input) Zymkey context.
https://docs.zymbit.com/api/c_api/ 17/40
8/1/24, 11:40 PM C API Documentation |

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. (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
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. (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
ctx —
(input) Zymkey context.

https://docs.zymbit.com/api/c_api/ 18/40
8/1/24, 11:40 PM C API Documentation |

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. (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
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. (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
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. (Supported Devices: HSM6, Secure Compute Module).

https://docs.zymbit.com/api/c_api/ 19/40
8/1/24, 11:40 PM C API Documentation |

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. (Supported Devices: HSM6, Secure Compute Module).

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

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

Parameters

https://docs.zymbit.com/api/c_api/ 20/40
8/1/24, 11:40 PM C API Documentation |

ctx —
(input) Zymkey context.

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

variant —
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.

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.

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

mnemonic —
(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
allocated slot number if successful, less than 0 for failure.

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
)

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

This function opens a session to generate a new blockchain master seed with the ability to recover from SLIP39 shards.

Parameters
ctx —
(input) Zymkey context.

https://docs.zymbit.com/api/c_api/ 21/40
8/1/24, 11:40 PM C API Documentation |

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

variant —
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.

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.

group_count —
(input) The total count of groups(shards) to split into.

group_threshold —
(input) The count of groups(shards) needed to restore the master seed.

group_iteration_exponent —
(input) The iteration of exponent of SLIP39.

master_passphrase —
(input) The master passphrase used for slip 39 recovery process.

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

int zkSetSLIP39GroupInfo ( zkCTX ctx , 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
ctx —
(input) Zymkey context.

group_index —
(input) The index of the group to generate shards from. Index starts at 0.

member_count —
(input) The total amount of member shards in this group to generate.

member_threshold —
(input) The number of member shards needed to recreate this group in recovery.

Returns
https://docs.zymbit.com/api/c_api/ 22/40
8/1/24, 11:40 PM C API Documentation |

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

int zkAddSLIP39MemberPassword ( zkCTX ctx , const char * passhrase , char ** mnemonic_sentence )

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
ctx —
(input) Zymkey context.

passhrase —
(input) Password for the shard. Can be empty string.

mnemonic_sentence —
(output) The mnemonic sentence of the shard.

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

int zkCancelSLIP39Session ( zkCTX ctx )

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.

Parameters
ctx —
(input) Zymkey context.

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

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
)

Generate master seed to start a new blockchain wallet. (Supported Devices: HSM6, Secure Compute Module).
https://docs.zymbit.com/api/c_api/ 23/40
8/1/24, 11:40 PM C API Documentation |

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

pub_key —
(input) The public key to create the oversight wallet from. Should come from a hardened node in a node tree.

chain_code —
(input) The chain code of the public key being used to create the oversight wallet.

node_addr —
(input) The node address index of the public key being used.

wallet_name —
(input) The name of the oversight wallet being created.

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 ,
bool return_chain_code ,
uint8_t ** chain_code
)

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

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.

https://docs.zymbit.com/api/c_api/ 24/40
8/1/24, 11:40 PM C API Documentation |

return_chain_code —
(input) If true, returns the chain code of the public key that was just generated. Has to be a hardened node as well.

chain_code —
(output) the chain code of the public key.

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

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
)

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
ctx —
(input) Zymkey context.

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

variant —
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.

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
https://docs.zymbit.com/api/c_api/ 25/40
8/1/24, 11:40 PM C API Documentation |

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

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
)

Open a SLIP39 restore master seed session (Supported Devices: HSM6, Secure Compute Module).

This function starts a restore SLIP39 session, in order to start feeding shards into.

Parameters
ctx —
(input) Zymkey context.

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

variant —
(input) The variant of the key_type to generate. Currently only “cardano” is supported for ed25519.

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.

SLIP39_passphrase —
(input) The master passphrase.

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

int zkAddRestoreSLIP39Mnemonic (
zkCTX ctx ,
const char * passphrase ,
const char * mnemonic_sentence
)

Feed a SLIP39 shard to restore a master seed (Supported Devices: HSM6, Secure Compute Module).
https://docs.zymbit.com/api/c_api/ 26/40
8/1/24, 11:40 PM C API Documentation |

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

Parameters
ctx —
(input) Zymkey context.

passphrase —
(input) The passphrase that was attached to the shard.

mnemonic_sentence —
(input) 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 zkGetWalletNodeAddrFromKeySlot (
zkCTX ctx ,
int slot ,
char ** node_addr ,
char ** wallet_name ,
int * master_seed_slot
)

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
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 ,
https://docs.zymbit.com/api/c_api/ 27/40
8/1/24, 11:40 PM C API Documentation |

const char * node_addr ,

const char * wallet_name ,
int master_seed_slot ,
int * 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
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
https://docs.zymbit.com/api/c_api/ 28/40
8/1/24, 11:40 PM C API Documentation |

0 for success, less than 0 for failure.

int zkSetDigitalPerimeterDetectLPPeriod ( zkCTX ctx , 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
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 (Supported Devices: HSM6, Secure Compute Module).

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 (Supported Devices: HSM6, Secure Compute Module).

This function sets delays on the digital perimeter detect.

Parameters
ctx —
(input) Zymkey context.

min_delay_ns —
(input) minimum delay in nanoseconds.

https://docs.zymbit.com/api/c_api/ 29/40
8/1/24, 11:40 PM C API Documentation |

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.
https://docs.zymbit.com/api/c_api/ 30/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 31/40
8/1/24, 11:40 PM C API Documentation |

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
https://docs.zymbit.com/api/c_api/ 32/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 33/40
8/1/24, 11:40 PM C API Documentation |

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.

https://docs.zymbit.com/api/c_api/ 34/40
8/1/24, 11:40 PM C API Documentation |

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. (Supported Devices: HSM6, Secure Compute Module).

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.

https://docs.zymbit.com/api/c_api/ 35/40
8/1/24, 11:40 PM C API Documentation |

int zkGetAUXTemp ( zkCTX ctx , int index , float * aux_temp )

Get current AUX temperature. (Only for secure compute modules).

This function gets an aux temp. THIS FUNCTION IS FOR INTERNAL ZYMBIT USE ONLY.

Parameters
ctx —
(input) Zymkey context.

index —
(input) Index for which aux temp to be polled.

aux_temp —
(output) The temperature in celsius.

Returns
0 for success, less than 0 for failure.

int zkGetRTCDrift ( zkCTX ctx , float * rtc_drift )

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

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 (Supported Devices: HSM6, Secure Compute Module).

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.

https://docs.zymbit.com/api/c_api/ 36/40
8/1/24, 11:40 PM C API Documentation |

Battery Voltage Monitor

int zkSetBatteryVoltageAction ( zkCTX ctx , int 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).

Returns
0 for success, less than 0 for failure.

int zkSetBatteryVoltageThreshold ( zkCTX ctx , 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. 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. (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.
https://docs.zymbit.com/api/c_api/ 37/40
8/1/24, 11:40 PM C API Documentation |

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

Returns
0 for success, less than 0 for failure.

int zkSetCPUHighTempThreshold ( zkCTX ctx , 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.

int zkSetSupervisedBootPolicy ( zkCTX ctx , 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.

https://docs.zymbit.com/api/c_api/ 38/40
8/1/24, 11:40 PM C API Documentation |

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.

int zkAddOrUpdateSupervisedBootFile ( zkCTX ctx , const char * file_path , int slot )

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.

Returns
0 for success, less than 0 for failure.

int zkRemoveSupervisedBootFile ( zkCTX ctx , const char * 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.

int zkGetSupervisedBootFileManifest ( zkCTX ctx , char ** manifest )

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
https://docs.zymbit.com/api/c_api/ 39/40
8/1/24, 11:40 PM C API Documentation |

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

Returns
0 for success, less than 0 for failure.

https://docs.zymbit.com/api/c_api/ 40/40