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      SPDX-License-Identifier: AGPL3.0-or-later
  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 #if 0 /* keep Emacsens' auto-indent happy */
  48 }
  49 #endif
  50 #endif
  51
  52 #include "gnunet_util_lib.h"
  53
  54
  55 /**
  56  * Version number of GNUnet Identity API.
  57  */
  58 #define GNUNET_IDENTITY_VERSION 0x00000100
  59
  60 /**
  61  * Handle to access the identity service.
  62  */
  63 struct GNUNET_IDENTITY_Handle;
  64
  65 /**
  66  * Handle for a ego.
  67  */
  68 struct GNUNET_IDENTITY_Ego;
  69
  70 /**
  71  * Handle for an operation with the identity service.
  72  */
  73 struct GNUNET_IDENTITY_Operation;
  74
  75
  76 /**
  77  * Obtain the ECC key associated with a ego.
  78  *
  79  * @param ego the ego
  80  * @return associated ECC key, valid as long as the ego is valid
  81  */
  82 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
  83 GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego);
  84
  85
  86 /**
  87  * Obtain the ego representing 'anonymous' users.
  88  *
  89  * @return handle for the anonymous user, must not be freed
  90  */
  91 const struct GNUNET_IDENTITY_Ego *
  92 GNUNET_IDENTITY_ego_get_anonymous (void);
  93
  94
  95 /**
  96  * Get the identifier (public key) of an ego.
  97  *
  98  * @param ego identity handle with the private key
  99  * @param pk set to ego's public key
 100  */
 101 void
 102 GNUNET_IDENTITY_ego_get_public_key (struct GNUNET_IDENTITY_Ego *ego,
 103                                     struct GNUNET_CRYPTO_EcdsaPublicKey *pk);
 104
 105
 106 /**
 107  * Method called to inform about the egos of this peer.
 108  *
 109  * When used with #GNUNET_IDENTITY_connect, this function is
 110  * initially called for all egos and then again whenever a
 111  * ego's name changes or if it is deleted.  At the end of
 112  * the initial pass over all egos, the function is once called
 113  * with 'NULL' for @a ego. That does NOT mean that the callback won't
 114  * be invoked in the future or that there was an error.
 115  *
 116  * When used with #GNUNET_IDENTITY_create or #GNUNET_IDENTITY_get,
 117  * this function is only called ONCE, and 'NULL' being passed in
 118  * @a ego does indicate an error (i.e. name is taken or no default
 119  * value is known).  If @a ego is non-NULL and if '*ctx'
 120  * is set in those callbacks, the value WILL be passed to a subsequent
 121  * call to the identity callback of #GNUNET_IDENTITY_connect (if
 122  * that one was not NULL).
 123  *
 124  * When an identity is renamed, this function is called with the
 125  * (known) @a ego but the NEW @a name.
 126  *
 127  * When an identity is deleted, this function is called with the
 128  * (known) ego and "NULL" for the @a name.  In this case,
 129  * the @a ego is henceforth invalid (and the @a ctx should also be
 130  * cleaned up).
 131  *
 132  * @param cls closure
 133  * @param ego ego handle
 134  * @param ctx context for application to store data for this ego
 135  *                 (during the lifetime of this process, initially NULL)
 136  * @param name name assigned by the user for this ego,
 137  *                   NULL if the user just deleted the ego and it
 138  *                   must thus no longer be used
 139  */
 140 typedef void
 141 (*GNUNET_IDENTITY_Callback) (void *cls,
 142                              struct GNUNET_IDENTITY_Ego *ego,
 143                              void **ctx,
 144                              const char *name);
 145
 146
 147 /**
 148  * Connect to the identity service.
 149  *
 150  * @param cfg Configuration to contact the identity service.
 151  * @param cb function to call on all identity events, can be NULL
 152  * @param cb_cls closure for @a cb
 153  * @return handle to communicate with identity service
 154  */
 155 struct GNUNET_IDENTITY_Handle *
 156 GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 157                          GNUNET_IDENTITY_Callback cb,
 158                          void *cb_cls);
 159
 160
 161 /**
 162  * Obtain the ego that is currently preferred/default for a service.
 163  *
 164  * @param id identity service to query
 165  * @param service_name for which service is an identity wanted
 166  * @param cb function to call with the result (will only be called once)
 167  * @param cb_cls closure for @a cb
 168  * @return handle to abort the operation
 169  */
 170 struct GNUNET_IDENTITY_Operation *
 171 GNUNET_IDENTITY_get (struct GNUNET_IDENTITY_Handle *id,
 172                      const char *service_name,
 173                      GNUNET_IDENTITY_Callback cb,
 174                      void *cb_cls);
 175
 176
 177 /**
 178  * Function called once the requested operation has
 179  * been completed.
 180  *
 181  * @param cls closure
 182  * @param emsg NULL on success, otherwise an error message
 183  */
 184 typedef void
 185 (*GNUNET_IDENTITY_Continuation) (void *cls,
 186                                  const char *emsg);
 187
 188
 189 /**
 190  * Set the preferred/default ego for a service.
 191  *
 192  * @param id identity service to inform
 193  * @param service_name for which service is an identity set
 194  * @param ego new default identity to be set for this service
 195  * @param cont function to call once the operation finished
 196  * @param cont_cls closure for @a cont
 197  * @return handle to abort the operation
 198  */
 199 struct GNUNET_IDENTITY_Operation *
 200 GNUNET_IDENTITY_set (struct GNUNET_IDENTITY_Handle *id,
 201                      const char *service_name,
 202                      struct GNUNET_IDENTITY_Ego *ego,
 203                      GNUNET_IDENTITY_Continuation cont,
 204                      void *cont_cls);
 205
 206
 207 /**
 208  * Disconnect from identity service.
 209  *
 210  * @param h identity service to disconnect
 211  */
 212 void
 213 GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *h);
 214
 215
 216 /**
 217  * Function called once the requested operation has
 218  * been completed.
 219  *
 220  * @param cls closure
 221  * @param pk private key, NULL on error
 222  * @param emsg error message, NULL on success
 223  */
 224 typedef void
 225 (*GNUNET_IDENTITY_CreateContinuation) (
 226   void *cls,
 227   const struct GNUNET_CRYPTO_EcdsaPrivateKey *pk,
 228   const char *emsg);
 229
 230
 231 /**
 232  * Create a new ego with the given name.
 233  *
 234  * @param id identity service to use
 235  * @param name desired name
 236  * @param cont function to call with the result (will only be called once)
 237  * @param cont_cls closure for @a cont
 238  * @return handle to abort the operation
 239  */
 240 struct GNUNET_IDENTITY_Operation *
 241 GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id,
 242                         const char *name,
 243                         GNUNET_IDENTITY_CreateContinuation cont,
 244                         void *cont_cls);
 245
 246
 247 /**
 248  * Renames an existing ego.
 249  *
 250  * @param id identity service to use
 251  * @param old_name old name
 252  * @param new_name desired new name
 253  * @param cb function to call with the result (will only be called once)
 254  * @param cb_cls closure for @a cb
 255  * @return handle to abort the operation
 256  */
 257 struct GNUNET_IDENTITY_Operation *
 258 GNUNET_IDENTITY_rename (struct GNUNET_IDENTITY_Handle *id,
 259                         const char *old_name,
 260                         const char *new_name,
 261                         GNUNET_IDENTITY_Continuation cb,
 262                         void *cb_cls);
 263
 264
 265 /**
 266  * Delete an existing ego.
 267  *
 268  * @param id identity service to use
 269  * @param name name of the identity to delete
 270  * @param cb function to call with the result (will only be called once)
 271  * @param cb_cls closure for @a cb
 272  * @return handle to abort the operation
 273  */
 274 struct GNUNET_IDENTITY_Operation *
 275 GNUNET_IDENTITY_delete (struct GNUNET_IDENTITY_Handle *id,
 276                         const char *name,
 277                         GNUNET_IDENTITY_Continuation cb,
 278                         void *cb_cls);
 279
 280
 281 /**
 282  * Cancel an identity operation.  Note that the operation MAY still
 283  * be executed; this merely cancels the continuation; if the request
 284  * was already transmitted, the service may still choose to complete
 285  * the operation.
 286  *
 287  * @param op operation to cancel
 288  */
 289 void
 290 GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
 291
 292
 293 /* ************* convenience API to lookup an ego ***************** */
 294
 295 /**
 296  * Function called with the result.
 297  *
 298  * @param cls closure
 299  * @param ego NULL on error / ego not found
 300  */
 301 typedef void
 302 (*GNUNET_IDENTITY_EgoCallback) (void *cls,
 303                                 const struct GNUNET_IDENTITY_Ego *ego);
 304
 305 /**
 306  * Handle for ego lookup.
 307  */
 308 struct GNUNET_IDENTITY_EgoLookup;
 309
 310
 311 /**
 312  * Lookup an ego by name.
 313  *
 314  * @param cfg configuration to use
 315  * @param name name to look up
 316  * @param cb callback to invoke with the result
 317  * @param cb_cls closure for @a cb
 318  * @return NULL on error
 319  */
 320 struct GNUNET_IDENTITY_EgoLookup *
 321 GNUNET_IDENTITY_ego_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg,
 322                             const char *name,
 323                             GNUNET_IDENTITY_EgoCallback cb,
 324                             void *cb_cls);
 325
 326
 327 /**
 328  * Abort ego lookup attempt.
 329  *
 330  * @param el handle for lookup to abort
 331  */
 332 void
 333 GNUNET_IDENTITY_ego_lookup_cancel (struct GNUNET_IDENTITY_EgoLookup *el);
 334
 335 /**
 336  * Function called with the result.
 337  *
 338  * @param cls closure
 339  * @param ego NULL on error / ego not found
 340  * @param ego_name NULL on error, name of the ego otherwise
 341  */
 342 typedef void
 343 (*GNUNET_IDENTITY_EgoSuffixCallback) (
 344   void *cls,
 345   const struct GNUNET_CRYPTO_EcdsaPrivateKey *priv,
 346   const char *ego_name);
 347
 348
 349 /**
 350  * Handle for suffix lookup.
 351  */
 352 struct GNUNET_IDENTITY_EgoSuffixLookup;
 353
 354
 355 /**
 356  * Obtain the ego with the maximum suffix match between the
 357  * ego's name and the given domain name @a suffix.  I.e., given
 358  * a @a suffix "a.b.c" and egos with names "d.a.b.c", "b.c" and "c",
 359  * we return the ego for "b.c".
 360  *
 361  * @param cfg configuration to use
 362  * @param suffix for which domain name suffix is an identity wanted
 363  * @param cb function to call with the result (will only be called once)
 364  * @param cb_cls closure for @a cb
 365  * @return handle to abort the operation
 366  */
 367 struct GNUNET_IDENTITY_EgoSuffixLookup *
 368 GNUNET_IDENTITY_ego_lookup_by_suffix (const struct
 369                                       GNUNET_CONFIGURATION_Handle *cfg,
 370                                       const char *suffix,
 371                                       GNUNET_IDENTITY_EgoSuffixCallback cb,
 372                                       void *cb_cls);
 373
 374
 375 /**
 376  * Abort ego suffix lookup attempt.
 377  *
 378  * @param el handle for lookup to abort
 379  */
 380 void
 381 GNUNET_IDENTITY_ego_lookup_by_suffix_cancel (
 382   struct GNUNET_IDENTITY_EgoSuffixLookup *el);
 383
 384
 385 #if 0 /* keep Emacsens' auto-indent happy */
 386 {
 387 #endif
 388 #ifdef __cplusplus
 389 }
 390 #endif
 391
 392 /* ifndef GNUNET_IDENTITY_SERVICE_H */
 393 #endif
 394
 395 /** @} */ /* end of group identity */
 396
 397 /* end of gnunet_identity_service.h */