Ethereum keystore file password lost: what the UTC JSON file is and how recovery works

You have a small JSON file, maybe named UTC--2018-03-14T09-21-07.123456789Z-- followed by a long hex string, and you no longer know the password that opens it. It might have come from MyEtherWallet, from Geth, from an old Parity install, or from a desktop wallet that exported it for you. The ether or tokens attached to that address are still on the blockchain. What is missing is the password that unlocks the key.

This guide explains what that file actually is, why nobody can reset it, what you can safely do today, and what a realistic recovery attempt looks like.

What the keystore file is

An Ethereum keystore file is an encrypted private key. The format is public and documented as the Web3 Secret Storage Definition, version 3 (ethereum.org documentation). One file holds one account. Inside the JSON you will see:

Your password is run through the KDF to derive an encryption key. That key decrypts the private key. The MAC is computed from the derived key and the ciphertext, so a wrong password fails the check immediately and cleanly. That is the reason wallets say "wrong password" rather than opening to garbage.

Why there is no reset

Nothing in the file lets a third party bypass the password. There is no recovery email, no server that holds a copy, and no master key. MyEtherWallet and other web wallets never stored your password or your keystore file. They generated the file in your browser and handed it to you. If a website or a person claims to "unlock" a keystore without the password, they are either guessing passwords like anyone else could, or running a scam.

The KDF is also deliberate friction. Scrypt is designed to be slow and memory-hungry so that each password guess costs real computing time. Geth's own documentation describes the keystore as the encrypted store of account keys (Geth account management). The upside of this design is that the file is safe to copy and test offline. The downside is that guessing is slow, which is why the size of your search matters so much.

First: find every copy you have

Before anyone tests a single password:

1. Copy the file, then work only on the copy. Put the original on two separate devices. The reasoning is the same as in get your crypto wallet back ASAP.
2. Look for other copies and other formats. Search old drives, cloud folders, email attachments, USB sticks and password-manager attachments for files starting with UTC--, or for .json files containing "crypto" and "kdf". Small JSON files are easy to overlook, and the same problem shows up when carving deleted wallet files.
3. Look for a seed phrase or a raw private key. Some wallets that exported a keystore also showed a recovery phrase at creation. A phrase makes the keystore password irrelevant. Do not type a phrase or private key into any website to "check" it.
4. Confirm the address. The address field is public. Put it in a block explorer, such as Etherscan, and confirm there are funds on it. If the balance is zero, you may have the wrong file or the funds may have moved years ago, and there is nothing to recover.
5. Check the file is intact. A keystore that was pasted into a word processor or saved with a changed extension can be damaged. The free wallet file inspector runs in your browser and the file never leaves your machine, which is the standard you should hold any tool to when handling a wallet file.

If you ran Geth yourself, the files live in the keystore folder inside the Geth data directory (by default ~/.ethereum/keystore on Linux, ~/Library/Ethereum/keystore on macOS, and %APPDATA%\Ethereum\keystore on Windows), per the Geth documentation.

Is it really a keystore? Two look-alikes

• A MetaMask vault is a different thing. MetaMask stores an encrypted vault in the browser profile, not a UTC-- file. Recovery there depends on the Secret Recovery Phrase and the local browser data, not on a keystore password. Do not treat them as the same problem.
• A hardware wallet or exchange account is not a keystore. A Ledger or Trezor works from a recovery phrase, and an exchange account is a login held by the exchange. See Trezor recovery and repair and Ledger wallet recovery for those.

How a realistic password search works

A recovery attempt on a keystore is a structured search, run offline against a copy of the file. It is not magic and it does not touch the network or your funds.

1. Extract, do not upload. The tooling reads the KDF parameters, salt, ciphertext and MAC from your copy. Nothing about the file needs to go to a third party for this.
2. Build a candidate list from you, not from a dictionary. Almost every successful search starts with what you remember: base words, the way you usually capitalize, the numbers and symbols you tend to add, keyboard habits, the year you made the wallet, and what you were using at the time. The ideas for remembering a forgotten password post walks through how to mine your own memory before spending any compute.
3. Test candidates offline against the MAC. Each candidate is run through the KDF and checked. Because scrypt is slow by design, the number of candidates you can test per hour is limited, and it is the size and quality of your candidate list that decides whether the search can finish.
4. Stop when the math says stop. If you remember nothing about the password, the search space can be too large to finish. An honest assessment says so before any work starts. Recovery odds by scenario explains where the line is.

The general tools and how they divide the work are covered in cryptocurrency wallet and key recovery tools, which also notes that the John the Ripper collection has extractors for Ethereum keystores.

Do not do these

• Do not upload the file or the password to a "keystore unlocker" website. A keystore plus a correct password is full control of the funds. Some of those sites exist to harvest exactly that.
• Do not trust anyone who contacts you first. Unsolicited offers to unlock a wallet, especially in replies under forum and social posts, are the standard recovery scam. How to tell a legitimate recovery service from a scam is the checklist.
• Do not pay an upfront fee to a service that has not looked at the file's parameters. A real assessment starts from your description of the file and what you remember, not from your password or key.
• Do not send the private key, seed or password in the first message to anyone. You do not need to.

When to get help

If you have the file, have confirmed a balance on the address, and can remember pieces of the password, a structured search can be worth running. If you would rather not run it yourself, describe what you have in your first message: the wallet software, roughly when it was created, the file's kdf value, and what you remember about the password. Do not include the password, the private key, or a seed phrase.

This is the service on the forgotten wallet password recovery page: a free assessment, published pricing, and no fee until your crypto is back.

Get your free assessment →