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 ticket the ticket
  94  * @param name name assigned by the user for this ego,
  95  *                   NULL if the user just deleted the ego and it
  96  *                   must thus no longer be used
  97  */
  98 typedef void
  99 (*GNUNET_IDENTITY_PROVIDER_IssueCallback)(void *cls,
 100                             const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 101
 102
 103 /**
 104  * Connect to the identity provider service.
 105  *
 106  * @param cfg Configuration to contact the identity provider service.
 107  * @return handle to communicate with identity provider service
 108  */
 109 struct GNUNET_IDENTITY_PROVIDER_Handle *
 110 GNUNET_IDENTITY_PROVIDER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
 111
 112
 113 /**
 114  * Issue a token for a specific audience.
 115  *
 116  * @param id identity provider service to use
 117  * @param iss issuer (identity)
 118  * @param aud audience (identity)
 119  * @param scope the identity attributes requested, comman separated
 120  * @param expiration the token expiration
 121  * @param nonce the nonce that will be included in token and ticket
 122  * @param cb callback to call with result
 123  * @param cb_cls closure
 124  * @return handle to abort the operation
 125  */
 126 struct GNUNET_IDENTITY_PROVIDER_Operation *
 127 GNUNET_IDENTITY_PROVIDER_issue_token (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 128                      const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss_key,
 129          const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
 130          const char* scope,
 131          struct GNUNET_TIME_Absolute *expiration,
 132          uint64_t nonce,
 133                      GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
 134                      void *cb_cls);
 135
 136
 137 /**
 138  * Exchange a ticket for a token. Intended to be used by audience that
 139  * received a ticket.
 140  *
 141  * @param id identity provider service to use
 142  * @param ticket the ticket to exchange
 143  * @param aud_privkey the audience of the ticket
 144  * @param cont function to call once the operation finished
 145  * @param cont_cls closure for @a cont
 146  * @return handle to abort the operation
 147  */
 148 struct GNUNET_IDENTITY_PROVIDER_Operation *
 149 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
 150                      const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
 151          const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
 152                      GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
 153                      void *cont_cls);
 154
 155
 156 /**
 157  * Disconnect from identity provider service.
 158  *
 159  * @param h identity provider service to disconnect
 160  */
 161 void
 162 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
 163
 164
 165 /**
 166  * Cancel an identity provider operation.  Note that the operation MAY still
 167  * be executed; this merely cancels the continuation; if the request
 168  * was already transmitted, the service may still choose to complete
 169  * the operation.
 170  *
 171  * @param op operation to cancel
 172  */
 173 void
 174 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
 175
 176
 177 /**
 178  * Convenience API
 179  */
 180 char *
 181 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
 182
 183 char *
 184 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
 185
 186
 187 int
 188 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
 189                                            struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
 190
 191 #if 0                           /* keep Emacsens' auto-indent happy */
 192 {
 193 #endif
 194 #ifdef __cplusplus
 195 }
 196 #endif
 197
 198 /** @} */ /* end of group identity */
 199
 200 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
 201 #endif
 202 /* end of gnunet_identity_provider_service.h */