src/include/gnunet_identity_provider_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
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Martin Schanzenbach
  23  *
  24  * @file
  25  * Identity provider service; implements identity provider for GNUnet
  26  *
  27  * @defgroup identity-provider  Identity Provider service
  28  * @{
  29  */
  30 #ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H
  31 #define GNUNET_IDENTITY_PROVIDER_SERVICE_H
  32
  33 #ifdef __cplusplus
  34 extern "C"
  35 {
  36 #if 0                           /* keep Emacsens' auto-indent happy */
  37 }
  38 #endif
  39 #endif
  40
  41 #include "gnunet_util_lib.h"
  42
  43
  44 /**
  45  * Version number of GNUnet Identity Provider API.
  46  */
  47 #define GNUNET_IDENTITY_PROVIDER_VERSION 0x00000000
  48
  49 /**
  50  * Handle to access the identity service.
  51  */
  52 struct GNUNET_IDENTITY_PROVIDER_Handle;
  53
  54 /**
  55  * Handle for a token.
  56  */
  57 struct GNUNET_IDENTITY_PROVIDER_Token;
  58
  59 /**
  60  * Handle for a ticket DEPRECATED
  61  */
  62 struct GNUNET_IDENTITY_PROVIDER_Ticket;
  63
  64 /**
  65  * The ticket
  66  */
  67 struct GNUNET_IDENTITY_PROVIDER_Ticket2
  68 {
  69   /**
  70    * The ticket issuer
  71    */
  72   struct GNUNET_CRYPTO_EcdsaPublicKey identity;
  73
  74   /**
  75    * The ticket audience
  76    */
  77   struct GNUNET_CRYPTO_EcdsaPublicKey audience;
  78
  79   /**
  80    * The ticket random (NBO)
  81    */
  82   uint64_t rnd;
  83 };
  84
  85 /**
  86  * Handle for an operation with the identity provider service.
  87  */
  88 struct GNUNET_IDENTITY_PROVIDER_Operation;
  89
  90 /**
  91  * Flags that can be set for an attribute.
  92  */
  93 enum GNUNET_IDENTITY_PROVIDER_AttributeType
  94 {
  95
  96   /**
  97    * No value attribute.
  98    */
  99   GNUNET_IDENTITY_PROVIDER_AT_NULL = 0,
 100
 101   /**
 102    * String attribute.
 103    */
 104   GNUNET_IDENTITY_PROVIDER_AT_STRING = 1,
 105
 106 };
 107
 108
 109
 110 /**
 111  * An attribute.
 112  */
 113 struct GNUNET_IDENTITY_PROVIDER_Attribute
 114 {
 115
 116   /**
 117    * Type of Attribute.
 118    */
 119   uint32_t attribute_type;
 120
 121   /**
 122    * Number of bytes in @e data.
 123    */
 124   size_t data_size;
 125
 126   /**
 127    * The name of the attribute. Note "name" must never be individually
 128    * free'd
 129    */
 130   const char* name;
 131
 132   /**
 133    * Binary value stored as attribute value.  Note: "data" must never
 134    * be individually 'malloc'ed, but instead always points into some
 135    * existing data area.
 136    */
 137   const void *data;
 138
 139 };
 140
 141 struct GNUNET_IDENTITY_PROVIDER_AttributeList
 142 {
 143   /**
 144    * List head
 145    */
 146   struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *list_head;
 147
 148   /**
 149    * List tail
 150    */
 151   struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *list_tail;
 152 };
 153
 154 struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry
 155 {
 156   /**
 157    * DLL
 158    */
 159   struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *prev;
 160
 161   /**
 162    * DLL
 163    */
 164   struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *next;
 165
 166   /**
 167    * The attribute
 168    */
 169   struct GNUNET_IDENTITY_PROVIDER_Attribute *attribute;
 170 };
 171
 172 /**
 173  * Method called when a token has been exchanged for a ticket.
 174  * On success returns a token
 175  *
 176  * @param cls closure
 177  * @param token the token
 178  */
 179 typedef void
 180 (*GNUNET_IDENTITY_PROVIDER_ExchangeCallback)(void *cls,
 181                             const struct GNUNET_IDENTITY_PROVIDER_Token *token,
 182                             uint64_t ticket_nonce);
 183
 184 /** TODO DEPRECATED
 185  * Method called when a token has been issued.
 186  * On success returns a ticket that can be given to the audience to retrive the
 187  * token
 188  *
 189  * @param cls closure
 190  * @param grant the label in GNS pointing to the token
 191  * @param ticket the ticket
 192  * @param token the issued token
 193  * @param name name assigned by the user for this ego,
 194  *                   NULL if the user just deleted the ego and it
 195  *                   must thus no longer be used
 196  */
 197 typedef void
 198 (*GNUNET_IDENTITY_PROVIDER_IssueCallback)(void *cls,
 199                             const char *grant,
 200                             const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 201                             const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 202
 203
 204 /**
 205  * Connect to the identity provider service.
 206  *
 207  * @param cfg Configuration to contact the identity provider service.
 208  * @return handle to communicate with identity provider service
 209  */
 210 struct GNUNET_IDENTITY_PROVIDER_Handle *
 211 GNUNET_IDENTITY_PROVIDER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 212
 213 /**
 214  * Continuation called to notify client about result of the
 215  * operation.
 216  *
 217  * @param cls closure
 218  * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
 219  *                #GNUNET_NO if content was already there or not found
 220  *                #GNUNET_YES (or other positive value) on success
 221  * @param emsg NULL on success, otherwise an error message
 222  */
 223 typedef void
 224 (*GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus) (void *cls,
 225                                             int32_t success,
 226                                             const char *emsg);
 227
 228
 229 /**
 230  * Store an attribute.  If the attribute is already present,
 231  * it is replaced with the new attribute.
 232  *
 233  * @param h handle to the identity provider
 234  * @param pkey private key of the identity
 235  * @param attr the attribute
 236  * @param cont continuation to call when done
 237  * @param cont_cls closure for @a cont
 238  * @return handle to abort the request
 239  */
 240 struct GNUNET_IDENTITY_PROVIDER_Operation *
 241 GNUNET_IDENTITY_PROVIDER_attribute_store (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
 242                                           const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
 243                                           const struct GNUNET_IDENTITY_PROVIDER_Attribute *attr,
 244                                           GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cont,
 245                                           void *cont_cls);
 246
 247
 248 /**
 249  * Create a new attribute.
 250  *
 251  * @param name the attribute name
 252  * @param type the attribute type
 253  * @param data the attribute value
 254  * @param data_size the attribute value size
 255  * @return the new attribute
 256  */
 257 struct GNUNET_IDENTITY_PROVIDER_Attribute *
 258 GNUNET_IDENTITY_PROVIDER_attribute_new (const char* attr_name,
 259                                         uint32_t attr_type,
 260                                         const void* data,
 261                                         size_t data_size);
 262
 263 /**
 264  * Process an attribute that was stored in the idp.
 265  *
 266  * @param cls closure
 267  * @param attr the attribute
 268  */
 269 typedef void
 270 (*GNUNET_IDENTITY_PROVIDER_AttributeResult) (void *cls,
 271                                    const struct GNUNET_CRYPTO_EcdsaPublicKey *identity,
 272                                    const struct GNUNET_IDENTITY_PROVIDER_Attribute *attr);
 273
 274
 275
 276 /**
 277  * List all attributes for a local identity.
 278  * This MUST lock the `struct GNUNET_IDENTITY_PROVIDER_Handle`
 279  * for any other calls than #GNUNET_IDENTITY_PROVIDER_get_attributes_next() and
 280  * #GNUNET_IDENTITY_PROVIDER_get_attributes_stop. @a proc will be called once
 281  * immediately, and then again after
 282  * #GNUNET_IDENTITY_PROVIDER_get_attributes_next() is invoked.
 283  *
 284  * On error (disconnect), @a error_cb will be invoked.
 285  * On normal completion, @a finish_cb proc will be
 286  * invoked.
 287  *
 288  * @param h handle to the idp
 289  * @param identity identity to access
 290  * @param error_cb function to call on error (i.e. disconnect),
 291  *        the handle is afterwards invalid
 292  * @param error_cb_cls closure for @a error_cb
 293  * @param proc function to call on each attribute; it
 294  *        will be called repeatedly with a value (if available)
 295  * @param proc_cls closure for @a proc
 296  * @param finish_cb function to call on completion
 297  *        the handle is afterwards invalid
 298  * @param finish_cb_cls closure for @a finish_cb
 299  * @return an iterator handle to use for iteration
 300  */
 301 struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *
 302 GNUNET_IDENTITY_PROVIDER_get_attributes_start (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
 303                                                const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 304                                                GNUNET_SCHEDULER_TaskCallback error_cb,
 305                                                void *error_cb_cls,
 306                                                GNUNET_IDENTITY_PROVIDER_AttributeResult proc,
 307                                                void *proc_cls,
 308                                                GNUNET_SCHEDULER_TaskCallback finish_cb,
 309                                                void *finish_cb_cls);
 310
 311
 312 /**
 313  * Calls the record processor specified in #GNUNET_IDENTITY_PROVIDER_get_attributes_start
 314  * for the next record.
 315  *
 316  * @param it the iterator
 317  */
 318 void
 319 GNUNET_IDENTITY_PROVIDER_get_attributes_next (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
 320
 321
 322 /**
 323  * Stops iteration and releases the idp handle for further calls.  Must
 324  * be called on any iteration that has not yet completed prior to calling
 325  * #GNUNET_IDENTITY_PROVIDER_disconnect.
 326  *
 327  * @param it the iterator
 328  */
 329 void
 330 GNUNET_IDENTITY_PROVIDER_get_attributes_stop (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
 331
 332
 333 /**
 334  * Method called when a token has been issued.
 335  * On success returns a ticket that can be given to the audience to retrive the
 336  * token
 337  *
 338  * @param cls closure
 339  * @param ticket the ticket
 340  */
 341 typedef void
 342 (*GNUNET_IDENTITY_PROVIDER_TicketCallback)(void *cls,
 343                             const struct GNUNET_IDENTITY_PROVIDER_Ticket2 *ticket);
 344
 345 /**
 346  * Issues a ticket to another identity. The identity may use
 347  * @GNUNET_IDENTITY_PROVIDER_authorization_ticket_consume to consume the ticket
 348  * and retrieve the attributes specified in the AttributeList.
 349  *
 350  * @param id the identity provider to use
 351  * @param iss the issuing identity
 352  * @param rp the subject of the ticket (the relying party)
 353  * @param attr the attributes that the relying party is given access to
 354  * @param cb the callback
 355  * @param cb_cls the callback closure
 356  * @return handle to abort the operation
 357  */
 358 struct GNUNET_IDENTITY_PROVIDER_Operation *
 359 GNUNET_IDENTITY_PROVIDER_idp_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 360                                            const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss,
 361                                            const struct GNUNET_CRYPTO_EcdsaPublicKey *rp,
 362                                            const struct GNUNET_IDENTITY_PROVIDER_AttributeList *attrs,
 363                                            GNUNET_IDENTITY_PROVIDER_TicketCallback cb,
 364                                            void *cb_cls);
 365
 366 /** TODO
 367  * Revoked an issued ticket. The relying party will be unable to retrieve
 368  * updated attributes.
 369  *
 370  * @param id the identity provider to use
 371  * @param identity the issuing identity
 372  * @param ticket the ticket to revoke
 373  * @param cb the callback
 374  * @param cb_cls the callback closure
 375  * @return handle to abort the operation
 376  */
 377 struct GNUNET_IDENTITY_PROVIDER_Operation *
 378 GNUNET_IDENTITY_PROVIDER_idp_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 379                                             const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 380                                             const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 381                                             GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cb,
 382                                             void *cb_cls);
 383
 384
 385
 386 /**
 387  * Consumes an issued ticket. The ticket is persisted
 388  * and used to retrieve identity information from the issuer
 389  *
 390  * @param id the identity provider to use
 391  * @param identity the identity that is the subject of the issued ticket (the relying party)
 392  * @param ticket the issued ticket to consume
 393  * @param cb the callback to call
 394  * @param cb_cls the callback closure
 395  * @return handle to abort the operation
 396  */
 397 struct GNUNET_IDENTITY_PROVIDER_Operation *
 398 GNUNET_IDENTITY_PROVIDER_rp_ticket_consume (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 399                                             const struct GNUNET_CRYPTO_EcdsaPrivateKey * identity,
 400                                             const struct GNUNET_IDENTITY_PROVIDER_Ticket2 *ticket,
 401                                             GNUNET_IDENTITY_PROVIDER_AttributeResult cb,
 402                                             void *cb_cls);
 403
 404 /**
 405  * Lists all tickets that have been issued to remote
 406  * identites (relying parties)
 407  *
 408  * @param h the identity provider to use
 409  * @param identity the issuing identity
 410  * @param error_cb function to call on error (i.e. disconnect),
 411  *        the handle is afterwards invalid
 412  * @param error_cb_cls closure for @a error_cb
 413  * @param proc function to call on each ticket; it
 414  *        will be called repeatedly with a value (if available)
 415  * @param proc_cls closure for @a proc
 416  * @param finish_cb function to call on completion
 417  *        the handle is afterwards invalid
 418  * @param finish_cb_cls closure for @a finish_cb
 419  * @return an iterator handle to use for iteration
 420  */
 421 struct GNUNET_IDENTITY_PROVIDER_TicketIterator *
 422 GNUNET_IDENTITY_PROVIDER_idp_ticket_iteration_start (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
 423                                                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 424                                                      GNUNET_SCHEDULER_TaskCallback error_cb,
 425                                                      void *error_cb_cls,
 426                                                      GNUNET_IDENTITY_PROVIDER_TicketCallback proc,
 427                                                      void *proc_cls,
 428                                                      GNUNET_SCHEDULER_TaskCallback finish_cb,
 429                                                      void *finish_cb_cls);
 430
 431 /**
 432  * Lists all tickets that have been issued to remote
 433  * identites (relying parties)
 434  *
 435  * @param id the identity provider to use
 436  * @param identity the issuing identity
 437  * @param error_cb function to call on error (i.e. disconnect),
 438  *        the handle is afterwards invalid
 439  * @param error_cb_cls closure for @a error_cb
 440  * @param proc function to call on each ticket; it
 441  *        will be called repeatedly with a value (if available)
 442  * @param proc_cls closure for @a proc
 443  * @param finish_cb function to call on completion
 444  *        the handle is afterwards invalid
 445  * @param finish_cb_cls closure for @a finish_cb
 446  * @return an iterator handle to use for iteration
 447  */
 448 struct GNUNET_IDENTITY_PROVIDER_TicketIterator *
 449 GNUNET_IDENTITY_PROVIDER_ticket_iteration_start_rp (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
 450                                                     const struct GNUNET_CRYPTO_EcdsaPublicKey *identity,
 451                                                     GNUNET_SCHEDULER_TaskCallback error_cb,
 452                                                     void *error_cb_cls,
 453                                                     GNUNET_IDENTITY_PROVIDER_TicketCallback proc,
 454                                                     void *proc_cls,
 455                                                     GNUNET_SCHEDULER_TaskCallback finish_cb,
 456                                                     void *finish_cb_cls);
 457
 458 /**
 459  * Calls the record processor specified in #GNUNET_IDENTITY_PROVIDER_ticket_iteration_start
 460  * for the next record.
 461  *
 462  * @param it the iterator
 463  */
 464 void
 465 GNUNET_IDENTITY_PROVIDER_ticket_iteration_next (struct GNUNET_IDENTITY_PROVIDER_TicketIterator *it);
 466
 467 /**
 468  * Stops iteration and releases the idp handle for further calls.  Must
 469  * be called on any iteration that has not yet completed prior to calling
 470  * #GNUNET_IDENTITY_PROVIDER_disconnect.
 471  *
 472  * @param it the iterator
 473  */
 474 void
 475 GNUNET_IDENTITY_PROVIDER_ticket_iteration_stop (struct GNUNET_IDENTITY_PROVIDER_TicketIterator *it);
 476
 477 /** TODO remove DEPRECATED
 478  * Issue a token for a specific audience.
 479  *
 480  * @param id identity provider service to use
 481  * @param iss issuer (identity)
 482  * @param aud audience (identity)
 483  * @param scope the identity attributes requested, comman separated
 484  * @param expiration the token expiration
 485  * @param nonce the nonce that will be included in token and ticket
 486  * @param cb callback to call with result
 487  * @param cb_cls closure
 488  * @return handle to abort the operation
 489  */
 490 struct GNUNET_IDENTITY_PROVIDER_Operation *
 491 GNUNET_IDENTITY_PROVIDER_issue_token (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 492                                       const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss_key,
 493                                       const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
 494                                       const char* scope,
 495                                       const char* vattr,
 496                                       struct GNUNET_TIME_Absolute expiration,
 497                                       uint64_t nonce,
 498                                       GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
 499                                       void *cb_cls);
 500
 501
 502 /** TODO remove DEPRECATED
 503  * Exchange a ticket for a token. Intended to be used by audience that
 504  * received a ticket.
 505  *
 506  * @param id identity provider service to use
 507  * @param ticket the ticket to exchange
 508  * @param aud_privkey the audience of the ticket
 509  * @param cont function to call once the operation finished
 510  * @param cont_cls closure for @a cont
 511  * @return handle to abort the operation
 512  */
 513 struct GNUNET_IDENTITY_PROVIDER_Operation *
 514 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 515                                           const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 516                                           const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
 517                                           GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
 518                                           void *cont_cls);
 519
 520
 521 /**
 522  * Disconnect from identity provider service.
 523  *
 524  * @param h identity provider service to disconnect
 525  */
 526 void
 527 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
 528
 529
 530 /**
 531  * Cancel an identity provider operation.  Note that the operation MAY still
 532  * be executed; this merely cancels the continuation; if the request
 533  * was already transmitted, the service may still choose to complete
 534  * the operation.
 535  *
 536  * @param op operation to cancel
 537  */
 538 void
 539 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
 540
 541
 542 /**
 543  * Convenience API
 544  */
 545
 546 /**
 547  * Destroy token
 548  *
 549  * @param token the token
 550  */
 551 void
 552 GNUNET_IDENTITY_PROVIDER_token_destroy(struct GNUNET_IDENTITY_PROVIDER_Token *token);
 553
 554 /**
 555  * Returns string representation of token. A JSON-Web-Token.
 556  *
 557  * @param token the token
 558  * @return The JWT (must be freed)
 559  */
 560 char *
 561 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 562
 563 /**
 564  * Returns string representation of ticket. Base64-Encoded
 565  *
 566  * @param ticket the ticket
 567  * @return the Base64-Encoded ticket
 568  */
 569 char *
 570 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 571
 572 /**
 573  * Created a ticket from a string (Base64 encoded ticket)
 574  *
 575  * @param input Base64 encoded ticket
 576  * @param ticket pointer where the ticket is stored
 577  * @return GNUNET_OK
 578  */
 579 int
 580 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
 581                                            struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
 582
 583 /**
 584  * Destroys a ticket
 585  *
 586  * @param ticket the ticket to destroy
 587  */
 588 void
 589 GNUNET_IDENTITY_PROVIDER_ticket_destroy(struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 590
 591 #if 0                           /* keep Emacsens' auto-indent happy */
 592 {
 593 #endif
 594 #ifdef __cplusplus
 595 }
 596 #endif
 597
 598
 599 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
 600 #endif
 601
 602 /** @} */ /* end of group identity */
 603
 604 /* end of gnunet_identity_provider_service.h */