2 This file is part of GNUnet.
3 Copyright (C) 2013 GNUnet e.V.
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.
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.
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/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
22 * @author Christian Grothoff
25 * Identity service; implements identity management for GNUnet
27 * @defgroup identity Identity service
28 * Identity management.
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.
38 * @see [Documentation](https://gnunet.org/identity-subsystem)
42 #ifndef GNUNET_IDENTITY_SERVICE_H
43 #define GNUNET_IDENTITY_SERVICE_H
47 #if 0 /* keep Emacsens' auto-indent happy */
52 #include "gnunet_util_lib.h"
56 * Version number of GNUnet Identity API.
58 #define GNUNET_IDENTITY_VERSION 0x00000000
61 * Handle to access the identity service.
63 struct GNUNET_IDENTITY_Handle;
68 struct GNUNET_IDENTITY_Ego;
71 * Handle for an operation with the identity service.
73 struct GNUNET_IDENTITY_Operation;
77 * Obtain the ECC key associated with a ego.
80 * @return associated ECC key, valid as long as the ego is valid
82 const struct GNUNET_CRYPTO_EcdsaPrivateKey *
83 GNUNET_IDENTITY_ego_get_private_key (const struct GNUNET_IDENTITY_Ego *ego);
87 * Obtain the ego representing 'anonymous' users.
89 * @return handle for the anonymous user, must not be freed
91 const struct GNUNET_IDENTITY_Ego *
92 GNUNET_IDENTITY_ego_get_anonymous (void);
96 * Get the identifier (public key) of an ego.
98 * @param ego identity handle with the private key
99 * @param pk set to ego's public key
102 GNUNET_IDENTITY_ego_get_public_key (const struct GNUNET_IDENTITY_Ego *ego,
103 struct GNUNET_CRYPTO_EcdsaPublicKey *pk);
107 * Method called to inform about the egos of this peer.
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.
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).
124 * When an identity is renamed, this function is called with the
125 * (known) @a ego but the NEW @a name.
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
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
140 typedef void (*GNUNET_IDENTITY_Callback) (void *cls,
141 struct GNUNET_IDENTITY_Ego *ego,
147 * Connect to the identity service.
149 * @param cfg Configuration to contact the identity service.
150 * @param cb function to call on all identity events, can be NULL
151 * @param cb_cls closure for @a cb
152 * @return handle to communicate with identity service
154 struct GNUNET_IDENTITY_Handle *
155 GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
156 GNUNET_IDENTITY_Callback cb,
161 * Obtain the ego that is currently preferred/default for a service.
163 * @param id identity service to query
164 * @param service_name for which service is an identity wanted
165 * @param cb function to call with the result (will only be called once)
166 * @param cb_cls closure for @a cb
167 * @return handle to abort the operation
169 struct GNUNET_IDENTITY_Operation *
170 GNUNET_IDENTITY_get (struct GNUNET_IDENTITY_Handle *id,
171 const char *service_name,
172 GNUNET_IDENTITY_Callback cb,
177 * Function called once the requested operation has
181 * @param emsg NULL on success, otherwise an error message
183 typedef void (*GNUNET_IDENTITY_Continuation) (void *cls, const char *emsg);
187 * Set the preferred/default ego 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 * Function called once the requested operation has
218 * @param pk private key, NULL on error
219 * @param emsg error message, NULL on success
221 typedef void (*GNUNET_IDENTITY_CreateContinuation) (
223 const struct GNUNET_CRYPTO_EcdsaPrivateKey *pk,
228 * Create a new ego with the given name.
230 * @param id identity service to use
231 * @param name desired name
232 * @param cont function to call with the result (will only be called once)
233 * @param cont_cls closure for @a cont
234 * @return handle to abort the operation
236 struct GNUNET_IDENTITY_Operation *
237 GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id,
239 GNUNET_IDENTITY_CreateContinuation cont,
244 * Renames an existing ego.
246 * @param id identity service to use
247 * @param old_name old name
248 * @param new_name desired new name
249 * @param cb function to call with the result (will only be called once)
250 * @param cb_cls closure for @a cb
251 * @return handle to abort the operation
253 struct GNUNET_IDENTITY_Operation *
254 GNUNET_IDENTITY_rename (struct GNUNET_IDENTITY_Handle *id,
255 const char *old_name,
256 const char *new_name,
257 GNUNET_IDENTITY_Continuation cb,
262 * Delete an existing ego.
264 * @param id identity service to use
265 * @param name name of the identity to delete
266 * @param cb function to call with the result (will only be called once)
267 * @param cb_cls closure for @a cb
268 * @return handle to abort the operation
270 struct GNUNET_IDENTITY_Operation *
271 GNUNET_IDENTITY_delete (struct GNUNET_IDENTITY_Handle *id,
273 GNUNET_IDENTITY_Continuation cb,
278 * Cancel an identity operation. Note that the operation MAY still
279 * be executed; this merely cancels the continuation; if the request
280 * was already transmitted, the service may still choose to complete
283 * @param op operation to cancel
286 GNUNET_IDENTITY_cancel (struct GNUNET_IDENTITY_Operation *op);
289 /* ************* convenience API to lookup an ego ***************** */
292 * Function called with the result.
295 * @param ego NULL on error / ego not found
297 typedef void (*GNUNET_IDENTITY_EgoCallback) (
299 const struct GNUNET_IDENTITY_Ego *ego);
302 * Handle for ego lookup.
304 struct GNUNET_IDENTITY_EgoLookup;
308 * Lookup an ego by name.
310 * @param cfg configuration to use
311 * @param name name to look up
312 * @param cb callback to invoke with the result
313 * @param cb_cls closure for @a cb
314 * @return NULL on error
316 struct GNUNET_IDENTITY_EgoLookup *
317 GNUNET_IDENTITY_ego_lookup (const struct GNUNET_CONFIGURATION_Handle *cfg,
319 GNUNET_IDENTITY_EgoCallback cb,
324 * Abort ego lookup attempt.
326 * @param el handle for lookup to abort
329 GNUNET_IDENTITY_ego_lookup_cancel (struct GNUNET_IDENTITY_EgoLookup *el);
332 #if 0 /* keep Emacsens' auto-indent happy */
339 /* ifndef GNUNET_IDENTITY_SERVICE_H */
342 /** @} */ /* end of group identity */
344 /* end of gnunet_identity_service.h */