improve user docs, especially for OS X

[ci skip]

Author: gurnec

README.md

@@ -6,14 +6,14 @@
 
  * Bitcoin wallet password recovery support for:
      * [Armory](https://github.com/goatpig/BitcoinArmory)
-     * [Bitcoin Classic](https://bitcoinclassic.com/)/[XT](https://bitcoinxt.software/)/[Core](https://bitcoincore.org/)
+     * [Bitcoin Unlimited](https://www.bitcoinunlimited.info/)/[Classic](https://bitcoinclassic.com/)/[XT](https://bitcoinxt.software/)/[Core](https://bitcoincore.org/)
      * [MultiBit Classic](https://multibit.org/) and [MultiBit HD](https://beta.multibit.org/)
      * [Electrum](https://electrum.org/) (1.x and 2.x)
      * Most wallets based on [bitcoinj](https://bitcoinj.github.io/), including [Hive for OS X](https://mac.hivewallet.com/)
-     * BIP-39 passphrases (e.g. [TREZOR](https://www.bitcointrezor.com/) passphrases)
+     * BIP-39 passphrases (e.g. [TREZOR](https://www.bitcointrezor.com/) & [Ledger](https://www.ledgerwallet.com/) passphrases)
      * [mSIGNA (CoinVault)](https://ciphrex.com/products/)
      * [Blockchain.info](https://blockchain.info/wallet)
-     * [pywallet --dumpwallet](https://github.com/jackjack-jj/pywallet) of Bitcoin Classic/XT/Core wallets
+     * [pywallet --dumpwallet](https://github.com/jackjack-jj/pywallet) of Bitcoin Unlimited/Classic/XT/Core wallets
      * [Bitcoin Wallet for Android/BlackBerry](https://play.google.com/store/apps/details?id=de.schildbach.wallet) spending PINs and encrypted backups
      * [KnC Wallet for Android](https://kncwallet.com/) encrypted backups
      * [Bither](https://bither.net/)
@@ -34,13 +34,14 @@
      * BIP-32/39/44 compliant wallets, including:
          * [Mycelium for Android](https://play.google.com/store/apps/details?id=com.mycelium.wallet)
          * [TREZOR](https://www.bitcointrezor.com/)
+         * [Ledger](https://www.ledgerwallet.com/)
          * [Bither](https://bither.net/)
          * [Blockchain.info](https://blockchain.info/wallet)
  * [Free and Open Source](http://en.wikipedia.org/wiki/Free_and_open-source_software) - anyone can download, inspect, use, and redistribute this software
  * Supported on Windows, Linux, and OS X
  * Support for Unicode passwords and seeds
  * Multithreaded searches, with user-selectable thread count
- * Experimental [GPU acceleration](docs/GPU_Acceleration.md) for Bitcoin Classic/XT/Core, Armory, and derived altcoin wallets
+ * Experimental [GPU acceleration](docs/GPU_Acceleration.md) for Bitcoin Unlimited/Classic/XT/Core, Armory, and derived altcoin wallets
  * Wildcard expansion for passwords
  * Typo simulation for passwords and seeds
  * Progress bar and ETA display (at the command line)

TUTORIAL.md

@@ -1,7 +1,7 @@
 # *btcrecover* Tutorial #
 
 
-*btcrecover* is a free and open source multithreaded wallet password recovery tool with support for Armory, Bitcoin Classic/XT/Core, MultiBit (Classic and HD), Electrum (1.x and 2.x), mSIGNA (CoinVault), Hive for OS X, Blockchain.info (v1-v3 wallet formats, both main and second passwords), Bither, and Bitcoin & KNC Wallets for Android. It is designed for the case where you already know most of your password, but need assistance in trying different possible combinations. This tutorial will guide you through the features it has to offer.
+*btcrecover* is a free and open source multithreaded wallet password recovery tool with support for Armory, Bitcoin Unlimited/Classic/XT/Core, MultiBit (Classic and HD), Electrum (1.x and 2.x), mSIGNA (CoinVault), Hive for OS X, Blockchain.info (v1-v3 wallet formats, both main and second passwords), Bither, and Bitcoin & KNC Wallets for Android. It is designed for the case where you already know most of your password, but need assistance in trying different possible combinations. This tutorial will guide you through the features it has to offer.
 
 If you find *btcrecover* helpful, please consider a small donation to help support my efforts:
 **[17LGpN2z62zp7RS825jXwYtE7zZ19Mxxu8](bitcoin:17LGpN2z62zp7RS825jXwYtE7zZ19Mxxu8?label=btcrecover)**
@@ -407,7 +407,7 @@ As you can see, the Windows command prompt was incapable of rendering some of th
  1. Unzip the `btcrecover-master.zip` file, it contains a single directory named "btcrecover-master". Inside the btcrecover-master directory is the Python script (program) file `btcrecover.py`.
  2. **Make a copy of your wallet file** into the directory which contains `btcrecover.py`. On Windows, you can usually find your wallet file by clicking on the Start Menu, then “Run...” (or for Windows 8+ by holding down the *Windows* key and pressing `r`), and then typing in one of the following paths and clicking OK. Some wallet software allows you to create multiple wallets, for example Armory wallets have an ID which you can view in the Armory interface, and the wallet file names contain this ID. Of course, you need to be sure to copy the correct wallet file.
      * Armory - `%appdata%\Armory` (it's a `.wallet` file)
-     * Bitcoin Classic/XT/Core - `%appdata%\Bitcoin` (it's named `wallet.dat`)
+     * Bitcoin Unlimited/Classic/XT/Core - `%appdata%\Bitcoin` (it's named `wallet.dat`)
      * Bitcoin Wallet for Android/BlackBerry, lost spending PINs - Please see the [Bitcoin Wallet for Android/BlackBerry Spending PINs](#bitcoin-wallet-for-androidblackberry-spending-pins) section below.
      * MultiBit Classic - Please see the [Finding MultiBit Classic Wallet Files](#finding-multibit-classic-wallet-files) section below.
      * MultiBit HD - `%appdata%\MultiBitHD` (it's in one of the folders here, it's named `mbhd.wallet.aes`)
@@ -420,10 +420,16 @@ As you can see, the Windows command prompt was incapable of rendering some of th
  3. If you have a `btcrecover-tokens-auto.txt` file, you're almost done. Copy it into the directory which contains `btcrecover.py`, and then simply double-click the `btcrecover.py` file, and *btcrecover* should begin testing passwords. (You may need to rename your wallet file if it doesn't match the file name listed insided the `btcrecover-tokens-auto.txt` file.) If you don't have a `btcrecover-tokens-auto.txt` file, continue reading below.
  4. Copy your `tokens.txt` file, or your passwordlist file if you're using one, into the directory which contains `btcrecover.py`.
  5. You will need to run `btcrecover.py` with at least two command-line options, `--wallet FILE` to identify the wallet file name and either `--tokenlist FILE` or `--passwordlist FILE` (the FILE is optional for `--passwordlist`), depending on whether you're using a [Token File](#the-token-file) or [Passwordlist](#the-passwordlist). If you're using [Typos](#typos) or [Autosave](#autosave), please refer the sections above for additional options you'll want to add.
- 6. What follows is an example on windows. Open a Command Prompt window, and type in the two lines below. The details for your system will be different, for example the download location may be different, or the wallet file name may differ, so you'll need to make some changes. Any additional options are all placed at the end of the *btcrecover* line.
+ 6. Here's an example for both Windows and OS X. The details for your system will be different, for example the download location may be different, or the wallet file name may differ, so you'll need to make some changes. Any additional options are all placed at the end of the *btcrecover* line.
+    * *Windows*: Open a Command Prompt window (click the Start Menu and type "command"), and type in the two lines below. 
 
-        cd \Users\Chris\Downloads\btcrecover-master
-        C:\python27\python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --other-options...
+            cd Downloads\btcrecover-master
+            C:\python27\python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --other-options...
+
+    * *OS X*: Open a terminal window (open the Launchpad and search for "terminal"), and type in the two lines below.
+
+            cd Downloads/btcrecover-master
+            python btcrecover.py --wallet wallet.dat --tokenlist tokens.txt --other-options...
 
 After a short delay, *btcrecover* should begin testing passwords and will display a progress bar and an ETA as shown below. If it appears to be stuck just counting upwards with the message `Counting passwords ...` and no progress bar, please read the [Memory limitations](docs/Limitations_and_Caveats.md#memory) section. If that doesn't help, then you've probably chosen too many tokens or typos to test resulting in more combinations than your system can handle (although the [`--max-tokens`](#token-counts) option may be able to help).
 
@@ -493,9 +499,9 @@ Once you have this information, run *btcrecover* normally, except that *instead*
 
 When you run this, you will be prompted for your master public key (or your address), and your seed.
 
-### GPU acceleration for Bitcoin Classic/XT/Core, Armory, and Litecoin-Qt wallets ###
+### GPU acceleration for Bitcoin Unlimited/Classic/XT/Core, Armory, and Litecoin-Qt wallets ###
 
-*btcrecover* includes experimental support for using one or more graphics cards or dedicated accelerator cards to increase search performance. This can offer on the order of *100x* better performance with Bitcoin Classic/XT/Core or Litecoin-Qt wallets when enabled and correctly tuned. With Armory (which uses a GPU-resistant key derivation function), this can offer a modest improvement of 2x - 5x.
+*btcrecover* includes experimental support for using one or more graphics cards or dedicated accelerator cards to increase search performance. This can offer on the order of *100x* better performance with Bitcoin Unlimited/Classic/XT/Core or Litecoin-Qt wallets when enabled and correctly tuned. With Armory (which uses a GPU-resistant key derivation function), this can offer a modest improvement of 2x - 5x.
 
 For more information, please see the [GPU Acceleration Guide](docs/GPU_Acceleration.md).
 

btcrecover/btcrpass.py

@@ -1095,7 +1095,7 @@ def return_verified_password_or_false(self, orig_passwords):
                 elif b58_privkey[2:6] == b"org." and b58_privkey[0] == b"\x0a" and ord(b58_privkey[1]) < 128:
                     for c in b58_privkey[6:14]:
                         # If it doesn't look like a lower alpha domain name of len >= 8 (e.g. 'bitcoin.'), break
-                        if c > b"z" or (c < b"a" and c != "."):
+                        if c > b"z" or (c < b"a" and c != b"."):
                             break
                     # If the loop above doesn't break, it looks like a domain name; we've found it
                     else:

btcrecover/btcrseed.py

@@ -724,7 +724,7 @@ def _performance_xpub():
 
 ############### BIP39 ###############
 
-@register_selectable_wallet_class("Generic BIP39/BIP44 (Mycelium, TREZOR, Bither, Blockchain.info)")
+@register_selectable_wallet_class("Generic BIP39/BIP44 (Mycelium, TREZOR, Ledger, Bither, Blockchain.info)")
 class WalletBIP39(WalletBIP32):
 
     # Load the wordlists for all languages (actual one to use is selected in config_mnemonic() )

docs/Extract_Scripts.md

@@ -17,7 +17,7 @@ You can download the entire *btcrecover* package from: <https://github.com/gurne
 If you'd prefer to download just a single extract script, please select the one for your wallet software from below, then right click and choose “Save link as...” or “Save target as...”:
 
  * Armory - <https://github.com/gurnec/btcrecover/raw/master/extract-scripts/extract-armory-privkey.py>
- * Bitcoin Classic/XT/Core - <https://github.com/gurnec/btcrecover/raw/master/extract-scripts/extract-bitcoincore-mkey.py>
+ * Bitcoin Unlimited/Classic/XT/Core - <https://github.com/gurnec/btcrecover/raw/master/extract-scripts/extract-bitcoincore-mkey.py>
  * Bither - <https://github.com/gurnec/btcrecover/raw/master/extract-scripts/extract-bither-partkey.py>
  * Blockchain main password - <https://github.com/gurnec/btcrecover/raw/master/extract-scripts/extract-blockchain-main-data.py>
  * Blockchain second password -  <https://github.com/gurnec/btcrecover/raw/master/extract-scripts/extract-blockchain-second-hash.py>
@@ -33,7 +33,7 @@ If you're on Windows, you will also need to install the latest version of Python
 ### Table of Contents ###
 
  * [Armory](#usage-for-armory)
- * [Bitcoin Classic/XT/Core (including pywallet dump files)](#usage-for-bitcoin-classicxtcore)
+ * [Bitcoin Unlimited/Classic/XT/Core (including pywallet dump files)](#usage-for-bitcoin-unlimitedclassicxtcore)
  * [Bither](#usage-for-bither)
  * [Blockchain.info](#usage-for-blockchaininfo)
  * [Electrum (1.x or 2.x)](#usage-for-electrum)
@@ -87,7 +87,7 @@ If someone has one of your (decrypted) private keys and also has or gains access
 Armory automatically pre-generates 100 addresses and private keys before they are needed, which is why you can ask it to display a "new" address without a password. If you've asked for and then used 100 new addresses without providing a password, it's possible that Armory will be unable to provide a new address (without a password) as required by this procedure. If this is the case, you'll have no choice but to choose an already used address. To assist in choosing such an address, you can run `extract-armory-privkey.py list` from the command line to display a list of addresses available in the wallet which include an encrypted private key (including pre-generated addresses that may not be visible via the Armory GUI) along with the first and last known dates of use for each address. These dates of known use do not check the current block chain; you should always check a questionable address on <https://btc.blockr.io/> to check it's current balance before you use it with this procedure.
 
 
-### Usage for Bitcoin Classic/XT/Core ###
+### Usage for Bitcoin Unlimited/Classic/XT/Core ###
 
 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-bitcoincore-mkey.py*). As an 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):
 
@@ -99,7 +99,7 @@ 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==
 
-If you instead have a dump file of a Bitcoin Classic/XT/Core wallet that was created by pywallet, just follow these same instructions except use the *extract-bitcoincore-mkey-from-pywallet.py* script instead.
+If you instead have a dump file of a Bitcoin Unlimited/Classic/XT/Core wallet that was created by pywallet, just follow these same instructions except use the *extract-bitcoincore-mkey-from-pywallet.py* script instead.
 
 When you (or someone else) runs *btcrecover* to search for passwords, you will not need your wallet file, only the output from *extract-bitcoincore-mkey.py*. To continue the example:
 
@@ -110,9 +110,9 @@ When you (or someone else) runs *btcrecover* to search for passwords, you will n
     ...
     Password found: xxxx
 
-#### Bitcoin Classic/XT/Core Technical Details ####
+#### Bitcoin Unlimited/Classic/XT/Core Technical Details ####
 
-The *extract-bitcoincore-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 Classic/XT/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 *extract-bitcoincore-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 Unlimited/Classic/XT/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.