diff options
Diffstat (limited to 'src/include/taler_exchange_service.h')
-rw-r--r-- | src/include/taler_exchange_service.h | 5986 |
1 files changed, 5341 insertions, 645 deletions
diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h index f95577d0c..0597799b5 100644 --- a/src/include/taler_exchange_service.h +++ b/src/include/taler_exchange_service.h @@ -1,23 +1,26 @@ /* - This file is part of TALER - Copyright (C) 2014-2021 Taler Systems SA + This file is part of TALER + Copyright (C) 2014-2024 Taler Systems SA - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU Affero General Public License as published by the Free Software - Foundation; either version 3, or (at your option) any later version. + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 3, or (at your option) any later version. - TALER is distributed in the hope that it will be useful, but WITHOUT ANY - WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. - You should have received a copy of the GNU Affero General Public License along with - TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> -*/ + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + */ /** * @file include/taler_exchange_service.h * @brief C interface of libtalerexchange, a C library to use exchange's HTTP API + * This library is not thread-safe, all APIs must only be used from a single thread. + * This library calls abort() if it runs out of memory. Be aware of these limitations. * @author Sree Harsha Totakura <sreeharsha@totakura.in> * @author Christian Grothoff + * @author Özgür Kesim */ #ifndef _TALER_EXCHANGE_SERVICE_H #define _TALER_EXCHANGE_SERVICE_H @@ -25,31 +28,17 @@ #include <jansson.h> #include "taler_util.h" #include "taler_error_codes.h" +#include "taler_kyclogic_lib.h" #include <gnunet/gnunet_curl_lib.h> -/* ********************* /keys *********************** */ - /** - * List of possible options to be passed to - * #TALER_EXCHANGE_connect(). + * Version of the Taler Exchange API, in hex. + * Thus 0.8.4-1 = 0x00080401. */ -enum TALER_EXCHANGE_Option -{ - /** - * Terminator (end of option list). - */ - TALER_EXCHANGE_OPTION_END = 0, +#define TALER_EXCHANGE_API_VERSION 0x00100000 - /** - * Followed by a "const json_t *" that was previously returned for - * this exchange URL by #TALER_EXCHANGE_serialize_data(). Used to - * resume a connection to an exchange without having to re-download - * /keys data (or at least only download the deltas). - */ - TALER_EXCHANGE_OPTION_DATA - -}; +/* ********************* /keys *********************** */ /** @@ -70,17 +59,17 @@ struct TALER_EXCHANGE_SigningPublicKey /** * Validity start time */ - struct GNUNET_TIME_Absolute valid_from; + struct GNUNET_TIME_Timestamp valid_from; /** * Validity expiration time (how long the exchange may use it). */ - struct GNUNET_TIME_Absolute valid_until; + struct GNUNET_TIME_Timestamp valid_until; /** * Validity expiration time for legal disputes. */ - struct GNUNET_TIME_Absolute valid_legal; + struct GNUNET_TIME_Timestamp valid_legal; }; @@ -97,7 +86,7 @@ struct TALER_EXCHANGE_DenomPublicKey /** * The hash of the public key. */ - struct GNUNET_HashCode h_key; + struct TALER_DenominationHashP h_key; /** * Exchange's master signature over this denomination record. @@ -107,18 +96,18 @@ struct TALER_EXCHANGE_DenomPublicKey /** * Timestamp indicating when the denomination key becomes valid */ - struct GNUNET_TIME_Absolute valid_from; + struct GNUNET_TIME_Timestamp valid_from; /** * Timestamp indicating when the denomination key can’t be used anymore to * withdraw new coins. */ - struct GNUNET_TIME_Absolute withdraw_valid_until; + struct GNUNET_TIME_Timestamp withdraw_valid_until; /** * Timestamp indicating when coins of this denomination become invalid. */ - struct GNUNET_TIME_Absolute expire_deposit; + struct GNUNET_TIME_Timestamp expire_deposit; /** * When do signatures with this denomination key become invalid? @@ -127,7 +116,7 @@ struct TALER_EXCHANGE_DenomPublicKey * of the evidence. @e expire_legal is expected to be significantly * larger than @e expire_deposit (by a year or more). */ - struct GNUNET_TIME_Absolute expire_legal; + struct GNUNET_TIME_Timestamp expire_legal; /** * The value of this denomination @@ -135,30 +124,23 @@ struct TALER_EXCHANGE_DenomPublicKey struct TALER_Amount value; /** - * The applicable fee for withdrawing a coin of this denomination + * The applicable fees for this denomination */ - struct TALER_Amount fee_withdraw; + struct TALER_DenomFeeSet fees; /** - * The applicable fee to spend a coin of this denomination - */ - struct TALER_Amount fee_deposit; - - /** - * The applicable fee to melt/refresh a coin of this denomination + * Set to true if the private denomination key has been + * lost by the exchange and thus the key cannot be + * used for withdrawing at this time. */ - struct TALER_Amount fee_refresh; - - /** - * The applicable fee to refund a coin of this denomination - */ - struct TALER_Amount fee_refund; + bool lost; /** * Set to true if this denomination key has been * revoked by the exchange. */ bool revoked; + }; @@ -219,6 +201,227 @@ struct TALER_EXCHANGE_AuditorInformation /** + * Global fees and options of an exchange for a given time period. + */ +struct TALER_EXCHANGE_GlobalFee +{ + + /** + * Signature affirming all of the data. + */ + struct TALER_MasterSignatureP master_sig; + + /** + * Starting time of the validity period (inclusive). + */ + struct GNUNET_TIME_Timestamp start_date; + + /** + * End time of the validity period (exclusive). + */ + struct GNUNET_TIME_Timestamp end_date; + + /** + * Unmerged purses will be timed out after at most this time. + */ + struct GNUNET_TIME_Relative purse_timeout; + + /** + * Account history is limited to this timeframe. + */ + struct GNUNET_TIME_Relative history_expiration; + + /** + * Fees that apply globally, independent of denomination + * and wire method. + */ + struct TALER_GlobalFeeSet fees; + + /** + * Number of free purses per account. + */ + uint32_t purse_account_limit; +}; + + +/** + * List sorted by @a start_date with fees to be paid for aggregate wire transfers. + */ +struct TALER_EXCHANGE_WireAggregateFees +{ + /** + * This is a linked list. + */ + struct TALER_EXCHANGE_WireAggregateFees *next; + + /** + * Fee to be paid whenever the exchange wires funds to the merchant. + */ + struct TALER_WireFeeSet fees; + + /** + * Time when this fee goes into effect (inclusive) + */ + struct GNUNET_TIME_Timestamp start_date; + + /** + * Time when this fee stops being in effect (exclusive). + */ + struct GNUNET_TIME_Timestamp end_date; + + /** + * Signature affirming the above fee structure. + */ + struct TALER_MasterSignatureP master_sig; +}; + + +/** + * Information about wire fees by wire method. + */ +struct TALER_EXCHANGE_WireFeesByMethod +{ + /** + * Wire method with the given @e fees. + */ + char *method; + + /** + * Linked list of wire fees the exchange charges for + * accounts of the wire @e method. + */ + struct TALER_EXCHANGE_WireAggregateFees *fees_head; + +}; + + +/** + * Type of an account restriction. + */ +enum TALER_EXCHANGE_AccountRestrictionType +{ + /** + * Invalid restriction. + */ + TALER_EXCHANGE_AR_INVALID = 0, + + /** + * Account must not be used for this operation. + */ + TALER_EXCHANGE_AR_DENY = 1, + + /** + * Other account must match given regular expression. + */ + TALER_EXCHANGE_AR_REGEX = 2 +}; + +/** + * Restrictions that apply to using a given exchange bank account. + */ +struct TALER_EXCHANGE_AccountRestriction +{ + + /** + * Type of the account restriction. + */ + enum TALER_EXCHANGE_AccountRestrictionType type; + + /** + * Restriction details depending on @e type. + */ + union + { + /** + * Details if type is #TALER_EXCHANGE_AR_REGEX. + */ + struct + { + /** + * Regular expression that the payto://-URI of the partner account must + * follow. The regular expression should follow posix-egrep, but + * without support for character classes, GNU extensions, + * back-references or intervals. See + * https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html + * for a description of the posix-egrep syntax. Applications may support + * regexes with additional features, but exchanges must not use such + * regexes. + */ + char *posix_egrep; + + /** + * Hint for a human to understand the restriction. + */ + char *human_hint; + + /** + * Internationalizations for the @e human_hint. Map from IETF BCP 47 + * language tax to localized human hints. + */ + json_t *human_hint_i18n; + } regex; + } details; + +}; + + +/** + * Information about a wire account of the exchange. + */ +struct TALER_EXCHANGE_WireAccount +{ + /** + * payto://-URI of the exchange. + */ + char *payto_uri; + + /** + * URL of a conversion service in case using this account is subject to + * currency conversion. NULL for no conversion needed. + */ + char *conversion_url; + + /** + * Array of restrictions that apply when crediting + * this account. + */ + struct TALER_EXCHANGE_AccountRestriction *credit_restrictions; + + /** + * Array of restrictions that apply when debiting + * this account. + */ + struct TALER_EXCHANGE_AccountRestriction *debit_restrictions; + + /** + * Length of the @e credit_restrictions array. + */ + unsigned int credit_restrictions_length; + + /** + * Length of the @e debit_restrictions array. + */ + unsigned int debit_restrictions_length; + + /** + * Signature of the exchange over the account (was checked by the API). + */ + struct TALER_MasterSignatureP master_sig; + + /** + * Display label for the account, can be NULL. + */ + char *bank_label; + + /** + * Priority for ordering the account in the display. + */ + int64_t priority; + +}; + + +/** * @brief Information about keys from the exchange. */ struct TALER_EXCHANGE_Keys @@ -230,6 +433,11 @@ struct TALER_EXCHANGE_Keys struct TALER_MasterPublicKeyP master_pub; /** + * Signature over extension configuration data, if any. + */ + struct TALER_MasterSignatureP extensions_sig; + + /** * Array of the exchange's online signing keys. */ struct TALER_EXCHANGE_SigningPublicKey *sign_keys; @@ -245,6 +453,16 @@ struct TALER_EXCHANGE_Keys struct TALER_EXCHANGE_AuditorInformation *auditors; /** + * Array with the global fees of the exchange. + */ + struct TALER_EXCHANGE_GlobalFee *global_fees; + + /** + * Configuration data for extensions. + */ + json_t *extensions; + + /** * Supported Taler protocol version by the exchange. * String in the format current:revision:age using the * semantics of GNU libtool. See @@ -258,6 +476,41 @@ struct TALER_EXCHANGE_Keys char *currency; /** + * What is the base URL of the exchange that returned + * these keys? + */ + char *exchange_url; + + /** + * Asset type used by the exchange. Typical values + * are "fiat" or "crypto" or "regional" or "stock". + * Wallets should adjust their UI/UX based on this + * value. + */ + char *asset_type; + + /** + * Array of amounts a wallet is allowed to hold from + * this exchange before it must undergo further KYC checks. + */ + struct TALER_Amount *wallet_balance_limit_without_kyc; + + /** + * Array of accounts of the exchange. + */ + struct TALER_EXCHANGE_WireAccount *accounts; + + /** + * Array of wire fees by wire method. + */ + struct TALER_EXCHANGE_WireFeesByMethod *fees; + + /** + * Currency rendering specification for this exchange. + */ + struct TALER_CurrencySpecification cspec; + + /** * How long after a reserve went idle will the exchange close it? * This is an approximate number, not cryptographically signed by * the exchange (advisory-only, may change anytime). @@ -267,14 +520,60 @@ struct TALER_EXCHANGE_Keys /** * Timestamp indicating the /keys generation. */ - struct GNUNET_TIME_Absolute list_issue_date; + struct GNUNET_TIME_Timestamp list_issue_date; + + /** + * When does this keys data expire? + */ + struct GNUNET_TIME_Timestamp key_data_expiration; /** * Timestamp indicating the creation time of the last * denomination key in /keys. * Used to fetch /keys incrementally. */ - struct GNUNET_TIME_Absolute last_denom_issue_date; + struct GNUNET_TIME_Timestamp last_denom_issue_date; + + /** + * If age restriction is enabled on the exchange, we get an non-zero age_mask + */ + struct TALER_AgeMask age_mask; + + /** + * Absolute STEFAN parameter. + */ + struct TALER_Amount stefan_abs; + + /** + * Logarithmic STEFAN parameter. + */ + struct TALER_Amount stefan_log; + + /** + * Linear STEFAN parameter. + */ + double stefan_lin; + + /** + * Length of @e accounts array. + */ + unsigned int accounts_len; + + /** + * Length of @e fees array. + */ + unsigned int fees_len; + + /** + * Length of the @e wallet_balance_limit_without_kyc + * array. + */ + unsigned int wblwk_length; + + /** + * Length of the @e global_fees array. + */ + unsigned int num_global_fees; /** * Length of the @e sign_keys array (number of valid entries). @@ -301,6 +600,16 @@ struct TALER_EXCHANGE_Keys */ unsigned int denom_keys_size; + /** + * Reference counter for this structure. + * Freed when it reaches 0. + */ + unsigned int rc; + + /** + * Set to true if rewards are allowed at this exchange. + */ + bool rewards_allowed; }; @@ -397,151 +706,195 @@ struct TALER_EXCHANGE_HttpResponse /** + * Response from /keys. + */ +struct TALER_EXCHANGE_KeysResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on the HTTP status code. + */ + union + { + + /** + * Details on #MHD_HTTP_OK. + */ + struct + { + /** + * Information about the various keys used by the exchange. + */ + const struct TALER_EXCHANGE_Keys *keys; + + /** + * Protocol compatibility information + */ + enum TALER_EXCHANGE_VersionCompatibility compat; + } ok; + } details; + +}; + + +/** * Function called with information about who is auditing * a particular exchange and what keys the exchange is using. + * The ownership over the @a keys object is passed to + * the callee, thus it is given explicitly and not + * (only) via @a kr. * * @param cls closure - * @param hr HTTP response data - * @param keys information about the various keys used - * by the exchange, NULL if /keys failed - * @param compat protocol compatibility information + * @param kr response from /keys + * @param[in] keys keys object passed to callback with + * reference counter of 1. Must be freed by callee + * using #TALER_EXCHANGE_keys_decref(). NULL on failure. */ typedef void -(*TALER_EXCHANGE_CertificationCallback) ( +(*TALER_EXCHANGE_GetKeysCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_EXCHANGE_Keys *keys, - enum TALER_EXCHANGE_VersionCompatibility compat); + const struct TALER_EXCHANGE_KeysResponse *kr, + struct TALER_EXCHANGE_Keys *keys); /** - * @brief Handle to the exchange. This is where we interact with - * a particular exchange and keep the per-exchange information. + * @brief Handle for a GET /keys request. */ -struct TALER_EXCHANGE_Handle; +struct TALER_EXCHANGE_GetKeysHandle; /** - * Initialise a connection to the exchange. Will connect to the - * exchange and obtain information about the exchange's master public - * key and the exchange's auditor. The respective information will - * be passed to the @a cert_cb once available, and all future - * interactions with the exchange will be checked to be signed - * (where appropriate) by the respective master key. + * Fetch the main /keys resources from an exchange. Does an incremental + * fetch if @a last_keys is given. The obtained information will be passed to + * the @a cert_cb (possibly after first merging it with @a last_keys to + * produce a full picture; expired keys (for deposit) will be removed from @a + * last_keys if there are any). * * @param ctx the context * @param url HTTP base URL for the exchange + * @param[in,out] last_keys previous keys object, NULL for none * @param cert_cb function to call with the exchange's certification information, * possibly called repeatedly if the information changes * @param cert_cb_cls closure for @a cert_cb - * @param ... list of additional arguments, terminated by #TALER_EXCHANGE_OPTION_END. * @return the exchange handle; NULL upon error */ -struct TALER_EXCHANGE_Handle * -TALER_EXCHANGE_connect (struct GNUNET_CURL_Context *ctx, - const char *url, - TALER_EXCHANGE_CertificationCallback cert_cb, - void *cert_cb_cls, - ...); +struct TALER_EXCHANGE_GetKeysHandle * +TALER_EXCHANGE_get_keys ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *last_keys, + TALER_EXCHANGE_GetKeysCallback cert_cb, + void *cert_cb_cls); /** - * Serialize the latest key data from @a exchange to be persisted - * on disk (to be used with #TALER_EXCHANGE_OPTION_DATA to more - * efficiently recover the state). + * Serialize the latest data from @a keys to be persisted + * (for example, to be used as @a last_keys later). * - * @param exchange which exchange's key and wire data should be serialized - * @return NULL on error (i.e. no current data available); otherwise - * json object owned by the caller + * @param kd the key data to serialize + * @return NULL on error; otherwise JSON object owned by the caller */ json_t * -TALER_EXCHANGE_serialize_data (struct TALER_EXCHANGE_Handle *exchange); +TALER_EXCHANGE_keys_to_json (const struct TALER_EXCHANGE_Keys *kd); /** - * Disconnect from the exchange. + * Deserialize keys data stored in @a j. * - * @param exchange the exchange handle + * @param j JSON keys data previously returned from #TALER_EXCHANGE_keys_to_json() + * @return NULL on error (i.e. invalid JSON); otherwise + * keys object with reference counter 1 owned by the caller */ -void -TALER_EXCHANGE_disconnect (struct TALER_EXCHANGE_Handle *exchange); +struct TALER_EXCHANGE_Keys * +TALER_EXCHANGE_keys_from_json (const json_t *j); /** - * Obtain the keys from the exchange. + * Cancel GET /keys operation. * - * @param exchange the exchange handle - * @return the exchange's key set + * @param[in] gkh the GET /keys handle */ -const struct TALER_EXCHANGE_Keys * -TALER_EXCHANGE_get_keys (struct TALER_EXCHANGE_Handle *exchange); +void +TALER_EXCHANGE_get_keys_cancel (struct TALER_EXCHANGE_GetKeysHandle *gkh); /** - * Let the user set the last valid denomination time manually. + * Increment reference counter for @a keys * - * @param exchange the exchange handle. - * @param last_denom_new new last denomination time. + * @param[in,out] keys object to increment reference counter for + * @return keys, with incremented reference counter */ -void -TALER_EXCHANGE_set_last_denom (struct TALER_EXCHANGE_Handle *exchange, - struct GNUNET_TIME_Absolute last_denom_new); +struct TALER_EXCHANGE_Keys * +TALER_EXCHANGE_keys_incref (struct TALER_EXCHANGE_Keys *keys); /** - * Flags for #TALER_EXCHANGE_check_keys_current(). + * Decrement reference counter for @a keys. + * Frees @a keys if reference counter becomes zero. + * + * @param[in,out] keys object to decrement reference counter for */ -enum TALER_EXCHANGE_CheckKeysFlags -{ - /** - * No special options. - */ - TALER_EXCHANGE_CKF_NONE, - - /** - * Force downloading /keys now, even if /keys is still valid - * (that is, the period advertised by the exchange for re-downloads - * has not yet expired). - */ - TALER_EXCHANGE_CKF_FORCE_DOWNLOAD = 1, - - /** - * Pull all keys again, resetting the client state to the original state. - * Using this flag disables the incremental download, and also prevents using - * the context until the re-download has completed. - */ - TALER_EXCHANGE_CKF_PULL_ALL_KEYS = 2, +void +TALER_EXCHANGE_keys_decref (struct TALER_EXCHANGE_Keys *keys); - /** - * Force downloading all keys now. - */ - TALER_EXCHANGE_CKF_FORCE_ALL_NOW = TALER_EXCHANGE_CKF_FORCE_DOWNLOAD - | TALER_EXCHANGE_CKF_PULL_ALL_KEYS -}; +/** + * Use STEFAN curve in @a keys to convert @a brut to @a net. Computes the + * expected minimum (!) @a net amount that should for sure arrive in the + * target amount at cost of @a brut to the wallet. Note that STEFAN curves by + * design over-estimate actual fees and a wallet may be able to achieve the + * same @a net amount with less fees --- or if the available coins are + * abnormal in structure, it may take more. + * + * @param keys exchange key data + * @param brut gross amount (actual cost including fees) + * @param[out] net net amount (effective amount) + * @return #GNUNET_OK on success, #GNUNET_NO if the + * resulting @a net is zero (or lower) + */ +enum GNUNET_GenericReturnValue +TALER_EXCHANGE_keys_stefan_b2n ( + const struct TALER_EXCHANGE_Keys *keys, + const struct TALER_Amount *brut, + struct TALER_Amount *net); /** - * Check if our current response for /keys is valid, and if - * not, trigger /keys download. + * Use STEFAN curve in @a keys to convert @a net to @a brut. Computes the + * expected maximum (!) @a brut amount that should be needed in the wallet to + * transfer @a net amount to the target account. Note that STEFAN curves by + * design over-estimate actual fees and a wallet may be able to achieve the + * same @a net amount with less fees --- or if the available coins are + * abnormal in structure, it may take more. * - * @param exchange exchange to check keys for - * @param flags options controlling when to download what - * @return until when the existing response is current, 0 if we are re-downloading now - */ -struct GNUNET_TIME_Absolute -TALER_EXCHANGE_check_keys_current (struct TALER_EXCHANGE_Handle *exchange, - enum TALER_EXCHANGE_CheckKeysFlags flags); + * @param keys exchange key data + * @param net net amount (effective amount) + * @param[out] brut gross amount (actual cost including fees) + * @return #GNUNET_OK on success, #GNUNET_NO if the + * resulting @a brut is zero (only if @a net was zero) + */ +enum GNUNET_GenericReturnValue +TALER_EXCHANGE_keys_stefan_n2b ( + const struct TALER_EXCHANGE_Keys *keys, + const struct TALER_Amount *net, + struct TALER_Amount *brut); /** - * Obtain the keys from the exchange in the raw JSON format. + * Round brutto or netto value computed via STEFAN + * curve to decimal places commonly used at the exchange. * - * @param exchange the exchange handle - * @return the exchange's keys in raw JSON + * @param keys exchange keys response data + * @param[in,out] val value to round */ -json_t * -TALER_EXCHANGE_get_keys_raw (struct TALER_EXCHANGE_Handle *exchange); +void +TALER_EXCHANGE_keys_stefan_round ( + const struct TALER_EXCHANGE_Keys *keys, + struct TALER_Amount *val); /** @@ -552,19 +905,10 @@ TALER_EXCHANGE_get_keys_raw (struct TALER_EXCHANGE_Handle *exchange); * @param pub claimed current online signing key for the exchange * @return #GNUNET_OK if @a pub is (according to /keys) a current signing key */ -int -TALER_EXCHANGE_test_signing_key (const struct TALER_EXCHANGE_Keys *keys, - const struct TALER_ExchangePublicKeyP *pub); - - -/** - * Get exchange's base URL. - * - * @param exchange exchange handle. - * @return the base URL from the handle. - */ -const char * -TALER_EXCHANGE_get_base_url (const struct TALER_EXCHANGE_Handle *exchange); +enum GNUNET_GenericReturnValue +TALER_EXCHANGE_test_signing_key ( + const struct TALER_EXCHANGE_Keys *keys, + const struct TALER_ExchangePublicKeyP *pub); /** @@ -582,10 +926,24 @@ TALER_EXCHANGE_get_denomination_key ( /** + * Obtain the global fee details from the exchange. + * + * @param keys the exchange's key set + * @param ts time for when to fetch the fees + * @return details about the fees, NULL if no fees are known at @a ts + */ +const struct TALER_EXCHANGE_GlobalFee * +TALER_EXCHANGE_get_global_fee ( + const struct TALER_EXCHANGE_Keys *keys, + struct GNUNET_TIME_Timestamp ts); + + +/** * Create a copy of a denomination public key. * * @param key key to copy - * @returns a copy, must be freed with #TALER_EXCHANGE_destroy_denomination_key + * @returns a copy, must be freed with #TALER_EXCHANGE_destroy_denomination_key() + * @deprecated */ struct TALER_EXCHANGE_DenomPublicKey * TALER_EXCHANGE_copy_denomination_key ( @@ -594,9 +952,10 @@ TALER_EXCHANGE_copy_denomination_key ( /** * Destroy a denomination public key. - * Should only be called with keys created by #TALER_EXCHANGE_copy_denomination_key. + * Should only be called with keys created by #TALER_EXCHANGE_copy_denomination_key(). * * @param key key to destroy. + * @deprecated */ void TALER_EXCHANGE_destroy_denomination_key ( @@ -613,7 +972,7 @@ TALER_EXCHANGE_destroy_denomination_key ( const struct TALER_EXCHANGE_DenomPublicKey * TALER_EXCHANGE_get_denomination_key_by_hash ( const struct TALER_EXCHANGE_Keys *keys, - const struct GNUNET_HashCode *hc); + const struct TALER_DenominationHashP *hc); /** @@ -630,167 +989,209 @@ TALER_EXCHANGE_get_signing_key_info ( const struct TALER_ExchangePublicKeyP *exchange_pub); -/* ********************* /wire *********************** */ +/* ********************* wire helpers *********************** */ /** - * Sorted list of fees to be paid for aggregate wire transfers. + * Parse array of @a accounts of the exchange into @a was. + * + * @param master_pub master public key of the exchange, NULL to not verify signatures + * @param accounts array of accounts to parse + * @param[out] was where to write the result (already allocated) + * @param was_length length of the @a was array, must match the length of @a accounts + * @return #GNUNET_OK if parsing @a accounts succeeded */ -struct TALER_EXCHANGE_WireAggregateFees +enum GNUNET_GenericReturnValue +TALER_EXCHANGE_parse_accounts ( + const struct TALER_MasterPublicKeyP *master_pub, + const json_t *accounts, + unsigned int was_length, + struct TALER_EXCHANGE_WireAccount was[static was_length]); + + +/** + * Free data within @a was, but not @a was itself. + * + * @param was array of wire account data + * @param was_len length of the @a was array + */ +void +TALER_EXCHANGE_free_accounts ( + unsigned int was_len, + struct TALER_EXCHANGE_WireAccount was[static was_len]); + + +/* ********************* /coins/$COIN_PUB/deposit *********************** */ + + +/** + * Information needed for a coin to be deposited. + */ +struct TALER_EXCHANGE_CoinDepositDetail { + /** - * This is a linked list. + * The amount to be deposited. */ - struct TALER_EXCHANGE_WireAggregateFees *next; + struct TALER_Amount amount; /** - * Fee to be paid whenever the exchange wires funds to the merchant. + * Hash over the age commitment of the coin. */ - struct TALER_Amount wire_fee; + struct TALER_AgeCommitmentHash h_age_commitment; /** - * Fee to be paid when the exchange closes a reserve and wires funds - * back to a customer. + * The coin’s public key. */ - struct TALER_Amount closing_fee; + struct TALER_CoinSpendPublicKeyP coin_pub; /** - * Time when this fee goes into effect (inclusive) + * The signature made with purpose #TALER_SIGNATURE_WALLET_COIN_DEPOSIT made + * by the customer with the coin’s private key. */ - struct GNUNET_TIME_Absolute start_date; + struct TALER_CoinSpendSignatureP coin_sig; /** - * Time when this fee stops being in effect (exclusive). + * Exchange’s unblinded signature of the coin. */ - struct GNUNET_TIME_Absolute end_date; + struct TALER_DenominationSignature denom_sig; /** - * Signature affirming the above fee structure. + * Hash of the public key of the coin. */ - struct TALER_MasterSignatureP master_sig; + struct TALER_DenominationHashP h_denom_pub; }; /** - * Information about a wire account of the exchange. + * Meta information about the contract relevant for a coin's deposit + * operation. */ -struct TALER_EXCHANGE_WireAccount +struct TALER_EXCHANGE_DepositContractDetail { + /** - * payto://-URI of the exchange. + * Hash of the contact of the merchant with the customer (further details + * are never disclosed to the exchange) */ - const char *payto_uri; + struct TALER_PrivateContractHashP h_contract_terms; /** - * Signature of the exchange over the account (was checked by the API). + * The public key of the merchant (used to identify the merchant for refund + * requests). */ - struct TALER_MasterSignatureP master_sig; + struct TALER_MerchantPublicKeyP merchant_pub; /** - * Linked list of wire fees the exchange charges for - * accounts of the wire method matching @e payto_uri. + * Salt used to hash the @e merchant_payto_uri. */ - const struct TALER_EXCHANGE_WireAggregateFees *fees; + struct TALER_WireSaltP wire_salt; -}; + /** + * Hash over data provided by the wallet to customize the contract. + * All zero if not used. + */ + struct GNUNET_HashCode wallet_data_hash; + /** + * Date until which the merchant can issue a refund to the customer via the + * exchange (can be zero if refunds are not allowed); must not be after the + * @e wire_deadline. + */ + struct GNUNET_TIME_Timestamp refund_deadline; -/** - * Callbacks of this type are used to serve the result of submitting a - * wire format inquiry request to a exchange. - * - * If the request fails to generate a valid response from the - * exchange, @a http_status will also be zero. - * - * @param cls closure - * @param hr HTTP response data - * @param accounts_len length of the @a accounts array - * @param accounts list of wire accounts of the exchange, NULL on error - */ -typedef void -(*TALER_EXCHANGE_WireCallback) ( - void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - unsigned int accounts_len, - const struct TALER_EXCHANGE_WireAccount *accounts); + /** + * Execution date, until which the merchant would like the exchange to + * settle the balance (advisory, the exchange cannot be forced to settle in + * the past or upon very short notice, but of course a well-behaved exchange + * will limit aggregation based on the advice received). + */ + struct GNUNET_TIME_Timestamp wire_deadline; + /** + * Timestamp when the contract was finalized, must match approximately the + * current time of the exchange. + */ + struct GNUNET_TIME_Timestamp wallet_timestamp; -/** - * @brief A Wire format inquiry handle - */ -struct TALER_EXCHANGE_WireHandle; + /** + * The merchant’s account details, in the payto://-format supported by the + * exchange. + */ + const char *merchant_payto_uri; + + /** + * Policy extension specific details about the deposit relevant to the exchange. + */ + const json_t *policy_details; + +}; /** - * Obtain information about a exchange's wire instructions. A - * exchange may provide wire instructions for creating a reserve. The - * wire instructions also indicate which wire formats merchants may - * use with the exchange. This API is typically used by a wallet for - * wiring funds, and possibly by a merchant to determine supported - * wire formats. - * - * Note that while we return the (main) 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. - * - * @param exchange the exchange handle; the exchange must be ready to operate - * @param wire_cb the callback to call when a reply for this request is available - * @param wire_cb_cls closure for the above callback - * @return a handle for this request + * @brief A Batch Deposit Handle */ -struct TALER_EXCHANGE_WireHandle * -TALER_EXCHANGE_wire (struct TALER_EXCHANGE_Handle *exchange, - TALER_EXCHANGE_WireCallback wire_cb, - void *wire_cb_cls); +struct TALER_EXCHANGE_BatchDepositHandle; /** - * Cancel a wire information request. This function cannot be used - * on a request handle if a response is already served for it. - * - * @param wh the wire information request handle + * Structure with information about a batch deposit + * operation's result. */ -void -TALER_EXCHANGE_wire_cancel (struct TALER_EXCHANGE_WireHandle *wh); +struct TALER_EXCHANGE_BatchDepositResult +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + union + { -/* ********************* /coins/$COIN_PUB/deposit *********************** */ + /** + * Information returned if the HTTP status is + * #MHD_HTTP_OK. + */ + struct + { + /** + * Time when the exchange generated the batch deposit confirmation + */ + struct GNUNET_TIME_Timestamp deposit_timestamp; + /** + * Deposit confirmation signature provided by the exchange + */ + const struct TALER_ExchangeSignatureP *exchange_sig; -/** - * Sign a deposit permission. Function for wallets. - * - * @param amount the amount to be deposited - * @param deposit_fee the deposit fee we expect to pay - * @param h_wire hash of the merchant’s account details - * @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the exchange) - * @param h_denom_pub hash of the coin denomination's public key - * @param coin_priv coin’s private key - * @param wallet_timestamp timestamp when the contract was finalized, must not be too far in the future - * @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests) - * @param refund_deadline date until which the merchant can issue a refund to the customer via the exchange (can be zero if refunds are not allowed); must not be after the @a wire_deadline - * @param[out] coin_sig set to the signature made with purpose #TALER_SIGNATURE_WALLET_COIN_DEPOSIT - */ -void -TALER_EXCHANGE_deposit_permission_sign ( - const struct TALER_Amount *amount, - const struct TALER_Amount *deposit_fee, - const struct GNUNET_HashCode *h_wire, - const struct GNUNET_HashCode *h_contract_terms, - const struct GNUNET_HashCode *h_denom_pub, - const struct TALER_CoinSpendPrivateKeyP *coin_priv, - struct GNUNET_TIME_Absolute wallet_timestamp, - const struct TALER_MerchantPublicKeyP *merchant_pub, - struct GNUNET_TIME_Absolute refund_deadline, - struct TALER_CoinSpendSignatureP *coin_sig); + /** + * exchange key used to sign @a exchange_sig. + */ + const struct TALER_ExchangePublicKeyP *exchange_pub; + /** + * Base URL for looking up wire transfers, or + * NULL to use the default base URL. + */ + const char *transaction_base_url; -/** - * @brief A Deposit Handle - */ -struct TALER_EXCHANGE_DepositHandle; + } ok; + + /** + * Information returned if the HTTP status is + * #MHD_HTTP_CONFLICT. + */ + struct + { + /** + * The coin that had a conflict. + */ + struct TALER_CoinSpendPublicKeyP coin_pub; + + } conflict; + + } details; +}; /** @@ -798,90 +1199,73 @@ struct TALER_EXCHANGE_DepositHandle; * deposit permission request to a exchange. * * @param cls closure - * @param hr HTTP response data - * @param deposit_timestamp time when the exchange generated the deposit confirmation - * @param exchange_sig signature provided by the exchange - * @param exchange_pub exchange key used to sign @a obj, or NULL + * @param dr deposit response details */ typedef void -(*TALER_EXCHANGE_DepositResultCallback) ( +(*TALER_EXCHANGE_BatchDepositResultCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - struct GNUNET_TIME_Absolute deposit_timestamp, - const struct TALER_ExchangeSignatureP *exchange_sig, - const struct TALER_ExchangePublicKeyP *exchange_pub); + const struct TALER_EXCHANGE_BatchDepositResult *dr); /** - * Submit a deposit permission to the exchange and get the exchange's - * response. This API is typically 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. + * Submit a batch of deposit permissions to the exchange and get the + * exchange's response. This API is typically 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. * - * We also verify that the @a coin_sig is valid for this deposit - * request, and that the @a ub_sig is a valid signature for @a + * We also verify that the @a cdds.coin_sig are valid for this deposit + * request, and that the @a cdds.ub_sig are a valid signatures for @a * coin_pub. Also, the @a exchange must be ready to operate (i.e. have * finished processing the /keys reply). If either 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 deposited - * @param wire_deadline execution date, until which the merchant would like the exchange to settle the balance (advisory, the exchange cannot be - * forced to settle in the past or upon very short notice, but of course a well-behaved exchange will limit aggregation based on the advice received) - * @param wire_details the merchant’s account details, in a format supported by the exchange - * @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the exchange) - * @param coin_pub coin’s public key - * @param denom_pub denomination key with which the coin is signed - * @param denom_sig exchange’s unblinded signature of the coin - * @param timestamp timestamp when the contract was finalized, must match approximately the current time of the exchange - * @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests) - * @param refund_deadline date until which the merchant can issue a refund to the customer via the exchange (can be zero if refunds are not allowed); must not be after the @a wire_deadline - * @param coin_sig the signature made with purpose #TALER_SIGNATURE_WALLET_COIN_DEPOSIT made by the customer with the coin’s private key. + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param dcd details about the contract the deposit is for + * @param num_cdds length of the @a cdds array + * @param cdds array with details about the coins to be deposited * @param cb the callback to call when a reply for this request is available * @param cb_cls closure for the above callback * @param[out] ec if NULL is returned, set to the error code explaining why the operation failed * @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_DepositHandle * -TALER_EXCHANGE_deposit (struct TALER_EXCHANGE_Handle *exchange, - const struct TALER_Amount *amount, - struct GNUNET_TIME_Absolute wire_deadline, - json_t *wire_details, - const struct GNUNET_HashCode *h_contract_terms, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - const struct TALER_DenominationSignature *denom_sig, - const struct TALER_DenominationPublicKey *denom_pub, - struct GNUNET_TIME_Absolute timestamp, - const struct TALER_MerchantPublicKeyP *merchant_pub, - struct GNUNET_TIME_Absolute refund_deadline, - const struct TALER_CoinSpendSignatureP *coin_sig, - TALER_EXCHANGE_DepositResultCallback cb, - void *cb_cls, - enum TALER_ErrorCode *ec); +struct TALER_EXCHANGE_BatchDepositHandle * +TALER_EXCHANGE_batch_deposit ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_EXCHANGE_DepositContractDetail *dcd, + unsigned int num_cdds, + const struct TALER_EXCHANGE_CoinDepositDetail cdds[static num_cdds], + TALER_EXCHANGE_BatchDepositResultCallback cb, + void *cb_cls, + enum TALER_ErrorCode *ec); /** * Change the chance that our deposit confirmation will be given to the * auditor to 100%. * - * @param deposit the deposit permission request handle + * @param[in,out] deposit the batch deposit permission request handle */ void -TALER_EXCHANGE_deposit_force_dc (struct TALER_EXCHANGE_DepositHandle *deposit); +TALER_EXCHANGE_batch_deposit_force_dc ( + struct TALER_EXCHANGE_BatchDepositHandle *deposit); /** - * Cancel a deposit permission request. This function cannot be used + * Cancel a batch deposit permission request. This function cannot be used * on a request handle if a response is already served for it. * - * @param deposit the deposit permission request handle + * @param[in] deposit the deposit permission request handle */ void -TALER_EXCHANGE_deposit_cancel (struct TALER_EXCHANGE_DepositHandle *deposit); +TALER_EXCHANGE_batch_deposit_cancel ( + struct TALER_EXCHANGE_BatchDepositHandle *deposit); /* ********************* /coins/$COIN_PUB/refund *********************** */ @@ -891,23 +1275,51 @@ TALER_EXCHANGE_deposit_cancel (struct TALER_EXCHANGE_DepositHandle *deposit); */ struct TALER_EXCHANGE_RefundHandle; +/** + * Response from the /refund API. + */ +struct TALER_EXCHANGE_RefundResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Response details depending on the HTTP status code. + */ + union + { + /** + * Details on #MHD_HTTP_OK. + */ + struct + { + /** + * Exchange key used to sign. + */ + struct TALER_ExchangePublicKeyP exchange_pub; + + /** + * The actual signature + */ + struct TALER_ExchangeSignatureP exchange_sig; + } ok; + } details; +}; + /** * Callbacks of this type are used to serve the result of submitting a * refund request to an exchange. * * @param cls closure - * @param hr HTTP response data - * @param sign_key exchange key used to sign @a obj, or NULL - * @param signature the actual signature, or NULL on error + * @param rr refund response */ typedef void (*TALER_EXCHANGE_RefundCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_ExchangePublicKeyP *sign_key, - const struct TALER_ExchangeSignatureP *signature); - + const struct TALER_EXCHANGE_RefundResponse *rr); /** * Submit a refund request to the exchange and get the exchange's response. @@ -921,7 +1333,9 @@ typedef void * 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 ctx curl context + * @param url exchange base URL + * @param keys exchange keys * @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 @@ -938,14 +1352,17 @@ typedef void * 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_terms, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - uint64_t rtransaction_id, - const struct TALER_MerchantPrivateKeyP *merchant_priv, - TALER_EXCHANGE_RefundCallback cb, - void *cb_cls); +TALER_EXCHANGE_refund ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_Amount *amount, + const struct TALER_PrivateContractHashP *h_contract_terms, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + uint64_t rtransaction_id, + const struct TALER_MerchantPrivateKeyP *merchant_priv, + TALER_EXCHANGE_RefundCallback cb, + void *cb_cls); /** @@ -960,15 +1377,548 @@ void TALER_EXCHANGE_refund_cancel (struct TALER_EXCHANGE_RefundHandle *refund); -/* ********************* GET /reserves/$RESERVE_PUB *********************** */ +/* ********************* POST /csr-melt *********************** */ /** - * @brief A /reserves/ GET Handle + * @brief A /csr-melt Handle */ -struct TALER_EXCHANGE_ReservesGetHandle; +struct TALER_EXCHANGE_CsRMeltHandle; + + +/** + * Details about a response for a CS R request. + */ +struct TALER_EXCHANGE_CsRMeltResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details about the response. + */ + union + { + /** + * Details if the status is #MHD_HTTP_OK. + */ + struct + { + /** + * Length of the @e alg_values array. + */ + unsigned int alg_values_len; + + /** + * Values contributed by the exchange for the + * respective coin's withdraw operation. + */ + const struct TALER_ExchangeWithdrawValues *alg_values; + } ok; + + /** + * Details if the status is #MHD_HTTP_GONE. + */ + struct + { + /* FIXME: returning full details is not implemented */ + } gone; + + } details; +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * CS R request to a exchange. + * + * @param cls closure + * @param csrr response details + */ +typedef void +(*TALER_EXCHANGE_CsRMeltCallback) ( + void *cls, + const struct TALER_EXCHANGE_CsRMeltResponse *csrr); + + +/** + * Information we pass per coin to a /csr-melt request. + */ +struct TALER_EXCHANGE_NonceKey +{ + /** + * Which denomination key is the /csr-melt request for? + */ + const struct TALER_EXCHANGE_DenomPublicKey *pk; + + /** + * What is number to derive the client nonce for the + * fresh coin? + */ + uint32_t cnc_num; +}; + + +/** + * Get a set of CS R values using a /csr-melt request. + * + * @param ctx curl context + * @param url exchange base URL + * @param rms master key used for the derivation of the CS values + * @param nks_len length of the @a nks array + * @param nks array of denominations and nonces + * @param res_cb the callback to call when the final result for this request is available + * @param res_cb_cls closure for the above callback + * @return handle for the operation on success, NULL on error, i.e. + * if the inputs are invalid (i.e. denomination key not with this exchange). + * In this case, the callback is not called. + */ +struct TALER_EXCHANGE_CsRMeltHandle * +TALER_EXCHANGE_csr_melt ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_RefreshMasterSecretP *rms, + unsigned int nks_len, + struct TALER_EXCHANGE_NonceKey nks[static nks_len], + TALER_EXCHANGE_CsRMeltCallback res_cb, + void *res_cb_cls); + + +/** + * + * Cancel a CS R melt request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param csrh the withdraw handle + */ +void +TALER_EXCHANGE_csr_melt_cancel (struct TALER_EXCHANGE_CsRMeltHandle *csrh); + + +/* ********************* POST /csr-withdraw *********************** */ + + +/** + * @brief A /csr-withdraw Handle + */ +struct TALER_EXCHANGE_CsRWithdrawHandle; + + +/** + * Details about a response for a CS R request. + */ +struct TALER_EXCHANGE_CsRWithdrawResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details about the response. + */ + union + { + /** + * Details if the status is #MHD_HTTP_OK. + */ + struct + { + /** + * Values contributed by the exchange for the + * respective coin's withdraw operation. + */ + struct TALER_ExchangeWithdrawValues alg_values; + + } ok; + + /** + * Details if the status is #MHD_HTTP_GONE. + */ + struct + { + /* TODO: returning full details is not implemented */ + } gone; + + } details; +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * CS R withdraw request to a exchange. + * + * @param cls closure + * @param csrr response details + */ +typedef void +(*TALER_EXCHANGE_CsRWithdrawCallback) ( + void *cls, + const struct TALER_EXCHANGE_CsRWithdrawResponse *csrr); + + +/** + * Get a CS R using a /csr-withdraw request. + * + * @param curl_ctx The curl context to use for the requests + * @param exchange_url Base-URL to the excnange + * @param pk Which denomination key is the /csr request for + * @param nonce client nonce for the request + * @param res_cb the callback to call when the final result for this request is available + * @param res_cb_cls closure for the above callback + * @return handle for the operation on success, NULL on error, i.e. + * if the inputs are invalid (i.e. denomination key not with this exchange). + * In this case, the callback is not called. + */ +struct TALER_EXCHANGE_CsRWithdrawHandle * +TALER_EXCHANGE_csr_withdraw ( + struct GNUNET_CURL_Context *curl_ctx, + const char *exchange_url, + const struct TALER_EXCHANGE_DenomPublicKey *pk, + const struct GNUNET_CRYPTO_CsSessionNonce *nonce, + TALER_EXCHANGE_CsRWithdrawCallback res_cb, + void *res_cb_cls); + + +/** + * + * Cancel a CS R withdraw request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param csrh the withdraw handle + */ +void +TALER_EXCHANGE_csr_withdraw_cancel ( + struct TALER_EXCHANGE_CsRWithdrawHandle *csrh); +/* ********************* GET /coins/$COIN_PUB *********************** */ + +/** + * Ways how a coin's balance may change. + */ +enum TALER_EXCHANGE_CoinTransactionType +{ + + /** + * Reserved for uninitialized / none. + */ + TALER_EXCHANGE_CTT_NONE, + + /** + * Deposit into a contract. + */ + TALER_EXCHANGE_CTT_DEPOSIT, + + /** + * Spent on melt. + */ + TALER_EXCHANGE_CTT_MELT, + + /** + * Refunded by merchant. + */ + TALER_EXCHANGE_CTT_REFUND, + + /** + * Debited in recoup (to reserve) operation. + */ + TALER_EXCHANGE_CTT_RECOUP, + + /** + * Debited in recoup-and-refresh operation. + */ + TALER_EXCHANGE_CTT_RECOUP_REFRESH, + + /** + * Credited in recoup-refresh. + */ + TALER_EXCHANGE_CTT_OLD_COIN_RECOUP, + + /** + * Deposited into purse. + */ + TALER_EXCHANGE_CTT_PURSE_DEPOSIT, + + /** + * Refund from purse. + */ + TALER_EXCHANGE_CTT_PURSE_REFUND, + + /** + * Reserve open payment operation. + */ + TALER_EXCHANGE_CTT_RESERVE_OPEN_DEPOSIT + +}; + + +/** + * @brief Entry in the coin's transaction history. + */ +struct TALER_EXCHANGE_CoinHistoryEntry +{ + + /** + * Type of the transaction. + */ + enum TALER_EXCHANGE_CoinTransactionType type; + + /** + * Amount transferred (in or out). + */ + struct TALER_Amount amount; + + /** + * Details depending on @e type. + */ + union + { + + struct + { + struct TALER_MerchantWireHashP h_wire; + struct TALER_PrivateContractHashP h_contract_terms; + struct TALER_ExtensionPolicyHashP h_policy; + bool no_h_policy; + struct GNUNET_HashCode wallet_data_hash; + bool no_wallet_data_hash; + struct GNUNET_TIME_Timestamp wallet_timestamp; + struct TALER_MerchantPublicKeyP merchant_pub; + struct GNUNET_TIME_Timestamp refund_deadline; + struct TALER_CoinSpendSignatureP sig; + struct TALER_AgeCommitmentHash hac; + bool no_hac; + struct TALER_Amount deposit_fee; + } deposit; + + struct + { + struct TALER_CoinSpendSignatureP sig; + struct TALER_RefreshCommitmentP rc; + struct TALER_AgeCommitmentHash h_age_commitment; + bool no_hac; + struct TALER_Amount melt_fee; + } melt; + + struct + { + struct TALER_PrivateContractHashP h_contract_terms; + struct TALER_MerchantPublicKeyP merchant_pub; + struct TALER_MerchantSignatureP sig; + struct TALER_Amount refund_fee; + struct TALER_Amount sig_amount; + uint64_t rtransaction_id; + } refund; + + struct + { + struct TALER_ReservePublicKeyP reserve_pub; + struct GNUNET_TIME_Timestamp timestamp; + union GNUNET_CRYPTO_BlindingSecretP coin_bks; + struct TALER_ExchangePublicKeyP exchange_pub; + struct TALER_ExchangeSignatureP exchange_sig; + struct TALER_CoinSpendSignatureP coin_sig; + } recoup; + + struct + { + struct TALER_CoinSpendPublicKeyP old_coin_pub; + union GNUNET_CRYPTO_BlindingSecretP coin_bks; + struct GNUNET_TIME_Timestamp timestamp; + struct TALER_ExchangePublicKeyP exchange_pub; + struct TALER_ExchangeSignatureP exchange_sig; + struct TALER_CoinSpendSignatureP coin_sig; + } recoup_refresh; + + struct + { + struct TALER_ExchangePublicKeyP exchange_pub; + struct TALER_ExchangeSignatureP exchange_sig; + struct TALER_CoinSpendPublicKeyP new_coin_pub; + struct GNUNET_TIME_Timestamp timestamp; + } old_coin_recoup; + + struct + { + struct TALER_PurseContractPublicKeyP purse_pub; + struct TALER_CoinSpendSignatureP coin_sig; + const char *exchange_base_url; + bool refunded; + struct TALER_AgeCommitmentHash phac; + } purse_deposit; + + struct + { + struct TALER_PurseContractPublicKeyP purse_pub; + struct TALER_Amount refund_fee; + struct TALER_ExchangePublicKeyP exchange_pub; + struct TALER_ExchangeSignatureP exchange_sig; + } purse_refund; + + struct + { + struct TALER_ReserveSignatureP reserve_sig; + struct TALER_CoinSpendSignatureP coin_sig; + } reserve_open_deposit; + + } details; + +}; + + +/** + * @brief A /coins/$RID/history Handle + */ +struct TALER_EXCHANGE_CoinsHistoryHandle; + + +/** + * Parses and verifies a coin's transaction history as + * returned by the exchange. Note that in case of + * incremental histories, the client must first combine + * the incremental histories into one complete history. + * + * @param keys /keys data of the exchange + * @param dk denomination key of the coin + * @param history JSON array with the coin's history + * @param coin_pub public key of the coin + * @param[out] total_in set to total amount credited to the coin in @a history + * @param[out] total_out set to total amount debited to the coin in @a history + * @param rlen length of the @a rhistory array + * @param[out] rhistory array where to write the parsed @a history + * @return #GNUNET_OK if @a history is valid, + * #GNUNET_SYSERR if not + */ +enum GNUNET_GenericReturnValue +TALER_EXCHANGE_parse_coin_history ( + const struct TALER_EXCHANGE_Keys *keys, + const struct TALER_EXCHANGE_DenomPublicKey *dk, + const json_t *history, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + struct TALER_Amount *total_in, + struct TALER_Amount *total_out, + unsigned int rlen, + struct TALER_EXCHANGE_CoinHistoryEntry rhistory[static rlen]); + + +/** + * Verify that @a coin_sig does NOT appear in the @a history of a coin's + * transactions and thus whatever transaction is authorized by @a coin_sig is + * a conflict with @a proof. + * + * @param history coin history to check + * @param coin_sig signature that must not be in @a history + * @return #GNUNET_OK if @a coin_sig is not in @a history + */ +enum GNUNET_GenericReturnValue +TALER_EXCHANGE_check_coin_signature_conflict ( + const json_t *history, + const struct TALER_CoinSpendSignatureP *coin_sig); + + +/** + * Response to a GET /coins/$COIN_PUB/history request. + */ +struct TALER_EXCHANGE_CoinHistory +{ + /** + * High-level HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on @e hr.http_status. + */ + union + { + + /** + * Information returned on success, if + * @e hr.http_status is #MHD_HTTP_OK + */ + struct + { + + /** + * Coin transaction history (possibly partial). + * Not yet validated, combine with other already + * known history data for this coin and then use + * #TALER_EXCHANGE_parse_coin_history() to validate + * the complete history and obtain it in binary + * format. + */ + const json_t *history; + + /** + * The hash of the coin denomination's public key + */ + struct TALER_DenominationHashP h_denom_pub; + + /** + * Coin balance. + */ + struct TALER_Amount balance; + + } ok; + + } details; + +}; + + +/** + * Signature of functions called with the result of + * a coin transaction history request. + * + * @param cls closure + * @param ch transaction history for the coin + */ +typedef void +(*TALER_EXCHANGE_CoinsHistoryCallback)( + void *cls, + const struct TALER_EXCHANGE_CoinHistory *ch); + + +/** + * Parses and verifies a coin's transaction history as + * returned by the exchange. Note that a client may + * have to combine multiple partial coin histories + * into one coherent history before calling this function. + * + * @param ctx context for managing request + * @param url base URL of the exchange + * @param coin_priv private key of the coin + * @param start_off offset from which on to request history + * @param cb function to call with results + * @param cb_cls closure for @a cb + * @return #GNUNET_OK if @a history is valid, + * #GNUNET_SYSERR if not + */ +struct TALER_EXCHANGE_CoinsHistoryHandle * +TALER_EXCHANGE_coins_history ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_CoinSpendPrivateKeyP *coin_priv, + uint64_t start_off, + TALER_EXCHANGE_CoinsHistoryCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_coins_history() operation. + * + * @param[in] rsh operation to cancel + */ +void +TALER_EXCHANGE_coins_history_cancel ( + struct TALER_EXCHANGE_CoinsHistoryHandle *rsh); + + +/* ********************* GET /reserves/$RESERVE_PUB *********************** */ + /** * Ways how a reserve's balance may change. */ @@ -986,6 +1936,11 @@ enum TALER_EXCHANGE_ReserveTransactionType TALER_EXCHANGE_RTT_WITHDRAWAL, /** + * Age-Withdrawal from the reserve. + */ + TALER_EXCHANGE_RTT_AGEWITHDRAWAL, + + /** * /recoup operation. */ TALER_EXCHANGE_RTT_RECOUP, @@ -993,6 +1948,21 @@ enum TALER_EXCHANGE_ReserveTransactionType /** * Reserve closed operation. */ + TALER_EXCHANGE_RTT_CLOSING, + + /** + * Reserve purse merge operation. + */ + TALER_EXCHANGE_RTT_MERGE, + + /** + * Reserve open request operation. + */ + TALER_EXCHANGE_RTT_OPEN, + + /** + * Reserve close request operation. + */ TALER_EXCHANGE_RTT_CLOSE }; @@ -1001,7 +1971,7 @@ enum TALER_EXCHANGE_ReserveTransactionType /** * @brief Entry in the reserve's transaction history. */ -struct TALER_EXCHANGE_ReserveHistory +struct TALER_EXCHANGE_ReserveHistoryEntry { /** @@ -1039,7 +2009,7 @@ struct TALER_EXCHANGE_ReserveHistory /** * When did the wire transfer happen? */ - struct GNUNET_TIME_Absolute timestamp; + struct GNUNET_TIME_Timestamp timestamp; } in_details; @@ -1061,6 +2031,28 @@ struct TALER_EXCHANGE_ReserveHistory } withdraw; /** + * Information about withdraw operation. + * @e type is #TALER_EXCHANGE_RTT_AGEWITHDRAWAL. + */ + struct + { + /** + * Signature authorizing the withdrawal for outgoing transaction. + */ + json_t *out_authorization_sig; + + /** + * Maximum age committed + */ + uint8_t max_age; + + /** + * Fee that was charged for the withdrawal. + */ + struct TALER_Amount fee; + } age_withdraw; + + /** * Information provided if the reserve was filled via /recoup. * @e type is #TALER_EXCHANGE_RTT_RECOUP. */ @@ -1086,7 +2078,7 @@ struct TALER_EXCHANGE_ReserveHistory /** * When did the /recoup operation happen? */ - struct GNUNET_TIME_Absolute timestamp; + struct GNUNET_TIME_Timestamp timestamp; } recoup_details; @@ -1097,7 +2089,7 @@ struct TALER_EXCHANGE_ReserveHistory struct { /** - * Receiver account information for the outgoing wire transfer. + * Receiver account information for the outgoing wire transfer as a payto://-URI. */ const char *receiver_account_details; @@ -1120,7 +2112,7 @@ struct TALER_EXCHANGE_ReserveHistory /** * When did the wire transfer happen? */ - struct GNUNET_TIME_Absolute timestamp; + struct GNUNET_TIME_Timestamp timestamp; /** * Fee that was charged for the closing. @@ -1129,6 +2121,173 @@ struct TALER_EXCHANGE_ReserveHistory } close_details; + /** + * Information about a merge operation on the reserve. + * @e type is #TALER_EXCHANGE_RTT_MERGE. + */ + struct + { + + /** + * Fee paid for the purse. + */ + struct TALER_Amount purse_fee; + + /** + * Hash over the contract. + */ + struct TALER_PrivateContractHashP h_contract_terms; + + /** + * Merge capability key. + */ + struct TALER_PurseMergePublicKeyP merge_pub; + + /** + * Purse public key. + */ + struct TALER_PurseContractPublicKeyP purse_pub; + + /** + * Signature by the reserve approving the merge. + */ + struct TALER_ReserveSignatureP reserve_sig; + + /** + * When was the merge made. + */ + struct GNUNET_TIME_Timestamp merge_timestamp; + + /** + * When was the purse set to expire. + */ + struct GNUNET_TIME_Timestamp purse_expiration; + + /** + * Minimum age required for depositing into the purse. + */ + uint32_t min_age; + + /** + * Flags of the purse. + */ + enum TALER_WalletAccountMergeFlags flags; + + /** + * True if the purse was actually merged, false + * if only the @e purse_fee was charged. + */ + bool merged; + + } merge_details; + + /** + * Information about an open request operation on the reserve. + * @e type is #TALER_EXCHANGE_RTT_OPEN. + */ + struct + { + + /** + * Signature by the reserve approving the open. + */ + struct TALER_ReserveSignatureP reserve_sig; + + /** + * Amount to be paid from the reserve balance to open + * the reserve. + */ + struct TALER_Amount reserve_payment; + + /** + * When was the request created. + */ + struct GNUNET_TIME_Timestamp request_timestamp; + + /** + * For how long should the reserve be kept open. + * (Determines amount to be paid.) + */ + struct GNUNET_TIME_Timestamp reserve_expiration; + + /** + * How many open purses should be included with the + * open reserve? + * (Determines amount to be paid.) + */ + uint32_t purse_limit; + + } open_request; + + /** + * Information about an close request operation on the reserve. + * @e type is #TALER_EXCHANGE_RTT_CLOSE. + */ + struct + { + + /** + * Signature by the reserve approving the close. + */ + struct TALER_ReserveSignatureP reserve_sig; + + /** + * When was the request created. + */ + struct GNUNET_TIME_Timestamp request_timestamp; + + /** + * Hash of the payto://-URI of the target account + * for the closure, or all zeros for the reserve + * origin account. + */ + struct TALER_PaytoHashP target_account_h_payto; + + } close_request; + + + } details; + +}; + + +/** + * @brief A /reserves/ GET Handle + */ +struct TALER_EXCHANGE_ReservesGetHandle; + + +/** + * @brief Reserve summary. + */ +struct TALER_EXCHANGE_ReserveSummary +{ + + /** + * High-level HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on @e hr.http_status. + */ + union + { + + /** + * Information returned on success, if + * @e hr.http_status is #MHD_HTTP_OK + */ + struct + { + + /** + * Reserve balance. + */ + struct TALER_Amount balance; + + } ok; + } details; }; @@ -1139,18 +2298,12 @@ struct TALER_EXCHANGE_ReserveHistory * reserve status request to a exchange. * * @param cls closure - * @param hr HTTP response data - * @param balance current balance in the reserve, NULL on error - * @param history_length number of entries in the transaction history, 0 on error - * @param history detailed transaction history, NULL on error + * @param rs HTTP response data */ typedef void (*TALER_EXCHANGE_ReservesGetCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_Amount *balance, - unsigned int history_length, - const struct TALER_EXCHANGE_ReserveHistory *history); + const struct TALER_EXCHANGE_ReserveSummary *rs); /** @@ -1162,7 +2315,8 @@ typedef void * reply is not well-formed, we return an HTTP status code of zero to * @a cb. * - * @param exchange the exchange handle; the exchange must be ready to operate + * @param ctx curl context + * @param url exchange base URL * @param reserve_pub public key of the reserve to inspect * @param timeout how long to wait for an affirmative reply * (enables long polling if the reserve does not yet exist) @@ -1173,7 +2327,8 @@ typedef void */ struct TALER_EXCHANGE_ReservesGetHandle * TALER_EXCHANGE_reserves_get ( - struct TALER_EXCHANGE_Handle *exchange, + struct GNUNET_CURL_Context *ctx, + const char *url, const struct TALER_ReservePublicKeyP *reserve_pub, struct GNUNET_TIME_Relative timeout, TALER_EXCHANGE_ReservesGetCallback cb, @@ -1191,84 +2346,352 @@ TALER_EXCHANGE_reserves_get_cancel ( struct TALER_EXCHANGE_ReservesGetHandle *rgh); -/* ********************* POST /reserves/$RESERVE_PUB/withdraw *********************** */ +/** + * @brief A /reserves/$RID/history Handle + */ +struct TALER_EXCHANGE_ReservesHistoryHandle; /** - * @brief A /reserves/$RESERVE_PUB/withdraw Handle + * @brief Reserve history details. */ -struct TALER_EXCHANGE_WithdrawHandle; +struct TALER_EXCHANGE_ReserveHistory +{ + + /** + * High-level HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on @e hr.http_history. + */ + union + { + + /** + * Information returned on success, if + * @e hr.http_history is #MHD_HTTP_OK + */ + struct + { + + /** + * Current reserve balance. May not be the difference between + * @e total_in and @e total_out because the @e may be truncated. + */ + struct TALER_Amount balance; + + /** + * Total of all inbound transactions in @e history. + */ + struct TALER_Amount total_in; + + /** + * Total of all outbound transactions in @e history. + */ + struct TALER_Amount total_out; + + /** + * Current etag / last entry in the history. + * Useful to filter requests by starting offset. + * Offsets are not necessarily contiguous. + */ + uint64_t etag; + + /** + * Reserve history. + */ + const struct TALER_EXCHANGE_ReserveHistoryEntry *history; + + /** + * Length of the @e history array. + */ + unsigned int history_len; + + } ok; + + } details; + +}; /** * Callbacks of this type are used to serve the result of submitting a - * withdraw request to a exchange. + * reserve history request to a exchange. * * @param cls closure - * @param hr HTTP response data - * @param sig signature over the coin, NULL on error + * @param rs HTTP response data */ typedef void -(*TALER_EXCHANGE_WithdrawCallback) ( +(*TALER_EXCHANGE_ReservesHistoryCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_DenominationSignature *sig); + const struct TALER_EXCHANGE_ReserveHistory *rs); /** - * Withdraw a coin from the exchange using a /reserves/$RESERVE_PUB/withdraw - * request. This API is typically used by a wallet to withdraw from a - * reserve. + * Submit a request to obtain the reserve history. + * + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param reserve_priv private key of the reserve to inspect + * @param start_off offset of the oldest history entry to exclude from the response + * @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_ReservesHistoryHandle * +TALER_EXCHANGE_reserves_history ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_ReservePrivateKeyP *reserve_priv, + uint64_t start_off, + TALER_EXCHANGE_ReservesHistoryCallback cb, + void *cb_cls); + + +/** + * Cancel a reserve history request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param rsh the reserve request handle + */ +void +TALER_EXCHANGE_reserves_history_cancel ( + struct TALER_EXCHANGE_ReservesHistoryHandle *rsh); + + +/** + * Information input into the withdraw process per coin. + */ +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; + +}; + + +/** + * All the details about a coin that are generated during withdrawal and that + * may be needed for future operations on the coin. + */ +struct TALER_EXCHANGE_PrivateCoinDetails +{ + /** + * Private key of the coin. + */ + struct TALER_CoinSpendPrivateKeyP coin_priv; + + /** + * Value used to blind the key for the signature. + * Needed for recoup operations. + */ + union GNUNET_CRYPTO_BlindingSecretP bks; + + /** + * Signature over the coin. + */ + struct TALER_DenominationSignature sig; + + /** + * Values contributed from the exchange during the + * withdraw protocol. + */ + struct TALER_ExchangeWithdrawValues exchange_vals; +}; + + +/** + * @brief A /reserves/$RESERVE_PUB/batch-withdraw Handle + */ +struct TALER_EXCHANGE_BatchWithdrawHandle; + + +/** + * Details about a response for a batch withdraw request. + */ +struct TALER_EXCHANGE_BatchWithdrawResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details about the response. + */ + union + { + /** + * Details if the status is #MHD_HTTP_OK. + */ + struct + { + + /** + * Array of coins returned by the batch withdraw operation. + */ + struct TALER_EXCHANGE_PrivateCoinDetails *coins; + + /** + * Length of the @e coins array. + */ + unsigned int num_coins; + } ok; + + /** + * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. + */ + struct + { + + /** + * Hash of the payto-URI of the account to KYC; + */ + struct TALER_PaytoHashP h_payto; + + /** + * Legitimization requirement that the merchant should use + * to check for its KYC status, 0 if not known. + */ + uint64_t requirement_row; + } unavailable_for_legal_reasons; + + /** + * Details if the status is #MHD_HTTP_CONFLICT. + */ + struct + { + /* TODO: returning full details is not implemented */ + } conflict; + + /** + * Details if the status is #MHD_HTTP_GONE. + */ + struct + { + /* TODO: returning full details is not implemented */ + } gone; + + } details; +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * batch withdraw request to a exchange. + * + * @param cls closure + * @param wr response details + */ +typedef void +(*TALER_EXCHANGE_BatchWithdrawCallback) ( + void *cls, + const struct TALER_EXCHANGE_BatchWithdrawResponse *wr); + + +/** + * 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. The blind signatures are unblinded and verified before being returned + * to the caller at @a res_cb. * * 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 exchange the exchange handle; the exchange must be ready to operate - * @param pk kind of coin to create + * @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 ps secrets of the planchet - * caller must have committed this value to disk before the call (with @a pk) + * @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_WithdrawHandle * -TALER_EXCHANGE_withdraw ( - struct TALER_EXCHANGE_Handle *exchange, - const struct TALER_EXCHANGE_DenomPublicKey *pk, +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, - const struct TALER_PlanchetSecretsP *ps, - TALER_EXCHANGE_WithdrawCallback res_cb, + unsigned int wci_length, + const struct TALER_EXCHANGE_WithdrawCoinInput wcis[static wci_length], + TALER_EXCHANGE_BatchWithdrawCallback res_cb, void *res_cb_cls); /** - * Cancel a withdraw status request. This function cannot be used - * on a request handle if a response is already served for it. + * Cancel a batch withdraw status request. This function cannot be used on a + * request handle if a response is already served for it. * - * @param wh the withdraw handle + * @param wh the batch withdraw handle */ void -TALER_EXCHANGE_withdraw_cancel (struct TALER_EXCHANGE_WithdrawHandle *wh); +TALER_EXCHANGE_batch_withdraw_cancel ( + struct TALER_EXCHANGE_BatchWithdrawHandle *wh); + + +/** + * Response from a withdraw2 request. + */ +struct TALER_EXCHANGE_Withdraw2Response +{ + /** + * 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 + { + /** + * blind signature over the coin + */ + struct TALER_BlindedDenominationSignature blind_sig; + } ok; + } details; + +}; /** * Callbacks of this type are used to serve the result of submitting a * withdraw request to a exchange without the (un)blinding factor. * * @param cls closure - * @param hr HTTP response data - * @param blind_sig blind signature over the coin, NULL on error + * @param w2r response data */ typedef void (*TALER_EXCHANGE_Withdraw2Callback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct GNUNET_CRYPTO_RsaSignature *blind_sig); + const struct TALER_EXCHANGE_Withdraw2Response *w2r); /** @@ -1284,14 +2707,20 @@ struct TALER_EXCHANGE_Withdraw2Handle; /** * Withdraw a coin from the exchange using a /reserves/$RESERVE_PUB/withdraw * request. This API is typically used by a merchant to withdraw a tip - * where the blinding factor is unknown to the merchant. + * where the blinding factor is unknown to the merchant. Note that unlike + * the #TALER_EXCHANGE_batch_withdraw() API, this API neither unblinds the signatures + * nor can it verify that the exchange signatures are valid, so these tasks + * are left to the caller. Wallets probably should use #TALER_EXCHANGE_batch_withdraw() + * which integrates these steps. * * 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 exchange the exchange handle; the exchange must be ready to operate + * @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 pd 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 @@ -1301,11 +2730,14 @@ struct TALER_EXCHANGE_Withdraw2Handle; * In this case, the callback is not called. */ struct TALER_EXCHANGE_Withdraw2Handle * -TALER_EXCHANGE_withdraw2 (struct TALER_EXCHANGE_Handle *exchange, - const struct TALER_PlanchetDetail *pd, - const struct TALER_ReservePrivateKeyP *reserve_priv, - TALER_EXCHANGE_Withdraw2Callback res_cb, - void *res_cb_cls); +TALER_EXCHANGE_withdraw2 ( + struct GNUNET_CURL_Context *curl_ctx, + const char *exchange_url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_PlanchetDetail *pd, + const struct TALER_ReservePrivateKeyP *reserve_priv, + TALER_EXCHANGE_Withdraw2Callback res_cb, + void *res_cb_cls); /** @@ -1318,56 +2750,592 @@ void TALER_EXCHANGE_withdraw2_cancel (struct TALER_EXCHANGE_Withdraw2Handle *wh); -/* ********************* /refresh/melt+reveal ***************************** */ +/** + * Response from a batch-withdraw request (2nd variant). + */ +struct TALER_EXCHANGE_BatchWithdraw2Response +{ + /** + * 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 + { + /** + * array of blind signatures over the coins. + */ + const struct TALER_BlindedDenominationSignature *blind_sigs; + + /** + * length of @e blind_sigs + */ + unsigned int blind_sigs_length; + + } ok; + + struct + { + /** + * Hash of the payto-URI of the account to KYC; + */ + struct TALER_PaytoHashP h_payto; + + /** + * ID identifying the KYC requirement to withdraw. + */ + uint64_t kyc_requirement_id; + + } unavailable_for_legal_reasons; + + } details; + +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a batch + * withdraw request to a exchange without the (un)blinding factor. + * + * @param cls closure + * @param bw2r response data + */ +typedef void +(*TALER_EXCHANGE_BatchWithdraw2Callback) ( + void *cls, + const struct TALER_EXCHANGE_BatchWithdraw2Response *bw2r); + + +/** + * @brief A /reserves/$RESERVE_PUB/batch-withdraw Handle, 2nd variant. + * 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 tipping logic of merchants. + */ +struct TALER_EXCHANGE_BatchWithdraw2Handle; + + +/** + * 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); /** - * Melt (partially spent) coins to obtain fresh coins that are - * unlinkable to the original coin(s). Note that melting more - * than one coin in a single request will make those coins linkable, - * so the safest operation only melts one coin at a time. + * Cancel a batch withdraw request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param wh the withdraw handle + */ +void +TALER_EXCHANGE_batch_withdraw2_cancel ( + struct TALER_EXCHANGE_BatchWithdraw2Handle *wh); + + +/* ********************* /reserve/$RESERVE_PUB/age-withdraw *************** */ + +/** + * @brief Information needed to withdraw (and reveal) age restricted coins. + */ +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 + */ + struct TALER_PlanchetMasterSecretP secrets[TALER_CNC_KAPPA]; + + /** + * The denomination of the coin. Must support age restriction, i.e + * its .keys.age_mask MUST not be 0 + */ + struct TALER_EXCHANGE_DenomPublicKey *denom_pub; +}; + + +/** + * All the details about a coin that are generated during age-withdrawal and + * that may be needed for future operations on the coin. + */ +struct TALER_EXCHANGE_AgeWithdrawCoinPrivateDetails +{ + /** + * Private key of the coin. + */ + struct TALER_CoinSpendPrivateKeyP coin_priv; + + /** + * Hash of the public key of the coin. + */ + struct TALER_CoinPubHashP h_coin_pub; + + /** + * Value used to blind the key for the signature. + * Needed for recoup operations. + */ + union GNUNET_CRYPTO_BlindingSecretP blinding_key; + + /** + * The age commitment, proof for the coin, derived from the + * Master secret and maximum age in the originating request + */ + struct TALER_AgeCommitmentProof age_commitment_proof; + + /** + * The hash of the age commitment + */ + struct TALER_AgeCommitmentHash h_age_commitment; + + /** + * Values contributed from the exchange during the + * withdraw protocol. + */ + struct TALER_ExchangeWithdrawValues alg_values; + + /** + * The planchet constructed + */ + struct TALER_PlanchetDetail planchet; +}; + +/** + * @brief A handle to a /reserves/$RESERVE_PUB/age-withdraw request + */ +struct TALER_EXCHANGE_AgeWithdrawHandle; + +/** + * @brief Details about the response for a age withdraw request. + */ +struct TALER_EXCHANGE_AgeWithdrawResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details about the response + */ + union + { + /** + * Details if the status is #MHD_HTTP_OK. + */ + struct + { + /** + * Index that should not be revealed during the age-withdraw reveal + * phase. + */ + uint8_t noreveal_index; + + /** + * The commitment of the age-withdraw request, needed for the + * subsequent call to /age-withdraw/$ACH/reveal + */ + struct TALER_AgeWithdrawCommitmentHashP h_commitment; + + /** + * The number of elements in @e coins, each referring to + * TALER_CNC_KAPPA elements + */ + size_t num_coins; + + /** + * The computed details of the non-revealed @e num_coins coins to keep. + */ + const struct TALER_EXCHANGE_AgeWithdrawCoinPrivateDetails *coin_details; + + /** + * The array of blinded hashes of the non-revealed + * @e num_coins coins, needed for the reveal step; + */ + const struct TALER_BlindedCoinHashP *blinded_coin_hs; + + /** + * Key used by the exchange to sign the response. + */ + struct TALER_ExchangePublicKeyP exchange_pub; + } ok; + } details; +}; + + +typedef void +(*TALER_EXCHANGE_AgeWithdrawCallback)( + void *cls, + const struct TALER_EXCHANGE_AgeWithdrawResponse *awr); + +/** + * Submit an age-withdraw 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, is operation does - * not actually initiate the request. Instead, it generates a buffer - * which the caller must store before proceeding with the actual call - * to #TALER_EXCHANGE_melt() that will generate the request. - * - * This function does verify that the given request data is internally - * consistent. However, the @a melts_sigs are NOT verified. - * - * Aside from some non-trivial cryptographic operations that might - * take a bit of CPU time to complete, this function returns - * its result immediately and does not start any asynchronous - * processing. This function is also thread-safe. - * - * @param melt_priv private keys of the coin to melt - * @param melt_amount amount specifying how much - * the coin will contribute to the melt (including fee) - * @param melt_sig signatures affirming the - * validity of the public keys corresponding to the - * @a melt_priv private key - * @param melt_pk denomination key information - * record corresponding to the @a melt_sig - * validity of the keys - * @param fresh_pks_len length of the @a pks array - * @param fresh_pks array of @a pks_len denominations of fresh coins to create - * @param[out] res_size set to the size of the return value, or 0 on error + * 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 keys The denomination keys from the exchange + * @param reserve_priv The private key to the reserve + * @param num_coins The number of elements in @e coin_inputs + * @param coin_inputs The input for the coins to withdraw + * @param max_age The maximum age we commit to. + * @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_AgeWithdrawHandle * +TALER_EXCHANGE_age_withdraw ( + struct GNUNET_CURL_Context *curl_ctx, + 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[static + num_coins], + uint8_t max_age, + TALER_EXCHANGE_AgeWithdrawCallback res_cb, + void *res_cb_cls); + +/** + * Cancel a age-withdraw request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param awh the age-withdraw handle + */ +void +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, needed for the subsequent + * call to /age-withdraw/$ACH/reveal. + */ + struct TALER_AgeWithdrawCommitmentHashP h_commitment; + + /** + * Key used by the exchange to sign the response. + */ + 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_AgeWithdrawBlindedHandle; + +/** + * 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 max_age The maximum age that the coins are committed to. + * @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). - * Otherwise, pointer to a buffer of @a res_size to store persistently - * before proceeding to #TALER_EXCHANGE_melt(). - * Non-null results should be freed using GNUNET_free(). + * 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, + uint8_t max_age, + 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 */ -char * -TALER_EXCHANGE_refresh_prepare ( - const struct TALER_CoinSpendPrivateKeyP *melt_priv, - const struct TALER_Amount *melt_amount, - const struct TALER_DenominationSignature *melt_sig, - const struct TALER_EXCHANGE_DenomPublicKey *melt_pk, - unsigned int fresh_pks_len, - const struct TALER_EXCHANGE_DenomPublicKey *fresh_pks, - size_t *res_size); +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 signatures returned. + */ + unsigned int num_sigs; + + /** + * Array of @e num_coins blinded denomination signatures, giving each + * coin its value and validity. The array give these 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_BlindedDenominationSignature *blinded_denom_sigs; + + } ok; + } 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 num_coins The number of elements in @e coin_inputs and @e alg_values + * @param coin_inputs The input for the coins to withdraw, same as in 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 reserve_pub The public key of the reserve the original call to /age-withdraw was made to + * @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 coin_inputs[static + num_coins], + uint8_t noreveal_index, + const struct TALER_AgeWithdrawCommitmentHashP *h_commitment, + const struct TALER_ReservePublicKeyP *reserve_pub, + 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 ***************************** */ + + +/** + * Information needed to melt (partially spent) coins to obtain fresh coins + * that are unlinkable to the original coin(s). Note that melting more than + * one coin in a single request will make those coins linkable, so we only melt + * one coin at a time. + */ +struct TALER_EXCHANGE_RefreshData +{ + /** + * private key of the coin to melt + */ + struct TALER_CoinSpendPrivateKeyP melt_priv; + + /** + * age commitment and proof that went into the original coin, + * might be NULL. + */ + const struct TALER_AgeCommitmentProof *melt_age_commitment_proof; + + /** + * Hash of age commitment and proof that went into the original coin, + * might be NULL. + */ + const struct TALER_AgeCommitmentHash *melt_h_age_commitment; + + /** + * amount specifying how much the coin will contribute to the melt + * (including fee) + */ + struct TALER_Amount melt_amount; + + /** + * signatures affirming the validity of the public keys corresponding to the + * @e melt_priv private key + */ + struct TALER_DenominationSignature melt_sig; + + /** + * denomination key information record corresponding to the @e melt_sig + * validity of the keys + */ + struct TALER_EXCHANGE_DenomPublicKey melt_pk; + + /** + * array of @e pks_len denominations of fresh coins to create + */ + const struct TALER_EXCHANGE_DenomPublicKey *fresh_pks; + + /** + * length of the @e pks array + */ + unsigned int fresh_pks_len; +}; /* ********************* /coins/$COIN_PUB/melt ***************************** */ @@ -1379,23 +3347,79 @@ struct TALER_EXCHANGE_MeltHandle; /** + * Information we obtain per coin during melting. + */ +struct TALER_EXCHANGE_MeltBlindingDetail +{ + /** + * Exchange values contributed to the refresh operation + */ + struct TALER_ExchangeWithdrawValues alg_value; + +}; + + +/** + * Response returned to a /melt request. + */ +struct TALER_EXCHANGE_MeltResponse +{ + /** + * Full HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Parsed response details, variant depending on the + * @e hr.http_status. + */ + union + { + /** + * Results for status #MHD_HTTP_OK. + */ + struct + { + + /** + * Information returned per coin. + */ + const struct TALER_EXCHANGE_MeltBlindingDetail *mbds; + + /** + * Key used by the exchange to sign the response. + */ + struct TALER_ExchangePublicKeyP sign_key; + + /** + * Length of the @a mbds array with the exchange values + * and blinding keys we are using. + */ + unsigned int num_mbds; + + /** + * Gamma value chosen by the exchange. + */ + uint32_t noreveal_index; + } ok; + + } details; +}; + + +/** * Callbacks of this type are used to notify the application about the result * of the /coins/$COIN_PUB/melt stage. If successful, the @a noreveal_index * should be committed to disk prior to proceeding * #TALER_EXCHANGE_refreshes_reveal(). * * @param cls closure - * @param hr HTTP response data - * @param noreveal_index choice by the exchange in the cut-and-choose protocol, - * UINT32_MAX on error - * @param sign_key exchange key used to sign @a full_response, or NULL + * @param mr response details */ typedef void (*TALER_EXCHANGE_MeltCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - uint32_t noreveal_index, - const struct TALER_ExchangePublicKeyP *sign_key); + const struct TALER_EXCHANGE_MeltResponse *mr); /** @@ -1404,26 +3428,28 @@ typedef void * * 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 should have been constructed using - * #TALER_EXCHANGE_refresh_prepare and committed to persistent storage + * argument @a rd should be committed to persistent storage * prior to calling this function. * - * @param exchange the exchange handle; the exchange must be ready to operate - * @param refresh_data_length size of the @a refresh_data (returned - * in the `res_size` argument from #TALER_EXCHANGE_refresh_prepare()) - * @param refresh_data the refresh data as returned from - #TALER_EXCHANGE_refresh_prepare()) + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param rms the fresh secret that defines the refresh operation + * @param rd the refresh data specifying the characteristics of the operation * @param melt_cb the callback to call with the result * @param melt_cb_cls closure for @a melt_cb * @return a handle for this request; NULL if the argument was invalid. * In this case, neither callback will be called. */ struct TALER_EXCHANGE_MeltHandle * -TALER_EXCHANGE_melt (struct TALER_EXCHANGE_Handle *exchange, - size_t refresh_data_length, - const char *refresh_data, - TALER_EXCHANGE_MeltCallback melt_cb, - void *melt_cb_cls); +TALER_EXCHANGE_melt ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_RefreshMasterSecretP *rms, + const struct TALER_EXCHANGE_RefreshData *rd, + TALER_EXCHANGE_MeltCallback melt_cb, + void *melt_cb_cls); /** @@ -1440,26 +3466,92 @@ TALER_EXCHANGE_melt_cancel (struct TALER_EXCHANGE_MeltHandle *mh); /** + * Information about a coin obtained via /refreshes/$RCH/reveal. + */ +struct TALER_EXCHANGE_RevealedCoinInfo +{ + /** + * Private key of the coin. + */ + struct TALER_CoinSpendPrivateKeyP coin_priv; + + /** + * Master secret of this coin. + */ + struct TALER_PlanchetMasterSecretP ps; + + /** + * Age commitment and its hash of the coin, might be NULL. + */ + struct TALER_AgeCommitmentProof *age_commitment_proof; + struct TALER_AgeCommitmentHash h_age_commitment; + + /** + * Blinding keys used to blind the fresh coin. + */ + union GNUNET_CRYPTO_BlindingSecretP bks; + + /** + * Signature affirming the validity of the coin. + */ + struct TALER_DenominationSignature sig; + +}; + + +/** + * Result of a /refreshes/$RCH/reveal request. + */ +struct TALER_EXCHANGE_RevealResult +{ + /** + * HTTP status. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Parsed response details, variant depending on the + * @e hr.http_status. + */ + union + { + /** + * Results for status #MHD_HTTP_OK. + */ + struct + { + /** + * Array of @e num_coins values about the coins obtained via the refresh + * operation. The array give the coins in the same order (and should + * have the same length) in which the original melt request specified the + * respective denomination keys. + */ + const struct TALER_EXCHANGE_RevealedCoinInfo *coins; + + /** + * Number of coins returned. + */ + unsigned int num_coins; + } ok; + + } details; + +}; + + +/** * Callbacks of this type are used to return the final result of * submitting a refresh request to a exchange. If the operation was * successful, this function returns the signatures over the coins - * that were remelted. The @a coin_privs and @a sigs arrays give the - * coins in the same order (and should have the same length) in which - * the original request specified the respective denomination keys. + * that were remelted. * * @param cls closure - * @param hr HTTP response data - * @param num_coins number of fresh coins created, length of the @a sigs and @a coin_privs arrays, 0 if the operation failed - * @param coin_privs array of @a num_coins private keys for the coins that were created, NULL on error - * @param sigs array of signature over @a num_coins coins, NULL on error + * @param rr result of the reveal operation */ typedef void (*TALER_EXCHANGE_RefreshesRevealCallback)( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - unsigned int num_coins, - const struct TALER_PlanchetSecretsP *coin_privs, - const struct TALER_DenominationSignature *sigs); + const struct TALER_EXCHANGE_RevealResult *rr); /** @@ -1477,11 +3569,12 @@ struct TALER_EXCHANGE_RefreshesRevealHandle; * arguments should have been committed to persistent storage * prior to calling this function. * - * @param exchange the exchange handle; the exchange must be ready to operate - * @param refresh_data_length size of the @a refresh_data (returned - * in the `res_size` argument from #TALER_EXCHANGE_refresh_prepare()) - * @param refresh_data the refresh data as returned from - #TALER_EXCHANGE_refresh_prepare()) + * @param ctx curl context + * @param url exchange base URL + * @param rms the fresh secret that defines the refresh operation + * @param rd the refresh data that characterizes the refresh operation + * @param num_coins number of fresh coins to be created, length of the @a exchange_vals array, must match value in @a rd + * @param alg_values array @a num_coins of exchange values contributed to the refresh operation * @param noreveal_index response from the exchange to the * #TALER_EXCHANGE_melt() invocation * @param reveal_cb the callback to call with the final result of the @@ -1492,9 +3585,12 @@ struct TALER_EXCHANGE_RefreshesRevealHandle; */ struct TALER_EXCHANGE_RefreshesRevealHandle * TALER_EXCHANGE_refreshes_reveal ( - struct TALER_EXCHANGE_Handle *exchange, - size_t refresh_data_length, - const char *refresh_data, + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_RefreshMasterSecretP *rms, + const struct TALER_EXCHANGE_RefreshData *rd, + unsigned int num_coins, + const struct TALER_ExchangeWithdrawValues alg_values[static num_coins], uint32_t noreveal_index, TALER_EXCHANGE_RefreshesRevealCallback reveal_cb, void *reveal_cb_cls); @@ -1521,26 +3617,90 @@ struct TALER_EXCHANGE_LinkHandle; /** + * Information about a coin obtained via /link. + */ +struct TALER_EXCHANGE_LinkedCoinInfo +{ + /** + * Private key of the coin. + */ + struct TALER_CoinSpendPrivateKeyP coin_priv; + + /** + * Age commitment and its hash, if applicable. + */ + bool has_age_commitment; + struct TALER_AgeCommitmentProof age_commitment_proof; + struct TALER_AgeCommitmentHash h_age_commitment; + + /** + * Master secret of this coin. + */ + struct TALER_PlanchetMasterSecretP ps; + + /** + * Signature affirming the validity of the coin. + */ + struct TALER_DenominationSignature sig; + + /** + * Denomination public key of the coin. + */ + struct TALER_DenominationPublicKey pub; +}; + + +/** + * Result of a /link request. + */ +struct TALER_EXCHANGE_LinkResult +{ + /** + * HTTP status. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Parsed response details, variant depending on the + * @e hr.http_status. + */ + union + { + /** + * Results for status #MHD_HTTP_OK. + */ + struct + { + /** + * Array of @e num_coins values about the + * coins obtained via linkage. + */ + const struct TALER_EXCHANGE_LinkedCoinInfo *coins; + + /** + * Number of coins returned. + */ + unsigned int num_coins; + } ok; + + } details; + +}; + + +/** * Callbacks of this type are used to return the final result of submitting a * /coins/$COIN_PUB/link request to a exchange. If the operation was * successful, this function returns the signatures over the coins that were * created when the original coin was melted. * * @param cls closure - * @param hr HTTP response data - * @param num_coins number of fresh coins created, length of the @a sigs and @a coin_privs arrays, 0 if the operation failed - * @param coin_privs array of @a num_coins private keys for the coins that were created, NULL on error - * @param sigs array of signature over @a num_coins coins, NULL on error - * @param pubs array of public keys for the @a sigs, NULL on error + * @param lr result of the /link operation */ typedef void (*TALER_EXCHANGE_LinkCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - unsigned int num_coins, - const struct TALER_CoinSpendPrivateKeyP *coin_privs, - const struct TALER_DenominationSignature *sigs, - const struct TALER_DenominationPublicKey *pubs); + const struct TALER_EXCHANGE_LinkResult *lr); /** @@ -1549,18 +3709,23 @@ typedef void * This API is typically not used by anyone, it is more a threat against those * trying to receive a funds transfer by abusing the refresh protocol. * - * @param exchange the exchange handle; the exchange must be ready to operate + * @param ctx CURL context + * @param url exchange base URL * @param coin_priv private key to request link data for + * @param age_commitment_proof age commitment to the corresponding coin, might be NULL * @param link_cb the callback to call with the useful result of the * refresh operation the @a coin_priv was involved in (if any) * @param link_cb_cls closure for @a link_cb * @return a handle for this request */ struct TALER_EXCHANGE_LinkHandle * -TALER_EXCHANGE_link (struct TALER_EXCHANGE_Handle *exchange, - const struct TALER_CoinSpendPrivateKeyP *coin_priv, - TALER_EXCHANGE_LinkCallback link_cb, - void *link_cb_cls); +TALER_EXCHANGE_link ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_CoinSpendPrivateKeyP *coin_priv, + const struct TALER_AgeCommitmentProof *age_commitment_proof, + TALER_EXCHANGE_LinkCallback link_cb, + void *link_cb_cls); /** @@ -1598,14 +3763,14 @@ struct TALER_EXCHANGE_TransferData struct TALER_ExchangeSignatureP exchange_sig; /** - * hash of the wire transfer address the transfer went to + * hash of the payto:// URI the transfer went to */ - struct GNUNET_HashCode h_wire; + struct TALER_PaytoHashP h_payto; /** * time when the exchange claims to have performed the wire transfer */ - struct GNUNET_TIME_Absolute execution_time; + struct GNUNET_TIME_Timestamp execution_time; /** * Actual amount of the wire transfer, excluding the wire fee. @@ -1631,25 +3796,52 @@ struct TALER_EXCHANGE_TransferData /** + * Response for a GET /transfers request. + */ +struct TALER_EXCHANGE_TransfersGetResponse +{ + /** + * HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on HTTP status code. + */ + union + { + /** + * Details if status code is #MHD_HTTP_OK. + */ + struct + { + struct TALER_EXCHANGE_TransferData td; + } ok; + + } details; +}; + + +/** * Function called with detailed wire transfer data, including all * of the coin transactions that were combined into the wire transfer. * * @param cls closure - * @param hr HTTP response data - * @param ta transfer data, (set only if @a http_status is #MHD_HTTP_OK, otherwise NULL) + * @param tgr response data */ typedef void (*TALER_EXCHANGE_TransfersGetCallback)( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_EXCHANGE_TransferData *ta); + const struct TALER_EXCHANGE_TransfersGetResponse *tgr); /** * Query the exchange about which transactions were combined * to create a wire transfer. * - * @param exchange exchange to query + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys * @param wtid raw wire transfer identifier to get information about * @param cb callback to call * @param cb_cls closure for @a cb @@ -1657,7 +3849,9 @@ typedef void */ struct TALER_EXCHANGE_TransfersGetHandle * TALER_EXCHANGE_transfers_get ( - struct TALER_EXCHANGE_Handle *exchange, + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, const struct TALER_WireTransferIdentifierRawP *wtid, TALER_EXCHANGE_TransfersGetCallback cb, void *cb_cls); @@ -1684,41 +3878,89 @@ struct TALER_EXCHANGE_DepositGetHandle; /** - * Data returned for a successful GET /deposits/ request. Note that - * most fields are only set if the status is #MHD_HTTP_OK. Only - * the @e execution_time is available if the status is #MHD_HTTP_ACCEPTED. + * Data returned for a successful GET /deposits/ request. */ -struct TALER_EXCHANGE_DepositData +struct TALER_EXCHANGE_GetDepositResponse { /** - * exchange key used to sign, all zeros if exchange did not - * yet execute the transaction + * HTTP response data. */ - struct TALER_ExchangePublicKeyP exchange_pub; + struct TALER_EXCHANGE_HttpResponse hr; /** - * signature from the exchange over the deposit data, all zeros if exchange did not - * yet execute the transaction + * Details about the response. */ - struct TALER_ExchangeSignatureP exchange_sig; + union + { - /** - * wire transfer identifier used by the exchange, all zeros if exchange did not - * yet execute the transaction - */ - struct TALER_WireTransferIdentifierRawP wtid; + /** + * Response if the status was #MHD_HTTP_OK + */ + struct TALER_EXCHANGE_DepositData + { + /** + * exchange key used to sign, all zeros if exchange did not + * yet execute the transaction + */ + struct TALER_ExchangePublicKeyP exchange_pub; - /** - * actual or planned execution time for the wire transfer - */ - struct GNUNET_TIME_Absolute execution_time; + /** + * signature from the exchange over the deposit data, all zeros if exchange did not + * yet execute the transaction + */ + struct TALER_ExchangeSignatureP exchange_sig; - /** - * contribution to the total amount by this coin, all zeros if exchange did not - * yet execute the transaction - */ - struct TALER_Amount coin_contribution; + /** + * wire transfer identifier used by the exchange, all zeros if exchange did not + * yet execute the transaction + */ + struct TALER_WireTransferIdentifierRawP wtid; + + /** + * actual execution time for the wire transfer + */ + struct GNUNET_TIME_Timestamp execution_time; + + /** + * contribution to the total amount by this coin, all zeros if exchange did not + * yet execute the transaction + */ + struct TALER_Amount coin_contribution; + + } ok; + + /** + * Response if the status was #MHD_HTTP_ACCEPTED + */ + struct + { + + /** + * planned execution time for the wire transfer + */ + struct GNUNET_TIME_Timestamp execution_time; + + /** + * KYC legitimization requirement that the merchant should use to check + * for its KYC status. + */ + uint64_t requirement_row; + + /** + * Current AML state for the account. May explain why transfers are + * not happening. + */ + enum TALER_AmlDecisionState aml_decision; + + /** + * Set to 'true' if the KYC check is already finished and + * the exchange is merely waiting for the @e execution_time. + */ + bool kyc_ok; + } accepted; + + } details; }; @@ -1726,14 +3968,12 @@ struct TALER_EXCHANGE_DepositData * Function called with detailed wire transfer data. * * @param cls closure - * @param hr HTTP response data - * @param dd details about the deposit (NULL on errors) + * @param dr details about the deposit response */ typedef void (*TALER_EXCHANGE_DepositGetCallback)( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_EXCHANGE_DepositData *dd); + const struct TALER_EXCHANGE_GetDepositResponse *dr); /** @@ -1741,22 +3981,28 @@ typedef void * which aggregate wire transfer the deposit operation identified by @a coin_pub, * @a merchant_priv and @a h_contract_terms contributed to. * - * @param exchange the exchange to query + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys * @param merchant_priv the merchant's private key * @param h_wire hash of merchant's wire transfer details * @param h_contract_terms hash of the proposal data * @param coin_pub public key of the coin + * @param timeout timeout to use for long-polling, 0 for no long polling * @param cb function to call with the result * @param cb_cls closure for @a cb * @return handle to abort request */ struct TALER_EXCHANGE_DepositGetHandle * TALER_EXCHANGE_deposits_get ( - struct TALER_EXCHANGE_Handle *exchange, + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, const struct TALER_MerchantPrivateKeyP *merchant_priv, - const struct GNUNET_HashCode *h_wire, - const struct GNUNET_HashCode *h_contract_terms, + const struct TALER_MerchantWireHashP *h_wire, + const struct TALER_PrivateContractHashP *h_contract_terms, const struct TALER_CoinSpendPublicKeyP *coin_pub, + struct GNUNET_TIME_Relative timeout, TALER_EXCHANGE_DepositGetCallback cb, void *cb_cls); @@ -1772,131 +4018,522 @@ TALER_EXCHANGE_deposits_get_cancel ( struct TALER_EXCHANGE_DepositGetHandle *dwh); +/* ********************* /recoup *********************** */ + + +/** + * @brief A /recoup Handle + */ +struct TALER_EXCHANGE_RecoupHandle; + + +/** + * Response from a recoup request. + */ +struct TALER_EXCHANGE_RecoupResponse +{ + /** + * 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 + { + /** + * public key of the reserve receiving the recoup + */ + struct TALER_ReservePublicKeyP reserve_pub; + + } ok; + } details; + +}; + + /** - * Convenience function. Verifies a coin's transaction history as - * returned by the exchange. + * Callbacks of this type are used to return the final result of + * submitting a recoup request to a exchange. If the operation was + * successful, this function returns the @a reserve_pub of the + * reserve that was credited. * - * @param dk fee structure for the coin, NULL to skip verifying fees - * @param currency expected currency for the coin - * @param coin_pub public key of the coin - * @param history history of the coin in json encoding - * @param[out] h_denom_pub set to the hash of the coin's denomination (if available) - * @param[out] total how much of the coin has been spent according to @a history - * @return #GNUNET_OK if @a history is valid, #GNUNET_SYSERR if not + * @param cls closure + * @param rr response data */ -int -TALER_EXCHANGE_verify_coin_history ( - const struct TALER_EXCHANGE_DenomPublicKey *dk, - const char *currency, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - json_t *history, - struct GNUNET_HashCode *h_denom_pub, - struct TALER_Amount *total); +typedef void +(*TALER_EXCHANGE_RecoupResultCallback) ( + void *cls, + const struct TALER_EXCHANGE_RecoupResponse *rr); /** - * Parse history given in JSON format and return it in binary - * format. + * Ask the exchange to pay back a coin due to the exchange triggering + * the emergency recoup protocol for a given denomination. The value + * of the coin will be refunded to the original customer (without fees). * - * @param exchange connection to the exchange we can use - * @param history JSON array with the history - * @param reserve_pub public key of the reserve to inspect - * @param currency currency we expect the balance to be in - * @param[out] balance final balance - * @param history_length number of entries in @a history - * @param[out] rhistory array of length @a history_length, set to the - * parsed history entries - * @return #GNUNET_OK if history was valid and @a rhistory and @a balance - * were set, - * #GNUNET_SYSERR if there was a protocol violation in @a history - */ -int -TALER_EXCHANGE_parse_reserve_history ( - struct TALER_EXCHANGE_Handle *exchange, - const json_t *history, - const struct TALER_ReservePublicKeyP *reserve_pub, - const char *currency, - struct TALER_Amount *balance, - unsigned int history_length, - struct TALER_EXCHANGE_ReserveHistory *rhistory); + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param pk kind of coin to pay back + * @param denom_sig signature over the coin by the exchange using @a pk + * @param exchange_vals contribution from the exchange on the withdraw + * @param ps secret internals of the original planchet + * @param recoup_cb the callback to call when the final result for this request is available + * @param recoup_cb_cls closure for @a recoup_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_RecoupHandle * +TALER_EXCHANGE_recoup ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_EXCHANGE_DenomPublicKey *pk, + const struct TALER_DenominationSignature *denom_sig, + const struct TALER_ExchangeWithdrawValues *exchange_vals, + const struct TALER_PlanchetMasterSecretP *ps, + TALER_EXCHANGE_RecoupResultCallback recoup_cb, + void *recoup_cb_cls); /** - * Free memory (potentially) allocated by #TALER_EXCHANGE_parse_reserve_history(). + * Cancel a recoup request. This function cannot be used on a + * request handle if the callback was already invoked. * - * @param rhistory result to free - * @param len number of entries in @a rhistory + * @param ph the recoup handle */ void -TALER_EXCHANGE_free_reserve_history ( - struct TALER_EXCHANGE_ReserveHistory *rhistory, - unsigned int len); +TALER_EXCHANGE_recoup_cancel (struct TALER_EXCHANGE_RecoupHandle *ph); -/* ********************* /recoup *********************** */ +/* ********************* /recoup-refresh *********************** */ /** - * @brief A /recoup Handle + * @brief A /recoup-refresh Handle */ -struct TALER_EXCHANGE_RecoupHandle; +struct TALER_EXCHANGE_RecoupRefreshHandle; + + +/** + * Response from a /recoup-refresh request. + */ +struct TALER_EXCHANGE_RecoupRefreshResponse +{ + /** + * 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 + { + /** + * public key of the dirty coin that was credited + */ + struct TALER_CoinSpendPublicKeyP old_coin_pub; + + } ok; + } details; + +}; /** * Callbacks of this type are used to return the final result of - * submitting a refresh request to a exchange. If the operation was - * successful, this function returns the signatures over the coins - * that were remelted. The @a coin_privs and @a sigs arrays give the - * coins in the same order (and should have the same length) in which - * the original request specified the respective denomination keys. + * submitting a recoup-refresh request to a exchange. * * @param cls closure - * @param hr HTTP response data - * @param reserve_pub public key of the reserve receiving the recoup, NULL if refreshed or on error - * @param old_coin_pub public key of the dirty coin, NULL if not refreshed or on error + * @param rrr response data */ typedef void -(*TALER_EXCHANGE_RecoupResultCallback) ( +(*TALER_EXCHANGE_RecoupRefreshResultCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_ReservePublicKeyP *reserve_pub, - const struct TALER_CoinSpendPublicKeyP *old_coin_pub); + const struct TALER_EXCHANGE_RecoupRefreshResponse *rrr); /** * Ask the exchange to pay back a coin due to the exchange triggering * the emergency recoup protocol for a given denomination. The value - * of the coin will be refunded to the original customer (without fees). + * of the coin will be refunded to the original coin that the + * revoked coin was refreshed from. The original coin is then + * considered a zombie. * - * @param exchange the exchange handle; the exchange must be ready to operate + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys * @param pk kind of coin to pay back * @param denom_sig signature over the coin by the exchange using @a pk - * @param ps secret internals of the original planchet - * @param was_refreshed true if the coin in @a ps was refreshed + * @param exchange_vals contribution from the exchange on the withdraw + * @param rms melt secret of the refreshing operation + * @param ps coin-specific secrets derived for this coin during the refreshing operation + * @param idx index of the fresh coin in the refresh operation that is now being recouped * @param recoup_cb the callback to call when the final result for this request is available * @param recoup_cb_cls closure for @a recoup_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_RecoupHandle * -TALER_EXCHANGE_recoup (struct TALER_EXCHANGE_Handle *exchange, - const struct TALER_EXCHANGE_DenomPublicKey *pk, - const struct TALER_DenominationSignature *denom_sig, - const struct TALER_PlanchetSecretsP *ps, - bool was_refreshed, - TALER_EXCHANGE_RecoupResultCallback recoup_cb, - void *recoup_cb_cls); +struct TALER_EXCHANGE_RecoupRefreshHandle * +TALER_EXCHANGE_recoup_refresh ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_EXCHANGE_DenomPublicKey *pk, + const struct TALER_DenominationSignature *denom_sig, + const struct TALER_ExchangeWithdrawValues *exchange_vals, + const struct TALER_RefreshMasterSecretP *rms, + const struct TALER_PlanchetMasterSecretP *ps, + unsigned int idx, + TALER_EXCHANGE_RecoupRefreshResultCallback recoup_cb, + void *recoup_cb_cls); /** - * Cancel a recoup request. This function cannot be used on a - * request handle if the callback was already invoked. + * Cancel a recoup-refresh request. This function cannot be used on a request + * handle if the callback was already invoked. * * @param ph the recoup handle */ void -TALER_EXCHANGE_recoup_cancel (struct TALER_EXCHANGE_RecoupHandle *ph); +TALER_EXCHANGE_recoup_refresh_cancel ( + struct TALER_EXCHANGE_RecoupRefreshHandle *ph); + + +/* ********************* /kyc* *********************** */ + +/** + * Handle for a ``/kyc-check`` operation. + */ +struct TALER_EXCHANGE_KycCheckHandle; + + +/** + * KYC status response details. + */ +struct TALER_EXCHANGE_KycStatus +{ + /** + * HTTP status code returned by the exchange. + */ + unsigned int http_status; + + /** + * Taler error code, if any. + */ + enum TALER_ErrorCode ec; + + union + { + + /** + * KYC is OK, affirmation returned by the exchange. + */ + struct + { + + /** + * Details about which KYC check(s) were passed. + */ + const json_t *kyc_details; + + /** + * Time of the affirmation. + */ + struct GNUNET_TIME_Timestamp timestamp; + + /** + * The signing public key used for @e exchange_sig. + */ + struct TALER_ExchangePublicKeyP exchange_pub; + + /** + * Signature of purpose + * #TALER_SIGNATURE_EXCHANGE_ACCOUNT_SETUP_SUCCESS affirming + * the successful KYC process. + */ + struct TALER_ExchangeSignatureP exchange_sig; + + /** + * AML status for the account. + */ + enum TALER_AmlDecisionState aml_status; + + } ok; + + /** + * KYC is required. + */ + struct + { + + /** + * URL the user should open in a browser if + * the KYC process is to be run. Returned if + * @e http_status is #MHD_HTTP_ACCEPTED. + */ + const char *kyc_url; + + /** + * AML status for the account. + */ + enum TALER_AmlDecisionState aml_status; + + } accepted; + + /** + * KYC is OK, but account needs positive AML decision. + */ + struct + { + + /** + * AML status for the account. + */ + enum TALER_AmlDecisionState aml_status; + + } unavailable_for_legal_reasons; + + } details; + +}; + +/** + * Function called with the result of a KYC check. + * + * @param cls closure + * @param ks the account's KYC status details + */ +typedef void +(*TALER_EXCHANGE_KycStatusCallback)( + void *cls, + const struct TALER_EXCHANGE_KycStatus *ks); + + +/** + * Run interaction with exchange to check KYC status + * of a merchant. + * + * @param ctx CURL context + * @param url exchange base URL + * @param keys keys of the exchange + * @param requirement_row number identifying the KYC requirement + * @param h_payto hash of the payto:// URI at @a payment_target + * @param ut type of the entity performing the KYC check + * @param timeout how long to wait for a positive KYC status + * @param cb function to call with the result + * @param cb_cls closure for @a cb + * @return NULL on error + */ +struct TALER_EXCHANGE_KycCheckHandle * +TALER_EXCHANGE_kyc_check ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + uint64_t requirement_row, + const struct TALER_PaytoHashP *h_payto, + enum TALER_KYCLOGIC_KycUserType ut, + struct GNUNET_TIME_Relative timeout, + TALER_EXCHANGE_KycStatusCallback cb, + void *cb_cls); + + +/** + * Cancel KYC check operation. + * + * @param kyc handle for operation to cancel + */ +void +TALER_EXCHANGE_kyc_check_cancel (struct TALER_EXCHANGE_KycCheckHandle *kyc); + + +/** + * KYC proof response details. + */ +struct TALER_EXCHANGE_KycProofResponse +{ + /** + * HTTP status code returned by the exchange. + */ + unsigned int http_status; + + union + { + + /** + * KYC is OK, affirmation returned by the exchange. + */ + struct + { + + /** + * Where to redirect the client next. + */ + const char *redirect_url; + + } found; + + } details; + +}; + +/** + * Function called with the result of a KYC check. + * + * @param cls closure + * @param kpr the account's KYC status details + */ +typedef void +(*TALER_EXCHANGE_KycProofCallback)( + void *cls, + const struct TALER_EXCHANGE_KycProofResponse *kpr); + + +/** + * Handle for a /kyc-proof operation. + */ +struct TALER_EXCHANGE_KycProofHandle; + + +/** + * Run interaction with exchange to provide proof of KYC status. + * + * @param ctx CURL context + * @param url exchange base URL + * @param h_payto hash of payto URI identifying the target account + * @param logic name of the KYC logic to run + * @param args additional args to pass, can be NULL + * or a string to append to the URL. Must then begin with '&'. + * @param cb function to call with the result + * @param cb_cls closure for @a cb + * @return NULL on error + */ +struct TALER_EXCHANGE_KycProofHandle * +TALER_EXCHANGE_kyc_proof ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_PaytoHashP *h_payto, + const char *logic, + const char *args, + TALER_EXCHANGE_KycProofCallback cb, + void *cb_cls); + + +/** + * Cancel KYC proof operation. + * + * @param kph handle for operation to cancel + */ +void +TALER_EXCHANGE_kyc_proof_cancel (struct TALER_EXCHANGE_KycProofHandle *kph); + + +/** + * Handle for a ``/kyc-wallet`` operation. + */ +struct TALER_EXCHANGE_KycWalletHandle; + + +/** + * KYC status response details. + */ +struct TALER_EXCHANGE_WalletKycResponse +{ + + /** + * HTTP status code returned by the exchange. + */ + unsigned int http_status; + + /** + * Taler error code, if any. + */ + enum TALER_ErrorCode ec; + + /** + * Variants depending on @e http_status. + */ + union + { + + /** + * In case @e http_status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. + */ + struct + { + /** + * Wallet's KYC requirement row. + */ + uint64_t requirement_row; + + /** + * Hash of the payto-URI identifying the wallet to KYC. + */ + struct TALER_PaytoHashP h_payto; + + } unavailable_for_legal_reasons; + + } details; + +}; + +/** + * Function called with the result for a wallet looking + * up its KYC payment target. + * + * @param cls closure + * @param ks the wallets KYC payment target details + */ +typedef void +(*TALER_EXCHANGE_KycWalletCallback)( + void *cls, + const struct TALER_EXCHANGE_WalletKycResponse *ks); + + +/** + * Run interaction with exchange to find out the wallet's KYC + * identifier. + * + * @param ctx CURL context + * @param url exchange base URL + * @param reserve_priv wallet private key to check + * @param balance balance (or balance threshold) crossed by the wallet + * @param cb function to call with the result + * @param cb_cls closure for @a cb + * @return NULL on error + */ +struct TALER_EXCHANGE_KycWalletHandle * +TALER_EXCHANGE_kyc_wallet ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_ReservePrivateKeyP *reserve_priv, + const struct TALER_Amount *balance, + TALER_EXCHANGE_KycWalletCallback cb, + void *cb_cls); + + +/** + * Cancel KYC wallet operation + * + * @param kwh handle for operation to cancel + */ +void +TALER_EXCHANGE_kyc_wallet_cancel (struct TALER_EXCHANGE_KycWalletHandle *kwh); /* ********************* /management *********************** */ @@ -1920,17 +4557,17 @@ struct TALER_EXCHANGE_FutureSigningPublicKey /** * Validity start time */ - struct GNUNET_TIME_Absolute valid_from; + struct GNUNET_TIME_Timestamp valid_from; /** * Validity expiration time (how long the exchange may use it). */ - struct GNUNET_TIME_Absolute valid_until; + struct GNUNET_TIME_Timestamp valid_until; /** * Validity expiration time for legal disputes. */ - struct GNUNET_TIME_Absolute valid_legal; + struct GNUNET_TIME_Timestamp valid_legal; }; @@ -1952,18 +4589,18 @@ struct TALER_EXCHANGE_FutureDenomPublicKey /** * Timestamp indicating when the denomination key becomes valid */ - struct GNUNET_TIME_Absolute valid_from; + struct GNUNET_TIME_Timestamp valid_from; /** * Timestamp indicating when the denomination key can’t be used anymore to * withdraw new coins. */ - struct GNUNET_TIME_Absolute withdraw_valid_until; + struct GNUNET_TIME_Timestamp withdraw_valid_until; /** * Timestamp indicating when coins of this denomination become invalid. */ - struct GNUNET_TIME_Absolute expire_deposit; + struct GNUNET_TIME_Timestamp expire_deposit; /** * When do signatures with this denomination key become invalid? @@ -1972,7 +4609,7 @@ struct TALER_EXCHANGE_FutureDenomPublicKey * of the evidence. @e expire_legal is expected to be significantly * larger than @e expire_deposit (by a year or more). */ - struct GNUNET_TIME_Absolute expire_legal; + struct GNUNET_TIME_Timestamp expire_legal; /** * The value of this denomination @@ -2024,11 +4661,16 @@ struct TALER_EXCHANGE_FutureKeys struct TALER_SecurityModulePublicKeyP signkey_secmod_public_key; /** - * Public key of the denomination security module. + * Public key of the RSA denomination security module. */ struct TALER_SecurityModulePublicKeyP denom_secmod_public_key; /** + * Public key of the CS denomination security module. + */ + struct TALER_SecurityModulePublicKeyP denom_secmod_cs_public_key; + + /** * Offline master public key used by this exchange. */ struct TALER_MasterPublicKeyP master_pub; @@ -2047,18 +4689,47 @@ struct TALER_EXCHANGE_FutureKeys /** + * Response from a /management/keys request. + */ +struct TALER_EXCHANGE_ManagementGetKeysResponse +{ + /** + * 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 + { + /** + * information about the various keys used + * by the exchange + */ + struct TALER_EXCHANGE_FutureKeys keys; + + } ok; + } details; + +}; + + +/** * Function called with information about future keys. * * @param cls closure - * @param hr HTTP response data - * @param keys information about the various keys used - * by the exchange, NULL if /management/keys failed + * @param mgr HTTP response data */ typedef void (*TALER_EXCHANGE_ManagementGetKeysCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr, - const struct TALER_EXCHANGE_FutureKeys *keys); + const struct TALER_EXCHANGE_ManagementGetKeysResponse *mgr); /** @@ -2078,10 +4749,11 @@ struct TALER_EXCHANGE_ManagementGetKeysHandle; * @return the request handle; NULL upon error */ struct TALER_EXCHANGE_ManagementGetKeysHandle * -TALER_EXCHANGE_get_management_keys (struct GNUNET_CURL_Context *ctx, - const char *url, - TALER_EXCHANGE_ManagementGetKeysCallback cb, - void *cb_cls); +TALER_EXCHANGE_get_management_keys ( + struct GNUNET_CURL_Context *ctx, + const char *url, + TALER_EXCHANGE_ManagementGetKeysCallback cb, + void *cb_cls); /** @@ -2121,7 +4793,7 @@ struct TALER_EXCHANGE_DenominationKeySignature /** * The hash of the denomination's public key */ - struct GNUNET_HashCode h_denom_pub; + struct TALER_DenominationHashP h_denom_pub; /** * Signature over this denomination key by the exchange's master signature. @@ -2161,15 +4833,28 @@ struct TALER_EXCHANGE_ManagementPostKeysData /** + * Response from a POST /management/keys request. + */ +struct TALER_EXCHANGE_ManagementPostKeysResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + +}; + + +/** * Function called with information about the post keys operation result. * * @param cls closure - * @param hr HTTP response data + * @param mr response data */ typedef void (*TALER_EXCHANGE_ManagementPostKeysCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementPostKeysResponse *mr); /** @@ -2206,6 +4891,163 @@ void TALER_EXCHANGE_post_management_keys_cancel ( struct TALER_EXCHANGE_ManagementPostKeysHandle *ph); + +/** + * Information needed for a POST /management/extensions operation. + * + * It represents the interface ExchangeKeysResponse as defined in + * https://docs.taler.net/design-documents/006-extensions.html#exchange + */ +struct TALER_EXCHANGE_ManagementPostExtensionsData +{ + const json_t *extensions; + struct TALER_MasterSignatureP extensions_sig; +}; + + +/** + * Response from a POST /management/extensions request. + */ +struct TALER_EXCHANGE_ManagementPostExtensionsResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + +}; + + +/** + * Function called with information about the post extensions operation result. + * + * @param cls closure + * @param hr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ManagementPostExtensionsCallback) ( + void *cls, + const struct TALER_EXCHANGE_ManagementPostExtensionsResponse *hr); + +/** + * @brief Handle for a POST /management/extensions request. + */ +struct TALER_EXCHANGE_ManagementPostExtensionsHandle; + + +/** + * Uploads the configurations of enabled extensions to the exchange, signed + * with the master key. + * + * @param ctx the context + * @param url HTTP base URL for the exchange + * @param ped signature data to POST + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_ManagementPostExtensionsHandle * +TALER_EXCHANGE_management_post_extensions ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_EXCHANGE_ManagementPostExtensionsData *ped, + TALER_EXCHANGE_ManagementPostExtensionsCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_management_post_extensions() operation. + * + * @param ph handle of the operation to cancel + */ +void +TALER_EXCHANGE_management_post_extensions_cancel ( + struct TALER_EXCHANGE_ManagementPostExtensionsHandle *ph); + + +/** + * Response from a POST /management/drain request. + */ +struct TALER_EXCHANGE_ManagementDrainResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + +}; + + +/** + * Function called with information about the drain profits result. + * + * @param cls closure + * @param hr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ManagementDrainProfitsCallback) ( + void *cls, + const struct TALER_EXCHANGE_ManagementDrainResponse *hr); + + +/** + * @brief Handle for a POST /management/drain request. + */ +struct TALER_EXCHANGE_ManagementDrainProfitsHandle; + + +/** + * Uploads the drain profits request. + * + * @param ctx the context + * @param url HTTP base URL for the exchange + * @param wtid wire transfer identifier to use + * @param amount total to transfer + * @param date when was the request created + * @param account_section configuration section identifying account to debit + * @param payto_uri RFC 8905 URI of the account to credit + * @param master_sig signature affirming the operation + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_ManagementDrainProfitsHandle * +TALER_EXCHANGE_management_drain_profits ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_WireTransferIdentifierRawP *wtid, + const struct TALER_Amount *amount, + struct GNUNET_TIME_Timestamp date, + const char *account_section, + const char *payto_uri, + const struct TALER_MasterSignatureP *master_sig, + TALER_EXCHANGE_ManagementDrainProfitsCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_management_drain_profits() operation. + * + * @param dp handle of the operation to cancel + */ +void +TALER_EXCHANGE_management_drain_profits_cancel ( + struct TALER_EXCHANGE_ManagementDrainProfitsHandle *dp); + + +/** + * Response from a POST /management/denominations/$DENOM/revoke request. + */ +struct TALER_EXCHANGE_ManagementRevokeDenominationResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + +}; + + /** * Function called with information about the post revocation operation result. * @@ -2215,7 +5057,7 @@ TALER_EXCHANGE_post_management_keys_cancel ( typedef void (*TALER_EXCHANGE_ManagementRevokeDenominationKeyCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementRevokeDenominationResponse *hr); /** @@ -2239,7 +5081,7 @@ struct TALER_EXCHANGE_ManagementRevokeDenominationKeyHandle * TALER_EXCHANGE_management_revoke_denomination_key ( struct GNUNET_CURL_Context *ctx, const char *url, - const struct GNUNET_HashCode *h_denom_pub, + const struct TALER_DenominationHashP *h_denom_pub, const struct TALER_MasterSignatureP *master_sig, TALER_EXCHANGE_ManagementRevokeDenominationKeyCallback cb, void *cb_cls); @@ -2256,6 +5098,18 @@ TALER_EXCHANGE_management_revoke_denomination_key_cancel ( /** + * Response from a POST /management/signkeys/$SK/revoke request. + */ +struct TALER_EXCHANGE_ManagementRevokeSigningKeyResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + +}; + +/** * Function called with information about the post revocation operation result. * * @param cls closure @@ -2264,7 +5118,7 @@ TALER_EXCHANGE_management_revoke_denomination_key_cancel ( typedef void (*TALER_EXCHANGE_ManagementRevokeSigningKeyCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementRevokeSigningKeyResponse *hr); /** @@ -2305,15 +5159,515 @@ TALER_EXCHANGE_management_revoke_signing_key_cancel ( /** - * Function called with information about the auditor setup operation result. + * Response from a POST /management/aml-officers request. + */ +struct TALER_EXCHANGE_ManagementUpdateAmlOfficerResponse +{ + /** + * HTTP response data + */ + struct TALER_EXCHANGE_HttpResponse hr; + +}; + +/** + * Function called with information about the change to + * an AML officer status. * * @param cls closure * @param hr HTTP response data */ typedef void +(*TALER_EXCHANGE_ManagementUpdateAmlOfficerCallback) ( + void *cls, + const struct TALER_EXCHANGE_ManagementUpdateAmlOfficerResponse *hr); + + +/** + * @brief Handle for a POST /management/aml-officers/$OFFICER_PUB request. + */ +struct TALER_EXCHANGE_ManagementUpdateAmlOfficer; + + +/** + * Inform the exchange that the status of an AML officer has changed. + * + * @param ctx the context + * @param url HTTP base URL for the exchange + * @param officer_pub the public signing key of the officer + * @param officer_name name of the officer + * @param change_date when to affect the status change + * @param is_active true to enable the officer + * @param read_only true to only allow read-only access + * @param master_sig signature affirming the change + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_ManagementUpdateAmlOfficer * +TALER_EXCHANGE_management_update_aml_officer ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_AmlOfficerPublicKeyP *officer_pub, + const char *officer_name, + struct GNUNET_TIME_Timestamp change_date, + bool is_active, + bool read_only, + const struct TALER_MasterSignatureP *master_sig, + TALER_EXCHANGE_ManagementUpdateAmlOfficerCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_management_update_aml_officer() operation. + * + * @param rh handle of the operation to cancel + */ +void +TALER_EXCHANGE_management_update_aml_officer_cancel ( + struct TALER_EXCHANGE_ManagementUpdateAmlOfficer *rh); + + +/** + * Summary data about an AML decision. + */ +struct TALER_EXCHANGE_AmlDecisionSummary +{ + /** + * What is the current monthly threshold. + */ + struct TALER_Amount threshold; + + /** + * Account the decision was made for. + */ + struct TALER_PaytoHashP h_payto; + + /** + * RowID of this decision. + */ + uint64_t rowid; + + /** + * Current decision state. + */ + enum TALER_AmlDecisionState current_state; +}; + + +/** + * Information about AML decisions returned by the exchange. + */ +struct TALER_EXCHANGE_AmlDecisionsResponse +{ + /** + * HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on the HTTP response code. + */ + union + { + + /** + * Information returned on success (#MHD_HTTP_OK). + */ + struct + { + + /** + * Array of AML decision summaries returned by the exchange. + */ + const struct TALER_EXCHANGE_AmlDecisionSummary *decisions; + + /** + * Length of the @e decisions array. + */ + unsigned int decisions_length; + + } ok; + + } details; +}; + + +/** + * Function called with summary information about + * AML decisions. + * + * @param cls closure + * @param adr response data + */ +typedef void +(*TALER_EXCHANGE_LookupAmlDecisionsCallback) ( + void *cls, + const struct TALER_EXCHANGE_AmlDecisionsResponse *adr); + + +/** + * @brief Handle for a POST /aml/$OFFICER_PUB/decisions/$STATUS request. + */ +struct TALER_EXCHANGE_LookupAmlDecisions; + + +/** + * Inform the exchange that an AML decision has been taken. + * + * @param ctx the context + * @param exchange_url HTTP base URL for the exchange + * @param start row number starting point (exclusive rowid) + * @param delta number of records to return, negative for descending, positive for ascending from start + * @param state type of AML decisions to return + * @param officer_priv private key of the deciding AML officer + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_LookupAmlDecisions * +TALER_EXCHANGE_lookup_aml_decisions ( + struct GNUNET_CURL_Context *ctx, + const char *exchange_url, + uint64_t start, + int delta, + enum TALER_AmlDecisionState state, + const struct TALER_AmlOfficerPrivateKeyP *officer_priv, + TALER_EXCHANGE_LookupAmlDecisionsCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_lookup_aml_decisions() operation. + * + * @param lh handle of the operation to cancel + */ +void +TALER_EXCHANGE_lookup_aml_decisions_cancel ( + struct TALER_EXCHANGE_LookupAmlDecisions *lh); + + +/** + * Detailed data about an AML decision. + */ +struct TALER_EXCHANGE_AmlDecisionDetail +{ + /** + * When was the decision made. + */ + struct GNUNET_TIME_Timestamp decision_time; + + /** + * New threshold set by this decision. + */ + struct TALER_Amount new_threshold; + + /** + * Who made the decision? + */ + struct TALER_AmlOfficerPublicKeyP decider_pub; + + /** + * Justification given for the decision. + */ + const char *justification; + + /** + * New decision state. + */ + enum TALER_AmlDecisionState new_state; +}; + + +/** + * Detailed data collected during a KYC process for the account. + */ +struct TALER_EXCHANGE_KycHistoryDetail +{ + /** + * Configuration section name of the KYC provider that contributed the data. + */ + const char *provider_section; + + /** + * The collected KYC data. + */ + const json_t *attributes; + + /** + * When was the data collection made. + */ + struct GNUNET_TIME_Timestamp collection_time; + +}; + + +/** + * Information about AML decision details returned by the exchange. + */ +struct TALER_EXCHANGE_AmlDecisionResponse +{ + /** + * HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on the HTTP response code. + */ + union + { + + /** + * Information returned on success (#MHD_HTTP_OK). + */ + struct + { + + /** + * Array of AML decision details returned by the exchange. + */ + const struct TALER_EXCHANGE_AmlDecisionDetail *aml_history; + + /** + * Length of the @e aml_history array. + */ + unsigned int aml_history_length; + + /** + * Array of KYC data collections returned by the exchange. + */ + const struct TALER_EXCHANGE_KycHistoryDetail *kyc_attributes; + + /** + * Length of the @e kyc_attributes array. + */ + unsigned int kyc_attributes_length; + + } ok; + + } details; +}; + + +/** + * Function called with summary information about + * AML decisions. + * + * @param cls closure + * @param adr response data + */ +typedef void +(*TALER_EXCHANGE_LookupAmlDecisionCallback) ( + void *cls, + const struct TALER_EXCHANGE_AmlDecisionResponse *adr); + + +/** + * @brief Handle for a POST /aml/$OFFICER_PUB/decision/$H_PAYTO request. + */ +struct TALER_EXCHANGE_LookupAmlDecision; + + +/** + * Inform the exchange that an AML decision has been taken. + * + * @param ctx the context + * @param exchange_url HTTP base URL for the exchange + * @param h_payto which account to return the decision history for + * @param officer_priv private key of the deciding AML officer + * @param history true to return the full history, otherwise only the last decision + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_LookupAmlDecision * +TALER_EXCHANGE_lookup_aml_decision ( + struct GNUNET_CURL_Context *ctx, + const char *exchange_url, + const struct TALER_PaytoHashP *h_payto, + const struct TALER_AmlOfficerPrivateKeyP *officer_priv, + bool history, + TALER_EXCHANGE_LookupAmlDecisionCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_lookup_aml_decision() operation. + * + * @param rh handle of the operation to cancel + */ +void +TALER_EXCHANGE_lookup_aml_decision_cancel ( + struct TALER_EXCHANGE_LookupAmlDecision *rh); + + +/** + * @brief Handle for a POST /aml-decision/$OFFICER_PUB request. + */ +struct TALER_EXCHANGE_AddAmlDecision; + + +/** + * Response when making an AML decision. + */ +struct TALER_EXCHANGE_AddAmlDecisionResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + + +/** + * Function called with information about storing an + * an AML decision. + * + * @param cls closure + * @param adr response data + */ +typedef void +(*TALER_EXCHANGE_AddAmlDecisionCallback) ( + void *cls, + const struct TALER_EXCHANGE_AddAmlDecisionResponse *adr); + +/** + * Inform the exchange that an AML decision has been taken. + * + * @param ctx the context + * @param url HTTP base URL for the exchange + * @param justification human-readable justification + * @param decision_time when was the decision made + * @param new_threshold at what monthly amount threshold + * should a revision be triggered + * @param h_payto payto URI hash of the account the + * decision is about + * @param new_state updated AML state + * @param kyc_requirements JSON array of KYC requirements being imposed, NULL for none + * @param officer_priv private key of the deciding AML officer + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_AddAmlDecision * +TALER_EXCHANGE_add_aml_decision ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const char *justification, + struct GNUNET_TIME_Timestamp decision_time, + const struct TALER_Amount *new_threshold, + const struct TALER_PaytoHashP *h_payto, + enum TALER_AmlDecisionState new_state, + const json_t *kyc_requirements, + const struct TALER_AmlOfficerPrivateKeyP *officer_priv, + TALER_EXCHANGE_AddAmlDecisionCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_add_aml_decision() operation. + * + * @param rh handle of the operation to cancel + */ +void +TALER_EXCHANGE_add_aml_decision_cancel ( + struct TALER_EXCHANGE_AddAmlDecision *rh); + + +/** + * Response when adding a partner exchange. + */ +struct TALER_EXCHANGE_ManagementAddPartnerResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + +/** + * Function called with information about the change to + * an AML officer status. + * + * @param cls closure + * @param apr response data + */ +typedef void +(*TALER_EXCHANGE_ManagementAddPartnerCallback) ( + void *cls, + const struct TALER_EXCHANGE_ManagementAddPartnerResponse *apr); + + +/** + * @brief Handle for a POST /management/partners/$PARTNER_PUB request. + */ +struct TALER_EXCHANGE_ManagementAddPartner; + + +/** + * Inform the exchange that the status of a partnering + * exchange was defined. + * + * @param ctx the context + * @param url HTTP base URL for the exchange + * @param partner_pub the offline signing key of the partner + * @param start_date validity period start + * @param end_date validity period end + * @param wad_frequency how often will we do wad transfers to this partner + * @param wad_fee what is the wad fee to this partner + * @param partner_base_url what is the base URL of the @a partner_pub exchange + * @param master_sig the signature the signature + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_ManagementAddPartner * +TALER_EXCHANGE_management_add_partner ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_MasterPublicKeyP *partner_pub, + struct GNUNET_TIME_Timestamp start_date, + struct GNUNET_TIME_Timestamp end_date, + struct GNUNET_TIME_Relative wad_frequency, + const struct TALER_Amount *wad_fee, + const char *partner_base_url, + const struct TALER_MasterSignatureP *master_sig, + TALER_EXCHANGE_ManagementAddPartnerCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_management_add_partner() operation. + * + * @param rh handle of the operation to cancel + */ +void +TALER_EXCHANGE_management_add_partner_cancel ( + struct TALER_EXCHANGE_ManagementAddPartner *rh); + + +/** + * Response when enabling an auditor. + */ +struct TALER_EXCHANGE_ManagementAuditorEnableResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + +/** + * Function called with information about the auditor setup operation result. + * + * @param cls closure + * @param aer response data + */ +typedef void (*TALER_EXCHANGE_ManagementAuditorEnableCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementAuditorEnableResponse *aer); /** @@ -2343,7 +5697,7 @@ TALER_EXCHANGE_management_enable_auditor ( const struct TALER_AuditorPublicKeyP *auditor_pub, const char *auditor_url, const char *auditor_name, - struct GNUNET_TIME_Absolute validity_start, + struct GNUNET_TIME_Timestamp validity_start, const struct TALER_MasterSignatureP *master_sig, TALER_EXCHANGE_ManagementAuditorEnableCallback cb, void *cb_cls); @@ -2358,17 +5712,27 @@ void TALER_EXCHANGE_management_enable_auditor_cancel ( struct TALER_EXCHANGE_ManagementAuditorEnableHandle *ah); +/** + * Response when disabling an auditor. + */ +struct TALER_EXCHANGE_ManagementAuditorDisableResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; /** * Function called with information about the auditor disable operation result. * * @param cls closure - * @param hr HTTP response data + * @param adr HTTP response data */ typedef void (*TALER_EXCHANGE_ManagementAuditorDisableCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementAuditorDisableResponse *adr); /** @@ -2394,7 +5758,7 @@ TALER_EXCHANGE_management_disable_auditor ( struct GNUNET_CURL_Context *ctx, const char *url, const struct TALER_AuditorPublicKeyP *auditor_pub, - struct GNUNET_TIME_Absolute validity_end, + struct GNUNET_TIME_Timestamp validity_end, const struct TALER_MasterSignatureP *master_sig, TALER_EXCHANGE_ManagementAuditorDisableCallback cb, void *cb_cls); @@ -2411,15 +5775,27 @@ TALER_EXCHANGE_management_disable_auditor_cancel ( /** + * Response from an exchange account/enable operation. + */ +struct TALER_EXCHANGE_ManagementWireEnableResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + + +/** * Function called with information about the wire enable operation result. * * @param cls closure - * @param hr HTTP response data + * @param wer HTTP response data */ typedef void (*TALER_EXCHANGE_ManagementWireEnableCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementWireEnableResponse *wer); /** @@ -2434,11 +5810,16 @@ struct TALER_EXCHANGE_ManagementWireEnableHandle; * @param ctx the context * @param url HTTP base URL for the exchange * @param payto_uri RFC 8905 URI of the exchange's bank account + * @param conversion_url URL of the conversion service, or NULL if none + * @param debit_restrictions JSON encoding of debit restrictions on the account; see AccountRestriction in the spec + * @param credit_restrictions JSON encoding of credit restrictions on the account; see AccountRestriction in the spec * @param validity_start when was this decided? * @param master_sig1 signature affirming the wire addition * of purpose #TALER_SIGNATURE_MASTER_ADD_WIRE * @param master_sig2 signature affirming the validity of the account for clients; * of purpose #TALER_SIGNATURE_MASTER_WIRE_DETAILS. + * @param bank_label label to use when showing the account, can be NULL + * @param priority priority for ordering the bank accounts * @param cb function to call with the exchange's result * @param cb_cls closure for @a cb * @return the request handle; NULL upon error @@ -2448,9 +5829,14 @@ TALER_EXCHANGE_management_enable_wire ( struct GNUNET_CURL_Context *ctx, const char *url, const char *payto_uri, - struct GNUNET_TIME_Absolute validity_start, + const char *conversion_url, + const json_t *debit_restrictions, + const json_t *credit_restrictions, + struct GNUNET_TIME_Timestamp validity_start, const struct TALER_MasterSignatureP *master_sig1, const struct TALER_MasterSignatureP *master_sig2, + const char *bank_label, + int64_t priority, TALER_EXCHANGE_ManagementWireEnableCallback cb, void *cb_cls); @@ -2466,15 +5852,26 @@ TALER_EXCHANGE_management_enable_wire_cancel ( /** + * Response from an exchange account/disable operation. + */ +struct TALER_EXCHANGE_ManagementWireDisableResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + +/** * Function called with information about the wire disable operation result. * * @param cls closure - * @param hr HTTP response data + * @param wdr response data */ typedef void (*TALER_EXCHANGE_ManagementWireDisableCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementWireDisableResponse *wdr); /** @@ -2501,7 +5898,7 @@ TALER_EXCHANGE_management_disable_wire ( struct GNUNET_CURL_Context *ctx, const char *url, const char *payto_uri, - struct GNUNET_TIME_Absolute validity_end, + struct GNUNET_TIME_Timestamp validity_end, const struct TALER_MasterSignatureP *master_sig, TALER_EXCHANGE_ManagementWireDisableCallback cb, void *cb_cls); @@ -2518,15 +5915,26 @@ TALER_EXCHANGE_management_disable_wire_cancel ( /** + * Response when setting wire fees. + */ +struct TALER_EXCHANGE_ManagementSetWireFeeResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + +/** * Function called with information about the wire enable operation result. * * @param cls closure - * @param hr HTTP response data + * @param wfr response data */ typedef void (*TALER_EXCHANGE_ManagementSetWireFeeCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_ManagementSetWireFeeResponse *wfr); /** @@ -2543,8 +5951,7 @@ struct TALER_EXCHANGE_ManagementSetWireFeeHandle; * @param wire_method for which wire method are fees provided * @param validity_start start date for the provided wire fees * @param validity_end end date for the provided wire fees - * @param wire_fee the wire fee for this time period - * @param closing_fee the closing fee for this time period + * @param fees the wire fees for this time period * @param master_sig signature affirming the wire fees; * of purpose #TALER_SIGNATURE_MASTER_WIRE_FEES * @param cb function to call with the exchange's result @@ -2556,12 +5963,11 @@ TALER_EXCHANGE_management_set_wire_fees ( struct GNUNET_CURL_Context *ctx, const char *exchange_base_url, const char *wire_method, - struct GNUNET_TIME_Absolute validity_start, - struct GNUNET_TIME_Absolute validity_end, - const struct TALER_Amount *wire_fee, - const struct TALER_Amount *closing_fee, + struct GNUNET_TIME_Timestamp validity_start, + struct GNUNET_TIME_Timestamp validity_end, + const struct TALER_WireFeeSet *fees, const struct TALER_MasterSignatureP *master_sig, - TALER_EXCHANGE_ManagementWireEnableCallback cb, + TALER_EXCHANGE_ManagementSetWireFeeCallback cb, void *cb_cls); @@ -2576,16 +5982,100 @@ TALER_EXCHANGE_management_set_wire_fees_cancel ( /** + * Response when setting global fees. + */ +struct TALER_EXCHANGE_ManagementSetGlobalFeeResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + + +/** + * Function called with information about the global fee setting operation result. + * + * @param cls closure + * @param gfr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ManagementSetGlobalFeeCallback) ( + void *cls, + const struct TALER_EXCHANGE_ManagementSetGlobalFeeResponse *gfr); + + +/** + * @brief Handle for a POST /management/global-fees request. + */ +struct TALER_EXCHANGE_ManagementSetGlobalFeeHandle; + + +/** + * Inform the exchange about global fees. + * + * @param ctx the context + * @param exchange_base_url HTTP base URL for the exchange + * @param validity_start start date for the provided wire fees + * @param validity_end end date for the provided wire fees + * @param fees the wire fees for this time period + * @param purse_timeout when do purses time out + * @param history_expiration how long are account histories preserved + * @param purse_account_limit how many purses are free per account + * @param master_sig signature affirming the wire fees; + * of purpose #TALER_SIGNATURE_MASTER_GLOBAL_FEES + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_ManagementSetGlobalFeeHandle * +TALER_EXCHANGE_management_set_global_fees ( + struct GNUNET_CURL_Context *ctx, + const char *exchange_base_url, + struct GNUNET_TIME_Timestamp validity_start, + struct GNUNET_TIME_Timestamp validity_end, + const struct TALER_GlobalFeeSet *fees, + struct GNUNET_TIME_Relative purse_timeout, + struct GNUNET_TIME_Relative history_expiration, + uint32_t purse_account_limit, + const struct TALER_MasterSignatureP *master_sig, + TALER_EXCHANGE_ManagementSetGlobalFeeCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_management_enable_wire() operation. + * + * @param sgfh handle of the operation to cancel + */ +void +TALER_EXCHANGE_management_set_global_fees_cancel ( + struct TALER_EXCHANGE_ManagementSetGlobalFeeHandle *sgfh); + + +/** + * Response when adding denomination signature by auditor. + */ +struct TALER_EXCHANGE_AuditorAddDenominationResponse +{ + /** + * HTTP response data. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + + +/** * Function called with information about the POST * /auditor/$AUDITOR_PUB/$H_DENOM_PUB operation result. * * @param cls closure - * @param hr HTTP response data + * @param adr HTTP response data */ typedef void (*TALER_EXCHANGE_AuditorAddDenominationCallback) ( void *cls, - const struct TALER_EXCHANGE_HttpResponse *hr); + const struct TALER_EXCHANGE_AuditorAddDenominationResponse *adr); /** @@ -2611,7 +6101,7 @@ struct TALER_EXCHANGE_AuditorAddDenominationHandle * TALER_EXCHANGE_add_auditor_denomination ( struct GNUNET_CURL_Context *ctx, const char *url, - const struct GNUNET_HashCode *h_denom_pub, + const struct TALER_DenominationHashP *h_denom_pub, const struct TALER_AuditorPublicKeyP *auditor_pub, const struct TALER_AuditorSignatureP *auditor_sig, TALER_EXCHANGE_AuditorAddDenominationCallback cb, @@ -2628,4 +6118,1210 @@ TALER_EXCHANGE_add_auditor_denomination_cancel ( struct TALER_EXCHANGE_AuditorAddDenominationHandle *ah); +/* ********************* W2W API ****************** */ + + +/** + * Response generated for a contract get request. + */ +struct TALER_EXCHANGE_ContractGetResponse +{ + /** + * Full HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on the HTTP status code. + */ + union + { + /** + * Information returned on #MHD_HTTP_OK. + */ + struct + { + + /** + * Public key of the purse. + */ + struct TALER_PurseContractPublicKeyP purse_pub; + + /** + * Encrypted contract. + */ + const void *econtract; + + /** + * Number of bytes in @e econtract. + */ + size_t econtract_size; + + } ok; + + } details; + +}; + +/** + * Function called with information about the a purse. + * + * @param cls closure + * @param cgr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ContractGetCallback) ( + void *cls, + const struct TALER_EXCHANGE_ContractGetResponse *cgr); + + +/** + * @brief Handle for a GET /contracts/$CPUB request. + */ +struct TALER_EXCHANGE_ContractsGetHandle; + + +/** + * Request information about a contract from the exchange. + * + * @param ctx CURL context + * @param url exchange base URL + * @param contract_priv private key of the contract + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_ContractsGetHandle * +TALER_EXCHANGE_contract_get ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_ContractDiffiePrivateP *contract_priv, + TALER_EXCHANGE_ContractGetCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_contract_get() operation. + * + * @param cgh handle of the operation to cancel + */ +void +TALER_EXCHANGE_contract_get_cancel ( + struct TALER_EXCHANGE_ContractsGetHandle *cgh); + + +/** + * Response generated for a purse get request. + */ +struct TALER_EXCHANGE_PurseGetResponse +{ + /** + * Full HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on the HTTP status. + */ + union + { + /** + * Response on #MHD_HTTP_OK. + */ + struct + { + + /** + * Time when the purse was merged (or zero if it + * was not merged). + */ + struct GNUNET_TIME_Timestamp merge_timestamp; + + /** + * Time when the full amount was deposited into + * the purse (or zero if a sufficient amount + * was not yet deposited). + */ + struct GNUNET_TIME_Timestamp deposit_timestamp; + + /** + * Reserve balance (how much was deposited in + * total into the reserve, minus deposit fees). + */ + struct TALER_Amount balance; + + /** + * Time when the purse will expire. + */ + struct GNUNET_TIME_Timestamp purse_expiration; + + } ok; + + } details; + +}; + + +/** + * Function called with information about the a purse. + * + * @param cls closure + * @param pgr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_PurseGetCallback) ( + void *cls, + const struct TALER_EXCHANGE_PurseGetResponse *pgr); + + +/** + * @brief Handle for a GET /purses/$PPUB request. + */ +struct TALER_EXCHANGE_PurseGetHandle; + + +/** + * Request information about a purse from the exchange. + * + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param purse_pub public key of the purse + * @param timeout how long to wait for a change to happen + * @param wait_for_merge true to wait for a merge event, otherwise wait for a deposit event + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_PurseGetHandle * +TALER_EXCHANGE_purse_get ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_PurseContractPublicKeyP *purse_pub, + struct GNUNET_TIME_Relative timeout, + bool wait_for_merge, + TALER_EXCHANGE_PurseGetCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_purse_get() operation. + * + * @param pgh handle of the operation to cancel + */ +void +TALER_EXCHANGE_purse_get_cancel ( + struct TALER_EXCHANGE_PurseGetHandle *pgh); + + +/** + * Response generated for a purse creation request. + */ +struct TALER_EXCHANGE_PurseCreateDepositResponse +{ + /** + * Full HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on the HTTP status. + */ + union + { + + /** + * Detailed returned on #MHD_HTTP_OK. + */ + struct + { + /** + * Signing key used by the exchange to sign the + * purse create with deposit confirmation. + */ + struct TALER_ExchangePublicKeyP exchange_pub; + + /** + * Signature from the exchange on the + * purse create with deposit confirmation. + */ + struct TALER_ExchangeSignatureP exchange_sig; + + + } ok; + + } details; + +}; + +/** + * Function called with information about the creation + * of a new purse. + * + * @param cls closure + * @param pcr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_PurseCreateDepositCallback) ( + void *cls, + const struct TALER_EXCHANGE_PurseCreateDepositResponse *pcr); + + +/** + * @brief Handle for a POST /purses/$PID/create request. + */ +struct TALER_EXCHANGE_PurseCreateDepositHandle; + + +/** + * Information about a coin to be deposited into a purse or reserve. + */ +struct TALER_EXCHANGE_PurseDeposit +{ + /** + * Age commitment data, might be NULL. + */ + const struct TALER_AgeCommitmentProof *age_commitment_proof; + + /** + * Private key of the coin. + */ + struct TALER_CoinSpendPrivateKeyP coin_priv; + + /** + * Signature proving the validity of the coin. + */ + struct TALER_DenominationSignature denom_sig; + + /** + * Hash of the denomination's public key. + */ + struct TALER_DenominationHashP h_denom_pub; + + /** + * Amount of the coin to transfer into the purse. + */ + struct TALER_Amount amount; + +}; + + +/** + * Inform the exchange that a purse should be created + * and coins deposited into it. + * + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param purse_priv private key of the purse + * @param merge_priv the merge credential + * @param contract_priv key needed to obtain and decrypt the contract + * @param contract_terms contract the purse is about + * @param num_deposits length of the @a deposits array + * @param deposits array of deposits to make into the purse + * @param upload_contract true to upload the contract; must + * be FALSE for repeated calls to this API for the + * same purse (i.e. when adding more deposits). + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_PurseCreateDepositHandle * +TALER_EXCHANGE_purse_create_with_deposit ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_PurseContractPrivateKeyP *purse_priv, + const struct TALER_PurseMergePrivateKeyP *merge_priv, + const struct TALER_ContractDiffiePrivateP *contract_priv, + const json_t *contract_terms, + unsigned int num_deposits, + const struct TALER_EXCHANGE_PurseDeposit deposits[static num_deposits], + bool upload_contract, + TALER_EXCHANGE_PurseCreateDepositCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_purse_create_with_deposit() operation. + * + * @param pch handle of the operation to cancel + */ +void +TALER_EXCHANGE_purse_create_with_deposit_cancel ( + struct TALER_EXCHANGE_PurseCreateDepositHandle *pch); + + +/** + * Response generated for a purse deletion request. + */ +struct TALER_EXCHANGE_PurseDeleteResponse +{ + /** + * Full HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; +}; + + +/** + * Function called with information about the deletion + * of a purse. + * + * @param cls closure + * @param pdr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_PurseDeleteCallback) ( + void *cls, + const struct TALER_EXCHANGE_PurseDeleteResponse *pdr); + + +/** + * @brief Handle for a DELETE /purses/$PID request. + */ +struct TALER_EXCHANGE_PurseDeleteHandle; + + +/** + * Asks the exchange to delete a purse. Will only succeed if + * the purse was not yet merged and did not yet time out. + * + * @param ctx CURL context + * @param url exchange base URL + * @param purse_priv private key of the purse + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_PurseDeleteHandle * +TALER_EXCHANGE_purse_delete ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_PurseContractPrivateKeyP *purse_priv, + TALER_EXCHANGE_PurseDeleteCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_purse_delete() operation. + * + * @param pdh handle of the operation to cancel + */ +void +TALER_EXCHANGE_purse_delete_cancel ( + struct TALER_EXCHANGE_PurseDeleteHandle *pdh); + + +/** + * Response generated for an account merge request. + */ +struct TALER_EXCHANGE_AccountMergeResponse +{ + /** + * Full HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Reserve signature affirming the merge. + */ + const struct TALER_ReserveSignatureP *reserve_sig; + + /** + * Details depending on the HTTP status. + */ + union + { + /** + * Detailed returned on #MHD_HTTP_OK. + */ + struct + { + /** + * Signature by the exchange affirming the merge. + */ + struct TALER_ExchangeSignatureP exchange_sig; + + /** + * Online signing key used by the exchange. + */ + struct TALER_ExchangePublicKeyP exchange_pub; + + /** + * Timestamp of the exchange for @e exchange_sig. + */ + struct GNUNET_TIME_Timestamp etime; + + } ok; + + /** + * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. + */ + struct + { + /** + * Requirement row target that the merchant should use + * to check for its KYC status. + */ + uint64_t requirement_row; + } unavailable_for_legal_reasons; + + } details; + +}; + +/** + * Function called with information about an account merge + * operation. + * + * @param cls closure + * @param amr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_AccountMergeCallback) ( + void *cls, + const struct TALER_EXCHANGE_AccountMergeResponse *amr); + + +/** + * @brief Handle for a POST /purses/$PID/merge request. + */ +struct TALER_EXCHANGE_AccountMergeHandle; + + +/** + * Inform the exchange that a purse should be merged + * with a reserve. + * + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param reserve_exchange_url base URL of the exchange with the reserve + * @param reserve_priv private key of the reserve to merge into + * @param purse_pub public key of the purse to merge + * @param merge_priv private key granting us the right to merge + * @param h_contract_terms hash of the purses' contract + * @param min_age minimum age of deposits into the purse + * @param purse_value_after_fees amount that should be in the purse + * @param purse_expiration when will the purse expire + * @param merge_timestamp when is the merge happening (current time) + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_AccountMergeHandle * +TALER_EXCHANGE_account_merge ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const char *reserve_exchange_url, + const struct TALER_ReservePrivateKeyP *reserve_priv, + const struct TALER_PurseContractPublicKeyP *purse_pub, + const struct TALER_PurseMergePrivateKeyP *merge_priv, + const struct TALER_PrivateContractHashP *h_contract_terms, + uint8_t min_age, + const struct TALER_Amount *purse_value_after_fees, + struct GNUNET_TIME_Timestamp purse_expiration, + struct GNUNET_TIME_Timestamp merge_timestamp, + TALER_EXCHANGE_AccountMergeCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_account_merge() operation. + * + * @param amh handle of the operation to cancel + */ +void +TALER_EXCHANGE_account_merge_cancel ( + struct TALER_EXCHANGE_AccountMergeHandle *amh); + + +/** + * Response generated for a purse creation request. + */ +struct TALER_EXCHANGE_PurseCreateMergeResponse +{ + /** + * Full HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Reserve signature generated for the request + * (client-side). + */ + const struct TALER_ReserveSignatureP *reserve_sig; + + /** + * Details depending on the HTTP status. + */ + union + { + /** + * Details returned on #MHD_HTTP_OK. + */ + struct + { + + } ok; + + /** + * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. + */ + struct + { + /** + * Requirement row that the merchant should use + * to check for its KYC status. + */ + uint64_t requirement_row; + } unavailable_for_legal_reasons; + + } details; + +}; + +/** + * Function called with information about the creation + * of a new purse. + * + * @param cls closure + * @param pcr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_PurseCreateMergeCallback) ( + void *cls, + const struct TALER_EXCHANGE_PurseCreateMergeResponse *pcr); + + +/** + * @brief Handle for a POST /reserves/$RID/purse request. + */ +struct TALER_EXCHANGE_PurseCreateMergeHandle; + + +/** + * Inform the exchange that a purse should be created + * and merged with a reserve. + * + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param reserve_priv private key of the reserve + * @param purse_priv private key of the purse + * @param merge_priv private key of the merge capability + * @param contract_priv private key to get the contract + * @param contract_terms contract the purse is about + * @param upload_contract true to upload the contract + * @param pay_for_purse true to pay for purse creation + * @param merge_timestamp when should the merge happen (use current time) + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_PurseCreateMergeHandle * +TALER_EXCHANGE_purse_create_with_merge ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_ReservePrivateKeyP *reserve_priv, + const struct TALER_PurseContractPrivateKeyP *purse_priv, + const struct TALER_PurseMergePrivateKeyP *merge_priv, + const struct TALER_ContractDiffiePrivateP *contract_priv, + const json_t *contract_terms, + bool upload_contract, + bool pay_for_purse, + struct GNUNET_TIME_Timestamp merge_timestamp, + TALER_EXCHANGE_PurseCreateMergeCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_purse_create_with_merge() operation. + * + * @param pcm handle of the operation to cancel + */ +void +TALER_EXCHANGE_purse_create_with_merge_cancel ( + struct TALER_EXCHANGE_PurseCreateMergeHandle *pcm); + + +/** + * Response generated for purse deposit request. + */ +struct TALER_EXCHANGE_PurseDepositResponse +{ + /** + * Full HTTP response. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on the HTTP status. + */ + union + { + /** + * Detailed returned on #MHD_HTTP_OK. + */ + struct + { + + /** + * When does the purse expire. + */ + struct GNUNET_TIME_Timestamp purse_expiration; + + /** + * How much was actually deposited into the purse. + */ + struct TALER_Amount total_deposited; + + /** + * How much should be in the purse in total in the end. + */ + struct TALER_Amount purse_value_after_fees; + + /** + * Hash of the contract (needed to verify signature). + */ + struct TALER_PrivateContractHashP h_contract_terms; + + } ok; + } details; + +}; + +/** + * Function called with information about a purse-deposit + * operation. + * + * @param cls closure + * @param pdr HTTP response data + */ +typedef void +(*TALER_EXCHANGE_PurseDepositCallback) ( + void *cls, + const struct TALER_EXCHANGE_PurseDepositResponse *pdr); + + +/** + * @brief Handle for a POST /purses/$PID/deposit request. + */ +struct TALER_EXCHANGE_PurseDepositHandle; + + +/** + * Inform the exchange that a deposit should be made into + * a purse. + * + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param purse_exchange_url base URL of the exchange hosting the purse + * @param purse_pub public key of the purse to merge + * @param min_age minimum age we need to prove for the purse + * @param num_deposits length of the @a deposits array + * @param deposits array of deposits to make into the purse + * @param cb function to call with the exchange's result + * @param cb_cls closure for @a cb + * @return the request handle; NULL upon error + */ +struct TALER_EXCHANGE_PurseDepositHandle * +TALER_EXCHANGE_purse_deposit ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const char *purse_exchange_url, + const struct TALER_PurseContractPublicKeyP *purse_pub, + uint8_t min_age, + unsigned int num_deposits, + const struct TALER_EXCHANGE_PurseDeposit deposits[static num_deposits], + TALER_EXCHANGE_PurseDepositCallback cb, + void *cb_cls); + + +/** + * Cancel #TALER_EXCHANGE_purse_deposit() operation. + * + * @param amh handle of the operation to cancel + */ +void +TALER_EXCHANGE_purse_deposit_cancel ( + struct TALER_EXCHANGE_PurseDepositHandle *amh); + + +/* ********************* /reserves/$RID/open *********************** */ + + +/** + * @brief A /reserves/$RID/open Handle + */ +struct TALER_EXCHANGE_ReservesOpenHandle; + + +/** + * @brief Reserve open result details. + */ +struct TALER_EXCHANGE_ReserveOpenResult +{ + + /** + * High-level HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on @e hr.http_status. + */ + union + { + + /** + * Information returned on success, if + * @e hr.http_status is #MHD_HTTP_OK + */ + struct + { + /** + * New expiration time + */ + struct GNUNET_TIME_Timestamp expiration_time; + + /** + * Actual cost of the open operation. + */ + struct TALER_Amount open_cost; + + } ok; + + + /** + * Information returned if the payment provided is insufficient, if + * @e hr.http_status is #MHD_HTTP_PAYMENT_REQUIRED + */ + struct + { + /** + * Current expiration time of the reserve. + */ + struct GNUNET_TIME_Timestamp expiration_time; + + /** + * Actual cost of the open operation that should have been paid. + */ + struct TALER_Amount open_cost; + + } payment_required; + + /** + * Information returned if status is + * #MHD_HTTP_CONFLICT. + */ + struct + { + /** + * Public key of the coin that caused the conflict. + */ + struct TALER_CoinSpendPublicKeyP coin_pub; + + } conflict; + + /** + * Information returned if KYC is required to proceed, set if + * @e hr.http_status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. + */ + struct + { + /** + * Requirement row that the merchant should use + * to check for its KYC status. + */ + uint64_t requirement_row; + + /** + * Hash of the payto-URI of the account to KYC; + */ + struct TALER_PaytoHashP h_payto; + + } unavailable_for_legal_reasons; + + } details; + +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * reserve open request to a exchange. + * + * @param cls closure + * @param ror HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ReservesOpenCallback) ( + void *cls, + const struct TALER_EXCHANGE_ReserveOpenResult *ror); + + +/** + * Submit a request to open a reserve. + * + * @param ctx curl context + * @param url exchange base URL + * @param keys exchange keys + * @param reserve_priv private key of the reserve to open + * @param reserve_contribution amount to pay from the reserve's balance for the operation + * @param coin_payments_length length of the @a coin_payments array + * @param coin_payments array of coin payments to use for opening the reserve + * @param expiration_time desired new expiration time for the reserve + * @param min_purses minimum number of purses to allow being concurrently opened per reserve + * @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_ReservesOpenHandle * +TALER_EXCHANGE_reserves_open ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_ReservePrivateKeyP *reserve_priv, + const struct TALER_Amount *reserve_contribution, + unsigned int coin_payments_length, + const struct TALER_EXCHANGE_PurseDeposit coin_payments[ + static coin_payments_length], + struct GNUNET_TIME_Timestamp expiration_time, + uint32_t min_purses, + TALER_EXCHANGE_ReservesOpenCallback cb, + void *cb_cls); + + +/** + * Cancel a reserve status request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param[in] roh the reserve open request handle + */ +void +TALER_EXCHANGE_reserves_open_cancel ( + struct TALER_EXCHANGE_ReservesOpenHandle *roh); + + +/* ********************* /reserves/$RID/attest *********************** */ + + +/** + * @brief A Get /reserves/$RID/attest Handle + */ +struct TALER_EXCHANGE_ReservesGetAttestHandle; + + +/** + * @brief Reserve GET attest result details. + */ +struct TALER_EXCHANGE_ReserveGetAttestResult +{ + + /** + * High-level HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on @e hr.http_status. + */ + union + { + + /** + * Information returned on success, if + * @e hr.http_status is #MHD_HTTP_OK + */ + struct + { + + /** + * Length of the @e attributes array. + */ + unsigned int attributes_length; + + /** + * Array of attributes available about the user. + */ + const char **attributes; + + } ok; + + } details; + +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * reserve attest request to a exchange. + * + * @param cls closure + * @param ror HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ReservesGetAttestCallback) ( + void *cls, + const struct TALER_EXCHANGE_ReserveGetAttestResult *ror); + + +/** + * Submit a request to get the list of attestable attributes for a reserve. + * + * @param ctx CURL context + * @param url exchange base URL + * @param reserve_pub public key of the reserve to get available attributes for + * @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_ReservesGetAttestHandle * +TALER_EXCHANGE_reserves_get_attestable ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_ReservePublicKeyP *reserve_pub, + TALER_EXCHANGE_ReservesGetAttestCallback cb, + void *cb_cls); + + +/** + * Cancel a request to get attestable attributes. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param rgah the reserve get attestable request handle + */ +void +TALER_EXCHANGE_reserves_get_attestable_cancel ( + struct TALER_EXCHANGE_ReservesGetAttestHandle *rgah); + + +/** + * @brief A POST /reserves/$RID/attest Handle + */ +struct TALER_EXCHANGE_ReservesPostAttestHandle; + + +/** + * @brief Reserve attest result details. + */ +struct TALER_EXCHANGE_ReservePostAttestResult +{ + + /** + * High-level HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on @e hr.http_status. + */ + union + { + + /** + * Information returned on success, if + * @e hr.http_status is #MHD_HTTP_OK + */ + struct + { + /** + * Time when the exchange made the signature. + */ + struct GNUNET_TIME_Timestamp exchange_time; + + /** + * Expiration time of the attested attributes. + */ + struct GNUNET_TIME_Timestamp expiration_time; + + /** + * Signature by the exchange affirming the attributes. + */ + struct TALER_ExchangeSignatureP exchange_sig; + + /** + * Online signing key used by the exchange. + */ + struct TALER_ExchangePublicKeyP exchange_pub; + + /** + * Attributes being confirmed by the exchange. + */ + const json_t *attributes; + + } ok; + + } details; + +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * reserve attest request to a exchange. + * + * @param cls closure + * @param ror HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ReservesPostAttestCallback) ( + void *cls, + const struct TALER_EXCHANGE_ReservePostAttestResult *ror); + + +/** + * Submit a request to attest attributes about the owner of a reserve. + * + * @param ctx CURL context + * @param url exchange base URL + * @param keys exchange key data + * @param reserve_priv private key of the reserve to attest + * @param attributes_length length of the @a attributes array + * @param attributes array of names of attributes to get attestations for + * @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_ReservesAttestHandle * +TALER_EXCHANGE_reserves_attest ( + struct GNUNET_CURL_Context *ctx, + const char *url, + struct TALER_EXCHANGE_Keys *keys, + const struct TALER_ReservePrivateKeyP *reserve_priv, + unsigned int attributes_length, + const char *attributes[const static attributes_length], + TALER_EXCHANGE_ReservesPostAttestCallback cb, + void *cb_cls); + + +/** + * Cancel a reserve attestation request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param rah the reserve attest request handle + */ +void +TALER_EXCHANGE_reserves_attest_cancel ( + struct TALER_EXCHANGE_ReservesAttestHandle *rah); + + +/* ********************* /reserves/$RID/close *********************** */ + + +/** + * @brief A /reserves/$RID/close Handle + */ +struct TALER_EXCHANGE_ReservesCloseHandle; + + +/** + * @brief Reserve close result details. + */ +struct TALER_EXCHANGE_ReserveCloseResult +{ + + /** + * High-level HTTP response details. + */ + struct TALER_EXCHANGE_HttpResponse hr; + + /** + * Details depending on @e hr.http_status. + */ + union + { + + /** + * Information returned on success, if + * @e hr.http_status is #MHD_HTTP_OK + */ + struct + { + + /** + * Amount wired to the target account. + */ + struct TALER_Amount wire_amount; + } ok; + + /** + * Information returned if KYC is required to proceed, set if + * @e hr.http_status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. + */ + struct + { + /** + * Requirement row that the merchant should use + * to check for its KYC status. + */ + uint64_t requirement_row; + + /** + * Hash of the payto-URI of the account to KYC; + */ + struct TALER_PaytoHashP h_payto; + + } unavailable_for_legal_reasons; + + } details; + +}; + + +/** + * Callbacks of this type are used to serve the result of submitting a + * reserve close request to a exchange. + * + * @param cls closure + * @param ror HTTP response data + */ +typedef void +(*TALER_EXCHANGE_ReservesCloseCallback) ( + void *cls, + const struct TALER_EXCHANGE_ReserveCloseResult *ror); + + +/** + * Submit a request to close a reserve. + * + * @param ctx curl context + * @param url exchange base URL + * @param reserve_priv private key of the reserve to close + * @param target_payto_uri where to send the payment, NULL to send to reserve origin + * @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_ReservesCloseHandle * +TALER_EXCHANGE_reserves_close ( + struct GNUNET_CURL_Context *ctx, + const char *url, + const struct TALER_ReservePrivateKeyP *reserve_priv, + const char *target_payto_uri, + TALER_EXCHANGE_ReservesCloseCallback cb, + void *cb_cls); + + +/** + * Cancel a reserve status request. This function cannot be used + * on a request handle if a response is already served for it. + * + * @param rch the reserve request handle + */ +void +TALER_EXCHANGE_reserves_close_cancel ( + struct TALER_EXCHANGE_ReservesCloseHandle *rch); + #endif /* _TALER_EXCHANGE_SERVICE_H */ |