add documentation for extract-mkey.py

also, cosmetic improvements when running btcrecover with redirected
stdin or stdout

README.md

@@ -16,7 +16,8 @@
  * Typo simulation
  * Progress bar and ETA display (at the command line)
  * Interrupt and Continue searches without losing progress
- * Optional autosave - continue searches even after inadvertent interruptions or crashes
+ * Optional autosave - continue searches even after inadvertent interruptions or crashes
+ * “Offline” mode for Bitcoin Core wallets - use [extract-mkey.py](extract-mkey/README.md) to extract just enough information to attempt password recovery, without giving *btcrecover* or whoever runs it access to any of your addresses or private keys in your Bitcoin wallet.
 
 ----------
 

btcrecover.py

@@ -395,7 +395,7 @@ def aes256_cbc_decrypt_pp(key, iv, ciphertext):
     parser.add_argument("--threads",     type=int, default=cpus, metavar="COUNT", help="number of worker threads (default: number of CPUs, "+str(cpus)+")")
     parser.add_argument("--max-eta",     type=int, default=168,  metavar="HOURS", help="max estimated runtime before refusing to even start (default: 168 hours, i.e. 1 week)")
     parser.add_argument("--no-dupchecks",action="store_true", help="disable duplicate guess checking to save memory")
-    parser.add_argument("--no-progress", action="store_true", help="disable the progress bar")
+    parser.add_argument("--no-progress", action="store_true", default=not sys.stdout.isatty(), help="disable the progress bar")
     parser.add_argument("--mkey",        action="store_true", help="prompt for a Bitcoin Core encrypted master key (from extract-mkey.py) instead of using a wallet file")
     parser.add_argument("--listpass",    action="store_true", help="just list all password combinations and exit")
     parser.add_argument("--pause",       action="store_true", help="pause before exiting")
@@ -638,7 +638,11 @@ def aes256_cbc_decrypt_pp(key, iv, ciphertext):
     if args.mkey:
         assert "readline" not in sys.modules, "readline not loaded during sensitive input"
         # Need to save mkey_data (in a global) for reinitializing worker processes on windows
-        mkey_data = raw_input("Please enter the Bitcoin Core encrypted master key from extract-mkey.py\n> ")
+        if sys.stdin.isatty():
+            prompt = "Please enter the Bitcoin Core encrypted master key from extract-mkey.py\n> "
+        else:
+            prompt = "Reading Bitcoin Core encrypted master key from stdin\n"
+        mkey_data = raw_input(prompt)
         # Emulates load_wallet, but using mkey_data instead; returns the crc (required by do_autosave() )
         mkey_crc = load_bitcoincore_from_mkey(mkey_data)
         if restored and mkey_crc != savestate["mkey_crc"]:

extract-mkey/README.md

@@ -0,0 +1,50 @@
+# *btcrecover* #
+
+## *extract-mkey.py* ##
+
+Sometimes, it is not desireable to run *btcrecover* directly on the computer which stores the target wallet file. For example:
+
+ * A computer or a cloud-based virtual machine with faster CPUs might be a better place to run *btcrecover*.
+ * Configuring *btcrecover* to search for your password correctly can be tricky; you might be interested in finding someone who can configure and run *btcrecover* for you on their computer.
+ * You may not trust that *btcrecover* is free from harmful bugs or other malicious behavior. *btcrecover* is open source, and requires no untrustworthy binaries be installed. However it's also a fairly long and complicated Python script, which makes it difficult even for other Python programmers to be certain that it doesn't contain any harmful code (either intentionally malicious or just by accident).
+
+*extract-mkey.py* is a relatively short and simple script which extracts just enough information from a Bitcoin Core wallet file to be useful to *btcrecover* in a password search, but it doesn't extract enough information to put any of your Bitcoin fortune at risk.
+
+### Download ###
+
+You can download the entire *btcrecover* package from: <https://github.com/gurnec/btcrecover/archive/master.zip>
+
+If you'd prefer to download only the *extract-mkey.py* script, please right click on the following link and choose “Save link as...” or “Save target as...”: <https://github.com/gurnec/btcrecover/raw/master/extract-mkey/extract-mkey.py>
+
+If you're on Windows, you will also need to install the latest version of Python 2.7, either the 32-bit version or the 64-bit version. Currently this is the “Python 2.7.6 Windows Installer” for the 32-bit version, or “Python 2.7.6 Windows X86-64 Installer” for the 64-bit version (which is preferable if you have a 64-bit version of Windows), both available here: <https://www.python.org/download/>
+
+### Usage ###
+
+After downloading the script, **make a copy of your wallet.dat file into a different folder** (to make it easy, into the same folder as *extract-mkey.py*). As a example for Windows, click on the Start Menu, then click “Run...”, and then type this to open your Bitcoin folder which contains your wallet.dat file: `%appdata%\Bitcoin`. From here you can copy and paste your wallet.dat file into a separate folder. Next you'll need to open a Command Prompt window and type something like this (depending on where the downloaded script is, and assuming you've made a copy of your wallet.dat into the same folder):
+
+    cd \Users\Chris\Downloads\btcrecover-master\extract-mkey
+    C:\python27\python extract-mkey.py wallet.dat
+
+You should get a message which looks like this as a result:
+
+    Bitcoin Core encrypted master key, salt, iter_count, and crc in base64:
+    lV/wGO5oAUM42KTfq5s3egX3Uhk6gc5gEf1R3TppgzWNW7NGZQF5t5U3Ik0qYs5/dprb+ifLDHuGNQIA+8oRWA==
+
+When you (or someone else) runs *btcrecover* to search for passwords, you will not need your wallet file, only the output from *extract-mkey.py*. To continue the example:
+
+    cd \Users\Chris\Downloads\btcrecover-master
+    C:\python27\python btcrecover.py --mkey --tokenlist tokens.txt
+    Please enter the Bitcoin Core encrypted master key from extract-mkey.py
+    > lV/wGO5oAUM42KTfq5s3egX3Uhk6gc5gEf1R3TppgzWNW7NGZQF5t5U3Ik0qYs5/dprb+ifLDHuGNQIA+8oRWA==
+    ...
+    Password found: xxx
+
+### Technical Details ###
+
+The *extract-mkey.py* script is intentionally short and should be easy to read for any Python programmer. It opens a wallet.dat file using the Python bsddb.db library (the Berkeley DB library which comes with Python 2.7), and then extracts a single key/value pair with the key string of `\x04mkey\x01\x00\x00\x00`. This key/value pair contains an encrypted version of the Bitcoin Core “master key”, or mkey for short, along with some other information required to try decrypting the mkey, specifically the mkey salt and iteration count. This information is then converted to base64 format for easy copy/paste, and printed to the screen.
+
+The encrypted mkey is useful to *btcrecover*, but it does not contain any of your Bitcoin address or private key information. *btcrecover* can attempt to decrypt the mkey by trying different password combinations. Should it succeed, it and whoever runs it will then know the password to your wallet file, but without the rest of your wallet file, the password and the decrypted mkey are of no use.
+
+### Limitations ###
+
+*extract-mkey.py* only works with Bitcoin Core (a.k.a. Bitcoin-QT) wallet files.