Skip to content

Latest commit

 

History

History
530 lines (332 loc) · 45.2 KB

TUTORIAL.md

File metadata and controls

530 lines (332 loc) · 45.2 KB
Raw

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.

If you find btcrecover helpful, please consider a small donation to help support my efforts: 17LGpN2z62zp7RS825jXwYtE7zZ19Mxxu8

Thank You!

Quick Start

This tutorial is pretty long... you don't have to read the whole thing. Here are some places to start.

  1. Read the Installation Guide for instructions and download links.
  2. (optional) Run the unit tests by double-clicking on run-all-tests.py. If you encounter any failures, please report them here.
  3. If you already have a btcrecover-tokens-auto.txt file, skip straight to step 6. If not, and you need help creating passwords from different combinations of smaller pieces you remember, start with step 4. 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 5.
  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.txt file you'll need later.
  5. 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 skipped step 4 above, read the simple Passwordlist section instead.
  6. 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.
  7. (optional, but highly recommended) Donate huge sums of Bitcoin to the donation address above once your password's been found.

The Token File

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 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). Note that if your password contains any non-ASCII (non-English) characters, you should read the section on Unicode Support before continuing.

Basics

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.

Mutual Exclusion

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.

Required Tokens

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!

Anchors

Beginning and Ending Anchors

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).

Positional Anchors

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

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

Token Counts

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.

Expanding Wildcards

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 a c, h, a, r, or s)
  • %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 %p or %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 %c if %c has 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 capital S that 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

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 - Test00 through Test99, but never Test12
  • Test%d%2b - Test000 through Test999, but never Test123
  • Test%d%0,3b - Test0 to Test9 (the backreference length is 0), Test00 to Test99, etc., Test0000 to Test9999

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 - Testt
  • Test%;1b - starts 1 back, same as above, Testt
  • Test%;2b - starts 2 back, Tests
  • Test%;4b - starts 4 back, TestT
  • Test%2;4b - starts 4 back, with a copy length of 2: TestTe
  • Test%8;4b - starts 4 back, with a copy length of 8: TestTestTest
  • Test%0,2;4b - starts 4 back, with a copy length from 0 to 2: Test, TestT, and TestTe
  • %2Atest%2;6b - patterns such as ABtestAB and XKtestXK where the two capital letters before and after test match each other, but never ABtestXK where 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.

Contracting Wildcards

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.

Keyboard Walking — Backreference Wildcards, revisited

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 to 0 through 9

  • %b - copies the previous character, so no we have 00 through 99

  • test - now we have 00test through 99test

  • %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 characters
    • 6 - how far to the left of the wildcard to start copying; 6 characters counting leftwards from the end of 00test is the first 0

    The result of expanding this wildcard when the token starts off with 00test is 00test11. It expands into two 1's because the copy length is 2, and it expands into modified 1's instead of just copying the 0's because the file maps a 0 (in its first column) to a 1 (in the second column). Likewise, a 77test is expanded into 77test88. 99test is expanded into 99test99 because the the lookup character, a 9, 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

The Passwordlist

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 your password contains any non-ASCII (non-English) characters, you should read the section on Unicode Support before continuing.

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.

Typos

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, an s). 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 %a would 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 --typos is greater than 1, --typos-insert will not normally try inserting multiple copies of the string at the same position. For example, with --typos 2 --typos-insert Z specified, guesses such as CaiZro and CZairoZ are tried, but CaiZZro is not. You can change this by using --max-adjacent-inserts # with a number greater than 1.

Typos Map

  • --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, named typos.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    0

    This would try replacing instances of a or A with @, instances of s or S with either a $ or a 5, etc., up to the maximum number of typos specified with the --typos # option. For example, if the token file contained the token Passwords, and if you specified --typos 3, P@55words and Pa$sword5 would both be tried because they each have three or fewer typos/replacements, but P@$$w0rd5 with its 5 typos would not be tried.

    The btcrecover package includes a few typos-map example files in the typos directory. You can read more about them in the Typos Quick Start Guide.

Max Typos by Type

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.

Autosave

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.

Interrupt and Continue

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.

Unicode Support

If your password contains any non-ASCII (non-English) characters, you will need to add the --utf8 command-line option to enable Unicode support.

Please note that all input to and output from btcrecover must be UTF-8 encoded (either with or without a Byte Order Mark, or "BOM"), so be sure to change the Encoding to UTF-8 when you save any text files. For example in Windows Notepad, the file Encoding setting is right next to the Save button in the File -> Save As... dialog.

On Windows (but usually not on Linux or OS X), you may have trouble if any of the command line options you need to use contain any non-ASCII characters. Usually, if it displays in the command prompt window correctly when you type it in, it will work correctly with btcrecover.py. If it doesn't display correctly, please read the section describing how to put command-line options inside the tokens file.

Also on Windows (but usually not on Linux or OS X), if your password is found it may not be displayed correctly in the command prompt window. Here is an example of what an incorrect output might look like:

Password found: 'btcr-????-??????'
HTML encoded:   'btcr-&#1090;&#1077;&#1089;&#1090;-&#1087;&#1072;&#1088;&#1086;&#1083;&#1100;'

As you can see, the Windows command prompt was incapable of rendering some of the characters (and they were replaced with ? characters). To view the password that was found, copy and paste the HTML encoded line into a text file, and save it with a name that ends with .html instead of the usual .txt. Double-click the new .html file and it will open in your web browser to display the correct password:

HTML encoded: 'btcr-тест-пароль'

Running btcrecover

(Also see the Quick Start section.) After you've installed all of the requirements (above) and have downloaded the latest version:

  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 Wallet for Android/BlackBerry, lost spending PINs - Please see the Bitcoin Wallet for Android/BlackBerry Spending PINs section below.
    • MultiBit Classic - Please see the 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)
    • Electrum - %appdata%\Electrum\wallets
    • BIP-39 passphrases (e.g. TREZOR) - Please see the BIP-39 Passphrases section below.
    • mSIGNA - %homedrive%%homepath% (it's a .vault file)
    • Bither - %appdata%\Bither (it's named address.db)
    • Blockchain.info - it's usually named wallet.aes.json; if you don't have a backup of your wallet file, you can download one by running the download-blockchain-wallet.py tool in the extract-scripts directory if you know your wallet ID (and 2FA if enabled)
    • Litecoin-Qt - %appdata%\Litecoin (it's named wallet.dat)

  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 or Passwordlist. If you're using Typos or 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.

    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. 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.

Testing your config

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.

Finding MultiBit Classic Wallet Files

btcrecover doesn’t operate directly on MultiBit Classic wallet files, instead it operates on MultiBit private key backup files. When you first add a password to your MultiBit Classic 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

Bitcoin Wallet for Android/BlackBerry Spending PINs

Bitcoin Wallet for Android/BlackBerry has a spending PIN feature which can optionally be enabled. If you lose your spending PIN, you can use btcrecover to try to recover it.

  1. Open the Bitcoin Wallet app, press the menu button, and choose Safety.
  2. Choose Back up wallet.
  3. Type in a password to protect your wallet backup file, and press OK. You'll need to remember this password for later.
  4. Press the Archive button in the lower-right corner.
  5. Select a method of sharing the wallet backup file with your PC, for example you might choose Gmail or perhaps Drive.

This wallet backup file, once saved to your PC, can be used just like any other wallet file in btcrecover with one important exception: when you run btcrecover, you must add the --android-pin option. When you do, btcrecover will ask you for your backup password (from step 3), and then it will try to recover the spending PIN.

Because PINs usually just contain digits, your token file will usually just contain something like this (for PINs of up to 6 digits for example): %1,6d. (See the section on Wildcards for more details.)

Note that if you don't include the --android-pin option, btcrecover will try to recover the backup password instead.

BIP-39 Passphrases

Some BIP-39 compliant wallets offer a feature to add a “BIP-39 passphrase” to your seed (mnemonic), most notably the TREZOR hardware wallet. Note that TREZOR also offers a PIN feature which is not supported by btcrecover.

If you know your seed, but need help recovering your passphrase, btcrecover may be able to help. You will also need to know either:

  1. Preferably your master public key / “xpub” (for the first account in your wallet, if it supports multiple accounts), or
  2. a receiving address that was generated by your wallet (in its first account), along with a good estimate of how many addresses you created before the receiving address you'd like to use.

Once you have this information, run btcrecover normally, except that instead of providing a wallet file on the command line as described above with the --wallet wallet.dat option, use the --bip39 option, e.g.:

C:\python27\python btcrecover.py --bip39 --tokenlist tokens.txt --other-options...

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

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.

For more information, please see the GPU Acceleration Guide.

command-line options inside the tokens file

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

btcrecover-tokens-auto.txt

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.

Limitations & Caveats

Beta Software

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.

Additional Limitations & Caveats

Please see the separate Limitations and Caveats documentation for additional details on these topics:

  • Delimiters, Spaces, and Special Symbols in Passwords
  • Memory & CPU Usage
  • Security Issues
  • Typos Details

Copyright and License

btcrecover -- Bitcoin wallet password and seed recovery tool

Copyright (C) 2014-2016 Christopher Gurnee

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

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 for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/