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