[age-withdraw] simplify lib-API

1 files changed, 236 insertions, 0 deletions

diff --git a/src/lib/notizen.md b/src/lib/notizen.md
new file mode 100644
index 000000000..835fad9e2
--- /dev/null
+++ b/src/lib/notizen.md
@@ -0,0 +1,236 @@
+# Notes re: planchets and blinding
+
+## `TALER_denom_blind()`
+
+```
+Blind coin for blind signing with @a dk using blinding secret @a coin_bks.
+```
+
+- `@param[out] c_hash resulting hashed coin`
+- `@param[out] blinded_planchet planchet data to initialize`
+
+## `TALER_planchet_prepare()`
+
+Prepare a planchet for withdrawal.  Creates and blinds a coin.
+
+- calls `TALER_denom_blind()!`
+- `@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, pd->blinded_planchet.cipher will be set to cipher from @a dk`
+
+
+## `TALER_coin_ev_hash`
+
+Compute the hash of a blinded coin.
+
+- `@param blinded_planchet blinded planchet`
+- `@param denom_hash hash of the denomination publick key`
+- `@param[out] bch where to write the hash, type struct TALER_BlindedCoinHashP`
+
+**Where is this called!?**
+
+```
+taler-exchange-httpd_refreshes_reveal.c
+605:    TALER_coin_ev_hash (&rrc->blinded_planchet,
+
+taler-exchange-httpd_recoup.c
+290:        TALER_coin_ev_hash (&blinded_planchet,
+
+taler-exchange-httpd_withdraw.c
+581:      TALER_coin_ev_hash (&wc.blinded_planchet,
+
+taler-exchange-httpd_age-withdraw_reveal.c
+350:    ret = TALER_coin_ev_hash (&detail.blinded_planchet,
+
+taler-exchange-httpd_recoup-refresh.c
+284:    TALER_coin_ev_hash (&blinded_planchet,
+
+taler-exchange-httpd_age-withdraw.c
+279:      ret = TALER_coin_ev_hash (&awc->coin_evs[c],
+884:    TALER_coin_ev_hash (&awc->coin_evs[i],
+
+taler-exchange-httpd_batch-withdraw.c
+832:        TALER_coin_ev_hash (&pc->blinded_planchet,
+```
+
+
+## `TALER_coin_pub_hash`
+
+Compute the hash of a coin.
+
+- `@param coin_pub public key of the coin`
+- `@param age_commitment_hash hash of the age commitment vector. NULL, if no age commitment was set`
+- `@param[out] coin_h where to write the hash`
+
+**Where is this called!?**
+
+### In `lib/crypto.c`, function `TALER_test_coin_valid`.
+
+```
+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
+```
+
+It then calls `TALER_denom_pub_verify` on the result of `TALER_coin_pub_hash` and the signature
+
+
+### In `util/denom.c`, function `TALER_denom_blind`
+
+## `TALER_EXCHANGE_batch_withdraw` vs `TALER_EXCHANGE_batch_withdraw2`
+
+### `TALER_EXCHANGE_batch_withdraw`
+
+```
+/**
+ * Withdraw multiple coins from the exchange using a /reserves/$RESERVE_PUB/batch-withdraw
+ * request.  This API is typically used by a wallet to withdraw many coins from a
+ * reserve.
+ *
+ * Note that to ensure that no money is lost in case of hardware
+ * failures, the caller must have committed (most of) the arguments to
+ * disk before calling, and be ready to repeat the request with the
+ * same arguments in case of failures.
+ *
+ * @param curl_ctx The curl context to use
+ * @param exchange_url The base-URL of the exchange
+ * @param keys The /keys material from the exchange
+ * @param reserve_priv private key of the reserve to withdraw from
+ * @param wci_length number of entries in @a wcis
+ * @param wcis inputs that determine the planchets
+ * @param res_cb the callback to call when the final result for this request is available
+ * @param res_cb_cls closure for @a res_cb
+ * @return NULL
+ *         if the inputs are invalid (i.e. denomination key not with this exchange).
+ *         In this case, the callback is not called.
+ */
+struct TALER_EXCHANGE_BatchWithdrawHandle *
+TALER_EXCHANGE_batch_withdraw (
+  struct GNUNET_CURL_Context *curl_ctx,
+  const char *exchange_url,
+  const struct TALER_EXCHANGE_Keys *keys,
+  const struct TALER_ReservePrivateKeyP *reserve_priv,
+  unsigned int wci_length,
+  const struct TALER_EXCHANGE_WithdrawCoinInput wcis[static wci_length],
+  TALER_EXCHANGE_BatchWithdrawCallback res_cb,
+  void *res_cb_cls);
+```
+
+### `TALER_EXCHANGE_batch_withdraw2`
+
+```
+/**
+ * Withdraw a coin from the exchange using a /reserves/$RESERVE_PUB/batch-withdraw
+ * request.  This API is typically used by a merchant to withdraw a tip
+ * where the blinding factor is unknown to the merchant.
+ *
+ * Note that to ensure that no money is lost in case of hardware
+ * failures, the caller must have committed (most of) the arguments to
+ * disk before calling, and be ready to repeat the request with the
+ * same arguments in case of failures.
+ *
+ * @param curl_ctx The curl context to use
+ * @param exchange_url The base-URL of the exchange
+ * @param keys The /keys material from the exchange
+ * @param pds array of planchet details of the planchet to withdraw
+ * @param pds_length number of entries in the @a pds array
+ * @param reserve_priv private key of the reserve to withdraw from
+ * @param res_cb the callback to call when the final result for this request is available
+ * @param res_cb_cls closure for @a res_cb
+ * @return NULL
+ *         if the inputs are invalid (i.e. denomination key not with this exchange).
+ *         In this case, the callback is not called.
+ */
+struct TALER_EXCHANGE_BatchWithdraw2Handle *
+TALER_EXCHANGE_batch_withdraw2 (
+  struct GNUNET_CURL_Context *curl_ctx,
+  const char *exchange_url,
+  const struct TALER_EXCHANGE_Keys *keys,
+  const struct TALER_ReservePrivateKeyP *reserve_priv,
+  unsigned int pds_length,
+  const struct TALER_PlanchetDetail pds[static pds_length],
+  TALER_EXCHANGE_BatchWithdraw2Callback res_cb,
+  void *res_cb_cls);
+```
+
+### Differences
+
+| batch_withdraw                     | batch_withdraw2        |
+|------------------------------------|------------------------|
+| `TALER_EXCHANGE_WithdrawCoinInput` | `TALER_PlanchetDetail` |
+
+
+```
+struct TALER_EXCHANGE_WithdrawCoinInput
+{
+  /**
+   * Denomination of the coin.
+   */
+  const struct TALER_EXCHANGE_DenomPublicKey *pk;
+
+  /**
+   * Master key material for the coin.
+   */
+  const struct TALER_PlanchetMasterSecretP *ps;
+
+  /**
+   * Age commitment for the coin.
+   */
+  const struct TALER_AgeCommitmentHash *ach;
+
+};
+```
+
+
+```
+struct TALER_PlanchetDetail
+{
+  /**
+   * Hash of the denomination public key.
+   */
+  struct TALER_DenominationHashP denom_pub_hash;
+
+  /**
+   * The blinded planchet
+   */
+  struct TALER_BlindedPlanchet {
+      /**
+       * Type of the sign blinded message
+       */
+      enum TALER_DenominationCipher cipher;
+
+      /**
+       * Details, depending on @e cipher.
+       */
+      union
+      {
+        /**
+         * If we use #TALER_DENOMINATION_CS in @a cipher.
+         */
+        struct TALER_BlindedCsPlanchet cs_blinded_planchet;
+
+        /**
+         * If we use #TALER_DENOMINATION_RSA in @a cipher.
+         */
+        struct TALER_BlindedRsaPlanchet rsa_blinded_planchet;
+
+      } details;
+  } blinded_planchet;
+};
+
+```
+
+
+
+## TODOs
+
+### Update documentation
+
+- [x] batch-withdraw needs error code for AgeRestrictionRequired
+- [x] withdraw needs error code for AgeRestrictionRequired
+
+