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 grant the label in GNS pointing to the token
 340  * @param ticket the ticket
 341  * @param token the issued token
 342  * @param name name assigned by the user for this ego,
 343  *                   NULL if the user just deleted the ego and it
 344  *                   must thus no longer be used
 345  */
 346 typedef void
 347 (*GNUNET_IDENTITY_PROVIDER_TicketCallback)(void *cls,
 348                             const struct GNUNET_IDENTITY_PROVIDER_Ticket2 *ticket);
 349
 350
 351 /**
 352  * Issues a ticket to another identity. The identity may use
 353  * @GNUNET_IDENTITY_PROVIDER_authorization_ticket_consume to consume the ticket
 354  * and retrieve the attributes specified in the AttributeList.
 355  *
 356  * @param id the identity provider to use
 357  * @param iss the issuing identity
 358  * @param rp the subject of the ticket (the relying party)
 359  * @param attr the attributes that the relying party is given access to
 360  * @param cb the callback
 361  * @param cb_cls the callback closure
 362  * @return handle to abort the operation
 363  */
 364 struct GNUNET_IDENTITY_PROVIDER_Operation *
 365 GNUNET_IDENTITY_PROVIDER_idp_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 366                                            const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss,
 367                                            const struct GNUNET_CRYPTO_EcdsaPublicKey *rp,
 368                                            const struct GNUNET_IDENTITY_PROVIDER_AttributeList *attrs,
 369                                            GNUNET_IDENTITY_PROVIDER_TicketCallback cb,
 370                                            void *cb_cls);
 371
 372 /** TODO
 373  * Revoked an issued ticket. The relying party will be unable to retrieve
 374  * updated attributes.
 375  *
 376  * @param id the identity provider to use
 377  * @param identity the issuing identity
 378  * @param ticket the ticket to revoke
 379  * @param cb the callback
 380  * @param cb_cls the callback closure
 381  * @return handle to abort the operation
 382  */
 383 struct GNUNET_IDENTITY_PROVIDER_Operation *
 384 GNUNET_IDENTITY_PROVIDER_idp_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 385                                             const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 386                                             const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 387                                             GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cb,
 388                                             void *cb_cls);
 389
 390
 391
 392 /** TODO
 393  * Consumes an issued ticket. The ticket is persisted
 394  * and used to retrieve identity information from the issuer
 395  *
 396  * @param id the identity provider to use
 397  * @param identity the identity that is the subject of the issued ticket (the relying party)
 398  * @param ticket the issued ticket to consume
 399  * @param cb the callback to call
 400  * @param cb_cls the callback closure
 401  * @return handle to abort the operation
 402  */
 403 struct GNUNET_IDENTITY_PROVIDER_Operation *
 404 GNUNET_IDENTITY_PROVIDER_rp_ticket_consume (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 405                                             const struct GNUNET_CRYPTO_EcdsaPrivateKey * identity,
 406                                             const struct GNUNET_IDENTITY_PROVIDER_Ticket2 *ticket,
 407                                             GNUNET_IDENTITY_PROVIDER_AttributeResult cb,
 408                                             void *cb_cls);
 409
 410 /** TODO
 411  * Lists all tickets that have been issued to remote
 412  * identites (relying parties)
 413  *
 414  * @param id the identity provider to use
 415  * @param identity the issuing identity
 416  * @param cb the callback to use
 417  * @param cb_cls the callback closure
 418  * @return handle to abort the operation
 419  */
 420 struct GNUNET_IDENTITY_PROVIDER_Operation *
 421 GNUNET_IDENTITY_PROVIDER_idp_tickets_list (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 422                                            const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 423                                            GNUNET_IDENTITY_PROVIDER_TicketCallback *cb,
 424                                            void *cb_cls);
 425
 426 /** TODO
 427  * Lists all attributes that are shared with this identity
 428  * by remote parties
 429  *
 430  * @param id identity provider service to use
 431  * @param identity the identity (relying party)
 432  * @param cb the result callback
 433  * @param cb_cls the result callback closure
 434  * @return handle to abort the operation
 435  */
 436 struct GNUNET_IDENTITY_PROVIDER_Operation *
 437 GNUNET_IDENTITY_PROVIDER_rp_attributes_list (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 438                                              const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 439                                              GNUNET_IDENTITY_PROVIDER_AttributeResult *cb,
 440                                              void *cb_cls);
 441
 442 /** TODO remove DEPRECATED
 443  * Issue a token for a specific audience.
 444  *
 445  * @param id identity provider service to use
 446  * @param iss issuer (identity)
 447  * @param aud audience (identity)
 448  * @param scope the identity attributes requested, comman separated
 449  * @param expiration the token expiration
 450  * @param nonce the nonce that will be included in token and ticket
 451  * @param cb callback to call with result
 452  * @param cb_cls closure
 453  * @return handle to abort the operation
 454  */
 455 struct GNUNET_IDENTITY_PROVIDER_Operation *
 456 GNUNET_IDENTITY_PROVIDER_issue_token (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 457                                       const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss_key,
 458                                       const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
 459                                       const char* scope,
 460                                       const char* vattr,
 461                                       struct GNUNET_TIME_Absolute expiration,
 462                                       uint64_t nonce,
 463                                       GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
 464                                       void *cb_cls);
 465
 466
 467 /** TODO remove DEPRECATED
 468  * Exchange a ticket for a token. Intended to be used by audience that
 469  * received a ticket.
 470  *
 471  * @param id identity provider service to use
 472  * @param ticket the ticket to exchange
 473  * @param aud_privkey the audience of the ticket
 474  * @param cont function to call once the operation finished
 475  * @param cont_cls closure for @a cont
 476  * @return handle to abort the operation
 477  */
 478 struct GNUNET_IDENTITY_PROVIDER_Operation *
 479 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 480                                           const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 481                                           const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
 482                                           GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
 483                                           void *cont_cls);
 484
 485
 486 /**
 487  * Disconnect from identity provider service.
 488  *
 489  * @param h identity provider service to disconnect
 490  */
 491 void
 492 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
 493
 494
 495 /**
 496  * Cancel an identity provider operation.  Note that the operation MAY still
 497  * be executed; this merely cancels the continuation; if the request
 498  * was already transmitted, the service may still choose to complete
 499  * the operation.
 500  *
 501  * @param op operation to cancel
 502  */
 503 void
 504 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
 505
 506
 507 /**
 508  * Convenience API
 509  */
 510
 511 /**
 512  * Destroy token
 513  *
 514  * @param token the token
 515  */
 516 void
 517 GNUNET_IDENTITY_PROVIDER_token_destroy(struct GNUNET_IDENTITY_PROVIDER_Token *token);
 518
 519 /**
 520  * Returns string representation of token. A JSON-Web-Token.
 521  *
 522  * @param token the token
 523  * @return The JWT (must be freed)
 524  */
 525 char *
 526 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 527
 528 /**
 529  * Returns string representation of ticket. Base64-Encoded
 530  *
 531  * @param ticket the ticket
 532  * @return the Base64-Encoded ticket
 533  */
 534 char *
 535 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 536
 537 /**
 538  * Created a ticket from a string (Base64 encoded ticket)
 539  *
 540  * @param input Base64 encoded ticket
 541  * @param ticket pointer where the ticket is stored
 542  * @return GNUNET_OK
 543  */
 544 int
 545 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
 546                                            struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
 547
 548 /**
 549  * Destroys a ticket
 550  *
 551  * @param ticket the ticket to destroy
 552  */
 553 void
 554 GNUNET_IDENTITY_PROVIDER_ticket_destroy(struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 555
 556 #if 0                           /* keep Emacsens' auto-indent happy */
 557 {
 558 #endif
 559 #ifdef __cplusplus
 560 }
 561 #endif
 562
 563
 564 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
 565 #endif
 566
 567 /** @} */ /* end of group identity */
 568
 569 /* end of gnunet_identity_provider_service.h */