1 /* Package waddrmgr provides a secure hierarchical deterministic wallet address manager.
2 3 Overview
4 5 One of the fundamental jobs of a wallet is to manage addresses, private keys, and script data associated with them. At a
6 high level, this package provides the facilities to perform this task with a focus on security and also allows recovery
7 through the use of hierarchical deterministic keys (BIP0032) generated from a caller provided seed. The specific
8 structure used is as described in BIP0044. This setup means as long as the user writes the seed down (even better is to
9 use a mnemonic for the seed), all their addresses and private keys can be regenerated from the seed.
10 11 There are two master keys which are protected by two independent passphrases. One is intended for public facing data,
12 while the other is intended for private data. The public password can be hardcoded for callers who don't want the
13 additional public data protection or the same password can be used if a single password is desired. These choices
14 provide a usability versus security tradeoff. However, keep in mind that extended hd keys, as called out in BIP0032 need
15 to be handled more carefully than normal EC public keys because they can be used to generate all future addresses. While
16 this is part of what makes them attractive, it also means an attacker getting access to your extended public key for an
17 account will allow them to know all derived addresses you will use and hence reduces privacy. For this reason, it is
18 highly recommended that you do not hard code a password which allows any attacker who gets a copy of your address
19 manager database to access your effectively plain text extended public keys.
20 21 Each master key in turn protects the three real encryption keys (called crypto keys) for public, private, and script
22 data. Some examples include payment addresses, extended hd keys, and scripts associated with pay-to-script-hash
23 addresses. This scheme makes changing passphrases more efficient since only the crypto keys need to be re-encrypted
24 versus every single piece of information (which is what is needed for *rekeying*). This results in a fully encrypted
25 database where access to it does not compromise address, key, or script privacy. This differs from the handling by other
26 wallets at the time of this writing in that they divulge your addresses, and worse, some even expose the chain code
27 which can be used by the attacker to know all future addresses that will be used.
28 29 The address manager is also hardened against memory scrapers. This is accomplished by typically having the address
30 manager locked meaning no private keys or scripts are in memory. Unlocking the address manager causes the crypto private
31 and script keys to be decrypted and loaded in memory which in turn are used to decrypt private keys and scripts on
32 demand. Relocking the address manager actively zeros all private material from memory. In addition, temp private key
33 material used internally is zeroed as soon as it's used.
34 35 Locking and Unlocking
36 37 As previously mentioned, this package provide facilities for locking and unlocking the address manager to protect access
38 to private material and remove it from memory when locked. The Lock, Unlock, and IsLocked functions are used for this
39 purpose.
40 41 Creating a New Address Manager
42 43 A new address manager is created via the Create function. This function accepts a wallet database namespace,
44 passphrases, network, and perhaps most importantly, a cryptographically random seed which is used to generate the master
45 node of the hierarchical deterministic keychain which allows all addresses and private keys to be recovered with only
46 the seed. The GenerateSeed function in the hdkeychain package can be used as a convenient way to create a random seed
47 for use with this function. The address manager is locked immediately upon being created.
48 49 Opening an Existing Address Manager
50 51 An existing address manager is opened via the Open function. This function accepts an existing wallet database
52 namespace, the public passphrase, and network. The address manager is opened locked as expected since the open function
53 does not take the private passphrase to unlock it.
54 55 Closing the Address Manager
56 57 The Close method should be called on the address manager when the caller is done with it. While it is not required, it
58 is recommended because it sanely shuts down the database and ensures all private and public key material is purged from
59 memory.
60 61 Managed Addresses
62 63 Each address returned by the address manager satisifies the ManagedAddress interface as well as either the
64 ManagedPubKeyAddress or ManagedScriptAddress interfaces. These interfaces provide the means to obtain relevant
65 information about the addresses such as their private keys and scripts.
66 67 Chained Addresses
68 69 Most callers will make use of the chained addresses for normal operations. Internal addresses are intended for internal
70 wallet uses such as change outputs, while external addresses are intended for uses such payment addresses that are
71 shared. The NextInternalAddresses and NextExternalAddresses functions provide the means to acquire one or more of the
72 next addresses that have not already been provided. In addition, the LastInternalAddress and LastExternalAddress
73 functions can be used to get the most recently provided internal and external address, respectively.
74 75 Requesting Existing Addresses
76 77 In addition to generating new addresses, access to old addresses is often required. Most notably, to sign transactions
78 in order to redeem them. The Address function provides this capability and returns a ManagedAddress.
79 80 Importing Addresses
81 82 While the recommended approach is to use the chained addresses discussed above because they can be deterministically
83 regenerated to avoid losing funds as long as the user has the master seed, there are many addresses that already exist,
84 and as a result, this package provides the ability to import existing private keys in Wallet Import Format (WIF) and
85 hence the associated public key and address.
86 87 Importing Scripts
88 89 In order to support pay-to-script-hash transactions, the script must be securely stored as it is needed to redeem the
90 transaction. This can be useful for a variety of scenarios, however the most common use is currently multi-signature
91 transactions.
92 93 Syncing
94 95 The address manager also supports storing and retrieving a block hash and height which the manager is known to have all
96 addresses synced through. The manager itself does not have any notion of which addresses are synced or not. It only
97 provides the storage as a convenience for the caller.
98 99 Network
100 101 The address manager must be associated with a given network in order to provide
102 appropriate addresses and reject imported addresses and scripts which don't
103 apply to the associated network.
104 105 Errors
106 107 All errors returned from this package are of type ManagerError. This allows the caller to programmatically ascertain the
108 specific reasons for failure by examining the ErrorCode field of the type asserted ManagerError. For certain error
109 codes, as documented by the specific error codes, the underlying error will be contained in the Err field.
110 111 Bitcoin Improvement Proposals
112 113 This package includes concepts outlined by the following BIPs:
114 115 BIP0032 (https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)
116 BIP0043 (https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki)
117 BIP0044 (https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)
118 */
119 package waddrmgr
120