summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--core/api-merchant.rst18
-rw-r--r--design-documents/009-backup.rst79
2 files changed, 78 insertions, 19 deletions
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 77e347e7..25f7c154 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -193,6 +193,9 @@ Making the payment
The client might want to try later again.
This includes failures like the denomination key of a coin not being
known to the exchange as far as the merchant can tell.
+ :http:statuscode:`504 Gateway timeout`:
+ The merchant's interaction with the exchange took too long.
+ The client might want to try later again.
The backend will return verbatim the error codes received from the exchange's
:ref:`deposit <deposit>` API. If the wallet made a mistake, like by
@@ -461,6 +464,9 @@ are for incomplete payments for an order and never for established contracts.
:http:statuscode:`502 Bad gateway`:
The merchant's interaction with the exchange failed in some way.
The error from the exchange is included.
+ :http:statuscode:`504 Gateway timeout`:
+ The merchant's interaction with the exchange took too long.
+ The client might want to try later again.
The backend will return an `abort response <AbortResponse>`, which includes
verbatim the error codes received from the exchange's
@@ -1614,6 +1620,9 @@ Inspecting orders
The order or instance is unknown to the backend.
:http:statuscode:`502 Bad gateway`:
We failed to obtain a response from the exchange (about the wire transfer status).
+ :http:statuscode:`504 Gateway timeout`:
+ The merchant's interaction with the exchange took too long.
+ The client might want to try later again.
.. ts:def:: MerchantOrderStatusResponse
@@ -1940,6 +1949,9 @@ Informing the backend about incoming wire transfers
:http:statuscode:`502 Bad gateway`:
The exchange returned an error when we asked it about the "GET /transfer" status
for this wire transfer. Details of the exchange error are returned.
+ :http:statuscode:`504 Gateway timeout`:
+ The merchant's interaction with the exchange took too long.
+ The client might want to try later again.
**Details:**
@@ -2250,6 +2262,9 @@ funds to the exchange.
The exchange does not support the requested wire method.
:http:statuscode:`502 Bad gateway`:
We could not obtain /wire details from the specified exchange base URL.
+ :http:statuscode:`504 Gateway timeout`:
+ The merchant's interaction with the exchange took too long.
+ The client might want to try later again.
.. ts:def:: ReserveCreateRequest
@@ -2352,6 +2367,9 @@ Query funds remaining
This is only returned if there was actual trouble with the exchange, not
if the exchange merely did not respond yet or if it responded that the
reserve was not yet filled.
+ :http:statuscode:`504 Gateway timeout`:
+ The merchant's interaction with the exchange took too long.
+ The client might want to try later again.
.. ts:def:: ReserveDetail
diff --git a/design-documents/009-backup.rst b/design-documents/009-backup.rst
index 1b4895ee..0f2a434a 100644
--- a/design-documents/009-backup.rst
+++ b/design-documents/009-backup.rst
@@ -12,19 +12,32 @@ out multi-device synchronization.
Requirements
============
-* Backup must work both with and without Anastasis
+* Backup must work both with and without Anastasis.
* When not using Anastasis, the user is responsible for keeping
- their wallet's root secret safe.
+ 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
+* 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.
+
+ .. Note::
+ CG: This boils down to the existing 'reset' button (developer mode).
+ Very dangerous. Could be OK if we had some way to notice the number of wallets
+ using the same backup and then allow this 'reset' as longa as # wallets > 1.
+ Still, doing so will require a handshake with the other wallets to ensure
+ that the user doesn't accidentally reset on both wallets at the same time,
+ each believing the other wallet is still sync'ed. So we would need like
+ a 2-phase commit "planning to remove", "acknowledged" (by other wallet), "remove".
+ Very bad UX without real-time sync.
+
* 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.
@@ -33,38 +46,58 @@ Requirements
Solution Overview
=================
-Each wallet has a 64 byte wallet root secret, which is used to derive all other secrets
+Each wallet has a 64 (CG: 32 should be enough, AND better for URLs/QR codes/printing/writing down)
+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
+1. The private **account key** for a sync provider, derived using the sync provider's base URL as salt.
+ The base URL must be normalized to end with a "/". The schema ("http://" or "https://") is part of the
+ base URL, thus different account keys would be used for "http://" vs. "https://" (reduces linkability).
+2. The **symmetric key** used to encrypt/decrypt the backup blob. FIXME: document exact KDF salt here
+ once implemented.
-If the user chooses to use Anastasis, the following information is backed up in Anastasis:
+If the user chooses to use Anastasis, the following information is backed up in Anastasis
+(as the **core secret** in Anastasis terminology):
-* list of used backup providers
-* wallet root secret
+* Taler Wallet core secret tag (new GANA registry) and format version
+* List of used backup providers (sync)
+* Wallet root secret
+* **Tor constraint** (boolean) advising wallets that the backup should only be accessed via
+ Tor and that users must be warned before attempting to restore the backup without Tor.
Supported Operations
--------------------
-* **restore-from-anastasis**: Start Anastasis recovery process. This requires
- the wallet backup state to be "uninitialized".
+* **restore-from-anastasis**: Start Anastasis recovery process.
+ This requires the wallet backup state to be uninitialized.
+ FIXME: The last sentence makes no sense, as the user may have to pay for recovery!
* **restore-from-recovery-secret**: This requires the wallet backup state to be uninitialized.
+ FIXME: Again, I do not think we can require this. User could make backup,
+ then loose device. Create new wallet. Use new wallet (including making
+ yet another backup). THEN user remembers that he
+ had a backup (or find root key) and now want to restore backup. This should
+ MERGE the two states (you can consider it a 'poor' version of 'sync'). Note
+ that the lost device cannot 'abandon' the backed up state here!
* **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.
+ also update the sync provider URL list in the Anastasis core secret (forcing
+ a new policy to be uploaded).
* **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.
+* **backup**: Do a backup cycle. Uploads the latest wallet state to all
+ sync providers. If sync provider state has changed unexpectedly, downloads
+ backup, merges, and then uploads the reconciled state.
* **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.
+ compromised. Requires a new payment to all configured sync providers.
+* **backup-to-anastasis** is missing.
+
Backup Format
@@ -90,11 +123,20 @@ signed planchets, the full withdrawal will be completed.
Open Questions
==============
+* Should the exchange tell the wallet about available sync/Anastasis providers?
+ Otherwise, what do we do if the wallet does not know any providers for the
+ currency of the user?
* 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?
+ .. Note::
+ CG would definitively solve this using a more complex format for the **master secret**,
+ basically serializing mutliple **root secret** values with meta data
+ (which wallet/device/name).
+
+
Future Work / Ideas
===================
@@ -115,4 +157,3 @@ Future Work / Ideas
* 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.)
-