src/include/gnunet_identity_service.h

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