taler/exchange
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
0d1eced630
exchange/src/include/taler_exchange_service.h
Christian Grothoff 0d1eced630 first refactoring of JSON logic to address #4150 and #4237
2016-03-19 15:23:11 +01:00

1222 lines
44 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/*
This file is part of TALER
Copyright (C) 2014, 2015 GNUnet e.V.
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.
You should have received a copy of the GNU Affero General Public License along with
TALER; see the file COPYING. If not, 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
* @author Sree Harsha Totakura <sreeharsha@totakura.in>
* @author Christian Grothoff
*/
#ifndef _TALER_EXCHANGE_SERVICE_H
#define _TALER_EXCHANGE_SERVICE_H
#include <jansson.h>
#include "taler_util.h"
/* ********************* event loop *********************** */
/**
* @brief Handle to this library context. This is where the
* main event loop logic lives.
*/
struct TALER_EXCHANGE_Context;
/**
* Initialise a context. A context should be used for each thread and should
* not be shared among multiple threads.
*
* @return the context, NULL on error (failure to initialize)
*/
struct TALER_EXCHANGE_Context *
TALER_EXCHANGE_init (void);
/**
* Obtain the information for a select() call to wait until
* #TALER_EXCHANGE_perform() is ready again. Note that calling
* any other TALER_EXCHANGE-API may also imply that the library
* is again ready for #TALER_EXCHANGE_perform().
*
* Basically, a client should use this API to prepare for select(),
* then block on select(), then call #TALER_EXCHANGE_perform() and then
* start again until the work with the context is done.
*
* This function will NOT zero out the sets and assumes that @a max_fd
* and @a timeout are already set to minimal applicable values. It is
* safe to give this API FD-sets and @a max_fd and @a timeout that are
* already initialized to some other descriptors that need to go into
* the select() call.
*
* @param ctx context to get the event loop information for
* @param read_fd_set will be set for any pending read operations
* @param write_fd_set will be set for any pending write operations
* @param except_fd_set is here because curl_multi_fdset() has this argument
* @param max_fd set to the highest FD included in any set;
* if the existing sets have no FDs in it, the initial
* value should be "-1". (Note that `max_fd + 1` will need
* to be passed to select().)
* @param timeout set to the timeout in milliseconds (!); -1 means
* no timeout (NULL, blocking forever is OK), 0 means to
* proceed immediately with #TALER_EXCHANGE_perform().
*/
void
TALER_EXCHANGE_get_select_info (struct TALER_EXCHANGE_Context *ctx,
fd_set *read_fd_set,
fd_set *write_fd_set,
fd_set *except_fd_set,
int *max_fd,
long *timeout);
/**
* Run the main event loop for the Taler interaction.
*
* @param ctx the library context
*/
void
TALER_EXCHANGE_perform (struct TALER_EXCHANGE_Context *ctx);
/**
* Cleanup library initialisation resources. This function should be called
* after using this library to cleanup the resources occupied during library's
* initialisation.
*
* @param ctx the library context
*/
void
TALER_EXCHANGE_fini (struct TALER_EXCHANGE_Context *ctx);
/* ********************* /keys *********************** */
/**
* List of possible options to be passed to
* #TALER_EXCHANGE_connect().
*/
enum TALER_EXCHANGE_Option
{
/**
* Terminator (end of option list).
*/
TALER_EXCHANGE_OPTION_END = 0
};
/**
* @brief Exchange's signature key
*/
struct TALER_EXCHANGE_SigningPublicKey
{
/**
* The signing public key
*/
struct TALER_ExchangePublicKeyP key;
/**
* Validity start time
*/
struct GNUNET_TIME_Absolute valid_from;
/**
* Validity expiration time
*/
struct GNUNET_TIME_Absolute valid_until;
};
/**
* @brief Public information about a exchange's denomination key
*/
struct TALER_EXCHANGE_DenomPublicKey
{
/**
* The public key
*/
struct TALER_DenominationPublicKey key;
/**
* The hash of the public key.
*/
struct GNUNET_HashCode h_key;
/**
* Timestamp indicating when the denomination key becomes valid
*/
struct GNUNET_TIME_Absolute valid_from;
/**
* Timestamp indicating when the denomination key can’t be used anymore to
* withdraw new coins.
*/
struct GNUNET_TIME_Absolute withdraw_valid_until;
/**
* Timestamp indicating when coins of this denomination become invalid.
*/
struct GNUNET_TIME_Absolute deposit_valid_until;
/**
* When do signatures with this denomination key become invalid?
* After this point, these signatures cannot be used in (legal)
* disputes anymore, as the Exchange is then allowed to destroy its side
* of the evidence. @e expire_legal is expected to be significantly
* larger than @e expire_spend (by a year or more).
*/
struct GNUNET_TIME_Absolute expire_legal;
/**
* The value of this denomination
*/
struct TALER_Amount value;
/**
* The applicable fee for withdrawing a coin of this denomination
*/
struct TALER_Amount fee_withdraw;
/**
* 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
*/
struct TALER_Amount fee_refresh;
};
/**
* @brief Information we get from the exchange about auditors.
*/
struct TALER_EXCHANGE_AuditorInformation
{
/**
* Public key of the auditing institution.
*/
struct TALER_AuditorPublicKeyP auditor_pub;
/**
* URL of the auditing institution. The application must check that
* this is an acceptable auditor for its purpose and also verify
* that the @a auditor_pub matches the auditor's public key given at
* that website. We expect that in practice software is going to
* often ship with an initial list of accepted auditors, just like
* browsers ship with a CA root store.
*
* This field may be NULL. (#3987).
*/
const char *auditor_url;
/**
* Number of denomination keys audited by this auditor.
*/
unsigned int num_denom_keys;
/**
* Array of length @a denom_keys with the denomination
* keys audited by this auditor. Note that the array
* elements point to the same locations as the entries
* in the key's main `denom_keys` array.
*/
const struct TALER_EXCHANGE_DenomPublicKey **denom_keys;
};
/**
* @brief Information about keys from the exchange.
*/
struct TALER_EXCHANGE_Keys
{
/**
* Long-term offline signing key of the exchange.
*/
struct TALER_MasterPublicKeyP master_pub;
/**
* Array of the exchange's online signing keys.
*/
struct TALER_EXCHANGE_SigningPublicKey *sign_keys;
/**
* Array of the exchange's denomination keys.
*/
struct TALER_EXCHANGE_DenomPublicKey *denom_keys;
/**
* Array of the keys of the auditors of the exchange.
*/
struct TALER_EXCHANGE_AuditorInformation *auditors;
/**
* Length of the @e sign_keys array.
*/
unsigned int num_sign_keys;
/**
* Length of the @e denom_keys array.
*/
unsigned int num_denom_keys;
/**
* Length of the @e auditors array.
*/
unsigned int num_auditors;
};
/**
* Function called with information about who is auditing
* a particular exchange and what key the exchange is using.
*
* @param cls closure
* @param keys information about the various keys used
* by the exchange
*/
typedef void
(*TALER_EXCHANGE_CertificationCallback) (void *cls,
const 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.
*/
struct TALER_EXCHANGE_Handle;
/**
* 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.
*
* @param ctx the context
* @param url HTTP base URL for the exchange
* @param cert_cb function to call with the exchange's certification information
* @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 TALER_EXCHANGE_Context *ctx,
const char *url,
TALER_EXCHANGE_CertificationCallback cert_cb,
void *cert_cb_cls,
...);
/**
* Disconnect from the exchange.
*
* @param exchange the exchange handle
*/
void
TALER_EXCHANGE_disconnect (struct TALER_EXCHANGE_Handle *exchange);
/**
* Obtain the keys from the exchange.
*
* @param exchange the exchange handle
* @return the exchange's key set
*/
const struct TALER_EXCHANGE_Keys *
TALER_EXCHANGE_get_keys (const struct TALER_EXCHANGE_Handle *exchange);
/**
* Test if the given @a pub is a the current signing key from the exchange
* according to @a keys.
*
* @param keys the exchange's key set
* @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);
/**
* Obtain the denomination key details from the exchange.
*
* @param keys the exchange's key set
* @param pk public key of the denomination to lookup
* @return details about the given denomination key, NULL if the key is not
* found
*/
const struct TALER_EXCHANGE_DenomPublicKey *
TALER_EXCHANGE_get_denomination_key (const struct TALER_EXCHANGE_Keys *keys,
const struct TALER_DenominationPublicKey *pk);
/**
* Obtain the denomination key details from the exchange.
*
* @param keys the exchange's key set
* @param hc hash of the public key of the denomination to lookup
* @return details about the given 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);
/* ********************* /wire *********************** */
/**
* @brief A Wire format inquiry handle
*/
struct TALER_EXCHANGE_WireHandle;
/**
* Callbacks of this type are used to serve the result of submitting a
* wire format inquiry request to a exchange.
*
* The callback is invoked multiple times, once for each supported @a
* method. Finally, it is invoked one more time with cls/0/NULL/NULL
* to indicate the end of the iteration. If any request fails to
* generate a valid response from the exchange, @a http_status will also
* be zero and the iteration will also end. Thus, the iteration
* always ends with a final call with an @a http_status of 0. If the
* @a http_status is already 0 on the first call, then the response to
* the /wire request was invalid. Later, clients can tell the
* difference between @a http_status of 0 indicating a failed
* /wire/method request and a regular end of the iteration by @a
* method being non-NULL. If the exchange simply correctly asserts that
* it does not support any methods, @a method will be NULL but the @a
* http_status will be #MHD_HTTP_OK for the first call (followed by a
* cls/0/NULL/NULL call to signal the end of the iteration).
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful request;
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param method wire format method supported, i.e. "test" or "sepa", or NULL
* if already the /wire request failed.
* @param obj the received JSON reply, if successful this should be the wire
* format details as provided by /wire/METHOD/, or NULL if the
* reply was not in JSON format (in this case, the client might
* want to do an HTTP request to /wire/METHOD/ with a browser to
* provide more information to the user about the @a method).
*/
typedef void
(*TALER_EXCHANGE_WireResultCallback) (void *cls,
unsigned int http_status,
const char *method,
json_t *obj);
/**
* 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
*/
struct TALER_EXCHANGE_WireHandle *
TALER_EXCHANGE_wire (struct TALER_EXCHANGE_Handle *exchange,
TALER_EXCHANGE_WireResultCallback wire_cb,
void *wire_cb_cls);
/**
* 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
*/
void
TALER_EXCHANGE_wire_cancel (struct TALER_EXCHANGE_WireHandle *wh);
/* ********************* /deposit *********************** */
/**
* @brief A Deposit Handle
*/
struct TALER_EXCHANGE_DepositHandle;
/**
* Callbacks of this type are used to serve the result of submitting a
* deposit permission request to a exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful deposit;
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param obj the received JSON reply, should be kept as proof (and, in case of errors,
* be forwarded to the customer)
*/
typedef void
(*TALER_EXCHANGE_DepositResultCallback) (void *cls,
unsigned int http_status,
json_t *obj);
/**
* 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.
*
* 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
* 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 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 transaction_id transaction id for the transaction between merchant and customer
* @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)
* @param coin_sig the signature made with purpose #TALER_SIGNATURE_WALLET_COIN_DEPOSIT made by the customer with the coin’s private key.
* @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_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,
const struct TALER_CoinSpendPublicKeyP *coin_pub,
const struct TALER_DenominationSignature *denom_sig,
const struct TALER_DenominationPublicKey *denom_pub,
struct GNUNET_TIME_Absolute timestamp,
uint64_t transaction_id,
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);
/**
* Cancel a 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
*/
void
TALER_EXCHANGE_deposit_cancel (struct TALER_EXCHANGE_DepositHandle *deposit);
/* ********************* /reserve/status *********************** */
/**
* @brief A /reserve/status Handle
*/
struct TALER_EXCHANGE_ReserveStatusHandle;
/**
* Ways how a reserve's balance may change.
*/
enum TALER_EXCHANGE_ReserveTransactionType {
/**
* Deposit into the reserve.
*/
TALER_EXCHANGE_RTT_DEPOSIT,
/**
* Withdrawal from the reserve.
*/
TALER_EXCHANGE_RTT_WITHDRAWAL
};
/**
* @brief Entry in the reserve's transaction history.
*/
struct TALER_EXCHANGE_ReserveHistory
{
/**
* Type of the transaction.
*/
enum TALER_EXCHANGE_ReserveTransactionType type;
/**
* Amount transferred (in or out).
*/
struct TALER_Amount amount;
/**
* Details depending on @e type.
*/
union {
/**
* Transaction details for the incoming transaction.
*/
json_t *wire_in_details;
/**
* Signature authorizing the withdrawal for outgoing transaction.
*/
json_t *out_authorization_sig;
} details;
};
/**
* Callbacks of this type are used to serve the result of submitting a
* deposit permission request to a exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param[in] json original response in JSON format (useful only for diagnostics)
* @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
*/
typedef void
(*TALER_EXCHANGE_ReserveStatusResultCallback) (void *cls,
unsigned int http_status,
json_t *json,
const struct TALER_Amount *balance,
unsigned int history_length,
const struct TALER_EXCHANGE_ReserveHistory *history);
/**
* Submit a request to obtain the transaction history of a reserve
* from the exchange. Note that while we return the full response 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 and add up to the balance). 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 reserve_pub public key of the reserve to inspect
* @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_ReserveStatusHandle *
TALER_EXCHANGE_reserve_status (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_ReservePublicKeyP *reserve_pub,
TALER_EXCHANGE_ReserveStatusResultCallback cb,
void *cb_cls);
/**
* Cancel a withdraw status request. This function cannot be used
* on a request handle if a response is already served for it.
*
* @param wsh the withdraw status request handle
*/
void
TALER_EXCHANGE_reserve_status_cancel (struct TALER_EXCHANGE_ReserveStatusHandle *wsh);
/* ********************* /reserve/withdraw *********************** */
/**
* @brief A /reserve/withdraw Handle
*/
struct TALER_EXCHANGE_ReserveWithdrawHandle;
/**
* Callbacks of this type are used to serve the result of submitting a
* deposit permission request to a exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param sig signature over the coin, NULL on error
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_ReserveWithdrawResultCallback) (void *cls,
unsigned int http_status,
const struct TALER_DenominationSignature *sig,
json_t *full_response);
/**
* Withdraw a coin from the exchange using a /reserve/withdraw request. This
* API is typically used by a wallet. 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 reserve_priv private key of the reserve to withdraw from
* @param coin_priv where to store the coin's private key,
* caller must have committed this value to disk before the call (with @a pk)
* @param blinding_key where to store the coin's blinding key
* caller must have committed this value to disk before the call (with @a pk)
* @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_ReserveWithdrawHandle *
TALER_EXCHANGE_reserve_withdraw (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_EXCHANGE_DenomPublicKey *pk,
const struct TALER_ReservePrivateKeyP *reserve_priv,
const struct TALER_CoinSpendPrivateKeyP *coin_priv,
const struct TALER_DenominationBlindingKey *blinding_key,
TALER_EXCHANGE_ReserveWithdrawResultCallback 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.
*
* @param sign the withdraw sign request handle
*/
void
TALER_EXCHANGE_reserve_withdraw_cancel (struct TALER_EXCHANGE_ReserveWithdrawHandle *sign);
/* ********************* /refresh/melt+reveal ***************************** */
/**
* 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.
*
* 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_refresh_melt() that will generate the request.
*
* This function does verify that the given request data is internally
* consistent. However, the @a melts_sigs are only verified if @a
* check_sigs is set to #GNUNET_YES, as this may be relatively
* expensive and should be redundant.
*
* 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 num_melts number of coins that are being melted (typically 1)
* @param melt_privs array of @a num_melts private keys of the coins to melt
* @param melt_amounts array of @a num_melts amounts specifying how much
* each coin will contribute to the melt (including fee)
* @param melt_sigs array of @a num_melts signatures affirming the
* validity of the public keys corresponding to the
* @a melt_privs private keys
* @param melt_pks array of @a num_melts denomination key information
* records corresponding to the @a melt_sigs
* validity of the keys
* @param check_sigs verify the validity of the signatures of @a melt_sigs
* @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
* @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_refresh_melt().
* Non-null results should be freed using #GNUNET_free().
*/
char *
TALER_EXCHANGE_refresh_prepare (unsigned int num_melts,
const struct TALER_CoinSpendPrivateKeyP *melt_privs,
const struct TALER_Amount *melt_amounts,
const struct TALER_DenominationSignature *melt_sigs,
const struct TALER_EXCHANGE_DenomPublicKey *melt_pks,
int check_sigs,
unsigned int fresh_pks_len,
const struct TALER_EXCHANGE_DenomPublicKey *fresh_pks,
size_t *res_size);
/* ********************* /refresh/melt ***************************** */
/**
* @brief A /refresh/melt Handle
*/
struct TALER_EXCHANGE_RefreshMeltHandle;
/**
* Callbacks of this type are used to notify the application about the
* result of the /refresh/melt stage. If successful, the @a noreveal_index
* should be committed to disk prior to proceeding #TALER_EXCHANGE_refresh_reveal().
*
* @param cls closure
* @param http_status HTTP response code, never #MHD_HTTP_OK (200) as for successful intermediate response this callback is skipped.
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param noreveal_index choice by the exchange in the cut-and-choose protocol,
* UINT16_MAX on error
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_RefreshMeltCallback) (void *cls,
unsigned int http_status,
uint16_t noreveal_index,
json_t *full_response);
/**
* Submit a melt 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 should have been constructed using
* #TALER_EXCHANGE_refresh_prepare and 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 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_RefreshMeltHandle *
TALER_EXCHANGE_refresh_melt (struct TALER_EXCHANGE_Handle *exchange,
size_t refresh_data_length,
const char *refresh_data,
TALER_EXCHANGE_RefreshMeltCallback melt_cb,
void *melt_cb_cls);
/**
* Cancel a refresh melt request. This function cannot be used
* on a request handle if the callback was already invoked.
*
* @param rmh the refresh handle
*/
void
TALER_EXCHANGE_refresh_melt_cancel (struct TALER_EXCHANGE_RefreshMeltHandle *rmh);
/* ********************* /refresh/reveal ***************************** */
/**
* 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.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @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 full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_RefreshRevealCallback) (void *cls,
unsigned int http_status,
unsigned int num_coins,
const struct TALER_CoinSpendPrivateKeyP *coin_privs,
const struct TALER_DenominationSignature *sigs,
json_t *full_response);
/**
* @brief A /refresh/reveal Handle
*/
struct TALER_EXCHANGE_RefreshRevealHandle;
/**
* Submit a /refresh/reval 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
* 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 noreveal_index response from the exchange to the
* #TALER_EXCHANGE_refresh_melt() invocation
* @param reveal_cb the callback to call with the final result of the
* refresh operation
* @param reveal_cb_cls closure for the above callback
* @return a handle for this request; NULL if the argument was invalid.
* In this case, neither callback will be called.
*/
struct TALER_EXCHANGE_RefreshRevealHandle *
TALER_EXCHANGE_refresh_reveal (struct TALER_EXCHANGE_Handle *exchange,
size_t refresh_data_length,
const char *refresh_data,
uint16_t noreveal_index,
TALER_EXCHANGE_RefreshRevealCallback reveal_cb,
void *reveal_cb_cls);
/**
* Cancel a refresh reveal request. This function cannot be used
* on a request handle if the callback was already invoked.
*
* @param rrh the refresh reval handle
*/
void
TALER_EXCHANGE_refresh_reveal_cancel (struct TALER_EXCHANGE_RefreshRevealHandle *rrh);
/* ********************* /refresh/link ***************************** */
/**
* @brief A /refresh/link Handle
*/
struct TALER_EXCHANGE_RefreshLinkHandle;
/**
* Callbacks of this type are used to return the final result of
* submitting a /refresh/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 http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @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 full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_RefreshLinkCallback) (void *cls,
unsigned int http_status,
unsigned int num_coins,
const struct TALER_CoinSpendPrivateKeyP *coin_privs,
const struct TALER_DenominationSignature *sigs,
const struct TALER_DenominationPublicKey *pubs,
json_t *full_response);
/**
* Submit a link request to the exchange and get the exchange's response.
*
* 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 coin_priv private key to request link data for
* @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_RefreshLinkHandle *
TALER_EXCHANGE_refresh_link (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_CoinSpendPrivateKeyP *coin_priv,
TALER_EXCHANGE_RefreshLinkCallback link_cb,
void *link_cb_cls);
/**
* Cancel a refresh link request. This function cannot be used
* on a request handle if the callback was already invoked.
*
* @param rlh the refresh link handle
*/
void
TALER_EXCHANGE_refresh_link_cancel (struct TALER_EXCHANGE_RefreshLinkHandle *rlh);
/* ********************* /admin/add/incoming *********************** */
/**
* @brief A /admin/add/incoming Handle
*/
struct TALER_EXCHANGE_AdminAddIncomingHandle;
/**
* Callbacks of this type are used to serve the result of submitting
* information about an incoming transaction to a exchange.
*
* @param cls closure
* @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request
* 0 if the exchange's reply is bogus (fails to follow the protocol)
* @param full_response full response from the exchange (for logging, in case of errors)
*/
typedef void
(*TALER_EXCHANGE_AdminAddIncomingResultCallback) (void *cls,
unsigned int http_status,
json_t *full_response);
/**
* Notify the exchange that we have received an incoming transaction
* which fills a reserve. Note that this API is an administrative
* API and thus not accessible to typical exchange clients, but only
* to the operators of the exchange.
*
* @param exchange the exchange handle; the exchange must be ready to operate
* @param reserve_pub public key of the reserve
* @param amount amount that was deposited
* @param execution_date when did we receive the amount
* @param wire wire details
* @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 NULL
* if the inputs are invalid (i.e. invalid amount).
* In this case, the callback is not called.
*/
struct TALER_EXCHANGE_AdminAddIncomingHandle *
TALER_EXCHANGE_admin_add_incoming (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_ReservePublicKeyP *reserve_pub,
const struct TALER_Amount *amount,
struct GNUNET_TIME_Absolute execution_date,
const json_t *wire,
TALER_EXCHANGE_AdminAddIncomingResultCallback res_cb,
void *res_cb_cls);
/**
* Cancel an add incoming. This function cannot be used on a request
* handle if a response is already served for it.
*
* @param aai the admin add incoming request handle
*/
void
TALER_EXCHANGE_admin_add_incoming_cancel (struct TALER_EXCHANGE_AdminAddIncomingHandle *aai);
/* ********************* /wire/deposits *********************** */
/**
* @brief A /wire/deposits Handle
*/
struct TALER_EXCHANGE_WireDepositsHandle;
/**
* Details for one of the /deposit operations that the
* exchange combined into a single wire transfer.
*/
struct TALER_WireDepositDetails
{
/**
* Hash of the contract.
*/
struct GNUNET_HashCode h_contract;
/**
* Which coin was deposited?
*/
struct TALER_CoinSpendPublicKeyP coin_pub;
/**
* Value of the deposit (including fee).
*/
struct TALER_Amount coin_value;
/**
* Fee charged by the exchange for the deposit.
*/
struct TALER_Amount coin_fee;
/**
* Merchant's transaction identifier.
*/
uint64_t transaction_id;
};
/**
* Function called with detailed wire transfer data, including all
* of the coin transactions that were combined into the wire transfer.
*
* @param cls closure
* @param http_status HTTP status code we got, 0 on exchange protocol violation
* @param json original json reply (may include signatures, those have then been
* validated already)
* @param wtid extracted wire transfer identifier, or NULL if the exchange could
* not provide any (set only if @a http_status is #MHD_HTTP_OK)
* @param total_amount total amount of the wire transfer, or NULL if the exchange could
* not provide any @a wtid (set only if @a http_status is #MHD_HTTP_OK)
* @param details_length length of the @a details array
* @param details array with details about the combined transactions
*/
typedef void
(*TALER_EXCHANGE_WireDepositsCallback)(void *cls,
unsigned int http_status,
json_t *json,
const struct GNUNET_HashCode *h_wire,
const struct TALER_Amount *total_amount,
unsigned int details_length,
const struct TALER_WireDepositDetails *details);
/**
* Query the exchange about which transactions were combined
* to create a wire transfer.
*
* @param exchange exchange to query
* @param wtid raw wire transfer identifier to get information about
* @param cb callback to call
* @param cb_cls closure for @a cb
* @return handle to cancel operation
*/
struct TALER_EXCHANGE_WireDepositsHandle *
TALER_EXCHANGE_wire_deposits (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_WireTransferIdentifierRawP *wtid,
TALER_EXCHANGE_WireDepositsCallback cb,
void *cb_cls);
/**
* Cancel wire deposits request. This function cannot be used on a request
* handle if a response is already served for it.
*
* @param wdh the wire deposits request handle
*/
void
TALER_EXCHANGE_wire_deposits_cancel (struct TALER_EXCHANGE_WireDepositsHandle *wdh);
/* ********************* /deposit/wtid *********************** */
/**
* @brief A /deposit/wtid Handle
*/
struct TALER_EXCHANGE_DepositWtidHandle;
/**
* Function called with detailed wire transfer data.
*
* @param cls closure
* @param http_status HTTP status code we got, 0 on exchange protocol violation
* @param json original json reply (may include signatures, those have then been
* validated already)
* @param wtid wire transfer identifier used by the exchange, NULL if exchange did not
* yet execute the transaction
* @param execution_time actual or planned execution time for the wire transfer
* @param coin_contribution contribution to the @a total_amount of the deposited coin (may be NULL)
*/
typedef void
(*TALER_EXCHANGE_DepositWtidCallback)(void *cls,
unsigned int http_status,
json_t *json,
const struct TALER_WireTransferIdentifierRawP *wtid,
struct GNUNET_TIME_Absolute execution_time,
const struct TALER_Amount *coin_contribution);
/**
* Obtain the wire transfer details for a given deposit.
*
* @param exchange the exchange to query
* @param merchant_priv the merchant's private key
* @param h_wire hash of merchant's wire transfer details
* @param h_contract hash of the contract
* @param coin_pub public key of the coin
* @param transaction_id transaction identifier
* @param cb function to call with the result
* @param cb_cls closure for @a cb
* @return handle to abort request
*/
struct TALER_EXCHANGE_DepositWtidHandle *
TALER_EXCHANGE_deposit_wtid (struct TALER_EXCHANGE_Handle *exchange,
const struct TALER_MerchantPrivateKeyP *merchant_priv,
const struct GNUNET_HashCode *h_wire,
const struct GNUNET_HashCode *h_contract,
const struct TALER_CoinSpendPublicKeyP *coin_pub,
uint64_t transaction_id,
TALER_EXCHANGE_DepositWtidCallback cb,
void *cb_cls);
/**
* Cancel deposit wtid request. This function cannot be used on a request
* handle if a response is already served for it.
*
* @param dwh the wire deposits request handle
*/
void
TALER_EXCHANGE_deposit_wtid_cancel (struct TALER_EXCHANGE_DepositWtidHandle *dwh);
#endif /* _TALER_EXCHANGE_SERVICE_H */
Reference in New Issue View Git Blame Copy Permalink