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          struct GNUNET_TIME_Absolute expiration,
 130          uint64_t nonce,
 131                      GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
 132                      void *cb_cls);
 133
 134
 135 /**
 136  * Exchange a ticket for a token. Intended to be used by audience that
 137  * received a ticket.
 138  *
 139  * @param id identity provider service to use
 140  * @param ticket the ticket to exchange
 141  * @param aud_privkey the audience of the ticket
 142  * @param cont function to call once the operation finished
 143  * @param cont_cls closure for @a cont
 144  * @return handle to abort the operation
 145  */
 146 struct GNUNET_IDENTITY_PROVIDER_Operation *
 147 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 148                      const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 149          const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
 150                      GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
 151                      void *cont_cls);
 152
 153
 154 /**
 155  * Disconnect from identity provider service.
 156  *
 157  * @param h identity provider service to disconnect
 158  */
 159 void
 160 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
 161
 162
 163 /**
 164  * Cancel an identity provider operation.  Note that the operation MAY still
 165  * be executed; this merely cancels the continuation; if the request
 166  * was already transmitted, the service may still choose to complete
 167  * the operation.
 168  *
 169  * @param op operation to cancel
 170  */
 171 void
 172 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
 173
 174
 175 /**
 176  * Convenience API
 177  */
 178
 179 /**
 180  * Destroy token
 181  *
 182  * @param token the token
 183  */
 184 void
 185 GNUNET_IDENTITY_PROVIDER_token_destroy(struct GNUNET_IDENTITY_PROVIDER_Token *token);
 186
 187 /**
 188  * Returns string representation of token. A JSON-Web-Token.
 189  *
 190  * @param token the token
 191  * @return The JWT (must be freed)
 192  */
 193 char *
 194 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 195
 196 /**
 197  * Returns string representation of ticket. Base64-Encoded
 198  *
 199  * @param ticket the ticket
 200  * @return the Base64-Encoded ticket
 201  */
 202 char *
 203 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 204
 205 /**
 206  * Created a ticket from a string (Base64 encoded ticket)
 207  *
 208  * @param input Base64 encoded ticket
 209  * @param ticket pointer where the ticket is stored
 210  * @return GNUNET_OK
 211  */
 212 int
 213 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
 214                                            struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
 215
 216 /**
 217  * Destroys a ticket
 218  *
 219  * @param ticket the ticket to destroy
 220  */
 221 void
 222 GNUNET_IDENTITY_PROVIDER_ticket_destroy(struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 223
 224 #if 0                           /* keep Emacsens' auto-indent happy */
 225 {
 226 #endif
 227 #ifdef __cplusplus
 228 }
 229 #endif
 230
 231
 232 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
 233 #endif
 234
 235 /** @} */ /* end of group identity */
 236
 237 /* end of gnunet_identity_provider_service.h */