From edd31c74151d6bfe3d840bcc62b619aacf7542eb Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 20 Apr 2016 02:50:52 +0200 Subject: implementing parsing of /refund requests --- src/include/taler_exchange_service.h | 77 +++++++++++++++++++++++++++++++++++ src/include/taler_exchangedb_plugin.h | 61 +++++++++++++++++++++++++++ src/include/taler_signatures.h | 58 ++++++++++++++++++++++++++ 3 files changed, 196 insertions(+) (limited to 'src/include') diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h index ffd420586..2f9a1932c 100644 --- a/src/include/taler_exchange_service.h +++ b/src/include/taler_exchange_service.h @@ -465,6 +465,83 @@ void TALER_EXCHANGE_deposit_cancel (struct TALER_EXCHANGE_DepositHandle *deposit); +/* ********************* /refund *********************** */ + +/** + * @brief A Refund Handle + */ +struct TALER_EXCHANGE_RefundHandle; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * deposit permission request to a exchange. + * + * @param cls closure + * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful deposit; + * 0 if the exchange's reply is bogus (fails to follow the protocol) + * @param obj the received JSON reply, should be kept as proof (and, in particular, + * be forwarded to the customer) + */ +typedef void +(*TALER_EXCHANGE_RefundResultCallback) (void *cls, + unsigned int http_status, + const json_t *obj); + + +/** + * Submit a refund request to the exchange and get the exchange's + * response. This API is used by a merchant. Note that + * while we return the response verbatim to the caller for further + * processing, we do already verify that the response is well-formed + * (i.e. that signatures included in the response are all valid). If + * the exchange's reply is not well-formed, we return an HTTP status code + * of zero to @a cb. + * + * The @a exchange must be ready to operate (i.e. have + * finished processing the /keys reply). If this check fails, we do + * NOT initiate the transaction with the exchange and instead return NULL. + * + * @param exchange the exchange handle; the exchange must be ready to operate + * @param amount the amount to be refunded; must be larger than the refund fee + * (as that fee is still being subtracted), and smaller than the amount + * (with deposit fee) of the original deposit contribution of this coin + * @param h_contract hash of the contact of the merchant with the customer that is being refunded + * @param transaction_id transaction id for the transaction being refunded, must match @a h_contract + * @param coin_pub coin’s public key of the coin from the original deposit operation + * @param rtransaction_id transaction id for the transaction between merchant and customer (of refunding operation); + * this is needed as we may first do a partial refund and later a full refund. If both + * refunds are also over the same amount, we need the @a rtransaction_id to make the disjoint + * refund requests different (as requests are idempotent and otherwise the 2nd refund might not work). + * @param merchant_priv the private key of the merchant, used to generate signature for refund request + * @param cb the callback to call when a reply for this request is available + * @param cb_cls closure for the above callback + * @return a handle for this request; NULL if the inputs are invalid (i.e. + * signatures fail to verify). In this case, the callback is not called. + */ +struct TALER_EXCHANGE_RefundHandle * +TALER_EXCHANGE_refund (struct TALER_EXCHANGE_Handle *exchange, + const struct TALER_Amount *amount, + const struct GNUNET_HashCode *h_contract, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + uint64_t rtransaction_id, + const struct TALER_MerchantPrivateKeyP *merchant_priv, + TALER_EXCHANGE_RefundResultCallback cb, + void *cb_cls); + + +/** + * Cancel a refund permission request. This function cannot be used + * on a request handle if a response is already served for it. If + * this function is called, the refund may or may not have happened. + * However, it is fine to try to refund the coin a second time. + * + * @param refund the refund request handle + */ +void +TALER_EXCHANGE_refund_cancel (struct TALER_EXCHANGE_RefundHandle *refund); + + /* ********************* /reserve/status *********************** */ diff --git a/src/include/taler_exchangedb_plugin.h b/src/include/taler_exchangedb_plugin.h index 3646981cd..e364d6b95 100644 --- a/src/include/taler_exchangedb_plugin.h +++ b/src/include/taler_exchangedb_plugin.h @@ -298,6 +298,67 @@ struct TALER_EXCHANGEDB_Deposit }; +/** + * @brief Specification for a /refund operation. The combination of + * the coin's public key, the merchant's public key and the + * transaction ID must be unique. While a coin can (theoretically) be + * deposited at the same merchant twice (with partial spending), the + * merchant must either use a different public key or a different + * transaction ID for the two transactions. The same goes for + * refunds, hence we also have a "rtransaction" ID which is disjoint + * from the transaction ID. The same coin must not be used twice at + * the same merchant for the same transaction or rtransaction ID. + */ +struct TALER_EXCHANGEDB_Refund +{ + /** + * Information about the coin that is being refunded. + */ + struct TALER_CoinPublicInfo coin; + + /** + * Public key of the merchant. + */ + struct TALER_MerchantPublicKeyP merchant_pub; + + /** + * Signature from the merchant affirming the refund. + */ + struct TALER_MerchantSignatureP merchant_sig; + + /** + * Hash over the contract between merchant and customer + * (remains unknown to the Exchange). + */ + struct GNUNET_HashCode h_contract; + + /** + * Merchant-generated transaction ID to detect duplicate + * transactions, of the original transaction that is being + * refunded. + */ + uint64_t transaction_id; + + /** + * Merchant-generated REFUND transaction ID to detect duplicate + * refunds. + */ + uint64_t rtransaction_id; + + /** + * Fraction of the original deposit's value to be refunded, including + * refund fee (if any). The coin is identified by @e coin_pub. + */ + struct TALER_Amount refund_amount; + + /** + * Refund fee to be covered by the customer. + */ + struct TALER_Amount refund_fee; + +}; + + /** * @brief Global information for a refreshing session. Includes * dimensions of the operation, security parameters and diff --git a/src/include/taler_signatures.h b/src/include/taler_signatures.h index 154e11610..f1586aa8c 100644 --- a/src/include/taler_signatures.h +++ b/src/include/taler_signatures.h @@ -395,6 +395,64 @@ struct TALER_DepositConfirmationPS }; +/** + * @brief Format used to generate the signature on a request to refund + * a coin into the account of the customer. + */ +struct TALER_RefundRequestPS +{ + /** + * Purpose must be #TALER_SIGNATURE_MERCHANT_REFUND. + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + + /** + * Hash over the contract which is being refunded. + */ + struct GNUNET_HashCode h_contract GNUNET_PACKED; + + /** + * Merchant-generated transaction ID of the orginal transaction. + */ + uint64_t transaction_id GNUNET_PACKED; + + /** + * The coin's public key. This is the value that must have been + * signed (blindly) by the Exchange. + */ + struct TALER_CoinSpendPublicKeyP coin_pub; + + /** + * The Merchant's public key. Allows the merchant to later refund + * the transaction or to inquire about the wire transfer identifier. + */ + struct TALER_MerchantPublicKeyP merchant; + + /** + * Merchant-generated transaction ID for the refund. + */ + uint64_t rtransaction_id GNUNET_PACKED; + + /** + * Amount to be refunded, including refund fee charged by the + * exchange to the customer. + */ + struct TALER_AmountNBO refund_amount; + + /** + * Refund fee charged by the exchange. This must match the + * Exchange's denomination key's refund fee. If the client puts in + * an invalid refund fee (too high or too low) that does not match + * the Exchange's denomination key, the refund operation is invalid + * and will be rejected by the exchange. The @e amount_with_fee + * minus the @e refund_fee is the amount that will be credited to + * the original coin. + */ + struct TALER_AmountNBO refund_fee; + +}; + + /** * @brief Message signed by a coin to indicate that the coin should be * melted. -- cgit v1.2.3