The eth-keyfile library is a Python tool designed for handling the encrypted keyfiles that store Ethereum private keys. It provides a robust set of functions for creating, parsing, and decoding these crucial files, ensuring secure management of cryptographic assets in Ethereum-based applications.
Originally developed by Piper Merriam, the project was transferred to the Ethereum Foundation in November 2017 and renamed from ethereum-keyfile to eth-keyfile. This change also affected the PyPi package, which was updated to reflect the new name.
Installation
Getting started with eth-keyfile is straightforward. You can install it using pip:
pip install eth-keyfileThis command fetches the latest version of the library and sets it up in your Python environment.
Core Functions and Usage
Loading a Keyfile
The load_keyfile function reads a keyfile from a given path or file object and returns its contents as a Python dictionary.
from eth_keyfile import load_keyfile
keyfile_data = load_keyfile('path/to/keystore.json')This function is essential for inspecting the structure of a keyfile, which includes details like the encryption cipher, key derivation function parameters, and the encrypted private key.
Creating a Keyfile JSON
To generate a new keyfile, use the create_keyfile_json function. It requires a private key (as a 32-byte bytestring) and a password, along with several optional parameters to customize the encryption process.
import os
from eth_keyfile import create_keyfile_json
private_key = os.urandom(32)
password = b'your_secure_password'
keyfile_json = create_keyfile_json(private_key, password, kdf="pbkdf2", iterations=1000000)This function supports both version 3 and version 4 keyfile standards, allowing flexibility based on your security needs.
Decoding a Keyfile
Retrieving the original private key from an encrypted keyfile is done with decode_keyfile_json or the convenience function extract_key_from_keyfile.
from eth_keyfile import decode_keyfile_json, extract_key_from_keyfile
private_key = decode_keyfile_json(keyfile_json, password)
# or
private_key = extract_key_from_keyfile('path/to/keystore.json', password)These functions decrypt the keyfile using the provided password, returning the private key as a bytestring.
Keyfile Versions: V3 vs. V4
Understanding the differences between keyfile versions is crucial for proper implementation.
- V3 Keyfiles: Use the
secp256k1curve, common in Ethereum. The private key must be below a specific large number, which is rarely an issue in practice. - V4 Keyfiles: Utilize the
bls12-381curve, often for advanced cryptographic purposes like signing. This version imposes a stricter limit on private key values.
Always ensure your private key meets the requirements of the chosen keyfile version to avoid errors.
👉 Explore advanced key management strategies
Setting Up a Development Environment
For those interested in contributing to eth-keyfile, setting up a local development environment is the first step.
git clone [email protected]:ethereum/eth-keyfile.git
cd eth-keyfile
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit installThis sequence clones the repository, creates a virtual environment, installs the package in development mode along with all dependencies, and sets up pre-commit hooks for code quality checks.
Running Tests and Making Contributions
The project relies on a robust testing framework outlined in the Snake Charmers Tactical Manual. Before submitting changes, ensure all tests pass and that your code adheres to the style guidelines enforced by pre-commit.
Versioning and Releases
The project uses semantic versioning. Stable releases follow major.minor.patch, while unstable versions (alpha/beta) append a stage identifier.
To create a new release, use the make release command with the appropriate bump parameter:
make release bump=minorThis process is typically run from the main branch, ensuring version history is maintained correctly.
Frequently Asked Questions
What is an Ethereum keyfile?
An Ethereum keyfile is an encrypted JSON file that stores a private key. It uses a password-based key derivation function to protect the key, ensuring that only someone with the password can access it.
Why would I use eth-keyfile instead of other libraries?eth-keyfile is officially maintained by the Ethereum Foundation, ensuring reliability and adherence to Ethereum standards. It provides a simple, focused API for keyfile management without unnecessary bloat.
Can I use eth-keyfile with hardware wallets?
No, eth-keyfile is designed specifically for managing software-based encrypted keyfiles. Hardware wallets use their own secure elements and interfaces, which are outside this library's scope.
What happens if I lose my password?
Without the password, the encrypted private key cannot be recovered. The security model relies entirely on the password's strength and secrecy. Always store passwords securely and consider using backup mechanisms.
Is it safe to use the default encryption settings?
Yes, the default settings for key derivation (PBKDF2 with a high iteration count) are considered secure. However, for extremely sensitive keys, you may want to increase the iteration count further to enhance security.
How do I choose between keyfile versions?
Use V3 for standard Ethereum accounts and V4 if you are working with advanced cryptographic schemes that require BLS signatures. Ensure your application supports the version you choose.