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  * Method called when a token has been exchanged for a ticket.
  71  * On success returns a token
  72  *
  73  * @param cls closure
  74  * @param token the token
  75  */
  76 typedef void
  77 (*GNUNET_IDENTITY_PROVIDER_ExchangeCallback)(void *cls,
  78                             const struct GNUNET_IDENTITY_PROVIDER_Token *token,
  79                             uint64_t ticket_nonce);
  80
  81 /**
  82  * Method called when a token has been issued.
  83  * On success returns a ticket that can be given to the audience to retrive the
  84  * token
  85  *
  86  * @param cls closure
  87  * @param grant the label in GNS pointing to the token
  88  * @param ticket the ticket
  89  * @param token the issued token
  90  * @param name name assigned by the user for this ego,
  91  *                   NULL if the user just deleted the ego and it
  92  *                   must thus no longer be used
  93  */
  94 typedef void
  95 (*GNUNET_IDENTITY_PROVIDER_IssueCallback)(void *cls,
  96                             const char *grant,
  97                             const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
  98                             const struct GNUNET_IDENTITY_PROVIDER_Token *token);
  99
 100
 101 /**
 102  * Connect to the identity provider service.
 103  *
 104  * @param cfg Configuration to contact the identity provider service.
 105  * @return handle to communicate with identity provider service
 106  */
 107 struct GNUNET_IDENTITY_PROVIDER_Handle *
 108 GNUNET_IDENTITY_PROVIDER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 109
 110
 111 /**
 112  * Issue a token for a specific audience.
 113  *
 114  * @param id identity provider service to use
 115  * @param iss issuer (identity)
 116  * @param aud audience (identity)
 117  * @param scope the identity attributes requested, comman separated
 118  * @param expiration the token expiration
 119  * @param nonce the nonce that will be included in token and ticket
 120  * @param cb callback to call with result
 121  * @param cb_cls closure
 122  * @return handle to abort the operation
 123  */
 124 struct GNUNET_IDENTITY_PROVIDER_Operation *
 125 GNUNET_IDENTITY_PROVIDER_issue_token (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 126                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss_key,
 127          const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
 128          const char* scope,
 129          const char* vattr,
 130          struct GNUNET_TIME_Absolute expiration,
 131          uint64_t nonce,
 132                      GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
 133                      void *cb_cls);
 134
 135
 136 /**
 137  * Exchange a ticket for a token. Intended to be used by audience that
 138  * received a ticket.
 139  *
 140  * @param id identity provider service to use
 141  * @param ticket the ticket to exchange
 142  * @param aud_privkey the audience of the ticket
 143  * @param cont function to call once the operation finished
 144  * @param cont_cls closure for @a cont
 145  * @return handle to abort the operation
 146  */
 147 struct GNUNET_IDENTITY_PROVIDER_Operation *
 148 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 149                      const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 150          const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
 151                      GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
 152                      void *cont_cls);
 153
 154
 155 /**
 156  * Disconnect from identity provider service.
 157  *
 158  * @param h identity provider service to disconnect
 159  */
 160 void
 161 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
 162
 163
 164 /**
 165  * Cancel an identity provider operation.  Note that the operation MAY still
 166  * be executed; this merely cancels the continuation; if the request
 167  * was already transmitted, the service may still choose to complete
 168  * the operation.
 169  *
 170  * @param op operation to cancel
 171  */
 172 void
 173 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
 174
 175
 176 /**
 177  * Convenience API
 178  */
 179
 180 /**
 181  * Destroy token
 182  *
 183  * @param token the token
 184  */
 185 void
 186 GNUNET_IDENTITY_PROVIDER_token_destroy(struct GNUNET_IDENTITY_PROVIDER_Token *token);
 187
 188 /**
 189  * Returns string representation of token. A JSON-Web-Token.
 190  *
 191  * @param token the token
 192  * @return The JWT (must be freed)
 193  */
 194 char *
 195 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 196
 197 /**
 198  * Returns string representation of ticket. Base64-Encoded
 199  *
 200  * @param ticket the ticket
 201  * @return the Base64-Encoded ticket
 202  */
 203 char *
 204 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 205
 206 /**
 207  * Created a ticket from a string (Base64 encoded ticket)
 208  *
 209  * @param input Base64 encoded ticket
 210  * @param ticket pointer where the ticket is stored
 211  * @return GNUNET_OK
 212  */
 213 int
 214 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
 215                                            struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
 216
 217 /**
 218  * Destroys a ticket
 219  *
 220  * @param ticket the ticket to destroy
 221  */
 222 void
 223 GNUNET_IDENTITY_PROVIDER_ticket_destroy(struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 224
 225 #if 0                           /* keep Emacsens' auto-indent happy */
 226 {
 227 #endif
 228 #ifdef __cplusplus
 229 }
 230 #endif
 231
 232
 233 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
 234 #endif
 235
 236 /** @} */ /* end of group identity */
 237
 238 /* end of gnunet_identity_provider_service.h */