SoftwareBip32SecureKeyHandler

class cometa.key_handler.software_bip32_secure_key_handler.SoftwareBip32SecureKeyHandler(encrypted_data, get_passphrase)

Bases: Bip32SecureKeyHandler

A software-based implementation of a secure key handler for BIP32 hierarchical deterministic keys.

This class securely manages a root key by encrypting it with a passphrase. The passphrase is provided on-demand via a callback, and the decrypted key material only exists in memory for the brief moment it’s needed for an operation, after which it is securely wiped.

Example

>>> def get_passphrase():
...     return b"my-secure-passphrase"
>>> handler = SoftwareBip32SecureKeyHandler.from_entropy(
...     entropy=my_entropy,
...     passphrase=b"my-secure-passphrase",
...     get_passphrase=get_passphrase
... )
>>> account_key = handler.get_account_public_key(account_path)

Parameters:

• encrypted_data (bytes)

• get_passphrase (Callable[[], bytes])

classmethod from_entropy(entropy, passphrase, get_passphrase)

Creates a new BIP32-based key handler from entropy and a passphrase.

Parameters:

• entropy (bytes) – The entropy bytes for the root key.

• passphrase (bytes) – The passphrase to initially encrypt the key.

• get_passphrase (Callable[[], bytes]) – An function called when the passphrase is needed for cryptographic operations.

Returns:

A new instance of the key handler.

Return type:

SoftwareBip32SecureKeyHandler

Warning

For security, consider zeroing out the entropy and passphrase buffers after calling this function if they are mutable bytearrays.

classmethod deserialize(data, get_passphrase)

Deserializes an encrypted key handler from a byte array.

The binary format is: [ 4-byte magic | 1-byte version | 1-byte type | 4-byte data_len | data | 4-byte crc32 checksum ]

Parameters:

• data (bytes) – The serialized and encrypted key data.

• get_passphrase (Callable[[], bytes]) – An function called when the passphrase is needed.

Returns:

A new instance of the key handler.

Raises:

ValueError – If the data is invalid or corrupted.

Return type:

SoftwareBip32SecureKeyHandler

serialize()

Serializes the encrypted key data for secure storage into a binary format.

The binary format is: [ 4-byte magic | 1-byte version | 1-byte type | 4-byte data_len | data | 4-byte crc32 checksum ]

Returns:

The serialized and encrypted key data.

Return type:

bytes

sign_transaction(transaction, derivation_paths)

Signs a transaction using BIP32-derived keys.

Parameters:

• transaction (Transaction) – The transaction to sign.

• derivation_paths (list[DerivationPath]) – The paths to the keys needed for signing.

Returns:

A VkeyWitnessSet containing the witnesses with signatures.

Raises:

ValueError – If derivation_paths is empty.

Return type:

VkeyWitnessSet

Note

During this operation, the root key is temporarily decrypted in memory and then securely wiped immediately after use.

sign_data(data, derivation_path)

Signs arbitrary data using a BIP32-derived key.

Parameters:

• data (str) – The hex-encoded data to be signed.

• derivation_path (DerivationPath) – The derivation path specifying which key to use.

Returns:

A dict with ‘signature’ and ‘key’ (public key) as hex strings.

Return type:

dict[str, str]

get_private_key(derivation_path)

Retrieves the securely stored private key.

Parameters:

derivation_path (DerivationPath) – The derivation path specifying which key to retrieve.

Returns:

The Ed25519PrivateKey.

Return type:

Ed25519PrivateKey

Warning

This operation exposes the private key in memory and should be used with extreme caution. The caller is responsible for securely handling and wiping the key from memory after use.

get_account_public_key(path)

Derives and returns an extended account public key.

Parameters:

path (AccountDerivationPath) – The derivation path for the account.

Returns:

The extended account public key.

Return type:

Bip32PublicKey

Note

This operation requires the root key, which is temporarily decrypted in memory and then securely wiped immediately after use.