src/include/gnunet_reclaim_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2016 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  *
  24  * @file
  25  * Identity provider service; implements identity provider for GNUnet
  26  *
  27  * @defgroup reclaim  Identity Provider service
  28  * @{
  29  */
  30 #ifndef GNUNET_RECLAIM_SERVICE_H
  31 #define GNUNET_RECLAIM_SERVICE_H
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #if 0 /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "gnunet_reclaim_attribute_lib.h"
  41 #include "gnunet_util_lib.h"
  42
  43 /**
  44  * Version number of the re:claimID API.
  45  */
  46 #define GNUNET_RECLAIM_VERSION 0x00000000
  47
  48 /**
  49  * Opaque handle to access the service.
  50  */
  51 struct GNUNET_RECLAIM_Handle;
  52
  53
  54 /**
  55  * Opaque handle for an operation at the re:claimID service.
  56  */
  57 struct GNUNET_RECLAIM_Operation;
  58
  59
  60 /**
  61  * The an authorization ticket. This ticket is meant to be transferred
  62  * out of band the a relying party.
  63  * The contents of a ticket must be protected and should be treated as a
  64  * SHARED SECRET between user and relying party.
  65  */
  66 struct GNUNET_RECLAIM_Ticket
  67 {
  68   /**
  69    * The ticket issuer (= the user)
  70    */
  71   struct GNUNET_CRYPTO_EcdsaPublicKey identity;
  72
  73   /**
  74    * The ticket audience (= relying party)
  75    */
  76   struct GNUNET_CRYPTO_EcdsaPublicKey audience;
  77
  78   /**
  79    * The ticket random (NBO)
  80    */
  81   uint64_t rnd;
  82 };
  83
  84
  85 /**
  86  * Method called when a token has been issued.
  87  * On success returns a ticket that can be given to the relying party to retrive
  88  * the token
  89  *
  90  * @param cls closure
  91  * @param ticket the ticket
  92  */
  93 typedef void (*GNUNET_RECLAIM_TicketCallback) (
  94     void *cls, const struct GNUNET_RECLAIM_Ticket *ticket);
  95
  96
  97 /**
  98  * Continuation called to notify client about result of the
  99  * operation.
 100  *
 101  * @param cls The callback closure
 102  * @param success #GNUNET_SYSERR on failure
 103  * @param emsg NULL on success, otherwise an error message
 104  */
 105 typedef void (*GNUNET_RECLAIM_ContinuationWithStatus) (void *cls,
 106                                                        int32_t success,
 107                                                        const char *emsg);
 108
 109
 110 /**
 111  * Callback used to notify the client of attribute results.
 112  *
 113  * @param cls The callback closure
 114  * @param identity The identity authoritative over the attributes
 115  * @param attr The attribute
 116  */
 117 typedef void (*GNUNET_RECLAIM_AttributeResult) (
 118     void *cls, const struct GNUNET_CRYPTO_EcdsaPublicKey *identity,
 119     const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr);
 120
 121
 122 /**
 123  * Connect to the re:claimID service.
 124  *
 125  * @param cfg Configuration to contact the re:claimID service.
 126  * @return handle to communicate with the service
 127  */
 128 struct GNUNET_RECLAIM_Handle *
 129 GNUNET_RECLAIM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 130
 131
 132 /**
 133  * Store an attribute.  If the attribute is already present,
 134  * it is replaced with the new attribute.
 135  *
 136  * @param h handle to the re:claimID service
 137  * @param pkey Private key of the identity to add an attribute to
 138  * @param attr The attribute
 139  * @param exp_interval The relative expiration interval for the attribute
 140  * @param cont Continuation to call when done
 141  * @param cont_cls Closure for @a cont
 142  * @return handle Used to to abort the request
 143  */
 144 struct GNUNET_RECLAIM_Operation *
 145 GNUNET_RECLAIM_attribute_store (
 146     struct GNUNET_RECLAIM_Handle *h,
 147     const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
 148     const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr,
 149     const struct GNUNET_TIME_Relative *exp_interval,
 150     GNUNET_RECLAIM_ContinuationWithStatus cont, void *cont_cls);
 151
 152
 153 /**
 154  * Delete an attribute. Tickets used to share this attribute are updated
 155  * accordingly.
 156  *
 157  * @param h handle to the re:claimID service
 158  * @param pkey Private key of the identity to add an attribute to
 159  * @param attr The attribute
 160  * @param cont Continuation to call when done
 161  * @param cont_cls Closure for @a cont
 162  * @return handle Used to to abort the request
 163  */
 164 struct GNUNET_RECLAIM_Operation *
 165 GNUNET_RECLAIM_attribute_delete (
 166     struct GNUNET_RECLAIM_Handle *h,
 167     const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
 168     const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr,
 169     GNUNET_RECLAIM_ContinuationWithStatus cont, void *cont_cls);
 170
 171
 172 /**
 173  * List all attributes for a local identity.
 174  * This MUST lock the `struct GNUNET_RECLAIM_Handle`
 175  * for any other calls than #GNUNET_RECLAIM_get_attributes_next() and
 176  * #GNUNET_RECLAIM_get_attributes_stop. @a proc will be called once
 177  * immediately, and then again after
 178  * #GNUNET_RECLAIM_get_attributes_next() is invoked.
 179  *
 180  * On error (disconnect), @a error_cb will be invoked.
 181  * On normal completion, @a finish_cb proc will be
 182  * invoked.
 183  *
 184  * @param h Handle to the re:claimID service
 185  * @param identity Identity to iterate over
 186  * @param error_cb Function to call on error (i.e. disconnect),
 187  *        the handle is afterwards invalid
 188  * @param error_cb_cls Closure for @a error_cb
 189  * @param proc Function to call on each attribute
 190  * @param proc_cls Closure for @a proc
 191  * @param finish_cb Function to call on completion
 192  *        the handle is afterwards invalid
 193  * @param finish_cb_cls Closure for @a finish_cb
 194  * @return an iterator Handle to use for iteration
 195  */
 196 struct GNUNET_RECLAIM_AttributeIterator *
 197 GNUNET_RECLAIM_get_attributes_start (
 198     struct GNUNET_RECLAIM_Handle *h,
 199     const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 200     GNUNET_SCHEDULER_TaskCallback error_cb, void *error_cb_cls,
 201     GNUNET_RECLAIM_AttributeResult proc, void *proc_cls,
 202     GNUNET_SCHEDULER_TaskCallback finish_cb, void *finish_cb_cls);
 203
 204
 205 /**
 206  * Calls the record processor specified in #GNUNET_RECLAIM_get_attributes_start
 207  * for the next record.
 208  *
 209  * @param it The iterator
 210  */
 211 void
 212 GNUNET_RECLAIM_get_attributes_next (
 213     struct GNUNET_RECLAIM_AttributeIterator *it);
 214
 215
 216 /**
 217  * Stops iteration and releases the handle for further calls. Must
 218  * be called on any iteration that has not yet completed prior to calling
 219  * #GNUNET_RECLAIM_disconnect.
 220  *
 221  * @param it the iterator
 222  */
 223 void
 224 GNUNET_RECLAIM_get_attributes_stop (
 225     struct GNUNET_RECLAIM_AttributeIterator *it);
 226
 227
 228 /**
 229  * Issues a ticket to a relying party. The identity may use
 230  * GNUNET_RECLAIM_ticket_consume to consume the ticket
 231  * and retrieve the attributes specified in the attribute list.
 232  *
 233  * @param h the identity provider to use
 234  * @param iss the issuing identity (= the user)
 235  * @param rp the subject of the ticket (= the relying party)
 236  * @param attrs the attributes that the relying party is given access to
 237  * @param cb the callback
 238  * @param cb_cls the callback closure
 239  * @return handle to abort the operation
 240  */
 241 struct GNUNET_RECLAIM_Operation *
 242 GNUNET_RECLAIM_ticket_issue (
 243     struct GNUNET_RECLAIM_Handle *h,
 244     const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss,
 245     const struct GNUNET_CRYPTO_EcdsaPublicKey *rp,
 246     const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs,
 247     GNUNET_RECLAIM_TicketCallback cb, void *cb_cls);
 248
 249 /**
 250  * Revoked an issued ticket. The relying party will be unable to retrieve
 251  * attributes. Other issued tickets remain unaffected.
 252  * This includes tickets issued to other relying parties as well as to
 253  * other tickets issued to the audience specified in this ticket.
 254  *
 255  * @param h the identity provider to use
 256  * @param identity the issuing identity
 257  * @param ticket the ticket to revoke
 258  * @param cb the callback
 259  * @param cb_cls the callback closure
 260  * @return handle to abort the operation
 261  */
 262 struct GNUNET_RECLAIM_Operation *
 263 GNUNET_RECLAIM_ticket_revoke (
 264     struct GNUNET_RECLAIM_Handle *h,
 265     const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 266     const struct GNUNET_RECLAIM_Ticket *ticket,
 267     GNUNET_RECLAIM_ContinuationWithStatus cb, void *cb_cls);
 268
 269
 270 /**
 271  * Consumes an issued ticket. The ticket is used to retrieve identity
 272  * information from the issuer
 273  *
 274  * @param h the identity provider to use
 275  * @param identity the identity that is the subject of the issued ticket (the
 276  * relying party)
 277  * @param ticket the issued ticket to consume
 278  * @param cb the callback to call
 279  * @param cb_cls the callback closure
 280  * @return handle to abort the operation
 281  */
 282 struct GNUNET_RECLAIM_Operation *
 283 GNUNET_RECLAIM_ticket_consume (
 284     struct GNUNET_RECLAIM_Handle *h,
 285     const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 286     const struct GNUNET_RECLAIM_Ticket *ticket,
 287     GNUNET_RECLAIM_AttributeResult cb, void *cb_cls);
 288
 289 /**
 290  * Lists all tickets that have been issued to remote
 291  * identites (relying parties)
 292  *
 293  * @param h the identity provider to use
 294  * @param identity the issuing identity
 295  * @param error_cb function to call on error (i.e. disconnect),
 296  *        the handle is afterwards invalid
 297  * @param error_cb_cls closure for @a error_cb
 298  * @param proc function to call on each ticket; it
 299  *        will be called repeatedly with a value (if available)
 300  * @param proc_cls closure for @a proc
 301  * @param finish_cb function to call on completion
 302  *        the handle is afterwards invalid
 303  * @param finish_cb_cls closure for @a finish_cb
 304  * @return an iterator handle to use for iteration
 305  */
 306 struct GNUNET_RECLAIM_TicketIterator *
 307 GNUNET_RECLAIM_ticket_iteration_start (
 308     struct GNUNET_RECLAIM_Handle *h,
 309     const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 310     GNUNET_SCHEDULER_TaskCallback error_cb, void *error_cb_cls,
 311     GNUNET_RECLAIM_TicketCallback proc, void *proc_cls,
 312     GNUNET_SCHEDULER_TaskCallback finish_cb, void *finish_cb_cls);
 313
 314
 315 /**
 316  * Calls the ticket processor specified in
 317  * #GNUNET_RECLAIM_ticket_iteration_start for the next record.
 318  *
 319  * @param it the iterator
 320  */
 321 void
 322 GNUNET_RECLAIM_ticket_iteration_next (struct GNUNET_RECLAIM_TicketIterator *it);
 323
 324 /**
 325  * Stops iteration and releases the handle for further calls.  Must
 326  * be called on any iteration that has not yet completed prior to calling
 327  * #GNUNET_RECLAIM_disconnect.
 328  *
 329  * @param it the iterator
 330  */
 331 void
 332 GNUNET_RECLAIM_ticket_iteration_stop (struct GNUNET_RECLAIM_TicketIterator *it);
 333
 334 /**
 335  * Disconnect from identity provider service.
 336  *
 337  * @param h identity provider service to disconnect
 338  */
 339 void
 340 GNUNET_RECLAIM_disconnect (struct GNUNET_RECLAIM_Handle *h);
 341
 342
 343 /**
 344  * Cancel an identity provider operation.  Note that the operation MAY still
 345  * be executed; this merely cancels the continuation; if the request
 346  * was already transmitted, the service may still choose to complete
 347  * the operation.
 348  *
 349  * @param op operation to cancel
 350  */
 351 void
 352 GNUNET_RECLAIM_cancel (struct GNUNET_RECLAIM_Operation *op);
 353
 354 #if 0 /* keep Emacsens' auto-indent happy */
 355 {
 356 #endif
 357 #ifdef __cplusplus
 358 }
 359 #endif
 360
 361
 362 /* ifndef GNUNET_RECLAIM_SERVICE_H */
 363 #endif
 364
 365 /** @} */ /* end of group identity */
 366
 367 /* end of gnunet_reclaim_service.h */