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