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