Software Secure Key Handler¶

cardano_error_t cardano_software_secure_key_handler_new(const byte_t *entropy_bytes, size_t entropy_bytes_len, const byte_t *passphrase, size_t passphrase_len, cardano_get_passphrase_func_t get_passphrase, cardano_secure_key_handler_t **secure_key_handler)¶

Creates a new software-based secure key handler with encrypted entropy.

The cardano_software_secure_key_handler_new function initializes a software-based secure key handler for managing cryptographic key operations, using provided entropy bytes and a passphrase for encryption. This key handler ensures the secure management and encryption of sensitive cryptographic material.

Upon creation, the handler immediately encrypts the provided entropy bytes using the given passphrase. All intermediary sensitive data used in the process, such as unencrypted entropy and passphrase, is securely wiped from memory once the encryption process is complete.

This secure key handler will:

Encrypt the entropy bytes with the provided passphrase for secure storage.
Use the get_passphrase callback to retrieve the passphrase when needed for decrypting the entropy during cryptographic operations.
Ensure that any decrypted entropy is wiped from memory immediately after use, employing secure memory clearing measures that prevent sensitive data from lingering in memory.

See also

cardano_secure_key_handler_t for the public interface to interact with this handler.

Note

This function securely wipes all intermediary sensitive data from memory, once they have been used for encryption. The caller must also ensure that both the passphrase and entropy bytes are securely erased from memory after calling this function.

Note

The get_passphrase callback is invoked every time the key material is required. The seed is decrypted only for the short period needed to perform the cryptographic operation, after which it is securely wiped from memory.

Parameters:¶

const byte_t *entropy_bytes¶: A pointer to a buffer containing entropy bytes used to generate cryptographic key material. This entropy should be high-quality and random.
size_t entropy_bytes_len¶: The length of the entropy_bytes buffer.
cardano_get_passphrase_func_t get_passphrase¶: A callback function used to securely retrieve the passphrase during cryptographic operations.
const byte_t *passphrase¶: A pointer to the buffer containing the passphrase, which will be used to encrypt the entropy.
size_t passphrase_len¶: The length of the passphrase buffer.
cardano_secure_key_handler_t **secure_key_handler¶: A pointer to the resulting secure key handler. This handler manages cryptographic operations such as signing and key derivation.

Returns:¶

cardano_error_t indicating success or the type of error encountered during initialization.

cardano_error_t cardano_software_secure_key_handler_ed25519_new(cardano_ed25519_private_key_t *ed25519_private_key, const byte_t *passphrase, size_t passphrase_len, cardano_get_passphrase_func_t get_passphrase, cardano_secure_key_handler_t **secure_key_handler)¶

Creates a new software secure key handler for an Ed25519 private key.

The cardano_software_secure_key_handler_ed25519_new function initializes a secure key handler to manage cryptographic operations using a pre-derived Ed25519 private key. Unlike BIP32-based handlers, this function is specifically designed for handling Ed25519 keys and does not support hierarchical key derivation (BIP32).

The handler encrypts the provided Ed25519 private key with the given passphrase immediately upon creation and securely stores it. All sensitive data (e.g., the private key and passphrase) are wiped from memory after use to ensure that no residual sensitive information remains in memory.

The function takes a reference to the ed25519_private_key, meaning the caller must manage the lifecycle of this object. The caller is responsible for releasing their reference by calling cardano_ed25519_private_key_unref when it is no longer needed. The cardano_ed25519_private_key_unref function safely wipes the memory before releasing it when its reference count reaches 0.

The get_passphrase callback is invoked every time the private key needs to be decrypted for cryptographic operations such as signing. Once decrypted, the key is used for a short period, and it is securely erased from memory after the operation is complete.

Example:

cardano_ed25519_private_key_t* ed25519_private_key = ...; // Pre-derived Ed25519 private key
const byte_t* passphrase = ...;                           // Passphrase to encrypt the key
cardano_secure_key_handler_t* secure_handler = NULL;

cardano_software_secure_key_handler_ed25519_new(
    ed25519_private_key,
    passphrase,
    passphrase_len,
    get_passphrase_callback,
    &secure_handler);

// When finished, the caller should release the private key reference.
cardano_ed25519_private_key_unref(ed25519_private_key);

See also

cardano_software_secure_key_handler_new for BIP32-based key handler creation.

See also

cardano_ed25519_private_key_unref for safely managing the memory of Ed25519 private keys.

Note

The private key is encrypted upon creation and only decrypted when necessary. The caller must ensure that the passphrase and private key are securely erased from memory after passing them to this function. The caller must also manage the lifecycle of the ed25519_private_key object and call cardano_ed25519_private_key_unref when it is no longer needed. The key handler will manage the memory securely, wiping out any sensitive data after use.

Parameters:¶

cardano_ed25519_private_key_t *ed25519_private_key¶: [in] A pointer to the cardano_ed25519_private_key_t that will be managed by the key handler.
const byte_t *passphrase¶: [in] A pointer to the passphrase used for encrypting the private key.
size_t passphrase_len¶: [in] The length of the passphrase in bytes.
cardano_get_passphrase_func_t get_passphrase¶: [in] A callback function for retrieving the passphrase when needed to decrypt the private key.
cardano_secure_key_handler_t **secure_key_handler¶: [out] A pointer to the secure key handler that will be created.

Returns:¶

cardano_error_t indicating success or failure of the operation.

cardano_error_t cardano_software_secure_key_handler_deserialize(const byte_t *serialized_data, size_t serialized_data_len, cardano_get_passphrase_func_t get_passphrase, cardano_secure_key_handler_t **secure_key_handler)¶

Deserializes a previously serialized software-based secure key handler.

The cardano_software_secure_key_handler_deserialize function initializes a secure key handler from serialized data. The serialized data is expected to be created using the cardano_secure_key_handler_serialize function of a secure software key handler.

See also

cardano_secure_key_handler_t for the public interface to interact with this handler.

Note

The key handler will not decrypt any sensitive data during the deserialization process. The sensitive key material will remain encrypted, and the get_passphrase callback will be invoked to retrieve the passphrase only when needed to decrypt secrets for specific cryptographic operations.

Parameters:¶

const byte_t *serialized_data¶: A pointer to the buffer containing the serialized representation of the secure key handler. This data should have been generated using the cardano_secure_key_handler_serialize function of a secure software key handler.
size_t serialized_data_len¶: The length of the serialized_data buffer.
cardano_get_passphrase_func_t get_passphrase¶: A callback function that will be used to securely retrieve the passphrase when sensitive data must be decrypted.
cardano_secure_key_handler_t **secure_key_handler¶: A pointer to the resulting secure key handler, which can now be used for cryptographic operations such as signing and key derivation. The key handler will only decrypt sensitive data when needed, invoking the get_passphrase callback at those times.

Returns:¶

cardano_error_t indicating success or the type of error encountered during deserialization.