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