src/reclaim/gnunet-service-reclaim_tickets.h

   1 /*
   2    This file is part of GNUnet.
   3    Copyright (C) 2012-2015 GNUnet e.V.
   4
   5    GNUnet is free software: you can redistribute it and/or modify it
   6    under the terms of the GNU Affero General Public License as published
   7    by the Free Software Foundation, either version 3 of the License,
   8    or (at your option) any later version.
   9
  10    GNUnet is distributed in the hope that it will be useful, but
  11    WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Affero General Public License for more details.
  14
  15    You should have received a copy of the GNU Affero General Public License
  16    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18    SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Martin Schanzenbach
  23  * @file src/reclaim/gnunet-service-reclaim_tickets.h
  24  * @brief reclaim tickets
  25  *
  26  */
  27
  28 #ifndef GNUNET_SERVICE_RECLAIM_TICKETS_H
  29 #define GNUNET_SERVICE_RECLAIM_TICKETS_H
  30
  31 #include "platform.h"
  32
  33 #include "gnunet_util_lib.h"
  34
  35 #include "gnunet_constants.h"
  36 #include "gnunet_gns_service.h"
  37 #include "gnunet_gnsrecord_lib.h"
  38 #include "gnunet_protocols.h"
  39 #include "gnunet_reclaim_lib.h"
  40 #include "gnunet_reclaim_service.h"
  41 #include "gnunet_signatures.h"
  42 #include "gnunet_statistics_service.h"
  43 #include "reclaim.h"
  44
  45 /**
  46  * Ticket iterator
  47  */
  48 struct RECLAIM_TICKETS_Iterator;
  49
  50
  51 /**
  52  * Handle to a consume operation
  53  */
  54 struct RECLAIM_TICKETS_ConsumeHandle;
  55
  56
  57 /**
  58  * Ticket revocation request handle
  59  */
  60 struct RECLAIM_TICKETS_RevokeHandle;
  61
  62
  63 /**
  64  * List of tickets
  65  */
  66 struct TicketRecordsEntry
  67 {
  68   /**
  69    * DLL
  70    */
  71   struct TicketRecordsEntry *next;
  72
  73   /**
  74    * DLL
  75    */
  76   struct TicketRecordsEntry *prev;
  77
  78   /**
  79    * Record count
  80    */
  81   unsigned int rd_count;
  82
  83   /**
  84    * Data
  85    */
  86   char *data;
  87
  88   /**
  89    * Data size
  90    */
  91   size_t data_size;
  92
  93   /**
  94    * Label
  95    */
  96   char *label;
  97 };
  98
  99
 100 /**
 101  * Continuation called with ticket.
 102  *
 103  * @param cls closure
 104  * @param ticket the ticket
 105  */
 106 typedef void (*RECLAIM_TICKETS_TicketIter) (
 107   void *cls,
 108   struct GNUNET_RECLAIM_Ticket *ticket);
 109
 110
 111 /**
 112  * Continuation called with ticket.
 113  *
 114  * @param cls closure
 115  * @param ticket the ticket
 116  * @param success #GNUNET_SYSERR on failure (including timeout/queue
 117  * drop/failure to validate) #GNUNET_OK on success
 118  * @param emsg NULL on success, otherwise an error message
 119  */
 120 typedef void (*RECLAIM_TICKETS_TicketResult) (
 121   void *cls,
 122   struct GNUNET_RECLAIM_Ticket *ticket,
 123   int32_t success,
 124   const char *emsg);
 125
 126
 127 /**
 128  * Consume callback.
 129  *
 130  * @param cls closure
 131  * @param identity the issuer of the ticket/attributes
 132  * @param l attribute list retrieved through ticket
 133  * @param success GNUNET_OK on success
 134  * @param emsg error message (NULL on success)
 135  */
 136 typedef void (*RECLAIM_TICKETS_ConsumeCallback) (
 137   void *cls,
 138   const struct GNUNET_CRYPTO_EcdsaPublicKey *identity,
 139   const struct GNUNET_RECLAIM_AttributeList *attributes,
 140   const struct GNUNET_RECLAIM_AttestationList *attestations,
 141   int32_t success,
 142   const char *emsg);
 143
 144
 145 /**
 146  * Revocation callback.
 147  *
 148  * @param cls closure
 149  * @param success GNUNET_OK on success
 150  */
 151 typedef void (*RECLAIM_TICKETS_RevokeCallback) (void *cls, int32_t success);
 152
 153
 154 /**
 155  * Revoke a ticket.
 156  * We start by looking up attribute references in order
 157  * to change attribute IDs.
 158  *
 159  * @param ticket ticket to revoke
 160  * @param identity private key of issuer
 161  * @param cb revocation status callback
 162  * @param cb_cls callback closure
 163  * @return handle to the operation
 164  */
 165 struct RECLAIM_TICKETS_RevokeHandle *
 166 RECLAIM_TICKETS_revoke (const struct GNUNET_RECLAIM_Ticket *ticket,
 167                         const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 168                         RECLAIM_TICKETS_RevokeCallback cb,
 169                         void *cb_cls);
 170
 171
 172 /**
 173  * Cancel a revocation.
 174  *
 175  * @param rh handle to the operation
 176  */
 177 void
 178 RECLAIM_TICKETS_revoke_cancel (struct RECLAIM_TICKETS_RevokeHandle *rh);
 179
 180
 181 /**
 182  * Consume a ticket.
 183  * We first looking attribute references under the label
 184  * ticket.rnd in GNS.
 185  *
 186  * @param id the audience of the ticket
 187  * @param ticket the ticket to consume
 188  * @param cb callback to call with attributes of ticket
 189  * @param cb_cls callback closure
 190  * @return handle to the operation
 191  */
 192 struct RECLAIM_TICKETS_ConsumeHandle *
 193 RECLAIM_TICKETS_consume (const struct GNUNET_CRYPTO_EcdsaPrivateKey *id,
 194                          const struct GNUNET_RECLAIM_Ticket *ticket,
 195                          RECLAIM_TICKETS_ConsumeCallback cb,
 196                          void *cb_cls);
 197
 198
 199 /**
 200  * Cancel a consume operation
 201  *
 202  * @param cth the operation to cancel
 203  */
 204 void
 205 RECLAIM_TICKETS_consume_cancel (struct RECLAIM_TICKETS_ConsumeHandle *cth);
 206
 207
 208 /**
 209  * Issue a new reclaim ticket, thereby authorizing
 210  * the audience to access the set of provided attributes.
 211  *
 212  * @param identity the issuer
 213  * @param attrs the attributes to share
 214  * @param audience the audience to share the attributes with
 215  * @param cb the callback to call with the ticket result
 216  * @param cb_cls the callback closure
 217  * FIXME: Return handle??
 218  */
 219 void
 220 RECLAIM_TICKETS_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 221                        const struct GNUNET_RECLAIM_AttributeList *attrs,
 222                        const struct GNUNET_CRYPTO_EcdsaPublicKey *audience,
 223                        RECLAIM_TICKETS_TicketResult cb,
 224                        void *cb_cls);
 225
 226
 227 /**
 228  * Continue ticket iteration
 229  *
 230  * @param iter the iteration to continue
 231  */
 232 void
 233 RECLAIM_TICKETS_iteration_next (struct RECLAIM_TICKETS_Iterator *iter);
 234
 235
 236 /**
 237  * Stop a running ticket iteration
 238  *
 239  * @param iter iteration to cancel
 240  */
 241 void
 242 RECLAIM_TICKETS_iteration_stop (struct RECLAIM_TICKETS_Iterator *iter);
 243
 244
 245 /**
 246  * Iterate over all tickets issued by an identity
 247  *
 248  * @param identity the issuing identity
 249  * @param cb ticket callback function
 250  * @param cb_cls callback closure
 251  * @return a handle to the iteration
 252  */
 253 struct RECLAIM_TICKETS_Iterator *
 254 RECLAIM_TICKETS_iteration_start (
 255   const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 256   RECLAIM_TICKETS_TicketIter cb,
 257   void *cb_cls);
 258
 259
 260 /**
 261  * Initialize tickets component
 262  *
 263  * @param c the configuration
 264  * @return GNUNET_SYSERR on error
 265  */
 266 int
 267 RECLAIM_TICKETS_init (const struct GNUNET_CONFIGURATION_Handle *c);
 268
 269
 270 /**
 271  * Close handles and clean up.
 272  * FIXME: cancel all pending operations (gns, ns etc)
 273  */
 274 void
 275 RECLAIM_TICKETS_deinit (void);
 276
 277 #endif