X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;ds=sidebyside;f=src%2Finclude%2Fgnunet_identity_service.h;h=e07951de7dbbd1b390f75515383c60fb978b751a;hb=a44744499d8f3df64cc1d15cd6b40b4b0e4a3683;hp=1d682cb1e9f05161bb47ce2b048ac4119f6b80c5;hpb=5a38c8f0d1826ea964e3e3452e1a3a2a24d7d35b;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_identity_service.h b/src/include/gnunet_identity_service.h index 1d682cb1e..e07951de7 100644 --- a/src/include/gnunet_identity_service.h +++ b/src/include/gnunet_identity_service.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2013 Christian Grothoff (and other contributing authors) + Copyright (C) 2013 GNUnet e.V. GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -14,25 +14,29 @@ You should have received a copy of the GNU General Public License along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ -/** - * @file include/gnunet_identity_service.h - * @brief Identity service; implements identity management for GNUnet +/** * @author Christian Grothoff * - * Identities in GNUnet are ECDSA keys. You assume an identity by - * using (signing with) a particular private key. As GNUnet users are - * expected to have many egos, we need an identity service to - * allow users to manage their egos. The identity service - * manages the egos (private keys) of the local user; it does - * NOT manage identities of other users (public keys). For giving - * names to other users and manage their public keys securely, we - * use GNS. + * @file + * Identity service; implements identity management for GNUnet + * + * @defgroup identity Identity service + * Identity management. + * + * Egos in GNUnet are ECDSA keys. You assume an ego by using (signing + * with) a particular private key. As GNUnet users are expected to + * have many egos, we need an identity service to allow users to + * manage their egos. The identity service manages the egos (private + * keys) of the local user; it does NOT manage egos of other users + * (public keys). For giving names to other users and manage their + * public keys securely, we use GNS. + * + * @see [Documentation](https://gnunet.org/identity-subsystem) * - * @defgroup identity identity management service * @{ */ #ifndef GNUNET_IDENTITY_SERVICE_H @@ -49,22 +53,22 @@ extern "C" #include "gnunet_util_lib.h" -/** +/** * Version number of GNUnet Identity API. */ #define GNUNET_IDENTITY_VERSION 0x00000000 -/** +/** * Handle to access the identity service. */ struct GNUNET_IDENTITY_Handle; -/** +/** * Handle for a ego. */ struct GNUNET_IDENTITY_Ego; -/** +/** * Handle for an operation with the identity service. */ struct GNUNET_IDENTITY_Operation; @@ -76,14 +80,14 @@ struct GNUNET_IDENTITY_Operation; * @param ego the ego * @return associated ECC key, valid as long as the ego is valid */ -const struct GNUNET_CRYPTO_EccPrivateKey * +const struct GNUNET_CRYPTO_EcdsaPrivateKey * GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego); /** * Obtain the ego representing 'anonymous' users. * - * @returns handle for the anonymous user, must not be freed + * @return handle for the anonymous user, must not be freed */ const struct GNUNET_IDENTITY_Ego * GNUNET_IDENTITY_ego_get_anonymous (void); @@ -97,12 +101,12 @@ GNUNET_IDENTITY_ego_get_anonymous (void); */ void GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego, - struct GNUNET_CRYPTO_EccPublicKey *pk); + struct GNUNET_CRYPTO_EcdsaPublicKey *pk); -/** +/** * Method called to inform about the egos of - * this peer. + * this peer. * * When used with #GNUNET_IDENTITY_connect, this function is * initially called for all egos and then again whenever a @@ -116,11 +120,11 @@ GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego, * @a ego does indicate an error (i.e. name is taken or no default * value is known). If @a ego is non-NULL and if '*ctx' * is set in those callbacks, the value WILL be passed to a subsequent - * call to the identity callback of #GNUNET_IDENTITY_connect (if + * call to the identity callback of #GNUNET_IDENTITY_connect (if * that one was not NULL). * * When an identity is renamed, this function is called with the - * (known) @a ego but the NEW @a name. + * (known) @a ego but the NEW @a name. * * When an identity is deleted, this function is called with the * (known) ego and "NULL" for the @a name. In this case, @@ -129,19 +133,20 @@ GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego, * * @param cls closure * @param ego ego handle - * @param ego_ctx context for application to store data for this ego + * @param ctx context for application to store data for this ego * (during the lifetime of this process, initially NULL) * @param name name assigned by the user for this ego, * NULL if the user just deleted the ego and it * must thus no longer be used */ -typedef void (*GNUNET_IDENTITY_Callback)(void *cls, - struct GNUNET_IDENTITY_Ego *ego, - void **ctx, - const char *name); +typedef void +(*GNUNET_IDENTITY_Callback)(void *cls, + struct GNUNET_IDENTITY_Ego *ego, + void **ctx, + const char *name); -/** +/** * Connect to the identity service. * * @param cfg Configuration to contact the identity service. @@ -156,7 +161,7 @@ GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, /** - * Obtain the identity that is currently preferred/default + * Obtain the ego that is currently preferred/default * for a service. * * @param id identity service to query @@ -179,12 +184,13 @@ GNUNET_IDENTITY_get (struct GNUNET_IDENTITY_Handle *id, * @param cls closure * @param emsg NULL on success, otherwise an error message */ -typedef void (*GNUNET_IDENTITY_Continuation)(void *cls, - const char *emsg); +typedef void +(*GNUNET_IDENTITY_Continuation)(void *cls, + const char *emsg); /** - * Set the preferred/default identity for a service. + * Set the preferred/default ego for a service. * * @param id identity service to inform * @param service_name for which service is an identity set @@ -205,13 +211,13 @@ GNUNET_IDENTITY_set (struct GNUNET_IDENTITY_Handle *id, * Disconnect from identity service. * * @param h identity service to disconnect - */ + */ void GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *h); -/** - * Create a new identity with the given name. +/** + * Create a new ego with the given name. * * @param id identity service to use * @param name desired name @@ -226,8 +232,8 @@ GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id, void *cont_cls); -/** - * Renames an existing identity. +/** + * Renames an existing ego. * * @param id identity service to use * @param old_name old name @@ -244,8 +250,8 @@ GNUNET_IDENTITY_rename (struct GNUNET_IDENTITY_Handle *id, void *cb_cls); -/** - * Delete an existing identity. +/** + * Delete an existing ego. * * @param id identity service to use * @param name name of the identity to delete @@ -272,6 +278,49 @@ void GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op); +/* ************* convenience API to lookup an ego ***************** */ + +/** + * Function called with the result. + * + * @param cls closure + * @param ego NULL on error / ego not found + */ +typedef void +(*GNUNET_IDENTITY_EgoCallback)(void *cls, + const struct GNUNET_IDENTITY_Ego *ego); + +/** + * Handle for ego lookup. + */ +struct GNUNET_IDENTITY_EgoLookup; + + +/** + * Lookup an ego by name. + * + * @param cfg configuration to use + * @param name name to look up + * @param cb callback to invoke with the result + * @param cb_cls closure for @a cb + * @return NULL on error + */ +struct GNUNET_IDENTITY_EgoLookup * +GNUNET_IDENTITY_ego_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *name, + GNUNET_IDENTITY_EgoCallback cb, + void *cb_cls); + + +/** + * Abort ego lookup attempt. + * + * @param el handle for lookup to abort + */ +void +GNUNET_IDENTITY_ego_lookup_cancel (struct GNUNET_IDENTITY_EgoLookup *el); + + #if 0 /* keep Emacsens' auto-indent happy */ { #endif @@ -279,8 +328,9 @@ GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op); } #endif -/** @} */ /* end of group identity */ - /* ifndef GNUNET_IDENTITY_SERVICE_H */ #endif + +/** @} */ /* end of group identity */ + /* end of gnunet_identity_service.h */