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