From f3ed6ea694e83e45d257fb64b5ae23e73bc81465 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 2 Aug 2021 15:58:53 +0200 Subject: misc doxygen fixes --- src/include/anastasis.h | 6 +- src/include/anastasis_authorization_lib.h | 6 +- src/include/anastasis_json.h | 410 ------------------------------ src/include/anastasis_redux.h | 12 +- src/include/anastasis_service.h | 1 - src/include/anastasis_testing_lib.h | 40 +-- src/include/platform.h | 2 +- 7 files changed, 34 insertions(+), 443 deletions(-) delete mode 100644 src/include/anastasis_json.h (limited to 'src/include') diff --git a/src/include/anastasis.h b/src/include/anastasis.h index 1591106..d253868 100644 --- a/src/include/anastasis.h +++ b/src/include/anastasis.h @@ -613,6 +613,7 @@ typedef void * * @param ctx the CURL context used to connect to the backend * @param user_id user identifier derived from user data and backend salt + * @param provider_url base URL of the provider to upload to * @param type defines the type of the challenge (secure question, sms, email) * @param instructions depending on @a type! usually only for security question/answer! * @param mime_type format of the challenge @@ -648,6 +649,7 @@ ANASTASIS_truth_upload ( * * @param ctx the CURL context used to connect to the backend * @param user_id user identifier derived from user data and backend salt + * @param provider_url base URL of the provider to upload to * @param type defines the type of the challenge (secure question, sms, email) * @param instructions depending on @a type! usually only for security question/answer! * @param mime_type format of the challenge @@ -946,11 +948,9 @@ struct ANASTASIS_ProviderDetails * @param providers array of providers with URLs to upload the policies to * @param pss_length length of the @a providers array * @param policies list of policies which are included in this recovery document - * @param policies_length length of the @a policies array + * @param policies_len length of the @a policies array * @param payment_years_requested for how many years would the client like the service to store the truth? * @param pay_timeout how long to wait for payment - * @param spc payment callback is opened to pay the upload - * @param spc_cls closure for the @a spc payment callback * @param src callback for the upload process * @param src_cls closure for the @a src upload callback * @param secret_name name of the core secret diff --git a/src/include/anastasis_authorization_lib.h b/src/include/anastasis_authorization_lib.h index 80740be..99a4602 100644 --- a/src/include/anastasis_authorization_lib.h +++ b/src/include/anastasis_authorization_lib.h @@ -30,7 +30,7 @@ * * @param method name of the method to load * @param AH_cfg configuration to use - * @param[out] set to the cost for using the plugin during recovery + * @param[out] cost set to the cost for using the plugin during recovery * @return #GNUNET_OK on success */ struct ANASTASIS_AuthorizationPlugin * @@ -41,9 +41,7 @@ ANASTASIS_authorization_plugin_load ( /** - * shutdown all loaded plugins. - * - * @param void + * Shutdown all loaded plugins. */ void ANASTASIS_authorization_plugin_shutdown (void); diff --git a/src/include/anastasis_json.h b/src/include/anastasis_json.h deleted file mode 100644 index d2523a2..0000000 --- a/src/include/anastasis_json.h +++ /dev/null @@ -1,410 +0,0 @@ -/* - This file is part of Anastasis - Copyright (C) 2020 Taler Systems SA - - Anastasis is free software; you can redistribute it and/or modify it under the - terms of the GNU Lesser General Public License as published by the Free Software - Foundation; either version 3, or (at your option) any later version. - - Anastasis 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 General Public License for more details. - - You should have received a copy of the GNU General Public License along with - Anastasis; see the file COPYING.GPL. If not, see -*/ -/** - * @file include/anastasis_json.h - * @brief anastasis de-/serialization api - * @author Christian Grothoff - * @author Dominik Meister - * @author Dennis Neufeld - */ -#ifndef ANASTASIS_JSON_H -#define ANASTASIS_JSON_H - -#include -#include -#include "anastasis_error_codes.h" - -/** - * Enumeration of possible backup process status. - */ -enum ANASTASIS_BackupStatus -{ - ANASTASIS_BS_INITIAL, - ANASTASIS_BS_SELECT_CONTINENT, - ANASTASIS_BS_SELECT_COUNTRY, - ANASTASIS_BS_ENTER_USER_ATTRIBUTES, - ANASTASIS_BS_ADD_AUTHENTICATION_METHOD, - ANASTASIS_BS_ADD_POLICY, - ANASTASIS_BS_PAY -}; - -/** - * Enumeration of possible recovery process status. - */ -enum ANASTASIS_RecoveryStatus -{ - ANASTASIS_RS_INITIAL, - ANASTASIS_RS_SELECT_CONTINENT, - ANASTASIS_RS_SELECT_COUNTRY, - ANASTASIS_RS_ENTER_USER_ATTRIBUTES, - ANASTASIS_RS_SOLVE_CHALLENGE -}; - -// A state for the backup process. -struct ANASTASIS_BackupState -{ - enum ANASTASIS_BackupStatus status; - - union - { - - struct - { - // empty! - } select_continent; - - struct - { - const char *continent; - } select_country; - - struct - { - const char *continent; - const char *country; - const char *currency; // derived or per manual override! - json_t *user_attributes; - } enter_attributes; - - struct - { - const char *continent; - const char *country; - const char *currency; - json_t *user_attributes; - - struct AuthenticationDetails - { - enum AuthenticationMethod - { - SMS, - VIDEO, - SECQUEST, - EMAIL, - SNAILMAIL - }; - char *provider_url; - union Truth - { - - struct - { - char *phone_number; - } sms; - - struct - { - char *question; - char *answer; // FIXME: Reasonable to store answer in clear text here? - } secquest; - - struct - { - char *mailaddress; - } email; - - struct - { - char *full_name; - char *street; // street name + number - char *postal_code; - char *city; - char *country; - } snailmail; - - struct - { - char *path_to_picture; - } video; - } truth; - }*ad; // array - size_t ad_length; - } add_authentication; - struct - { - const char *continent; - const char *country; - const char *currency; - json_t *user_attributes; - - struct AuthenticationDetails - { - enum AuthenticationMethod - { - SMS, - VIDEO, - SECQUEST, - EMAIL, - SNAILMAIL - }; - char *provider_url; - union Truth - { - - struct - { - char *phone_number; - } sms; - - struct - { - char *question; - char *answer; // FIXME: Reasonable to store answer in clear text here? - } secquest; - - struct - { - char *mailaddress; - } email; - - struct - { - char *full_name; - char *street; // street name + number - char *postal_code; - char *city; - char *country; - } snailmail; - - struct - { - char *path_to_picture; - } video; - } truth; - }*ad; // array - size_t ad_length; - - struct PolicyDetails - { - struct AuthenticationDetails *ad; // array - }*pd; // array - size_t pd_length; - } add_policy; - // FIXME: add_payment - } details; -}; - - -// A state for the recovery process. -struct ANASTASIS_RecoveryState -{ - enum ANASTASIS_RecoveryStatus status; - - struct - { - // empty! - } select_continent; - - struct - { - const char *continent; - } select_country; - - struct - { - const char *continent; - const char *country; - const char *currency; // derived or per manual override! - json_t *user_attributes; - } enter_attributes; - - struct - { - const char *continent; - const char *country; - const char *currency; - json_t *user_attributes; - - struct ChallengeDetails - { - enum AuthenticationMethod - { - SMS, - VIDEO, - SECQUEST, - EMAIL, - SNAILMAIL - }; - char *provider_url; - union Challenge - { - - struct - { - char *phone_number; - char *code; - } sms; - - struct - { - char *question; - char *answer; // FIXME: Reasonable to store answer in clear text here? - } secquest; - - struct - { - char *mailaddress; - char *code; - } email; - - struct - { - char *full_name; - char *street; // street name + number - char *postal_code; - char *city; - char *country; - char *code; - } snailmail; - - struct - { - char *path_to_picture; - char *code; - } video; - } truth; - }*cd; // array - size_t cd_length; - } solve_challenge; -}; - -/** - * Definition of actions on ANASTASIS_BackupState. - */ -struct ANASTASIS_BackupAction -{ - enum action - { - ANASTASIS_BA_GET_SELECT_CONTINENT, - ANASTASIS_BA_GET_SELECT_COUNTRY, - ANASTASIS_BA_GET_ENTER_USER_ATTRIBUTES, - ANASTASIS_BA_GET_ADD_AUTHENTICATION_METHOD, - ANASTASIS_BA_GET_ADD_POLICY, - ANASTASIS_BA_GET_PAY, - ANASTASIS_BA_SET_SELECT_CONTINENT, - ANASTASIS_BA_SET_SELECT_COUNTRY, - ANASTASIS_BA_SET_ENTER_USER_ATTRIBUTES, - ANASTASIS_BA_SET_ADD_AUTHENTICATION_METHOD, - ANASTASIS_BA_SET_ADD_POLICY, - ANASTASIS_BA_SET_PAY - }; -}; - -/** - * Definition of actions on ANASTASIS_RecoveryState. - */ -struct ANASTASIS_RecoveryAction -{ - enum action - { - ANASTASIS_RS_GET_SELECT_CONTINENT, - ANASTASIS_RS_GET_SELECT_COUNTRY, - ANASTASIS_RS_GET_ENTER_USER_ATTRIBUTES, - ANASTASIS_RS_GET_SOLVE_CHALLENGE, - ANASTASIS_RS_SET_SELECT_CONTINENT, - ANASTASIS_RS_SET_SELECT_COUNTRY, - ANASTASIS_RS_SET_ENTER_USER_ATTRIBUTES, - ANASTASIS_RS_SET_SOLVE_CHALLENGE - }; -}; - - -/** - * Signature of the callback bassed to #ANASTASIS_apply_anastasis_backup_action - * for asynchronous actions on a #ANASTASIS_BackupState. - * - * @param cls closure - * @param new_bs the new #ANASTASIS_BackupState - * @param error error code - */ -typedef void -(*ANASTASIS_BackupApplyActionCallback)( - void *cls, - const struct ANASTASIS_BackupState *new_bs, - enum TALER_ErrorCode error); - - -/** - * Signature of the callback bassed to #ANASTASIS_apply_anastasis_recovery_action - * for asynchronous actions on a #ANASTASIS_RecoveryState. - * - * @param cls closure - * @param new_bs the new #ANASTASIS_RecoveryState - * @param error error code - */ -typedef void -(*ANASTASIS_RecoveryApplyActionCallback)( - void *cls, - const struct ANASTASIS_RecoveryState *new_rs, - enum TALER_ErrorCode error); - - -/** - * Returns an initial ANASTASIS_BackupState. - * - * @return initial ANASTASIS_BackupState - */ -struct ANASTASIS_BackupState * -ANASTASIS_get_initial_backup_state (); - - -/** - * Returns an initial ANASTASIS_RecoveryState. - * - * @return initial ANASTASIS_RecoveryState - */ -struct ANASTASIS_RecoveryState * -ANASTASIS_get_initial_recovery_state (); - - -/** - * Operates on a backup state depending on given #ANASTASIS_BackupState - * and #ANASTASIS_BackupAction. The new #ANASTASIS_BackupState is returned - * by a callback function. - * This function can do network access to talk to anastasis service providers. - * - * @param ctx url context for the event loop - * @param bs the previous *ANASTASIS_BackupState - * @param ba the action to do on #ANASTASIS_BackupState - * @param cb callback function to call with the action - */ -void -ANASTASIS_apply_anastasis_backup_action ( - struct GNUNET_CURL_Context *ctx, - struct ANASTASIS_BackupState *bs, - struct ANASTASIS_BackupAction *ba, - ANASTASIS_BackupApplyActionCallback cb); - - -/** - * Operates on a recovery state depending on given #ANASTASIS_RecoveryState - * and #ANASTASIS_RecoveryAction. The new #ANASTASIS_RecoveryState is returned - * by a callback function. - * This function can do network access to talk to anastasis service providers. - * - * @param ctx url context for the event loop - * @param bs the previous *ANASTASIS_RecoveryState - * @param ba the action to do on #ANASTASIS_RecoveryState - * @param cb callback function to call with the action - */ -void -ANASTASIS_apply_anastasis_recovery_action ( - struct GNUNET_CURL_Context *ctx, - struct ANASTASIS_RecoveryState *rs, - struct ANASTASIS_RecoveryAction *ra, - ANASTASIS_RecoveryApplyActionCallback cb); - -#endif /* _ANASTASIS_JSON_H */ diff --git a/src/include/anastasis_redux.h b/src/include/anastasis_redux.h index 7a0ff53..3a0b3f1 100644 --- a/src/include/anastasis_redux.h +++ b/src/include/anastasis_redux.h @@ -73,8 +73,7 @@ ANASTASIS_recovery_start (const struct GNUNET_CONFIGURATION_Handle *cfg); /** - * Signature of the callback passed to #ANASTASIS_backup_action and - * #ANASTASIS_recover_action. + * Signature of the callback passed to #ANASTASIS_redux_action() * * @param cls closure * @param error error code, #TALER_EC_NONE if @a new_bs is the new successful state @@ -93,12 +92,9 @@ struct ANASTASIS_ReduxAction; /** - * Operates on a state depending on given #ANASTASIS_BackupState - * or #ANASTASIS_RecoveryState and #ANASTASIS_BackupAction or - * #ANASTASIS_RecoveryAction. - * The new #ANASTASIS_BackupState or #ANASTASIS_RecoveryState is returned - * by a callback function. - * This function can do network access to talk to anastasis service providers. + * Operates on a state. The new state is returned by a callback + * function. This function can do network access to talk to Anastasis + * service providers. * * @param state input state * @param action what action to perform diff --git a/src/include/anastasis_service.h b/src/include/anastasis_service.h index 9069035..8e12b02 100644 --- a/src/include/anastasis_service.h +++ b/src/include/anastasis_service.h @@ -661,7 +661,6 @@ typedef void * @param ctx the CURL context used to connect to the backend * @param backend_url backend's base URL, including final "/" * @param uuid unique identfication of the Truth Upload - * @param prev_truth_data_hash hash of the previous truth upload, NULL for the first upload ever * @param type type of the authorization method * @param encrypted_keyshare key material to return to the client upon authorization * @param truth_mime mime type of @e encrypted_truth (after decryption) diff --git a/src/include/anastasis_testing_lib.h b/src/include/anastasis_testing_lib.h index 80018d9..ba6f801 100644 --- a/src/include/anastasis_testing_lib.h +++ b/src/include/anastasis_testing_lib.h @@ -37,17 +37,11 @@ */ #define ANASTASIS_TESTING_TRAIT_HASH_CURRENT 0 -/** - * Index used in #SYNC_TESTING_get_trait_hash() for the previous hash. - */ -#define ANASTASIS_TESTING_TRAIT_HASH_PREVIOUS 1 - /** * Obtain a hash from @a cmd. * * @param cmd command to extract the number from. - * @param index the number's index number, #ANASTASIS_TESTING_TRAIT_HASH_CURRENT or - * #SYNC_TESTING_TRAIT_HASH_PREVIOUS + * @param index the number's index number, use #ANASTASIS_TESTING_TRAIT_HASH_CURRENT * @param[out] h set to the hash coming from @a cmd. * @return #GNUNET_OK on success. */ @@ -107,8 +101,7 @@ ANASTASIS_TESTING_make_trait_truth_key ( */ int ANASTASIS_TESTING_get_trait_account_pub ( - const struct - TALER_TESTING_Command *cmd, + const struct TALER_TESTING_Command *cmd, unsigned int index, const struct ANASTASIS_CRYPTO_AccountPublicKeyP **pub); @@ -216,7 +209,7 @@ ANASTASIS_TESTING_make_trait_truth_uuid ( * * @param cmd command to extract the number from. * @param index the number's index number. - * @param[out] uuid set to the number coming from @a cmd. + * @param[out] eks set to the key share coming from @a cmd. * @return #GNUNET_OK on success. */ int @@ -255,10 +248,10 @@ ANASTASIS_TESTING_get_trait_code ( /** - * Offer a filename. + * Offer an authentication code. * * @param index the number's index number. - * @param tpk the public key to offer. + * @param code the code to offer. * @return trait on success */ struct TALER_TESTING_Trait @@ -300,7 +293,7 @@ TALER_TESTING_run_merchant (const char *config_filename, * anastasis" function to do such tasks. * * @param config_filename configuration filename. - * + * @param anastasis_url URL to use to confirm service running * @return the process, or NULL if the process could not * be started. */ @@ -383,19 +376,32 @@ ANASTASIS_TESTING_cmd_policy_store ( * Make the "policy lookup" command. * * @param label command label - * @param ANASTASIS_url base URL of the ANASTASIS serving - * the policy lookup request. + * @param anastasis_url base URL of the ANASTASIS serving + * the policy store request. * @param http_status expected HTTP status. * @param upload_ref reference to upload command * @return the command */ struct TALER_TESTING_Command ANASTASIS_TESTING_cmd_policy_lookup (const char *label, - const char *ANASTASIS_url, + const char *anastasis_url, unsigned int http_status, const char *upload_ref); +/** + * Make the "policy lookup" command for a non-existent upload. + * + * @param label command label + * @param anastasis_url base URL of the ANASTASIS serving + * the policy lookup request. + * @return the command + */ +struct TALER_TESTING_Command +ANASTASIS_TESTING_cmd_policy_nx (const char *label, + const char *anastasis_url); + + /** * Types of options for performing the upload. Used as a bitmask. */ @@ -482,6 +488,8 @@ ANASTASIS_TESTING_cmd_truth_question ( * @param answer (response to challenge) * @param payment_ref reference to the payment request * @param upload_ref reference to upload command + * @param lookup_mode 0 for security question, 1 for + * code-based * @param ksdd expected status * @return the command */ diff --git a/src/include/platform.h b/src/include/platform.h index d4b8bbe..a44a4a6 100644 --- a/src/include/platform.h +++ b/src/include/platform.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015, 2016 GNUnet e.V. and INRIA + Copyright (C) 2014, 2015, 2016, 2021 Anastasis SARL TALER 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 -- cgit v1.2.3