update sync doc

1 files changed, 90 insertions, 69 deletions

diff --git a/core/api-sync.rst b/core/api-sync.rst
index 6404c9e7..803eee0f 100644
--- a/core/api-sync.rst
+++ b/core/api-sync.rst
@@ -1,6 +1,6 @@
 ..
   This file is part of GNU TALER.
-  Copyright (C) 2018 Taler Systems SA
+  Copyright (C) 2018, 2019 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU General Public License as published by the Free Software
@@ -17,27 +17,27 @@
 
 .. _sync-api:
 
-=============================================
-Wallet Backup and Synchronization Service API
-=============================================
+======================================
+Backup and Synchronization Service API
+======================================
 
-The wallet backup and synchronization service uses an EdDSA wallet key
-to identify the "account" of the user.  The wallet key is Crockford
+The backup and synchronization service uses an EdDSA key
+to identify the "account" of the user.  The key is Crockford
 Base32-encoded in the URI to access the data and used to sign requests
 as well as to encrypt the contents (see below).  These signatures are
 provided in detached from as HTTP headers.
 
-Once the user activates backup or synchronization, the wallet should
-display the wallet key as a QR code as well as in text format together
+Once the user activates backup or synchronization, the client should
+display the key as a QR code as well as in text format together
 with the synchronization service's URL and ask the user to print this
 key material and keep it safe.
 
-The actual format of the wallet database is not relevant for the
+The actual format of the backup is not relevant for the
 backup and synchronization service, as the service must only ever see
 a padded and encrypted version of the data.
 
 However, there are a few general rules that will apply to
-any version of the wallet database.  Still, except for the
+any version of the backup.  Still, except for the
 32 byte minimum upload size, the synchronization service
 itself cannot not enforce these rules.
 
@@ -45,11 +45,11 @@ itself cannot not enforce these rules.
      padded to a power of 2 in kilobytes or a multiple of
      megabytes, then encrypted and finally protected with
      an HDKF.
-  *  The encryption should use an ephemeral Curve25519 point that
+  *  The encryption should use an SHA-512 nonce which
      is prefixed to the actual database, and combined with
-     the private wallet key via ECDH to create a symmetric secret.
-     With every revision of the wallet (but only real
-     revisions or merge operations), a fresh ephemeral must be
+     the master key to create the encryption symmetric secret.
+     With every revision of the backup (but only real
+     revisions or merge operations), a fresh nonce must be
      used to ensure that the symmetric secret differs every
      time.  HKDFs are used to derive symmetric key material
      for authenticated encryption (encrypt-then-mac or a
@@ -57,7 +57,7 @@ itself cannot not enforce these rules.
      easily available and will likey increase the code of
      the wallet less, AES plus a SHA-512 HMAC should suffice
      for now.
-  *  The wallet must enable merging databases in a way that is
+  *  The client must enable merging databases in a way that is
      associative and commutative.  For most activities, this implies
      merging lists, applying expirations, dropping duplicates and
      sorting the result.  For deletions (operations by which the user
@@ -69,13 +69,13 @@ itself cannot not enforce these rules.
      "delete all transactions smaller than amount Y before time T"
      into "delete all transactions smaller than amount max(X,Y) before
      time T".  Similar summarizations should be applied to all
-     deletion operations supported by the wallet.  Deletion operations
+     deletion operations supported by the client.  Deletion operations
      themselves are associated with an expiration time reflecting the
      expiration of the longest lasting record that they explicitly
      deleted.
      Purchases do not have an expiration time, thus they create
      a challenge if an indivdiual purchase is deleted. Thus, when
-     an individual purchase is deleted, the wallet is to keep track
+     an individual purchase is deleted, the client is to keep track
      of the deletion with a deletion record. The deletion record
      still includes the purchase amount and purchase date.  Thus,
      when purchases are deleted "in bulk" in a way that would have
@@ -88,15 +88,15 @@ itself cannot not enforce these rules.
      we do not go backwards in time if the synchronization service is
      malicious.  Merging two databases means taking the max of the
      "last modified" timestamps, not setting it to the current time.
-     The wallet should reject a "fast forward" database update if the
-     result would imply going back in time.  If the wallet receives a
+     The client should reject a "fast forward" database update if the
+     result would imply going back in time.  If the client receives a
      database with a timestamp into the future, it must still
      increment it by the smallest possible amount when uploading an
      update.
 
 It is assumed that the synchronization service is only ever accessed
 over TLS, and that the synchronization service is trusted to not build
-user's location profiles by linking client IP addresses and wallet
+user's location profiles by linking client IP addresses and client
 keys.
 
 
@@ -115,7 +115,7 @@ Receiving Terms of Service
   .. ts:def:: SyncTermsOfServiceResponse
 
     interface SyncTermsOfServiceResponse {
-      // maximum wallet database backup size supported
+      // maximum backup size supported
       storage_limit_in_megabytes: number;
 
       // Fee for an account, per year.
@@ -126,9 +126,9 @@ Receiving Terms of Service
 
 .. _sync:
 
-.. http:get:: /$WALLET-KEY
+.. http:get:: /$ACCOUNT-KEY
 
-  Download latest version of the wallet database.
+  Download latest version of the backup.
   The returned headers must include "Etags" based on
   the hash of the (encrypted) database. The server must
   check the client's caching headers and only return the
@@ -137,10 +137,10 @@ Receiving Terms of Service
 
   This method is generally only performed once per device
   when the private key and URL of a synchronization service are
-  first given to the wallet on the respective device.  Once a
-  wallet has a database, it should always use the POST method.
+  first given to the client on the respective device.  Once a
+  client has made a backup, it should always use the POST method.
 
-  A signature is not required, as (1) the wallet-key should
+  A signature is not required, as (1) the account-key should
   be reasonably private and thus unauthorized users should not
   know how to produce the correct request, and (2) the
   information returned is encrypted to the private key anyway
@@ -150,19 +150,19 @@ Receiving Terms of Service
   **Response**
 
   :status 200 OK:
-    The body contains the current version of the wallet's
-    database as known to the server.
+    The body contains the current version of the backup
+    as known to the server.
 
   :status 204 No content:
-    This is a fresh account, no previous wallet data exists at
+    This is a fresh account, no previous backup data exists at
     the server.
 
-  :status 402 Payment required:
-    The synchronization service requires payment before the
-    account can continue to be used.  The fulfillment URL
-    should be the /$WALLET-KEY URL, but can be safely ignored
-    by the wallet.  The contract should be shown to the user
-    in the canonical dialog, possibly in a fresh tab.
+  :status 304 Not modified:
+    The version available at the server is identical to that
+    specified in the "If-None-Match" header.
+
+  :status 404 Not found:
+    The backup service is unaware of a matching account.
 
   :status 410 Gone:
     The backup service has closed operations.  The body will
@@ -171,24 +171,24 @@ Receiving Terms of Service
     The user should be urged to find another provider.
 
   :status 429 Too many requests:
-    This account has exceeded daily thresholds for the number of
-    requests.  The wallet should try again later, and may want
+    This account has exceeded thresholds for the number of
+    requests.  The client should try again later, and may want
     to decrease its synchronization frequency.
 
   .. note::
 
     "200 OK" responses include an HTTP header
-    "X-Taler-Sync-Signature" with the signature of the
-    wallet from the orginal upload, and an
-    "X-Taler-Sync-Previous" with the version that was
+    "Sync-Signature" with the signature of the
+    client from the orginal upload, and an
+    "Sync-Previous" with the version that was
     being updated (unless this is the first revision).
-    "X-Taler-Sync-Previous" is only given to enable
+    "Sync-Previous" is only given to enable
     signature validation.
 
 
-.. http:post:: /$WALLET-KEY
+.. http:post:: /$ACCOUNT-KEY
 
-  Upload a new version of the wallet's database, or download the
+  Upload a new version of the account's database, or download the
   latest version.  The request must include the "Expect: 100 Continue"
   header.  The client must wait for "100 Continue" before proceeding
   with the upload, regardless of the size of the upload.
@@ -196,28 +196,51 @@ Receiving Terms of Service
   **Request**
 
   The request must include a "If-Match" header indicating the latest
-  version of the wallet's database known to the client.  If the server
+  version of the account's database known to the client.  If the server
   knows a more recent version, it will respond with a "409 conflict"
   and return the server's version in the response.  The client must
   then merge the two versions before retrying the upload.  Note that
   a "409 Conflict" response will typically be given before the upload,
   (instead of "100 continue"), but may also be given after the upload,
-  for example due to concurrent activities from other wallets on the
+  for example due to concurrent activities from other accounts on the
   same account!
 
-  The request must also include an "X-Taler-Sync-Signature" signing
+  The request must also include an "Sync-Signature" signing
   the "If-Match" SHA-512 value and the SHA-512 hash of the body with
-  the wallet private key.
+  the account private key.
 
   Finally, the SHA-512 hash of the body must also be given in an
-  "E-tag" header of the request (so that the signature can be verified
+  "Etag" header of the request (so that the signature can be verified
   before the upload is allowed to proceed).  We note that the use
-  of "E-tag" in HTTP requests is non-standard, but in this case
+  of "ETag" in HTTP requests is non-standard, but in this case
   logical.
 
   The uploaded body must have at least 32 bytes of payload (see
   suggested upload format beginning with an ephemeral key).
 
+  :query paying:
+     Optional argument providing an order identifier.
+     The client is promising that it is already paying on a
+     related order. This will cause the
+     server to delay processing until the respective payment
+     has arrived (if the operation requires a payment). Useful
+     if the server previously returned a ``402 Payment required``
+     and the client wants to proceed as soon as the payment
+     went through.
+  :query pay:
+     Optional argument, any non-empty value will do,
+     suggested is ``y`` for ``yes``.
+     The client insists on making a payment for the respective
+     account, even if this is not yet required. The server
+     will respond with a ``402 Payment required'', but only
+     if the rest of the request is well-formed (account
+     signature must match).  Clients that do not actually
+     intend to make a new upload but that only want to pay
+     may attempt to upload the latest backup again, as this
+     option will be checked before the ``304 Not modified``
+     case.
+
+
 
   **Response**
 
@@ -226,7 +249,7 @@ Receiving Terms of Service
     the new version.
 
   :status 304 Not modified:
-    The server is already aware of this version of the wallet.
+    The server is already aware of this version of the client.
     Returned before 100 continue to avoid upload.
 
   :status 400 Bad request:
@@ -238,8 +261,8 @@ Receiving Terms of Service
   :status 402 Payment required:
     The synchronization service requires payment before the
     account can continue to be used.  The fulfillment URL
-    should be the /$WALLET-KEY URL, but can be safely ignored
-    by the wallet.  The contract should be shown to the user
+    should be the /$ACCOUNT-KEY URL, but can be safely ignored
+    by the client.  The contract should be shown to the user
     in the canonical dialog, possibly in a fresh tab.
 
   :status 409 Conflict:
@@ -262,24 +285,22 @@ Receiving Terms of Service
 
   :status 413 Request Entity Too Large:
     The requested upload exceeds the quota for the type of
-    account.  The wallet should suggest to the user to
+    account.  The client should suggest to the user to
     migrate to another backup and synchronization service
     (like with "410 Gone").
 
   :status 429 Too many requests:
     This account has exceeded daily thresholds for the number of
-    requests.  The wallet should try again later, and may want
+    requests.  The client should try again later, and may want
     to decrease its synchronization frequency.
 
   .. note::
 
     Responses with a body include an HTTP header
-    "X-Taler-Sync-Signature" with the signature of the
-    wallet from the orginal upload, and an
-    "X-Taler-Sync-Previous" with the version that was
+    "Sync-Signature" with the signature of the
+    client from the orginal upload, and an
+    "If-Match" with the version that is
     being updated (unless this is the first revision).
-    "X-Taler-Sync-Previous" is only given to enable
-    signature validation.
 
 
 
@@ -287,7 +308,7 @@ Receiving Terms of Service
 Special constraints for Tor
 ---------------------------
 
-We might introduce the notion of a "constraint" into the wallet's
+We might introduce the notion of a "constraint" into the client's
 database that states that the database is a "Tor wallet".  Then,
 synchronizing a "Tor-wallet" with a non-Tor wallet should trigger a
 stern warning and require user confirmation (as otherwise
@@ -299,7 +320,7 @@ users).
 Discovery of backup and synchronization services
 ------------------------------------------------
 
-The wallet should keep a list of "default" synchronization services
+The client should keep a list of "default" synchronization services
 per currency (by the currency the synchronization service accepts
 for payment).  If a synchronization service is entirely free, it
 should be kept in a special list that is always available.
@@ -308,17 +329,17 @@ Extending (or shortening) the list of synchronization services should
 be possible using the same mechanism that is used to add/remove
 auditors or exchanges.
 
-The wallet should urge the user to make use of a synchronization
+The client should urge the user to make use of a synchronization
 service upon first withdrawal, suggesting one that is free or
 accepts payment in the respective currency. If none is available,
-the wallet should warn the user about the lack of availalable
+the client should warn the user about the lack of availalable
 backups and synchronization and suggest to the user to find a
 reasonable service.  Once a synchronization service was selected,
-the wallet should urge the user to print the respective key
+the client should urge the user to print the respective key
 material.
 
-When the wallet starts the first time on a new device, it should
-ask the user if he wants to synchronize with an existing wallet,
+When the client starts the first time on a new device, it should
+ask the user if he wants to synchronize with an existing client,
 and if so, ask the user to enter the respective key and the
 (base) URL of the synchronization service.
 
@@ -327,10 +348,10 @@ and if so, ask the user to enter the respective key and the
 Synchronization frequency
 -------------------------
 
-Generally, the wallet should attempt to synchronize at a randomized
+Generally, the client should attempt to synchronize at a randomized
 time interval between 30 and 300 seconds of being started, unless it
 already synchronized less than two hours ago already.  Afterwards,
-the wallet should synchronize every two hours, or after purchases
+the client should synchronize every two hours, or after purchases
 exceed 5 percent of the last bulk amount that the user withdrew.
 In all cases the exact time of synchronization should be randomized
 between 30 and 300 seconds of the specified event, both to minimize
@@ -362,7 +383,7 @@ The menu should include three entries for synchronization:
     including manual specification of a URL; here
     confirmation should only be possible if the provider
     is free or can be paid for; in this case, the
-    wallet should trigger the payment interaction when
+    client should trigger the payment interaction when
     the user presses the "select" button.
   * a special button to "disable synchronization and backup"