From 4fd677cec39e5621d16bc2c63926b803b31582e3 Mon Sep 17 00:00:00 2001 From: "Schanzenbach, Martin" Date: Thu, 19 Jul 2018 23:28:53 +0200 Subject: renamed identity-provider subsystem to reclaim --- src/include/gnunet_reclaim_service.h | 378 +++++++++++++++++++++++++++++++++++ 1 file changed, 378 insertions(+) create mode 100644 src/include/gnunet_reclaim_service.h (limited to 'src/include/gnunet_reclaim_service.h') diff --git a/src/include/gnunet_reclaim_service.h b/src/include/gnunet_reclaim_service.h new file mode 100644 index 000000000..7e668cd62 --- /dev/null +++ b/src/include/gnunet_reclaim_service.h @@ -0,0 +1,378 @@ +/* + This file is part of GNUnet. + Copyright (C) 2016 GNUnet e.V. + + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . +*/ + +/** + * @author Martin Schanzenbach + * + * @file + * Identity provider service; implements identity provider for GNUnet + * + * @defgroup reclaim Identity Provider service + * @{ + */ +#ifndef GNUNET_RECLAIM_SERVICE_H +#define GNUNET_RECLAIM_SERVICE_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +#include "gnunet_util_lib.h" +#include "gnunet_reclaim_attribute_lib.h" + +/** + * Version number of GNUnet Identity Provider API. + */ +#define GNUNET_RECLAIM_VERSION 0x00000000 + +/** + * Handle to access the identity service. + */ +struct GNUNET_RECLAIM_Handle; + +/** + * Handle for a token. + */ +struct GNUNET_RECLAIM_Token; + +/** + * The ticket + */ +struct GNUNET_RECLAIM_Ticket +{ + /** + * The ticket issuer + */ + struct GNUNET_CRYPTO_EcdsaPublicKey identity; + + /** + * The ticket audience + */ + struct GNUNET_CRYPTO_EcdsaPublicKey audience; + + /** + * The ticket random (NBO) + */ + uint64_t rnd; +}; + +/** + * Handle for an operation with the identity provider service. + */ +struct GNUNET_RECLAIM_Operation; + + +/** + * Connect to the identity provider service. + * + * @param cfg Configuration to contact the identity provider service. + * @return handle to communicate with identity provider service + */ +struct GNUNET_RECLAIM_Handle * +GNUNET_RECLAIM_connect (const struct GNUNET_CONFIGURATION_Handle *cfg); + +/** + * Continuation called to notify client about result of the + * operation. + * + * @param cls closure + * @param success #GNUNET_SYSERR on failure (including timeout/queue drop/failure to validate) + * #GNUNET_NO if content was already there or not found + * #GNUNET_YES (or other positive value) on success + * @param emsg NULL on success, otherwise an error message + */ +typedef void +(*GNUNET_RECLAIM_ContinuationWithStatus) (void *cls, + int32_t success, + const char *emsg); + + +/** + * Store an attribute. If the attribute is already present, + * it is replaced with the new attribute. + * + * @param h handle to the identity provider + * @param pkey private key of the identity + * @param attr the attribute + * @param exp_interval the relative expiration interval for the attribute + * @param cont continuation to call when done + * @param cont_cls closure for @a cont + * @return handle to abort the request + */ +struct GNUNET_RECLAIM_Operation * +GNUNET_RECLAIM_attribute_store (struct GNUNET_RECLAIM_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *pkey, + const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr, + const struct GNUNET_TIME_Relative *exp_interval, + GNUNET_RECLAIM_ContinuationWithStatus cont, + void *cont_cls); + + +/** + * Process an attribute that was stored in the idp. + * + * @param cls closure + * @param identity the identity + * @param attr the attribute + */ +typedef void +(*GNUNET_RECLAIM_AttributeResult) (void *cls, + const struct GNUNET_CRYPTO_EcdsaPublicKey *identity, + const struct GNUNET_RECLAIM_ATTRIBUTE_Claim *attr); + + + +/** + * List all attributes for a local identity. + * This MUST lock the `struct GNUNET_RECLAIM_Handle` + * for any other calls than #GNUNET_RECLAIM_get_attributes_next() and + * #GNUNET_RECLAIM_get_attributes_stop. @a proc will be called once + * immediately, and then again after + * #GNUNET_RECLAIM_get_attributes_next() is invoked. + * + * On error (disconnect), @a error_cb will be invoked. + * On normal completion, @a finish_cb proc will be + * invoked. + * + * @param h handle to the idp + * @param identity identity to access + * @param error_cb function to call on error (i.e. disconnect), + * the handle is afterwards invalid + * @param error_cb_cls closure for @a error_cb + * @param proc function to call on each attribute; it + * will be called repeatedly with a value (if available) + * @param proc_cls closure for @a proc + * @param finish_cb function to call on completion + * the handle is afterwards invalid + * @param finish_cb_cls closure for @a finish_cb + * @return an iterator handle to use for iteration + */ +struct GNUNET_RECLAIM_AttributeIterator * +GNUNET_RECLAIM_get_attributes_start (struct GNUNET_RECLAIM_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, + GNUNET_SCHEDULER_TaskCallback error_cb, + void *error_cb_cls, + GNUNET_RECLAIM_AttributeResult proc, + void *proc_cls, + GNUNET_SCHEDULER_TaskCallback finish_cb, + void *finish_cb_cls); + + +/** + * Calls the record processor specified in #GNUNET_RECLAIM_get_attributes_start + * for the next record. + * + * @param it the iterator + */ +void +GNUNET_RECLAIM_get_attributes_next (struct GNUNET_RECLAIM_AttributeIterator *it); + + +/** + * Stops iteration and releases the idp handle for further calls. Must + * be called on any iteration that has not yet completed prior to calling + * #GNUNET_RECLAIM_disconnect. + * + * @param it the iterator + */ +void +GNUNET_RECLAIM_get_attributes_stop (struct GNUNET_RECLAIM_AttributeIterator *it); + + +/** + * Method called when a token has been issued. + * On success returns a ticket that can be given to the audience to retrive the + * token + * + * @param cls closure + * @param ticket the ticket + */ +typedef void +(*GNUNET_RECLAIM_TicketCallback)(void *cls, + const struct GNUNET_RECLAIM_Ticket *ticket); + +/** + * Issues a ticket to another identity. The identity may use + * GNUNET_RECLAIM_ticket_consume to consume the ticket + * and retrieve the attributes specified in the AttributeList. + * + * @param h the identity provider to use + * @param iss the issuing identity + * @param rp the subject of the ticket (the relying party) + * @param attrs the attributes that the relying party is given access to + * @param cb the callback + * @param cb_cls the callback closure + * @return handle to abort the operation + */ +struct GNUNET_RECLAIM_Operation * +GNUNET_RECLAIM_ticket_issue (struct GNUNET_RECLAIM_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *iss, + const struct GNUNET_CRYPTO_EcdsaPublicKey *rp, + const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs, + GNUNET_RECLAIM_TicketCallback cb, + void *cb_cls); + +/** + * Revoked an issued ticket. The relying party will be unable to retrieve + * updated attributes. + * + * @param h the identity provider to use + * @param identity the issuing identity + * @param ticket the ticket to revoke + * @param cb the callback + * @param cb_cls the callback closure + * @return handle to abort the operation + */ +struct GNUNET_RECLAIM_Operation * +GNUNET_RECLAIM_ticket_revoke (struct GNUNET_RECLAIM_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, + const struct GNUNET_RECLAIM_Ticket *ticket, + GNUNET_RECLAIM_ContinuationWithStatus cb, + void *cb_cls); + + + +/** + * Consumes an issued ticket. The ticket is persisted + * and used to retrieve identity information from the issuer + * + * @param h the identity provider to use + * @param identity the identity that is the subject of the issued ticket (the audience) + * @param ticket the issued ticket to consume + * @param cb the callback to call + * @param cb_cls the callback closure + * @return handle to abort the operation + */ +struct GNUNET_RECLAIM_Operation * +GNUNET_RECLAIM_ticket_consume (struct GNUNET_RECLAIM_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, + const struct GNUNET_RECLAIM_Ticket *ticket, + GNUNET_RECLAIM_AttributeResult cb, + void *cb_cls); + +/** + * Lists all tickets that have been issued to remote + * identites (relying parties) + * + * @param h the identity provider to use + * @param identity the issuing identity + * @param error_cb function to call on error (i.e. disconnect), + * the handle is afterwards invalid + * @param error_cb_cls closure for @a error_cb + * @param proc function to call on each ticket; it + * will be called repeatedly with a value (if available) + * @param proc_cls closure for @a proc + * @param finish_cb function to call on completion + * the handle is afterwards invalid + * @param finish_cb_cls closure for @a finish_cb + * @return an iterator handle to use for iteration + */ +struct GNUNET_RECLAIM_TicketIterator * +GNUNET_RECLAIM_ticket_iteration_start (struct GNUNET_RECLAIM_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, + GNUNET_SCHEDULER_TaskCallback error_cb, + void *error_cb_cls, + GNUNET_RECLAIM_TicketCallback proc, + void *proc_cls, + GNUNET_SCHEDULER_TaskCallback finish_cb, + void *finish_cb_cls); + +/** + * Lists all tickets that have been issued to remote + * identites (relying parties) + * + * @param h the identity provider to use + * @param identity the issuing identity + * @param error_cb function to call on error (i.e. disconnect), + * the handle is afterwards invalid + * @param error_cb_cls closure for @a error_cb + * @param proc function to call on each ticket; it + * will be called repeatedly with a value (if available) + * @param proc_cls closure for @a proc + * @param finish_cb function to call on completion + * the handle is afterwards invalid + * @param finish_cb_cls closure for @a finish_cb + * @return an iterator handle to use for iteration + */ +struct GNUNET_RECLAIM_TicketIterator * +GNUNET_RECLAIM_ticket_iteration_start_rp (struct GNUNET_RECLAIM_Handle *h, + const struct GNUNET_CRYPTO_EcdsaPublicKey *identity, + GNUNET_SCHEDULER_TaskCallback error_cb, + void *error_cb_cls, + GNUNET_RECLAIM_TicketCallback proc, + void *proc_cls, + GNUNET_SCHEDULER_TaskCallback finish_cb, + void *finish_cb_cls); + +/** + * Calls the record processor specified in #GNUNET_RECLAIM_ticket_iteration_start + * for the next record. + * + * @param it the iterator + */ +void +GNUNET_RECLAIM_ticket_iteration_next (struct GNUNET_RECLAIM_TicketIterator *it); + +/** + * Stops iteration and releases the idp handle for further calls. Must + * be called on any iteration that has not yet completed prior to calling + * #GNUNET_RECLAIM_disconnect. + * + * @param it the iterator + */ +void +GNUNET_RECLAIM_ticket_iteration_stop (struct GNUNET_RECLAIM_TicketIterator *it); + +/** + * Disconnect from identity provider service. + * + * @param h identity provider service to disconnect + */ +void +GNUNET_RECLAIM_disconnect (struct GNUNET_RECLAIM_Handle *h); + + +/** + * Cancel an identity provider operation. Note that the operation MAY still + * be executed; this merely cancels the continuation; if the request + * was already transmitted, the service may still choose to complete + * the operation. + * + * @param op operation to cancel + */ +void +GNUNET_RECLAIM_cancel (struct GNUNET_RECLAIM_Operation *op); + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + + +/* ifndef GNUNET_RECLAIM_SERVICE_H */ +#endif + +/** @} */ /* end of group identity */ + +/* end of gnunet_reclaim_service.h */ -- cgit v1.2.3