From 59ed5cb398f3817cebd8f5c6aeba3424de2acefe Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Thu, 11 Aug 2011 13:09:25 +0200 Subject: [PATCH] Add specific wallet encryption details to doc/README --- doc/README | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/doc/README b/doc/README index 5a05950b9..831d66069 100644 --- a/doc/README +++ b/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: https://en.bitcoin.it/wiki/Main_Page