From 79f08cc39a1d1241261534bf199933cbbb8fca4d Mon Sep 17 00:00:00 2001 From: "Schanzenbach, Martin" Date: Sun, 11 Aug 2019 19:00:30 +0200 Subject: [PATCH] formatting; comments --- src/reclaim/gnunet-service-reclaim_tickets.c | 640 ++++++++++++++----- src/reclaim/gnunet-service-reclaim_tickets.h | 139 +++- 2 files changed, 613 insertions(+), 166 deletions(-) diff --git a/src/reclaim/gnunet-service-reclaim_tickets.c b/src/reclaim/gnunet-service-reclaim_tickets.c index 645f26baf..fcfb2267d 100644 --- a/src/reclaim/gnunet-service-reclaim_tickets.c +++ b/src/reclaim/gnunet-service-reclaim_tickets.c @@ -27,8 +27,17 @@ #include #include "gnunet-service-reclaim_tickets.h" + +/** + * FIXME: the defaul ticket iteration interval should probably + * be the minimim attribute expiration. + */ #define DEFAULT_TICKET_REFRESH_INTERVAL GNUNET_TIME_UNIT_HOURS +/** + * Handle for a parallel GNS lookup job + * (Declaration further below) + */ struct ParallelLookup; @@ -59,6 +68,9 @@ struct TicketReference }; +/** + * Handle to a consume operation + */ struct RECLAIM_TICKETS_ConsumeHandle { /** @@ -117,6 +129,7 @@ struct RECLAIM_TICKETS_ConsumeHandle void *cb_cls; }; + /** * Handle for a parallel GNS lookup job */ @@ -185,6 +198,7 @@ struct TicketIssueHandle void *cb_cls; }; + /** * Ticket iterator */ @@ -297,28 +311,25 @@ struct RECLAIM_TICKETS_RevokeHandle struct TicketRecordsEntry *tickets_to_update_tail; }; + /** * Ticket expiration interval */ static struct GNUNET_TIME_Relative ticket_refresh_interval; + /* Namestore handle */ static struct GNUNET_NAMESTORE_Handle *nsh; + /* GNS handle */ static struct GNUNET_GNS_Handle *gns; + /* Handle to the statistics service */ static struct GNUNET_STATISTICS_Handle *stats; -static void -move_attrs (struct RECLAIM_TICKETS_RevokeHandle *rh); -static void -move_attrs_cont (void *cls) -{ - move_attrs ((struct RECLAIM_TICKETS_RevokeHandle *) cls); -} /** * Cleanup revoke handle @@ -353,108 +364,117 @@ cleanup_rvk (struct RECLAIM_TICKETS_RevokeHandle *rh) GNUNET_free (rh); } + +/** + * For each ticket, store new, updated attribute references + * (Implementation further below) + * + * @param cls handle to the operation + */ static void -del_attr_finished (void *cls, int32_t success, const char *emsg) +process_tickets (void *cls); + + +/** + * Finished storing updated attribute references. + * Abort on error, else continue processing tickets + * + * @param cls handle to the operation + * @param success result of namestore operation + * @param emsg (NULL on success) + */ +static void +ticket_processed (void *cls, int32_t success, const char *emsg) { struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; rvk->ns_qe = NULL; - if (GNUNET_SYSERR == success) - { - GNUNET_log (GNUNET_ERROR_TYPE_ERROR, - "Error removing attribute: %s\n", - emsg); - rvk->cb (rvk->cb_cls, GNUNET_SYSERR); - cleanup_rvk (rvk); - return; - } - rvk->move_attr = rvk->move_attr->next; - GNUNET_SCHEDULER_add_now (&move_attrs_cont, rvk); + GNUNET_SCHEDULER_add_now (&process_tickets, rvk); } + +/** + * For each ticket, store new, updated attribute references + * + * @param cls handle to the operation + */ static void -move_attr_finished (void *cls, int32_t success, const char *emsg) +process_tickets (void *cls) { struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; - char *label; - rvk->ns_qe = NULL; - if (GNUNET_SYSERR == success) + struct TicketRecordsEntry *le; + struct RevokedAttributeEntry *ae; + if (NULL == rvk->tickets_to_update_head) { - GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Error moving attribute: %s\n", emsg); + GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, + "Finished updatding tickets, success\n"); + rvk->cb (rvk->cb_cls, GNUNET_OK); + cleanup_rvk (rvk); + return; + } + le = rvk->tickets_to_update_head; + GNUNET_CONTAINER_DLL_remove (rvk->tickets_to_update_head, + rvk->tickets_to_update_tail, + le); + struct GNUNET_GNSRECORD_Data rd[le->rd_count]; + if (GNUNET_OK != GNUNET_GNSRECORD_records_deserialize (le->data_size, + le->data, + le->rd_count, + rd)) + { + GNUNET_log (GNUNET_ERROR_TYPE_ERROR, + "Unable to deserialize ticket record(s)\n"); rvk->cb (rvk->cb_cls, GNUNET_SYSERR); cleanup_rvk (rvk); return; } - label = GNUNET_STRINGS_data_to_string_alloc (&rvk->move_attr->old_id, - sizeof (uint64_t)); - GNUNET_assert (NULL != label); - GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Removing attribute %s\n", label); + for (int i = 0; i < le->rd_count; i++) + { + if (GNUNET_GNSRECORD_TYPE_RECLAIM_ATTR_REF != rd[i].record_type) + continue; + for (ae = rvk->attrs_head; NULL != ae; ae = ae->next) + { + if (0 != memcmp (rd[i].data, &ae->old_id, sizeof (uint64_t))) + continue; + rd[i].data = &ae->new_id; + } + } rvk->ns_qe = GNUNET_NAMESTORE_records_store (nsh, &rvk->identity, - label, - 0, - NULL, - &del_attr_finished, + le->label, + le->rd_count, + rd, + &ticket_processed, rvk); - GNUNET_free (label); + GNUNET_free (le->label); + GNUNET_free (le->data); + GNUNET_free (le); } +/** + * Done collecting tickets. Start processing. + * + * @param cls handle to the operation + */ static void -rvk_move_attr_cb (void *cls, - const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, - const char *label, - unsigned int rd_count, - const struct GNUNET_GNSRECORD_Data *rd) +rvk_ticket_update_finished (void *cls) { struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; - struct GNUNET_RECLAIM_ATTRIBUTE_Claim *claim; - struct GNUNET_GNSRECORD_Data new_rd; - struct RevokedAttributeEntry *le; - char *new_label; - char *attr_data; - rvk->ns_qe = NULL; - if (0 == rd_count) - { - GNUNET_log (GNUNET_ERROR_TYPE_WARNING, - "The attribute %s no longer exists!\n", - label); - le = rvk->move_attr; - rvk->move_attr = le->next; - GNUNET_CONTAINER_DLL_remove (rvk->attrs_head, rvk->attrs_tail, le); - GNUNET_free (le); - GNUNET_SCHEDULER_add_now (&move_attrs_cont, rvk); - return; - } - /** find a new place for this attribute **/ - rvk->move_attr->new_id = - GNUNET_CRYPTO_random_u64 (GNUNET_CRYPTO_QUALITY_STRONG, UINT64_MAX); - new_rd = *rd; - claim = GNUNET_RECLAIM_ATTRIBUTE_deserialize (rd->data, rd->data_size); - GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, - "Attribute to update: Name=%s, ID=%" PRIu64 "\n", - claim->name, - claim->id); - claim->id = rvk->move_attr->new_id; - new_rd.data_size = GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (claim); - attr_data = GNUNET_malloc (rd->data_size); - new_rd.data_size = GNUNET_RECLAIM_ATTRIBUTE_serialize (claim, attr_data); - new_rd.data = attr_data; - new_label = GNUNET_STRINGS_data_to_string_alloc (&rvk->move_attr->new_id, - sizeof (uint64_t)); - GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Adding attribute %s\n", new_label); - rvk->ns_qe = GNUNET_NAMESTORE_records_store (nsh, - &rvk->identity, - new_label, - 1, - &new_rd, - &move_attr_finished, - rvk); - GNUNET_free (new_label); - GNUNET_free (claim); - GNUNET_free (attr_data); + rvk->ns_it = NULL; + GNUNET_SCHEDULER_add_now (&process_tickets, rvk); } +/** + * We need to update all other tickets with the new attribute IDs. + * We first collect them all. Processing after. + * + * @param cls handle to the operation + * @param zone ticket issuer private key + * @param label ticket rnd + * @param rd_cound size of record set + * @param rd record set + */ static void rvk_ticket_update (void *cls, const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, @@ -498,106 +518,204 @@ rvk_ticket_update (void *cls, } +/** + * Error iterating namestore. Abort. + * + * @param cls handle to the operation + */ static void -process_tickets (void *cls); +rvk_ns_iter_err (void *cls) +{ + struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; + rvk->ns_it = NULL; + GNUNET_log (GNUNET_ERROR_TYPE_ERROR, + "Namestore error on revocation (id=%" PRIu64 "\n", + rvk->move_attr->old_id); + rvk->cb (rvk->cb_cls, GNUNET_SYSERR); + cleanup_rvk (rvk); +} +/** + * Error storing new attribute in namestore. Abort + * + * @param cls handle to the operation + */ static void -ticket_processed (void *cls, int32_t success, const char *emsg) +rvk_ns_err (void *cls) { struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; rvk->ns_qe = NULL; - GNUNET_SCHEDULER_add_now (&process_tickets, rvk); + GNUNET_log (GNUNET_ERROR_TYPE_ERROR, + "Namestore error on revocation (id=%" PRIu64 "\n", + rvk->move_attr->old_id); + rvk->cb (rvk->cb_cls, GNUNET_SYSERR); + cleanup_rvk (rvk); } + +/** + * We change every attribute ID of the ticket attributes we + * want to revoke. + * When we are done, we need to update any other ticket which + * included references to any of the changed attributes. + * (Implementation further below) + * + * @param rvk handle to the operation + */ static void -process_tickets (void *cls) +move_attrs (struct RECLAIM_TICKETS_RevokeHandle *rh); + + +/** + * Delayed continuation for move_attrs + * + * @param cls handle to the operation. + */ +static void +move_attrs_cont (void *cls) +{ + move_attrs ((struct RECLAIM_TICKETS_RevokeHandle *) cls); +} + + +/** + * Done deleting the old record. Abort on error. + * Else, continue updating attribute IDs. + * + * @param cls handle to the operation + * @param success result of the namestore operation + * @param emsg error message (NULL on success) + */ +static void +del_attr_finished (void *cls, int32_t success, const char *emsg) { struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; - struct TicketRecordsEntry *le; - struct RevokedAttributeEntry *ae; - if (NULL == rvk->tickets_to_update_head) - { - GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, - "Finished updatding tickets, success\n"); - rvk->cb (rvk->cb_cls, GNUNET_OK); - cleanup_rvk (rvk); - return; - } - le = rvk->tickets_to_update_head; - GNUNET_CONTAINER_DLL_remove (rvk->tickets_to_update_head, - rvk->tickets_to_update_tail, - le); - struct GNUNET_GNSRECORD_Data rd[le->rd_count]; - if (GNUNET_OK != GNUNET_GNSRECORD_records_deserialize (le->data_size, - le->data, - le->rd_count, - rd)) + rvk->ns_qe = NULL; + if (GNUNET_SYSERR == success) { GNUNET_log (GNUNET_ERROR_TYPE_ERROR, - "Unable to deserialize ticket record(s)\n"); + "Error removing attribute: %s\n", + emsg); rvk->cb (rvk->cb_cls, GNUNET_SYSERR); cleanup_rvk (rvk); return; } - for (int i = 0; i < le->rd_count; i++) - { - if (GNUNET_GNSRECORD_TYPE_RECLAIM_ATTR_REF != rd[i].record_type) - continue; - for (ae = rvk->attrs_head; NULL != ae; ae = ae->next) - { - if (0 != memcmp (rd[i].data, &ae->old_id, sizeof (uint64_t))) - continue; - rd[i].data = &ae->new_id; - } - } - rvk->ns_qe = GNUNET_NAMESTORE_records_store (nsh, - &rvk->identity, - le->label, - le->rd_count, - rd, - &ticket_processed, - rvk); - GNUNET_free (le->label); - GNUNET_free (le->data); - GNUNET_free (le); -} - -static void -rvk_ticket_update_finished (void *cls) -{ - struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; - rvk->ns_it = NULL; - GNUNET_SCHEDULER_add_now (&process_tickets, rvk); + rvk->move_attr = rvk->move_attr->next; + GNUNET_SCHEDULER_add_now (&move_attrs_cont, rvk); } +/** + * Updated an attribute ID. + * Abort on error if namestore operation failed. + * Else, we have to delete the old record. + * + * @param cls handle to the operation + * @param success result of the store operation + * @param emsg error message (NULL on success) + */ static void -rvk_ns_iter_err (void *cls) +move_attr_finished (void *cls, int32_t success, const char *emsg) { struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; - rvk->ns_it = NULL; - GNUNET_log (GNUNET_ERROR_TYPE_ERROR, - "Namestore error on revocation (id=%" PRIu64 "\n", - rvk->move_attr->old_id); - rvk->cb (rvk->cb_cls, GNUNET_SYSERR); - cleanup_rvk (rvk); + char *label; + rvk->ns_qe = NULL; + if (GNUNET_SYSERR == success) + { + GNUNET_log (GNUNET_ERROR_TYPE_ERROR, "Error moving attribute: %s\n", emsg); + rvk->cb (rvk->cb_cls, GNUNET_SYSERR); + cleanup_rvk (rvk); + return; + } + label = GNUNET_STRINGS_data_to_string_alloc (&rvk->move_attr->old_id, + sizeof (uint64_t)); + GNUNET_assert (NULL != label); + GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Removing attribute %s\n", label); + rvk->ns_qe = GNUNET_NAMESTORE_records_store (nsh, + &rvk->identity, + label, + 0, + NULL, + &del_attr_finished, + rvk); + GNUNET_free (label); } +/** + * Got the referenced attribute. Updating the ID + * + * @param cls handle to the operation + * @param zone issuer identity + * @param label attribute ID + * @param rd_count size of record set (should be 1) + * @param rd record set (the attribute) + */ static void -rvk_ns_err (void *cls) +rvk_move_attr_cb (void *cls, + const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, + const char *label, + unsigned int rd_count, + const struct GNUNET_GNSRECORD_Data *rd) { struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; + struct GNUNET_RECLAIM_ATTRIBUTE_Claim *claim; + struct GNUNET_GNSRECORD_Data new_rd; + struct RevokedAttributeEntry *le; + char *new_label; + char *attr_data; rvk->ns_qe = NULL; - GNUNET_log (GNUNET_ERROR_TYPE_ERROR, - "Namestore error on revocation (id=%" PRIu64 "\n", - rvk->move_attr->old_id); - rvk->cb (rvk->cb_cls, GNUNET_SYSERR); - cleanup_rvk (rvk); + if (0 == rd_count) + { + GNUNET_log (GNUNET_ERROR_TYPE_WARNING, + "The attribute %s no longer exists!\n", + label); + le = rvk->move_attr; + rvk->move_attr = le->next; + GNUNET_CONTAINER_DLL_remove (rvk->attrs_head, rvk->attrs_tail, le); + GNUNET_free (le); + GNUNET_SCHEDULER_add_now (&move_attrs_cont, rvk); + return; + } + /** find a new place for this attribute **/ + rvk->move_attr->new_id = + GNUNET_CRYPTO_random_u64 (GNUNET_CRYPTO_QUALITY_STRONG, UINT64_MAX); + new_rd = *rd; + claim = GNUNET_RECLAIM_ATTRIBUTE_deserialize (rd->data, rd->data_size); + GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, + "Attribute to update: Name=%s, ID=%" PRIu64 "\n", + claim->name, + claim->id); + claim->id = rvk->move_attr->new_id; + new_rd.data_size = GNUNET_RECLAIM_ATTRIBUTE_serialize_get_size (claim); + attr_data = GNUNET_malloc (rd->data_size); + new_rd.data_size = GNUNET_RECLAIM_ATTRIBUTE_serialize (claim, attr_data); + new_rd.data = attr_data; + new_label = GNUNET_STRINGS_data_to_string_alloc (&rvk->move_attr->new_id, + sizeof (uint64_t)); + GNUNET_log (GNUNET_ERROR_TYPE_DEBUG, "Adding attribute %s\n", new_label); + rvk->ns_qe = GNUNET_NAMESTORE_records_store (nsh, + &rvk->identity, + new_label, + 1, + &new_rd, + &move_attr_finished, + rvk); + GNUNET_free (new_label); + GNUNET_free (claim); + GNUNET_free (attr_data); } +/** + * We change every attribute ID of the ticket attributes we + * want to revoke. + * When we are done, we need to update any other ticket which + * included references to any of the changed attributes. + * + * @param rvk handle to the operation + */ static void move_attrs (struct RECLAIM_TICKETS_RevokeHandle *rvk) { @@ -632,6 +750,17 @@ move_attrs (struct RECLAIM_TICKETS_RevokeHandle *rvk) } +/** + * Finished deleting ticket and attribute references. + * Abort on failure. + * Else, we start changing every attribute ID in the + * found attribute references so that access is no longer + * possible. + * + * @param cls handle to the operation + * @param success Namestore operation return value + * @param emsg error message (NULL on success) + */ static void remove_ticket_cont (void *cls, int32_t success, const char *emsg) { @@ -658,6 +787,16 @@ remove_ticket_cont (void *cls, int32_t success, const char *emsg) } +/** + * We found the attribute references. + * Store them for later and remove the record set. + * + * @param cls handle to the operation + * @param zone the issuer key + * @param label ticket rnd + * @param rd_cound size of record set + * @param rd record set + */ static void revoke_attrs_cb (void *cls, const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, @@ -669,6 +808,10 @@ revoke_attrs_cb (void *cls, struct RECLAIM_TICKETS_RevokeHandle *rvk = cls; struct RevokedAttributeEntry *le; rvk->ns_qe = NULL; + /** + * Temporarily store attribute references. + * We need it later. + */ for (int i = 0; i < rd_count; i++) { if (GNUNET_GNSRECORD_TYPE_RECLAIM_ATTR_REF != rd[i].record_type) @@ -679,7 +822,7 @@ revoke_attrs_cb (void *cls, rvk->ticket_attrs++; } - /** Now, remove ticket **/ + /** Remove attribute references **/ rvk->ns_qe = GNUNET_NAMESTORE_records_store (nsh, &rvk->identity, label, @@ -690,6 +833,11 @@ revoke_attrs_cb (void *cls, } +/** + * Failed to query namestore. Abort operation + * + * @param cls handle to the operation + */ static void rvk_attrs_err_cb (void *cls) { @@ -699,6 +847,17 @@ rvk_attrs_err_cb (void *cls) } +/** + * Revoke a ticket. + * We start by looking up attribute references in order + * to change attribute IDs. + * + * @param ticket ticket to revoke + * @param identity private key of issuer + * @param cb revocation status callback + * @param cb_cls callback closure + * @return handle to the operation + */ struct RECLAIM_TICKETS_RevokeHandle * RECLAIM_TICKETS_revoke (const struct GNUNET_RECLAIM_Ticket *ticket, const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, @@ -729,17 +888,26 @@ RECLAIM_TICKETS_revoke (const struct GNUNET_RECLAIM_Ticket *ticket, } +/** + * Cancel a revocation. + * + * @param rh handle to the operation + */ void RECLAIM_TICKETS_revoke_cancel (struct RECLAIM_TICKETS_RevokeHandle *rh) { + GNUNET_assert (NULL != rh); cleanup_rvk (rh); } + + /******************************* * Ticket consume *******************************/ /** * Cleanup ticket consume handle + * * @param cth the handle to clean up */ static void @@ -767,6 +935,13 @@ cleanup_cth (struct RECLAIM_TICKETS_ConsumeHandle *cth) } +/** + * We found an attribute record. + * + * @param cls handle to the operation + * @param rd_cound size of record set + * @param rd record set + */ static void process_parallel_lookup_result (void *cls, uint32_t rd_count, @@ -795,7 +970,7 @@ process_parallel_lookup_result (void *cls, GNUNET_free (parallel_lookup); if (1 != rd_count) - GNUNET_break (0); // TODO + GNUNET_break (0); // FIXME: We should never find this. if (rd->record_type == GNUNET_GNSRECORD_TYPE_RECLAIM_ATTR) { attr_le = GNUNET_new (struct GNUNET_RECLAIM_ATTRIBUTE_ClaimListEntry); @@ -805,15 +980,21 @@ process_parallel_lookup_result (void *cls, cth->attrs->list_tail, attr_le); } + if (NULL != cth->parallel_lookups_head) return; // Wait for more - /* Else we are done */ + /* Else we are done */ cth->cb (cth->cb_cls, &cth->ticket.identity, cth->attrs, GNUNET_OK, NULL); cleanup_cth (cth); } +/** + * Cancel the lookups for attribute records + * + * @param cls handle to the operation + */ static void abort_parallel_lookups (void *cls) { @@ -837,6 +1018,15 @@ abort_parallel_lookups (void *cls) } +/** + * GNS result with attribute references. + * For each result, we start a (parallel) lookup of the actual + * attribute record under the referenced label. + * + * @param cls handle to the operation + * @param rd_cound size of the record set + * @param rd record set + */ static void lookup_authz_cb (void *cls, uint32_t rd_count, @@ -881,6 +1071,10 @@ lookup_authz_cb (void *cls, cth->parallel_lookups_tail, parallel_lookup); } + /** + * We started lookups. Add a timeout task. + * FIXME: Really needed here? + */ if (NULL != cth->parallel_lookups_head) { cth->kill_task = GNUNET_SCHEDULER_add_delayed ( @@ -889,11 +1083,25 @@ lookup_authz_cb (void *cls, cth); return; } + /** + * No references found, return empty attribute list + */ cth->cb (cth->cb_cls, &cth->ticket.identity, cth->attrs, GNUNET_OK, NULL); cleanup_cth (cth); } +/** + * Consume a ticket. + * We first looking attribute references under the label + * ticket.rnd in GNS. + * + * @param id the audience of the ticket + * @param ticket the ticket to consume + * @param cb callback to call with attributes of ticket + * @param cb_cls callback closure + * @return handle to the operation + */ struct RECLAIM_TICKETS_ConsumeHandle * RECLAIM_TICKETS_consume (const struct GNUNET_CRYPTO_EcdsaPrivateKey *id, const struct GNUNET_RECLAIM_Ticket *ticket, @@ -928,6 +1136,12 @@ RECLAIM_TICKETS_consume (const struct GNUNET_CRYPTO_EcdsaPrivateKey *id, return cth; } + +/** + * Cancel a consume operation + * + * @param cth the operation to cancel + */ void RECLAIM_TICKETS_consume_cancel (struct RECLAIM_TICKETS_ConsumeHandle *cth) { @@ -953,6 +1167,14 @@ cleanup_issue_handle (struct TicketIssueHandle *handle) } +/** + * Store finished, abort on error. + * Else, return new ticket to caller. + * + * @param cls handle to the operation + * @param success store operation result + * @param emsg error message (or NULL on success) + */ static void store_ticket_issue_cont (void *cls, int32_t success, const char *emsg) { @@ -972,6 +1194,13 @@ store_ticket_issue_cont (void *cls, int32_t success, const char *emsg) } +/** + * Issue a new ticket. + * We store references to attribute record labels and the ticket itself + * under the label base64(ticket.rnd). + * + * @param ih handle to the operation containing relevant metadata + */ static void issue_ticket (struct TicketIssueHandle *ih) { @@ -991,7 +1220,10 @@ issue_ticket (struct TicketIssueHandle *ih) { attrs_record[i].data = &le->claim->id; attrs_record[i].data_size = sizeof (le->claim->id); - //FIXME: Should this be the attribute expiration time or ticket refresh intv + /** + * FIXME: Should this be the attribute expiration time or ticket + * refresh interval? Probably min(attrs.expiration) + */ attrs_record[i].expiration_time = ticket_refresh_interval.rel_value_us; attrs_record[i].record_type = GNUNET_GNSRECORD_TYPE_RECLAIM_ATTR_REF; attrs_record[i].flags = GNUNET_GNSRECORD_RF_RELATIVE_EXPIRATION; @@ -1022,6 +1254,12 @@ issue_ticket (struct TicketIssueHandle *ih) * Ticket iteration (finding a specific ticket) *************************************************/ + +/** + * Namestore error on issue. Abort. + * + * @param cls handle to the operation + */ static void filter_tickets_error_cb (void *cls) { @@ -1034,6 +1272,19 @@ filter_tickets_error_cb (void *cls) cleanup_issue_handle (tih); } + +/** + * Iterator over records. + * Check if any previously issued ticket already + * matches what we need to prevent duplicates and + * improve resolution synergy. + * + * @param cls handle to the operation + * @param zone issuer identity + * @param label ticket rnd + * @param rd_count size of record set + * @param rd record set + */ static void filter_tickets_cb (void *cls, const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, @@ -1087,6 +1338,10 @@ filter_tickets_cb (void *cls, } } + /** + * If we found a matching ticket, return that to the caller and + * we are done. + */ if (attr_cnt == found_attrs_cnt && NULL != ticket) { GNUNET_NAMESTORE_zone_iteration_stop (tih->ns_it); @@ -1095,11 +1350,18 @@ filter_tickets_cb (void *cls, return; } - // ticket not found in current record + // ticket not found in current record, checking next record set GNUNET_NAMESTORE_zone_iterator_next (tih->ns_it, 1); } +/** + * Done iterating over tickets and we apparently did + * not find an existing, matching ticket. + * Continue by issuing a new ticket. + * + * @param cls handle to the operation + */ static void filter_tickets_finished_cb (void *cls) { @@ -1110,6 +1372,18 @@ filter_tickets_finished_cb (void *cls) issue_ticket (tih); } + +/** + * Issue a new reclaim ticket, thereby authorizing + * the audience to access the set of provided attributes. + * + * @param identity the issuer + * @param attrs the attributes to share + * @param audience the audience to share the attributes with + * @param cb the callback to call with the ticket result + * @param cb_cls the callback closure + * FIXME: Return handle?? + */ void RECLAIM_TICKETS_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs, @@ -1125,7 +1399,7 @@ RECLAIM_TICKETS_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, tih->identity = *identity; tih->ticket.audience = *audience; - // check whether the ticket has already been issued + // First check whether the ticket has already been issued tih->ns_it = GNUNET_NAMESTORE_zone_iteration_start (nsh, &tih->identity, @@ -1137,10 +1411,16 @@ RECLAIM_TICKETS_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, tih); } + /************************************ * Ticket iteration ************************************/ +/** + * Cleanup ticket iterator + * + * @param iter handle to the iteration + */ static void cleanup_iter (struct RECLAIM_TICKETS_Iterator *iter) { @@ -1150,6 +1430,17 @@ cleanup_iter (struct RECLAIM_TICKETS_Iterator *iter) } +/** + * Return each record of type @GNUNET_GNSRECORD_TYPE_RECLAIM_TICKET + * to the caller and proceed with the iteration. + * FIXME: Should we _not_ proceed automatically here? + * + * @param cls handle to the iteration + * @param zone the ticket issuer + * @param label the ticket rnd + * @param rd_count number of records in record set + * @param rd record set containing a ticket + */ static void collect_tickets_cb (void *cls, const struct GNUNET_CRYPTO_EcdsaPrivateKey *zone, @@ -1170,6 +1461,11 @@ collect_tickets_cb (void *cls, } +/** + * Signal ticket iteration has finished + * + * @param cls handle to the iteration + */ static void collect_tickets_finished_cb (void *cls) { @@ -1180,6 +1476,11 @@ collect_tickets_finished_cb (void *cls) } +/** + * Cancel ticket iteration on namestore error + * + * @param cls the iteration handle + */ static void collect_tickets_error_cb (void *cls) { @@ -1190,6 +1491,11 @@ collect_tickets_error_cb (void *cls) } +/** + * Continue ticket iteration + * + * @param iter the iteration to continue + */ void RECLAIM_TICKETS_iteration_next (struct RECLAIM_TICKETS_Iterator *iter) { @@ -1197,6 +1503,11 @@ RECLAIM_TICKETS_iteration_next (struct RECLAIM_TICKETS_Iterator *iter) } +/** + * Stop a running ticket iteration + * + * @param iter iteration to cancel + */ void RECLAIM_TICKETS_iteration_stop (struct RECLAIM_TICKETS_Iterator *iter) { @@ -1205,6 +1516,14 @@ RECLAIM_TICKETS_iteration_stop (struct RECLAIM_TICKETS_Iterator *iter) } +/** + * Iterate over all tickets issued by an identity + * + * @param identity the issuing identity + * @param cb ticket callback function + * @param cb_cls callback closure + * @return a handle to the iteration + */ struct RECLAIM_TICKETS_Iterator * RECLAIM_TICKETS_iteration_start ( const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, @@ -1229,6 +1548,12 @@ RECLAIM_TICKETS_iteration_start ( } +/** + * Initialize tickets component + * + * @param c the configuration + * @return GNUNET_SYSERR on error + */ int RECLAIM_TICKETS_init (const struct GNUNET_CONFIGURATION_Handle *c) { @@ -1266,6 +1591,11 @@ RECLAIM_TICKETS_init (const struct GNUNET_CONFIGURATION_Handle *c) return GNUNET_OK; } + +/** + * Close handles and clean up. + * FIXME: cancel all pending operations (gns, ns etc) + */ void RECLAIM_TICKETS_deinit (void) { diff --git a/src/reclaim/gnunet-service-reclaim_tickets.h b/src/reclaim/gnunet-service-reclaim_tickets.h index 6e69355fa..05f834b1e 100644 --- a/src/reclaim/gnunet-service-reclaim_tickets.h +++ b/src/reclaim/gnunet-service-reclaim_tickets.h @@ -42,11 +42,27 @@ #include "gnunet_statistics_service.h" #include "reclaim.h" +/** + * Ticket iterator + */ struct RECLAIM_TICKETS_Iterator; + + +/** + * Handle to a consume operation + */ struct RECLAIM_TICKETS_ConsumeHandle; + + +/** + * Ticket revocation request handle + */ struct RECLAIM_TICKETS_RevokeHandle; +/** + * List of tickets + */ struct TicketRecordsEntry { /** @@ -88,7 +104,8 @@ struct TicketRecordsEntry * @param ticket the ticket */ typedef void (*RECLAIM_TICKETS_TicketIter) ( - void *cls, struct GNUNET_RECLAIM_Ticket *ticket); + void *cls, + struct GNUNET_RECLAIM_Ticket *ticket); /** @@ -101,59 +118,159 @@ typedef void (*RECLAIM_TICKETS_TicketIter) ( * @param emsg NULL on success, otherwise an error message */ typedef void (*RECLAIM_TICKETS_TicketResult) ( - void *cls, struct GNUNET_RECLAIM_Ticket *ticket, int32_t success, - const char *emsg); + void *cls, + struct GNUNET_RECLAIM_Ticket *ticket, + int32_t success, + const char *emsg); +/** + * Consume callback. + * + * @param cls closure + * @param identity the issuer of the ticket/attributes + * @param l attribute list retrieved through ticket + * @param success GNUNET_OK on success + * @param emsg error message (NULL on success) + */ typedef void (*RECLAIM_TICKETS_ConsumeCallback) ( - void *cls, const struct GNUNET_CRYPTO_EcdsaPublicKey *identity, - const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *l, int32_t success, - const char *emsg); + void *cls, + const struct GNUNET_CRYPTO_EcdsaPublicKey *identity, + const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *l, + int32_t success, + const char *emsg); +/** + * Revocation callback. + * + * @param cls closure + * @param success GNUNET_OK on success + */ typedef void (*RECLAIM_TICKETS_RevokeCallback) (void *cls, int32_t success); + +/** + * Revoke a ticket. + * We start by looking up attribute references in order + * to change attribute IDs. + * + * @param ticket ticket to revoke + * @param identity private key of issuer + * @param cb revocation status callback + * @param cb_cls callback closure + * @return handle to the operation + */ struct RECLAIM_TICKETS_RevokeHandle * RECLAIM_TICKETS_revoke (const struct GNUNET_RECLAIM_Ticket *ticket, const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, - RECLAIM_TICKETS_RevokeCallback cb, void *cb_cls); + RECLAIM_TICKETS_RevokeCallback cb, + void *cb_cls); +/** + * Cancel a revocation. + * + * @param rh handle to the operation + */ void RECLAIM_TICKETS_revoke_cancel (struct RECLAIM_TICKETS_RevokeHandle *rh); +/** + * Consume a ticket. + * We first looking attribute references under the label + * ticket.rnd in GNS. + * + * @param id the audience of the ticket + * @param ticket the ticket to consume + * @param cb callback to call with attributes of ticket + * @param cb_cls callback closure + * @return handle to the operation + */ struct RECLAIM_TICKETS_ConsumeHandle * RECLAIM_TICKETS_consume (const struct GNUNET_CRYPTO_EcdsaPrivateKey *id, const struct GNUNET_RECLAIM_Ticket *ticket, - RECLAIM_TICKETS_ConsumeCallback cb, void *cb_cls); + RECLAIM_TICKETS_ConsumeCallback cb, + void *cb_cls); + +/** + * Cancel a consume operation + * + * @param cth the operation to cancel + */ void RECLAIM_TICKETS_consume_cancel (struct RECLAIM_TICKETS_ConsumeHandle *cth); + +/** + * Issue a new reclaim ticket, thereby authorizing + * the audience to access the set of provided attributes. + * + * @param identity the issuer + * @param attrs the attributes to share + * @param audience the audience to share the attributes with + * @param cb the callback to call with the ticket result + * @param cb_cls the callback closure + * FIXME: Return handle?? + */ void RECLAIM_TICKETS_issue (const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, const struct GNUNET_RECLAIM_ATTRIBUTE_ClaimList *attrs, const struct GNUNET_CRYPTO_EcdsaPublicKey *audience, - RECLAIM_TICKETS_TicketResult cb, void *cb_cls); + RECLAIM_TICKETS_TicketResult cb, + void *cb_cls); + +/** + * Continue ticket iteration + * + * @param iter the iteration to continue + */ void RECLAIM_TICKETS_iteration_next (struct RECLAIM_TICKETS_Iterator *iter); +/** + * Stop a running ticket iteration + * + * @param iter iteration to cancel + */ void RECLAIM_TICKETS_iteration_stop (struct RECLAIM_TICKETS_Iterator *iter); +/** + * Iterate over all tickets issued by an identity + * + * @param identity the issuing identity + * @param cb ticket callback function + * @param cb_cls callback closure + * @return a handle to the iteration + */ struct RECLAIM_TICKETS_Iterator * RECLAIM_TICKETS_iteration_start ( - const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, - RECLAIM_TICKETS_TicketIter cb, void *cb_cls); + const struct GNUNET_CRYPTO_EcdsaPrivateKey *identity, + RECLAIM_TICKETS_TicketIter cb, + void *cb_cls); +/** + * Initialize tickets component + * + * @param c the configuration + * @return GNUNET_SYSERR on error + */ int RECLAIM_TICKETS_init (const struct GNUNET_CONFIGURATION_Handle *c); + +/** + * Close handles and clean up. + * FIXME: cancel all pending operations (gns, ns etc) + */ void RECLAIM_TICKETS_deinit (void); + #endif -- 2.25.1