Browse files

Add specific wallet encryption details to doc/README

  • Loading branch information...
1 parent 8acb491 commit 59ed5cb398f3817cebd8f5c6aeba3424de2acefe @TheBlueMatt committed Aug 11, 2011
Showing with 44 additions and 0 deletions.
  1. +44 −0 doc/README
44 doc/README
@@ -67,6 +67,50 @@ entering your wallet passphrase in the Bitcoin client and using the
same passphrase only as your wallet passphrase.
+Technical details of wallet encryption
+Wallet encryption uses AES-256-CBC to encrypt only the private keys
+that are held in a wallet. The keys are encrypted with a master key
+which is entirely random. This master key is then encrypted with
+AES-256-CBC with a key derived from the passphrase using SHA512 and
+OpenSSL's EVP_BytesToKey and a dynamic number of rounds determined by
+the speed of the machine which does the initial encryption (and is
+updated based on the speed of a computer which does a subsequent
+passphrase change). Although the underlying code supports multiple
+encrypted copies of the same master key (and thus multiple passphrases)
+the client does not yet have a method to add additional passphrases.
+At runtime, the client loads the wallet as it normally would, however
+the keystore stores the keys in encrypted form. When the passphrase
+is required (to top up keypool or send coins) it will either be queried
+by a GUI prompt, or must first be entered with the walletpassphrase
+RPC command. This will change the wallet to "unlocked" state where the
+unencrypted master key is stored in memory (in the case of GUI, only for
+long enough to complete the requested operation, in RPC, for as long as
+is specified by the second parameter to walletpassphrase). The wallet is
+then locked (or can be manually locked using the walletlock RPC command)
+and the unencrypted master key is removed from memory.
+Implementation details of wallet encryption
+When the wallet is locked, calls to sendtoaddress, sendfrom, sendmany,
+and keypoolrefill will return Error -13: "Error: Please enter the wallet
+passphrase with walletpassphrase first."
+When the wallet is unlocked, calls to walletpassphrase will fail.
+When a wallet is encrypted, the passphrase is required to top up the
+keypool, thus, if the passphrase is rarely entered, it is possible that
+keypool might run out. In this case, the default key will be used as the
+target for payouts for mining, and calls to getnewaddress and getaccount
+address will return an error. In order to prevent such cases, the keypool
+is automatically refilled when walletpassphrase is called with a correct
+passphrase and when topupkeypool is called (while the wallet is unlocked).
+Note that the keypool continues to be topped up on various occasions when
+a new key from pool is used and the wallet is unlocked (or unencrypted).
See the documentation at the bitcoin wiki:

0 comments on commit 59ed5cb

Please sign in to comment.