From 2f8f51d1e4e5285fdd5724f7264d32d08a42f7e9 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Thu, 11 Aug 2011 11:21:55 +0200 Subject: [PATCH 1/3] Missed a 'password' should be 'passphrase'. --- doc/README | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README b/doc/README index f72bca01f..5a05950b9 100644 --- a/doc/README +++ b/doc/README @@ -36,7 +36,7 @@ every time you wish to send Bitcoins. If you lose this passphrase, you will lose access to spend all of the bitcoins in your wallet, no one, not even the Bitcoin developers can recover your Bitcoins. This means you are responsible for your own security, store your -password in a secure location and do not forget it. +passphrase in a secure location and do not forget it. Remember that the encryption built into bitcoin only encrypts the actual keys which are required to send your bitcoins, not the full From 8acb491eef2044443b34e867b91ddb70244cefcf Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Thu, 11 Aug 2011 13:18:37 +0200 Subject: [PATCH 2/3] Fix incorrect RPC error messages --- src/rpc.cpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/rpc.cpp b/src/rpc.cpp index d62a0d9ac..dd3430d42 100644 --- a/src/rpc.cpp +++ b/src/rpc.cpp @@ -552,7 +552,7 @@ Value sendtoaddress(const Array& params, bool fHelp) CRITICAL_BLOCK(pwalletMain->cs_vMasterKey) { if(pwalletMain->IsLocked()) - throw JSONRPCError(-14, "Error: The wallet passphrase entered was incorrect."); + throw JSONRPCError(-13, "Error: Please enter the wallet passphrase with walletpassphrase first."); string strError = pwalletMain->SendMoneyToBitcoinAddress(address, nAmount, wtx); if (strError != "") @@ -827,7 +827,7 @@ Value sendfrom(const Array& params, bool fHelp) CRITICAL_BLOCK(pwalletMain->cs_vMasterKey) { if(pwalletMain->IsLocked()) - throw JSONRPCError(-14, "Error: The wallet passphrase entered was incorrect."); + throw JSONRPCError(-13, "Error: Please enter the wallet passphrase with walletpassphrase first."); // Check funds int64 nBalance = GetAccountBalance(strAccount, nMinDepth); @@ -894,7 +894,7 @@ Value sendmany(const Array& params, bool fHelp) CRITICAL_BLOCK(pwalletMain->cs_vMasterKey) { if(pwalletMain->IsLocked()) - throw JSONRPCError(-14, "Error: The wallet passphrase entered was incorrect."); + throw JSONRPCError(-13, "Error: Please enter the wallet passphrase with walletpassphrase first."); // Check funds int64 nBalance = GetAccountBalance(strAccount, nMinDepth); From 59ed5cb398f3817cebd8f5c6aeba3424de2acefe Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Thu, 11 Aug 2011 13:09:25 +0200 Subject: [PATCH 3/3] 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