2 This file is part of GNUnet.
3 (C) 2013 Christian Grothoff (and other contributing authors)
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.
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.
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.
22 * @file include/gnunet_identity_service.h
23 * @brief Identity service; implements identity management for GNUnet
24 * @author Christian Grothoff
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
35 * @defgroup identity identity management service
38 #ifndef GNUNET_IDENTITY_SERVICE_H
39 #define GNUNET_IDENTITY_SERVICE_H
44 #if 0 /* keep Emacsens' auto-indent happy */
49 #include "gnunet_util_lib.h"
53 * Version number of GNUnet Identity API.
55 #define GNUNET_IDENTITY_VERSION 0x00000000
58 * Handle to access the identity service.
60 struct GNUNET_IDENTITY_Handle;
65 struct GNUNET_IDENTITY_Ego;
68 * Handle for an operation with the identity service.
70 struct GNUNET_IDENTITY_Operation;
74 * Obtain the ECC key associated with a ego.
77 * @return associated ECC key, valid as long as the ego is valid
79 const struct GNUNET_CRYPTO_EccPrivateKey *
80 GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego);
84 * Obtain the ego representing 'anonymous' users.
86 * @return handle for the anonymous user, must not be freed
88 const struct GNUNET_IDENTITY_Ego *
89 GNUNET_IDENTITY_ego_get_anonymous (void);
93 * Get the identifier (public key) of an ego.
95 * @param ego identity handle with the private key
96 * @param pk set to ego's public key
99 GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego,
100 struct GNUNET_CRYPTO_EccPublicKey *pk);
104 * Method called to inform about the egos of
107 * When used with #GNUNET_IDENTITY_connect, this function is
108 * initially called for all egos and then again whenever a
109 * ego's name changes or if it is deleted. At the end of
110 * the initial pass over all egos, the function is once called
111 * with 'NULL' for @a ego. That does NOT mean that the callback won't
112 * be invoked in the future or that there was an error.
114 * When used with #GNUNET_IDENTITY_create or #GNUNET_IDENTITY_get,
115 * this function is only called ONCE, and 'NULL' being passed in
116 * @a ego does indicate an error (i.e. name is taken or no default
117 * value is known). If @a ego is non-NULL and if '*ctx'
118 * is set in those callbacks, the value WILL be passed to a subsequent
119 * call to the identity callback of #GNUNET_IDENTITY_connect (if
120 * that one was not NULL).
122 * When an identity is renamed, this function is called with the
123 * (known) @a ego but the NEW @a name.
125 * When an identity is deleted, this function is called with the
126 * (known) ego and "NULL" for the @a name. In this case,
127 * the @a ego is henceforth invalid (and the @a ctx should also be
131 * @param ego ego handle
132 * @param ctx context for application to store data for this ego
133 * (during the lifetime of this process, initially NULL)
134 * @param name name assigned by the user for this ego,
135 * NULL if the user just deleted the ego and it
136 * must thus no longer be used
138 typedef void (*GNUNET_IDENTITY_Callback)(void *cls,
139 struct GNUNET_IDENTITY_Ego *ego,
145 * Connect to the identity service.
147 * @param cfg Configuration to contact the identity service.
148 * @param cb function to call on all identity events, can be NULL
149 * @param cb_cls closure for @a cb
150 * @return handle to communicate with identity service
152 struct GNUNET_IDENTITY_Handle *
153 GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
154 GNUNET_IDENTITY_Callback cb,
159 * Obtain the identity that is currently preferred/default
162 * @param id identity service to query
163 * @param service_name for which service is an identity wanted
164 * @param cb function to call with the result (will only be called once)
165 * @param cb_cls closure for @a cb
166 * @return handle to abort the operation
168 struct GNUNET_IDENTITY_Operation *
169 GNUNET_IDENTITY_get (struct GNUNET_IDENTITY_Handle *id,
170 const char *service_name,
171 GNUNET_IDENTITY_Callback cb,
176 * Function called once the requested operation has
180 * @param emsg NULL on success, otherwise an error message
182 typedef void (*GNUNET_IDENTITY_Continuation)(void *cls,
187 * Set the preferred/default identity for a service.
189 * @param id identity service to inform
190 * @param service_name for which service is an identity set
191 * @param ego new default identity to be set for this service
192 * @param cont function to call once the operation finished
193 * @param cont_cls closure for @a cont
194 * @return handle to abort the operation
196 struct GNUNET_IDENTITY_Operation *
197 GNUNET_IDENTITY_set (struct GNUNET_IDENTITY_Handle *id,
198 const char *service_name,
199 struct GNUNET_IDENTITY_Ego *ego,
200 GNUNET_IDENTITY_Continuation cont,
205 * Disconnect from identity service.
207 * @param h identity service to disconnect
210 GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *h);
214 * Create a new identity with the given name.
216 * @param id identity service to use
217 * @param name desired name
218 * @param cont function to call with the result (will only be called once)
219 * @param cont_cls closure for @a cont
220 * @return handle to abort the operation
222 struct GNUNET_IDENTITY_Operation *
223 GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id,
225 GNUNET_IDENTITY_Continuation cont,
230 * Renames an existing identity.
232 * @param id identity service to use
233 * @param old_name old name
234 * @param new_name desired new name
235 * @param cb function to call with the result (will only be called once)
236 * @param cb_cls closure for @a cb
237 * @return handle to abort the operation
239 struct GNUNET_IDENTITY_Operation *
240 GNUNET_IDENTITY_rename (struct GNUNET_IDENTITY_Handle *id,
241 const char *old_name,
242 const char *new_name,
243 GNUNET_IDENTITY_Continuation cb,
248 * Delete an existing identity.
250 * @param id identity service to use
251 * @param name name of the identity to delete
252 * @param cb function to call with the result (will only be called once)
253 * @param cb_cls closure for @a cb
254 * @return handle to abort the operation
256 struct GNUNET_IDENTITY_Operation *
257 GNUNET_IDENTITY_delete (struct GNUNET_IDENTITY_Handle *id,
259 GNUNET_IDENTITY_Continuation cb,
264 * Cancel an identity operation. Note that the operation MAY still
265 * be executed; this merely cancels the continuation; if the request
266 * was already transmitted, the service may still choose to complete
269 * @param op operation to cancel
272 GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
275 /* ************* convenience API to lookup an ego ***************** */
278 * Function called with the result.
281 * @param ego NULL on error / ego not found
283 typedef void (*GNUNET_IDENTITY_EgoCallback)(void *cls,
284 const struct GNUNET_IDENTITY_Ego *ego);
287 * Handle for ego lookup.
289 struct GNUNET_IDENTITY_EgoLookup;
293 * Lookup an ego by name.
295 * @param cfg configuration to use
296 * @param name name to look up
297 * @param cb callback to invoke with the result
298 * @param cb_cls closure for @a cb
299 * @return NULL on error
301 struct GNUNET_IDENTITY_EgoLookup *
302 GNUNET_IDENTITY_ego_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg,
304 GNUNET_IDENTITY_EgoCallback cb,
309 * Abort ego lookup attempt.
311 * @param el handle for lookup to abort
314 GNUNET_IDENTITY_ego_lookup_cancel (struct GNUNET_IDENTITY_EgoLookup *el);
317 #if 0 /* keep Emacsens' auto-indent happy */
324 /** @} */ /* end of group identity */
326 /* ifndef GNUNET_IDENTITY_SERVICE_H */
328 /* end of gnunet_identity_service.h */