diff options
Diffstat (limited to 'src/include')
| -rw-r--r-- | src/include/taler_exchange_service.h | 264 |
1 files changed, 259 insertions, 5 deletions
diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h index d19d4fdb8..d98aba254 100644 --- a/src/include/taler_exchange_service.h +++ b/src/include/taler_exchange_service.h @@ -2662,7 +2662,7 @@ TALER_EXCHANGE_batch_withdraw2_cancel ( /* ********************* /reserve/$RESERVE_PUB/age-withdraw *************** */ /** - * @brief Information needed to withdraw age restricted coins. + * @brief Information needed to withdraw (and reveal) age restricted coins. */ struct TALER_EXCHANGE_AgeWithdrawCoinInput { @@ -2670,7 +2670,7 @@ struct TALER_EXCHANGE_AgeWithdrawCoinInput * The master secret from which we derive all other relevant values for * the coin: private key, nonces (if applicable) and age restriction */ - const struct TALER_PlanchetMasterSecretP secret[TALER_CNC_KAPPA]; + const struct TALER_PlanchetMasterSecretP secrets[TALER_CNC_KAPPA]; /** * The denomination of the coin. Must support age restriction, i.e @@ -2712,6 +2712,23 @@ struct TALER_EXCHANGE_AgeWithdrawResponse uint8_t noreveal_index; /** + * The commitment of the call to /age-withdraw + */ + struct TALER_AgeWithdrawCommitmentHashP h_commitment; + + /** + * The algorithm specific values (for CS) need for the coins that were + * retrieved from /csr-withdraw. + */ + struct TALER_ExchangeWithdrawValues *alg_values; + + /** + * Number of elements in @e alg_values, same as number coin candidates.from + * the request. + */ + size_t num_alg_values; + + /** * Signature of the exchange over the origina TALER_AgeWithdrawRequestPS */ struct TALER_ExchangeSignatureP exchange_sig; @@ -2722,7 +2739,6 @@ struct TALER_EXCHANGE_AgeWithdrawResponse struct TALER_ExchangePublicKeyP exchange_pub; } ok; - /* FIXME[oec]: error cases */ } details; }; @@ -2755,11 +2771,11 @@ typedef void struct TALER_EXCHANGE_AgeWithdrawHandle * TALER_EXCHANGE_age_withdraw ( struct GNUNET_CURL_Context *curl_ctx, - const char *exchange_url, struct TALER_EXCHANGE_Keys *keys, + const char *exchange_url, const struct TALER_ReservePrivateKeyP *reserve_priv, size_t num_coins, - const struct TALER_EXCHANGE_AgeWithdrawCoinInput coin_inputs[const static + const struct TALER_EXCHANGE_AgeWithdrawCoinInput coin_inputs[static num_coins], uint8_t max_age, TALER_EXCHANGE_AgeWithdrawCallback res_cb, @@ -2776,6 +2792,244 @@ TALER_EXCHANGE_age_withdraw_cancel ( struct TALER_EXCHANGE_AgeWithdrawHandle *awh); +/**++++++ age-withdraw with pre-blinded planchets ***************************/ + +/** + * @brief Information needed to withdraw (and reveal) age restricted coins. + */ +struct TALER_EXCHANGE_AgeWithdrawBlindedInput +{ + /** + * The denomination of the coin. Must support age restriction, i.e + * its .keys.age_mask MUST not be 0 + */ + const struct TALER_EXCHANGE_DenomPublicKey *denom_pub; + + /** + * Blinded Planchets + */ + struct TALER_PlanchetDetail planchet_details[TALER_CNC_KAPPA]; + +}; + +/** + * Response from an age-withdraw request with pre-blinded planchets + */ +struct TALER_EXCHANGE_AgeWithdrawBlindedResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Response details depending on the HTTP status. + */ + union + { + /** + * Details if HTTP status is #MHD_HTTP_OK. + */ + struct + { + /** + * Index that should not be revealed during the age-withdraw reveal phase. + * The struct TALER_PlanchetMasterSecretP * from the request + * with this index are the ones to keep. + */ + uint8_t noreveal_index; + + /** + * The commitment of the call to /age-withdraw + */ + struct TALER_AgeWithdrawCommitmentHashP h_commitment; + + /** + * Signature of the exchange over the origina TALER_AgeWithdrawRequestPS + */ + struct TALER_ExchangeSignatureP exchange_sig; + + /** + * Key used by the exchange for @e exchange_sig + */ + struct TALER_ExchangePublicKeyP exchange_pub; + } ok; + } details; + +}; + + +/** + * Callbacks of this type are used to serve the result of submitting an + * age-withdraw request to a exchange with pre-blinded planchets + * without the (un)blinding factor. + * + * @param cls closure + * @param awbr response data + */ +typedef void +(*TALER_EXCHANGE_AgeWithdrawBlindedCallback) ( + void *cls, + const struct TALER_EXCHANGE_AgeWithdrawBlindedResponse *awbr); + + +/** + * @brief A /reserves/$RESERVE_PUB/age-withdraw Handle, 2nd variant with + * pre-blinded planchets. + * + * This variant does not do the blinding/unblinding and only + * fetches the blind signatures on the already blinded planchets. + * Used internally by the `struct TALER_EXCHANGE_BatchWithdrawHandle` + * implementation as well as for the reward logic of merchants. + */ +struct TALER_EXCHANGE_BatchWithdraw2Handle; + +/** + * Withdraw age-restricted coins from the exchange using a + * /reserves/$RESERVE_PUB/age-withdraw request. This API is typically used + * by a merchant to withdraw a reward where the planchets are pre-blinded and + * 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 num_input number of entries in the @a blinded_input array + * @param blinded_input array of planchet details of the planchet to withdraw + * @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_AgeWithdrawBlindedHandle * +TALER_EXCHANGE_age_withdraw_blinded ( + struct GNUNET_CURL_Context *curl_ctx, + struct TALER_EXCHANGE_Keys *keys, + const char *exchange_url, + const struct TALER_ReservePrivateKeyP *reserve_priv, + unsigned int num_input, + const struct TALER_EXCHANGE_AgeWithdrawBlindedInput blinded_input[static + num_input], + TALER_EXCHANGE_AgeWithdrawBlindedCallback res_cb, + void *res_cb_cls); + + +/** + * Cancel an age-withdraw request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param awbh the age-withdraw handle + */ +void +TALER_EXCHANGE_age_withdraw_blinded_cancel ( + struct TALER_EXCHANGE_AgeWithdrawBlindedHandle *awbh); + + +/* ********************* /age-withdraw/$ACH/reveal ************************ */ + +/** + * @brief A handle to a /age-withdraw/$ACH/reveal request + */ +struct TALER_EXCHANGE_AgeWithdrawRevealHandle; + +/** + * The response from a /age-withdraw/$ACH/reveal request + */ +struct TALER_EXCHANGE_AgeWithdrawRevealResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details about the response + */ + union + { + /** + * Details if the status is #MHD_HTTP_OK. + */ + struct + { + /** + * Number of coins returned. + */ + unsigned int num_coins; + + /** + * Array of @e num_coins values about the coins obtained via the reveal + * operation. The array give thes coins in the same order (and should + * have the same length) in which the original age-withdraw request + * specified the respective denomination keys. + */ + const struct TALER_EXCHANGE_RevealedCoinInfo *revealed_coins; + + } ok; + /* FIXME[oec]: error cases */ + } details; + +}; + +typedef void +(*TALER_EXCHANGE_AgeWithdrawRevealCallback)( + void *cls, + const struct TALER_EXCHANGE_AgeWithdrawRevealResponse *awr); + +/** + * Submit an age-withdraw-reveal request to the exchange and get the exchange's + * response. + * + * This API is typically used by a wallet. Note that to ensure that + * no money is lost in case of hardware failures, the provided + * argument @a rd should be committed to persistent storage + * prior to calling this function. + * + * @param curl_ctx The curl context + * @param exchange_url The base url of the exchange + * @param reserve_priv The pivate key to the reserve + * @param num_coins The number of elements in @e coin_inputs and @e alg_values + * @param coins_input The input for the coins to withdraw, same as in the previous call to /age-withdraw + * @param alg_values The algorithm specific parameters per coin, from the result to the previous call to /age-withdraw + * @param noreveal_index The index into each of the kappa coin candidates, that should not be revealed to the exchange + * @param h_commitment The commmitment from the previous call to /age-withdraw + * @param max_age maximum age, as used in the to /age-withdraw + * @param res_cb A callback for the result, maybe NULL + * @param res_cb_cls A closure for @e res_cb, maybe NULL + * @return a handle for this request; NULL if the argument was invalid. + * In this case, the callback will not be called. + */ +struct TALER_EXCHANGE_AgeWithdrawRevealHandle * +TALER_EXCHANGE_age_withdraw_reveal ( + struct GNUNET_CURL_Context *curl_ctx, + const char *exchange_url, + size_t num_coins, + const struct TALER_EXCHANGE_AgeWithdrawCoinInput coins_input[static + num_coins], + const struct TALER_ExchangeWithdrawValues alg_values[static num_coins], + uint8_t noreveal_index, + const struct TALER_AgeWithdrawCommitmentHashP *h_commitment, + uint8_t max_age, + TALER_EXCHANGE_AgeWithdrawRevealCallback res_cb, + void *res_cb_cls); + + +/** + * @brief Cancel an age-withdraw-reveal request + * + * @param awrh Handle to an age-withdraw-reqveal request + */ +void +TALER_EXCHANGE_age_withdraw_reveal_cancel ( + struct TALER_EXCHANGE_AgeWithdrawRevealHandle *awrh); + + /* ********************* /refresh/melt+reveal ***************************** */ |