3.0 KiB
Keyspace Module Specification
This document explains the purpose and functionality of the keyspace module within the Hero Vault.
Purpose of the Module
The keyspace module provides a secure and organized way to manage cryptographic keypairs. It allows for the creation, storage, loading, and utilization of keypairs within designated containers called keyspaces. This module is essential for handling sensitive cryptographic material securely.
What is a Keyspace?
A keyspace is a logical container designed to hold multiple cryptographic keypairs. It is represented by the KeySpace struct in the code. Keyspaces can be encrypted and persisted to disk, providing a secure method for storing collections of keypairs. Each keyspace is identified by a unique name.
What is a Keypair?
A keypair, represented by the KeyPair struct, is a fundamental cryptographic element consisting of a mathematically linked pair of keys: a public key and a private key. In this module, ECDSA (Elliptic Curve Digital Signature Algorithm) keypairs are used.
- Private Key: This key is kept secret and is used for operations like signing data or decrypting messages intended for the keypair's owner.
- Public Key: This key can be shared openly and is used to verify signatures created by the corresponding private key or to encrypt messages that can only be decrypted by the private key.
How Many Keypairs Per Space?
A keyspace can hold multiple keypairs. The KeySpace struct uses a HashMap to store keypairs, where each keypair is associated with a unique string name. There is no inherent, fixed limit on the number of keypairs a keyspace can contain, beyond the practical limitations of system memory.
How Do We Load Them?
Keyspaces are loaded from persistent storage (disk) using the KeySpace::load function, which requires the keyspace name and a password for decryption. Once a KeySpace object is loaded into memory, it can be set as the currently active keyspace for the session using the session_manager::set_current_space function. Individual keypairs within the loaded keyspace are then accessed by their names using functions like session_manager::select_keypair and session_manager::get_selected_keypair.
What Do They Do?
Keypairs within a keyspace are used to perform various cryptographic operations. The KeyPair struct provides methods for:
- Digital Signatures: Signing messages with the private key (
KeyPair::sign) and verifying those signatures with the public key (KeyPair::verify). - Ethereum Address Derivation: Generating an Ethereum address from the public key (
KeyPair::to_ethereum_address). - Asymmetric Encryption/Decryption: Encrypting data using a recipient's public key (
KeyPair::encrypt_asymmetric) and decrypting data encrypted with the keypair's public key using the private key (KeyPair::decrypt_asymmetric).
The session_manager module provides functions that utilize the currently selected keypair to perform these operations within the context of the active session.