doc/README

   1 Bitcoin 0.4.5 BETA
   2
   3 Copyright (c) 2009-2012 Bitcoin Developers
   4 Distributed under the MIT/X11 software license, see the accompanying
   5 file license.txt or http://www.opensource.org/licenses/mit-license.php.
   6 This product includes software developed by the OpenSSL Project for use in
   7 the OpenSSL Toolkit (http://www.openssl.org/).  This product includes
   8 cryptographic software written by Eric Young (eay@cryptsoft.com).
   9
  10
  11 Intro
  12 -----
  13 Bitcoin is a free open source peer-to-peer electronic cash system that is
  14 completely decentralized, without the need for a central server or trusted
  15 parties.  Users hold the crypto keys to their own money and transact directly
  16 with each other, with the help of a P2P network to check for double-spending.
  17
  18
  19 Setup
  20 -----
  21 Unpack the files into a directory and run:
  22  bin/32/bitcoin (GUI, 32-bit)
  23  bin/32/bitcoind (headless, 32-bit)
  24  bin/64/bitcoin (GUI, 64-bit)
  25  bin/64/bitcoind (headless, 64-bit)
  26
  27
  28 Wallet Encryption
  29 -----------------
  30 Bitcoin supports native wallet encryption so that people who steal your
  31 wallet file don't automatically get access to all of your Bitcoins.
  32 In order to enable this feature, chose "Encrypt Wallet" from the
  33 Options menu.  You will be prompted to enter a passphrase, which
  34 will be used as the key to encrypt your wallet and will be needed
  35 every time you wish to send Bitcoins.  If you lose this passphrase,
  36 you will lose access to spend all of the bitcoins in your wallet,
  37 no one, not even the Bitcoin developers can recover your Bitcoins.
  38 This means you are responsible for your own security, store your
  39 passphrase in a secure location and do not forget it.
  40
  41 Remember that the encryption built into bitcoin only encrypts the
  42 actual keys which are required to send your bitcoins, not the full
  43 wallet.  This means that someone who steals your wallet file will
  44 be able to see all the addresses which belong to you, as well as the
  45 relevant transactions, you are only protected from someone spending
  46 your coins.
  47
  48 It is recommended that you backup your wallet file before you
  49 encrypt your wallet.  To do this, close the Bitcoin client and
  50 copy the wallet.dat file from ~/.bitcoin/ on Linux, /Users/(user
  51 name)/Application Support/Bitcoin/ on Mac OSX, and %APPDATA%/Bitcoin/
  52 on Windows (that is /Users/(user name)/AppData/Roaming/Bitcoin on
  53 Windows Vista and 7 and /Documents and Settings/(user name)/Application
  54 Data/Bitcoin on Windows XP).  Once you have copied that file to a
  55 safe location, reopen the Bitcoin client and Encrypt your wallet.
  56 If everything goes fine, delete the backup and enjoy your encrypted
  57 wallet.  Note that once you encrypt your wallet, you will never be
  58 able to go back to a version of the Bitcoin client older than 0.4.
  59
  60 Keep in mind that you are always responsible for your own security.
  61 All it takes is a slightly more advanced wallet-stealing trojan which
  62 installs a keylogger to steal your wallet passphrase as you enter it
  63 in addition to your wallet file and you have lost all your Bitcoins.
  64 Wallet encryption cannot keep you safe if you do not practice
  65 good security, such as running up-to-date antivirus software, only
  66 entering your wallet passphrase in the Bitcoin client and using the
  67 same passphrase only as your wallet passphrase.
  68
  69
  70 Technical details of wallet encryption
  71 --------------------------------------
  72 Wallet encryption uses AES-256-CBC to encrypt only the private keys
  73 that are held in a wallet.  The keys are encrypted with a master key
  74 which is entirely random.  This master key is then encrypted with
  75 AES-256-CBC with a key derived from the passphrase using SHA512 and
  76 OpenSSL's EVP_BytesToKey and a dynamic number of rounds determined by
  77 the speed of the machine which does the initial encryption (and is
  78 updated based on the speed of a computer which does a subsequent
  79 passphrase change).  Although the underlying code supports multiple
  80 encrypted copies of the same master key (and thus multiple passphrases)
  81 the client does not yet have a method to add additional passphrases.
  82
  83 At runtime, the client loads the wallet as it normally would, however
  84 the keystore stores the keys in encrypted form.  When the passphrase
  85 is required (to top up keypool or send coins) it will either be queried
  86 by a GUI prompt, or must first be entered with the walletpassphrase
  87 RPC command.  This will change the wallet to "unlocked" state where the
  88 unencrypted master key is stored in memory (in the case of GUI, only for
  89 long enough to complete the requested operation, in RPC, for as long as
  90 is specified by the second parameter to walletpassphrase).  The wallet is
  91 then locked (or can be manually locked using the walletlock RPC command)
  92 and the unencrypted master key is removed from memory.
  93
  94 Implementation details of wallet encryption
  95 -------------------------------------------
  96 When the wallet is locked, calls to sendtoaddress, sendfrom, sendmany,
  97 and keypoolrefill will return Error -13: "Error: Please enter the wallet
  98 passphrase with walletpassphrase first."
  99
 100 When the wallet is unlocked, calls to walletpassphrase will fail.
 101
 102 When a wallet is encrypted, the passphrase is required to top up the
 103 keypool, thus, if the passphrase is rarely entered, it is possible that
 104 keypool might run out.  In this case, the default key will be used as the
 105 target for payouts for mining, and calls to getnewaddress and getaccount
 106 address will return an error.  In order to prevent such cases, the keypool
 107 is automatically refilled when walletpassphrase is called with a correct
 108 passphrase and when topupkeypool is called (while the wallet is unlocked).
 109 Note that the keypool continues to be topped up on various occasions when
 110 a new key from pool is used and the wallet is unlocked (or unencrypted).
 111
 112
 113
 114 See the documentation at the bitcoin wiki:
 115   https://en.bitcoin.it/wiki/Main_Page
 116
 117 ... for help and more information.