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.

EPHEMERAL_KEY_SLOT = -1

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

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.

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.

  • 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
—
  • 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.
  • 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) — TODO_DESCRIPTION
  • derived_key_size (bool) — TODO_DESCRIPTION
Returns
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
TYPE — 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
  • 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)

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
TYPE — 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
TYPE — 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.

Parameters
  • key_type — This parameter indicates the EC curve type that should be associated with the new key pair.
Returns
TYPE — 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
TYPE — 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
TYPE — 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.
  • 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
TYPE — 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
TYPE — 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
TYPE — 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
TYPE — 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
TYPE — 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
TYPE — 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)

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

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
TYPE — 0 for success, less than 0 for failure.

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
TYPE — 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
TYPE — 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
TYPE — 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
  • timeout_ms — (input) The maximum amount of time in milliseconds to wait for a perimeter breach event to arrive.
Returns
TYPE — 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
TYPE — 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
TYPE — 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
TYPE — 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
TYPE — The temperature in celsius as a float

get_rtc_drift ()

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

This function gets the current RTC drift.

Returns
TYPE — 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
TYPE — The battery voltage as a float

get_model_number ()

Get Zymkey model number.

This function gets the Zymkey model number.

Returns
TYPE — The model number as a string.

get_firmware_version ()

Get Zymkey firmware version.

This function gets the Zymkey firmware version.

Returns
TYPE — The firmware version as a string.

get_serial_number ()

Get Zymkey serial number.

This function gets the Zymkey serial number.

Returns
TYPE — The serial number as a string.

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

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
TYPE — 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
TYPE — 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.

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.