Split off guide for recovering coins from backup files into a README.…

…recover.

wallet/README

@@ -22,9 +22,8 @@ Your wallet can be manually backed up to and restored from external storage:
 
 	Testnet: /sdcard/Download/bitcoin-wallet-backup-testnet-<yyyy-MM-dd>
 
-The manual backup files are encrypted using your chosen backup password. You can use OpenSSL to decrypt:
-
-	openssl enc -d -aes-256-cbc -a -in <filename>
+If you want to recover coins from manual backups and for whatever reason you cannot use the app
+itself to restore from the backup, see the separate README.recover guide.
 
 
 DEBUGGING

wallet/README.recover

@@ -0,0 +1,149 @@
+PROLOGUE
+
+This document describes how you can use a backup file on a standard PC to recover your Bitcoins.
+Normally, this shouldn't be needed. It is much preferred to just use Options > Safety > Restore
+wallet from within the Bitcoin Wallet app if you can. This guide is only meant for rare cases:
+
+- Your Android device is destroyed or missing and you do not want or cannot get a new Android
+  device.
+- Legislation in your country forbids you to continue using the app and you missed the chance to
+  move your coins out while it was still legal.
+- The app suddenly goes out of service for whatever reason. This event is extremely unlikely,
+  given the fact that the app is open source and many developers from all over the world have and
+  know the code.
+
+Be aware some of the steps in this tutorial require handling your private keys in the unencrypted
+form. Do not expose them to anyone. Whoever knows your private keys can spend your coins on these
+keys. It'd good practise that after you are finished handling these keys, they should be
+considered compromised, even if they are not. Make sure your system is free of any malware.
+
+We recommend using Ubuntu Linux. You can boot from a Live CD if you want, but if you do please
+refrain from sending your coins to a temporary wallet created in that environment, which would be
+lost e.g. on a power outage or computer failure. Your desired destination wallet should already be
+set up and you should have one of its receiving addresses or a QR code at hand.
+
+You should be at least a bit familiar with the Linux shell. Commands indented in this document
+are meant to be executed as a shell command. Before you execute each command by pressing return,
+make sure to understand what it does. You will need to adjust some file or directory names.
+Commands starting with "sudo apt-get" will ask for your permission to install software by
+requiring your Ubuntu user password.
+
+
+PREPARATION
+
+On your PC, install the following Ubuntu packages:
+
+	sudo apt-get install android-tools-adb openssl git maven
+
+On your Android device, go to Settings > Developer options and enable "USB debugging". On most
+recent devices you need to go to Settings > About first and tap on "Build number" multiple times
+until you see the "You are now a developer" message.
+
+
+LOCATING THE BACKUP FILES
+
+If you followed the apps guidance your backup files will be located both on-device and off-device.
+Let's look at off-device first. When backing up, the app instructed you to archive your backup to
+mail or cloud storage. Depending on how you decided, your backup probably ended up as attachment
+on a mail sent to yourself (look into your Inbox and Sent folders) or uploaded to a Google Drive
+or Dropbox kind of service. Just save the backup file to your PCs filesystem. Skip the rest of this
+paragraph directly to DECRYPTING.
+
+You cannot find your backup? If you're still using the device you made the backup with, there is
+a good chance the backup is on-device. Use
+
+	adb shell ls -l /sdcard/Download/bitcoin-wallet-*
+
+It will list any backup files present. Pick one and use
+
+    adb pull /sdcard/Download/bitcoin-wallet-backup-testnet-2014-11-01
+
+to copy the file to your PC.
+
+
+DECRYPTING
+
+You now have your backup file on your PC. Wallet backups are encrypted. Let's decrypt it using:
+
+	openssl enc -d -aes-256-cbc -a -in bitcoin-wallet-backup-testnet-2014-11-01 > bitcoin-wallet-decrypted-backup
+
+It will ask you for a decryption password, which is your backup password. If it prints
+"bad password" you've got the wrong password, but if it doesn't print anything your password might
+still be wrong. We can only be sure by looking at the decrypted data.
+
+Historically there is two backup formats. Let's look at the first printable characters in the file:
+
+	cat bitcoin-wallet-decrypted-backup | tr -cd "[:print:]" | awk '{print $1}'
+
+If it prints "org.bitcoin.production", you got the right password and the backup file uses the
+bitcoinj protobuf format. This backup format was introduced in v3.47 (May 2014). Skip to
+RECOVERING FROM PROTOBUF WALLET FORMAT.
+
+If it prints just a hash sign (#), you got the right password and the backup file uses the old
+text based private key format. Skip to RECOVERING FROM BASE58 KEY FORMAT.
+
+If it prints something else or nothing, you likely didn't get the password right. Passwords are
+case sensitive, and make sure you didn't accidently type a space character in front or after the
+password.
+
+
+RECOVERING FROM PROTOBUF WALLET FORMAT
+
+We need wallet-tool from bitcoinj. First, in a working directory, let's get bitcoinj:
+
+	git clone -b release-0.12 https://github.com/bitcoinj/bitcoinj.git
+
+Make sure everything is compiled and ready to go by using once:
+
+	cd bitcoinj/tools
+	./wallet-tool
+
+Now use wallet-tool to sync the wallet from your backup:
+
+	./wallet-tool reset --wallet=/tmp/bitcoin-wallet-decrypted-backup
+	./wallet-tool sync --wallet=/tmp/bitcoin-wallet-decrypted-backup --debuglog
+
+The sync process will take anywhere from a few minutes to hours. Wallet-tool will return to the
+shell prompt if its finished synching. Have a look at the wallet:
+
+	./wallet-tool dump --wallet=/tmp/bitcoin-wallet-decrypted-backup
+
+Does the balance look right? You can see all transactions that ever touched your wallet. Now empty
+your entire wallet to the desired destination wallet:
+
+	./wallet-tool send --wallet=/tmp/bitcoin-wallet-decrypted-backup --output=<receiving address of destination wallet>:<balance>
+
+If your wallet was protected by a spending PIN, you need to supply that PIN using the
+--password=<PIN> option. Be extra careful with this command to get all parameters right. If it
+succeeds, it will print the transaction hash of the created transaction. You can use that on
+a block explorer to watch, or just open the destination wallet and watch from there. If your coins
+are confirmed, you're done and you can skip the next paragraph to EPILOGUE.
+
+
+RECOVERING FROM BASE58 KEY FORMAT
+
+Have a deeper look at the backup file:
+
+	cat bitcoin-wallet-decrypted-backup
+
+You'll see each line contains a key in WIF (wallet import format), technically Base58. The
+datetime string after each key is the birthdate of that key which you can ignore for the purpose
+of this one-time recovery.
+
+The easiest way to recover this backup is probably installing MultiBit v0.5.x from
+https://multibit.org/ and restore from inside that application.
+
+Another option is importing each individual key into Electrum or bitcoin-qt/bitcoind. You can
+install Electrum with
+
+	sudo apt-get install electrum
+
+As soon as you see your whole balance again, empty your entire wallet to the desired destination
+wallet. Please do not continue to use the imported wallet. Remember you just operated on
+unencrypted keys which can be dangerous, so it's good practise to handle them as if they were
+compromised even if they in fact aren't.
+
+
+EPILOGUE
+
+Let us know if this document helped you with recovering your coins!