diff options
author | Özgür Kesim <oec-taler@kesim.org> | 2023-07-18 13:34:27 +0200 |
---|---|---|
committer | Özgür Kesim <oec-taler@kesim.org> | 2023-07-18 13:34:27 +0200 |
commit | 2eb3ff1f64f4eecb6f70c57c37469547757bc84b (patch) | |
tree | b52024edbf08d230bbb71803a258a729447adbd8 /src/lib/notizen.md | |
parent | 2ca7ce1b89b54fc318ceb241cad0533a1e751043 (diff) | |
download | exchange-2eb3ff1f64f4eecb6f70c57c37469547757bc84b.tar.xz |
[age-withdraw] simplify lib-API
Diffstat (limited to 'src/lib/notizen.md')
-rw-r--r-- | src/lib/notizen.md | 236 |
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 + + |