introducing GNUNET_CRYPTO_ecdhe_create2() to avoid malloc nonsense

[oweals/gnunet.git] / src / include / gnunet_set_service.h

diff --git a/src/include/gnunet_set_service.h b/src/include/gnunet_set_service.h
index 72d7ee521c667dc6548211631e21fee9448d81b9..44773f1872457753d44769225482e0b58ffe8c5f 100644 (file)
--- a/src/include/gnunet_set_service.h
+++ b/src/include/gnunet_set_service.h
@@ -1,10 +1,10 @@
 /*
       This file is part of GNUnet
 /*
       This file is part of GNUnet

-      (C) 2013 Christian Grothoff (and other contributing authors)
+      Copyright (C) 2013, 2014 GNUnet e.V.

 
       GNUnet is free software; you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published
 
       GNUnet 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 Foundation; either version 2, or (at your
+      by the Free Software Foundation; either version 3, or (at your

       option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but
       option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but


@@ -14,14 +14,23 @@
 
       You should have received a copy of the GNU General Public License
       along with GNUnet; see the file COPYING.  If not, write to the
 
       You should have received a copy of the GNU General Public License
       along with GNUnet; see the file COPYING.  If not, write to the

-      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-      Boston, MA 02111-1307, USA.
+      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+      Boston, MA 02110-1301, USA.

  */
 
 /**
  */
 
 /**

- * @file include/gnunet_set_service.h
- * @brief two-peer set operations

  * @author Florian Dold
  * @author Florian Dold

+ * @author Christian Grothoff
+ *
+ * @file
+ * Two-peer set operations
+ *
+ * @defgroup set  Set service
+ * Two-peer set operations
+ *
+ * @see [Documentation](https://gnunet.org/set-subsystem)
+ *
+ * @{

  */
 
 #ifndef GNUNET_SET_SERVICE_H
  */
 
 #ifndef GNUNET_SET_SERVICE_H


@@ -35,12 +44,17 @@ extern "C"
 #endif
 #endif
 
 #endif
 #endif
 

-#include "platform.h"

 #include "gnunet_common.h"
 #include "gnunet_time_lib.h"
 #include "gnunet_configuration_lib.h"
 
 
 #include "gnunet_common.h"
 #include "gnunet_time_lib.h"
 #include "gnunet_configuration_lib.h"
 
 

+/**
+ * Maximum size of a context message for set operation requests.
+ */
+#define GNUNET_SET_CONTEXT_MESSAGE_MAX_SIZE ((1<<16) - 1024)
+
+

 /**
  * Opaque handle to a set.
  */
 /**
  * Opaque handle to a set.
  */


@@ -67,30 +81,57 @@ struct GNUNET_SET_OperationHandle;
  */
 enum GNUNET_SET_OperationType
 {
  */
 enum GNUNET_SET_OperationType
 {

+  /**
+   * A purely local set that does not support any operation.
+   */
+  GNUNET_SET_OPERATION_NONE,
+

   /**
    * Set intersection, only return elements that are in both sets.
    */
   GNUNET_SET_OPERATION_INTERSECTION,
   /**
    * Set intersection, only return elements that are in both sets.
    */
   GNUNET_SET_OPERATION_INTERSECTION,

+

   /**
    * Set union, return all elements that are in at least one of the sets.
    */
   GNUNET_SET_OPERATION_UNION
 };
 
   /**
    * Set union, return all elements that are in at least one of the sets.
    */
   GNUNET_SET_OPERATION_UNION
 };
 

+

 /**
  * Status for the result callback
  */
 enum GNUNET_SET_Status
 {
   /**
 /**
  * Status for the result callback
  */
 enum GNUNET_SET_Status
 {
   /**

-   * Everything went ok.
+   * Everything went ok, we are transmitting an element of the
+   * result (in set, or to be removed from set, depending on
+   * the `enum GNUNET_SET_ResultMode`).
+   *
+   * Only applies to
+   * #GNUNET_SET_RESULT_FULL,
+   * #GNUNET_SET_RESULT_ADDED,
+   * #GNUNET_SET_RESULT_REMOVED,

    */
   GNUNET_SET_STATUS_OK,
 
   /**
    */
   GNUNET_SET_STATUS_OK,
 
   /**

-   * There was a timeout.
+   * Element should be added to the result set
+   * of the local peer, i.e. the local peer is
+   * missing an element.
+   *
+   * Only applies to #GNUNET_SET_RESULT_SYMMETRIC

    */
    */

-  GNUNET_SET_STATUS_TIMEOUT,
+  GNUNET_SET_STATUS_ADD_LOCAL,
+
+  /**
+   * Element should be added to the result set
+   * of the remove peer, i.e. the remote peer is
+   * missing an element.
+   *
+   * Only applies to #GNUNET_SET_RESULT_SYMMETRIC
+   */
+  GNUNET_SET_STATUS_ADD_REMOTE,

 
   /**
    * The other peer refused to to the operation with us,
 
   /**
    * The other peer refused to to the operation with us,


@@ -99,8 +140,9 @@ enum GNUNET_SET_Status
   GNUNET_SET_STATUS_FAILURE,
 
   /**
   GNUNET_SET_STATUS_FAILURE,
 
   /**

-   * Success, all elements have been returned (but the other
-   * peer might still be receiving some from us, so we are not done).
+   * Success, all elements have been returned (but the other peer
+   * might still be receiving some from us, so we are not done).  Only
+   * used during UNION operation.

    */
   GNUNET_SET_STATUS_HALF_DONE,
 
    */
   GNUNET_SET_STATUS_HALF_DONE,
 


@@ -110,6 +152,7 @@ enum GNUNET_SET_Status
   GNUNET_SET_STATUS_DONE
 };
 
   GNUNET_SET_STATUS_DONE
 };
 

+

 /**
  * The way results are given to the client.
  */
 /**
  * The way results are given to the client.
  */


@@ -117,20 +160,35 @@ enum GNUNET_SET_ResultMode
 {
   /**
    * Client gets every element in the resulting set.
 {
   /**
    * Client gets every element in the resulting set.

+   *
+   * Only supported for set intersection.

    */
   GNUNET_SET_RESULT_FULL,
    */
   GNUNET_SET_RESULT_FULL,

+

   /**
   /**

-   * Client gets only elements that have been added to the set.
-   * Only works with set union.
+   * Client gets notified of the required changes
+   * for both the local and the remote set.
+   *
+   * Only supported for set

    */
    */

-  GNUNET_SET_RESULT_ADDED,
+  GNUNET_SET_RESULT_SYMMETRIC,
+
+  /**
+   * Client gets only elements that have been removed from the set.
+   *
+   * Only supported for set intersection.
+   */
+  GNUNET_SET_RESULT_REMOVED,
+

   /**
    * Client gets only elements that have been removed from the set.
   /**
    * Client gets only elements that have been removed from the set.

-   * Only works with set intersection.
+   *
+   * Only supported for set union.

    */
    */

-  GNUNET_SET_RESULT_REMOVED
+  GNUNET_SET_RESULT_ADDED

 };
 
 };
 

+

 /**
  * Element stored in a set.
  */
 /**
  * Element stored in a set.
  */


@@ -144,7 +202,7 @@ struct GNUNET_SET_Element
   /**
    * Application-specific element type.
    */
   /**
    * Application-specific element type.
    */

-  uint16_t type;
+  uint16_t element_type;

 
   /**
    * Actual data of the element
 
   /**
    * Actual data of the element


@@ -156,9 +214,10 @@ struct GNUNET_SET_Element
 /**
  * Continuation used for some of the set operations
  *
 /**
  * Continuation used for some of the set operations
  *

- * @cls closure
+ * @param cls closure

  */
  */

-typedef void (*GNUNET_SET_Continuation) (void *cls);
+typedef void
+(*GNUNET_SET_Continuation) (void *cls);

 
 
 /**
 
 
 /**


@@ -166,27 +225,41 @@ typedef void (*GNUNET_SET_Continuation) (void *cls);
  * in the result set.
  *
  * @param cls closure
  * in the result set.
  *
  * @param cls closure

- * @param element a result element, only valid if status is GNUNET_SET_STATUS_OK
- * @param status see enum GNUNET_SET_Status
+ * @param element a result element, only valid if status is #GNUNET_SET_STATUS_OK
+ * @param status see `enum GNUNET_SET_Status`

  */
  */

-typedef void (*GNUNET_SET_ResultIterator) (void *cls,
-                                           const struct GNUNET_SET_Element *element,
-                                           enum GNUNET_SET_Status status);
+typedef void
+(*GNUNET_SET_ResultIterator) (void *cls,
+                              const struct GNUNET_SET_Element *element,
+                              enum GNUNET_SET_Status status);
+
+/**
+ * Iterator for set elements.
+ *
+ * @param cls closure
+ * @param element the current element, NULL if all elements have been
+ *        iterated over
+ * @return #GNUNET_YES to continue iterating, #GNUNET_NO to stop.
+ */
+typedef int
+(*GNUNET_SET_ElementIterator) (void *cls,
+                               const struct GNUNET_SET_Element *element);

 
 
 /**
  * Called when another peer wants to do a set operation with the
 
 
 /**
  * Called when another peer wants to do a set operation with the

- * local peer
+ * local peer. If a listen error occurs, the @a request is NULL.

  *
  *

+ * @param cls closure

  * @param other_peer the other peer
  * @param context_msg message with application specific information from
  *        the other peer
  * @param other_peer the other peer
  * @param context_msg message with application specific information from
  *        the other peer

- * @param request request from the other peer, use GNUNET_SET_accept
+ * @param request request from the other peer (never NULL), use GNUNET_SET_accept()

  *        to accept it, otherwise the request will be refused
  *        to accept it, otherwise the request will be refused

- *        Note that we don't use a return value here, as it is also
- *        necessary to specify the set we want to do the operation with,
- *        whith sometimes can be derived from the context message.
- *        Also necessary to specify the timeout.
+ *        Note that we can't just return value from the listen callback,
+ *        as it is also necessary to specify the set we want to do the
+ *        operation with, whith sometimes can be derived from the context
+ *        message. It's necessary to specify the timeout.

  */
 typedef void
 (*GNUNET_SET_ListenCallback) (void *cls,
  */
 typedef void
 (*GNUNET_SET_ListenCallback) (void *cls,


@@ -196,6 +269,11 @@ typedef void
 
 
 
 
 
 

+typedef void
+(*GNUNET_SET_CopyReadyCallback) (void *cls,
+                                 struct GNUNET_SET_Handle *copy);
+
+

 /**
  * Create an empty set, supporting the specified operation.
  *
 /**
  * Create an empty set, supporting the specified operation.
  *


@@ -215,15 +293,17 @@ GNUNET_SET_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
 /**
  * Add an element to the given set.
  * After the element has been added (in the sense of being
 /**
  * Add an element to the given set.
  * After the element has been added (in the sense of being

- * transmitted to the set service), cont will be called.
- * Calls to add_element can be queued
+ * transmitted to the set service), @a cont will be called.
+ * Calls to #GNUNET_SET_add_element can be queued

  *
  * @param set set to add element to
  * @param element element to add to the set
  * @param cont continuation called after the element has been added
  *
  * @param set set to add element to
  * @param element element to add to the set
  * @param cont continuation called after the element has been added

- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
+ *         set is invalid (e.g. the set service crashed)

  */
  */

-void
+int

 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
                         const struct GNUNET_SET_Element *element,
                         GNUNET_SET_Continuation cont,
 GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
                         const struct GNUNET_SET_Element *element,
                         GNUNET_SET_Continuation cont,


@@ -239,63 +319,70 @@ GNUNET_SET_add_element (struct GNUNET_SET_Handle *set,
  * @param set set to remove element from
  * @param element element to remove from the set
  * @param cont continuation called after the element has been removed
  * @param set set to remove element from
  * @param element element to remove from the set
  * @param cont continuation called after the element has been removed

- * @param cont_cls closure for cont
+ * @param cont_cls closure for @a cont
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
+ *         set is invalid (e.g. the set service crashed)

  */
  */

-void
+int

 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
                            const struct GNUNET_SET_Element *element,
                            GNUNET_SET_Continuation cont,
                            void *cont_cls);
 
 
 GNUNET_SET_remove_element (struct GNUNET_SET_Handle *set,
                            const struct GNUNET_SET_Element *element,
                            GNUNET_SET_Continuation cont,
                            void *cont_cls);
 
 

+void
+GNUNET_SET_copy_lazy (struct GNUNET_SET_Handle *set,
+                      GNUNET_SET_CopyReadyCallback cb,
+                      void *cls);
+
+

 /**
  * Destroy the set handle, and free all associated resources.
 /**
  * Destroy the set handle, and free all associated resources.

+ * Iterations must have completed (or be explicitly canceled)
+ * before destroying the corresponding set.  Operations may
+ * still be pending when a set is destroyed.
+ *
+ * @param set set to destroy

  */
 void
 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
 
 
 /**
  */
 void
 GNUNET_SET_destroy (struct GNUNET_SET_Handle *set);
 
 
 /**

- * Evaluate a set operation with our set and the set of another peer.
+ * Prepare a set operation to be evaluated with another peer.
+ * The evaluation will not start until the client provides
+ * a local set with GNUNET_SET_commit().

  *
  *

- * @param set set to use
- * @param salt salt for HKDF (explain more here)

  * @param other_peer peer with the other set
  * @param app_id hash for the application using the set
  * @param context_msg additional information for the request
  * @param other_peer peer with the other set
  * @param app_id hash for the application using the set
  * @param context_msg additional information for the request

- * @param salt salt used for the set operation; sometimes set operations
- *        fail due to hash collisions, using a different salt for each operation
- *        makes it harder for an attacker to exploit this
- * @param timeout result_cb will be called with GNUNET_SET_STATUS_TIMEOUT
- *        if the operation is not done after the specified time; @deprecated

  * @param result_mode specified how results will be returned,
  * @param result_mode specified how results will be returned,

- *        see 'GNUNET_SET_ResultMode'.
+ *        see `enum GNUNET_SET_ResultMode`.

  * @param result_cb called on error or success
  * @param result_cb called on error or success

- * @param result_cls closure for result_cb
+ * @param result_cls closure for @a result_cb

  * @return a handle to cancel the operation
  */
 struct GNUNET_SET_OperationHandle *
  * @return a handle to cancel the operation
  */
 struct GNUNET_SET_OperationHandle *

-GNUNET_SET_evaluate (struct GNUNET_SET_Handle *set,
-                     const struct GNUNET_PeerIdentity *other_peer,
-                     const struct GNUNET_HashCode *app_id,
-                     const struct GNUNET_MessageHeader *context_msg,
-                     uint16_t salt,
-                     struct GNUNET_TIME_Relative timeout,
-                     enum GNUNET_SET_ResultMode result_mode,
-                     GNUNET_SET_ResultIterator result_cb,
-                     void *result_cls);
+GNUNET_SET_prepare (const struct GNUNET_PeerIdentity *other_peer,
+                    const struct GNUNET_HashCode *app_id,
+                    const struct GNUNET_MessageHeader *context_msg,
+                    enum GNUNET_SET_ResultMode result_mode,
+                    GNUNET_SET_ResultIterator result_cb,
+                    void *result_cls);

 
 
 /**
 
 
 /**

- * Wait for set operation requests for the given application id
- * 
+ * Wait for set operation requests for the given application ID.
+ * If the connection to the set service is lost, the listener is
+ * re-created transparently with exponential backoff.
+ *

  * @param cfg configuration to use for connecting to
  *            the set service
  * @param operation operation we want to listen for
  * @param app_id id of the application that handles set operation requests
  * @param listen_cb called for each incoming request matching the operation
  *                  and application id
  * @param cfg configuration to use for connecting to
  *            the set service
  * @param operation operation we want to listen for
  * @param app_id id of the application that handles set operation requests
  * @param listen_cb called for each incoming request matching the operation
  *                  and application id

- * @param listen_cls handle for listen_cb
+ * @param listen_cls handle for @a listen_cb

  * @return a handle that can be used to cancel the listen operation
  */
 struct GNUNET_SET_ListenHandle *
  * @return a handle that can be used to cancel the listen operation
  */
 struct GNUNET_SET_ListenHandle *


@@ -306,9 +393,9 @@ GNUNET_SET_listen (const struct GNUNET_CONFIGURATION_Handle *cfg,
                    void *listen_cls);
 
 
                    void *listen_cls);
 
 

-

 /**
 /**

- * Cancel the given listen operation.
+ * Cancel the given listen operation.  After calling cancel, the
+ * listen callback for this listen handle will not be called again.

  *
  * @param lh handle for the listen operation
  */
  *
  * @param lh handle for the listen operation
  */


@@ -316,30 +403,49 @@ void
 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
 
 
 GNUNET_SET_listen_cancel (struct GNUNET_SET_ListenHandle *lh);
 
 

-

 /**
 /**

- * Accept a request we got via GNUNET_SET_listen.
+ * Accept a request we got via GNUNET_SET_listen().  Must be called during
+ * GNUNET_SET_listen(), as the `struct GNUNET_SET_Request` becomes invalid
+ * afterwards.
+ * Call GNUNET_SET_commit() to provide the local set to use for the operation,
+ * and to begin the exchange with the remote peer.

  *
  * @param request request to accept
  *
  * @param request request to accept

- * @param set set used for the requested operation 
- * @param timeout timeout for the set operation, @deprecated

  * @param result_mode specified how results will be returned,
  * @param result_mode specified how results will be returned,

- *        see 'GNUNET_SET_ResultMode'.
+ *        see `enum GNUNET_SET_ResultMode`.

  * @param result_cb callback for the results
  * @param result_cb callback for the results

- * @param result_cls closure for result_cb
+ * @param result_cls closure for @a result_cb

  * @return a handle to cancel the operation
  */
 struct GNUNET_SET_OperationHandle *
 GNUNET_SET_accept (struct GNUNET_SET_Request *request,
  * @return a handle to cancel the operation
  */
 struct GNUNET_SET_OperationHandle *
 GNUNET_SET_accept (struct GNUNET_SET_Request *request,

-                   struct GNUNET_SET_Handle *set,
-                   struct GNUNET_TIME_Relative timeout,

                    enum GNUNET_SET_ResultMode result_mode,
                    GNUNET_SET_ResultIterator result_cb,
                    enum GNUNET_SET_ResultMode result_mode,
                    GNUNET_SET_ResultIterator result_cb,

-                   void *cls);
+                   void *result_cls);

 
 
 /**
 
 
 /**

- * Cancel the given set operation.
+ * Commit a set to be used with a set operation.
+ * This function is called once we have fully constructed
+ * the set that we want to use for the operation.  At this
+ * time, the P2P protocol can then begin to exchange the
+ * set information and call the result callback with the
+ * result information.
+ *
+ * @param oh handle to the set operation
+ * @param set the set to use for the operation
+ * @return #GNUNET_OK on success, #GNUNET_SYSERR if the
+ *         set is invalid (e.g. the set service crashed)
+ */
+int
+GNUNET_SET_commit (struct GNUNET_SET_OperationHandle *oh,
+                   struct GNUNET_SET_Handle *set);
+
+
+/**
+ * Cancel the given set operation.  May not be called after the
+ * operation's `GNUNET_SET_ResultIterator` has been called with a
+ * status that indicates error, timeout or done.

  *
  * @param oh set operation to cancel
  */
  *
  * @param oh set operation to cancel
  */


@@ -347,6 +453,55 @@ void
 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
 
 
 GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
 
 

+/**
+ * Iterate over all elements in the given set.
+ * Note that this operation involves transferring every element of the set
+ * from the service to the client, and is thus costly.
+ * Only one iteration per set may be active at the same time.
+ *
+ * @param set the set to iterate over
+ * @param iter the iterator to call for each element
+ * @param iter_cls closure for @a iter
+ * @return #GNUNET_YES if the iteration started successfuly,
+ *         #GNUNET_NO if another iteration was still active,
+ *         #GNUNET_SYSERR if the set is invalid (e.g. the server crashed, disconnected)
+ */
+int
+GNUNET_SET_iterate (struct GNUNET_SET_Handle *set,
+                    GNUNET_SET_ElementIterator iter,
+                    void *iter_cls);
+
+/**
+ * Stop iteration over all elements in the given set.  Can only
+ * be called before the iteration has "naturally" completed its
+ * turn.
+ *
+ * @param set the set to stop iterating over
+ */
+void
+GNUNET_SET_iterate_cancel (struct GNUNET_SET_Handle *set);
+
+/**
+ * Create a copy of an element.  The copy
+ * must be GNUNET_free-d by the caller.
+ *
+ * @param element the element to copy
+ * @return the copied element
+ */
+struct GNUNET_SET_Element *
+GNUNET_SET_element_dup (const struct GNUNET_SET_Element *element);
+
+/**
+ * Hash a set element.
+ *
+ * @param element the element that should be hashed
+ * @param ret_hash a pointer to where the hash of @a element
+ *        should be stored
+ */
+void
+GNUNET_SET_element_hash (const struct GNUNET_SET_Element *element, struct GNUNET_HashCode *ret_hash);
+
+

 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif
 #if 0                           /* keep Emacsens' auto-indent happy */
 {
 #endif


@@ -355,3 +510,5 @@ GNUNET_SET_operation_cancel (struct GNUNET_SET_OperationHandle *oh);
 #endif
 
 #endif
 #endif
 
 #endif

+
+/** @} */  /* end of group */