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 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
35 #ifndef GNUNET_IDENTITY_SERVICE_H
36 #define GNUNET_IDENTITY_SERVICE_H
41 #if 0 /* keep Emacsens' auto-indent happy */
46 #include "gnunet_util_lib.h"
50 * Version number of GNUnet Identity API.
52 #define GNUNET_IDENTITY_VERSION 0x00000000
55 * Handle to access the identity service.
57 struct GNUNET_IDENTITY_Handle;
60 * Handle for a pseudonym.
62 struct GNUNET_IDENTITY_Pseudonym;
66 * Obtain the ECC key associated with a pseudonym.
68 * @param pseudonym the pseudonym
69 * @return associated ECC key, valid as long as the pseudonym is valid
71 const struct GNUNET_CRYPTO_EccPrivateKey *
72 GNUNET_IDENTITY_pseudonym_get_key (struct GNUNET_IDENTITY_Pseudonym *pseudonym);
76 * Method called to inform about the pseudonyms of
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.
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).
95 * @param pseu pseudonym handle
96 * @param pseu_ctx context for application to store data for this pseudonym
97 * (during the lifetime of this process, initially NULL)
98 * @param identifier identifier assigned by the user for this pseudonym,
99 * NULL if the user just deleted the pseudonym and it
100 * must thus no longer be used
102 typedef void (*GNUNET_IDENTITY_Callback)(void *cls,
103 struct GNUNET_IDENTITY_Pseudonym *pseu,
105 const char *identifier);
109 * Connect to the identity service.
111 * @param cfg Configuration to contact the identity service.
112 * @param cb function to call on all identity events, can be NULL
113 * @param cb_cls closure for 'cb'
114 * @return handle to communicate with identity service
116 struct GNUNET_IDENTITY_Handle *
117 GNUNET_IDENTITY_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
118 GNUNET_IDENTITY_Callback cb,
123 * Obtain the identity that is currently preferred/default
126 * @param id identity service to query
127 * @param service_name for which service is an identity wanted
128 * @param cb function to call with the result (will only be called once)
129 * @param cb_cls closure for cb
130 * @return handle to abort the operation
132 struct GNUNET_IDENTITY_Operation *
133 GNUNET_IDENTITY_get (struct GNUNET_IDENTITY_Handle *id,
134 const char *service_name,
135 GNUNET_IDENTITY_Callback cb,
140 * Function called once the requested operation has
144 * @param emsg NULL on success, otherwise an error message
146 typedef void (*GNUNET_IDENTITY_Continuation)(void *cls,
151 * Set the preferred/default identity for a service.
153 * @param id identity service to inform
154 * @param service_name for which service is an identity set
155 * @param pseu new default identity to be set for this service
156 * @param cont function to call once the operation finished
157 * @param cont_cls closure for cont
158 * @return handle to abort the operation
160 struct GNUNET_IDENTITY_Operation *
161 GNUNET_IDENTITY_set (struct GNUNET_IDENTITY_Handle *id,
162 const char *service_name,
163 struct GNUNET_IDENTITY_Pseudonym *pseu,
164 GNUNET_IDENTITY_Continuation cont,
169 * Disconnect from identity service.
171 * @param id identity service to disconnect
174 GNUNET_IDENTITY_disconnect (struct GNUNET_IDENTITY_Handle *id);
178 * Create a new identity with the given identifier.
180 * @param id identity service to use
181 * @param identifier desired identifier
182 * @param cb function to call with the result (will only be called once)
183 * @param cb_cls closure for cb
184 * @return handle to abort the operation
186 struct GNUNET_IDENTITY_Operation *
187 GNUNET_IDENTITY_create (struct GNUNET_IDENTITY_Handle *id,
188 const char *identifier,
189 GNUNET_IDENTITY_Callback cb,
194 * Cancel an identity operation.
196 * @param op operation to cancel
199 GNUNET_IDENITY_cancel (struct GNUNET_IDENTITY_Operation *op);
202 #if 0 /* keep Emacsens' auto-indent happy */
209 /* ifndef GNUNET_IDENTITY_SERVICE_H */
211 /* end of gnunet_identity_service.h */