src/include/gnunet_identity_provider_service.h

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