[taler-sync] branch master updated: define sync API

[gnunet]

This is an automated email from the git hooks/post-receive script.

grothoff pushed a commit to branch master
in repository sync.

The following commit(s) were added to refs/heads/master by this push:
     new 3986928  define sync API
3986928 is described below

commit 398692841c64a0c486af1bfbeb47df3bc0cc3534
Author: Christian Grothoff <address@hidden>
AuthorDate: Sun Nov 17 19:24:00 2019 +0100

    define sync API
---
 src/include/sync_service.h | 225 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 213 insertions(+), 12 deletions(-)

diff --git a/src/include/sync_service.h b/src/include/sync_service.h
index 595df3c..b210921 100644
--- a/src/include/sync_service.h
+++ b/src/include/sync_service.h
@@ -18,14 +18,17 @@
  * @brief C interface of libsync, a C library to use sync's HTTP API
  * @author Christian Grothoff
  */
-#ifndef _SYNC_SERVICE_H
-#define _SYNC_SERVICE_H
+#ifndef SYNC_SERVICE_H
+#define SYNC_SERVICE_H
 
 #include <gnunet/gnunet_util_lib.h>
 #include <gnunet/gnunet_curl_lib.h>
 #include <jansson.h>
 
 
+GNUNET_NETWORK_STRUCT_BEGIN
+
+
 /**
  * Private key identifying an account.
  */
@@ -50,9 +53,6 @@ struct SYNC_AccountPublicKeyP
 };
 
 
-GNUNET_NETWORK_STRUCT_BEGIN
-
-
 /**
  * Data signed by the account public key of a sync client to
  * authorize the upload of the backup.
@@ -77,9 +77,6 @@ struct SYNC_UploadSignaturePS
 };
 
 
-GNUNET_NETWORK_STRUCT_END
-
-
 /**
  * Signature made with an account's public key.
  */
@@ -91,29 +88,233 @@ struct SYNC_AccountSignatureP
   struct GNUNET_CRYPTO_EddsaSignature eddsa_sig;
 };
 
+GNUNET_NETWORK_STRUCT_END
 
+
+/**
+ * High-level ways how an upload may conclude.
+ */
+enum SYNC_UploadStatus
+{
+  /**
+   * Backup was successfully made.
+   */
+  SYNC_US_SUCCESS = 0,
+
+  /**
+   * Account expired or payment was explicitly requested
+   * by the client.
+   */
+  SYNC_US_PAYMENT_REQUIRED = 1,
+
+  /**
+   * Conflicting backup existed on server. Client should
+   * reconcile and try again with (using the provided
+   * recovered backup as the previous backup).
+   */
+  SYNC_US_CONFLICTING_BACKUP = 2,
+
+  /**
+   * HTTP interaction failed, see HTTP status.
+   */
+  SYNC_US_HTTP_ERROR = 3,
+
+  /**
+   * We had an internal error (not sure this can happen,
+   * but reserved for HTTP 400 status codes).
+   */
+  SYNC_US_CLIENT_ERROR = 4,
+
+  /**
+   * Server had an internal error.
+   */
+  SYNC_US_SERVER_ERROR = 5
+};
+
+
+/**
+ * Result of an upload.
+ */
+struct SYNC_UploadDetails
+{
+  /**
+   * High level status of the upload operation.
+   */
+  enum SYNC_UploadStatus us;
+
+  union
+  {
+
+    /**
+     * Hash of the synchronized backup, returned if
+     * @e us is #SYNC_US_SUCCESS.
+     */
+    const struct GNUNET_HashCode *curr_backup_hash;
+
+    /**
+     * Previous backup. Returned if @e us is
+     * #SYNC_US_CONFLICTING_BACKUP
+     */
+    struct
+    {
+      /**
+       * Hash over @e existing_backup.
+       */
+      const struct GNUNET_HashCode *existing_backup_hash;
+
+      /**
+       * Number of bytes in @e existing_backup.
+       */
+      size_t existing_backup_size;
+
+      /**
+       * The backup on the server, which does not match the
+       * "previous" backup expected by the client and thus
+       * needs to be decrypted, reconciled and re-uploaded.
+       */
+      const void *existing_backup;
+
+    } recovered_backup;
+
+    /**
+     * A taler://pay/-URI with a request to pay the annual fee for
+     * the service.  Returned if @e us is #SYNC_US_PAYMENT_REQUIRED.
+     */
+    const char *payment_request;
+
+  } details;
+
+};
+
+
+/**
+ * Function called with the results of a #SYNC_upload().
+ *
+ * @param cls closure
+ * @param ec Taler error code
+ * @param http_status HTTP status of the request
+ * @param ud details about the upload operation
+ */
+typedef void
+(*SYNC_UploadCallback)(void *cls,
+                       enum TALER_ErrorCode ec,
+                       unsigned int http_status,
+                       const struct SYNC_UploadDetails *ud);
+
+
+/**
+ * Handle for an upload operatoin.
+ */
 struct SYNC_UploadOperation;
 
+
+/**
+ * Upload a @a backup to a Sync server. Note that @a backup must
+ * have already been compressed, padded and encrypted by the
+ * client.
+ *
+ * While @a pub is theoretically protected by the HTTPS protocol and
+ * required to access the backup, it should be assumed that an
+ * adversary might be able to download the backups from the Sync
+ * server -- or even run the Sync server. Thus, strong encryption
+ * is essential and NOT implemented by this function.
+ *
+ * The use of Anastasis to safely store the Sync encryption keys and
+ * @a pub is recommended.  Storing @a priv in Anastasis depends on
+ * your priorities: without @a priv, further updates to the backup are
+ * not possible, and the user would have to pay for another
+ * account. OTOH, without @a priv an adversary that compromised
+ * Anastasis can only read the backups, but not alter or destroy them.
+ *
+ * @param ctx for HTTP client request processing
+ * @param base_url base URL of the Sync server
+ * @param priv private key of an account with the server
+ * @param prev_backup_hash hash of the previous backup, NULL for the first 
upload ever
+ * @param backup_size number of bytes in @a backup
+ * @param payment_requested #GNUNET_YES if the client wants to pay more for 
the account now
+ * @param paid_order_id order ID of a recent payment made, or NULL for none
+ * @param cb function to call with the result
+ * @param cb_cls closure for @a cb
+ * @return handle for the operation
+ */
 struct SYNC_UploadOperation *
 SYNC_upload (struct GNUNET_CURL_Context *ctx,
              const char *base_url,
-             ...);
+             struct SYNC_AccountPrivateKeyP *priv,
+             const struct GNUNET_HashCode *prev_backup_hash,
+             size_t backup_size,
+             const void *backup,
+             int payment_requested,
+             const char *paid_order_id,
+             SYNC_UploadCallback cb,
+             void *cb_cls);
 
 
+/**
+ * Cancel the upload.  Note that aborting an upload does NOT guarantee
+ * that it did not complete, it is possible that the server did
+ * receive the full request before the upload is aborted.
+ *
+ * @param uo operation to cancel.
+ */
 void
 SYNC_upload_cancel (struct SYNC_UploadOperation *uo);
 
 
+/**
+ * Function called with the results of a #SYNC_download().
+ *
+ * @param cls closure
+ * @param sig signature of the account owner, affirming the
+ *            integrity of the backup (already verified)
+ * @param prev_backup_hash hash of the previous backup (used
+ *            to verify the signature, could be used by clients
+ *            to verify backup chains)
+ * @param curr_backup_hash hash over @a backup (verified)
+ * @param backup_size number of bytes in @a backup
+ * @param backup the lastest backup as downloaded from the
+ *        server and affirmed by @a sig
+ */
+typedef void
+(*SYNC_DownloadCallback)(void *cls,
+                         const struct SYNC_AccountPublicKeyP *sig,
+                         const struct GNUNET_HashCode *prev_backup_hash,
+                         const struct GNUNET_HashCode *curr_backup_hash,
+                         size_t backup_size,
+                         const void *backup);
+
+
+/**
+ * Handle for a download operation.
+ */
 struct SYNC_DownloadOperation;
 
+
+/**
+ * Download the latest version of a backup for account @a pub.
+ *
+ * @param ctx for HTTP client request processing
+ * @param base_url base URL of the Sync server
+ * @param pub account public key
+ * @param cb function to call with the backup
+ * @param cb_cls closure for @a cb
+ * @return handle for the operation
+ */
 struct SYNC_DownloadOperation *
 SYNC_download (struct GNUNET_CURL_Context *ctx,
                const char *base_url,
-               ...);
+               const struct SYNC_AccountPublicKeyP *pub,
+               SYNC_DownloadCallback cb,
+               void *cb_cls);
 
 
+/**
+ * Cancel the download.
+ *
+ * @param do operation to cancel.
+ */
 void
-SYNC_download_cancel (struct SYNC_DownloadOperation *uo);
+SYNC_download_cancel (struct SYNC_DownloadOperation *download);
 
 
-#endif  /* _SYNC_SERVICE_H */
+#endif  /* SYNC_SERVICE_H */

-- 
To stop receiving notification emails like this one, please contact
address@hidden.