009-backup.rst (7855B)
1 XX 09: Wallet Backup 2 #################### 3 4 :Design status: Superseded 5 :Implementation status: Prototype 6 :DD shepherd: TBD 7 :Historical contributors: Florian Dold, Christian Grothoff, Iván Ávalos 8 :First published: 2020-11-06 9 :Last substantive change: 2026-08-09 10 :Superseded by: :doc:`092-incremental-backup-sync` 11 12 .. warning:: 13 14 This design document is deprecated. The incremental backup and sync 15 protocol described in `DD 92`_ supersedes it. 16 17 The body below is retained for historical context and is non-normative. 18 19 .. _DD 92: https://docs.taler.net/design-documents/092-incremental-backup-sync.html 20 21 Summary 22 ======= 23 24 This document describes the backup system used by Taler wallets. 25 This is the second, simplified iteration of the proposal, which leaves 26 out multi-device synchronization. 27 28 29 Requirements 30 ============ 31 32 * Backup must work both with and without Anastasis. 33 34 * When not using Anastasis, the user is responsible for keeping 35 their wallet's **root secret** safe. 36 37 * Arbitrary number of backup providers must be supported. 38 * Minimize information leaks / timing side channels. 39 40 * User might be able to change some setting to allow more frequent 41 backup with less potential data loss but more leakage. 42 43 * Minimize potential to lose money or important information. 44 * Since real-time sync is not supported yet, wallets should have a feature 45 where their whole content is "emptied" to another wallet, and the wallet is 46 reset. 47 48 .. Note:: 49 CG: This boils down to the existing 'reset' button (developer mode). 50 Very dangerous. Could be OK if we had some way to notice the number of wallets 51 using the same backup and then allow this 'reset' as longa as # wallets > 1. 52 Still, doing so will require a handshake with the other wallets to ensure 53 that the user doesn't accidentally reset on both wallets at the same time, 54 each believing the other wallet is still sync'ed. So we would need like 55 a 2-phase commit "planning to remove", "acknowledged" (by other wallet), "remove". 56 Very bad UX without real-time sync. 57 58 * Even without real-time sync, the backup data must support merging with old, existing wallet 59 state, as the device that the wallet runs on may be restored from backup or be offline 60 for a long time. 61 62 63 Solution Overview 64 ================= 65 66 Each wallet has a 64 (CG: 32 should be enough, AND better for URLs/QR codes/printing/writing down) 67 byte wallet **root secret**, which is used to derive all other secrets 68 used during backup, which are currently: 69 70 1. The private **account key** for a sync provider, derived using the sync provider's base URL as salt. 71 The base URL must be normalized to end with a "/". The schema ("http://" or "https://") is part of the 72 base URL, thus different account keys would be used for "http://" vs. "https://" (reduces linkability). 73 2. The **symmetric key** used to encrypt/decrypt the backup blob. FIXME: document exact KDF salt here 74 once implemented. 75 76 If the user chooses to use Anastasis, the following information is backed up in Anastasis 77 (as the **core secret** in Anastasis terminology): 78 79 * Taler Wallet core secret tag (new GANA registry) and format version 80 * List of used backup providers (sync) 81 * Wallet root secret 82 * **Tor constraint** (boolean) advising wallets that the backup should only be accessed via 83 Tor and that users must be warned before attempting to restore the backup without Tor. 84 85 86 Supported Operations 87 -------------------- 88 89 * **restore-from-anastasis**: Start Anastasis recovery process. 90 This requires the wallet backup state to be uninitialized. 91 FIXME: The last sentence makes no sense, as the user may have to pay for recovery! 92 * **restore-from-recovery-secret**: This requires the wallet backup state to be uninitialized. 93 FIXME: Again, I do not think we can require this. User could make backup, 94 then loose device. Create new wallet. Use new wallet (including making 95 yet another backup). THEN user remembers that he 96 had a backup (or find root key) and now want to restore backup. This should 97 MERGE the two states (you can consider it a 'poor' version of 'sync'). Note 98 that the lost device cannot 'abandon' the backed up state here! 99 * **add-provider** / **remove-provider**: Add/remove a sync provider from the 100 list of providers. Adding a provider will cause payment(s) to the provider 101 to be scheduled according to the provider's terms. If the wallet backup 102 state is "uninitialized", adding a provider will set the backup state to 103 "initialized" with a fresh wallet root key. Changing the provider list will 104 also update the sync provider URL list in the Anastasis core secret (forcing 105 a new policy to be uploaded). 106 * **abandon** / **takeover**: When the user wants to stop using a wallet on a particular 107 device, another wallet can "take over" by reading the recovery secret of the abandoned wallet. 108 The abandoned wallet marks explicitly in its backup blob that it is abandoned. 109 Abandoning a wallet will set the backup state to "uninitialized". 110 * **backup**: Do a backup cycle. Uploads the latest wallet state to all 111 sync providers. If sync provider state has changed unexpectedly, downloads 112 backup, merges, and then uploads the reconciled state. 113 * **rekey**: Change to a new wallet root secret, in case the old one has been 114 compromised. Only protectes future funds of the wallet from being 115 compromised. Requires a new payment to all configured sync providers. 116 * **backup-to-anastasis** is missing. 117 118 119 120 Backup Format 121 ------------- 122 123 TBD. Considerations from :doc:`005-wallet-backup-sync` still apply, 124 especially regarding the CRDT. 125 126 127 Initial User Experience 128 ----------------------- 129 130 The user will be asked to set up backup&sync (by selecting a provider) 131 after the first withdrawal operation has been confirmed. After selecting 132 the backup&sync providers, the user will be presented with a "checklist" that 133 contains an option to (1) show/print the recovery secret and (2) set up Anastasis. 134 135 The wallet will initially only withdraw enough money to pay the 136 backup&sync/anastasis providers. Only after successful backup of the wallet's 137 signed planchets, the full withdrawal will be completed. 138 139 140 Open Questions 141 ============== 142 143 * Should the exchange tell the wallet about available sync/Anastasis providers? 144 Otherwise, what do we do if the wallet does not know any providers for the 145 currency of the user? 146 * Should the wallet root secret and wallet database be locally encrypted 147 and protected via a passphrase? 148 * What happens if the same Anastasis user has multiple wallets? Can Anastasis somehow 149 support multiple "instances" per application? 150 151 .. Note:: 152 CG would definitively solve this using a more complex format for the **master secret**, 153 basically serializing multiple **root secret** values with meta data 154 (which wallet/device/name). 155 156 157 Future Work / Ideas 158 =================== 159 160 * Incremental backups? 161 162 * Instead of one big blob that always needs to be read/written, we could have (1) a 163 limited length append-only journal and (2) a merkle tree so that the backup blob can 164 be updated incrementally once the journal is full. 165 * Leaks more information and is more complex. 166 167 * Mult-device synchronization, with synchronous communication either over some signaling server 168 or P2P connectivity (WebRTC, etc.) 169 170 * Destroys the "wallet" metaphor, now the wallet is more like an account. 171 * We should first agree on the requirements from the perspective of end users 172 * P2P payments in Taler might also make sync less important 173 * Maybe only parts of the state (purchases / contracts, but not coins) should be synchronized? 174 * WhatsApp web model: The wallet runs only on one devices, but other devices 175 can connect to it as clients. (Allows my browser wallet to temporarily access 176 money from my phone wallet and vice versa.)