diff options
Diffstat (limited to 'design-documents')
| -rw-r--r-- | design-documents/002-wallet-exchange-management.rst | 2 | ||||
| -rw-r--r-- | design-documents/003-tos-rendering.rst | 2 | ||||
| -rw-r--r-- | design-documents/005-wallet-backup-sync.rst | 6 | ||||
| -rw-r--r-- | design-documents/007-payment.rst | 5 | ||||
| -rw-r--r-- | design-documents/008-fees.rst (renamed from design-documents/fees.rst) | 6 | ||||
| -rw-r--r-- | design-documents/009-backup.rst | 118 | ||||
| -rw-r--r-- | design-documents/index.rst | 2 |
7 files changed, 133 insertions, 8 deletions
diff --git a/design-documents/002-wallet-exchange-management.rst b/design-documents/002-wallet-exchange-management.rst index d70a799c..9d10045a 100644 --- a/design-documents/002-wallet-exchange-management.rst +++ b/design-documents/002-wallet-exchange-management.rst @@ -154,7 +154,7 @@ Response: // The "reasonable-ness" of the exchange's fees. feeStructureSummary: FeeStructureSummary | undefined; - // Detailled info for each individual denomination + // Detailed info for each individual denomination denominations: ExchangeDenomination[]; // Currency of the exchange. diff --git a/design-documents/003-tos-rendering.rst b/design-documents/003-tos-rendering.rst index 52d293c3..3011775c 100644 --- a/design-documents/003-tos-rendering.rst +++ b/design-documents/003-tos-rendering.rst @@ -34,7 +34,7 @@ Legal documents with mime type ``text/markdown`` **should** confirm to the When wallets render ``text/markdown`` legal documents, they **must** disable embedded HTML rendering. Wallets **may** style the markdown rendering to improve -usability. For example, they can make sections collabsible or add a nagivation side-bar +usability. For example, they can make sections collabsible or add a navigation side-bar on bigger screens. It is recommended that the ``text/markdown`` document is used as the "master diff --git a/design-documents/005-wallet-backup-sync.rst b/design-documents/005-wallet-backup-sync.rst index 26dbbf17..20fce37b 100644 --- a/design-documents/005-wallet-backup-sync.rst +++ b/design-documents/005-wallet-backup-sync.rst @@ -3,7 +3,11 @@ Design Doc 005: Wallet Backup and Sync .. warning:: - This is an unfinished draft. + This document is deprecated. We have decided to first + implement backup, and tackle sync later. + The multi-device sync described in this document would lead + to a bad/unexpected user experience that does not justify the + conceptual / implementation complexity. Summary ======= diff --git a/design-documents/007-payment.rst b/design-documents/007-payment.rst index 0095d1d7..9a16776d 100644 --- a/design-documents/007-payment.rst +++ b/design-documents/007-payment.rst @@ -40,8 +40,9 @@ When *resource-URL* is requested, the storefront runs the following steps: 1. Extract the *resource name* from the *resource-URL*. 2. Extract the *session-ID* (or null) from the request's validated cookie (for example, by using signed cookies). 3. Extract the *order-ID* (or null) from the request's ``order_id`` cookie. This cookie may optionally be validated. -.. - is "invalid" equivalent to "null"? + + .. + is "invalid" equivalent to "null"? 4. If *session-ID* or *order-ID* is null, assign a fresh session ID and create a new order for *resource name* by doing a ``POST /private/orders`` diff --git a/design-documents/fees.rst b/design-documents/008-fees.rst index 96459423..331d6cd7 100644 --- a/design-documents/fees.rst +++ b/design-documents/008-fees.rst @@ -1,4 +1,4 @@ -Design Doc 003: Fee Structure Metrics +Design Doc 008: Fee Structure Metrics ##################################### .. note:: @@ -48,7 +48,7 @@ cost for the user and and (2) restrictions on denomination/fee structures. Thus the metrics should still allow some degree of variability between exchanges. -We make the assumption that wallet always perfer operations with better +We make the assumption that wallet always prefer operations with better privacy. For example, a single coin should only be used for at most one spend operation and at most one refresh operation. @@ -109,7 +109,7 @@ Drawbacks ========= * The approach does not work well in some special-purpose deployments, - where the coin structure is taylored to the products of merchants, + where the coin structure is tailored to the products of merchants, and refreshing would never even happen. * The approach also does not consider more "creative" fee structures, diff --git a/design-documents/009-backup.rst b/design-documents/009-backup.rst new file mode 100644 index 00000000..1b4895ee --- /dev/null +++ b/design-documents/009-backup.rst @@ -0,0 +1,118 @@ +Design Doc 009: Wallet Backup +############################# + +Summary +======= + +This document describes the backup system used by Taler wallets. +This is the second, simplified iteration of the proposal, which leaves +out multi-device synchronization. + + +Requirements +============ + +* Backup must work both with and without Anastasis + + * When not using Anastasis, the user is responsible for keeping + their wallet's root secret safe. + +* Arbitrary number of backup providers must be supported +* Minimize information leaks / timing side channels (user might be able to change + some setting to allow more frequent backup with less potential data loss but more + leakage) +* Minimize potential to lose money or important information +* Since real-time sync is not supported yet, wallets should have a feature + where their whole content is "emptied" to another wallet, and the wallet is + reset. +* Even without real-time sync, the backup data must support merging with old, existing wallet + state, as the device that the wallet runs on may be restored from backup or be offline + for a long time. + + +Solution Overview +================= + +Each wallet has a 64 byte wallet root secret, which is used to derive all other secrets +used during backup, which are currently: + +1. The sync account key for a sync provider, derived via the sync provider's base URL. +2. The symmetric key used to encrypt the backup blob + +If the user chooses to use Anastasis, the following information is backed up in Anastasis: + +* list of used backup providers +* wallet root secret + + +Supported Operations +-------------------- + +* **restore-from-anastasis**: Start Anastasis recovery process. This requires + the wallet backup state to be "uninitialized". +* **restore-from-recovery-secret**: This requires the wallet backup state to be uninitialized. +* **add-provider** / **remove-provider**: Add/remove a sync provider from the + list of providers. Adding a provider will cause payment(s) to the provider + to be scheduled according to the provider's terms. If the wallet backup + state is "uninitialized", adding a provider will set the backup state to + "initialized" with a fresh wallet root key. Changing the provider list will + also update the backup provider URL list in the anastasis core secret. +* **abandon** / **takeover**: When the user wants to stop using a wallet on a particular + device, another wallet can "take over" by reading the recovery secret of the abandoned wallet. + The abandoned wallet marks explicitly in its backup blob that it is abandoned. + Abandoning a wallet will set the backup state to "uninitialized". +* **backup**: Do a backup cycle. +* **rekey**: Change to a new wallet root secret, in case the old one has been + compromised. Only protectes future funds of the wallet from being + compromised. Requires a new payment to all configured backup providers. + + +Backup Format +------------- + +TBD. Considerations from :doc:`005-wallet-backup-sync` still apply, +especially regarding the CRDT. + + +Initial User Experience +----------------------- + +The user will be asked to set up backup&sync (by selecting a provider) +after the first withdrawal operation has been confirmed. After selecting +the backup&sync providers, the user will be presented with a "checklist" that +contains an option to (1) show/print the recovery secret and (2) set up Anastasis. + +The wallet will initially only withdraw enough money to pay the +backup&sync/anastasis providers. Only after successful backup of the wallet's +signed planchets, the full withdrawal will be completed. + + +Open Questions +============== + +* Should the wallet root secret and wallet database be locally encrypted + and protected via a passphrase? +* What happens if the same Anastasis user has multiple wallets? Can Anastasis somehow + support multiple "instances" per application? + +Future Work / Ideas +=================== + +* Incremental backups? + + * Instead of one big blob that always needs to be read/written, we could have (1) a + limited length append-only journal and (2) a merkle tree so that the backup blob can + be updated incrementally once the journal is full. + * Leaks more information and is more complex. + +* Mult-device synchronization, with synchronous communication either over some signaling server + or P2P connectivity (WebRTC, etc.) + + * Destroys the "wallet" metaphor, now the wallet is more like an account. + * We should first agree on the requirements from the perspective of end users + * P2P payments in Taler might also make sync less important + * Maybe only parts of the state (purchases / contracts, but not coins) should be synchronized? + * WhatsApp web model: The wallet runs only on one devices, but other devices + can connect to it as clients. (Allows my browser wallet to temporarily access + money from my phone wallet and vice versa.) + diff --git a/design-documents/index.rst b/design-documents/index.rst index fda8b2e5..55dd8c1e 100644 --- a/design-documents/index.rst +++ b/design-documents/index.rst @@ -17,3 +17,5 @@ and protocol. 005-wallet-backup-sync 006-anastasis-ux 007-payment + 008-fees + 009-backup |