BitVMX Key Manager is a comprehensive Rust library designed for managing cryptographic keys used in BitVMX protocol transactions. It offers robust methods for generating, importing, and deriving keys, as well as signing messages using ECDSA, Schnorr, Winternitz, and MuSig2 algorithms. The library ensures secure storage of keys, making it a reliable choice for blockchain and cryptographic applications.
This library is currently under development and may not be fully stable. It is not production-ready, has not been audited, and future updates may introduce breaking changes without preserving backward compatibility.
A random mnemonic will be auto generated and stored, is no one is provided by configuration, and if it's not already found at the keystore. Make sure to back it up securely!
- 🔑 Key Generation and Storage: Generate new keys and store them securely.
- 📥 Key Importing: Import existing private keys into the keystore.
- 🌐 Key Derivation: Derive keys using BIP39, BIP44 hierarchical deterministic wallets.
- ✍️ Message Signing: Sign messages using ECDSA, Schnorr, Winternitz, and MuSig2 algorithms.
- ✅ Signature Verification: Verify signatures for ECDSA, Schnorr, Winternitz, and MuSig2.
The BitVMX Key Manager implements different strategies for key derivation and storage based on the cryptographic algorithm and practical considerations:
- HD Derivation: Bitcoin keys are derived using hierarchical deterministic (HD) derivation following BIP39/BIP44 standards from a master seed/mnemonic
- Storage: Both private and public keys are stored in the encrypted keystore for persistent access
- Rationale: Standard Bitcoin practice enabling deterministic key generation and wallet recovery
- HD Derivation: Winternitz keys are HD derived from the same master seed for consistency
- Storage: Keys are not stored in the keystore - they are regenerated on-demand each time they're needed
- Rationale: Storage scalability - Winternitz signatures require large key sets that would significantly bloat storage requirements. Since they can be deterministically regenerated from the HD seed, we prioritize storage efficiency
- HD Derivation: Lamport keys are HD derived from the same master seed for consistency, adn are also able to be imported
- Storage: Derived keys are not stored in the keystore - they are regenerated on-demand each time they're needed, Imported keys are stored
- Rationale: Storage scalability - Lamport signatures require large key sets that would significantly bloat storage requirements. Since they can be deterministically regenerated from the HD seed, we prioritize storage efficiency. Imported keys are stores, as there is no way to re generate them from the seed. The storage key is the public key compressed using blake3, private materials are fully stored
- Fresh Entropy: RSA keys are generated using fresh entropy provided by the user, with no correlation to the HD mnemonic
- Storage: Private and public keys are stored in the encrypted keystore
- Rationale: While HD derivation of RSA keys is theoretically possible (as explored in research), we deliberately choose fresh entropy generation to:
- Align with RSA industry standards and best practices
- Provide stronger security guarantees independent of the HD seed
- Acknowledge that users must backup the keystore anyway due to key importing features
- No HD Correlation: Imported keys have no relationship to the master HD mnemonic by design
- Storage: Stored in the encrypted keystore alongside generated keys
- Rationale: Preserves the original entropy and properties of externally generated keys
Important: Since the key manager supports importing external keys and uses fresh entropy for RSA keys, users must backup the entire encrypted keystore in addition to the HD mnemonic. The mnemonic alone is insufficient for complete wallet recovery.
Internally the key manager generates a key pair, stores the private key and the corresponding public key in the encrypted keystore. The public key is later used to select the corresponding private key for signing.
next_keypair is always the preferred way to get a new keypair, as it manages the derivation index automatically.
The KeyManager supports both Taproot script path spends and key path spends (with or without tweaking). These methods use Schnorr signatures and are compatible with BIP-340/341 Taproot usage in Bitcoin.
The key manager supports Winternitz one-time keys. Winternitz keys can be generated using SHA-256 or RIPEMD-160 hash functions. As with the ECDSA keys, a key pair is generated and only the public key is returned. The public key can later be used to select the corresponding private key for signing.
The key manager also supports Lamport one-time signature keys. Lamport keys are derived and managed similarly to Winternitz keys, with the key pair being generated and only the public key returned for later use in signing operations.
The KeyManager supports MuSig2 multi-signature schemes, allowing multiple parties to jointly produce a single Schnorr signature. See more details on MuSig2 for Rust.
- Clone the repository
- Install dependencies:
cargo build - Run tests:
cargo test --release -- --test-threads=1
- create:
run with
cargo run --example create - key_gen:
run with
cargo run --example key_gen - key_import:
run with
cargo run --example key_import - deriving_winternitz:
run with
cargo run --example deriving_winternitz - deriving_lamport:
run with
cargo run --example deriving_lamport - import_lamport:
run with
cargo run --example import_lamport - sign_verify_ecdsa:
run with
cargo run --example sign_verify_ecdsa - sign_verify_schnorr_taproot:
run with
cargo run --example sign_verify_schnorr_taproot - sign_verify_winternitz:
run with
cargo run --example sign_verify_winternitz - sign_verify_lamport:
run with
cargo run --example sign_verify_lamport - rsa:
run with
cargo run --example rsa
The library provides several compile-time feature flags to customize behavior:
-
transactional(enabled by default): Enables transactional database operations for atomicity guarantees when storing keys. When enabled, all database operations are wrapped in transactions to ensure consistency. Disable this feature if you need to use the library without transactional support. -
wots_idx_check(enabled by default): Enables index validation checks for Winternitz One-Time Signature (WOTS) keys. This ensures that each WOTS key index is only used once, preventing security vulnerabilities from key reuse. It's highly recommended to keep this enabled for production use. -
strict(disabled by default): Enables strict validation and additional safety checks throughout the library. When enabled, operations perform extra validation steps that may impact performance but provide stronger guarantees. Useful for development and testing environments.
To use without default features:
bitvmx-key-manager = { version = "0.5.0", default-features = false }To enable specific features:
bitvmx-key-manager = { version = "0.5.0", features = ["strict"] }Contributions are welcome! Please open an issue or submit a pull request on GitHub.
This project is licensed under the MIT License - see LICENSE file for details.
This repository is a component of the BitVMX Ecosystem, an open platform for disputable computation secured by Bitcoin. You can find the index of all BitVMX open-source components at FairgateLabs/BitVMX.