btcrecover is a free and open source multithreaded wallet password recovery tool with support for Armory, Bitcoin Core (a.k.a. Bitcoin-Qt), MultiBit (a.k.a. MultiBit Classic, MultiBit HD is not supported), Electrum, Blockchain (v1 and v2 wallet formats, both main and second passwords) and Litecoin-Qt. 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
This tutorial is pretty long... you don't have to read the whole thing. Here are some places to start.
- Read the Installation section for instructions and download links.
- If you already have a
btcrecover-tokens-auto.txtfile, skip straight to step 5. If you need help creating passwords from different combinations of smaller pieces you remember, start with step 3. If you you think there's a typo in your password, or if you mostly know what your whole password is and only need to try different variations of it, read step 4. - Read The Token File section (at least the beginning), which describes how btcrecover builds up a whole password you don't remember from smaller pieces you do remember. Once you're done, you'll know how to create a
tokens.txtfile you'll need later. - Read the Typos section, which describes how btcrecover can make variations to a whole password to create different password guesses. Once you're done, you'll have a list of command-line options which will create the variations you want to test.
- If you didn't need step 3, read The Passwordlist section instead.
- Read the Running btcrecover section to see how to put these pieces together and how to run btcrecover in a Command Prompt window.
- (optional) Read the Testing your config section to view the passwords that will be tested.
- (optional) If you're testing a lot of combinations that will take a long time, use the Autosave feature to safeguard against losing your progress.
- (optional, but highly recommended) Donate huge sums of Bitcoin to the donation address above once your password's been found.
btcrecover can accept as input a text file which has a list of what are called password “tokens”. A token is simply a portion of a password which you do remember, even if you don't remember where that portion appears in the actual password. It will combine these tokens in different ways to create different whole password guesses to try.
This plain text file, typically named tokens.txt, can be created in any basic text editor, such as Notepad on Windows or TextEdit on OS X, and should probably be saved into the same folder as the btcrecover.py script (just to keep things simple).
Let’s say that you remember your password contains 3 parts, you just can’t remember in what order you used them. Here are the contents of a simple tokens.txt file:
Cairo
Beetlejuice
Hotel_california
When used with these contents, btcrecover will try all possible combinations using one or more of these three tokens, e.g. Hotel_california (just one token), BettlejuiceCairo (two tokens pasted together), etc.
Maybe you’re not sure about how you spelled or capitalized one of those words. Take this token file:
Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california
Tokens listed on the same line, separated by spaces, are mutually exclusive and will never be tried together in a password guess. btcrecover will try Cairo and bettlejuiceCairoHotel_california, but it will skip over Betelgeusebetelgeuse. Had all four Beetlejuice versions been listed out on separate lines, this would have resulted in trying thousands of additional passwords which we know to be incorrect. As is, this token file only needs to try 48 passwords to account for all possible combinations. Had they all been on separate lines, it would have had to try 1,956 different combinations.
In short, when you’re sure that certain tokens or variations of a token have no chance of appearing together in a password, placing them all on the same line can save a lot of time.
What if you’re certain that Cairo appears in the password, but you’re not so sure about the other tokens?
+ Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california
Placing a + (and some space after it) at the beginning of a line tells btcrecover to only try passwords that include Cairo in them. You can also combine these two last features. Here’s a longer example:
Cairo cairo Katmai katmai
+ Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california hotel_california
In this example above, passwords will be constructed by taking at most one token from the first line, exactly one token from the second line (it’s required), and at most one token from the third line. So Hotel_californiaBetelgeuse would be tried, but cairoKatmaiBetelgeuse would be skipped (cairo and Katmai are on the same line, so they’re never tried together) and katmaiHotel_california is also skipped (because one token from the second line is required in every try).
This file will create a total of just 244 different combinations. Had all ten of those tokens been listed on separate lines, it would have produced 9,864,100 guesses, which could take days longer to test!
Another way to save time is to use “anchors”. You can tell btcrecover that certain tokens, if they are present at all, are definitely at the beginning or end of the password:
^Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
Hotel_california$
In this example above, the ^ symbol is considered special if it appears at the beginning of any token (it’s not actually a part of the password), and the $ symbol is special if it appears at the end of any token. Cairo, if it is tried, is only tried at the beginning of a password, and Hotel_california, if it is tried, is only tried at the end. Note that neither is required to be tried in password guesses with the example above. As before, all of these options can be combined:
Cairo
Beetlejuice beetlejuice Betelgeuse betelgeuse
+ ^Hotel_california ^hotel_california
In this example above, either Hotel_california or hotel_california is required at the beginning of every password that is tried (and the other tokens are tried normally after that).
Tokens with positional anchors may only appear at one specific position in the password -- there are always a specific number of other tokens which precede the anchored one. In the example below you'll notice a number in between the two ^ symbols added to the very beginning to create positionally anchored tokens (with no spaces):
^2^Second_or_bust
^3^Third_or_bust
Cairo
Beetlejuice
Hotel_california
As you can guess, Second_or_bust, if it is tried, is only tried as the second token in a password, and Third_or_bust, if it is tried, is only tried as the third. (Neither token is required because there is no + at the beginning these of these lines.)
Middle anchors are a bit like positional anchors, only more flexible: the anchored tokens may appear once throughout a specific range of positions in the password.
Note that placing a middle anchor on a token introduces a special restriction: it forces the token into the middle of a password. A token with a middle anchor (unlike any of the other anchors described above) will never be tried as the first or last token of a password.
You specify a middle anchor by adding a comma and two numbers (between the ^ symbols) at the very beginning of a token (all with no spaces):
^2,3^Second_or_third_(but_never_last)
^2,4^Second_to_fourth_(but_never_last)
Cairo
Beetlejuice
Hotel_california
As mentioned above, neither of those middle-anchored tokens will ever be tried as the last token in a password, so something (one or more of the non-anchored tokens) will appear after the middle-anchored ones in every guess in which they appear. Since tokens with middle anchors never appear at the beginning either, the smallest value you can use for that first number is 2. Finally, when you specify the range, you can leave out one (or even both) of the numbers, like this:
^3,^Third_or_after_(but_never_last)
^,3^Third_or_earlier((but_never_first_or_last)
^,^Anywhere_in_the_middle
Cairo
Beetlejuice
Hotel_california
You can't leave out the comma (that's what makes it a middle anchor instead of a positional anchor). Leaving out a number doesn't change the “never at the beginning or the end” rule which always applies to middle anchors. If you do need a token with a middle anchor to also possibly appear at the beginning or end of a password, you can add second copy to the same line with a beginning or end anchor (because at most one token on a line can appear in any guess):
^,^Anywhere_in_the_middle_or_end Anywhere_in_the_middle_or_end$
^,^Anywhere_in_the_middle_or_beginning ^Anywhere_in_the_middle_or_beginning
There are a number of command-line options that affect the combinations tried. The --max-tokens option limits the number of tokens that are added together and tried. With --max-tokens set to 2, Hotel_californiaCairo, made from two tokens, would be tried from the earlier example, but Hotel_californiaCairoBeetlejuice would be skipped because it’s made from three tokens. You can still use btcrecover even if you have a large number of tokens, as long as --max-tokens is set to something reasonable. If you’d like to re-run btcrecover with a larger number of --max-tokens if at first it didn’t succeed, you can also specify --min-tokens to avoid trying combinations you’ve already tried.
What if you think one of the tokens has a number in it, but you’re not sure what that number is? For example, if you think that Cairo is definitely followed by a single digit, you could do this:
Cairo0 Cairo1 Cairo2 Cairo3 Cairo4 Cairo5 Cairo6 Cairo7 Cairo8 Cairo9
Beetlejuice
Hotel_california
While this definitely works, it’s not very convenient. This next token file has the same effect, but it’s easier to write:
Cairo%d
Beetlejuice
Hotel_california
The %d is a wildcard which is replaced by all combinations of a single digit. Here are some examples of the different types of wildcards you can use:
%d- a single digit%2d- exactly 2 digits%1,3d- between 1 and 3 digits (all possible permutations thereof)%0,2d- between 0 and 2 digits (in other words, the case where there are no digits is also tried)%a- a single ASCII lowercase letter%1,3a- between 1 and 3 lowercase letters%A- a single ASCII uppercase letter%n- a single digit or lowercase letter%N- a single digit or uppercase letter%ia- a “case-insensitive” version of %a: a single lower or uppercase letter%in- a single digit, lower or uppercase letter%1,2in- between 1 and 2 characters long of digits, lower or uppercase letters%[chars]- exactly 1 of the characters between[and](e.g. either ac,h,a,r, ors)%1,3[chars]- between 1 and 3 of the characters between[and]%[0-9a-f]- exactly 1 of these characters:0123456789abcdef%2i[0-9a-f]- exactly 2 of these characters:0123456789abcdefABCDEF%s- a single space%l- a single line feed character%r- a single carriage return character%R- a single line feed or carriage return character%t- a single tab character%T- a single space or tab character%w- a single space, line feed, or carriage return character%W- a single space, line feed, carriage return, or tab character%y- any single ASCII symbol%Y- any single ASCII digit or symbol%p- any single ASCII letter, digit, or symbol%P- any single character from either%por%W(pretty much everything)%c- a single character from a custom set specified at the command line with--custom-wild characters%C- an uppercased version of%c(the same as%cif%chas no lowercase letters)%ic- a case-insensitive version of%c%%- a single%(so that%’s in your password aren’t confused as wildcards)%^- a single^(so it’s not confused with an anchor if it’s at the beginning of a token)%S- a single$(yes, that’s%and a capitalSthat gets replaced by a dollar sign, sorry if that’s confusing)
Up until now, most of the features help by reducing the number of passwords that need to be tried by exploiting your knowledge of what’s probably in the password. Wildcards significantly expand the number of passwords that need to be tried, so they’re best used in moderation.
Backreference wildcards copy one or more characters which appear somewhere earlier in the password. In the simplest case, they're not very useful. For example, in the token Z%b, the %b simply copies the character which immediately precedes it, resulting in ZZ.
Consider the case where the password contains patterns such as AA, BB, up through ZZ, but would never contain AZ. You could use %2A to generate these patterns, but then you'd end up with AZ being tried. %2A generates 676 different combinations, but in this example we only want to try 26. Instead you can use two wildcards together: %A%b. The %A will expand into a single letter (from A to Z), and after this expansion happens, the %b will copy that letter, resulting in only the 26 patterns we want.
As with normal wildcards, backreference wildcards may contain a copy length, for example:
Test%d%b-Test00throughTest99, but neverTest12Test%d%2b-Test000throughTest999, but neverTest123Test%d%0,3b-Test(the length is 0),Test0toTest9, etc.,Test0000toTest9999
In the examples so far, the copying starts with the character immediately to the left of the %b, but this can be changed by adding a ;# just before the b, for example:
Test%b-TesttTest%;1b- starts 1 back, same as above,TesttTest%;2b- starts 2 back,TestsTest%;4b- starts 4 back,TestTTest%2;4b- starts 4 back, with a copy length of 2:TestTeTest%8;4b- starts 4 back, with a copy length of 8:TestTestTestTest%0,2;4b- starts 4 back, with a copy length from 0 to 2:Test,TestT, andTestTe%2Atest%2;6b- patterns such asABtestABandXKtestXKwhere the two capital letters before and aftertestmatch each other, but neverABtestXKwhere they don't match
To summarize, wildcards to the left of a %b are expanded first, and then the %b is replaced by copying one or more characters from the left, and then wildcards towards the right (if any) are examined.
Instead of adding new characters to a password guess, contracting wildcards remove one or more characters. Here's an example:
Start%0,2-End
The %0,2- contracting wildcard will remove between 0 and 2 adjacent characters from either side, so that each of StartEnd (removes 0), StarEnd (removes 1 from left), StaEnd (removes 2 from left), Starnd (removes 1 from left and 1 from right), Startnd (removes 1 from right), and Startd (removes 2 from right) will be tried. This can be useful when considering copy-paste errors, for example:
%0,20-A/Long/Password/with/symbols/that/maybe/was/partially/copy/pasted%0,20-
Different versions of this password will be tried removing up to 20 characters from either end.
Here are the three types of contracting wildcards:
%0,5-- removes between 0 and 5 adjacent characters (total) taken from either side of the wildcard%0,5<- removes between 0 and 5 adjacent characters only from the wildcard's left%0,5>- removes between 0 and 5 adjacent characters only from the wildcard's right
You may want to note that a contracting wildcard in one token can potentially remove characters from other tokens, but it will never remove or cross over another wildcard. Here's an example to fully illustrate this (feel free to skip to the next section if you're not interested in these specific details):
AAAA%0,10>BBBB
xxxx%dyyyy
These two tokens each have eight normal letters. The first token has a contracting wildcard which removes up to 10 characters from its right, and the second token has an expanding wildcard which expands to a single digit.
One of the passwords generated from these tokens is AAAABBxxxx5yyyy, which comes from selecting the first token followed by the second token, and then applying the wildcards with the contracting wildcard removing two characters. Another is AAAAxx5yyyy which comes from the same tokens, but the contracting wildcard now is removing six characters, two of which are from the second token.
The digit and the yyyy will never be removed by the contracting wildcard because other wildcards are never removed or crossed over. Even though the contracting wildcard is set to remove up to 10 characters, AAAAyyy will never be produced because the %d blocks it.
This feature combines traits of both backreference wildcards and typos maps into a single function. If you haven't read about typos maps below (or about backreference wildcards above), you should probably skip this section for now and come back later.
Consider a complex password pattern such as this: 00test11, 11test22, etc. up through 88test99. In other words, the pattern is generated by combining these 5 strings: # # test #+1 #+1. Using simple backreference wildcards, we can almost produce such a pattern with this token: %d%btest%d%b. This produces everything from our list, but it also produced a lot more that we don't want, for example 33test55 is produced even though it doesn't match the pattern because 3+1 is not 5.
Instead a way is needed for a backreference wildcard to do more than simply copy a previous character, it must be able to create a modified copy of a previous character. It can do this the same way that a typos map replaces characters by using a separate map file to determine the replacement. So to continue this example, a new map file is needed, nextdigit.txt:
0 1
1 2
2 3
3 4
4 5
5 6
6 7
7 8
8 9
Finally, here's a token that makes use of this map file to generate the pattern we're looking for: %d%btest%2;nextdigit.txt;6b. That's pretty complicated, so let's break it down:
-
%d- expands to0through9 -
%b- copies the previous character, so no we have00through99 -
test- now we have00testthrough99test -
%2;nextdigit.txt;6b- a single backreference wildcard which is made up of:2- the copy length (the length of the result after expansion)nextdigit.txt- the map file used determine how to modify characters6- how far to the left of the wildcard to start copying; 6 characters counting leftwards from the end of00testis the first0
The result of expanding this wildcard when the token starts off with
00testis00test11. It expands into two1's because the copy length is 2, and it expands into modified1's instead of just copying the0's because the file maps a0(in its first column) to a1(in the second column). Likewise, a77testis expanded into77test88.99testis expanded into99test99because the the lookup character, a9, isn't present in (the first column of) the map file, and so it's copied unmodified.
Note that when you use a map file inside a backreference wildcard, the file name always has a semicolon (;) on either side. These are all valid backreference wildcards (but they're all different because the have different copy lengths and starting positions): %;file.txt;b, %2;file.txt;b, %;file.txt;6b, %2;file.txt;6b.
The final example involves something called keyboard walking. Consider a password pattern where a typist starts with any letter, and then chooses the next character by moving their finger using a particular pattern, for example by always going either diagonal up and right, or diagonal down and right, and then repeating until the result is a certain length. A single backreference wildcard that uses a map file can create this pattern.
Here's what the beginning of a map file for this pattern, pattern.txt, would look like:
q 2a
a wz
z s
2 w
w 3s
...
So if the last letter is a q, the next letter in the pattern is either a 2 or an a (for going upper-right or lower-right). If the last letter is a z, there's only one direction available for the next letter, upper-right to s. With this map file, and the following token, all combinations which follow this pattern between 4 and 6 characters long would be tried: %a%3,5;pattern.txt;b
If you already have a simple list of whole passwords you'd like to test, and you don't need any of the features described above, you can use the --passwordlist command-line option (instead of the --tokenlist option as described later in the Running btcrecover section).
If you specify --passwordlist without a file, btcrecover will prompt you to type in a list of passwords, one per line, in the Command Prompt window. If you already have a text file with the passwords in it, you can use --passwordlist FILE instead (replacing FILE with the file name).
Be sure not to add any extra spaces, unless those spaces are actually a part of a password.
Each line is used verbatim as a single password when using the --passwordlist option (and none of the features from above are applied). You can however use any of the Typos features described below to try different variations of the passwords in the passwordlist.
btcrecover can generate different variations of passwords to find typos or mistakes you may have inadvertently made while typing a password in or writing one down. This feature is enabled by including one or more command-line options when you run btcrecover.
If you'd just like some specific examples of command-line options you can add, please see the Typos Quick Start Guide.
With the --typos # command-line option (with # replaced with a count of typos), you tell btcrecover up to how many typos you’d like it to add to each password (that has been either generated from a token file or taken from a passwordlist as described above). You must also specify the types of typos you’d like it to generate, and it goes through all possible combinations for you (including the no-typos-present possibility). Here is a summary of the basic types of typos along with the command-line options which enable each:
--typos-capslock- tries the whole password with caps lock turned on--typos-swap- swaps two adjacent characters--typos-repeat- repeats (doubles) a character--typos-delete- deletes a character--typos-case- changes the case (upper/lower) of a single letter
For example, with --typos 2 --typos-capslock --typos-repeat options specified on the command line, all combinations containing up to two typos will be tried, e.g. Cairo (no typos), cAIRO (one typo: caps lock), CCairoo (two typos: both repeats), and cAIROO (two typos: one of each type) will be tried. Adding lots of typo types to the command line can significantly increase the number of combinations, and increasing the --typos count can be even more dramatic, so it’s best to tread lightly when using this feature unless you have a small token file or passwordlist.
Here are some additional types of typos that require a bit more explanation:
-
--typos-closecase- Like--typos-case, but it only tries changing the case of a letter if that letter is next to another letter with a different case, or if it's at the beginning or the end. This produces fewer combinations to try so it will run faster, and it will still catch the more likely instances of someone holding down shift for too long or for not long enough. -
--typos-replace s- This tries replacing each single character with the specified string (in the example, ans). The string can be a single character, or some longer string (in which case each single character is replaced by the entire string), or even a string with one or more expanding wildcards in it. For example,--typos 1 --typos-replace %awould try replacing each character (one at a time) with a lower-case letter, working through all possible combinations. Using wildcards can drastically increase the total number of combinations. -
--typos-insert s- Just like--typos-replace, but instead of replacing a character, this tries inserting a single copy of the string (or the wildcard substitutions) in between each pair of characters, as well as at the beginning and the end.Even when
--typosis greater than 1,--typos-insertwill not normally try inserting multiple copies of the string at the same position. For example, with--typos 2 --typos-insert Zspecified, guesses such asCaiZroandCZairoZare tried, butCaiZZrois not. You can change this by using--max-adjacent-inserts #with a number greater than 1.
-
--typos-map typos.txt- This is a relatively complicated, but also flexible type of typo. It tries replacing certain specific characters with certain other specific characters, using a separate file (in this example, namedtypos.txt) to spell out the details. For example, if you know that you often make mistakes with punctuation, you could create a typos-map file which has these two lines in it:. ,/; ; [‘/.In this example, btcrecover will try replacing each
.with one of the three punctuation marks which follow the spaces on the same line, and it will try replacing each;with one of the four punctuation marks which follow it.This feature can be used for more than just typos. If for example you’re a fan of “1337” (leet) speak in your passwords, you could create a typos-map along these lines:
aA @ sS $5 oO 0This would try replacing instances of
aorAwith@, instances ofsorSwith either a$or a5, etc., up to the maximum number of typos specified with the--typos #option. For example, if the token file contained the tokenPasswords, and if you specified--typos 3,P@55wordsandPa$sword5would both be tried because they each have three or fewer typos/replacements, butP@$$w0rd5with its 5 typos would not be tried.The btcrecover package includes a few typos-map example files in the
typosdirectory. You can read more about them in the Typos Quick Start Guide
As described above, the --typos # command-line option limits the total number of typos, regardless of type, that will ever be applied to a single guess. You can also set limits which are only applied to specific types of typos. For each of the --typos-xxxx command-line options above there is a corresponding --max-typos-xxxx # option.
For example, with --typos 3 --typos-delete --typos-insert %a --max-typos-insert 1, up to three typos will be tried. All of them could be delete typos, but at most only one will ever be an insert typo (which would insert a single lowercase letter in this case). This is particularly useful when --typos-insert and --typos-replace are used with wildcards as in this example, because it can greatly decrease the total number of combinations that need to be tried, turning a total number that would take far too long to test into one that is much more reasonable.
Depending on the number of passwords which need to be tried, running btcrecover might take a very long time. If it is interrupted in the middle of testing (with Ctrl-C (see below), due to a reboot, accidentally closing the Command Prompt, or for any other reason), you might lose your progress and have to start the search over from the beginning. To safeguard against this, you can add the --autosave savefile option when you first start btcrecover. It will automatically save its progress about every 5 minutes to the file that you specify (in this case, it was named savefile – you can just make up any file name, as long as it doesn’t already exist).
If interrupted, you can restart testing by either running it with the exact same options, or by providing this option and nothing else: --restore savefile. btcrecover will then begin testing exactly where it had left off. (Note that the token file, as well as the typos-map file, if used, must still be present and must be unmodified for this to work. If they are not present or if they’ve been changed, btcrecover will refuse to start.)
The autosave feature is not currently supported with passwordlists, only with token files.
If you need to interrupt btcrecover in the middle of testing, you can do so with Ctrl-C (hold down the Ctrl key and press C) and it will respond with a message such this and then it will exit:
Interrupted after finishing password # 357449
If you didn't have the autosave feature enabled, you can still manually start testing where you left off. You need to start btcrecover with the exact same token file or passwordlist, typos-map file (if you were using one), and command-line options plus one extra option, --skip 357449, and it will start up right where it had left off.
Just download the latest version from https://github.com/gurnec/btcrecover/archive/master.zip and unzip it to a location of your choice. There’s no installation procedure for btcrecover itself, however there are additional requirements below depending on your operating system and the wallet type you’re trying to recover.
You must have Armory installed if you’re trying to recover an Armory password. btcrecover has only been tested with Armory versions 0.91 through 0.92.3; other versions may not work at all or may only work after some changes have been made. If btcrecover is unable to locate the Armory installation directory automatically, you may need to move the btcrecover files into the Armory Program Files or lib directory, or learn how to use the PYTHONPATH environment variable.
In addition to requiring Armory, you will also need to download and install:
- The latest version of Python 2.7, 32-bit (it must be the 32-bit version). Currently this is the “Python 2.7.8 Windows Installer” available here: https://www.python.org/download/
With this combination, you will also need to download and 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.8 Windows Installer” for the 32-bit version, or “Python 2.7.8 Windows X86-64 Installer” for the 64-bit version (which is preferable if you have a 64-bit version of Windows and don't plan on using GPU acceleration), both available here: https://www.python.org/download/
Please note that for Blockchain wallets, Python version 2.7.8 or greater is highly recommened, and will run approximately 5 times faster than earlier versions.
-
Optional, but highly recommended for MultiBit or Electrum (for a 30x speed improvement): The latest binary version of PyCrypto for Python 2.7, either the 32-bit version or the 64-bit version to match your version of Python. Currently this is “PyCrypto 2.6 for Python 2.7 32bit” or “PyCrypto 2.6 for Python 2.7 64bit” available here: http://www.voidspace.org.uk/python/modules.shtml#pycrypto
-
Optional, allows btcrecover to run as a low-priority process so it doesn’t hog your CPU and slightly improves autosave safety: The latest version of pywin32 for Python 2.7, either the 32-bit version or the 64-bit version to match your version of Python. Currently this is “pywin32-219.win32-py2.7.exe” for the 32-bit version or “pywin32-219.win-amd64-py2.7.exe” for the 64-bit version available in the “Build 219” folder here: http://sourceforge.net/projects/pywin32/files/pywin32/
To enable the experimental GPU acceleration features in Windows, you will need to download and install the 32-bit version of Python 2.7 plus the optional components you'd like as detailed above (and only this version, no other version of Python can be installed except the 32-bit version of Python 2.7 plus any optional libraries), and you will also need to download and install:
-
The latest binary version of PyOpenCL for Python 2 & Python(x,y) available here: https://code.google.com/p/pythonxy/wiki/AdditionalPlugins. (The download link on that page is a button to the right of “pyopencl” which has an arrow pointing downwards.)
-
The latest binary version of NumPy for Python 2.7. Currently this is “numpy-1.9.1-win32-superpack-python2.7.exe”, available in the "1.9.1" folder here: http://sourceforge.net/projects/numpy/files/NumPy/
-
The latest version of Python setuptools. Installation instructions for setuptools can be found here: https://pypi.python.org/pypi/setuptools#installation-instructions
-
Optional, but recommended Bitcoin Core or Litecoin-Qt (for a 2x speed improvement): The latest binary version of PyCrypto for Python 2.7. Currently this is “PyCrypto 2.6 for Python 2.7 32bit” available here: http://www.voidspace.org.uk/python/modules.shtml#pycrypto
If you encounter the error ImportError: DLL load failed when running btcrecover, you will also need to copy the file named boost_python-vc90-mt-1_54.dll from the C:\Python27\DLLs\ directory into the C:\Python27\Lib\site-packages\pyopencl\ directory (this is apparently a bug in the PyOpenCL installer).
-
Python 2.7.x – Most distributions include this pre-installed. Please note that for Blockchain wallets, Python version 2.7.8 or greater is highly recommened, and will run approximately 5 times faster than earlier versions.
-
Optional, but highly recommended for MultiBit or Electrum: PyCrypto for Python 2.7.x – Many distributions include this pre-installed, check your distribution’s package management system to see if this is available. It is often called “python2.7 crypto” or just “python-crypto”. If not, try installing it by using PyPI, for example on Debian-like distributions:
sudo apt-get install python-pip sudo pip install pycryptoOn OS X, installing PyCrypto is unfortunately a bit more difficult:
-
Download and install the "Command Line Tools for Xcode" for your version of OS X from Apple here: https://developer.apple.com/downloads/. This site requires that you register as an Apple Developer using your Apple ID.
-
Open a Terminal window, and install Python pip and then PyCrypto:
curl https://bootstrap.pypa.io/get-pip.py | sudo python sudo pip install pycrypto
-
(Also see the Quick Start section.) After you've installed all of the requirements (above) and have downloaded the latest version:
-
Unzip the
btcrecover-master.zipfile, it contains a single directory named "btcrecover-master". Inside the btcrecover-master directory is the Python script (program) filebtcrecover.py. -
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...”, 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 - Bitcoin Core -
%appdata%\Bitcoin - Electrum -
%appdata%\Electrum\wallets - Litecoin-Qt -
%appdata%\Litecoin - MultiBit - Please see the Finding MultiBit Wallet Files section below
- Armory -
-
If you have a
btcrecover-tokens-auto.txtfile, you're almost done. Copy it into the directory which containsbtcrecover.py, and then simply double-click thebtcrecover.pyfile, and btcrecover should begin testing passwords. (You may need to rename your wallet file if it doesn't match the file name listed insided thebtcrecover-tokens-auto.txtfile.) If you don't have abtcrecover-tokens-auto.txtfile, continue reading below. -
Copy your
tokens.txtfile, or your passwordlist file if you're using one, into the directory which containsbtcrecover.py. -
You will need to run
btcrecover.pywith at least two command-line options,--wallet FILEto identify the wallet file name and either--tokenlist FILEor--passwordlist FILE(the FILE is optional for--passwordlist), depending on whether you're using a Token File or Passwordlist. If you're using Typos or Autosave, please refer the sections above for additional options you'll want to add. -
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.
cd \Users\Chris\Downloads\btcrecover-master C:\python27\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 section below. 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 option may be able to help).
Counting passwords ...
Done
Using 4 worker threads
439 of 7661527 [-------------------------------] 0:00:10, ETA: 2 days, 0:25:56
If one of the combinations is the correct password for the wallet, the password will eventually be displayed and btcrecover will stop running:
1298935 of 7661527 [####-----------------------] 8:12:42, ETA: 1 day, 16:13:24
Password found: 'Passwd42'
If all of the password combinations are tried, and none of them were correct for the wallet, this message will be dislayed instead:
7661527 of 7661527 [########################################] 2 days, 0:26:06,
Password search exhausted
Running btcrecover.py with the --help option will give you a summary of all of the available command-line options, most of which are described in the sections above.
If you'd just like to test your token file and/or chosen typos, you can use the --listpass option in place of the --wallet FILE option as demonstrated below. btcrecover will then list out all the passwords to the screen instead of actually testing them against a wallet file. This can also be useful if you have another tool which can test some other type of wallet, and is capable of taking a list of passwords to test from btcrecover. Because this option can generate so much output, you may want only use it with short token files and few typo options.
C:\python27\python btcrecover.py --listpass --tokenlist tokens.txt | more
The | more at the end (the | symbol is a shifted \ backslash) will introduce a pause after each screenful of passwords.
btcrecover doesn’t operate directly on MultiBit wallet files, instead it operates on MultiBit private key backup files. When you first add a password to your MultiBit wallet, and after that each time you add a new receiving address or change your wallet password, MultiBit creates an encrypted private key backup file in a key-backup directory that's near the wallet file. These private key backup files are much faster to try passwords against (by a factor of over 1,000), which is why btcrecover uses them. For the default wallet that is created when MultiBit is first installed, this directory is located here:
%appdata%\MultiBit\multibit-data\key-backup
The key files have names which look like walletname-20140407200743.key. If you've created additional wallets, their key-backup directories will be located elsewhere and it's up to you to locate them. Once you have, choose the most recent .key file and copy it into the directory containing btcrecover.py for it to use.
For more details on locating your MultiBit private key backup files, see: https://www.multibit.org/en/help/v0.5/help_fileDescriptions.html
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 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.
In order to use this feature, you must have a card and drivers which support OpenCL (most AMD and NVIDIA cards and drivers already support OpenCL on Windows), and you must install the required Python libraries as described in the Windows GPU acceleration section. GPU acceleration should also work on Linux and OS X, however instructions for installing the required Python libraries are not currently included in this tutorial.
Due to its experimental status, it's highly recommended that you run the GPU unit tests before running it with a wallet. The two commands below will run the relevant tests for Bitcoin Core and Armory, respectively (or you can leave out the test names to run all of the unit tests if you'd prefer). The "_sli" tests will be skipped and can be ignored if you don't have multiple identical GPUs installed in your system.
C:\python27\python test-btcr.py -v Test08KeyDecryption.test_bitcoincore_cl Test08KeyDecryption.test_bitcoincore_cl_sli
C:\python27\python test-btcr.py -v Test08KeyDecryption.test_armory_cl Test08KeyDecryption.test_armory_cl_mem_factor Test08KeyDecryption.test_armory_cl_sli
Assuming the tests do not fail, GPU support can be enabled by adding the --enable-gpu option to the command line. There are other additional options, specifically --global-ws and --local-ws, which should also be provided along with particular values to improve the search performance. Unfortunately, the exact values for these options can only be determined by trial and error, as detailed below.
A good starting point for these wallets is:
C:\python27\python btcrecover.py --wallet wallet.dat --performance --enable-gpu --global-ws 4096 --local-ws 512
The --performance option tells btcrecover to simply measure the performance until Ctrl-C is pressed, and not to try testing any particular passwords. You will still need a wallet file (or an --extract-data option) for performance testing. After you you have a baseline from this initial test, you can try different values for --global-ws and --local-ws to see if they improve or worsen performance.
Finding the right values for --global-ws and --local-ws can make a 10x improvement, so it's usually worth the effort.
Generally when testing, you should increase or decrease these two values by powers of 2, for example you should increase or decrease them by 128 or 256 at a time. It's important to note that --global-ws must always be evenly divisible by --local-ws, otherwise btcrecover will exit with an error message.
Although this procedure can be tedious, with larger tokenlists or passwordlists it can make a significant difference.
Performance tuning for Armory is similar to tuning for Bitcoin Core, but unfortunately it's much more complex. Armory uses a memory-hard key derivation function called ROMix-SHA-512 which is specifically designed to resist GPU-based acceleration. You should start by reading the section above, which also applies to Armory. In addition to --global-ws and --local-ws, there is a third option, --mem-factor, which affects the GPU memory usage, and as a consequence overall performance.
GPU memory usage is directly proportional to --global-ws. The larger the --global-ws, the more GPU memory is used. With Armory wallets, a larger --global-ws usually improves performance, so you should start with a --global-ws that is as high as your GPU will allow. In order to help you locate this value, you can run btcrecover with the --calc-memory options, as seen below:
C:\python27\python btcrecover.py --wallet armory_2dRkxw76K_.wallet --enable-gpu --calc-memory
Details for this wallet
ROMix V-table length: 32,768
outer iteration count: 4
with -mem_factor 1 (the default),
memory per global worker: 2,048 KB
Details for GeForce GTX 560 Ti
global memory size: 1,024 MB
with -mem_factor 1 (the default),
est. max --global-ws: 480
with --global-ws 4096 (the default),
est. memory usage: 8,192 MB
So for this particular wallet and GPU, a --global-ws of around 480 is the maximum supported, and this would be a good starting point for performance searching:
C:\python27\python btcrecover.py --wallet armory_2dRkxw76K_.wallet --enable-gpu --global-ws 480 --local-ws 32 --performance
If this generates a memory allocation error message (and it probably will), try decreasing --global-ws by 32 or 64 at a time until it succeeds. Once you've determined a good --global-ws (near its maximum) and a good --local-ws (through trial and error, unfortunately), you can move onto the next step.
The --mem-factor # option decreases memory usage by the factor specified, allowing you to use a larger --global-ws. Next, you should try the same procedure above, but use a higher --mem-factor (the default is 1) to see if performance can be further improved. In this example, I've determined that the best settings so far are --global-ws 448 --local-ws 64, and now I'm starting with these values and adding --mem-factor 2:
C:\python27\python btcrecover.py --wallet armory_2dRkxw76K_.wallet --enable-gpu --global-ws 448 --local-ws 64 --mem-factor 2 --calc-memory
Details for this wallet
ROMix V-table length: 32,768
outer iteration count: 4
with -mem_factor 2,
memory per global worker: 1,024 KB
Details for GeForce GTX 560 Ti
global memory size: 1,024 MB
with -mem_factor 2,
est. max --global-ws: 992
with --global-ws 448,
est. memory usage: 448 MB
So for the next round of testing, we should start somewhere around --global-ws 992 --local-ws 64 --mem-factor 2, except that 992 isn't evenly divisible by 64, so we reduce it until it is evenly divisible which results in starting values of --global-ws 960 --local-ws 64 --mem-factor 2.
For the next few rounds of testing, you can generally keep --local-ws at the same value, and just focus on determining the highest value of --global-ws which provides the best performance for each successively larger value of --mem-factor. Eventually you will reach a point where increasing --mem-factor and --global-ws will no longer provide any performance benefit, and may actually start hurting performance. This is generally the best you can get with this particular wallet and GPU combination. In this example, the best I could get was at these settings which resulted in a 3.5x improvement over my quad-core CPU, or a 6x improvement when using two GPUs:
C:\python27\python btcrecover.py --wallet armory_2dRkxw76K_.wallet --enable-gpu --global-ws 2816 --local-ws 128 --mem-factor 6 --performance
This procedure is definitely tedious, so it's up to you to decide whether the improvement you might realize is worth it.
If you'd prefer, you can also place command-line options directly inside the tokens.txt file. In order to do this, the very first line of the tokens file must begin with exactly #--, and the rest of this line (and only this line) is interpreted as additional command-line options. For example, here's a tokens file which enables autosave, pause-before-exit, and one type of typo:
#--autosave progress.sav --pause --typos 1 --typos-case
Cairo
Beetlejuice Betelgeuse
Hotel_california
Normally, when you run btcrecover it expects you to run it with at least a few options, such as the location of the tokens file and of the wallet file. If you run it without specifying --tokenlist or --passwordlist, it will check to see if there is a file named btcrecover-tokens-auto.txt in the current directory, and if found it will use that for the tokenlist. Because you can specify options inside the tokenlist file if you'd prefer (see above), this allows you to run btcrecover without using the command line at all. You may want to consider using the --pause option to prevent a Command Prompt window from immediately closing once it's done running if you decide to run it this way.
Although this software is unlikely to harm any wallet files, you are strongly encouraged to only run it with copies of your wallets. In particular, this software is distributed WITHOUT ANY WARRANTY; please see the accompanying GPLv2 licensing terms for more details.
Because this software is beta software, and also because it interacts with other beta software, it’s entirely possible that it may fail to find a password which it’s been correctly configure by you to find.
By default, btcrecover uses one or more whitespaces to separate tokens in the tokenlist file, and to separated to-be-replaced characters from their replacements in the typos-map file. It also ignores any extra whitespace in these files. This makes it difficult to test passwords which include spaces and certain other symbols.
One way around this, which only works for the tokenlist file, is to use the %s wildcard which will be replaced by a single space. Another option, which works both for the tokenlist file and a typos-map file, is using the --delimiter which option allows you to change this behavior. If used, whitespace is no longer ignored, nor is extra whitespace stripped. Instead, the new --delimiter string must be used exactly as specified to separate tokens or typos-map columns. Any whitespace becomes a part of a token, so you must take care not to add any inadvertent whitespace to these files.
Additionally, btcrecover considers the following symbols special under certain specific circumstances in the tokenlist file (and for the # symbol, also in the typos-map file). A special symbol is part of the syntax, and not part of a password.
%- always considered special;%%in a token will be replaced by%during searches^- only special if it's the first character of a token;%^will be replaced by^during searches$- only special if it's the last character of a token;%S(note the capitalS) will be replaced by$during searches#- only special if it's the very first character on a line, the rest of the line is then ignored (a comment); note that if#--is at the very beginning of the tokenlist file, then the first line is parsed as additional command-line options+- only special if it's the first token (after possibly stripping whitespace) on a line, followed by a delimiter, and then followed by other token(s) (see the Mutual Exclusion section); if you need a+character in a token, make sure it's either not first on a line, or it's part of a larger token, or it's on a line all by itself
None of this applies to passwordlist files, which always treat spaces and symbols (except for carriage-returns and line-feeds) verbatim, treating them as parts of a password.
Although Unicode support is available in btcrecover, its use is considered experimental and is currently undocumented in this tutorial. More information may be available in the GitHub issues list.
When btcrecover starts, it's first task is to count all the passwords it's about to try, looking for and recording duplicates for future reference (so that no password is tried twice) and also so it can display an ETA. This duplicate checking can take a lot of memory, depending on how many passwords need to be counted, but in some circumstances it can also save a lot of time. If btcrecover appears to hang after displaying the Counting passwords ... message, or if it outright crashes, try running it again with the --no-dupchecks option. After this initial counting phase, it doesn't use up much RAM as it searches through passwords.
Although this initial counting phase can be skipped by using the --no-eta option, it's not recommended. If you do use --no-eta, it's highly recommended that you also use --no-dupchecks at the same time.
You may want to always use a single --no-dupchecks option when working with MultiBit or Electrum wallets because the duplicate checking can actually decrease CPU efficiency (and always decreases memory efficiency) with these wallets in many cases.
If you specify --no-dupchecks more than once, it will disable even more of the duplicate checking logic:
- 1 time - disables the most comprehensive and also the most memory intensive duplicate checking
- 2 times - disables duplicate checking that rarely consumes much memory relative to the time it saves, although it may if the tokenlist file has a large number of tokens on relatively few lines with at least one but relatively few identical tokens
- 3 times - disables duplicate checking which consumes very little memory relative to the duplicates it can potentially find; it's almost never useful to use this level
- 4 times - disables duplicate checking which consumes no additional memory; it's never useful to use this level (and it's only available for debugging purposes)
By default, btcrecover tries to use as much CPU time as is available and spare. You can use the --threads option to decrease the number of worker threads (which defaults to the number of logical processors in your system) if you'd like to decrease CPU usage (but also the guess rate).
With MultiBit or Electrum wallets, btcrecover may not be able to efficiently use more than four or five CPU cores, sometimes even less depending on the contents of the tokenlist and the chosen typos. Specifying the --no-dupchecks option may help improve CPU usage and therefore the password guess rate in many cases with these two wallet types, and using slightly fewer or slightly greater --threads might also help. The only way to find out is to experiment.
btcrecover places itself in the lowest CPU priority class to minimize disruption to your PC while searching (but for Windows, it can only do this if you've installed the optional pywin32).
As already mentioned, MultiBit HD is not supported. Electrum BIP32 wallets are also currently unsupported.
Most Bitcoin wallet software goes to great lengths to protect your wallet password while it's stored unencrypted. btcrecover does not. This includes, but is not limited to:
- you must create the tokenlist file which will probably have lots of sensitive password information in it, and save it to an unencrypted file;
- no attempt is made to overwrite sensitive password information in RAM during or after running;
- unless you use the
--no-dupchecksoption, a large amount of sensitive password information is stored in RAM temporarily, is not securely overwritten, and is very likely swapped out to the paging file where it could remain for a long time even after btcrecover has exited.
None of these issues are intentionally malicious, they should be considered security bugs. There are no workarounds for them, short of only running btcrecover inside a VM on a hard disk drive (not a solid-state drive) and securely deleting the VM once finished, all of which is far beyond the scope of this tutorial...
The intent of the typos features is to only apply at most one typo at a time to any single character, even when applying multiple typos to a single password guess. For example, when specifying --typos 2 --typo-case --typo-repeat, each password guess can have up to two typos applied (so two case changes, or two repeated characters, or one case change plus one repeated character, at most). No single character in a guess will have more than one typo applied to it in a single guess, e.g. a single character will never be both repeated and case-changed at the same time.
There are however some exceptions to this one-typo-per-character rule-- one intentional, and one due to limitations in the software.
The --typos-capslock typo simulates leaving the caps lock turned on during a guess. It can affect all the letters in a password at once even though it's a single typo. As in exception to the one-typo-per-character rule, a single letter can be affected by a caps lock typo plus another typo at the same time.
The --typos-swap typo also ignores the one-typo-per-character rule. Two adjacent characters can be swapped (which counts as one typo) and then a second typo can be applied to one (or both) of the swapped characters. This is more a software limitation than a design choice, but it's unlikely to change. You are however guaranteed that a single character will never be swapped more than once per guess.
Finally it should be noted that wildcard substitutions (expansions and contractions) occur before typos are applied, and that typos can be applied to the results of wildcard expansions. The exact order of password creation is:
- Create a "base" password from one or more tokens, following all the token rules (mutual exclusion, anchors, etc.).
- Apply all wildcard expansions and contractions.
- Apply up to a single caps lock typo.
- Apply zero or more swap typos.
- Apply zero or more character-changing typos (these typos do follow the one-typo-per-character rule).
- Apply zero or more typo insertions (from the
typos-insertoption).
At no time will the total number of typos in a single guess be more than requested with the --typos # option (nor will it be less than the --min-typos option if it's used).
btcrecover.py -- Bitcoin wallet password recovery tool
Copyright (C) 2014 Christopher Gurnee
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License version 2 for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.