From c0657d0519ff7b96f70c1b9c77cff66e59aafdfb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=96zg=C3=BCr=20Kesim?= Date: Thu, 20 Jul 2023 18:16:54 +0200 Subject: [PATCH] -remove notes from source tree --- src/lib/notizen.md | 236 --------------------------------------------- 1 file changed, 236 deletions(-) delete mode 100644 src/lib/notizen.md diff --git a/src/lib/notizen.md b/src/lib/notizen.md deleted file mode 100644 index 835fad9e2..000000000 --- a/src/lib/notizen.md +++ /dev/null @@ -1,236 +0,0 @@ -# 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 - -