misc doxygen fixes

7 files changed, 34 insertions, 443 deletions

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 <http://www.gnu.org/licenses/>
-*/
-/**
- * @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 <jansson.h>
-#include <gnunet/gnunet_util_lib.h>
-#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
@@ -38,16 +38,10 @@
 #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,20 +376,33 @@ 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.
  */
 enum ANASTASIS_TESTING_TruthStoreOption
@@ -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