8/1/24, 11:41 PM Python API Documentation |

Python API Documentation

Python interface module to Zymkey Application Utilities Library.

Introduction
Python interface module to Zymkey Application Utilities Library.

This file contains a Python class which interfaces to the the Zymkey Application Utilities library. This class facilitates writing user space
applications which use Zymkey to perform cryptographic operations, such as:

1. Signing of payloads using ECDSA.

2. Verification of payloads that were signed using Zymkey.
3. Exporting the public key that matches Zymkey’s private key.
4. “Locking” and “unlocking” data objects.
5. Generating random data.

Additionally, there are methods for changing the i2c address (i2c units only), setting tap sensitivity, and controlling the LED.

Classes
class zymkey.Zymkey
The Zymkey class definition.

This class provides access to the Zymkey within Python.

__init__ ()

Initialize an instance of a Zymkey context.

__del__ ()

led_on ()

Turn the LED on.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

led_off ()

Turn the LED off.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

https://docs.zymbit.com/api/python_api/ 1/23
8/1/24, 11:41 PM Python API Documentation |

led_flash ( on_ms , off_ms = 0 , num_flashes = 0 )

Flash the LED.

Parameters
on_ms (int) — The amount of time in milliseconds that the LED will be on for.

off_ms (int) — The amount of time in milliseconds that the LED will be off for. If this parameter is set to 0 (default), the off
time is the same as the on time.

num_flashes (int) — The number of on/off cycles to execute. If this parameter is set to 0 (default), the LED flashes indefinitely.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

get_random ( num_bytes )

Get some random bytes.

Parameters
num_bytes (int) — The number of random bytes to get.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
bytearray — An array of bytes returned by the random number generator.

create_random_file ( file_path , num_bytes )

Deposit random data in a file.

Parameters
file_path (str) — The absolute path name for the destination file.

num_bytes (int) — The number of random bytes to get.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

lock ( src , dst = None , encryption_key = “zymkey” )

Lock up source (plaintext) data.

https://docs.zymbit.com/api/python_api/ 2/23
8/1/24, 11:41 PM Python API Documentation |

This methods encrypts and signs a block of data.

The Zymkey that can be used for locking/unlocking operations.

1. The one-way key is meant to lock up data only on the local host computer. Data encrypted using this key cannot be exported
and deciphered anywhere else.

Parameters
src (Union[str, bytes]) —
The source (plaintext) data to lock.

If a str is passed to this method, the value is assumed to be the absolute path to the location of the source file. If bytes or
bytesarray is passed, it is assumed to contain binary data.

dst (Optional[str]) —
The destination (ciphertext) of the locked data.

If a str is passed to this method, the value is assumed to be the absolute path to the location of the file where the destination
data is meant to be written. Otherwise, if None is passed to the method (the default), the locked data is returned from the
method as a bytearray.

encryption_key (str) — This specifies which key will be used to lock the data. A value of “zymbit” (default) specifies that the
Zymkey will use the one-way key.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
bytearray or None — The locked data is returned as a bytearray if no destination is specified when this method is called. Otherwise,
None is returned.

unlock ( src , dst = None , encryption_key = “zymkey” , raise_exception = True )

Unlock source (ciphertext) data.

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

The Zymkey has two keys that can be used for locking/unlocking operations.

1. The one-way key is meant to lock up data only on the local host computer. Data encrypted using this key cannot be exported
and deciphered anywhere else.

Parameters
src (Union[str, bytes]) —
The source (ciphertext) data to verify and decrypt.

If a str is passed to this method, the value is assumed to be the absolute path to the location of the source file. If bytes or
bytesarray is passed, it is assumed to contain binary data.

dst (Optional[str]) —
The destination of the decrypted data (plaintext).

If a str is passed to this method, the value is assumed to be the absolute path to the location of the file where the destination
data is meant to be written. Otherwise, if None is passed to the method (the default), the locked data is returned from the
method as a bytearray.

https://docs.zymbit.com/api/python_api/ 3/23
8/1/24, 11:41 PM Python API Documentation |

encryption_key (str) — This specifies which key will be used to lock the data. A value of “zymbit” (default) specifies that the
Zymkey will use the one-way key.

raise_exception (bool) — Specifies if an exception should be raised if the signature verification of the locked object fails.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
bytearray or None — The locked data is returned as a bytearray if no destination is specified when this method is called. Otherwise,
None is returned.

sign ( src , slot = 0 , return_recid = False , encoding = “utf-8” , digest = None )

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

Parameters
src (Union[str, bytes, bytearray]) — The SHA256 digest of the data that will be used to generate the signature.

slot (int) — The key slot used for signing. [HSM6]Slot can’t contain a X25519 key pair

return_recid (bool) — This parameter asks for the y parity to be returned.

encoding (str) — This parameter asks for the encoding for the string source.

digest (_hashlib.HASH) — This parameter asks for the type of hash. Can be None. Defaults to sha256.

Returns
—
bytearray – A bytearray of the signature.
int – If return_recid = True, then return the y parity of the signature (either a 1 or 0).

sign_digest ( digest , slot = 0 , return_recid = False )

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

Parameters
digest (_hashlib.HASH) — A encoded str instance representing the digest to be signed.

slot (int) — This parameter specifies the key slot used for signing. [HSM6]Slot can’t contain a X25519 key pair

return_recid (bool) — This parameter asks for the y parity to be returned.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns

https://docs.zymbit.com/api/python_api/ 4/23
8/1/24, 11:41 PM Python API Documentation |

—
bytearray – The signature of the SHA-256 digest passed to this method.
int – If return_recid = True, then return the y parity of the signature (either a 1 or 0).

verify (
src ,
sig ,
raise_exception = True ,
pubkey_slot = 0 ,
foreign = False ,
encoding = “utf-8” ,
digest = None
)

Verify data against a signature.

The public key is not specified in the parameter list to ensure that the public key that matches the Zymkey’s ECDSA private key is
used.

Parameters
src — The buffer to verify.

sig — The signature to verify against.

raise_exception (bool) — By default, when verification fails a VerificationError will be raised, unless this is set to False.

pubkey_slot (int) — The key slot to use to verify the signature against. Defaults to the first key slot.

foreign (bool) — If false, the normal key store is referenced. Otherwise, the foreign public key store is referenced.Note: This
parameter is only applicable for Supported Devices: HSM6, Secure Compute Module.

encoding (str) — This parameter asks for the encoding for the string source.

digest (_hashlib.HASH) — This parameter asks for the type of hash. Can be None. Defaults to sha256.

Returns
bool — Returns
True for a good verification or False for a bad verification when the raise_exception parameters is False.

verify_digest ( digest , sig , raise_exception = True , pubkey_slot = 0 , foreign = False )

Verify a signature using the Zymkey’s ECDSA public key.

The public key is not specified in the parameter list to ensure that the public key that matches the Zymkey’s ECDSA private key is
used.

Parameters
digest — A hashlib instance that will be used to generate the signature.

sig — The signature to verify.

https://docs.zymbit.com/api/python_api/ 5/23
8/1/24, 11:41 PM Python API Documentation |

raise_exception (bool) — By default, when verification fails, a VerificationError will be raised, unless this is set to False.

pubkey_slot (int) — The key slot to use to verify the signature against. Defaults to the first key slot.

foreign (bool) — If false, the normal key store is referenced. Otherwise, the foreign public key store is referenced.Note: This
parameter is only applicable for Supported Devices: HSM6, Secure Compute Module.

Returns
bool — Returns
True for a good verification or False for a bad verification when raise_exception is False.

ecdh (
local_slot ,
peer_pubkey ,
kdf_func_type = “none” ,
salt = [] ,
info = [] ,
num_iterations = 1 ,
peer_pubkey_slot_is_foreign = True ,
derived_key_size = 32
)

Derive a key or a pre-master secret from an ECDH operation. (Supported Devices: HSM6, Secure Compute Module).

Parameters
local_slot (int) — The local key slot to use.

peer_pubkey (t.Union[t.List[bytes], int]) — The public key of the peer used to generate the pre-master secret against the
private key located in local_slot. This parameter can be a list of bytes if the key is provided explicitly or an int if it refers to a key
slot.

kdf_func_type (str) —
Specifies the KDF (Key Derivation Function) to use for the returned derived key. Valid values are:

“none”: just return the pre-master secret. NOTE: The raw pre-master secret should not be used as a derived key should
be put through a suitable KDF. Use “none” when it is desired to use a different KDF than what is offered by this method.
“rfc5869-sha256”: RFC5869 with SHA256
“rfc5869-sha512”: RFC5869 with SHA512
“pbkdf2-sha256”: PBKDF2 with SHA256
“pbkdf2-sha512”: PBKDF2 with SHA512

salt (t.Optional[t.List[bytes]]) — A unique identifier for KDF. Ignored for kdf_func_type=’none’.

info (t.Optional[t.List[bytes]]) — A unique field for rfc5869. Ignore for other KDF types.

num_iterations (int) — The number of iterations that the KDF should complete.

peer_pubkey_slot_is_foreign (bool)

derived_key_size (bool)

Returns
https://docs.zymbit.com/api/python_api/ 6/23
8/1/24, 11:41 PM Python API Documentation |

bytearray — The computed signature.

create_ecdsa_public_key_file ( filename , slot = 0 )

Create a file with the PEM-formatted ECDSA public key.

[DEPRECATED]: Use create_public_key_file instead.

This method is useful for generating a Certificate Signing Request.

Parameters
filename (str) — The absolute file path where the public key will be stored in PEM format.

slot (int) — The key slot for the public key.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

create_public_key_file ( filename , slot = 0 , foreign = False )

Create a file with the PEM-formatted public key.

This method is useful for generating a Certificate Signing Request.

Parameters
filename (str) — The absolute file path where the public key will be stored in PEM format.

slot (int) — The key slot for the public key.

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

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
— 0 for success, less than 0 for failure.

get_ecdsa_public_key ( slot = 0 )

Retrieves the ECDSA public key as a binary bytearray.

[DEPRECATED]: Use get_public_key instead.

This method is used to retrieve the public key in binary form.

Parameters

https://docs.zymbit.com/api/python_api/ 7/23
8/1/24, 11:41 PM Python API Documentation |

slot (int) — The key slot for the public key.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
bytearray — The public key in binary form.

get_public_key ( slot = 0 , foreign = False )

Retrieves a public key as a binary bytearray.

This method is used to retrieve the public key in binary form.

Parameters
slot (int) — The key slot for the public key. Zymkey and HSM4 have slots 0, 1, and 2.

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

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
bytearray — The public key in binary form.

get_slot_alloc_list ( foreign = False )

Get a list of the allocated slots in the key store (Supported Devices: HSM6, Secure Compute Module).

This method gets a list of the allocated slots in the key store.

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

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
t.Tuple[list, int] — The allocation list and the maximum number of keys

store_foreign_public_key ( key_type , pubkey )

https://docs.zymbit.com/api/python_api/ 8/23
8/1/24, 11:41 PM Python API Documentation |

Stores a foreign public key on the Zymkey foreign keyring (Supported Devices: HSM6, Secure Compute Module).

This method stores a foreign public key onto the Zymkey foreign public keyring.

Parameters
key_type — The EC curve type that should be associated with the public key.

pubkey — The public key binary data.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
int — The slot allocated to the key, or less than one for failure.

disable_public_key_export ( slot = 0 , foreign = False )

Disable exporting of a public key at a given slot (Supported Devices: HSM6, Secure Compute Module).

This method permanently disables exporting a public key from a given slot.

Parameters
slot — This parameter specifies the key slot for the public key.

foreign — If true, the slot refers to the foreign public keyring.

Returns
— 0 for success, less than 0 for failure.

gen_key_pair ( key_type )

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

This method generates a new key pair of the specified type.

Parameters
key_type — This parameter indicates the EC curve type that should be associated with the new key pair.

Returns
— the slot allocated to the key or less than one for failure.

gen_ephemeral_key_pair ( key_type )

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

This method generates a new ephemeral key pair of the specified type, overwriting the previous ephemeral key pair.

https://docs.zymbit.com/api/python_api/ 9/23
8/1/24, 11:41 PM Python API Documentation |

Parameters
key_type — This parameter indicates the EC curve type that should be associated with the new key pair.

Returns
— 0 for success, less than 0 for failure.

remove_key ( slot , foreign = False )

Remove a key at the designated slot (Supported Devices: HSM6, Secure Compute Module).

This method removes a key at the designated slot in either the standard key store or the foreign public keyring.

Parameters
slot — This parameter specifies the key slot for the key.

foreign — If true, a public key in the foreign keyring will be deleted.

Returns
— 0 for success, less than 0 for failure.

invalidate_ephemeral_key ()

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

This method invalidates the ephemeral key, effectively removing it from service until a new key is generated.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
— 0 for success, less than 0 for failure.

gen_wallet_master_seed (
key_type,
master_gen_key,
wallet_name,
recovery_strategy=<zymkey.RecoveryStrategy object>
)

Generates a new master seed for creating a new BIP32 wallet (Supported Devices: HSM6, Secure Compute Module).

This method generates a new master seed for creating a new BIP32 wallet.

Parameters
key_type — This parameter indicates the EC curve type that should be associated with the new key pair.

https://docs.zymbit.com/api/python_api/ 10/23
8/1/24, 11:41 PM Python API Documentation |

master_gen_key — The master generator key (bytearray) used in the derivation of the child key.

wallet_name — The name of the wallet (string) that this master seed is attached to.

recovery_strategy — RecoveryStrategy() class that defines what strategy to be used {None, BIP39, SLIP39} are currently
supported. RecoveryStrategy->passphrase must be b64 encoded.

Returns
— the slot the master seed was generated in. 0 for starting SLIP39 sessions.

set_gen_SLIP39_group_info ( group_index , member_count , member_threshold )

Configures the number of members and threshold for the group shares (Supported Devices: HSM6, Secure Compute Module).

This method sets the number of members required for a group share once a SLIP39 session was opened via
gen_wallet_master_seed().

Parameters
group_index — This parameter indicates the index of the group share to set the amount of member count/threshold for.

member_count — The total number of members (mnemonics) in this group share.

member_threshold — The number of members (mnemonics) needed to reconstruct the group share.

Returns
— 0 on successful configuration. non-zero for error.

add_gen_SLIP39_member_pwd ( passphrase = ’’ )

Generates a new mnemonic_str tied to a SLIP39 member (Supported Devices: HSM6, Secure Compute Module).

This method generates a new member of a group share. Members can also be passphrase protected. Passphrases are not required
to be unique. This function is meant to be called after configuring a group via set_gen_SLIP39_group_info().

Parameters
passphrase — This parameter indicates the passphrase of the SLIP39 member and is associated with the mnemonic string
generated. Can be empty string for no passphrase.

Returns
— A 24-word recovery phrase known as a mnemonic sentence. non-zero for error.

cancel_SLIP39_session ()

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

This method cancels an ongoing SLIP39 session for both master seed generation and recovery.

Returns
https://docs.zymbit.com/api/python_api/ 11/23
8/1/24, 11:41 PM Python API Documentation |

— 0 on success. non-zero for error.

gen_oversight_wallet ( key_type , pub_key , chain_code , node_addr , wallet_name , variant = ’’ )

Generates a supervisory bip32 wallet. (Supported Devices: HSM6, Secure Compute Module).

This method generates a new supervisory Bip32 wallet. Meant for read-only transactions and supervising history.

Parameters
key_type — This parameter indicates the EC curve type that should be associated with the new key pair.

pub_key — The public key (bytearray) of the last hardened node of the node address.

chain_code — The chain code (bytearray) of the last hardened node of the node address.

node_addr — The bip32 node address used. (EX: “m/1852’/1815’/0’”).

wallet_name — The name of the wallet (string) that this master seed is attached to.

variant — Key type variant to generate from. Currently only “cardano” is supported for “ed25519”.

Returns
— the slot the oversight wallet was generated in.

gen_wallet_child_key ( parent_key_slot , index , hardened , return_chain_code = False )

Generates a child key based on a parent key that is in a wallet (Supported Devices: HSM6, Secure Compute Module).

This method generates a child key based on a parent key that is in a wallet.

Parameters
parent_key_slot — This parameter specifies the parent key slot. This key must already be part of a wallet.

index — This parameter represents the index for the child key derivation which becomes part of the node address.

hardened — If true, the key is a hardened key.

return_chain_code — If true, returns the chain code for the key as well. (Must be from a hardened key).

Returns
— the allocated slot on success, or a tuple containing the chain code as well.

restore_wallet_master_seed (
key_type ,
master_gen_key ,
wallet_name ,
recovery_strategy ,
mnemonics = None
https://docs.zymbit.com/api/python_api/ 12/23
8/1/24, 11:41 PM Python API Documentation |

Restore a wallet’s master seed based on the recovery strategy object (Supported Devices: HSM6, Secure Compute Module).

This method restores a wallet’s master seed based on a mnemonic string and a master generator key. This method can be used in
the process of wallet duplication.

Parameters
key_type — This parameter indicates the EC curve type that should be associated with the new key pair.

master_gen_key — The master generator key used in the derivation of the child key.

wallet_name — Name of the new wallet to be generated.

recovery_strategy — RecoveryStategy class object that provides the type of recovery and key variant required for
restoration.

mnemonics — Mnemonic sentences required for restoration, number of mnemonics dependant on recovery strategy used.
This field is not used for SLIP39.

Returns
— the allocated slot on success

add_restore_SLIP39_mnemonic ( mnemonic_sentence , passphrase = ’’ )

Feed a mnemonic string and the passphrase associated with it (Supported Devices: HSM6, Secure Compute Module).

This method feeds in mnemonic sentences (shards) into the module. Meant to be called after starting a
restore_wallet_master_seed() SLIP39 session. Will return -1 until the master seed is reconstructed properly.

Parameters
mnemonic_sentence — 24-word recovery phrase associated with the SLIP39 member.

passphrase — This parameter indicates the passphrase of the SLIP39 member and is associated with the mnemonic string
generated. Can be empty string for no passphrase.

Returns
— A -1 for no change in status. Otherwise returns the slot of the master seed successfully reconstructed from the last shard passed
in.

get_wallet_node_addr ( slot )

Get a wallet node address from a key slot (Supported Devices: HSM6, Secure Compute Module).

This method gets a wallet entry’s node address from its key slot assignment. The wallet name and master seed slot are also
returned.

Parameters
slot — The key slot assignment.

Returns
https://docs.zymbit.com/api/python_api/ 13/23
8/1/24, 11:41 PM Python API Documentation |

— the node address, wallet name and master seed key slot.

get_wallet_key_slot ( node_addr , wallet_name = None , master_seed_slot = None )

Look up a wallet key slot number from a node address (Supported Devices: HSM6, Secure Compute Module).

This method gets a wallet key slot number from its node address and wallet name or master seed key slot. Either the wallet name or
the master seed slot must be present.

Parameters
node_addr — The desired node address to look up

wallet_name — The name of the wallet that the node address belongs to. Either this parameter or master_seed_slot must be
specified or this function will fail.

master_seed_slot — The master seed slot that the node address belongs to. Either this parameter or wallet_name must be
specified or this function will fail.

Returns
— the key slot.

set_i2c_address ( address )

Set the i2c address of the Zymkey.

Note: This is only applicable to versions of the Zymkey with i2c.

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 reboot itself.

Parameters
address (int) — The i2c address that the Zymkey will set itself to.

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

Returns
— 0 for success, less than 0 for failure.

set_tap_sensitivity ( axis = “all” , pct = 50.0 )

Set 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/python_api/ 14/23
8/1/24, 11:41 PM Python API Documentation |

axis — The axis to configure. Valid values include:

1. ’all’: Configure all axes with the specified sensitivity value.
2. ’x’ or “X”: Configure only the x-axis.
3. ’y’ or “Y”: Configure only the y-axis.
4. ’z’ or “Z”: Configure only the z-axis.

pct — The sensitivity expressed as percentage.

1. 0% = Shut down: Tap detection should not occur along the axis.
2. 100% = Maximum sensitivity.

Returns
— 0 for success, less than 0 for failure.

wait_for_tap ( timeout_ms = -1 )

Wait for tap event.

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 — The maximum amount of time in milliseconds to wait for a tap event to arrive.

class ZymkeyAccelAxisData ( g_force, tap_dir)

__init__ ( g_force , tap_dir )

Initialize self. See help(type(self)) for accurate signature.

get_accelerometer_data ()

Get current accelerometer data and tap info.

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

Returns
An array of accelerometer readings in units of g-force.
array index 0 = x axis – 1 = y axis 2 = z axis
A value of -1 indicates that the tap event was detected in a
negative direction for the axis, +1 for a positive direction
and 0 for stationary.

get_time ( precise = False )

Get current GMT time.

https://docs.zymbit.com/api/python_api/ 15/23
8/1/24, 11:41 PM Python API Documentation |

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

Parameters
precise — 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
Time in epoch seconds —

lock_binding ()

Set soft binding lock.

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

Exceptions
AssertionError If ret is a bad return code from the Zymkey library function.

get_current_binding_info ()

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.

Returns
binding_is_locked – Binary value which expresses the current binding lock state.
is_bound – Binary value which expresses the current bind state.

set_perimeter_event_actions ( channel , action_notify = True , action_self_destruct = False )

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 — The channel (0 or 1) that the action flags will be applied to

action_notify — Set a perimeter breach to notify. (default = True)

action_self_destruct — Set a perimeter breach to self destruct. (default = False)

Returns
— 0 for success, less than 0 for failure.

https://docs.zymbit.com/api/python_api/ 16/23
8/1/24, 11:41 PM Python API Documentation |

set_digital_perimeter_lp_period ( lp_period )

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

This function sets the digital perimeter detect low power period (microseconds).

Parameters
lp_period — The perimeter detect low power period in microseconds.

Returns
— 0 for success, less than 0 for failure.

set_digital_perimeter_lp_max_bits ( max_num_bits )

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

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

Parameters
max_num_bits — The perimeter detect low power max number of bits

Returns
— 0 for success, less than 0 for failure.

set_digital_perimeter_delays ( min_delay_ns , max_delay_ns )

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

This function sets the digital perimeter detect delay values.

Parameters
min_delay_ns — The minimum delay in nanoseconds.

max_delay_ns — The maximum delay in nanoseconds.

Returns
— 0 for success, less than 0 for failure.

wait_for_perimeter_event ( timeout_ms = -1 )

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.

Parameters

https://docs.zymbit.com/api/python_api/ 17/23
8/1/24, 11:41 PM Python API Documentation |

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

Returns
— 0 for success, less than 0 for failure.

get_perimeter_detect_info ()

Get current perimeter detect info.

This function gets the timestamp of the first perimeter detect event for the given channel. The index corresponds to the channel
specified in set_perimeter_event_actions.

Returns
— The array of timestamps for each channel for the first detected event in epoch seconds

clear_perimeter_detect_info ()

Clear perimeter detect info.

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

Returns
— 0 for success, less than 0 for failure.

get_cpu_temp ()

Get current CPU temperature (Supported Devices: HSM6, Secure Compute Module).

This function gets the current HSM CPU temperature.

Returns
— The CPU temperature in celsius as a float

get_aux_temp ( index = 0 )

Get current aux temperature (Secure Compute Modules only).

THIS FUNCTION IS FOR INTERNAL ZYMBIT USE ONLY.

This function gets the current aux temperature. (defaults to 0).

Parameters
index — (input) The index id of the processor.

Returns
— The temperature in celsius as a float

https://docs.zymbit.com/api/python_api/ 18/23
8/1/24, 11:41 PM Python API Documentation |

get_rtc_drift ()

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

This function gets the current RTC drift.

Returns
— The RTC drift as a float

get_batt_volt ()

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

This function gets the current battery voltage.

Returns
— The battery voltage as a float

get_model_number ()

Get Zymkey model number.

This function gets the Zymkey model number.

Returns
— The model number as a string.

get_firmware_version ()

Get Zymkey firmware version.

This function gets the Zymkey firmware version.

Returns
— The firmware version as a string.

get_serial_number ()

Get Zymkey serial number.

This function gets the Zymkey serial number.

Returns
— The serial number as a string.

https://docs.zymbit.com/api/python_api/ 19/23
8/1/24, 11:41 PM Python API Documentation |

set_battery_voltage_action ( sleep = False , self_destruct = False )

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

This function specifies the action to take when the battery voltage falls below the threshold set by set_battery_voltage_threshold. 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.

With sleep and self_destruct set to False, it removes a previously set sleep or self_destruct action.

Parameters
sleep — Set the sleep action.

self_destruct — Set the self_destruct action.

Returns
— 0 for success, less than 0 for failure.

set_battery_voltage_threshold ( 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 set_battery_voltage_action will be
carried out. The recommended threshold is 2.3V is assumed by default. Threshold must be below 2.5V.

Parameters
threshold — The threshold in Volts.

Returns
— 0 for success, less than 0 for failure.

set_cpu_temp_action ( self_destruct = False )

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
set_cpu_low_temp_threshold, or rises above the threshold set by set_cpu_high_temp_threshold. There are two actions to apply:

Do nothing.
Self-destruct.

To remove a previously set self-destruct action, call this function with self_destruct=False.

Parameters
self_destruct — Set the self_destruct action.

Returns
https://docs.zymbit.com/api/python_api/ 20/23
8/1/24, 11:41 PM Python API Documentation |

— 0 for success, less than 0 for failure.

set_cpu_low_temp_threshold ( 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 set_cpu_temp_action
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 this function is never called, -10 degrees celsius is assumed.

Parameters
threshold — The threshold in celsius.

Returns
— 0 for success, less than 0 for failure.

set_cpu_high_temp_threshold ( 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 set_cpu_temp_action
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 this function is never called, 65 degrees celsius is assumed.

Parameters
threshold — The threshold in celsius.

Returns
— 0 for success, less than 0 for failure.

set_supervised_boot_policy ( policy_id = 0 )

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

This function sets the action policy to take when Supervised boot detects a file change during the boot process.

Parameters
policy_id (int) — The actions to apply to the Supervised boot process: - 0 Do Nothing - 1 Self-Destruct - 2 Hold Chip in Reset

Returns
— 0 for success, less than 0 for failure.

add_or_update_supervised_boot_file ( filepath = ’’ , slot = 15 )

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

https://docs.zymbit.com/api/python_api/ 21/23
8/1/24, 11:41 PM Python API Documentation |

This function adds or updates a file in the file manifest to be checked by Supervised during the boot process.

Parameters
slot (int) — The slot to sign the file with.

filepath (str) — The file to be signed and checked by Supervised boot.

Returns
— 0 for success, less than 0 for failure.

remove_supervised_boot_file ( filepath = ’’ )

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

This function removes a file in the file manifest to be checked by Supervised boot during the boot process.

Parameters
filepath (str) — The file to be removed from the manifest.

Returns
— 0 for success, less than 0 for failure.

get_supervised_boot_file_manifest ()

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

This function gets a list of the files that are checked by Supervised boot during the boot process.

Returns
TYPE – 0 for success, less than 0 for failure.
TYPE – File manifest to be checked by Supervised boot.

class zymkey.RecoveryStrategy ( variant = ’’)

The RecoveryStrategy class definition.

This class specifies the recovery strategy used for wallet generation within Python. Base class strategy is to do no recovery.

__init__ ( variant = ’’ )

Initialize an instance of RecoveryStrategy.

Parameters
variant — Variant of the key type. Currently only “cardano” for ed25519 is supported.

class zymkey.RecoveryStrategyBIP39 ( variant = ’’, passphrase = ’’)

The RecoveryStrategyBIP39 class definition.
https://docs.zymbit.com/api/python_api/ 22/23
8/1/24, 11:41 PM Python API Documentation |

This class specifies the BIP39 recovery strategy used for wallet generation within Python. Derived from RecoveryStrategy class.

__init__ ( variant = ’’ , passphrase = ’’ )

Initialize an instance of RecoveryStrategyBIP39.

Parameters
variant — Variant of the key type. Currently only “cardano” for ed25519 is supported.

passphrase — Passphrase used for BIP39 generation. Can be empty string. Must be b64 encoded.

class zymkey.RecoveryStrategySLIP39 ( group_count, group_threshold, iteration_exponent,

variant = ’’, passphrase = ’’)
The RecoveryStrategySLIP39 class definition.

This class specifies the SLIP39 recovery strategy used for wallet generation within Python. Derived from RecoveryStrategy class.

__init__ ( group_count , group_threshold , iteration_exponent , variant = ’’ , passphrase = ’’ )

Initialize an instance of RecoveryStrategySLIP39.

Parameters
group_count — Total number of group shares to generate [Max: 14 Groups].

group_threshold — Number of groups needed to restore a master seed with [threshold <= group_count].

iteration_exponent — The higher the exponent the more PBKDF2 hashing is done. [Exponent: 0-5]

variant — Variant of the key type. Currently only “cardano” for ed25519 is supported.

passphrase — Passphrase used for BIP39 generation. Can be empty string. Must be b64 encoded.

https://docs.zymbit.com/api/python_api/ 23/23