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
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Martin Schanzenbach
25 * Identity provider service; implements identity provider for GNUnet
27 * @defgroup identity-provider Identity Provider service
30 #ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H
31 #define GNUNET_IDENTITY_PROVIDER_SERVICE_H
36 #if 0 /* keep Emacsens' auto-indent happy */
41 #include "gnunet_util_lib.h"
45 * Version number of GNUnet Identity Provider API.
47 #define GNUNET_IDENTITY_PROVIDER_VERSION 0x00000000
50 * Handle to access the identity service.
52 struct GNUNET_IDENTITY_PROVIDER_Handle;
57 struct GNUNET_IDENTITY_PROVIDER_Token;
60 * Handle for a ticket DEPRECATED
62 struct GNUNET_IDENTITY_PROVIDER_Ticket;
67 struct GNUNET_IDENTITY_PROVIDER_Ticket2
72 struct GNUNET_CRYPTO_EcdsaPublicKey identity;
77 struct GNUNET_CRYPTO_EcdsaPublicKey audience;
80 * The ticket random (NBO)
86 * Handle for an operation with the identity provider service.
88 struct GNUNET_IDENTITY_PROVIDER_Operation;
91 * Flags that can be set for an attribute.
93 enum GNUNET_IDENTITY_PROVIDER_AttributeType
99 GNUNET_IDENTITY_PROVIDER_AT_NULL = 0,
104 GNUNET_IDENTITY_PROVIDER_AT_STRING = 1,
113 struct GNUNET_IDENTITY_PROVIDER_Attribute
119 uint32_t attribute_type;
122 * Number of bytes in @e data.
127 * The name of the attribute. Note "name" must never be individually
133 * Binary value stored as attribute value. Note: "data" must never
134 * be individually 'malloc'ed, but instead always points into some
135 * existing data area.
141 struct GNUNET_IDENTITY_PROVIDER_AttributeList
146 struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *list_head;
151 struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *list_tail;
154 struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry
159 struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *prev;
164 struct GNUNET_IDENTITY_PROVIDER_AttributeListEntry *next;
169 struct GNUNET_IDENTITY_PROVIDER_Attribute *attribute;
173 * Method called when a token has been exchanged for a ticket.
174 * On success returns a token
177 * @param token the token
180 (*GNUNET_IDENTITY_PROVIDER_ExchangeCallback)(void *cls,
181 const struct GNUNET_IDENTITY_PROVIDER_Token *token,
182 uint64_t ticket_nonce);
185 * Method called when a token has been issued.
186 * On success returns a ticket that can be given to the audience to retrive the
190 * @param grant the label in GNS pointing to the token
191 * @param ticket the ticket
192 * @param token the issued token
193 * @param name name assigned by the user for this ego,
194 * NULL if the user just deleted the ego and it
195 * must thus no longer be used
198 (*GNUNET_IDENTITY_PROVIDER_IssueCallback)(void *cls,
200 const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
201 const struct GNUNET_IDENTITY_PROVIDER_Token *token);
205 * Connect to the identity provider service.
207 * @param cfg Configuration to contact the identity provider service.
208 * @return handle to communicate with identity provider service
210 struct GNUNET_IDENTITY_PROVIDER_Handle *
211 GNUNET_IDENTITY_PROVIDER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg);
214 * Continuation called to notify client about result of the
218 * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate)
219 * #GNUNET_NO if content was already there or not found
220 * #GNUNET_YES (or other positive value) on success
221 * @param emsg NULL on success, otherwise an error message
224 (*GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus) (void *cls,
230 * Store an attribute. If the attribute is already present,
231 * it is replaced with the new attribute.
233 * @param h handle to the identity provider
234 * @param pkey private key of the identity
235 * @param attr the attribute
236 * @param cont continuation to call when done
237 * @param cont_cls closure for @a cont
238 * @return handle to abort the request
240 struct GNUNET_IDENTITY_PROVIDER_Operation *
241 GNUNET_IDENTITY_PROVIDER_attribute_store (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
242 const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey,
243 const struct GNUNET_IDENTITY_PROVIDER_Attribute *attr,
244 GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cont,
249 * Create a new attribute.
251 * @param name the attribute name
252 * @param type the attribute type
253 * @param data the attribute value
254 * @param data_size the attribute value size
255 * @return the new attribute
257 struct GNUNET_IDENTITY_PROVIDER_Attribute *
258 GNUNET_IDENTITY_PROVIDER_attribute_new (const char* attr_name,
264 * Process an attribute that was stored in the idp.
267 * @param attr the attribute
270 (*GNUNET_IDENTITY_PROVIDER_AttributeResult) (void *cls,
271 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
272 const struct GNUNET_IDENTITY_PROVIDER_Attribute *attr);
277 * List all attributes for a local identity.
278 * This MUST lock the `struct GNUNET_IDENTITY_PROVIDER_Handle`
279 * for any other calls than #GNUNET_IDENTITY_PROVIDER_get_attributes_next() and
280 * #GNUNET_IDENTITY_PROVIDER_get_attributes_stop. @a proc will be called once
281 * immediately, and then again after
282 * #GNUNET_IDENTITY_PROVIDER_get_attributes_next() is invoked.
284 * On error (disconnect), @a error_cb will be invoked.
285 * On normal completion, @a finish_cb proc will be
288 * @param h handle to the idp
289 * @param identity identity to access
290 * @param error_cb function to call on error (i.e. disconnect),
291 * the handle is afterwards invalid
292 * @param error_cb_cls closure for @a error_cb
293 * @param proc function to call on each attribute; it
294 * will be called repeatedly with a value (if available)
295 * @param proc_cls closure for @a proc
296 * @param finish_cb function to call on completion
297 * the handle is afterwards invalid
298 * @param finish_cb_cls closure for @a finish_cb
299 * @return an iterator handle to use for iteration
301 struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *
302 GNUNET_IDENTITY_PROVIDER_get_attributes_start (struct GNUNET_IDENTITY_PROVIDER_Handle *h,
303 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
304 GNUNET_SCHEDULER_TaskCallback error_cb,
306 GNUNET_IDENTITY_PROVIDER_AttributeResult proc,
308 GNUNET_SCHEDULER_TaskCallback finish_cb,
309 void *finish_cb_cls);
313 * Calls the record processor specified in #GNUNET_IDENTITY_PROVIDER_get_attributes_start
314 * for the next record.
316 * @param it the iterator
319 GNUNET_IDENTITY_PROVIDER_get_attributes_next (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
323 * Stops iteration and releases the idp handle for further calls. Must
324 * be called on any iteration that has not yet completed prior to calling
325 * #GNUNET_IDENTITY_PROVIDER_disconnect.
327 * @param it the iterator
330 GNUNET_IDENTITY_PROVIDER_get_attributes_stop (struct GNUNET_IDENTITY_PROVIDER_AttributeIterator *it);
334 * Method called when a token has been issued.
335 * On success returns a ticket that can be given to the audience to retrive the
339 * @param grant the label in GNS pointing to the token
340 * @param ticket the ticket
341 * @param token the issued token
342 * @param name name assigned by the user for this ego,
343 * NULL if the user just deleted the ego and it
344 * must thus no longer be used
347 (*GNUNET_IDENTITY_PROVIDER_TicketCallback)(void *cls,
348 const struct GNUNET_IDENTITY_PROVIDER_Ticket2 *ticket);
352 * Issues a ticket to another identity. The identity may use
353 * @GNUNET_IDENTITY_PROVIDER_authorization_ticket_consume to consume the ticket
354 * and retrieve the attributes specified in the AttributeList.
356 * @param id the identity provider to use
357 * @param iss the issuing identity
358 * @param rp the subject of the ticket (the relying party)
359 * @param attr the attributes that the relying party is given access to
360 * @param cb the callback
361 * @param cb_cls the callback closure
362 * @return handle to abort the operation
364 struct GNUNET_IDENTITY_PROVIDER_Operation *
365 GNUNET_IDENTITY_PROVIDER_idp_ticket_issue (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
366 const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss,
367 const struct GNUNET_CRYPTO_EcdsaPublicKey *rp,
368 const struct GNUNET_IDENTITY_PROVIDER_AttributeList *attrs,
369 GNUNET_IDENTITY_PROVIDER_TicketCallback cb,
373 * Revoked an issued ticket. The relying party will be unable to retrieve
374 * updated attributes.
376 * @param id the identity provider to use
377 * @param identity the issuing identity
378 * @param ticket the ticket to revoke
379 * @param cb the callback
380 * @param cb_cls the callback closure
381 * @return handle to abort the operation
383 struct GNUNET_IDENTITY_PROVIDER_Operation *
384 GNUNET_IDENTITY_PROVIDER_idp_ticket_revoke (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
385 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
386 const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
387 GNUNET_IDENTITY_PROVIDER_ContinuationWithStatus cb,
393 * Consumes an issued ticket. The ticket is persisted
394 * and used to retrieve identity information from the issuer
396 * @param id the identity provider to use
397 * @param identity the identity that is the subject of the issued ticket (the relying party)
398 * @param ticket the issued ticket to consume
399 * @param cb the callback to call
400 * @param cb_cls the callback closure
401 * @return handle to abort the operation
403 struct GNUNET_IDENTITY_PROVIDER_Operation *
404 GNUNET_IDENTITY_PROVIDER_rp_ticket_consume (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
405 const struct GNUNET_CRYPTO_EcdsaPrivateKey * identity,
406 const struct GNUNET_IDENTITY_PROVIDER_Ticket2 *ticket,
407 GNUNET_IDENTITY_PROVIDER_AttributeResult cb,
411 * Lists all tickets that have been issued to remote
412 * identites (relying parties)
414 * @param id the identity provider to use
415 * @param identity the issuing identity
416 * @param cb the callback to use
417 * @param cb_cls the callback closure
418 * @return handle to abort the operation
420 struct GNUNET_IDENTITY_PROVIDER_Operation *
421 GNUNET_IDENTITY_PROVIDER_idp_tickets_list (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
422 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
423 GNUNET_IDENTITY_PROVIDER_TicketCallback *cb,
427 * Lists all attributes that are shared with this identity
430 * @param id identity provider service to use
431 * @param identity the identity (relying party)
432 * @param cb the result callback
433 * @param cb_cls the result callback closure
434 * @return handle to abort the operation
436 struct GNUNET_IDENTITY_PROVIDER_Operation *
437 GNUNET_IDENTITY_PROVIDER_rp_attributes_list (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
438 const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity,
439 GNUNET_IDENTITY_PROVIDER_AttributeResult *cb,
442 /** TODO remove DEPRECATED
443 * Issue a token for a specific audience.
445 * @param id identity provider service to use
446 * @param iss issuer (identity)
447 * @param aud audience (identity)
448 * @param scope the identity attributes requested, comman separated
449 * @param expiration the token expiration
450 * @param nonce the nonce that will be included in token and ticket
451 * @param cb callback to call with result
452 * @param cb_cls closure
453 * @return handle to abort the operation
455 struct GNUNET_IDENTITY_PROVIDER_Operation *
456 GNUNET_IDENTITY_PROVIDER_issue_token (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
457 const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss_key,
458 const struct GNUNET_CRYPTO_EcdsaPublicKey *aud_key,
461 struct GNUNET_TIME_Absolute expiration,
463 GNUNET_IDENTITY_PROVIDER_IssueCallback cb,
467 /** TODO remove DEPRECATED
468 * Exchange a ticket for a token. Intended to be used by audience that
471 * @param id identity provider service to use
472 * @param ticket the ticket to exchange
473 * @param aud_privkey the audience of the ticket
474 * @param cont function to call once the operation finished
475 * @param cont_cls closure for @a cont
476 * @return handle to abort the operation
478 struct GNUNET_IDENTITY_PROVIDER_Operation *
479 GNUNET_IDENTITY_PROVIDER_exchange_ticket (struct GNUNET_IDENTITY_PROVIDER_Handle *id,
480 const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket,
481 const struct GNUNET_CRYPTO_EcdsaPrivateKey *aud_privkey,
482 GNUNET_IDENTITY_PROVIDER_ExchangeCallback cont,
487 * Disconnect from identity provider service.
489 * @param h identity provider service to disconnect
492 GNUNET_IDENTITY_PROVIDER_disconnect (struct GNUNET_IDENTITY_PROVIDER_Handle *h);
496 * Cancel an identity provider operation. Note that the operation MAY still
497 * be executed; this merely cancels the continuation; if the request
498 * was already transmitted, the service may still choose to complete
501 * @param op operation to cancel
504 GNUNET_IDENTITY_PROVIDER_cancel (struct GNUNET_IDENTITY_PROVIDER_Operation *op);
514 * @param token the token
517 GNUNET_IDENTITY_PROVIDER_token_destroy(struct GNUNET_IDENTITY_PROVIDER_Token *token);
520 * Returns string representation of token. A JSON-Web-Token.
522 * @param token the token
523 * @return The JWT (must be freed)
526 GNUNET_IDENTITY_PROVIDER_token_to_string (const struct GNUNET_IDENTITY_PROVIDER_Token *token);
529 * Returns string representation of ticket. Base64-Encoded
531 * @param ticket the ticket
532 * @return the Base64-Encoded ticket
535 GNUNET_IDENTITY_PROVIDER_ticket_to_string (const struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
538 * Created a ticket from a string (Base64 encoded ticket)
540 * @param input Base64 encoded ticket
541 * @param ticket pointer where the ticket is stored
545 GNUNET_IDENTITY_PROVIDER_string_to_ticket (const char* input,
546 struct GNUNET_IDENTITY_PROVIDER_Ticket **ticket);
551 * @param ticket the ticket to destroy
554 GNUNET_IDENTITY_PROVIDER_ticket_destroy(struct GNUNET_IDENTITY_PROVIDER_Ticket *ticket);
556 #if 0 /* keep Emacsens' auto-indent happy */
564 /* ifndef GNUNET_IDENTITY_PROVIDER_SERVICE_H */
567 /** @} */ /* end of group identity */
569 /* end of gnunet_identity_provider_service.h */