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  * @file include/gnunet_identity_provider_service.h
  23  * @brief Identity provider service; implements identity provider for GNUnet
  24  * @author Martin Schanzenbach
  25  *
  26  * Egos in GNUnet are ECDSA keys.  You assume an ego by using (signing
  27  * with) a particular private key.  As GNUnet users are expected to
  28  * have many egos, we need an identity service to allow users to
  29  * manage their egos.  The identity service manages the egos (private
  30  * keys) of the local user; it does NOT manage egos of other users
  31  * (public keys).  For giving names to other users and manage their
  32  * public keys securely, we use GNS.
  33  *
  34  * @defgroup identity-provider service
  35  * @{
  36  */
  37 #ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H
  38 #define GNUNET_IDENTITY_PROVIDER_SERVICE_H
  39
  40 #ifdef __cplusplus
  41 extern "C"
  42 {
  43 #if 0                           /* keep Emacsens' auto-indent happy */
  44 }
  45 #endif
  46 #endif
  47
  48 #include "gnunet_util_lib.h"
  49
  50
  51 /**
  52  * Version number of GNUnet Identity Provider API.
  53  */
  54 #define GNUNET_IDENTITY_PROVIDER_VERSION 0x00000000
  55
  56 /**
  57  * Handle to access the identity service.
  58  */
  59 struct GNUNET_IDENTITY_PROVIDER_Handle;
  60
  61 /**
  62  * Handle for a token.
  63  */
  64 struct GNUNET_IDENTITY_PROVIDER_Token;
  65
  66 /**
  67  * Handle for a ticket
  68  */
  69 struct GNUNET_IDENTITY_PROVIDER_Ticket;
  70
  71 /**
  72  * Handle for an operation with the identity provider service.
  73  */
  74 struct GNUNET_IDENTITY_PROVIDER_Operation;
  75
  76 /**
  77  * Method called when a token has been exchanged for a ticket.
  78  * On success returns a token
  79  *
  80  * @param cls closure
  81  * @param token the token
  82  */
  83 typedef void
  84 (*GNUNET_IDENTITY_PROVIDER_ExchangeCallback)(void *cls,
  85                             const struct GNUNET_IDENTITY_PROVIDER_Token *token);
  86
  87 /**
  88  * Method called when a token has been issued.
  89  * On success returns a ticket that can be given to the audience to retrive the
  90  * token
  91  *
  92  * @param cls closure
  93  * @param grant the label in GNS pointing to the token
  94  * @param ticket the ticket
  95  * @param token the issued token
  96  * @param name name assigned by the user for this ego,
  97  *                   NULL if the user just deleted the ego and it
  98  *                   must thus no longer be used
  99  */
 100 typedef void
 101 (*GNUNET_IDENTITY_PROVIDER_IssueCallback)(void *cls,
 102                             const char *grant,
 103                             const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 104                             const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 105
 106
 107 /**
 108  * Connect to the identity provider service.
 109  *
 110  * @param cfg Configuration to contact the identity provider service.
 111  * @return handle to communicate with identity provider service
 112  */
 113 struct GNUNET_IDENTITY_PROVIDER_Handle *
 114 GNUNET_IDENTITY_PROVIDER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 115
 116
 117 /**
 118  * Issue a token for a specific audience.
 119  *
 120  * @param id identity provider service to use
 121  * @param iss issuer (identity)
 122  * @param aud audience (identity)
 123  * @param scope the identity attributes requested, comman separated
 124  * @param expiration the token expiration
 125  * @param nonce the nonce that will be included in token and ticket
 126  * @param cb callback to call with result
 127  * @param cb_cls closure
 128  * @return handle to abort the operation
 129  */
 130 struct GNUNET_IDENTITY_PROVIDER_Operation *
 131 GNUNET_IDENTITY_PROVIDER_issue_token (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 132                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss_key,
 133          const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
 134          const char* scope,
 135          struct GNUNET_TIME_Absolute expiration,
 136          uint64_t nonce,
 137                      GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
 138                      void *cb_cls);
 139
 140
 141 /**
 142  * Exchange a ticket for a token. Intended to be used by audience that
 143  * received a ticket.
 144  *
 145  * @param id identity provider service to use
 146  * @param ticket the ticket to exchange
 147  * @param aud_privkey the audience of the ticket
 148  * @param cont function to call once the operation finished
 149  * @param cont_cls closure for @a cont
 150  * @return handle to abort the operation
 151  */
 152 struct GNUNET_IDENTITY_PROVIDER_Operation *
 153 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 154                      const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 155          const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
 156                      GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
 157                      void *cont_cls);
 158
 159
 160 /**
 161  * Disconnect from identity provider service.
 162  *
 163  * @param h identity provider service to disconnect
 164  */
 165 void
 166 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
 167
 168
 169 /**
 170  * Cancel an identity provider operation.  Note that the operation MAY still
 171  * be executed; this merely cancels the continuation; if the request
 172  * was already transmitted, the service may still choose to complete
 173  * the operation.
 174  *
 175  * @param op operation to cancel
 176  */
 177 void
 178 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
 179
 180
 181 /**
 182  * Convenience API
 183  */
 184
 185 /**
 186  * Destroy token
 187  *
 188  * @param token the token
 189  */
 190 void
 191 GNUNET_IDENTITY_PROVIDER_token_destroy(struct GNUNET_IDENTITY_PROVIDER_Token *token);
 192
 193 /**
 194  * Returns string representation of token. A JSON-Web-Token.
 195  *
 196  * @param token the token
 197  * @return The JWT (must be freed)
 198  */
 199 char *
 200 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 201
 202 /**
 203  * Returns string representation of ticket. Base64-Encoded
 204  *
 205  * @param ticket the ticket
 206  * @return the Base64-Encoded ticket
 207  */
 208 char *
 209 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 210
 211 /**
 212  * Created a ticket from a string (Base64 encoded ticket)
 213  *
 214  * @param input Base64 encoded ticket
 215  * @param ticket pointer where the ticket is stored
 216  * @return GNUNET_OK
 217  */
 218 int
 219 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
 220                                            struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
 221
 222 /**
 223  * Destroys a ticket
 224  *
 225  * @param ticket the ticket to destroy
 226  */
 227 void
 228 GNUNET_IDENTITY_PROVIDER_ticket_destroy(struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 229
 230 #if 0                           /* keep Emacsens' auto-indent happy */
 231 {
 232 #endif
 233 #ifdef __cplusplus
 234 }
 235 #endif
 236
 237 /** @} */ /* end of group identity */
 238
 239 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
 240 #endif
 241 /* end of gnunet_identity_provider_service.h */