misc doxygen fixes

9 files changed, 30 insertions, 151 deletions

diff --git a/src/util/auditor_signatures.c b/src/util/auditor_signatures.c
index 837b31c6c..b41ce66a8 100644
--- a/src/util/auditor_signatures.c
+++ b/src/util/auditor_signatures.c
@@ -70,7 +70,7 @@ TALER_auditor_denom_validity_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_auditor_denom_validity_verify (
   const char *auditor_url,
   const struct GNUNET_HashCode *h_denom_pub,
diff --git a/src/util/crypto.c b/src/util/crypto.c
index dcff5fd22..4f084b19c 100644
--- a/src/util/crypto.c
+++ b/src/util/crypto.c
@@ -26,9 +26,8 @@
 #include <gcrypt.h>
 
 /**
- * Should we use the RSA blind signing implementation
- * from libgnunetutil?  The blinding only works
- * correctly with a current version of libgnunetutil.
+ * Should we use the RSA blind signing implementation from libgnunetutil?  The
+ * blinding only works correctly with a current version of libgnunetutil.
  *
  * Only applies to blinding and unblinding, but
  * not to blind signing.
@@ -82,17 +81,7 @@ TALER_gcrypt_init ()
 }
 
 
-/**
- * Check if a coin is valid; that is, whether the denomination key exists,
- * is not expired, and the signature is correct.
- *
- * @param coin_public_info the coin public info to check for validity
- * @param denom_pub denomination key, must match @a coin_public_info's `denom_pub_hash`
- * @return #GNUNET_YES if the coin is valid,
- *         #GNUNET_NO if it is invalid
- *         #GNUNET_SYSERR if an internal error occurred
- */
-int
+enum GNUNET_GenericReturnValue
 TALER_test_coin_valid (const struct TALER_CoinPublicInfo *coin_public_info,
                        const struct TALER_DenominationPublicKey *denom_pub)
 {
@@ -122,17 +111,6 @@ TALER_test_coin_valid (const struct TALER_CoinPublicInfo *coin_public_info,
 }
 
 
-/**
- * Given the coin and the transfer private keys, compute the
- * transfer secret.  (Technically, we only need one of the two
- * private keys, but the caller currently trivially only has
- * the two private keys, so we derive one of the public keys
- * internally to this function.)
- *
- * @param coin_priv coin key
- * @param trans_priv transfer private key
- * @param[out] ts computed transfer secret
- */
 void
 TALER_link_derive_transfer_secret (
   const struct TALER_CoinSpendPrivateKeyP *coin_priv,
@@ -151,14 +129,6 @@ TALER_link_derive_transfer_secret (
 }
 
 
-/**
- * Decrypt the shared @a secret from the information in the
- * @a trans_priv and @a coin_pub.
- *
- * @param trans_priv transfer private key
- * @param coin_pub coin public key
- * @param[out] transfer_secret set to the shared secret
- */
 void
 TALER_link_reveal_transfer_secret (
   const struct TALER_TransferPrivateKeyP *trans_priv,
@@ -172,14 +142,6 @@ TALER_link_reveal_transfer_secret (
 }
 
 
-/**
- * Decrypt the shared @a secret from the information in the
- * @a trans_priv and @a coin_pub.
- *
- * @param trans_pub transfer private key
- * @param coin_priv coin public key
- * @param[out] transfer_secret set to the shared secret
- */
 void
 TALER_link_recover_transfer_secret (
   const struct TALER_TransferPublicKeyP *trans_pub,
@@ -193,13 +155,6 @@ TALER_link_recover_transfer_secret (
 }
 
 
-/**
- * Setup information for a fresh coin.
- *
- * @param secret_seed seed to use for KDF to derive coin keys
- * @param coin_num_salt number of the coin to include in KDF
- * @param[out] ps value to initialize
- */
 void
 TALER_planchet_setup_refresh (const struct TALER_TransferSecretP *secret_seed,
                               uint32_t coin_num_salt,
@@ -220,11 +175,6 @@ TALER_planchet_setup_refresh (const struct TALER_TransferSecretP *secret_seed,
 }
 
 
-/**
- * Setup information for a fresh coin.
- *
- * @param[out] ps value to initialize
- */
 void
 TALER_planchet_setup_random (struct TALER_PlanchetSecretsP *ps)
 {
@@ -234,17 +184,7 @@ TALER_planchet_setup_random (struct TALER_PlanchetSecretsP *ps)
 }
 
 
-/**
- * Prepare a planchet for tipping.  Creates and blinds a coin.
- *
- * @param dk denomination key for the coin to be created
- * @param ps secret planchet internals (for #TALER_planchet_to_coin)
- * @param[out] c_hash set to the hash of the public key of the coin (needed later)
- * @param[out] pd set to the planchet detail for TALER_MERCHANT_tip_pickup() and
- *               other withdraw operations
- * @return #GNUNET_OK on success
- */
-int
+enum GNUNET_GenericReturnValue
 TALER_planchet_prepare (const struct TALER_DenominationPublicKey *dk,
                         const struct TALER_PlanchetSecretsP *ps,
                         struct GNUNET_HashCode *c_hash,
@@ -273,18 +213,7 @@ TALER_planchet_prepare (const struct TALER_DenominationPublicKey *dk,
 }
 
 
-/**
- * Obtain a coin from the planchet's secrets and the blind signature
- * of the exchange.
- *
- * @param dk denomination key, must match what was given to #TALER_planchet_prepare()
- * @param blind_sig blind signature from the exchange
- * @param ps secrets from #TALER_planchet_prepare()
- * @param c_hash hash of the coin's public key for verification of the signature
- * @param[out] coin set to the details of the fresh coin
- * @return #GNUNET_OK on success
- */
-int
+enum GNUNET_GenericReturnValue
 TALER_planchet_to_coin (const struct TALER_DenominationPublicKey *dk,
                         const struct GNUNET_CRYPTO_RsaSignature *blind_sig,
                         const struct TALER_PlanchetSecretsP *ps,
@@ -311,17 +240,6 @@ TALER_planchet_to_coin (const struct TALER_DenominationPublicKey *dk,
 }
 
 
-/**
- * Compute the commitment for a /refresh/melt operation from
- * the respective public inputs.
- *
- * @param[out] rc set to the value the wallet must commit to
- * @param kappa number of transfer public keys involved (must be #TALER_CNC_KAPPA)
- * @param num_new_coins number of new coins to be created
- * @param rcs commitments array of @a kappa commitments
- * @param coin_pub public key of the coin to be melted
- * @param amount_with_fee amount to be melted, including fee
- */
 void
 TALER_refresh_get_commitment (struct TALER_RefreshCommitmentP *rc,
                               uint32_t kappa,
@@ -556,7 +474,6 @@ rsa_gcd_validate (gcry_mpi_t r, gcry_mpi_t n)
  *
  * @param hash initial hash of the message to sign
  * @param pkey the public key of the signer
- * @param rsize If not NULL, the number of bytes actually stored in buffer
  * @return MPI value set to the FDH, NULL if RSA key is malicious
  */
 static gcry_mpi_t
@@ -598,7 +515,7 @@ rsa_full_domain_hash (const struct GNUNET_CRYPTO_RsaPublicKey *pkey,
 /**
  * Create a blinding key
  *
- * @param len length of the key in bits (i.e. 2048)
+ * @param pkey the public key to blind for
  * @param bks pre-secret to use to derive the blinding key
  * @return the newly created blinding key, NULL if RSA key is malicious
  */
@@ -638,7 +555,7 @@ rsa_blinding_key_derive (const struct GNUNET_CRYPTO_RsaPublicKey *pkey,
  * Print an MPI to a newly created buffer
  *
  * @param v MPI to print.
- * @param[out] newly allocated buffer containing the result
+ * @param[out] buffer newly allocated buffer containing the result
  * @return number of bytes stored in @a buffer
  */
 static size_t
@@ -669,17 +586,7 @@ numeric_mpi_alloc_n_print (gcry_mpi_t v,
 #endif /* ! USE_GNUNET_RSA_BLINDING */
 
 
-/**
- * Blinds the given message with the given blinding key
- *
- * @param hash hash of the message to sign
- * @param bkey the blinding key
- * @param pkey the public key of the signer
- * @param[out] buf set to a buffer with the blinded message to be signed
- * @param[out] buf_size number of bytes stored in @a buf
- * @return #GNUNET_YES if successful, #GNUNET_NO if RSA key is malicious
- */
-int
+enum GNUNET_GenericReturnValue
 TALER_rsa_blind (const struct GNUNET_HashCode *hash,
                  const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
                  struct GNUNET_CRYPTO_RsaPublicKey *pkey,
@@ -710,7 +617,7 @@ TALER_rsa_blind (const struct GNUNET_HashCode *hash,
     GNUNET_break (0);
     *buf = NULL;
     *buf_size = 0;
-    return 0;
+    return GNUNET_NO;
   }
 
   data = rsa_full_domain_hash (pkey, hash);
@@ -758,16 +665,6 @@ rsa_gcd_validate_failure:
 }
 
 
-/**
- * Unblind a blind-signed signature.  The signature should have been generated
- * with #GNUNET_CRYPTO_rsa_sign() using a hash that was blinded with
- * #GNUNET_CRYPTO_rsa_blind().
- *
- * @param sig the signature made on the blinded signature purpose
- * @param bks the blinding key secret used to blind the signature purpose
- * @param pkey the public key of the signer
- * @return unblinded signature on success, NULL if RSA key is bad or malicious.
- */
 struct GNUNET_CRYPTO_RsaSignature *
 TALER_rsa_unblind (const struct GNUNET_CRYPTO_RsaSignature *sig,
                    const struct GNUNET_CRYPTO_RsaBlindingKeySecret *bks,
diff --git a/src/util/crypto_helper_denom.c b/src/util/crypto_helper_denom.c
index c61a46f1d..4618383a9 100644
--- a/src/util/crypto_helper_denom.c
+++ b/src/util/crypto_helper_denom.c
@@ -663,7 +663,8 @@ void
 TALER_CRYPTO_helper_denom_disconnect (
   struct TALER_CRYPTO_DenominationHelper *dh)
 {
-  do_disconnect (dh);
+  if (-1 != dh->sock)
+    do_disconnect (dh);
   GNUNET_free (dh->template);
   GNUNET_free (dh);
 }
diff --git a/src/util/crypto_helper_esign.c b/src/util/crypto_helper_esign.c
index 1cf20e914..688afc7de 100644
--- a/src/util/crypto_helper_esign.c
+++ b/src/util/crypto_helper_esign.c
@@ -317,7 +317,7 @@ handle_mt_purge (struct TALER_CRYPTO_ExchangeSignHelper *esh,
 /**
  * Wait until the socket is ready to read.
  *
- * @param dh helper to wait for
+ * @param esh helper to wait for
  * @return false on timeout (after 5s)
  */
 static bool
@@ -591,7 +591,8 @@ void
 TALER_CRYPTO_helper_esign_disconnect (
   struct TALER_CRYPTO_ExchangeSignHelper *esh)
 {
-  do_disconnect (esh);
+  if (-1 != esh->sock)
+    do_disconnect (esh);
   GNUNET_free (esh->template);
   GNUNET_free (esh);
 }
diff --git a/src/util/crypto_wire.c b/src/util/crypto_wire.c
index 7aaf7d15d..0d31720a7 100644
--- a/src/util/crypto_wire.c
+++ b/src/util/crypto_wire.c
@@ -53,7 +53,7 @@ TALER_exchange_wire_signature_hash (const char *payto_uri,
  * @param master_sig signature of the exchange
  * @return #GNUNET_OK if signature is valid
  */
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_wire_signature_check (
   const char *payto_uri,
   const struct TALER_MasterPublicKeyP *master_pub,
@@ -143,7 +143,7 @@ TALER_merchant_wire_signature_hash (const char *payto_uri,
  * @param merch_sig signature of the merchant
  * @return #GNUNET_OK if signature is valid
  */
-int
+enum GNUNET_GenericReturnValue
 TALER_merchant_wire_signature_check (
   const char *payto_uri,
   const char *salt,
diff --git a/src/util/offline_signatures.c b/src/util/offline_signatures.c
index 5899c134b..aab46fc7d 100644
--- a/src/util/offline_signatures.c
+++ b/src/util/offline_signatures.c
@@ -47,17 +47,7 @@ TALER_exchange_offline_auditor_add_sign (
 }
 
 
-/**
- * Verify auditor add signature.
- *
- * @param auditor_pub public key of the auditor
- * @param auditor_url URL of the auditor
- * @param start_date when to enable the auditor (for replay detection)
- * @param master_pub public key to verify against
- * @param master_sig the signature the signature
- * @return #GNUNET_OK if the signature is valid
- */
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_auditor_add_verify (
   const struct TALER_AuditorPublicKeyP *auditor_pub,
   const char *auditor_url,
@@ -103,7 +93,7 @@ TALER_exchange_offline_auditor_del_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_auditor_del_verify (
   const struct TALER_AuditorPublicKeyP *auditor_pub,
   struct GNUNET_TIME_Absolute end_date,
@@ -143,7 +133,7 @@ TALER_exchange_offline_denomination_revoke_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_denomination_revoke_verify (
   const struct GNUNET_HashCode *h_denom_pub,
   const struct TALER_MasterPublicKeyP *master_pub,
@@ -183,7 +173,7 @@ TALER_exchange_offline_signkey_revoke_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_signkey_revoke_verify (
   const struct TALER_ExchangePublicKeyP *exchange_pub,
   const struct TALER_MasterPublicKeyP *master_pub,
@@ -231,7 +221,7 @@ TALER_exchange_offline_signkey_validity_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_signkey_validity_verify (
   const struct TALER_ExchangePublicKeyP *exchange_pub,
   struct GNUNET_TIME_Absolute start_sign,
@@ -305,7 +295,7 @@ TALER_exchange_offline_denom_validity_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_denom_validity_verify (
   const struct GNUNET_HashCode *h_denom_pub,
   struct GNUNET_TIME_Absolute stamp_start,
@@ -374,7 +364,7 @@ TALER_exchange_offline_wire_add_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_wire_add_verify (
   const char *payto_uri,
   struct GNUNET_TIME_Absolute sign_time,
@@ -421,7 +411,7 @@ TALER_exchange_offline_wire_del_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_wire_del_verify (
   const char *payto_uri,
   struct GNUNET_TIME_Absolute sign_time,
@@ -475,7 +465,7 @@ TALER_exchange_offline_wire_fee_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_offline_wire_fee_verify (
   const char *payment_method,
   struct GNUNET_TIME_Absolute start_time,
diff --git a/src/util/secmod_signatures.c b/src/util/secmod_signatures.c
index e7542c1e1..3df68861d 100644
--- a/src/util/secmod_signatures.c
+++ b/src/util/secmod_signatures.c
@@ -45,7 +45,7 @@ TALER_exchange_secmod_eddsa_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_secmod_eddsa_verify (
   const struct TALER_ExchangePublicKeyP *exchange_pub,
   struct GNUNET_TIME_Absolute start_sign,
@@ -96,7 +96,7 @@ TALER_exchange_secmod_rsa_sign (
 }
 
 
-int
+enum GNUNET_GenericReturnValue
 TALER_exchange_secmod_rsa_verify (
   const struct GNUNET_HashCode *h_denom_pub,
   const char *section_name,
diff --git a/src/util/taler-helper-crypto-eddsa.c b/src/util/taler-helper-crypto-eddsa.c
index ad1a783ee..c229a8c1f 100644
--- a/src/util/taler-helper-crypto-eddsa.c
+++ b/src/util/taler-helper-crypto-eddsa.c
@@ -18,11 +18,6 @@
  * @brief Standalone process to perform private key EDDSA operations
  * @author Christian Grothoff
  *
- * INTEGRATION NOTES:
- * - Option 'DURATION_OVERLAP' renamed to 'OVERLAP_DURATION' for consistency;
- *   => need to update in deployment scripts and default configuration!
- * - option 'KEY_DIR' moved from section 'exchange' to 'taler-helper-crypto-eddsa'!
- *
  * Key design points:
  * - EVERY thread of the exchange will have its own pair of connections to the
  *   crypto helpers.  This way, every threat will also have its own /keys state
@@ -236,7 +231,7 @@ static char *keydir;
 /**
  * How much should coin creation duration overlap
  * with the next key?  Basically, the starting time of two
- * keys is always #duration - #duration_overlap apart.
+ * keys is always #duration - #overlap_duration apart.
  */
 static struct GNUNET_TIME_Relative overlap_duration;
 
diff --git a/src/util/taler-helper-crypto-rsa.c b/src/util/taler-helper-crypto-rsa.c
index 53d5c2c7c..345a826a6 100644
--- a/src/util/taler-helper-crypto-rsa.c
+++ b/src/util/taler-helper-crypto-rsa.c
@@ -18,11 +18,6 @@
  * @brief Standalone process to perform private key RSA operations
  * @author Christian Grothoff
  *
- * INTEGRATION NOTES:
- * - Option 'DURATION_OVERLAP' renamed to 'OVERLAP_DURATION' for consistency;
- *   => need to update in deployment scripts and default configuration!
- * - option 'KEY_DIR' moved from section 'exchange' to 'taler-helper-crypto-rsa'!
- *
  * Key design points:
  * - EVERY thread of the exchange will have its own pair of connections to the
  *   crypto helpers.  This way, every threat will also have its own /keys state
@@ -288,7 +283,7 @@ static char *keydir;
 /**
  * How much should coin creation (@e duration_withdraw) duration overlap
  * with the next denomination?  Basically, the starting time of two
- * denominations is always @e duration_withdraw - #duration_overlap apart.
+ * denominations is always @e duration_withdraw - #overlap_duration apart.
  */
 static struct GNUNET_TIME_Relative overlap_duration;