src/include/gnunet_identity_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2013 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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @file include/gnunet_identity_service.h
  23  * @brief Identity service; implements identity management for GNUnet
  24  * @author Christian Grothoff
  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 identity management service
  35  * @{
  36  */
  37 #ifndef GNUNET_IDENTITY_SERVICE_H
  38 #define GNUNET_IDENTITY_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 API.
  53  */
  54 #define GNUNET_IDENTITY_VERSION 0x00000000
  55
  56 /**
  57  * Handle to access the identity service.
  58  */
  59 struct GNUNET_IDENTITY_Handle;
  60
  61 /**
  62  * Handle for a ego.
  63  */
  64 struct GNUNET_IDENTITY_Ego;
  65
  66 /**
  67  * Handle for an operation with the identity service.
  68  */
  69 struct GNUNET_IDENTITY_Operation;
  70
  71
  72 /**
  73  * Obtain the ECC key associated with a ego.
  74  *
  75  * @param ego the ego
  76  * @return associated ECC key, valid as long as the ego is valid
  77  */
  78 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
  79 GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego);
  80
  81
  82 /**
  83  * Obtain the ego representing 'anonymous' users.
  84  *
  85  * @return handle for the anonymous user, must not be freed
  86  */
  87 const struct GNUNET_IDENTITY_Ego *
  88 GNUNET_IDENTITY_ego_get_anonymous (void);
  89
  90
  91 /**
  92  * Get the identifier (public key) of an ego.
  93  *
  94  * @param ego identity handle with the private key
  95  * @param pk set to ego's public key
  96  */
  97 void
  98 GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego,
  99                                     struct GNUNET_CRYPTO_EcdsaPublicKey *pk);
 100
 101
 102 /**
 103  * Method called to inform about the egos of
 104  * this peer.
 105  *
 106  * When used with #GNUNET_IDENTITY_connect, this function is
 107  * initially called for all egos and then again whenever a
 108  * ego's name changes or if it is deleted.  At the end of
 109  * the initial pass over all egos, the function is once called
 110  * with 'NULL' for @a ego. That does NOT mean that the callback won't
 111  * be invoked in the future or that there was an error.
 112  *
 113  * When used with #GNUNET_IDENTITY_create or #GNUNET_IDENTITY_get,
 114  * this function is only called ONCE, and 'NULL' being passed in
 115  * @a ego does indicate an error (i.e. name is taken or no default
 116  * value is known).  If @a ego is non-NULL and if '*ctx'
 117  * is set in those callbacks, the value WILL be passed to a subsequent
 118  * call to the identity callback of #GNUNET_IDENTITY_connect (if
 119  * that one was not NULL).
 120  *
 121  * When an identity is renamed, this function is called with the
 122  * (known) @a ego but the NEW @a name.
 123  *
 124  * When an identity is deleted, this function is called with the
 125  * (known) ego and "NULL" for the @a name.  In this case,
 126  * the @a ego is henceforth invalid (and the @a ctx should also be
 127  * cleaned up).
 128  *
 129  * @param cls closure
 130  * @param ego ego handle
 131  * @param ctx context for application to store data for this ego
 132  *                 (during the lifetime of this process, initially NULL)
 133  * @param name name assigned by the user for this ego,
 134  *                   NULL if the user just deleted the ego and it
 135  *                   must thus no longer be used
 136  */
 137 typedef void (*GNUNET_IDENTITY_Callback)(void *cls,
 138                                          struct GNUNET_IDENTITY_Ego *ego,
 139                                          void **ctx,
 140                                          const char *name);
 141
 142
 143 /**
 144  * Connect to the identity service.
 145  *
 146  * @param cfg Configuration to contact the identity service.
 147  * @param cb function to call on all identity events, can be NULL
 148  * @param cb_cls closure for @a cb
 149  * @return handle to communicate with identity service
 150  */
 151 struct GNUNET_IDENTITY_Handle *
 152 GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 153                          GNUNET_IDENTITY_Callback cb,
 154                          void *cb_cls);
 155
 156
 157 /**
 158  * Obtain the ego that is currently preferred/default
 159  * for a service.
 160  *
 161  * @param id identity service to query
 162  * @param service_name for which service is an identity wanted
 163  * @param cb function to call with the result (will only be called once)
 164  * @param cb_cls closure for @a cb
 165  * @return handle to abort the operation
 166  */
 167 struct GNUNET_IDENTITY_Operation *
 168 GNUNET_IDENTITY_get (struct GNUNET_IDENTITY_Handle *id,
 169                      const char *service_name,
 170                      GNUNET_IDENTITY_Callback cb,
 171                      void *cb_cls);
 172
 173
 174 /**
 175  * Function called once the requested operation has
 176  * been completed.
 177  *
 178  * @param cls closure
 179  * @param emsg NULL on success, otherwise an error message
 180  */
 181 typedef void (*GNUNET_IDENTITY_Continuation)(void *cls,
 182                                              const char *emsg);
 183
 184
 185 /**
 186  * Set the preferred/default ego for a service.
 187  *
 188  * @param id identity service to inform
 189  * @param service_name for which service is an identity set
 190  * @param ego new default identity to be set for this service
 191  * @param cont function to call once the operation finished
 192  * @param cont_cls closure for @a cont
 193  * @return handle to abort the operation
 194  */
 195 struct GNUNET_IDENTITY_Operation *
 196 GNUNET_IDENTITY_set (struct GNUNET_IDENTITY_Handle *id,
 197                      const char *service_name,
 198                      struct GNUNET_IDENTITY_Ego *ego,
 199                      GNUNET_IDENTITY_Continuation cont,
 200                      void *cont_cls);
 201
 202
 203 /**
 204  * Disconnect from identity service.
 205  *
 206  * @param h identity service to disconnect
 207  */
 208 void
 209 GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *h);
 210
 211
 212 /**
 213  * Create a new ego with the given name.
 214  *
 215  * @param id identity service to use
 216  * @param name desired name
 217  * @param cont function to call with the result (will only be called once)
 218  * @param cont_cls closure for @a cont
 219  * @return handle to abort the operation
 220  */
 221 struct GNUNET_IDENTITY_Operation *
 222 GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id,
 223                         const char *name,
 224                         GNUNET_IDENTITY_Continuation cont,
 225                         void *cont_cls);
 226
 227
 228 /**
 229  * Renames an existing ego.
 230  *
 231  * @param id identity service to use
 232  * @param old_name old name
 233  * @param new_name desired new name
 234  * @param cb function to call with the result (will only be called once)
 235  * @param cb_cls closure for @a cb
 236  * @return handle to abort the operation
 237  */
 238 struct GNUNET_IDENTITY_Operation *
 239 GNUNET_IDENTITY_rename (struct GNUNET_IDENTITY_Handle *id,
 240                         const char *old_name,
 241                         const char *new_name,
 242                         GNUNET_IDENTITY_Continuation cb,
 243                         void *cb_cls);
 244
 245
 246 /**
 247  * Delete an existing ego.
 248  *
 249  * @param id identity service to use
 250  * @param name name of the identity to delete
 251  * @param cb function to call with the result (will only be called once)
 252  * @param cb_cls closure for @a cb
 253  * @return handle to abort the operation
 254  */
 255 struct GNUNET_IDENTITY_Operation *
 256 GNUNET_IDENTITY_delete (struct GNUNET_IDENTITY_Handle *id,
 257                         const char *name,
 258                         GNUNET_IDENTITY_Continuation cb,
 259                         void *cb_cls);
 260
 261
 262 /**
 263  * Cancel an identity operation.  Note that the operation MAY still
 264  * be executed; this merely cancels the continuation; if the request
 265  * was already transmitted, the service may still choose to complete
 266  * the operation.
 267  *
 268  * @param op operation to cancel
 269  */
 270 void
 271 GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
 272
 273
 274 /* ************* convenience API to lookup an ego ***************** */
 275
 276 /**
 277  * Function called with the result.
 278  *
 279  * @param cls closure
 280  * @param ego NULL on error / ego not found
 281  */
 282 typedef void (*GNUNET_IDENTITY_EgoCallback)(void *cls,
 283                                             const struct GNUNET_IDENTITY_Ego *ego);
 284
 285 /**
 286  * Handle for ego lookup.
 287  */
 288 struct GNUNET_IDENTITY_EgoLookup;
 289
 290
 291 /**
 292  * Lookup an ego by name.
 293  *
 294  * @param cfg configuration to use
 295  * @param name name to look up
 296  * @param cb callback to invoke with the result
 297  * @param cb_cls closure for @a cb
 298  * @return NULL on error
 299  */
 300 struct GNUNET_IDENTITY_EgoLookup *
 301 GNUNET_IDENTITY_ego_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg,
 302                             const char *name,
 303                             GNUNET_IDENTITY_EgoCallback cb,
 304                             void *cb_cls);
 305
 306
 307 /**
 308  * Abort ego lookup attempt.
 309  *
 310  * @param el handle for lookup to abort
 311  */
 312 void
 313 GNUNET_IDENTITY_ego_lookup_cancel (struct GNUNET_IDENTITY_EgoLookup *el);
 314
 315
 316 #if 0                           /* keep Emacsens' auto-indent happy */
 317 {
 318 #endif
 319 #ifdef __cplusplus
 320 }
 321 #endif
 322
 323 /** @} */ /* end of group identity */
 324
 325 /* ifndef GNUNET_IDENTITY_SERVICE_H */
 326 #endif
 327 /* end of gnunet_identity_service.h */