Every Ethereum external account is defined by a cryptographic key pair consisting of a public key and a private key. These accounts are indexed by addresses derived from the public key's last 20 bytes. The private key/address combination is encoded in a key file—commonly known as a keystore file. This JSON-formatted text file can be opened and inspected with any text editor. Crucially, the account's private key within this file is encrypted using the password set during account creation.
👉 Learn how to secure your Ethereum assets today
What’s Inside a Keystore File?
A keystore file contains several critical components, primarily housed under the crypto field. Here’s a breakdown:
| Field | Description |
|---|---|
address | The Ethereum account address (e.g., df5f032...15132f5). |
version | The keystore file format version (typically 3). |
crypto | Contains encryption details: |
cipher | Symmetric AES algorithm name (e.g., aes-128-ctr). |
cipherparams | Parameters like iv (initialization vector) for the cipher. |
ciphertext | Encrypted Ethereum private key. |
kdf | Key derivation function (e.g., scrypt) to generate the decryption key from your password. |
kdfparams | Parameters for the KDF (e.g., dklen, salt, n, r, p). |
mac | Integrity check to verify the password. |
Example keystore snippet:
{
"address": "df5f03234385f576f8f69e85194a8e02315132f5",
"crypto": {
"cipher": "aes-128-ctr",
"cipherparams": { "iv": "caf873134967841a20a2e341fe4f2c16" },
"ciphertext": "ca0cf572f6f5f6e4db7467430ee1b15e25082181a6002cf1d0d954e771b53395",
"kdf": "scrypt",
"kdfparams": { "dklen": 32, "n": 4096, "p": 6, "r": 8, "salt": "a8cc9a642bebe14c32f4e2ed249dd4c30e21379abcccfc3fc0596d7c80b5de2c" },
"mac": "2c529cb3be67518c41a3394fa4054e773449bcc34671389c17e453391ca31413"
}
}How Does a Keystore File Work?
Step 1: Encrypting Your Private Key
The Ethereum private key is encrypted using a symmetric algorithm (aes-128-ctr), which requires:
- Cipher parameters: Initialization vector (
iv). - Ciphertext: Encrypted output of the private key.
Step 2: Password-Based Protection
Instead of memorizing the decryption key, users rely on a password processed by a Key Derivation Function (KDF) like scrypt. The KDF uses parameters (salt, n, r, p) to generate the decryption key from the password.
Step 3: Password Verification
The mac value ensures password correctness by comparing a hash of the derived decryption key and ciphertext. If they match, decryption proceeds.
👉 Discover best practices for Ethereum security
Combining the Steps:
- Input: Password → KDF → Decryption key.
- Verify: Decryption key + ciphertext → Matches
mac. - Decrypt: Use the decryption key to reveal the private key.
FAQ: Keystore Files
1. What happens if I lose my keystore file?
Losing the keystore file means losing access to your private key, rendering your funds permanently inaccessible. Always back it up securely.
2. Can I change the password of a keystore file?
Yes, but you’ll need the original password to decrypt and re-encrypt the private key with a new password.
3. Is sharing my keystore file safe?
Never share your keystore file—it’s encrypted, but if paired with the password, it compromises your account.
4. Why use AES-128-CTR and scrypt?
AES-128-CTR provides strong encryption, while scrypt slows brute-force attacks via computational intensity.
5. How do I recover funds if I forget my password?
Without the password, recovery is impossible. Consider hardware wallets for better security.