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)

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

Parameters
  • src (str)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.
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 ( sha256, slot = 0, return_recid = False)

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

Parameters
  • sha256 (_hashlib.HASH)A hashlib.sha256 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)

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 model >= HSM6.
Returns
bool Returns

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

verify_digest ( sha256, 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
  • sha256 A hashlib.sha256 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 model >= HSM6.
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. (model >= HSM6).

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 (model >= HSM6).
Exceptions
  • AssertionError If ret is a bad return code from the Zymkey library function.

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 (model >= HSM6).
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 (model >= HSM6).

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 (model >= HSM6).
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 (model >= HSM6).

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 (model >= HSM6).

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.

gen_key_pair ( key_type)

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

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 (model >= HSM6).

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.

remove_key ( slot, foreign = False)

Remove a key at the designated slot (model >= HSM6).

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.

invalidate_ephemeral_key ()

Invalidate the ephemeral key (model >= HSM6).

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.

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 (model >= HSM6).

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. (Curve25519 Not Supported)
  • 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[not supported right now]}. Bip39Strategy->passphrase must be b64 encoded.
Returns
TYPE a tuple with the slot and the BIP39 mnemonic if specified

gen_wallet_child_key ( parent_key_slot, index, hardened)

Generates a child key based on a parent key that is in a wallet (model >= HSM6).

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.
Returns
TYPE the allocated slot on success

restore_wallet_master_seed_from_bip39_mnemonic ( key_type, master_gen_key, wallet_name, bip39_passphrase, bip39_mnemonic)

Restore a wallet’s master seed based on a BIP39 mnemonic string (model >= HSM6).

This method restores a wallet’s master seed based on a BIP39 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. (Curve25519 Not Supported)
  • 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.
  • bip39_passphrase Passphrase used to generate the bip39_mnemonic.
  • bip39_mnemonic The BIP39 mnemonic string.
Returns
TYPE the allocated slot on success

get_wallet_node_addr ( slot)

Get a wallet node address from a key slot (model >= HSM6).

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 (model >= HSM6).

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.

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.

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)

set_digital_perimeter_lp_period ( lp_period)

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

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

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

set_digital_perimeter_lp_max_bits ( max_num_bits)

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

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

set_digital_perimeter_delays ( min_delay_ns, max_delay_ns)

Set the digital perimeter detect delays (model >= HSM6).

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.

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.

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.

get_cpu_temp ()

Get current CPU temperature (model >= HSM6).

This function gets the current HSM CPU temperature.

Returns
TYPE The CPU temperature in celsius as a float

get_rtc_drift ()

Get RTC drift (model >= HSM6).

This function gets the current RTC drift.

Returns
TYPE The RTC drift as a float

get_batt_volt ()

Get current battery voltage (model >= HSM6).

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. (model >= HSM6).

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.

set_battery_voltage_threshold ( threshold)

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

This function sets the threshold at which if the battery voltage falls bellow, the action set by 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.

set_cpu_temp_action ( self_destruct = False)

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

This function specifies the action to take when the HSM CPU temperature falls below the threshold set by 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. (model >= HSM6).

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.

set_cpu_high_temp_threshold ( threshold)

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

This function sets the threshold at which if the on-board HSM CPU’s tempreature rises above, the action set by 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.

class zymkey.RecoveryStrategy

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

Initialize an instance of RecoveryStrategy.

class zymkey.RecoveryStrategyBip39 ( passphrase)

The RecoveryStrategyBip39 class definition.

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

__init__ ( passphrase)

Initialize an instance of RecoveryStrategyBip39.

Parameters
  • passphrase (str)Passphrase used for bip39 generation. Can be empty string. Must be b64 encoded.