Python API Documentation

Python interface module to Zymkey Application Utilities Library.

Generated from zkapputilslib version 1.2.2-1 (commit a547582).

This file contains a Python class which interfaces to the the Zymkey Application Utilities library. Systems intending to run such applications require that the python3-zku package be installed.

This class facilitates writing userspace 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

Zymkey class

class Zymkey()

Inherits from object.

The Zymkey class definition.
This class provides access to the Zymkey within Python.

Attributes

EPHEMERAL_KEY_SLOT attribute
EPHEMERAL_KEY_SLOT = -1

Methods

__init__ method
def __init__()
Initialize an instance of a Zymkey context.
led_on method
def led_on() -> None
Turn the LED on.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
led_off method
def led_off() -> None
Turn the LED off.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
led_flash method
def led_flash(on_ms: int, off_ms: int = 0, num_flashes: int = 0) -> None
Flash the LED.
Parameters
on_ms int
The amount of time in milliseconds that the LED will be on for.
off_ms int default 0
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 default 0
The number of on/off cycles to execute. If this parameter is set to 0 (default), the LED flashes indefinitely.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_random method
def get_random(num_bytes: int) -> bytearray
Get some random bytes.
Parameters
num_bytes int
The number of random bytes to get.
Returns
bytearray
An array of bytes returned by the random number generator.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
create_random_file method
def create_random_file(file_path: str, num_bytes: int) -> None
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
lock method
def lock(src: t.Union[str, bytes], dst: t.Optional[str] = None, encryption_key: str = ZYMKEY_ENCRYPTION_KEY) -> t.Union[None, bytearray]
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 t.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 t.Optional[str] default None

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 default ZYMKEY_ENCRYPTION_KEY
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.
Returns
t.Union[None, bytearray]
The locked data is returned as a bytearray if no destination is specified when this method is called. Otherwise, None is returned.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
unlock method
def unlock(src: t.Union[str, bytes], dst: t.Optional[str] = None, encryption_key: str = ZYMKEY_ENCRYPTION_KEY, raise_exception: bool = True) -> t.Union[None, bytearray, t.NoReturn]
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 t.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 t.Optional[str] default None

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 default ZYMKEY_ENCRYPTION_KEY
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 default True
Specifies if an exception should be raised if the signature verification of the locked object fails.
Returns
t.Union[None, bytearray, t.NoReturn]
The locked data is returned as a bytearray if no destination is specified when this method is called. Otherwise, None is returned.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
sign method
def sign(src: t.Union[str, bytes, bytearray], slot: int = 0, return_recid: bool = False, encoding: str = 'utf-8', digest: t.Any = None) -> bytearray
Generate a signature using the Zymkey’s ECDSA private key.
Todo: Allow for overloading of source parameter in similar fashion to lock/unlock.
Parameters
src t.Union[str, bytes, bytearray]
The SHA256 digest of the data that will be used to generate the signature.
slot int default 0
The key slot used for signing. [ZYMKEY5, HSM60, HSM64, HSM6] Slot can’t contain a X25519 key pair
return_recid bool default False
This parameter asks for the y parity to be returned.
encoding str default 'utf-8'
This parameter asks for the encoding for the string source.
digest _hashlib.HASH default None
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 method
def sign_digest(digest: t.Any, slot: int = 0, return_recid: bool = False) -> bytearray
Generate a signature using the Zymkey’s ECDSA private key.
Todo: Allow for overloading of source parameter in similar fashion to lock/unlockData.
Parameters
digest _hashlib.HASH
A encoded str instance representing the digest to be signed.
slot int default 0
This parameter specifies the key slot used for signing. [ZYMKEY5, HSM60, HSM64, HSM6] Slot can’t contain a X25519 key pair
return_recid bool default False
This parameter asks for the y parity to be returned.
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).
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
verify method
def verify(src: t.Union[str, bytes, bytearray], sig: bytearray, raise_exception: bool = True, pubkey_slot: int = 0, foreign: bool = False, encoding: str = 'utf-8', digest: t.Any = None) -> bool
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 t.Union[str, bytes, bytearray]
The buffer to verify.
sig bytearray
The signature to verify against.
raise_exception bool default True
By default, when verification fails a VerificationError will be raised, unless this is set to False.
pubkey_slot int default 0
The key slot to use to verify the signature against. Defaults to the first key slot.
foreign bool default False
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: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module.
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
encoding str default 'utf-8'
This parameter asks for the encoding for the string source.
digest _hashlib.HASH default None
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 method
def verify_digest(digest: t.Any, sig: bytearray, raise_exception: bool = True, pubkey_slot: int = 0, foreign: bool = False) -> bool
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 _hashlib.HASH
A hashlib instance that will be used to generate the signature.
sig bytearray
The signature to verify.
raise_exception bool default True
By default, when verification fails, a VerificationError will be raised, unless this is set to False.
pubkey_slot int default 0
The key slot to use to verify the signature against. Defaults to the first key slot.
foreign bool default False
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: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module.
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Returns
bool
Returns True for a good verification or False for a bad verification when raise_exception is False.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
ecdh method
def ecdh(local_slot: int, peer_pubkey: t.Union[t.List[bytes], int], kdf_func_type: str = 'none', salt: t.Optional[t.List[bytes]] = [], info: t.Optional[t.List[bytes]] = [], num_iterations: int = 1, peer_pubkey_slot_is_foreign: bool = True, derived_key_size: bool = 32) -> bytearray
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Derive a key or a pre-master secret from an ECDH operation.
Todo: Allow for overloading of source parameter in similar fashion to lock/unlockData.
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 default 'none'

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]] default []
A unique identifier for KDF. Ignored for kdf_func_type='none'.
info t.Optional[t.List[bytes]] default []
A unique field for rfc5869. Ignore for other KDF types.
num_iterations int default 1
The number of iterations that the KDF should complete.
peer_pubkey_slot_is_foreign bool default True
TODO_DESCRIPTION
derived_key_size bool default 32
TODO_DESCRIPTION
Returns
bytearray
The computed signature.
create_ecdsa_public_key_file method
def create_ecdsa_public_key_file(filename: str, slot: int = 0) -> None
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 default 0
The key slot for the public key.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
create_public_key_file method
def create_public_key_file(filename: str, slot: int = 0, foreign: bool = False) -> None
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 default 0
The key slot for the public key.
foreign bool default False
If True, designates the pubkey slot to come from the foreign keystore (Supported Devices: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module).
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_ecdsa_public_key method
def get_ecdsa_public_key(slot: int = 0) -> bytearray
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 default 0
The key slot for the public key.
Returns
bytearray
The public key in binary form.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_public_key method
def get_public_key(slot: int = 0, foreign: bool = False)
Retrieves a public key as a binary bytearray.
This method is used to retrieve the public key in binary form.
Parameters
slot int default 0
The key slot for the public key. Zymkey and HSM4 have slots 0, 1, and 2.
foreign bool default False
If True, designates the pubkey slot to come from the foreign keystore (Supported Devices: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module).
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Returns
bytearray
The public key in binary form.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_slot_alloc_list method
def get_slot_alloc_list(foreign: bool = False) -> t.Tuple[list, int]
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get a list of the allocated slots in the key store.
This method gets a list of the allocated slots in the key store.
Parameters
foreign bool default False
If True, designates the pubkey slot to come from the foreign keystore (Supported Devices: ZYMKEY5, HSM60, HSM64, HSM6, Secure Compute Module).
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Returns
t.Tuple[list, int]
The allocation list and the maximum number of keys
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
store_foreign_public_key method
def store_foreign_public_key(key_type: str, pubkey: bytearray) -> int
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Stores a foreign public key on the Zymkey foreign keyring.
This method stores a foreign public key onto the Zymkey foreign public keyring.
Parameters
key_type str
The EC curve type that should be associated with the public key.
pubkey bytearray
The public key binary data.
Returns
int
The slot allocated to the key, or less than one for failure.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
disable_public_key_export method
def disable_public_key_export(slot=0, foreign=False)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Disable exporting of a public key at a given slot.
This method permanently disables exporting a public key from a given slot.
Parameters
slot default 0
This parameter specifies the key slot for the public key.
foreign default False
If true, the slot refers to the foreign public keyring.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
gen_key_pair method
def gen_key_pair(key_type)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate a new key pair.
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
int
The slot the new key pair was allocated to.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
gen_ephemeral_key_pair method
def gen_ephemeral_key_pair(key_type)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generate a new ephemeral key pair.
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
remove_key method
def remove_key(slot, foreign=False)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Remove a key at the designated slot.
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 default False
If true, a public key in the foreign keyring will be deleted.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
invalidate_ephemeral_key method
def invalidate_ephemeral_key() -> int
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Invalidate the ephemeral key.
This method invalidates the ephemeral key, effectively removing it from service until a new key is generated.
Returns
int
0 for success.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
gen_wallet_master_seed method
def gen_wallet_master_seed(key_type, master_gen_key, wallet_name, recovery_strategy=RecoveryStrategy())
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generates a new master seed for creating a new BIP32 wallet.
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 default RecoveryStrategy()
RecoveryStrategy() class that defines what strategy to be used {None, BIP39, SLIP39} are currently supported. RecoveryStrategy->passphrase must be b64 encoded.
Returns
int or tuple of (int, str)
The slot the master seed was generated in. With a BIP39 recovery strategy, a tuple of that slot and the BIP39 mnemonic sentence. 0 for starting SLIP39 sessions.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_gen_SLIP39_group_info method
def set_gen_SLIP39_group_info(group_index, member_count, member_threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Configures the number of members and threshold for the group shares.
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
add_gen_SLIP39_member_pwd method
def add_gen_SLIP39_member_pwd(passphrase='')
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generates a new mnemonic_str tied to a SLIP39 member.
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 default ''
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
tuple of (int, str)
The return code from the Zymkey library, and the member’s 24-word recovery phrase (mnemonic sentence).
Raises
AssertionError
If the library returned no mnemonic sentence.
cancel_SLIP39_session method
def cancel_SLIP39_session()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Cancels an active SLIP39 session.
This method cancels an ongoing SLIP39 session for both master seed generation and recovery.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
gen_oversight_wallet method
def gen_oversight_wallet(key_type, pub_key, chain_code, node_addr, wallet_name, variant='')
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generates a supervisory bip32 wallet.
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 default ''
Key type variant to generate from. Currently only “cardano” is supported for “ed25519”.
Returns
int
the slot the oversight wallet was generated in.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
gen_wallet_child_key method
def gen_wallet_child_key(parent_key_slot, index, hardened, return_chain_code=False)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Generates a child key based on a parent key that is in a wallet.
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 default False
If true, returns the chain code for the key as well. (Must be from a hardened key).
Returns
int or tuple of (int, bytearray)
The allocated slot. If return_chain_code is true, a tuple of the slot and the 32-byte chain code.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
restore_wallet_master_seed method
def restore_wallet_master_seed(key_type, master_gen_key, wallet_name, recovery_strategy, mnemonics=None)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Restore a wallet’s master seed based on the recovery strategy object.
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 default None
Mnemonic sentences required for restoration, number of mnemonics dependant on recovery strategy used. This field is not used for SLIP39.
Returns
int
the allocated slot on success
Raises
AssertionError
If ret is a bad return code from the Zymkey library function (BIP39), if mnemonics is not given for BIP39, or if the recovery strategy is not BIP39 or SLIP39.
add_restore_SLIP39_mnemonic method
def add_restore_SLIP39_mnemonic(mnemonic_sentence, passphrase='')
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Feed a mnemonic string and the passphrase associated with it.
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 default ''
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
int
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 method
def get_wallet_node_addr(slot)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get a wallet node address from a key slot
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
tuple of (str, str, int)
the node address, wallet name and master seed key slot.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_wallet_key_slot method
def get_wallet_key_slot(node_addr, wallet_name=None, master_seed_slot=None)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Look up a wallet key slot number from a node address
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 default None
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 default None
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
int
the key slot.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_i2c_address method
def set_i2c_address(address: int) -> None
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_tap_sensitivity method
def 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 default 'all'

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 default 50.0

The sensitivity expressed as percentage.

  1. 0% = Shut down: Tap detection should not occur along the axis.
  2. 100% = Maximum sensitivity.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
wait_for_tap method
def 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 default -1
The maximum amount of time in milliseconds to wait for a tap event to arrive.
get_accelerometer_data method
def 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 method
def 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 default False
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 method
def lock_binding()
Set soft binding lock.
This function locks the binding for a specific HSM. This API is only valid for HSM series products.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_current_binding_info method
def 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 method
def 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 default True
Set a perimeter breach to notify. (default = True)
action_self_destruct default False
Set a perimeter breach to self destruct. (default = False)
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_digital_perimeter_lp_period method
def set_digital_perimeter_lp_period(lp_period)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set the digital perimeter detect low power period.
This function sets the digital perimeter detect low power period (microseconds).
Parameters
lp_period
The perimeter detect low power period in microseconds.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_digital_perimeter_lp_max_bits method
def set_digital_perimeter_lp_max_bits(max_num_bits)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set the low power max number of bits.
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
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_digital_perimeter_delays method
def set_digital_perimeter_delays(min_delay_ns, max_delay_ns)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set the digital perimeter detect delays.
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
wait_for_perimeter_event method
def 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 default -1
(input) The maximum amount of time in milliseconds to wait for a perimeter breach event to arrive.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
ZymkeyTimeoutError
If no perimeter event arrives within timeout_ms.
get_perimeter_detect_info method
def 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
list of int
The array of timestamps for each channel for the first detected event in epoch seconds
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
clear_perimeter_detect_info method
def clear_perimeter_detect_info()
Clear perimeter detect info.
This function clears all perimeter detect info and rearms all perimeter detect channels
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_cpu_temp method
def get_cpu_temp()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get current CPU temperature.
This function gets the current HSM CPU temperature.
Returns
float
The CPU temperature in celsius as a float
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_aux_temp method
def 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 default 0
(input) The index id of the processor.
Returns
float
The temperature in celsius as a float
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_rtc_drift method
def get_rtc_drift()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get RTC drift.
This function gets the current RTC drift.
Returns
float
The RTC drift as a float
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_batt_volt method
def get_batt_volt()
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Get current battery voltage.
This function gets the current battery voltage.
Returns
float
The battery voltage as a float
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_model_number method
def get_model_number()
Get Zymkey model number
This function gets the Zymkey model number.
Returns
str
The model number as a string.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_firmware_version method
def get_firmware_version()
Get Zymkey firmware version
This function gets the Zymkey firmware version.
Returns
str
The firmware version as a string.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_serial_number method
def get_serial_number()
Get Zymkey serial number
This function gets the Zymkey serial number.
Returns
str
The serial number as a string.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_battery_voltage_action method
def set_battery_voltage_action(sleep=False, self_destruct=False)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set battery voltage action.

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 default False
Set the sleep action.
self_destruct default False
Set the self_destruct action.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_battery_voltage_threshold method
def set_battery_voltage_threshold(threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Sets the battery voltage threshold.
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_cpu_temp_action method
def set_cpu_temp_action(self_destruct=False)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Set HSM CPU temperature threshold action.

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 default False
Set the self_destruct action.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_cpu_low_temp_threshold method
def set_cpu_low_temp_threshold(threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Sets the HSM CPU low temperature threshold.
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_cpu_high_temp_threshold method
def set_cpu_high_temp_threshold(threshold)
Supported devices: ZYMKEY5 HSM60 HSM64 HSM6 Secure Compute Module
Sets the HSM CPU high temperature threshold.
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.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
set_supervised_boot_policy method
def set_supervised_boot_policy(policy_id: int = 0)
Supported devices: Secure Compute Module
Sets the Supervised boot policy.
This function sets the action policy to take when Supervised boot detects a file change during the boot process.
Parameters
policy_id int default 0

The actions to apply to the Supervised boot process:

  • 0 Do Nothing
  • 1 Self-Destruct
  • 2 Hold Chip in Reset
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
add_or_update_supervised_boot_file method
def add_or_update_supervised_boot_file(filepath: str = '', slot: int = 15)
Supported devices: Secure Compute Module
Update file manifest for Supervised boot to check.
This function adds or updates a file in the file manifest to be checked by Supervised during the boot process.
Parameters
filepath str default ''
The file to be signed and checked by Supervised boot.
slot int default 15
The slot to sign the file with.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
remove_supervised_boot_file method
def remove_supervised_boot_file(filepath: str = '')
Supported devices: Secure Compute Module
Remove a file from file manifest for Supervised boot to check.
This function removes a file in the file manifest to be checked by Supervised boot during the boot process.
Parameters
filepath str default ''
The file to be removed from the manifest.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.
get_supervised_boot_file_manifest method
def get_supervised_boot_file_manifest()
Supported devices: Secure Compute Module
Get the file manifest for Supervised boot to check.
This function gets a list of the files that are checked by Supervised boot during the boot process.
Returns
str
File manifest to be checked by Supervised boot.
Raises
AssertionError
If ret is a bad return code from the Zymkey library function.

Classes

ZymkeyAccelAxisData class
class ZymkeyAccelAxisData(g_force, tap_dir)

Inherits from object.

Methods
__init__ method
def __init__(g_force, tap_dir)
Parameters
g_force
tap_dir

RecoveryStrategy class

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

Methods

__init__ method
def __init__(variant='')
Initialize an instance of RecoveryStrategy.
Parameters
variant default ''
Variant of the key type. Currently only “cardano” for ed25519 is supported.

RecoveryStrategyBIP39 class

class RecoveryStrategyBIP39(variant='', passphrase='')

Inherits from RecoveryStrategy.

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

Methods

__init__ method
def __init__(variant='', passphrase='')
Initialize an instance of RecoveryStrategyBIP39.
Parameters
variant default ''
Variant of the key type. Currently only “cardano” for ed25519 is supported.
passphrase default ''
Passphrase used for BIP39 generation. Can be empty string. Must be b64 encoded.

RecoveryStrategySLIP39 class

class RecoveryStrategySLIP39(group_count, group_threshold, iteration_exponent, variant='', passphrase='')

Inherits from RecoveryStrategy.

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

Methods

__init__ method
def __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 default ''
Variant of the key type. Currently only “cardano” for ed25519 is supported.
passphrase default ''
Passphrase used for BIP39 generation. Can be empty string. Must be b64 encoded.

Attributes

client attribute

client: t.Optional[Zymkey] = Zymkey()