2 This file is part of GNUnet.
3 Copyright (C) 2016 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.
17 * @author Martin Schanzenbach
20 * Identity provider service; implements identity provider for GNUnet
22 * @defgroup identity-provider Identity Provider service
25 #ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H
26 #define GNUNET_IDENTITY_PROVIDER_SERVICE_H
31 #if 0 /* keep Emacsens' auto-indent happy */
36 #include "gnunet_util_lib.h"
37 #include "gnunet_identity_attribute_lib.h"
40 * Version number of GNUnet Identity Provider API.
42 #define GNUNET_IDENTITY_PROVIDER_VERSION 0x00000000
45 * Handle to access the identity service.
47 struct GNUNET_IDENTITY_PROVIDER_Handle;
52 struct GNUNET_IDENTITY_PROVIDER_Token;
57 struct GNUNET_IDENTITY_PROVIDER_Ticket
62 struct GNUNET_CRYPTO_EcdsaPublicKey identity;
67 struct GNUNET_CRYPTO_EcdsaPublicKey audience;
70 * The ticket random (NBO)
76 * Handle for an operation with the identity provider service.
78 struct GNUNET_IDENTITY_PROVIDER_Operation;
82 * Connect to the identity provider service.
84 * @param cfg Configuration to contact the identity provider service.
85 * @return handle to communicate with identity provider service
87 struct GNUNET_IDENTITY_PROVIDER_Handle *
88 GNUNET_IDENTITY_PROVIDER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
91 * Continuation called to notify client about result of the
95 * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
96 * #GNUNET_NO if content was already there or not found
97 * #GNUNET_YES (or other positive value) on success
98 * @param emsg NULL on success, otherwise an error message
101 (*GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus) (void *cls,
107 * Store an attribute. If the attribute is already present,
108 * it is replaced with the new attribute.
110 * @param h handle to the identity provider
111 * @param pkey private key of the identity
112 * @param attr the attribute
113 * @param exp_interval the relative expiration interval for the attribute
114 * @param cont continuation to call when done
115 * @param cont_cls closure for @a cont
116 * @return handle to abort the request
118 struct GNUNET_IDENTITY_PROVIDER_Operation *
119 GNUNET_IDENTITY_PROVIDER_attribute_store (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
120 const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
121 const struct GNUNET_IDENTITY_ATTRIBUTE_Claim *attr,
122 const struct GNUNET_TIME_Relative *exp_interval,
123 GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cont,
128 * Process an attribute that was stored in the idp.
131 * @param identity the identity
132 * @param attr the attribute
135 (*GNUNET_IDENTITY_PROVIDER_AttributeResult) (void *cls,
136 const struct GNUNET_CRYPTO_EcdsaPublicKey *identity,
137 const struct GNUNET_IDENTITY_ATTRIBUTE_Claim *attr);
142 * List all attributes for a local identity.
143 * This MUST lock the `struct GNUNET_IDENTITY_PROVIDER_Handle`
144 * for any other calls than #GNUNET_IDENTITY_PROVIDER_get_attributes_next() and
145 * #GNUNET_IDENTITY_PROVIDER_get_attributes_stop. @a proc will be called once
146 * immediately, and then again after
147 * #GNUNET_IDENTITY_PROVIDER_get_attributes_next() is invoked.
149 * On error (disconnect), @a error_cb will be invoked.
150 * On normal completion, @a finish_cb proc will be
153 * @param h handle to the idp
154 * @param identity identity to access
155 * @param error_cb function to call on error (i.e. disconnect),
156 * the handle is afterwards invalid
157 * @param error_cb_cls closure for @a error_cb
158 * @param proc function to call on each attribute; it
159 * will be called repeatedly with a value (if available)
160 * @param proc_cls closure for @a proc
161 * @param finish_cb function to call on completion
162 * the handle is afterwards invalid
163 * @param finish_cb_cls closure for @a finish_cb
164 * @return an iterator handle to use for iteration
166 struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *
167 GNUNET_IDENTITY_PROVIDER_get_attributes_start (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
168 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
169 GNUNET_SCHEDULER_TaskCallback error_cb,
171 GNUNET_IDENTITY_PROVIDER_AttributeResult proc,
173 GNUNET_SCHEDULER_TaskCallback finish_cb,
174 void *finish_cb_cls);
178 * Calls the record processor specified in #GNUNET_IDENTITY_PROVIDER_get_attributes_start
179 * for the next record.
181 * @param it the iterator
184 GNUNET_IDENTITY_PROVIDER_get_attributes_next (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
188 * Stops iteration and releases the idp handle for further calls. Must
189 * be called on any iteration that has not yet completed prior to calling
190 * #GNUNET_IDENTITY_PROVIDER_disconnect.
192 * @param it the iterator
195 GNUNET_IDENTITY_PROVIDER_get_attributes_stop (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
199 * Method called when a token has been issued.
200 * On success returns a ticket that can be given to the audience to retrive the
204 * @param ticket the ticket
207 (*GNUNET_IDENTITY_PROVIDER_TicketCallback)(void *cls,
208 const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
211 * Issues a ticket to another identity. The identity may use
212 * GNUNET_IDENTITY_PROVIDER_ticket_consume to consume the ticket
213 * and retrieve the attributes specified in the AttributeList.
215 * @param h the identity provider to use
216 * @param iss the issuing identity
217 * @param rp the subject of the ticket (the relying party)
218 * @param attrs the attributes that the relying party is given access to
219 * @param cb the callback
220 * @param cb_cls the callback closure
221 * @return handle to abort the operation
223 struct GNUNET_IDENTITY_PROVIDER_Operation *
224 GNUNET_IDENTITY_PROVIDER_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
225 const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss,
226 const struct GNUNET_CRYPTO_EcdsaPublicKey *rp,
227 const struct GNUNET_IDENTITY_ATTRIBUTE_ClaimList *attrs,
228 GNUNET_IDENTITY_PROVIDER_TicketCallback cb,
232 * Revoked an issued ticket. The relying party will be unable to retrieve
233 * updated attributes.
235 * @param h the identity provider to use
236 * @param identity the issuing identity
237 * @param ticket the ticket to revoke
238 * @param cb the callback
239 * @param cb_cls the callback closure
240 * @return handle to abort the operation
242 struct GNUNET_IDENTITY_PROVIDER_Operation *
243 GNUNET_IDENTITY_PROVIDER_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
244 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
245 const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
246 GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cb,
252 * Consumes an issued ticket. The ticket is persisted
253 * and used to retrieve identity information from the issuer
255 * @param h the identity provider to use
256 * @param identity the identity that is the subject of the issued ticket (the audience)
257 * @param ticket the issued ticket to consume
258 * @param cb the callback to call
259 * @param cb_cls the callback closure
260 * @return handle to abort the operation
262 struct GNUNET_IDENTITY_PROVIDER_Operation *
263 GNUNET_IDENTITY_PROVIDER_ticket_consume (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
264 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
265 const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
266 GNUNET_IDENTITY_PROVIDER_AttributeResult cb,
270 * Lists all tickets that have been issued to remote
271 * identites (relying parties)
273 * @param h the identity provider to use
274 * @param identity the issuing identity
275 * @param error_cb function to call on error (i.e. disconnect),
276 * the handle is afterwards invalid
277 * @param error_cb_cls closure for @a error_cb
278 * @param proc function to call on each ticket; it
279 * will be called repeatedly with a value (if available)
280 * @param proc_cls closure for @a proc
281 * @param finish_cb function to call on completion
282 * the handle is afterwards invalid
283 * @param finish_cb_cls closure for @a finish_cb
284 * @return an iterator handle to use for iteration
286 struct GNUNET_IDENTITY_PROVIDER_TicketIterator *
287 GNUNET_IDENTITY_PROVIDER_ticket_iteration_start (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
288 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
289 GNUNET_SCHEDULER_TaskCallback error_cb,
291 GNUNET_IDENTITY_PROVIDER_TicketCallback proc,
293 GNUNET_SCHEDULER_TaskCallback finish_cb,
294 void *finish_cb_cls);
297 * Lists all tickets that have been issued to remote
298 * identites (relying parties)
300 * @param h the identity provider to use
301 * @param identity the issuing identity
302 * @param error_cb function to call on error (i.e. disconnect),
303 * the handle is afterwards invalid
304 * @param error_cb_cls closure for @a error_cb
305 * @param proc function to call on each ticket; it
306 * will be called repeatedly with a value (if available)
307 * @param proc_cls closure for @a proc
308 * @param finish_cb function to call on completion
309 * the handle is afterwards invalid
310 * @param finish_cb_cls closure for @a finish_cb
311 * @return an iterator handle to use for iteration
313 struct GNUNET_IDENTITY_PROVIDER_TicketIterator *
314 GNUNET_IDENTITY_PROVIDER_ticket_iteration_start_rp (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
315 const struct GNUNET_CRYPTO_EcdsaPublicKey *identity,
316 GNUNET_SCHEDULER_TaskCallback error_cb,
318 GNUNET_IDENTITY_PROVIDER_TicketCallback proc,
320 GNUNET_SCHEDULER_TaskCallback finish_cb,
321 void *finish_cb_cls);
324 * Calls the record processor specified in #GNUNET_IDENTITY_PROVIDER_ticket_iteration_start
325 * for the next record.
327 * @param it the iterator
330 GNUNET_IDENTITY_PROVIDER_ticket_iteration_next (struct GNUNET_IDENTITY_PROVIDER_TicketIterator *it);
333 * Stops iteration and releases the idp handle for further calls. Must
334 * be called on any iteration that has not yet completed prior to calling
335 * #GNUNET_IDENTITY_PROVIDER_disconnect.
337 * @param it the iterator
340 GNUNET_IDENTITY_PROVIDER_ticket_iteration_stop (struct GNUNET_IDENTITY_PROVIDER_TicketIterator *it);
343 * Disconnect from identity provider service.
345 * @param h identity provider service to disconnect
348 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
352 * Cancel an identity provider operation. Note that the operation MAY still
353 * be executed; this merely cancels the continuation; if the request
354 * was already transmitted, the service may still choose to complete
357 * @param op operation to cancel
360 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
362 #if 0 /* keep Emacsens' auto-indent happy */
370 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
373 /** @} */ /* end of group identity */
375 /* end of gnunet_identity_provider_service.h */