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
  61  */
  62 struct GNUNET_IDENTITY_PROVIDER_Ticket;
  63
  64 /**
  65  * Handle for an operation with the identity provider service.
  66  */
  67 struct GNUNET_IDENTITY_PROVIDER_Operation;
  68
  69 /**
  70  * Flags that can be set for an attribute.
  71  */
  72 enum GNUNET_IDENTITY_PROVIDER_AttributeType
  73 {
  74
  75   /**
  76    * No value attribute.
  77    */
  78   GNUNET_IDENTITY_PROVIDER_AT_NULL = 0,
  79
  80   /**
  81    * String attribute.
  82    */
  83   GNUNET_IDENTITY_PROVIDER_AT_STRING = 1,
  84
  85 };
  86
  87
  88
  89 /**
  90  * An attribute.
  91  */
  92 struct GNUNET_IDENTITY_PROVIDER_Attribute
  93 {
  94
  95   /**
  96    * Type of Attribute.
  97    */
  98   uint32_t attribute_type;
  99
 100   /**
 101    * Number of bytes in @e data.
 102    */
 103   size_t data_size;
 104
 105   /**
 106    * The name of the attribute. Note "name" must never be individually
 107    * free'd
 108    */
 109   const char* name;
 110
 111   /**
 112    * Binary value stored as attribute value.  Note: "data" must never
 113    * be individually 'malloc'ed, but instead always points into some
 114    * existing data area.
 115    */
 116   const void *data;
 117
 118 };
 119
 120
 121
 122 /**
 123  * Method called when a token has been exchanged for a ticket.
 124  * On success returns a token
 125  *
 126  * @param cls closure
 127  * @param token the token
 128  */
 129 typedef void
 130 (*GNUNET_IDENTITY_PROVIDER_ExchangeCallback)(void *cls,
 131                             const struct GNUNET_IDENTITY_PROVIDER_Token *token,
 132                             uint64_t ticket_nonce);
 133
 134 /**
 135  * Method called when a token has been issued.
 136  * On success returns a ticket that can be given to the audience to retrive the
 137  * token
 138  *
 139  * @param cls closure
 140  * @param grant the label in GNS pointing to the token
 141  * @param ticket the ticket
 142  * @param token the issued token
 143  * @param name name assigned by the user for this ego,
 144  *                   NULL if the user just deleted the ego and it
 145  *                   must thus no longer be used
 146  */
 147 typedef void
 148 (*GNUNET_IDENTITY_PROVIDER_IssueCallback)(void *cls,
 149                             const char *grant,
 150                             const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 151                             const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 152
 153
 154 /**
 155  * Connect to the identity provider service.
 156  *
 157  * @param cfg Configuration to contact the identity provider service.
 158  * @return handle to communicate with identity provider service
 159  */
 160 struct GNUNET_IDENTITY_PROVIDER_Handle *
 161 GNUNET_IDENTITY_PROVIDER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 162
 163 /**
 164  * Continuation called to notify client about result of the
 165  * operation.
 166  *
 167  * @param cls closure
 168  * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
 169  *                #GNUNET_NO if content was already there or not found
 170  *                #GNUNET_YES (or other positive value) on success
 171  * @param emsg NULL on success, otherwise an error message
 172  */
 173 typedef void
 174 (*GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus) (void *cls,
 175                                             int32_t success,
 176                                             const char *emsg);
 177
 178
 179 /**
 180  * Store an attribute.  If the attribute is already present,
 181  * it is replaced with the new attribute.
 182  *
 183  * @param h handle to the identity provider
 184  * @param pkey private key of the identity
 185  * @param attr the attribute
 186  * @param cont continuation to call when done
 187  * @param cont_cls closure for @a cont
 188  * @return handle to abort the request
 189  */
 190 struct GNUNET_IDENTITY_PROVIDER_Operation *
 191 GNUNET_IDENTITY_PROVIDER_attribute_store (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
 192                                           const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
 193                                           const struct GNUNET_IDENTITY_PROVIDER_Attribute *attr,
 194                                           GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cont,
 195                                           void *cont_cls);
 196
 197
 198 /**
 199  * Create a new attribute.
 200  *
 201  * @param name the attribute name
 202  * @param type the attribute type
 203  * @param data the attribute value
 204  * @param data_size the attribute value size
 205  * @return the new attribute
 206  */
 207 struct GNUNET_IDENTITY_PROVIDER_Attribute *
 208 GNUNET_IDENTITY_PROVIDER_attribute_new (const char* attr_name,
 209                                         uint32_t attr_type,
 210                                         const void* data,
 211                                         size_t data_size);
 212
 213 /**
 214  * Process an attribute that was stored in the idp.
 215  *
 216  * @param cls closure
 217  * @param attr the attribute
 218  */
 219 typedef void
 220 (*GNUNET_IDENTITY_PROVIDER_AttributeResult) (void *cls,
 221                                    const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 222                                    const struct GNUNET_IDENTITY_PROVIDER_Attribute *attr);
 223
 224
 225
 226 /**
 227  * List all attributes for a local identity.
 228  * This MUST lock the `struct GNUNET_IDENTITY_PROVIDER_Handle`
 229  * for any other calls than #GNUNET_IDENTITY_PROVIDER_get_attributes_next() and
 230  * #GNUNET_IDENTITY_PROVIDER_get_attributes_stop. @a proc will be called once
 231  * immediately, and then again after
 232  * #GNUNET_IDENTITY_PROVIDER_get_attributes_next() is invoked.
 233  *
 234  * On error (disconnect), @a error_cb will be invoked.
 235  * On normal completion, @a finish_cb proc will be
 236  * invoked.
 237  *
 238  * @param h handle to the idp
 239  * @param identity identity to access
 240  * @param error_cb function to call on error (i.e. disconnect),
 241  *        the handle is afterwards invalid
 242  * @param error_cb_cls closure for @a error_cb
 243  * @param proc function to call on each attribute; it
 244  *        will be called repeatedly with a value (if available)
 245  * @param proc_cls closure for @a proc
 246  * @param finish_cb function to call on completion
 247  *        the handle is afterwards invalid
 248  * @param finish_cb_cls closure for @a finish_cb
 249  * @return an iterator handle to use for iteration
 250  */
 251 struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *
 252 GNUNET_IDENTITY_PROVIDER_get_attributes_start (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
 253                                                const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
 254                                                GNUNET_SCHEDULER_TaskCallback error_cb,
 255                                                void *error_cb_cls,
 256                                                GNUNET_IDENTITY_PROVIDER_AttributeResult proc,
 257                                                void *proc_cls,
 258                                                GNUNET_SCHEDULER_TaskCallback finish_cb,
 259                                                void *finish_cb_cls);
 260
 261
 262 /**
 263  * Calls the record processor specified in #GNUNET_IDENTITY_PROVIDER_get_attributes_start
 264  * for the next record.
 265  *
 266  * @param it the iterator
 267  */
 268 void
 269 GNUNET_IDENTITY_PROVIDER_get_attributes_next (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
 270
 271
 272 /**
 273  * Stops iteration and releases the idp handle for further calls.  Must
 274  * be called on any iteration that has not yet completed prior to calling
 275  * #GNUNET_IDENTITY_PROVIDER_disconnect.
 276  *
 277  * @param it the iterator
 278  */
 279 void
 280 GNUNET_IDENTITY_PROVIDER_get_attributes_stop (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
 281
 282
 283
 284 /**
 285  * Issue a token for a specific audience.
 286  *
 287  * @param id identity provider service to use
 288  * @param iss issuer (identity)
 289  * @param aud audience (identity)
 290  * @param scope the identity attributes requested, comman separated
 291  * @param expiration the token expiration
 292  * @param nonce the nonce that will be included in token and ticket
 293  * @param cb callback to call with result
 294  * @param cb_cls closure
 295  * @return handle to abort the operation
 296  */
 297 struct GNUNET_IDENTITY_PROVIDER_Operation *
 298 GNUNET_IDENTITY_PROVIDER_issue_token (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 299                                       const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss_key,
 300                                       const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
 301                                       const char* scope,
 302                                       const char* vattr,
 303                                       struct GNUNET_TIME_Absolute expiration,
 304                                       uint64_t nonce,
 305                                       GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
 306                                       void *cb_cls);
 307
 308
 309 /**
 310  * Exchange a ticket for a token. Intended to be used by audience that
 311  * received a ticket.
 312  *
 313  * @param id identity provider service to use
 314  * @param ticket the ticket to exchange
 315  * @param aud_privkey the audience of the ticket
 316  * @param cont function to call once the operation finished
 317  * @param cont_cls closure for @a cont
 318  * @return handle to abort the operation
 319  */
 320 struct GNUNET_IDENTITY_PROVIDER_Operation *
 321 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 322                                           const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 323                                           const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
 324                                           GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
 325                                           void *cont_cls);
 326
 327
 328 /**
 329  * Disconnect from identity provider service.
 330  *
 331  * @param h identity provider service to disconnect
 332  */
 333 void
 334 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
 335
 336
 337 /**
 338  * Cancel an identity provider operation.  Note that the operation MAY still
 339  * be executed; this merely cancels the continuation; if the request
 340  * was already transmitted, the service may still choose to complete
 341  * the operation.
 342  *
 343  * @param op operation to cancel
 344  */
 345 void
 346 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
 347
 348
 349 /**
 350  * Convenience API
 351  */
 352
 353 /**
 354  * Destroy token
 355  *
 356  * @param token the token
 357  */
 358 void
 359 GNUNET_IDENTITY_PROVIDER_token_destroy(struct GNUNET_IDENTITY_PROVIDER_Token *token);
 360
 361 /**
 362  * Returns string representation of token. A JSON-Web-Token.
 363  *
 364  * @param token the token
 365  * @return The JWT (must be freed)
 366  */
 367 char *
 368 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 369
 370 /**
 371  * Returns string representation of ticket. Base64-Encoded
 372  *
 373  * @param ticket the ticket
 374  * @return the Base64-Encoded ticket
 375  */
 376 char *
 377 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 378
 379 /**
 380  * Created a ticket from a string (Base64 encoded ticket)
 381  *
 382  * @param input Base64 encoded ticket
 383  * @param ticket pointer where the ticket is stored
 384  * @return GNUNET_OK
 385  */
 386 int
 387 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
 388                                            struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
 389
 390 /**
 391  * Destroys a ticket
 392  *
 393  * @param ticket the ticket to destroy
 394  */
 395 void
 396 GNUNET_IDENTITY_PROVIDER_ticket_destroy(struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 397
 398 #if 0                           /* keep Emacsens' auto-indent happy */
 399 {
 400 #endif
 401 #ifdef __cplusplus
 402 }
 403 #endif
 404
 405
 406 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
 407 #endif
 408
 409 /** @} */ /* end of group identity */
 410
 411 /* end of gnunet_identity_provider_service.h */