From b5cba3251053c22bf1df46282f1dd0a4c46f6a38 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 1 Mar 2016 15:35:04 +0100 Subject: renaming mint->exchange --- src/include/Makefile.am | 6 +- src/include/taler_crypto_lib.h | 24 +- src/include/taler_exchange_service.h | 1220 ++++++++++++++++++++++++++++ src/include/taler_exchangedb_lib.h | 291 +++++++ src/include/taler_exchangedb_plugin.h | 1431 +++++++++++++++++++++++++++++++++ src/include/taler_mint_service.h | 1220 ---------------------------- src/include/taler_mintdb_lib.h | 291 ------- src/include/taler_mintdb_plugin.h | 1431 --------------------------------- src/include/taler_signatures.h | 200 ++--- 9 files changed, 3057 insertions(+), 3057 deletions(-) create mode 100644 src/include/taler_exchange_service.h create mode 100644 src/include/taler_exchangedb_lib.h create mode 100644 src/include/taler_exchangedb_plugin.h delete mode 100644 src/include/taler_mint_service.h delete mode 100644 src/include/taler_mintdb_lib.h delete mode 100644 src/include/taler_mintdb_plugin.h (limited to 'src/include') diff --git a/src/include/Makefile.am b/src/include/Makefile.am index 4d7ae3cb2..6f7f53acb 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am @@ -16,9 +16,9 @@ talerinclude_HEADERS = \ taler_crypto_lib.h \ taler_json_lib.h \ taler_util.h \ - taler_mint_service.h \ - taler_mintdb_lib.h \ - taler_mintdb_plugin.h \ + taler_exchange_service.h \ + taler_exchangedb_lib.h \ + taler_exchangedb_plugin.h \ taler_pq_lib.h \ taler_signatures.h \ taler_wire_lib.h \ diff --git a/src/include/taler_crypto_lib.h b/src/include/taler_crypto_lib.h index 6056270fa..e948fa28a 100644 --- a/src/include/taler_crypto_lib.h +++ b/src/include/taler_crypto_lib.h @@ -140,23 +140,23 @@ struct TALER_TransferPrivateKeyP /** - * @brief Type of online public keys used by the mint to sign + * @brief Type of online public keys used by the exchange to sign * messages. */ -struct TALER_MintPublicKeyP +struct TALER_ExchangePublicKeyP { /** - * Taler uses EdDSA for online mint message signing. + * Taler uses EdDSA for online exchange message signing. */ struct GNUNET_CRYPTO_EddsaPublicKey eddsa_pub; }; /** - * @brief Type of online public keys used by the mint to + * @brief Type of online public keys used by the exchange to * sign messages. */ -struct TALER_MintPrivateKeyP +struct TALER_ExchangePrivateKeyP { /** * Taler uses EdDSA for online signatures sessions. @@ -166,9 +166,9 @@ struct TALER_MintPrivateKeyP /** - * @brief Type of signatures used by the mint to sign messages online. + * @brief Type of signatures used by the exchange to sign messages online. */ -struct TALER_MintSignatureP +struct TALER_ExchangeSignatureP { /** * Taler uses EdDSA for online signatures sessions. @@ -178,7 +178,7 @@ struct TALER_MintSignatureP /** - * @brief Type of the offline master public key used by the mint. + * @brief Type of the offline master public key used by the exchange. */ struct TALER_MasterPublicKeyP { @@ -214,7 +214,7 @@ struct TALER_AuditorSignatureP /** - * @brief Type of the offline master public keys used by the mint. + * @brief Type of the offline master public keys used by the exchange. */ struct TALER_MasterPrivateKeyP { @@ -226,7 +226,7 @@ struct TALER_MasterPrivateKeyP /** - * @brief Type of signatures by the offline master public key used by the mint. + * @brief Type of signatures by the offline master public key used by the exchange. */ struct TALER_MasterSignatureP { @@ -464,8 +464,8 @@ struct TALER_WireTransferIdentifierRawP /** * Binary information encoded in Crockford's Base32 in wire transfer * subjects of transfers from Taler to a merchant. The actual value - * is chosen by the mint and has no particular semantics, other than - * being unique so that the mint can lookup details about the wire + * is chosen by the exchange and has no particular semantics, other than + * being unique so that the exchange can lookup details about the wire * transfer when needed. */ struct TALER_WireTransferIdentifierP diff --git a/src/include/taler_exchange_service.h b/src/include/taler_exchange_service.h new file mode 100644 index 000000000..566dec6f8 --- /dev/null +++ b/src/include/taler_exchange_service.h @@ -0,0 +1,1220 @@ +/* + 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 +*/ +/** + * @file include/taler_exchange_service.h + * @brief C interface of libtalerexchange, a C library to use exchange's HTTP API + * @author Sree Harsha Totakura + * @author Christian Grothoff + */ +#ifndef _TALER_EXCHANGE_SERVICE_H +#define _TALER_EXCHANGE_SERVICE_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 */ diff --git a/src/include/taler_exchangedb_lib.h b/src/include/taler_exchangedb_lib.h new file mode 100644 index 000000000..347ad0650 --- /dev/null +++ b/src/include/taler_exchangedb_lib.h @@ -0,0 +1,291 @@ +/* + 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 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 General Public License for more details. + + You should have received a copy of the GNU General Public License along with + TALER; see the file COPYING. If not, If not, see +*/ +/** + * @file include/taler_exchangedb_lib.h + * @brief IO operations for the exchange's private keys + * @author Florian Dold + * @author Benedikt Mueller + * @author Christian Grothoff + */ +#ifndef TALER_EXCHANGEDB_LIB_H +#define TALER_EXCHANGEDB_LIB_H + +#include "taler_signatures.h" + +/** + * Subdirectroy under the exchange's base directory which contains + * the exchange's signing keys. + */ +#define TALER_EXCHANGEDB_DIR_SIGNING_KEYS "signkeys" + +/** + * Subdirectory under the exchange's base directory which contains + * the exchange's denomination keys. + */ +#define TALER_EXCHANGEDB_DIR_DENOMINATION_KEYS "denomkeys" + +/** + * Subdirectory under the exchange's base directory which contains + * the exchange's auditing information. + */ +#define TALER_EXCHANGEDB_DIR_AUDITORS "auditors" + + +GNUNET_NETWORK_STRUCT_BEGIN + +/** + * @brief On disk format used for a exchange signing key. Signing keys are used + * by the exchange to affirm its messages, but not to create coins. + * Includes the private key followed by the public information about + * the signing key. + */ +struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP +{ + /** + * Private key part of the exchange's signing key. + */ + struct TALER_ExchangePrivateKeyP signkey_priv; + + /** + * Public information about a exchange signing key. + */ + struct TALER_ExchangeSigningKeyValidityPS issue; +}; + + +/** + * Information about a denomination key. + */ +struct TALER_EXCHANGEDB_DenominationKeyInformationP +{ + + /** + * Signature over this struct to affirm the validity of the key. + */ + struct TALER_MasterSignatureP signature; + + /** + * Signed properties of the denomination key. + */ + struct TALER_DenominationKeyValidityPS properties; +}; + + +GNUNET_NETWORK_STRUCT_END + + +/** + * @brief All information about a denomination key (which is used to + * sign coins into existence). + */ +struct TALER_EXCHANGEDB_DenominationKeyIssueInformation +{ + /** + * The private key of the denomination. Will be NULL if the private + * key is not available (this is the case after the key has expired + * for signing coins, but is still valid for depositing coins). + */ + struct TALER_DenominationPrivateKey denom_priv; + + /** + * Decoded denomination public key (the hash of it is in + * @e issue, but we sometimes need the full public key as well). + */ + struct TALER_DenominationPublicKey denom_pub; + + /** + * Signed public information about a denomination key. + */ + struct TALER_EXCHANGEDB_DenominationKeyInformationP issue; +}; + + +/** + * @brief Iterator over signing keys. + * + * @param cls closure + * @param filename name of the file the key came from + * @param ski the sign key + * @return #GNUNET_OK to continue to iterate, + * #GNUNET_NO to stop iteration with no error, + * #GNUNET_SYSERR to abort iteration with error! + */ +typedef int +(*TALER_EXCHANGEDB_SigningKeyIterator)(void *cls, + const char *filename, + const struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP *ski); + + +/** + * Call @a it for each signing key found in the @a exchange_base_dir. + * + * @param exchange_base_dir base directory for the exchange, + * the signing keys must be in the #TALER_EXCHANGEDB_DIR_SIGNING_KEYS + * subdirectory + * @param it function to call on each signing key + * @param it_cls closure for @a it + * @return number of files found (may not match + * number of keys given to @a it as malformed + * files are simply skipped), -1 on error + */ +int +TALER_EXCHANGEDB_signing_keys_iterate (const char *exchange_base_dir, + TALER_EXCHANGEDB_SigningKeyIterator it, + void *it_cls); + + + +/** + * @brief Iterator over denomination keys. + * + * @param cls closure + * @param dki the denomination key + * @param alias coin alias + * @return #GNUNET_OK to continue to iterate, + * #GNUNET_NO to stop iteration with no error, + * #GNUNET_SYSERR to abort iteration with error! + */ +typedef int +(*TALER_EXCHANGEDB_DenominationKeyIterator)(void *cls, + const char *alias, + const struct TALER_EXCHANGEDB_DenominationKeyIssueInformation *dki); + + +/** + * Call @a it for each denomination key found in the @a exchange_base_dir. + * + * @param exchange_base_dir base directory for the exchange, + * the signing keys must be in the #TALER_EXCHANGEDB_DIR_DENOMINATION_KEYS + * subdirectory + * @param it function to call on each denomination key found + * @param it_cls closure for @a it + * @return -1 on error, 0 if no files were found, otherwise + * a positive number (however, even with a positive + * number it is possible that @a it was never called + * as maybe none of the files were well-formed) + */ +int +TALER_EXCHANGEDB_denomination_keys_iterate (const char *exchange_base_dir, + TALER_EXCHANGEDB_DenominationKeyIterator it, + void *it_cls); + + +/** + * Exports a denomination key to the given file. + * + * @param filename the file where to write the denomination key + * @param dki the denomination key + * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure. + */ +int +TALER_EXCHANGEDB_denomination_key_write (const char *filename, + const struct TALER_EXCHANGEDB_DenominationKeyIssueInformation *dki); + + +/** + * Import a denomination key from the given file. + * + * @param filename the file to import the key from + * @param[out] dki set to the imported denomination key + * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure + */ +int +TALER_EXCHANGEDB_denomination_key_read (const char *filename, + struct TALER_EXCHANGEDB_DenominationKeyIssueInformation *dki); + + +/** + * @brief Iterator over auditor information. + * + * @param cls closure + * @param apub the auditor's public key + * @param mpub the exchange's public key (as expected by the auditor) + * @param dki_len length of @a asig and @a dki arrays + * @param asigs array of the auditor's signatures over the @a dks, of length @a dki_len + * @param dki array of denomination coin data signed by the auditor, of length @a dki_len + * @return #GNUNET_OK to continue to iterate, + * #GNUNET_NO to stop iteration with no error, + * #GNUNET_SYSERR to abort iteration with error! + */ +typedef int +(*TALER_EXCHANGEDB_AuditorIterator)(void *cls, + const struct TALER_AuditorPublicKeyP *apub, + const struct TALER_MasterPublicKeyP *mpub, + unsigned int dki_len, + const struct TALER_AuditorSignatureP *asigs, + const struct TALER_DenominationKeyValidityPS *dki); + + +/** + * Call @a it with information for each auditor found in the @a exchange_base_dir. + * + * @param exchange_base_dir base directory for the exchange, + * the signing keys must be in the #TALER_EXCHANGEDB_DIR_DENOMINATION_KEYS + * subdirectory + * @param it function to call with auditor information + * @param it_cls closure for @a it + * @return -1 on error, 0 if no files were found, otherwise + * a positive number (however, even with a positive + * number it is possible that @a it was never called + * as maybe none of the files were well-formed) + */ +int +TALER_EXCHANGEDB_auditor_iterate (const char *exchange_base_dir, + TALER_EXCHANGEDB_AuditorIterator it, + void *it_cls); + + +/** + * Write auditor information to the given file. + * + * @param filename the file where to write the auditor information to + * @param apub the auditor's public key + * @param asigs the auditor's signatures, array of length @a dki_len + * @param mpub the exchange's public key (as expected by the auditor) + * @param dki_len length of @a dki and @a asigs arrays + * @param dki array of denomination coin data signed by the auditor + * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure. + */ +int +TALER_EXCHANGEDB_auditor_write (const char *filename, + const struct TALER_AuditorPublicKeyP *apub, + const struct TALER_AuditorSignatureP *asigs, + const struct TALER_MasterPublicKeyP *mpub, + unsigned int dki_len, + const struct TALER_DenominationKeyValidityPS *dki); + + +/** + * Initialize the plugin. + * + * @param cfg configuration to use + * @return NULL on failure + */ +struct TALER_EXCHANGEDB_Plugin * +TALER_EXCHANGEDB_plugin_load (const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Shutdown the plugin. + * + * @param plugin plugin to unload + */ +void +TALER_EXCHANGEDB_plugin_unload (struct TALER_EXCHANGEDB_Plugin *plugin); + + + +#endif diff --git a/src/include/taler_exchangedb_plugin.h b/src/include/taler_exchangedb_plugin.h new file mode 100644 index 000000000..aecb050a7 --- /dev/null +++ b/src/include/taler_exchangedb_plugin.h @@ -0,0 +1,1431 @@ +/* + This file is part of TALER + Copyright (C) 2014, 2015, 2016 GNUnet e.V. + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU 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 General Public License for more details. + + You should have received a copy of the GNU General Public License along with + TALER; see the file COPYING. If not, If not, see +*/ +/** + * @file include/taler_exchangedb_plugin.h + * @brief Low-level (statement-level) database access for the exchange + * @author Florian Dold + * @author Christian Grothoff + */ +#ifndef TALER_EXCHANGEDB_PLUGIN_H +#define TALER_EXCHANGEDB_PLUGIN_H + +#include +#include "taler_exchangedb_lib.h" + + +/** + * @brief Information we keep on bank transfer(s) that established a reserve. + */ +struct TALER_EXCHANGEDB_BankTransfer +{ + + /** + * Public key of the reserve that was filled. + */ + struct TALER_ReservePublicKeyP reserve_pub; + + /** + * Amount that was transferred to the exchange. + */ + struct TALER_Amount amount; + + /** + * When did the exchange receive the incoming transaction? + * (This is the execution date of the exchange's database, + * the execution date of the bank should be in @e wire). + */ + struct GNUNET_TIME_Absolute execution_date; + + /** + * Detailed wire information about the transaction. + */ + json_t *wire; + +}; + + +/** + * @brief A summary of a Reserve + */ +struct TALER_EXCHANGEDB_Reserve +{ + /** + * The reserve's public key. This uniquely identifies the reserve + */ + struct TALER_ReservePublicKeyP pub; + + /** + * The balance amount existing in the reserve + */ + struct TALER_Amount balance; + + /** + * The expiration date of this reserve + */ + struct GNUNET_TIME_Absolute expiry; +}; + + +/** + * @brief Information we keep for a withdrawn coin to reproduce + * the /withdraw operation if needed, and to have proof + * that a reserve was drained by this amount. + */ +struct TALER_EXCHANGEDB_CollectableBlindcoin +{ + + /** + * Our signature over the (blinded) coin. + */ + struct TALER_DenominationSignature sig; + + /** + * Denomination key (which coin was generated). + */ + struct TALER_DenominationPublicKey denom_pub; + + /** + * Value of the coin being exchangeed (matching the denomination key) + * plus the transaction fee. We include this in what is being + * signed so that we can verify a reserve's remaining total balance + * without needing to access the respective denomination key + * information each time. + */ + struct TALER_Amount amount_with_fee; + + /** + * Withdrawl fee charged by the exchange. This must match the Exchange's + * denomination key's withdrawl fee. If the client puts in an + * invalid withdrawl fee (too high or too low) that does not match + * the Exchange's denomination key, the withdraw operation is invalid + * and will be rejected by the exchange. The @e amount_with_fee minus + * the @e withdraw_fee is must match the value of the generated + * coin. We include this in what is being signed so that we can + * verify a exchange's accounting without needing to access the + * respective denomination key information each time. + */ + struct TALER_Amount withdraw_fee; + + /** + * Public key of the reserve that was drained. + */ + struct TALER_ReservePublicKeyP reserve_pub; + + /** + * Hash over the blinded message, needed to verify + * the @e reserve_sig. + */ + struct GNUNET_HashCode h_coin_envelope; + + /** + * Signature confirming the withdrawl, matching @e reserve_pub, + * @e denom_pub and @e h_coin_envelope. + */ + struct TALER_ReserveSignatureP reserve_sig; +}; + + + +/** + * @brief Types of operations on a reserved. + */ +enum TALER_EXCHANGEDB_ReserveOperation +{ + /** + * Money was deposited into the reserve via a bank transfer. + */ + TALER_EXCHANGEDB_RO_BANK_TO_EXCHANGE = 0, + + /** + * A Coin was withdrawn from the reserve using /withdraw. + */ + TALER_EXCHANGEDB_RO_WITHDRAW_COIN = 1 +}; + + +/** + * @brief Reserve history as a linked list. Lists all of the transactions + * associated with this reserve (such as the bank transfers that + * established the reserve and all /withdraw operations we have done + * since). + */ +struct TALER_EXCHANGEDB_ReserveHistory +{ + + /** + * Next entry in the reserve history. + */ + struct TALER_EXCHANGEDB_ReserveHistory *next; + + /** + * Type of the event, determins @e details. + */ + enum TALER_EXCHANGEDB_ReserveOperation type; + + /** + * Details of the operation, depending on @e type. + */ + union + { + + /** + * Details about a bank transfer to the exchange. + */ + struct TALER_EXCHANGEDB_BankTransfer *bank; + + /** + * Details about a /withdraw operation. + */ + struct TALER_EXCHANGEDB_CollectableBlindcoin *withdraw; + + } details; + +}; + + +/** + * @brief Specification for a /deposit operation. The combination of + * the coin's public key, the merchant's public key and the + * transaction ID must be unique. While a coin can (theoretically) be + * deposited at the same merchant twice (with partial spending), the + * merchant must either use a different public key or a different + * transaction ID for the two transactions. The same coin must not + * be used twice at the same merchant for the same transaction + * (as determined by transaction ID). (Note: we might want to + * fix #3819 and include at least h_contract as well.) + */ +struct TALER_EXCHANGEDB_Deposit +{ + /** + * Information about the coin that is being deposited. + */ + struct TALER_CoinPublicInfo coin; + + /** + * ECDSA signature affirming that the customer intends + * this coin to be deposited at the merchant identified + * by @e h_wire in relation to the contract identified + * by @e h_contract. + */ + struct TALER_CoinSpendSignatureP csig; + + /** + * Public key of the merchant. Enables later identification + * of the merchant in case of a need to rollback transactions. + */ + struct TALER_MerchantPublicKeyP merchant_pub; + + /** + * Hash over the contract between merchant and customer + * (remains unknown to the Exchange). + */ + struct GNUNET_HashCode h_contract; + + /** + * Hash of the (canonical) representation of @e wire, used + * to check the signature on the request. Generated by + * the exchange from the detailed wire data provided by the + * merchant. + */ + struct GNUNET_HashCode h_wire; + + /** + * Detailed wire information for executing the transaction. + */ + json_t *wire; + + /** + * Merchant-generated transaction ID to detect duplicate + * transactions. + */ + uint64_t transaction_id; + + /** + * Time when this request was generated. Used, for example, to + * assess when (roughly) the income was achieved for tax purposes. + * Note that the Exchange will only check that the timestamp is not "too + * far" into the future (i.e. several days). The fact that the + * timestamp falls within the validity period of the coin's + * denomination key is irrelevant for the validity of the deposit + * request, as obviously the customer and merchant could conspire to + * set any timestamp. Also, the Exchange must accept very old deposit + * requests, as the merchant might have been unable to transmit the + * deposit request in a timely fashion (so back-dating is not + * prevented). + */ + struct GNUNET_TIME_Absolute timestamp; + + /** + * How much time does the merchant have to issue a refund request? + * Zero if refunds are not allowed. After this time, the coin + * cannot be refunded. + */ + struct GNUNET_TIME_Absolute refund_deadline; + + /** + * How much time does the merchant have to execute the wire transfer? + * This time is advisory for aggregating transactions, not a hard + * constraint (as the merchant can theoretically pick any time, + * including one in the past). + */ + struct GNUNET_TIME_Absolute wire_deadline; + + /** + * Fraction of the coin's remaining value to be deposited, including + * depositing fee (if any). The coin is identified by @e coin_pub. + */ + struct TALER_Amount amount_with_fee; + + /** + * Depositing fee. + */ + struct TALER_Amount deposit_fee; + +}; + + +/** + * @brief Global information for a refreshing session. Includes + * dimensions of the operation, security parameters and + * client signatures from "/refresh/melt" and "/refresh/commit". + */ +struct TALER_EXCHANGEDB_RefreshSession +{ + + /** + * Number of coins we are melting. + */ + uint16_t num_oldcoins; + + /** + * Number of new coins we are creating. + */ + uint16_t num_newcoins; + + /** + * Index (smaller #TALER_CNC_KAPPA) which the exchange has chosen to not + * have revealed during cut and choose. + */ + uint16_t noreveal_index; + +}; + + +/** + * @brief Specification for coin in a /refresh/melt operation. + */ +struct TALER_EXCHANGEDB_RefreshMelt +{ + /** + * Information about the coin that is being melted. + */ + struct TALER_CoinPublicInfo coin; + + /** + * Signature over the melting operation. + */ + struct TALER_CoinSpendSignatureP coin_sig; + + /** + * Hash of the refresh session this coin is melted into. + */ + struct GNUNET_HashCode session_hash; + + /** + * How much value is being melted? This amount includes the fees, + * so the final amount contributed to the melt is this value minus + * the fee for melting the coin. We include the fee in what is + * being signed so that we can verify a reserve's remaining total + * balance without needing to access the respective denomination key + * information each time. + */ + struct TALER_Amount amount_with_fee; + + /** + * Melting fee charged by the exchange. This must match the Exchange's + * denomination key's melting fee. If the client puts in an invalid + * melting fee (too high or too low) that does not match the Exchange's + * denomination key, the melting operation is invalid and will be + * rejected by the exchange. The @e amount_with_fee minus the @e + * melt_fee is the amount that will be credited to the melting + * session. + */ + struct TALER_Amount melt_fee; + +}; + + +/** + * @brief We have as many `struct TALER_EXCHANGEDB_RefreshCommitCoin` as there are new + * coins being created by the refresh (for each of the #TALER_CNC_KAPPA + * sets). These are the coins we ask the exchange to sign if the + * respective set is selected. + */ +struct TALER_EXCHANGEDB_RefreshCommitCoin +{ + + /** + * Encrypted data allowing those able to decrypt it to derive + * the private keys of the new coins created by the refresh. + */ + struct TALER_RefreshLinkEncrypted *refresh_link; + + /** + * Blinded message to be signed (in envelope), with @e coin_env_size bytes. + */ + char *coin_ev; + + /** + * Number of bytes in @e coin_ev. + */ + size_t coin_ev_size; + +}; + + +/** + * @brief Linked list of refresh information linked to a coin. + */ +struct TALER_EXCHANGEDB_LinkDataList +{ + /** + * Information is stored in a NULL-terminated linked list. + */ + struct TALER_EXCHANGEDB_LinkDataList *next; + + /** + * Link data, used to recover the private key of the coin + * by the owner of the old coin. + */ + struct TALER_RefreshLinkEncrypted *link_data_enc; + + /** + * Denomination public key, determines the value of the coin. + */ + struct TALER_DenominationPublicKey denom_pub; + + /** + * Signature over the blinded envelope. + */ + struct TALER_DenominationSignature ev_sig; +}; + + +/** + * @brief Enumeration to classify the different types of transactions + * that can be done with a coin. + */ +enum TALER_EXCHANGEDB_TransactionType +{ + /** + * /deposit operation. + */ + TALER_EXCHANGEDB_TT_DEPOSIT = 0, + + /** + * /refresh/melt operation. + */ + TALER_EXCHANGEDB_TT_REFRESH_MELT = 1 + +}; + + +/** + * @brief List of transactions we performed for a particular coin. + */ +struct TALER_EXCHANGEDB_TransactionList +{ + + /** + * Next pointer in the NULL-terminated linked list. + */ + struct TALER_EXCHANGEDB_TransactionList *next; + + /** + * Type of the transaction, determines what is stored in @e details. + */ + enum TALER_EXCHANGEDB_TransactionType type; + + /** + * Details about the transaction, depending on @e type. + */ + union + { + + /** + * Details if transaction was a /deposit operation. + */ + struct TALER_EXCHANGEDB_Deposit *deposit; + + /** + * Details if transaction was a /refresh/melt operation. + */ + struct TALER_EXCHANGEDB_RefreshMelt *melt; + + } details; + +}; + + +/** + * @brief All of the information from a /refresh/melt commitment. + */ +struct TALER_EXCHANGEDB_MeltCommitment +{ + + /** + * Number of coins we are melting. + */ + uint16_t num_oldcoins; + + /** + * Number of new coins we are creating. + */ + uint16_t num_newcoins; + + /** + * Array of @e num_oldcoins melt operation details. + */ + struct TALER_EXCHANGEDB_RefreshMelt *melts; + + /** + * Array of @e num_newcoins denomination keys + */ + struct TALER_DenominationPublicKey *denom_pubs; + + /** + * 2D-Array of #TALER_CNC_KAPPA and @e num_newcoins commitments. + */ + struct TALER_EXCHANGEDB_RefreshCommitCoin *commit_coins[TALER_CNC_KAPPA]; + + /** + * 2D-Array of #TALER_CNC_KAPPA and @e new_oldcoins links. + */ + struct TALER_RefreshCommitLinkP *commit_links[TALER_CNC_KAPPA]; +}; + + +/** + * @brief Handle for a database session (per-thread, for transactions). + */ +struct TALER_EXCHANGEDB_Session; + + +/** + * Function called with details about deposits that + * have been made, with the goal of executing the + * corresponding wire transaction. + * + * @param cls closure + * @param rowid unique ID for the deposit in our DB, used for marking + * it as 'tiny' or 'done' + * @param merchant_pub public key of the merchant + * @param coin_pub public key of the coin + * @param amount_with_fee amount that was deposited including fee + * @param deposit_fee amount the exchange gets to keep as transaction fees + * @param transaction_id unique transaction ID chosen by the merchant + * @param h_contract hash of the contract between merchant and customer + * @param wire_deadline by which the merchant adviced that he would like the + * wire transfer to be executed + * @param wire wire details for the merchant, NULL from iterate_matching_deposits() + * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop + */ +typedef int +(*TALER_EXCHANGEDB_DepositIterator)(void *cls, + unsigned long long rowid, + const struct TALER_MerchantPublicKeyP *merchant_pub, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + const struct TALER_Amount *amount_with_fee, + const struct TALER_Amount *deposit_fee, + uint64_t transaction_id, + const struct GNUNET_HashCode *h_contract, + struct GNUNET_TIME_Absolute wire_deadline, + const json_t *wire); + + +/** + * Function called with the session hashes and transfer secret + * information for a given coin. + * + * @param cls closure + * @param session_hash a session the coin was melted in + * @param transfer_pub public transfer key for the session + * @param shared_secret_enc set to shared secret for the session + */ +typedef void +(*TALER_EXCHANGEDB_TransferDataCallback)(void *cls, + const struct GNUNET_HashCode *session_hash, + const struct TALER_TransferPublicKeyP *transfer_pub, + const struct TALER_EncryptedLinkSecretP *shared_secret_enc); + + +/** + * Function called with the results of the lookup of the + * wire transfer identifier information. Only called if + * we are at least aware of the transaction existing. + * + * @param cls closure + * @param wtid wire transfer identifier, NULL + * if the transaction was not yet done + * @param coin_contribution how much did the coin we asked about + * contribute to the total transfer value? (deposit value including fee) + * @param coin_fee how much did the exchange charge for the deposit fee + * @param execution_time when was the transaction done, or + * when we expect it to be done (if @a wtid was NULL) + */ +typedef void +(*TALER_EXCHANGEDB_DepositWtidCallback)(void *cls, + const struct TALER_WireTransferIdentifierRawP *wtid, + const struct TALER_Amount *coin_contribution, + const struct TALER_Amount *coin_fee, + struct GNUNET_TIME_Absolute execution_time); + + +/** + * Function called with the results of the lookup of the + * transaction data associated with a wire transfer identifier. + * + * @param cls closure + * @param merchant_pub public key of the merchant (should be same for all callbacks with the same @e cls) + * @param h_wire hash of wire transfer details of the merchant (should be same for all callbacks with the same @e cls) + * @param h_contract which contract was this payment about + * @param transaction_id merchant's transaction ID for the payment + * @param coin_pub which public key was this payment about + * @param coin_value amount contributed by this coin in total (with fee) + * @param coin_fee applicable fee for this coin + */ +typedef void +(*TALER_EXCHANGEDB_WireTransferDataCallback)(void *cls, + const struct TALER_MerchantPublicKeyP *merchant_pub, + const struct GNUNET_HashCode *h_wire, + const struct GNUNET_HashCode *h_contract, + uint64_t transaction_id, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + const struct TALER_Amount *coin_value, + const struct TALER_Amount *coin_fee); + + +/** + * Callback with data about a prepared transaction. + * + * @param cls closure + * @param rowid row identifier used to mark prepared transaction as done + * @param buf transaction data that was persisted, NULL on error + * @param buf_size number of bytes in @a buf, 0 on error + */ +typedef void +(*TALER_EXCHANGEDB_WirePreparationCallback) (void *cls, + unsigned long long rowid, + const char *buf, + size_t buf_size); + + +/** + * @brief The plugin API, returned from the plugin's "init" function. + * The argument given to "init" is simply a configuration handle. + */ +struct TALER_EXCHANGEDB_Plugin +{ + + /** + * Closure for all callbacks. + */ + void *cls; + + /** + * Name of the library which generated this plugin. Set by the + * plugin loader. + */ + char *library_name; + + /** + * Get the thread-local database-handle. + * Connect to the db if the connection does not exist yet. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param temporary #GNUNET_YES to use a temporary schema; #GNUNET_NO to use the + * database default one + * @param the database connection, or NULL on error + */ + struct TALER_EXCHANGEDB_Session * + (*get_session) (void *cls, + int temporary); + + + /** + * Drop the temporary taler schema. This is only useful for testcases. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure + */ + int + (*drop_temporary) (void *cls, + struct TALER_EXCHANGEDB_Session *db); + + + /** + * Create the necessary tables if they are not present + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param temporary should we use a temporary schema + * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure + */ + int + (*create_tables) (void *cls, + int temporary); + + + /** + * Start a transaction. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to use + * @return #GNUNET_OK on success + */ + int + (*start) (void *cls, + struct TALER_EXCHANGEDB_Session *session); + + + /** + * Commit a transaction. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to use + * @return #GNUNET_OK on success, #GNUNET_NO if the transaction + * can be retried, #GNUNET_SYSERR on hard failures + */ + int + (*commit) (void *cls, + struct TALER_EXCHANGEDB_Session *session); + + + /** + * Abort/rollback a transaction. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to use + */ + void + (*rollback) (void *cls, + struct TALER_EXCHANGEDB_Session *session); + + + /** + * Insert information about a denomination key and in particular + * the properties (value, fees, expiration times) the coins signed + * with this key have. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to use + * @param denom_pub the public key used for signing coins of this denomination + * @param issue issuing information with value, fees and other info about the coin + * @return #GNUNET_OK on success; #GNUNET_SYSERR on failure + */ + int + (*insert_denomination_info) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_DenominationPublicKey *denom_pub, + const struct TALER_EXCHANGEDB_DenominationKeyInformationP *issue); + + + /** + * Fetch information about a denomination key. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to use + * @param denom_pub the public key used for signing coins of this denomination + * @param[out] issue set to issue information with value, fees and other info about the coin, can be NULL + * @return #GNUNET_OK on success; #GNUNET_NO if no record was found, #GNUNET_SYSERR on failure + */ + int + (*get_denomination_info) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_DenominationPublicKey *denom_pub, + struct TALER_EXCHANGEDB_DenominationKeyInformationP *issue); + + + /** + * Get the summary of a reserve. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param db the database connection handle + * @param[in,out] reserve the reserve data. The public key of the reserve should be set + * in this structure; it is used to query the database. The balance + * and expiration are then filled accordingly. + * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure + */ + int + (*reserve_get) (void *cls, + struct TALER_EXCHANGEDB_Session *db, + struct TALER_EXCHANGEDB_Reserve *reserve); + + + /** + * Insert a incoming transaction into reserves. New reserves are + * also created through this function. Note that this API call + * starts (and stops) its own transaction scope (so the application + * must not do so). + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param db the database connection handle + * @param reserve_pub public key of the reserve + * @param balance the amount that has to be added to the reserve + * @param execution_time when was the amount added + * @param details bank transaction details justifying the increment, + * must be unique for each incoming transaction + * @return #GNUNET_OK upon success; #GNUNET_NO if the given + * @a details are already known for this @a reserve_pub, + * #GNUNET_SYSERR upon failures (DB error, incompatible currency) + */ + int + (*reserves_in_insert) (void *cls, + struct TALER_EXCHANGEDB_Session *db, + const struct TALER_ReservePublicKeyP *reserve_pub, + const struct TALER_Amount *balance, + struct GNUNET_TIME_Absolute execution_time, + const json_t *details); + + + /** + * Locate the response for a /withdraw request under the + * key of the hash of the blinded message. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection to use + * @param h_blind hash of the blinded coin to be signed (will match + * `h_coin_envelope` in the @a collectable to be returned) + * @param collectable corresponding collectable coin (blind signature) + * if a coin is found + * @return #GNUNET_SYSERR on internal error + * #GNUNET_NO if the collectable was not found + * #GNUNET_YES on success + */ + int + (*get_withdraw_info) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *h_blind, + struct TALER_EXCHANGEDB_CollectableBlindcoin *collectable); + + + /** + * Store collectable bit coin under the corresponding + * hash of the blinded message. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection to use + * @param collectable corresponding collectable coin (blind signature) + * if a coin is found + * @return #GNUNET_SYSERR on internal error + * #GNUNET_NO if the collectable was not found + * #GNUNET_YES on success + */ + int + (*insert_withdraw_info) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_EXCHANGEDB_CollectableBlindcoin *collectable); + + + /** + * Get all of the transaction history associated with the specified + * reserve. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to use + * @param reserve_pub public key of the reserve + * @return known transaction history (NULL if reserve is unknown) + */ + struct TALER_EXCHANGEDB_ReserveHistory * + (*get_reserve_history) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_ReservePublicKeyP *reserve_pub); + + + /** + * Free memory associated with the given reserve history. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param rh history to free. + */ + void + (*free_reserve_history) (void *cls, + struct TALER_EXCHANGEDB_ReserveHistory *rh); + + + /** + * Check if we have the specified deposit already in the database. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param deposit deposit to search for + * @return #GNUNET_YES if we know this operation, + * #GNUNET_NO if this exact deposit is unknown to us, + * #GNUNET_SYSERR on DB error + */ + int + (*have_deposit) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_EXCHANGEDB_Deposit *deposit); + + + /** + * Insert information about deposited coin into the database. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to the database + * @param deposit deposit information to store + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ + int + (*insert_deposit) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_EXCHANGEDB_Deposit *deposit); + + + /** + * Mark a deposit as tiny, thereby declaring that it cannot be + * executed by itself and should no longer be returned by + * @e iterate_ready_deposits() + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to the database + * @param deposit_rowid identifies the deposit row to modify + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ + int + (*mark_deposit_tiny) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + unsigned long long rowid); + + + /** + * Mark a deposit as done, thereby declaring that it cannot be + * executed at all anymore, and should no longer be returned by + * @e iterate_ready_deposits() or @e iterate_matching_deposits(). + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to the database + * @param deposit_rowid identifies the deposit row to modify + * @return #GNUNET_OK on success, #GNUNET_SYSERR on error + */ + int + (*mark_deposit_done) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + unsigned long long rowid); + + + /** + * Obtain information about deposits that are ready to be executed. + * Such deposits must not be marked as "tiny" or "done", and the + * execution time must be in the past. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to the database + * @param deposit_cb function to call for ONE such deposit + * @param deposit_cb_cls closure for @a deposit_cb + * @return number of rows processed, 0 if none exist, + * #GNUNET_SYSERR on error + */ + int + (*get_ready_deposit) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + TALER_EXCHANGEDB_DepositIterator deposit_cb, + void *deposit_cb_cls); + + + /** + * Obtain information about other pending deposits for the same + * destination. Those deposits must not already be "done". + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session connection to the database + * @param h_wire destination of the wire transfer + * @param merchant_pub public key of the merchant + * @param deposit_cb function to call for each deposit + * @param deposit_cb_cls closure for @a deposit_cb + * @param limit maximum number of matching deposits to return + * @return number of rows processed, 0 if none exist, + * #GNUNET_SYSERR on error + */ + int + (*iterate_matching_deposits) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *h_wire, + const struct TALER_MerchantPublicKeyP *merchant_pub, + TALER_EXCHANGEDB_DepositIterator deposit_cb, + void *deposit_cb_cls, + uint32_t limit); + + + /** + * Lookup refresh session data under the given @a session_hash. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database handle to use + * @param session_hash hash over the melt to use for the lookup + * @param[out] refresh_session where to store the result + * @return #GNUNET_YES on success, + * #GNUNET_NO if not found, + * #GNUNET_SYSERR on DB failure + */ + int + (*get_refresh_session) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + struct TALER_EXCHANGEDB_RefreshSession *refresh_session); + + + /** + * Store new refresh session data under the given @a session_hash. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database handle to use + * @param session_hash hash over the melt to use to locate the session + * @param refresh_session session data to store + * @return #GNUNET_YES on success, + * #GNUNET_SYSERR on DB failure + */ + int + (*create_refresh_session) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + const struct TALER_EXCHANGEDB_RefreshSession *refresh_session); + + + /** + * Store the given /refresh/melt request in the database. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param oldcoin_index index of the coin to store + * @param melt coin melt operation details to store; includes + * the session hash of the melt + * @return #GNUNET_OK on success + * #GNUNET_SYSERR on internal error + */ + int + (*insert_refresh_melt) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + uint16_t oldcoin_index, + const struct TALER_EXCHANGEDB_RefreshMelt *melt); + + + /** + * Get information about melted coin details from the database. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param session_hash hash to identify refresh session + * @param oldcoin_index index of the coin to retrieve + * @param melt melt data to fill in, can be NULL + * @return #GNUNET_OK on success + * #GNUNET_SYSERR on internal error + */ + int + (*get_refresh_melt) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t oldcoin_index, + struct TALER_EXCHANGEDB_RefreshMelt *melt); + + + /** + * Store in the database which coin(s) we want to create + * in a given refresh operation. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param session_hash hash to identify refresh session + * @param num_newcoins number of coins to generate, size of the @a denom_pubs array + * @param denom_pubs array denominations of the coins to create + * @return #GNUNET_OK on success + * #GNUNET_SYSERR on internal error + */ + int + (*insert_refresh_order) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t num_newcoins, + const struct TALER_DenominationPublicKey *denom_pubs); + + + /** + * Lookup in the database for the @a num_newcoins coins that we want to + * create in the given refresh operation. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param session_hash hash to identify refresh session + * @param num_newcoins size of the @a denom_pubs array + * @param[out] denom_pubs where to write @a num_newcoins denomination keys + * @return #GNUNET_OK on success + * #GNUNET_SYSERR on internal error + */ + int + (*get_refresh_order) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t num_newcoins, + struct TALER_DenominationPublicKey *denom_pubs); + + + /** + * Store information about the commitments of the given index @a i + * for the given refresh session in the database. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection to use + * @param session_hash hash to identify refresh session + * @param cnc_index cut and choose index (1st dimension), relating to #TALER_CNC_KAPPA + * @param num_newcoins coin index size of the @a commit_coins array + * @param commit_coin array of coin commitments to store + * @return #GNUNET_OK on success + * #GNUNET_SYSERR on error + */ + int + (*insert_refresh_commit_coins) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t cnc_index, + uint16_t num_newcoins, + const struct TALER_EXCHANGEDB_RefreshCommitCoin *commit_coins); + + + /** + * Obtain information about the commitment of the + * given coin of the given refresh session from the database. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection to use + * @param session_hash hash to identify refresh session + * @param cnc_index cut and choose set index (1st dimension) + * @param num_coins size of the @a commit_coins array + * @param[out] commit_coins array of coin commitments to return + * @return #GNUNET_OK on success + * #GNUNET_NO if not found + * #GNUNET_SYSERR on error + */ + int + (*get_refresh_commit_coins) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t cnc_index, + uint16_t num_coins, + struct TALER_EXCHANGEDB_RefreshCommitCoin *commit_coins); + + + /** + * Store the commitment to the given (encrypted) refresh link data + * for the given refresh session. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection to use + * @param session_hash hash to identify refresh session + * @param cnc_index cut and choose index (1st dimension), relating to #TALER_CNC_KAPPA + * @param num_links size of the @a commit_link array + * @param commit_links array of link information to store + * @return #GNUNET_SYSERR on internal error, #GNUNET_OK on success + */ + int + (*insert_refresh_commit_links) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t cnc_index, + uint16_t num_links, + const struct TALER_RefreshCommitLinkP *commit_links); + + /** + * Obtain the commited (encrypted) refresh link data + * for the given refresh session. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection to use + * @param session_hash hash to identify refresh session + * @param cnc_index cut and choose index (1st dimension) + * @param num_links size of the @a links array to return + * @param[out] links array link information to return + * @return #GNUNET_SYSERR on internal error, + * #GNUNET_NO if commitment was not found + * #GNUNET_OK on success + */ + int + (*get_refresh_commit_links) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t cnc_index, + uint16_t num_links, + struct TALER_RefreshCommitLinkP *links); + + + /** + * Get all of the information from the given melt commit operation. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection to use + * @param session_hash hash to identify refresh session + * @return NULL if the @a session_hash does not correspond to any known melt + * operation + */ + struct TALER_EXCHANGEDB_MeltCommitment * + (*get_melt_commitment) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash); + + + /** + * Free information about a melt commitment. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param mc melt commitment data to free + */ + void + (*free_melt_commitment) (void *cls, + struct TALER_EXCHANGEDB_MeltCommitment *mc); + + + /** + * Insert signature of a new coin generated during refresh into + * the database indexed by the refresh session and the index + * of the coin. This data is later used should an old coin + * be used to try to obtain the private keys during "/refresh/link". + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param session_hash hash to identify refresh session + * @param newcoin_index coin index + * @param ev_sig coin signature + * @return #GNUNET_OK on success + */ + int + (*insert_refresh_out) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t newcoin_index, + const struct TALER_DenominationSignature *ev_sig); + + + /** + * Obtain the link data of a coin, that is the encrypted link + * information, the denomination keys and the signatures. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param session_hash session to get linkage data for + * @return all known link data for the session + */ + struct TALER_EXCHANGEDB_LinkDataList * + (*get_link_data_list) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *session_hash); + + + /** + * Free memory of the link data list. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param ldl link data list to release + */ + void + (*free_link_data_list) (void *cls, + struct TALER_EXCHANGEDB_LinkDataList *ldl); + + + /** + * Obtain shared secret and transfer public key from the public key of + * the coin. This information and the link information returned by + * @e get_link_data_list() enable the owner of an old coin to determine + * the private keys of the new coins after the melt. + * + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param coin_pub public key of the coin + * @param tdc function to call for each session the coin was melted into + * @param tdc_cls closure for @a tdc + * @return #GNUNET_OK on success, + * #GNUNET_NO on failure (not found) + * #GNUNET_SYSERR on internal failure (database issue) + */ + int + (*get_transfer) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + TALER_EXCHANGEDB_TransferDataCallback tdc, + void *tdc_cls); + + + /** + * Compile a list of all (historic) transactions performed + * with the given coin (/refresh/melt and /deposit operations). + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param coin_pub coin to investigate + * @return list of transactions, NULL if coin is fresh + */ + struct TALER_EXCHANGEDB_TransactionList * + (*get_coin_transactions) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_CoinSpendPublicKeyP *coin_pub); + + + /** + * Free linked list of transactions. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param list list to free + */ + void + (*free_coin_transaction_list) (void *cls, + struct TALER_EXCHANGEDB_TransactionList *list); + + + /** + * Lookup the list of Taler transactions that was aggregated + * into a wire transfer by the respective @a raw_wtid. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param session database connection + * @param wtid the raw wire transfer identifier we used + * @param cb function to call on each transaction found + * @param cb_cls closure for @a cb + * @return #GNUNET_OK on success, #GNUNET_SYSERR on database errors, + * #GNUNET_NO if we found no results + */ + int + (*lookup_wire_transfer) (void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_WireTransferIdentifierRawP *wtid, + TALER_EXCHANGEDB_WireTransferDataCallback cb, + void *cb_cls); + + + /** + * Try to find the wire transfer details for a deposit operation. + * If we did not execute the deposit yet, return when it is supposed + * to be executed. + * + * @param cls closure + * @param session database connection + * @param h_contract hash of the contract + * @param h_wire hash of merchant wire details + * @param coin_pub public key of deposited coin + * @param merchant_pub merchant public key + * @param transaction_id transaction identifier + * @param cb function to call with the result + * @param cb_cls closure to pass to @a cb + * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors, + * #GNUNET_NO if nothing was found + */ + int + (*wire_lookup_deposit_wtid)(void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct GNUNET_HashCode *h_contract, + const struct GNUNET_HashCode *h_wire, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + const struct TALER_MerchantPublicKeyP *merchant_pub, + uint64_t transaction_id, + TALER_EXCHANGEDB_DepositWtidCallback cb, + void *cb_cls); + + + /** + * Function called to insert aggregation information into the DB. + * + * @param cls closure + * @param session database connection + * @param wtid the raw wire transfer identifier we used + * @param merchant_pub public key of the merchant (should be same for all callbacks with the same @e cls) + * @param h_wire hash of wire transfer details of the merchant (should be same for all callbacks with the same @e cls) + * @param h_contract which contract was this payment about + * @param transaction_id merchant's transaction ID for the payment + * @param execution_time when did we execute the transaction + * @param coin_pub which public key was this payment about + * @param coin_value amount contributed by this coin in total + * @param coin_fee deposit fee charged by exchange for this coin + * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors + */ + int + (*insert_aggregation_tracking)(void *cls, + struct TALER_EXCHANGEDB_Session *session, + const struct TALER_WireTransferIdentifierRawP *wtid, + const struct TALER_MerchantPublicKeyP *merchant_pub, + const struct GNUNET_HashCode *h_wire, + const struct GNUNET_HashCode *h_contract, + uint64_t transaction_id, + struct GNUNET_TIME_Absolute execution_time, + const struct TALER_CoinSpendPublicKeyP *coin_pub, + const struct TALER_Amount *coin_value, + const struct TALER_Amount *coin_fee); + + + /** + * Function called to insert wire transfer commit data into the DB. + * + * @param cls closure + * @param session database connection + * @param type type of the wire transfer (i.e. "sepa") + * @param buf buffer with wire transfer preparation data + * @param buf_size number of bytes in @a buf + * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors + */ + int + (*wire_prepare_data_insert)(void *cls, + struct TALER_EXCHANGEDB_Session *session, + const char *type, + const char *buf, + size_t buf_size); + + + /** + * Function called to mark wire transfer commit data as finished. + * + * @param cls closure + * @param session database connection + * @param rowid which entry to mark as finished + * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors + */ + int + (*wire_prepare_data_mark_finished)(void *cls, + struct TALER_EXCHANGEDB_Session *session, + unsigned long long rowid); + + + /** + * Function called to get an unfinished wire transfer + * preparation data. Fetches at most one item. + * + * @param cls closure + * @param session database connection + * @param type type fo the wire transfer (i.e. "sepa") + * @param cb function to call for ONE unfinished item + * @param cb_cls closure for @a cb + * @return #GNUNET_OK on success, + * #GNUNET_NO if there are no entries, + * #GNUNET_SYSERR on DB errors + */ + int + (*wire_prepare_data_get)(void *cls, + struct TALER_EXCHANGEDB_Session *session, + const char *type, + TALER_EXCHANGEDB_WirePreparationCallback cb, + void *cb_cls); + + +}; + + +#endif /* _TALER_EXCHANGE_DB_H */ diff --git a/src/include/taler_mint_service.h b/src/include/taler_mint_service.h deleted file mode 100644 index 1502edfbc..000000000 --- a/src/include/taler_mint_service.h +++ /dev/null @@ -1,1220 +0,0 @@ -/* - 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 -*/ -/** - * @file include/taler_mint_service.h - * @brief C interface of libtalermint, a C library to use mint's HTTP API - * @author Sree Harsha Totakura - * @author Christian Grothoff - */ -#ifndef _TALER_MINT_SERVICE_H -#define _TALER_MINT_SERVICE_H - -#include "taler_util.h" - -/* ********************* event loop *********************** */ - -/** - * @brief Handle to this library context. This is where the - * main event loop logic lives. - */ -struct TALER_MINT_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_MINT_Context * -TALER_MINT_init (void); - - -/** - * Obtain the information for a select() call to wait until - * #TALER_MINT_perform() is ready again. Note that calling - * any other TALER_MINT-API may also imply that the library - * is again ready for #TALER_MINT_perform(). - * - * Basically, a client should use this API to prepare for select(), - * then block on select(), then call #TALER_MINT_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_MINT_perform(). - */ -void -TALER_MINT_get_select_info (struct TALER_MINT_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_MINT_perform (struct TALER_MINT_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_MINT_fini (struct TALER_MINT_Context *ctx); - - -/* ********************* /keys *********************** */ - - -/** - * List of possible options to be passed to - * #TALER_MINT_connect(). - */ -enum TALER_MINT_Option -{ - /** - * Terminator (end of option list). - */ - TALER_MINT_OPTION_END = 0 - -}; - - -/** - * @brief Mint's signature key - */ -struct TALER_MINT_SigningPublicKey -{ - /** - * The signing public key - */ - struct TALER_MintPublicKeyP key; - - /** - * Validity start time - */ - struct GNUNET_TIME_Absolute valid_from; - - /** - * Validity expiration time - */ - struct GNUNET_TIME_Absolute valid_until; -}; - - -/** - * @brief Public information about a mint's denomination key - */ -struct TALER_MINT_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 Mint 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 mint about auditors. - */ -struct TALER_MINT_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_MINT_DenomPublicKey **denom_keys; -}; - - -/** - * @brief Information about keys from the mint. - */ -struct TALER_MINT_Keys -{ - - /** - * Long-term offline signing key of the mint. - */ - struct TALER_MasterPublicKeyP master_pub; - - /** - * Array of the mint's online signing keys. - */ - struct TALER_MINT_SigningPublicKey *sign_keys; - - /** - * Array of the mint's denomination keys. - */ - struct TALER_MINT_DenomPublicKey *denom_keys; - - /** - * Array of the keys of the auditors of the mint. - */ - struct TALER_MINT_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 mint and what key the mint is using. - * - * @param cls closure - * @param keys information about the various keys used - * by the mint - */ -typedef void -(*TALER_MINT_CertificationCallback) (void *cls, - const struct TALER_MINT_Keys *keys); - - -/** - * @brief Handle to the mint. This is where we interact with - * a particular mint and keep the per-mint information. - */ -struct TALER_MINT_Handle; - - -/** - * Initialise a connection to the mint. Will connect to the - * mint and obtain information about the mint's master public - * key and the mint's auditor. The respective information will - * be passed to the @a cert_cb once available, and all future - * interactions with the mint will be checked to be signed - * (where appropriate) by the respective master key. - * - * @param ctx the context - * @param url HTTP base URL for the mint - * @param cert_cb function to call with the mint's certification information - * @param cert_cb_cls closure for @a cert_cb - * @param ... list of additional arguments, terminated by #TALER_MINT_OPTION_END. - * @return the mint handle; NULL upon error - */ -struct TALER_MINT_Handle * -TALER_MINT_connect (struct TALER_MINT_Context *ctx, - const char *url, - TALER_MINT_CertificationCallback cert_cb, - void *cert_cb_cls, - ...); - - -/** - * Disconnect from the mint. - * - * @param mint the mint handle - */ -void -TALER_MINT_disconnect (struct TALER_MINT_Handle *mint); - - -/** - * Obtain the keys from the mint. - * - * @param mint the mint handle - * @return the mint's key set - */ -const struct TALER_MINT_Keys * -TALER_MINT_get_keys (const struct TALER_MINT_Handle *mint); - - -/** - * Test if the given @a pub is a the current signing key from the mint - * according to @a keys. - * - * @param keys the mint's key set - * @param pub claimed current online signing key for the mint - * @return #GNUNET_OK if @a pub is (according to /keys) a current signing key - */ -int -TALER_MINT_test_signing_key (const struct TALER_MINT_Keys *keys, - const struct TALER_MintPublicKeyP *pub); - - -/** - * Obtain the denomination key details from the mint. - * - * @param keys the mint'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_MINT_DenomPublicKey * -TALER_MINT_get_denomination_key (const struct TALER_MINT_Keys *keys, - const struct TALER_DenominationPublicKey *pk); - - -/** - * Obtain the denomination key details from the mint. - * - * @param keys the mint'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_MINT_DenomPublicKey * -TALER_MINT_get_denomination_key_by_hash (const struct TALER_MINT_Keys *keys, - const struct GNUNET_HashCode *hc); - - -/* ********************* /wire *********************** */ - - -/** - * @brief A Wire format inquiry handle - */ -struct TALER_MINT_WireHandle; - - -/** - * Callbacks of this type are used to serve the result of submitting a - * wire format inquiry request to a mint. - * - * 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 mint, @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 mint 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 mint'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_MINT_WireResultCallback) (void *cls, - unsigned int http_status, - const char *method, - json_t *obj); - - -/** - * Obtain information about a mint's wire instructions. - * A mint may provide wire instructions for creating - * a reserve. The wire instructions also indicate - * which wire formats merchants may use with the mint. - * 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 mint's reply is not well-formed, - * we return an HTTP status code of zero to @a cb. - * - * @param mint the mint handle; the mint 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_MINT_WireHandle * -TALER_MINT_wire (struct TALER_MINT_Handle *mint, - TALER_MINT_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_MINT_wire_cancel (struct TALER_MINT_WireHandle *wh); - - -/* ********************* /deposit *********************** */ - - -/** - * @brief A Deposit Handle - */ -struct TALER_MINT_DepositHandle; - - -/** - * Callbacks of this type are used to serve the result of submitting a - * deposit permission request to a mint. - * - * @param cls closure - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful deposit; - * 0 if the mint'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_MINT_DepositResultCallback) (void *cls, - unsigned int http_status, - json_t *obj); - - -/** - * Submit a deposit permission to the mint and get the mint'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 mint'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 mint 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 mint and instead return NULL. - * - * @param mint the mint handle; the mint must be ready to operate - * @param amount the amount to be deposited - * @param wire_deadline execution date, until which the merchant would like the mint to settle the balance (advisory, the mint cannot be - * forced to settle in the past or upon very short notice, but of course a well-behaved mint will limit aggregation based on the advice received) - * @param wire_details the merchant’s account details, in a format supported by the mint - * @param h_contract hash of the contact of the merchant with the customer (further details are never disclosed to the mint) - * @param coin_pub coin’s public key - * @param denom_pub denomination key with which the coin is signed - * @param denom_sig mint’s unblinded signature of the coin - * @param timestamp timestamp when the contract was finalized, must match approximately the current time of the mint - * @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 mint (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_MINT_DepositHandle * -TALER_MINT_deposit (struct TALER_MINT_Handle *mint, - 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_MINT_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_MINT_deposit_cancel (struct TALER_MINT_DepositHandle *deposit); - - -/* ********************* /reserve/status *********************** */ - - -/** - * @brief A /reserve/status Handle - */ -struct TALER_MINT_ReserveStatusHandle; - - -/** - * Ways how a reserve's balance may change. - */ -enum TALER_MINT_ReserveTransactionType { - - /** - * Deposit into the reserve. - */ - TALER_MINT_RTT_DEPOSIT, - - /** - * Withdrawal from the reserve. - */ - TALER_MINT_RTT_WITHDRAWAL - -}; - - -/** - * @brief Entry in the reserve's transaction history. - */ -struct TALER_MINT_ReserveHistory -{ - - /** - * Type of the transaction. - */ - enum TALER_MINT_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 mint. - * - * @param cls closure - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request - * 0 if the mint'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_MINT_ReserveStatusResultCallback) (void *cls, - unsigned int http_status, - json_t *json, - const struct TALER_Amount *balance, - unsigned int history_length, - const struct TALER_MINT_ReserveHistory *history); - - -/** - * Submit a request to obtain the transaction history of a reserve - * from the mint. 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 mint's - * reply is not well-formed, we return an HTTP status code of zero to - * @a cb. - * - * @param mint the mint handle; the mint 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_MINT_ReserveStatusHandle * -TALER_MINT_reserve_status (struct TALER_MINT_Handle *mint, - const struct TALER_ReservePublicKeyP *reserve_pub, - TALER_MINT_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_MINT_reserve_status_cancel (struct TALER_MINT_ReserveStatusHandle *wsh); - - -/* ********************* /reserve/withdraw *********************** */ - - -/** - * @brief A /reserve/withdraw Handle - */ -struct TALER_MINT_ReserveWithdrawHandle; - - -/** - * Callbacks of this type are used to serve the result of submitting a - * deposit permission request to a mint. - * - * @param cls closure - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request - * 0 if the mint'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 mint (for logging, in case of errors) - */ -typedef void -(*TALER_MINT_ReserveWithdrawResultCallback) (void *cls, - unsigned int http_status, - const struct TALER_DenominationSignature *sig, - json_t *full_response); - - -/** - * Withdraw a coin from the mint 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 mint the mint handle; the mint 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 mint). - * In this case, the callback is not called. - */ -struct TALER_MINT_ReserveWithdrawHandle * -TALER_MINT_reserve_withdraw (struct TALER_MINT_Handle *mint, - const struct TALER_MINT_DenomPublicKey *pk, - const struct TALER_ReservePrivateKeyP *reserve_priv, - const struct TALER_CoinSpendPrivateKeyP *coin_priv, - const struct TALER_DenominationBlindingKey *blinding_key, - TALER_MINT_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_MINT_reserve_withdraw_cancel (struct TALER_MINT_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_MINT_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 mint). - * Otherwise, pointer to a buffer of @a res_size to store persistently - * before proceeding to #TALER_MINT_refresh_melt(). - * Non-null results should be freed using #GNUNET_free(). - */ -char * -TALER_MINT_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_MINT_DenomPublicKey *melt_pks, - int check_sigs, - unsigned int fresh_pks_len, - const struct TALER_MINT_DenomPublicKey *fresh_pks, - size_t *res_size); - - -/* ********************* /refresh/melt ***************************** */ - -/** - * @brief A /refresh/melt Handle - */ -struct TALER_MINT_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_MINT_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 mint's reply is bogus (fails to follow the protocol) - * @param noreveal_index choice by the mint in the cut-and-choose protocol, - * UINT16_MAX on error - * @param full_response full response from the mint (for logging, in case of errors) - */ -typedef void -(*TALER_MINT_RefreshMeltCallback) (void *cls, - unsigned int http_status, - uint16_t noreveal_index, - json_t *full_response); - - -/** - * Submit a melt request to the mint and get the mint'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_MINT_refresh_prepare and committed to persistent storage - * prior to calling this function. - * - * @param mint the mint handle; the mint must be ready to operate - * @param refresh_data_length size of the @a refresh_data (returned - * in the `res_size` argument from #TALER_MINT_refresh_prepare()) - * @param refresh_data the refresh data as returned from - #TALER_MINT_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_MINT_RefreshMeltHandle * -TALER_MINT_refresh_melt (struct TALER_MINT_Handle *mint, - size_t refresh_data_length, - const char *refresh_data, - TALER_MINT_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_MINT_refresh_melt_cancel (struct TALER_MINT_RefreshMeltHandle *rmh); - - -/* ********************* /refresh/reveal ***************************** */ - - -/** - * Callbacks of this type are used to return the final result of - * submitting a refresh request to a mint. 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 mint'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 mint (for logging, in case of errors) - */ -typedef void -(*TALER_MINT_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_MINT_RefreshRevealHandle; - - -/** - * Submit a /refresh/reval request to the mint and get the mint'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 mint the mint handle; the mint must be ready to operate - * @param refresh_data_length size of the @a refresh_data (returned - * in the `res_size` argument from #TALER_MINT_refresh_prepare()) - * @param refresh_data the refresh data as returned from - #TALER_MINT_refresh_prepare()) - * @param noreveal_index response from the mint to the - * #TALER_MINT_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_MINT_RefreshRevealHandle * -TALER_MINT_refresh_reveal (struct TALER_MINT_Handle *mint, - size_t refresh_data_length, - const char *refresh_data, - uint16_t noreveal_index, - TALER_MINT_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_MINT_refresh_reveal_cancel (struct TALER_MINT_RefreshRevealHandle *rrh); - - -/* ********************* /refresh/link ***************************** */ - - -/** - * @brief A /refresh/link Handle - */ -struct TALER_MINT_RefreshLinkHandle; - - -/** - * Callbacks of this type are used to return the final result of - * submitting a /refresh/link request to a mint. 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 mint'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 mint (for logging, in case of errors) - */ -typedef void -(*TALER_MINT_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 mint and get the mint'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 mint the mint handle; the mint 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_MINT_RefreshLinkHandle * -TALER_MINT_refresh_link (struct TALER_MINT_Handle *mint, - const struct TALER_CoinSpendPrivateKeyP *coin_priv, - TALER_MINT_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_MINT_refresh_link_cancel (struct TALER_MINT_RefreshLinkHandle *rlh); - - -/* ********************* /admin/add/incoming *********************** */ - - -/** - * @brief A /admin/add/incoming Handle - */ -struct TALER_MINT_AdminAddIncomingHandle; - - -/** - * Callbacks of this type are used to serve the result of submitting - * information about an incoming transaction to a mint. - * - * @param cls closure - * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request - * 0 if the mint's reply is bogus (fails to follow the protocol) - * @param full_response full response from the mint (for logging, in case of errors) - */ -typedef void -(*TALER_MINT_AdminAddIncomingResultCallback) (void *cls, - unsigned int http_status, - json_t *full_response); - - -/** - * Notify the mint 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 mint clients, but only - * to the operators of the mint. - * - * @param mint the mint handle; the mint 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_MINT_AdminAddIncomingHandle * -TALER_MINT_admin_add_incoming (struct TALER_MINT_Handle *mint, - const struct TALER_ReservePublicKeyP *reserve_pub, - const struct TALER_Amount *amount, - struct GNUNET_TIME_Absolute execution_date, - const json_t *wire, - TALER_MINT_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_MINT_admin_add_incoming_cancel (struct TALER_MINT_AdminAddIncomingHandle *aai); - - -/* ********************* /wire/deposits *********************** */ - -/** - * @brief A /wire/deposits Handle - */ -struct TALER_MINT_WireDepositsHandle; - - -/** - * Details for one of the /deposit operations that the - * mint 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 mint 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 mint 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 mint 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 mint 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_MINT_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 mint about which transactions were combined - * to create a wire transfer. - * - * @param mint mint 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_MINT_WireDepositsHandle * -TALER_MINT_wire_deposits (struct TALER_MINT_Handle *mint, - const struct TALER_WireTransferIdentifierRawP *wtid, - TALER_MINT_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_MINT_wire_deposits_cancel (struct TALER_MINT_WireDepositsHandle *wdh); - - -/* ********************* /deposit/wtid *********************** */ - - -/** - * @brief A /deposit/wtid Handle - */ -struct TALER_MINT_DepositWtidHandle; - - -/** - * Function called with detailed wire transfer data. - * - * @param cls closure - * @param http_status HTTP status code we got, 0 on mint protocol violation - * @param json original json reply (may include signatures, those have then been - * validated already) - * @param wtid wire transfer identifier used by the mint, NULL if mint 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_MINT_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 mint the mint 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_MINT_DepositWtidHandle * -TALER_MINT_deposit_wtid (struct TALER_MINT_Handle *mint, - 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_MINT_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_MINT_deposit_wtid_cancel (struct TALER_MINT_DepositWtidHandle *dwh); - - -#endif /* _TALER_MINT_SERVICE_H */ diff --git a/src/include/taler_mintdb_lib.h b/src/include/taler_mintdb_lib.h deleted file mode 100644 index 70e314d9a..000000000 --- a/src/include/taler_mintdb_lib.h +++ /dev/null @@ -1,291 +0,0 @@ -/* - 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 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 General Public License for more details. - - You should have received a copy of the GNU General Public License along with - TALER; see the file COPYING. If not, If not, see -*/ -/** - * @file include/taler_mintdb_lib.h - * @brief IO operations for the mint's private keys - * @author Florian Dold - * @author Benedikt Mueller - * @author Christian Grothoff - */ -#ifndef TALER_MINTDB_LIB_H -#define TALER_MINTDB_LIB_H - -#include "taler_signatures.h" - -/** - * Subdirectroy under the mint's base directory which contains - * the mint's signing keys. - */ -#define TALER_MINTDB_DIR_SIGNING_KEYS "signkeys" - -/** - * Subdirectory under the mint's base directory which contains - * the mint's denomination keys. - */ -#define TALER_MINTDB_DIR_DENOMINATION_KEYS "denomkeys" - -/** - * Subdirectory under the mint's base directory which contains - * the mint's auditing information. - */ -#define TALER_MINTDB_DIR_AUDITORS "auditors" - - -GNUNET_NETWORK_STRUCT_BEGIN - -/** - * @brief On disk format used for a mint signing key. Signing keys are used - * by the mint to affirm its messages, but not to create coins. - * Includes the private key followed by the public information about - * the signing key. - */ -struct TALER_MINTDB_PrivateSigningKeyInformationP -{ - /** - * Private key part of the mint's signing key. - */ - struct TALER_MintPrivateKeyP signkey_priv; - - /** - * Public information about a mint signing key. - */ - struct TALER_MintSigningKeyValidityPS issue; -}; - - -/** - * Information about a denomination key. - */ -struct TALER_MINTDB_DenominationKeyInformationP -{ - - /** - * Signature over this struct to affirm the validity of the key. - */ - struct TALER_MasterSignatureP signature; - - /** - * Signed properties of the denomination key. - */ - struct TALER_DenominationKeyValidityPS properties; -}; - - -GNUNET_NETWORK_STRUCT_END - - -/** - * @brief All information about a denomination key (which is used to - * sign coins into existence). - */ -struct TALER_MINTDB_DenominationKeyIssueInformation -{ - /** - * The private key of the denomination. Will be NULL if the private - * key is not available (this is the case after the key has expired - * for signing coins, but is still valid for depositing coins). - */ - struct TALER_DenominationPrivateKey denom_priv; - - /** - * Decoded denomination public key (the hash of it is in - * @e issue, but we sometimes need the full public key as well). - */ - struct TALER_DenominationPublicKey denom_pub; - - /** - * Signed public information about a denomination key. - */ - struct TALER_MINTDB_DenominationKeyInformationP issue; -}; - - -/** - * @brief Iterator over signing keys. - * - * @param cls closure - * @param filename name of the file the key came from - * @param ski the sign key - * @return #GNUNET_OK to continue to iterate, - * #GNUNET_NO to stop iteration with no error, - * #GNUNET_SYSERR to abort iteration with error! - */ -typedef int -(*TALER_MINTDB_SigningKeyIterator)(void *cls, - const char *filename, - const struct TALER_MINTDB_PrivateSigningKeyInformationP *ski); - - -/** - * Call @a it for each signing key found in the @a mint_base_dir. - * - * @param mint_base_dir base directory for the mint, - * the signing keys must be in the #TALER_MINTDB_DIR_SIGNING_KEYS - * subdirectory - * @param it function to call on each signing key - * @param it_cls closure for @a it - * @return number of files found (may not match - * number of keys given to @a it as malformed - * files are simply skipped), -1 on error - */ -int -TALER_MINTDB_signing_keys_iterate (const char *mint_base_dir, - TALER_MINTDB_SigningKeyIterator it, - void *it_cls); - - - -/** - * @brief Iterator over denomination keys. - * - * @param cls closure - * @param dki the denomination key - * @param alias coin alias - * @return #GNUNET_OK to continue to iterate, - * #GNUNET_NO to stop iteration with no error, - * #GNUNET_SYSERR to abort iteration with error! - */ -typedef int -(*TALER_MINTDB_DenominationKeyIterator)(void *cls, - const char *alias, - const struct TALER_MINTDB_DenominationKeyIssueInformation *dki); - - -/** - * Call @a it for each denomination key found in the @a mint_base_dir. - * - * @param mint_base_dir base directory for the mint, - * the signing keys must be in the #TALER_MINTDB_DIR_DENOMINATION_KEYS - * subdirectory - * @param it function to call on each denomination key found - * @param it_cls closure for @a it - * @return -1 on error, 0 if no files were found, otherwise - * a positive number (however, even with a positive - * number it is possible that @a it was never called - * as maybe none of the files were well-formed) - */ -int -TALER_MINTDB_denomination_keys_iterate (const char *mint_base_dir, - TALER_MINTDB_DenominationKeyIterator it, - void *it_cls); - - -/** - * Exports a denomination key to the given file. - * - * @param filename the file where to write the denomination key - * @param dki the denomination key - * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure. - */ -int -TALER_MINTDB_denomination_key_write (const char *filename, - const struct TALER_MINTDB_DenominationKeyIssueInformation *dki); - - -/** - * Import a denomination key from the given file. - * - * @param filename the file to import the key from - * @param[out] dki set to the imported denomination key - * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure - */ -int -TALER_MINTDB_denomination_key_read (const char *filename, - struct TALER_MINTDB_DenominationKeyIssueInformation *dki); - - -/** - * @brief Iterator over auditor information. - * - * @param cls closure - * @param apub the auditor's public key - * @param mpub the mint's public key (as expected by the auditor) - * @param dki_len length of @a asig and @a dki arrays - * @param asigs array of the auditor's signatures over the @a dks, of length @a dki_len - * @param dki array of denomination coin data signed by the auditor, of length @a dki_len - * @return #GNUNET_OK to continue to iterate, - * #GNUNET_NO to stop iteration with no error, - * #GNUNET_SYSERR to abort iteration with error! - */ -typedef int -(*TALER_MINTDB_AuditorIterator)(void *cls, - const struct TALER_AuditorPublicKeyP *apub, - const struct TALER_MasterPublicKeyP *mpub, - unsigned int dki_len, - const struct TALER_AuditorSignatureP *asigs, - const struct TALER_DenominationKeyValidityPS *dki); - - -/** - * Call @a it with information for each auditor found in the @a mint_base_dir. - * - * @param mint_base_dir base directory for the mint, - * the signing keys must be in the #TALER_MINTDB_DIR_DENOMINATION_KEYS - * subdirectory - * @param it function to call with auditor information - * @param it_cls closure for @a it - * @return -1 on error, 0 if no files were found, otherwise - * a positive number (however, even with a positive - * number it is possible that @a it was never called - * as maybe none of the files were well-formed) - */ -int -TALER_MINTDB_auditor_iterate (const char *mint_base_dir, - TALER_MINTDB_AuditorIterator it, - void *it_cls); - - -/** - * Write auditor information to the given file. - * - * @param filename the file where to write the auditor information to - * @param apub the auditor's public key - * @param asigs the auditor's signatures, array of length @a dki_len - * @param mpub the mint's public key (as expected by the auditor) - * @param dki_len length of @a dki and @a asigs arrays - * @param dki array of denomination coin data signed by the auditor - * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure. - */ -int -TALER_MINTDB_auditor_write (const char *filename, - const struct TALER_AuditorPublicKeyP *apub, - const struct TALER_AuditorSignatureP *asigs, - const struct TALER_MasterPublicKeyP *mpub, - unsigned int dki_len, - const struct TALER_DenominationKeyValidityPS *dki); - - -/** - * Initialize the plugin. - * - * @param cfg configuration to use - * @return NULL on failure - */ -struct TALER_MINTDB_Plugin * -TALER_MINTDB_plugin_load (const struct GNUNET_CONFIGURATION_Handle *cfg); - - -/** - * Shutdown the plugin. - * - * @param plugin plugin to unload - */ -void -TALER_MINTDB_plugin_unload (struct TALER_MINTDB_Plugin *plugin); - - - -#endif diff --git a/src/include/taler_mintdb_plugin.h b/src/include/taler_mintdb_plugin.h deleted file mode 100644 index b65b3e4f7..000000000 --- a/src/include/taler_mintdb_plugin.h +++ /dev/null @@ -1,1431 +0,0 @@ -/* - This file is part of TALER - Copyright (C) 2014, 2015, 2016 GNUnet e.V. - - TALER is free software; you can redistribute it and/or modify it under the - terms of the GNU 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 General Public License for more details. - - You should have received a copy of the GNU General Public License along with - TALER; see the file COPYING. If not, If not, see -*/ -/** - * @file include/taler_mintdb_plugin.h - * @brief Low-level (statement-level) database access for the mint - * @author Florian Dold - * @author Christian Grothoff - */ -#ifndef TALER_MINTDB_PLUGIN_H -#define TALER_MINTDB_PLUGIN_H - -#include -#include "taler_mintdb_lib.h" - - -/** - * @brief Information we keep on bank transfer(s) that established a reserve. - */ -struct TALER_MINTDB_BankTransfer -{ - - /** - * Public key of the reserve that was filled. - */ - struct TALER_ReservePublicKeyP reserve_pub; - - /** - * Amount that was transferred to the mint. - */ - struct TALER_Amount amount; - - /** - * When did the mint receive the incoming transaction? - * (This is the execution date of the mint's database, - * the execution date of the bank should be in @e wire). - */ - struct GNUNET_TIME_Absolute execution_date; - - /** - * Detailed wire information about the transaction. - */ - json_t *wire; - -}; - - -/** - * @brief A summary of a Reserve - */ -struct TALER_MINTDB_Reserve -{ - /** - * The reserve's public key. This uniquely identifies the reserve - */ - struct TALER_ReservePublicKeyP pub; - - /** - * The balance amount existing in the reserve - */ - struct TALER_Amount balance; - - /** - * The expiration date of this reserve - */ - struct GNUNET_TIME_Absolute expiry; -}; - - -/** - * @brief Information we keep for a withdrawn coin to reproduce - * the /withdraw operation if needed, and to have proof - * that a reserve was drained by this amount. - */ -struct TALER_MINTDB_CollectableBlindcoin -{ - - /** - * Our signature over the (blinded) coin. - */ - struct TALER_DenominationSignature sig; - - /** - * Denomination key (which coin was generated). - */ - struct TALER_DenominationPublicKey denom_pub; - - /** - * Value of the coin being minted (matching the denomination key) - * plus the transaction fee. We include this in what is being - * signed so that we can verify a reserve's remaining total balance - * without needing to access the respective denomination key - * information each time. - */ - struct TALER_Amount amount_with_fee; - - /** - * Withdrawl fee charged by the mint. This must match the Mint's - * denomination key's withdrawl fee. If the client puts in an - * invalid withdrawl fee (too high or too low) that does not match - * the Mint's denomination key, the withdraw operation is invalid - * and will be rejected by the mint. The @e amount_with_fee minus - * the @e withdraw_fee is must match the value of the generated - * coin. We include this in what is being signed so that we can - * verify a mint's accounting without needing to access the - * respective denomination key information each time. - */ - struct TALER_Amount withdraw_fee; - - /** - * Public key of the reserve that was drained. - */ - struct TALER_ReservePublicKeyP reserve_pub; - - /** - * Hash over the blinded message, needed to verify - * the @e reserve_sig. - */ - struct GNUNET_HashCode h_coin_envelope; - - /** - * Signature confirming the withdrawl, matching @e reserve_pub, - * @e denom_pub and @e h_coin_envelope. - */ - struct TALER_ReserveSignatureP reserve_sig; -}; - - - -/** - * @brief Types of operations on a reserved. - */ -enum TALER_MINTDB_ReserveOperation -{ - /** - * Money was deposited into the reserve via a bank transfer. - */ - TALER_MINTDB_RO_BANK_TO_MINT = 0, - - /** - * A Coin was withdrawn from the reserve using /withdraw. - */ - TALER_MINTDB_RO_WITHDRAW_COIN = 1 -}; - - -/** - * @brief Reserve history as a linked list. Lists all of the transactions - * associated with this reserve (such as the bank transfers that - * established the reserve and all /withdraw operations we have done - * since). - */ -struct TALER_MINTDB_ReserveHistory -{ - - /** - * Next entry in the reserve history. - */ - struct TALER_MINTDB_ReserveHistory *next; - - /** - * Type of the event, determins @e details. - */ - enum TALER_MINTDB_ReserveOperation type; - - /** - * Details of the operation, depending on @e type. - */ - union - { - - /** - * Details about a bank transfer to the mint. - */ - struct TALER_MINTDB_BankTransfer *bank; - - /** - * Details about a /withdraw operation. - */ - struct TALER_MINTDB_CollectableBlindcoin *withdraw; - - } details; - -}; - - -/** - * @brief Specification for a /deposit operation. The combination of - * the coin's public key, the merchant's public key and the - * transaction ID must be unique. While a coin can (theoretically) be - * deposited at the same merchant twice (with partial spending), the - * merchant must either use a different public key or a different - * transaction ID for the two transactions. The same coin must not - * be used twice at the same merchant for the same transaction - * (as determined by transaction ID). (Note: we might want to - * fix #3819 and include at least h_contract as well.) - */ -struct TALER_MINTDB_Deposit -{ - /** - * Information about the coin that is being deposited. - */ - struct TALER_CoinPublicInfo coin; - - /** - * ECDSA signature affirming that the customer intends - * this coin to be deposited at the merchant identified - * by @e h_wire in relation to the contract identified - * by @e h_contract. - */ - struct TALER_CoinSpendSignatureP csig; - - /** - * Public key of the merchant. Enables later identification - * of the merchant in case of a need to rollback transactions. - */ - struct TALER_MerchantPublicKeyP merchant_pub; - - /** - * Hash over the contract between merchant and customer - * (remains unknown to the Mint). - */ - struct GNUNET_HashCode h_contract; - - /** - * Hash of the (canonical) representation of @e wire, used - * to check the signature on the request. Generated by - * the mint from the detailed wire data provided by the - * merchant. - */ - struct GNUNET_HashCode h_wire; - - /** - * Detailed wire information for executing the transaction. - */ - json_t *wire; - - /** - * Merchant-generated transaction ID to detect duplicate - * transactions. - */ - uint64_t transaction_id; - - /** - * Time when this request was generated. Used, for example, to - * assess when (roughly) the income was achieved for tax purposes. - * Note that the Mint will only check that the timestamp is not "too - * far" into the future (i.e. several days). The fact that the - * timestamp falls within the validity period of the coin's - * denomination key is irrelevant for the validity of the deposit - * request, as obviously the customer and merchant could conspire to - * set any timestamp. Also, the Mint must accept very old deposit - * requests, as the merchant might have been unable to transmit the - * deposit request in a timely fashion (so back-dating is not - * prevented). - */ - struct GNUNET_TIME_Absolute timestamp; - - /** - * How much time does the merchant have to issue a refund request? - * Zero if refunds are not allowed. After this time, the coin - * cannot be refunded. - */ - struct GNUNET_TIME_Absolute refund_deadline; - - /** - * How much time does the merchant have to execute the wire transfer? - * This time is advisory for aggregating transactions, not a hard - * constraint (as the merchant can theoretically pick any time, - * including one in the past). - */ - struct GNUNET_TIME_Absolute wire_deadline; - - /** - * Fraction of the coin's remaining value to be deposited, including - * depositing fee (if any). The coin is identified by @e coin_pub. - */ - struct TALER_Amount amount_with_fee; - - /** - * Depositing fee. - */ - struct TALER_Amount deposit_fee; - -}; - - -/** - * @brief Global information for a refreshing session. Includes - * dimensions of the operation, security parameters and - * client signatures from "/refresh/melt" and "/refresh/commit". - */ -struct TALER_MINTDB_RefreshSession -{ - - /** - * Number of coins we are melting. - */ - uint16_t num_oldcoins; - - /** - * Number of new coins we are creating. - */ - uint16_t num_newcoins; - - /** - * Index (smaller #TALER_CNC_KAPPA) which the mint has chosen to not - * have revealed during cut and choose. - */ - uint16_t noreveal_index; - -}; - - -/** - * @brief Specification for coin in a /refresh/melt operation. - */ -struct TALER_MINTDB_RefreshMelt -{ - /** - * Information about the coin that is being melted. - */ - struct TALER_CoinPublicInfo coin; - - /** - * Signature over the melting operation. - */ - struct TALER_CoinSpendSignatureP coin_sig; - - /** - * Hash of the refresh session this coin is melted into. - */ - struct GNUNET_HashCode session_hash; - - /** - * How much value is being melted? This amount includes the fees, - * so the final amount contributed to the melt is this value minus - * the fee for melting the coin. We include the fee in what is - * being signed so that we can verify a reserve's remaining total - * balance without needing to access the respective denomination key - * information each time. - */ - struct TALER_Amount amount_with_fee; - - /** - * Melting fee charged by the mint. This must match the Mint's - * denomination key's melting fee. If the client puts in an invalid - * melting fee (too high or too low) that does not match the Mint's - * denomination key, the melting operation is invalid and will be - * rejected by the mint. The @e amount_with_fee minus the @e - * melt_fee is the amount that will be credited to the melting - * session. - */ - struct TALER_Amount melt_fee; - -}; - - -/** - * @brief We have as many `struct TALER_MINTDB_RefreshCommitCoin` as there are new - * coins being created by the refresh (for each of the #TALER_CNC_KAPPA - * sets). These are the coins we ask the mint to sign if the - * respective set is selected. - */ -struct TALER_MINTDB_RefreshCommitCoin -{ - - /** - * Encrypted data allowing those able to decrypt it to derive - * the private keys of the new coins created by the refresh. - */ - struct TALER_RefreshLinkEncrypted *refresh_link; - - /** - * Blinded message to be signed (in envelope), with @e coin_env_size bytes. - */ - char *coin_ev; - - /** - * Number of bytes in @e coin_ev. - */ - size_t coin_ev_size; - -}; - - -/** - * @brief Linked list of refresh information linked to a coin. - */ -struct TALER_MINTDB_LinkDataList -{ - /** - * Information is stored in a NULL-terminated linked list. - */ - struct TALER_MINTDB_LinkDataList *next; - - /** - * Link data, used to recover the private key of the coin - * by the owner of the old coin. - */ - struct TALER_RefreshLinkEncrypted *link_data_enc; - - /** - * Denomination public key, determines the value of the coin. - */ - struct TALER_DenominationPublicKey denom_pub; - - /** - * Signature over the blinded envelope. - */ - struct TALER_DenominationSignature ev_sig; -}; - - -/** - * @brief Enumeration to classify the different types of transactions - * that can be done with a coin. - */ -enum TALER_MINTDB_TransactionType -{ - /** - * /deposit operation. - */ - TALER_MINTDB_TT_DEPOSIT = 0, - - /** - * /refresh/melt operation. - */ - TALER_MINTDB_TT_REFRESH_MELT = 1 - -}; - - -/** - * @brief List of transactions we performed for a particular coin. - */ -struct TALER_MINTDB_TransactionList -{ - - /** - * Next pointer in the NULL-terminated linked list. - */ - struct TALER_MINTDB_TransactionList *next; - - /** - * Type of the transaction, determines what is stored in @e details. - */ - enum TALER_MINTDB_TransactionType type; - - /** - * Details about the transaction, depending on @e type. - */ - union - { - - /** - * Details if transaction was a /deposit operation. - */ - struct TALER_MINTDB_Deposit *deposit; - - /** - * Details if transaction was a /refresh/melt operation. - */ - struct TALER_MINTDB_RefreshMelt *melt; - - } details; - -}; - - -/** - * @brief All of the information from a /refresh/melt commitment. - */ -struct TALER_MINTDB_MeltCommitment -{ - - /** - * Number of coins we are melting. - */ - uint16_t num_oldcoins; - - /** - * Number of new coins we are creating. - */ - uint16_t num_newcoins; - - /** - * Array of @e num_oldcoins melt operation details. - */ - struct TALER_MINTDB_RefreshMelt *melts; - - /** - * Array of @e num_newcoins denomination keys - */ - struct TALER_DenominationPublicKey *denom_pubs; - - /** - * 2D-Array of #TALER_CNC_KAPPA and @e num_newcoins commitments. - */ - struct TALER_MINTDB_RefreshCommitCoin *commit_coins[TALER_CNC_KAPPA]; - - /** - * 2D-Array of #TALER_CNC_KAPPA and @e new_oldcoins links. - */ - struct TALER_RefreshCommitLinkP *commit_links[TALER_CNC_KAPPA]; -}; - - -/** - * @brief Handle for a database session (per-thread, for transactions). - */ -struct TALER_MINTDB_Session; - - -/** - * Function called with details about deposits that - * have been made, with the goal of executing the - * corresponding wire transaction. - * - * @param cls closure - * @param rowid unique ID for the deposit in our DB, used for marking - * it as 'tiny' or 'done' - * @param merchant_pub public key of the merchant - * @param coin_pub public key of the coin - * @param amount_with_fee amount that was deposited including fee - * @param deposit_fee amount the mint gets to keep as transaction fees - * @param transaction_id unique transaction ID chosen by the merchant - * @param h_contract hash of the contract between merchant and customer - * @param wire_deadline by which the merchant adviced that he would like the - * wire transfer to be executed - * @param wire wire details for the merchant, NULL from iterate_matching_deposits() - * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop - */ -typedef int -(*TALER_MINTDB_DepositIterator)(void *cls, - unsigned long long rowid, - const struct TALER_MerchantPublicKeyP *merchant_pub, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - const struct TALER_Amount *amount_with_fee, - const struct TALER_Amount *deposit_fee, - uint64_t transaction_id, - const struct GNUNET_HashCode *h_contract, - struct GNUNET_TIME_Absolute wire_deadline, - const json_t *wire); - - -/** - * Function called with the session hashes and transfer secret - * information for a given coin. - * - * @param cls closure - * @param session_hash a session the coin was melted in - * @param transfer_pub public transfer key for the session - * @param shared_secret_enc set to shared secret for the session - */ -typedef void -(*TALER_MINTDB_TransferDataCallback)(void *cls, - const struct GNUNET_HashCode *session_hash, - const struct TALER_TransferPublicKeyP *transfer_pub, - const struct TALER_EncryptedLinkSecretP *shared_secret_enc); - - -/** - * Function called with the results of the lookup of the - * wire transfer identifier information. Only called if - * we are at least aware of the transaction existing. - * - * @param cls closure - * @param wtid wire transfer identifier, NULL - * if the transaction was not yet done - * @param coin_contribution how much did the coin we asked about - * contribute to the total transfer value? (deposit value including fee) - * @param coin_fee how much did the mint charge for the deposit fee - * @param execution_time when was the transaction done, or - * when we expect it to be done (if @a wtid was NULL) - */ -typedef void -(*TALER_MINTDB_DepositWtidCallback)(void *cls, - const struct TALER_WireTransferIdentifierRawP *wtid, - const struct TALER_Amount *coin_contribution, - const struct TALER_Amount *coin_fee, - struct GNUNET_TIME_Absolute execution_time); - - -/** - * Function called with the results of the lookup of the - * transaction data associated with a wire transfer identifier. - * - * @param cls closure - * @param merchant_pub public key of the merchant (should be same for all callbacks with the same @e cls) - * @param h_wire hash of wire transfer details of the merchant (should be same for all callbacks with the same @e cls) - * @param h_contract which contract was this payment about - * @param transaction_id merchant's transaction ID for the payment - * @param coin_pub which public key was this payment about - * @param coin_value amount contributed by this coin in total (with fee) - * @param coin_fee applicable fee for this coin - */ -typedef void -(*TALER_MINTDB_WireTransferDataCallback)(void *cls, - const struct TALER_MerchantPublicKeyP *merchant_pub, - const struct GNUNET_HashCode *h_wire, - const struct GNUNET_HashCode *h_contract, - uint64_t transaction_id, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - const struct TALER_Amount *coin_value, - const struct TALER_Amount *coin_fee); - - -/** - * Callback with data about a prepared transaction. - * - * @param cls closure - * @param rowid row identifier used to mark prepared transaction as done - * @param buf transaction data that was persisted, NULL on error - * @param buf_size number of bytes in @a buf, 0 on error - */ -typedef void -(*TALER_MINTDB_WirePreparationCallback) (void *cls, - unsigned long long rowid, - const char *buf, - size_t buf_size); - - -/** - * @brief The plugin API, returned from the plugin's "init" function. - * The argument given to "init" is simply a configuration handle. - */ -struct TALER_MINTDB_Plugin -{ - - /** - * Closure for all callbacks. - */ - void *cls; - - /** - * Name of the library which generated this plugin. Set by the - * plugin loader. - */ - char *library_name; - - /** - * Get the thread-local database-handle. - * Connect to the db if the connection does not exist yet. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param temporary #GNUNET_YES to use a temporary schema; #GNUNET_NO to use the - * database default one - * @param the database connection, or NULL on error - */ - struct TALER_MINTDB_Session * - (*get_session) (void *cls, - int temporary); - - - /** - * Drop the temporary taler schema. This is only useful for testcases. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure - */ - int - (*drop_temporary) (void *cls, - struct TALER_MINTDB_Session *db); - - - /** - * Create the necessary tables if they are not present - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param temporary should we use a temporary schema - * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure - */ - int - (*create_tables) (void *cls, - int temporary); - - - /** - * Start a transaction. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to use - * @return #GNUNET_OK on success - */ - int - (*start) (void *cls, - struct TALER_MINTDB_Session *session); - - - /** - * Commit a transaction. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to use - * @return #GNUNET_OK on success, #GNUNET_NO if the transaction - * can be retried, #GNUNET_SYSERR on hard failures - */ - int - (*commit) (void *cls, - struct TALER_MINTDB_Session *session); - - - /** - * Abort/rollback a transaction. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to use - */ - void - (*rollback) (void *cls, - struct TALER_MINTDB_Session *session); - - - /** - * Insert information about a denomination key and in particular - * the properties (value, fees, expiration times) the coins signed - * with this key have. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to use - * @param denom_pub the public key used for signing coins of this denomination - * @param issue issuing information with value, fees and other info about the coin - * @return #GNUNET_OK on success; #GNUNET_SYSERR on failure - */ - int - (*insert_denomination_info) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_DenominationPublicKey *denom_pub, - const struct TALER_MINTDB_DenominationKeyInformationP *issue); - - - /** - * Fetch information about a denomination key. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to use - * @param denom_pub the public key used for signing coins of this denomination - * @param[out] issue set to issue information with value, fees and other info about the coin, can be NULL - * @return #GNUNET_OK on success; #GNUNET_NO if no record was found, #GNUNET_SYSERR on failure - */ - int - (*get_denomination_info) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_DenominationPublicKey *denom_pub, - struct TALER_MINTDB_DenominationKeyInformationP *issue); - - - /** - * Get the summary of a reserve. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param db the database connection handle - * @param[in,out] reserve the reserve data. The public key of the reserve should be set - * in this structure; it is used to query the database. The balance - * and expiration are then filled accordingly. - * @return #GNUNET_OK upon success; #GNUNET_SYSERR upon failure - */ - int - (*reserve_get) (void *cls, - struct TALER_MINTDB_Session *db, - struct TALER_MINTDB_Reserve *reserve); - - - /** - * Insert a incoming transaction into reserves. New reserves are - * also created through this function. Note that this API call - * starts (and stops) its own transaction scope (so the application - * must not do so). - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param db the database connection handle - * @param reserve_pub public key of the reserve - * @param balance the amount that has to be added to the reserve - * @param execution_time when was the amount added - * @param details bank transaction details justifying the increment, - * must be unique for each incoming transaction - * @return #GNUNET_OK upon success; #GNUNET_NO if the given - * @a details are already known for this @a reserve_pub, - * #GNUNET_SYSERR upon failures (DB error, incompatible currency) - */ - int - (*reserves_in_insert) (void *cls, - struct TALER_MINTDB_Session *db, - const struct TALER_ReservePublicKeyP *reserve_pub, - const struct TALER_Amount *balance, - struct GNUNET_TIME_Absolute execution_time, - const json_t *details); - - - /** - * Locate the response for a /withdraw request under the - * key of the hash of the blinded message. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection to use - * @param h_blind hash of the blinded coin to be signed (will match - * `h_coin_envelope` in the @a collectable to be returned) - * @param collectable corresponding collectable coin (blind signature) - * if a coin is found - * @return #GNUNET_SYSERR on internal error - * #GNUNET_NO if the collectable was not found - * #GNUNET_YES on success - */ - int - (*get_withdraw_info) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *h_blind, - struct TALER_MINTDB_CollectableBlindcoin *collectable); - - - /** - * Store collectable bit coin under the corresponding - * hash of the blinded message. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection to use - * @param collectable corresponding collectable coin (blind signature) - * if a coin is found - * @return #GNUNET_SYSERR on internal error - * #GNUNET_NO if the collectable was not found - * #GNUNET_YES on success - */ - int - (*insert_withdraw_info) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_MINTDB_CollectableBlindcoin *collectable); - - - /** - * Get all of the transaction history associated with the specified - * reserve. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to use - * @param reserve_pub public key of the reserve - * @return known transaction history (NULL if reserve is unknown) - */ - struct TALER_MINTDB_ReserveHistory * - (*get_reserve_history) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_ReservePublicKeyP *reserve_pub); - - - /** - * Free memory associated with the given reserve history. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param rh history to free. - */ - void - (*free_reserve_history) (void *cls, - struct TALER_MINTDB_ReserveHistory *rh); - - - /** - * Check if we have the specified deposit already in the database. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param deposit deposit to search for - * @return #GNUNET_YES if we know this operation, - * #GNUNET_NO if this exact deposit is unknown to us, - * #GNUNET_SYSERR on DB error - */ - int - (*have_deposit) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_MINTDB_Deposit *deposit); - - - /** - * Insert information about deposited coin into the database. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to the database - * @param deposit deposit information to store - * @return #GNUNET_OK on success, #GNUNET_SYSERR on error - */ - int - (*insert_deposit) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_MINTDB_Deposit *deposit); - - - /** - * Mark a deposit as tiny, thereby declaring that it cannot be - * executed by itself and should no longer be returned by - * @e iterate_ready_deposits() - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to the database - * @param deposit_rowid identifies the deposit row to modify - * @return #GNUNET_OK on success, #GNUNET_SYSERR on error - */ - int - (*mark_deposit_tiny) (void *cls, - struct TALER_MINTDB_Session *session, - unsigned long long rowid); - - - /** - * Mark a deposit as done, thereby declaring that it cannot be - * executed at all anymore, and should no longer be returned by - * @e iterate_ready_deposits() or @e iterate_matching_deposits(). - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to the database - * @param deposit_rowid identifies the deposit row to modify - * @return #GNUNET_OK on success, #GNUNET_SYSERR on error - */ - int - (*mark_deposit_done) (void *cls, - struct TALER_MINTDB_Session *session, - unsigned long long rowid); - - - /** - * Obtain information about deposits that are ready to be executed. - * Such deposits must not be marked as "tiny" or "done", and the - * execution time must be in the past. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to the database - * @param deposit_cb function to call for ONE such deposit - * @param deposit_cb_cls closure for @a deposit_cb - * @return number of rows processed, 0 if none exist, - * #GNUNET_SYSERR on error - */ - int - (*get_ready_deposit) (void *cls, - struct TALER_MINTDB_Session *session, - TALER_MINTDB_DepositIterator deposit_cb, - void *deposit_cb_cls); - - - /** - * Obtain information about other pending deposits for the same - * destination. Those deposits must not already be "done". - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session connection to the database - * @param h_wire destination of the wire transfer - * @param merchant_pub public key of the merchant - * @param deposit_cb function to call for each deposit - * @param deposit_cb_cls closure for @a deposit_cb - * @param limit maximum number of matching deposits to return - * @return number of rows processed, 0 if none exist, - * #GNUNET_SYSERR on error - */ - int - (*iterate_matching_deposits) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *h_wire, - const struct TALER_MerchantPublicKeyP *merchant_pub, - TALER_MINTDB_DepositIterator deposit_cb, - void *deposit_cb_cls, - uint32_t limit); - - - /** - * Lookup refresh session data under the given @a session_hash. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database handle to use - * @param session_hash hash over the melt to use for the lookup - * @param[out] refresh_session where to store the result - * @return #GNUNET_YES on success, - * #GNUNET_NO if not found, - * #GNUNET_SYSERR on DB failure - */ - int - (*get_refresh_session) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - struct TALER_MINTDB_RefreshSession *refresh_session); - - - /** - * Store new refresh session data under the given @a session_hash. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database handle to use - * @param session_hash hash over the melt to use to locate the session - * @param refresh_session session data to store - * @return #GNUNET_YES on success, - * #GNUNET_SYSERR on DB failure - */ - int - (*create_refresh_session) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - const struct TALER_MINTDB_RefreshSession *refresh_session); - - - /** - * Store the given /refresh/melt request in the database. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param oldcoin_index index of the coin to store - * @param melt coin melt operation details to store; includes - * the session hash of the melt - * @return #GNUNET_OK on success - * #GNUNET_SYSERR on internal error - */ - int - (*insert_refresh_melt) (void *cls, - struct TALER_MINTDB_Session *session, - uint16_t oldcoin_index, - const struct TALER_MINTDB_RefreshMelt *melt); - - - /** - * Get information about melted coin details from the database. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param session_hash hash to identify refresh session - * @param oldcoin_index index of the coin to retrieve - * @param melt melt data to fill in, can be NULL - * @return #GNUNET_OK on success - * #GNUNET_SYSERR on internal error - */ - int - (*get_refresh_melt) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t oldcoin_index, - struct TALER_MINTDB_RefreshMelt *melt); - - - /** - * Store in the database which coin(s) we want to create - * in a given refresh operation. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param session_hash hash to identify refresh session - * @param num_newcoins number of coins to generate, size of the @a denom_pubs array - * @param denom_pubs array denominations of the coins to create - * @return #GNUNET_OK on success - * #GNUNET_SYSERR on internal error - */ - int - (*insert_refresh_order) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t num_newcoins, - const struct TALER_DenominationPublicKey *denom_pubs); - - - /** - * Lookup in the database for the @a num_newcoins coins that we want to - * create in the given refresh operation. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param session_hash hash to identify refresh session - * @param num_newcoins size of the @a denom_pubs array - * @param[out] denom_pubs where to write @a num_newcoins denomination keys - * @return #GNUNET_OK on success - * #GNUNET_SYSERR on internal error - */ - int - (*get_refresh_order) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t num_newcoins, - struct TALER_DenominationPublicKey *denom_pubs); - - - /** - * Store information about the commitments of the given index @a i - * for the given refresh session in the database. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection to use - * @param session_hash hash to identify refresh session - * @param cnc_index cut and choose index (1st dimension), relating to #TALER_CNC_KAPPA - * @param num_newcoins coin index size of the @a commit_coins array - * @param commit_coin array of coin commitments to store - * @return #GNUNET_OK on success - * #GNUNET_SYSERR on error - */ - int - (*insert_refresh_commit_coins) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t cnc_index, - uint16_t num_newcoins, - const struct TALER_MINTDB_RefreshCommitCoin *commit_coins); - - - /** - * Obtain information about the commitment of the - * given coin of the given refresh session from the database. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection to use - * @param session_hash hash to identify refresh session - * @param cnc_index cut and choose set index (1st dimension) - * @param num_coins size of the @a commit_coins array - * @param[out] commit_coins array of coin commitments to return - * @return #GNUNET_OK on success - * #GNUNET_NO if not found - * #GNUNET_SYSERR on error - */ - int - (*get_refresh_commit_coins) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t cnc_index, - uint16_t num_coins, - struct TALER_MINTDB_RefreshCommitCoin *commit_coins); - - - /** - * Store the commitment to the given (encrypted) refresh link data - * for the given refresh session. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection to use - * @param session_hash hash to identify refresh session - * @param cnc_index cut and choose index (1st dimension), relating to #TALER_CNC_KAPPA - * @param num_links size of the @a commit_link array - * @param commit_links array of link information to store - * @return #GNUNET_SYSERR on internal error, #GNUNET_OK on success - */ - int - (*insert_refresh_commit_links) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t cnc_index, - uint16_t num_links, - const struct TALER_RefreshCommitLinkP *commit_links); - - /** - * Obtain the commited (encrypted) refresh link data - * for the given refresh session. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection to use - * @param session_hash hash to identify refresh session - * @param cnc_index cut and choose index (1st dimension) - * @param num_links size of the @a links array to return - * @param[out] links array link information to return - * @return #GNUNET_SYSERR on internal error, - * #GNUNET_NO if commitment was not found - * #GNUNET_OK on success - */ - int - (*get_refresh_commit_links) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t cnc_index, - uint16_t num_links, - struct TALER_RefreshCommitLinkP *links); - - - /** - * Get all of the information from the given melt commit operation. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection to use - * @param session_hash hash to identify refresh session - * @return NULL if the @a session_hash does not correspond to any known melt - * operation - */ - struct TALER_MINTDB_MeltCommitment * - (*get_melt_commitment) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash); - - - /** - * Free information about a melt commitment. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param mc melt commitment data to free - */ - void - (*free_melt_commitment) (void *cls, - struct TALER_MINTDB_MeltCommitment *mc); - - - /** - * Insert signature of a new coin generated during refresh into - * the database indexed by the refresh session and the index - * of the coin. This data is later used should an old coin - * be used to try to obtain the private keys during "/refresh/link". - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param session_hash hash to identify refresh session - * @param newcoin_index coin index - * @param ev_sig coin signature - * @return #GNUNET_OK on success - */ - int - (*insert_refresh_out) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash, - uint16_t newcoin_index, - const struct TALER_DenominationSignature *ev_sig); - - - /** - * Obtain the link data of a coin, that is the encrypted link - * information, the denomination keys and the signatures. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param session_hash session to get linkage data for - * @return all known link data for the session - */ - struct TALER_MINTDB_LinkDataList * - (*get_link_data_list) (void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *session_hash); - - - /** - * Free memory of the link data list. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param ldl link data list to release - */ - void - (*free_link_data_list) (void *cls, - struct TALER_MINTDB_LinkDataList *ldl); - - - /** - * Obtain shared secret and transfer public key from the public key of - * the coin. This information and the link information returned by - * @e get_link_data_list() enable the owner of an old coin to determine - * the private keys of the new coins after the melt. - * - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param coin_pub public key of the coin - * @param tdc function to call for each session the coin was melted into - * @param tdc_cls closure for @a tdc - * @return #GNUNET_OK on success, - * #GNUNET_NO on failure (not found) - * #GNUNET_SYSERR on internal failure (database issue) - */ - int - (*get_transfer) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - TALER_MINTDB_TransferDataCallback tdc, - void *tdc_cls); - - - /** - * Compile a list of all (historic) transactions performed - * with the given coin (/refresh/melt and /deposit operations). - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param coin_pub coin to investigate - * @return list of transactions, NULL if coin is fresh - */ - struct TALER_MINTDB_TransactionList * - (*get_coin_transactions) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_CoinSpendPublicKeyP *coin_pub); - - - /** - * Free linked list of transactions. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param list list to free - */ - void - (*free_coin_transaction_list) (void *cls, - struct TALER_MINTDB_TransactionList *list); - - - /** - * Lookup the list of Taler transactions that was aggregated - * into a wire transfer by the respective @a raw_wtid. - * - * @param cls the @e cls of this struct with the plugin-specific state - * @param session database connection - * @param wtid the raw wire transfer identifier we used - * @param cb function to call on each transaction found - * @param cb_cls closure for @a cb - * @return #GNUNET_OK on success, #GNUNET_SYSERR on database errors, - * #GNUNET_NO if we found no results - */ - int - (*lookup_wire_transfer) (void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_WireTransferIdentifierRawP *wtid, - TALER_MINTDB_WireTransferDataCallback cb, - void *cb_cls); - - - /** - * Try to find the wire transfer details for a deposit operation. - * If we did not execute the deposit yet, return when it is supposed - * to be executed. - * - * @param cls closure - * @param session database connection - * @param h_contract hash of the contract - * @param h_wire hash of merchant wire details - * @param coin_pub public key of deposited coin - * @param merchant_pub merchant public key - * @param transaction_id transaction identifier - * @param cb function to call with the result - * @param cb_cls closure to pass to @a cb - * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors, - * #GNUNET_NO if nothing was found - */ - int - (*wire_lookup_deposit_wtid)(void *cls, - struct TALER_MINTDB_Session *session, - const struct GNUNET_HashCode *h_contract, - const struct GNUNET_HashCode *h_wire, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - const struct TALER_MerchantPublicKeyP *merchant_pub, - uint64_t transaction_id, - TALER_MINTDB_DepositWtidCallback cb, - void *cb_cls); - - - /** - * Function called to insert aggregation information into the DB. - * - * @param cls closure - * @param session database connection - * @param wtid the raw wire transfer identifier we used - * @param merchant_pub public key of the merchant (should be same for all callbacks with the same @e cls) - * @param h_wire hash of wire transfer details of the merchant (should be same for all callbacks with the same @e cls) - * @param h_contract which contract was this payment about - * @param transaction_id merchant's transaction ID for the payment - * @param execution_time when did we execute the transaction - * @param coin_pub which public key was this payment about - * @param coin_value amount contributed by this coin in total - * @param coin_fee deposit fee charged by mint for this coin - * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors - */ - int - (*insert_aggregation_tracking)(void *cls, - struct TALER_MINTDB_Session *session, - const struct TALER_WireTransferIdentifierRawP *wtid, - const struct TALER_MerchantPublicKeyP *merchant_pub, - const struct GNUNET_HashCode *h_wire, - const struct GNUNET_HashCode *h_contract, - uint64_t transaction_id, - struct GNUNET_TIME_Absolute execution_time, - const struct TALER_CoinSpendPublicKeyP *coin_pub, - const struct TALER_Amount *coin_value, - const struct TALER_Amount *coin_fee); - - - /** - * Function called to insert wire transfer commit data into the DB. - * - * @param cls closure - * @param session database connection - * @param type type of the wire transfer (i.e. "sepa") - * @param buf buffer with wire transfer preparation data - * @param buf_size number of bytes in @a buf - * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors - */ - int - (*wire_prepare_data_insert)(void *cls, - struct TALER_MINTDB_Session *session, - const char *type, - const char *buf, - size_t buf_size); - - - /** - * Function called to mark wire transfer commit data as finished. - * - * @param cls closure - * @param session database connection - * @param rowid which entry to mark as finished - * @return #GNUNET_OK on success, #GNUNET_SYSERR on DB errors - */ - int - (*wire_prepare_data_mark_finished)(void *cls, - struct TALER_MINTDB_Session *session, - unsigned long long rowid); - - - /** - * Function called to get an unfinished wire transfer - * preparation data. Fetches at most one item. - * - * @param cls closure - * @param session database connection - * @param type type fo the wire transfer (i.e. "sepa") - * @param cb function to call for ONE unfinished item - * @param cb_cls closure for @a cb - * @return #GNUNET_OK on success, - * #GNUNET_NO if there are no entries, - * #GNUNET_SYSERR on DB errors - */ - int - (*wire_prepare_data_get)(void *cls, - struct TALER_MINTDB_Session *session, - const char *type, - TALER_MINTDB_WirePreparationCallback cb, - void *cb_cls); - - -}; - - -#endif /* _TALER_MINT_DB_H */ diff --git a/src/include/taler_signatures.h b/src/include/taler_signatures.h index 2526597ee..729bed262 100644 --- a/src/include/taler_signatures.h +++ b/src/include/taler_signatures.h @@ -54,62 +54,62 @@ #define TALER_IDLE_RESERVE_EXPIRATION_TIME GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_YEARS, 5) /*********************************************/ -/* Mint offline signatures (with master key) */ +/* Exchange offline signatures (with master key) */ /*********************************************/ /** - * Purpose for signing public keys signed by the mint master key. + * Purpose for signing public keys signed by the exchange master key. */ #define TALER_SIGNATURE_MASTER_SIGNING_KEY_VALIDITY 1024 /** - * Purpose for denomination keys signed by the mint master key. + * Purpose for denomination keys signed by the exchange master key. */ #define TALER_SIGNATURE_MASTER_DENOMINATION_KEY_VALIDITY 1025 /** - * Signature where the Mint confirms its SEPA details in + * Signature where the Exchange confirms its SEPA details in * the /wire/sepa response. */ #define TALER_SIGNATURE_MASTER_SEPA_DETAILS 1026 /*********************************************/ -/* Mint online signatures (with signing key) */ +/* Exchange online signatures (with signing key) */ /*********************************************/ /** - * Purpose for the state of a reserve, signed by the mint's signing + * Purpose for the state of a reserve, signed by the exchange's signing * key. */ -#define TALER_SIGNATURE_MINT_RESERVE_STATUS 1032 +#define TALER_SIGNATURE_EXCHANGE_RESERVE_STATUS 1032 /** - * Signature where the Mint confirms a deposit request. + * Signature where the Exchange confirms a deposit request. */ -#define TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT 1033 +#define TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT 1033 /** - * Signature where the mint (current signing key) confirms the + * Signature where the exchange (current signing key) confirms the * no-reveal index for cut-and-choose and the validity of the melted * coins. */ -#define TALER_SIGNATURE_MINT_CONFIRM_MELT 1034 +#define TALER_SIGNATURE_EXCHANGE_CONFIRM_MELT 1034 /** - * Signature where the Mint confirms the full /keys response set. + * Signature where the Exchange confirms the full /keys response set. */ -#define TALER_SIGNATURE_MINT_KEY_SET 1035 +#define TALER_SIGNATURE_EXCHANGE_KEY_SET 1035 /** - * Signature where the Mint confirms the /wire response. + * Signature where the Exchange confirms the /wire response. */ -#define TALER_SIGNATURE_MINT_WIRE_TYPES 1036 +#define TALER_SIGNATURE_EXCHANGE_WIRE_TYPES 1036 /** - * Signature where the Mint confirms the /deposit/wtid response. + * Signature where the Exchange confirms the /deposit/wtid response. */ -#define TALER_SIGNATURE_MINT_CONFIRM_WIRE 1036 +#define TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE 1036 /*********************/ @@ -118,9 +118,9 @@ /** * Signature where the auditor confirms that he is - * aware of certain denomination keys from the mint. + * aware of certain denomination keys from the exchange. */ -#define TALER_SIGNATURE_AUDITOR_MINT_KEYS 1064 +#define TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS 1064 /***********************/ @@ -176,7 +176,7 @@ /** * EdDSA test signature. */ -#define TALER_SIGNATURE_MINT_TEST_EDDSA 1303 +#define TALER_SIGNATURE_EXCHANGE_TEST_EDDSA 1303 @@ -202,7 +202,7 @@ struct TALER_WithdrawRequestPS struct TALER_ReservePublicKeyP reserve_pub; /** - * Value of the coin being minted (matching the denomination key) + * Value of the coin being exchangeed (matching the denomination key) * plus the transaction fee. We include this in what is being * signed so that we can verify a reserve's remaining total balance * without needing to access the respective denomination key @@ -211,14 +211,14 @@ struct TALER_WithdrawRequestPS struct TALER_AmountNBO amount_with_fee; /** - * Withdrawl fee charged by the mint. This must match the Mint's + * Withdrawl fee charged by the exchange. This must match the Exchange's * denomination key's withdrawl fee. If the client puts in an * invalid withdrawl fee (too high or too low) that does not match - * the Mint's denomination key, the withdraw operation is invalid - * and will be rejected by the mint. The @e amount_with_fee minus + * the Exchange's denomination key, the withdraw operation is invalid + * and will be rejected by the exchange. The @e amount_with_fee minus * the @e withdraw_fee is must match the value of the generated * coin. We include this in what is being signed so that we can - * verify a mint's accounting without needing to access the + * verify a exchange's accounting without needing to access the * respective denomination key information each time. */ struct TALER_AmountNBO withdraw_fee; @@ -229,7 +229,7 @@ struct TALER_WithdrawRequestPS struct GNUNET_HashCode h_denomination_pub GNUNET_PACKED; /** - * Hash of the (blinded) message to be signed by the Mint. + * Hash of the (blinded) message to be signed by the Exchange. */ struct GNUNET_HashCode h_coin_envelope GNUNET_PACKED; }; @@ -260,12 +260,12 @@ struct TALER_DepositRequestPS /** * Time when this request was generated. Used, for example, to * assess when (roughly) the income was achieved for tax purposes. - * Note that the Mint will only check that the timestamp is not "too + * Note that the Exchange will only check that the timestamp is not "too * far" into the future (i.e. several days). The fact that the * timestamp falls within the validity period of the coin's * denomination key is irrelevant for the validity of the deposit * request, as obviously the customer and merchant could conspire to - * set any timestamp. Also, the Mint must accept very old deposit + * set any timestamp. Also, the Exchange must accept very old deposit * requests, as the merchant might have been unable to transmit the * deposit request in a timely fashion (so back-dating is not * prevented). @@ -293,17 +293,17 @@ struct TALER_DepositRequestPS /** * Amount to be deposited, including deposit fee charged by the - * mint. This is the total amount that the coin's value at the mint + * exchange. This is the total amount that the coin's value at the exchange * will be reduced by. */ struct TALER_AmountNBO amount_with_fee; /** - * Depositing fee charged by the mint. This must match the Mint's + * Depositing fee charged by the exchange. This must match the Exchange's * denomination key's depositing fee. If the client puts in an * invalid deposit fee (too high or too low) that does not match the - * Mint's denomination key, the deposit operation is invalid and - * will be rejected by the mint. The @e amount_with_fee minus the + * Exchange's denomination key, the deposit operation is invalid and + * will be rejected by the exchange. The @e amount_with_fee minus the * @e deposit_fee is the amount that will be transferred to the * account identified by @e h_wire. */ @@ -317,7 +317,7 @@ struct TALER_DepositRequestPS /** * The coin's public key. This is the value that must have been - * signed (blindly) by the Mint. The deposit request is to be + * signed (blindly) by the Exchange. The deposit request is to be * signed by the corresponding private key (using EdDSA). */ struct TALER_CoinSpendPublicKeyP coin_pub; @@ -327,13 +327,13 @@ struct TALER_DepositRequestPS /** * @brief Format used to generate the signature on a confirmation - * from the mint that a deposit request succeeded. + * from the exchange that a deposit request succeeded. */ struct TALER_DepositConfirmationPS { /** - * Purpose must be #TALER_SIGNATURE_MINT_CONFIRM_DEPOSIT. Signed - * by a `struct TALER_MintPublicKeyP` using EdDSA. + * Purpose must be #TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT. Signed + * by a `struct TALER_ExchangePublicKeyP` using EdDSA. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -362,7 +362,7 @@ struct TALER_DepositConfirmationPS * How much time does the @e merchant have to issue a refund * request? Zero if refunds are not allowed. After this time, the * coin cannot be refunded. Note that the wire transfer will not be - * performed by the mint until the refund deadline. This value + * performed by the exchange until the refund deadline. This value * is taken from the original deposit request. */ struct GNUNET_TIME_AbsoluteNBO refund_deadline; @@ -375,7 +375,7 @@ struct TALER_DepositConfirmationPS /** * The coin's public key. This is the value that must have been - * signed (blindly) by the Mint. The deposit request is to be + * signed (blindly) by the Exchange. The deposit request is to be * signed by the corresponding private key (using EdDSA). */ struct TALER_CoinSpendPublicKeyP coin_pub; @@ -417,11 +417,11 @@ struct TALER_RefreshMeltCoinAffirmationPS struct TALER_AmountNBO amount_with_fee; /** - * Melting fee charged by the mint. This must match the Mint's + * Melting fee charged by the exchange. This must match the Exchange's * denomination key's melting fee. If the client puts in an invalid - * melting fee (too high or too low) that does not match the Mint's + * melting fee (too high or too low) that does not match the Exchange's * denomination key, the melting operation is invalid and will be - * rejected by the mint. The @e amount_with_fee minus the @e + * rejected by the exchange. The @e amount_with_fee minus the @e * melt_fee is the amount that will be credited to the melting * session. */ @@ -429,7 +429,7 @@ struct TALER_RefreshMeltCoinAffirmationPS /** * The coin's public key. This is the value that must have been - * signed (blindly) by the Mint. The deposit request is to be + * signed (blindly) by the Exchange. The deposit request is to be * signed by the corresponding private key (using EdDSA). */ struct TALER_CoinSpendPublicKeyP coin_pub; @@ -437,16 +437,16 @@ struct TALER_RefreshMeltCoinAffirmationPS /** - * @brief Format of the block signed by the Mint in response to a successful - * "/refresh/melt" request. Hereby the mint affirms that all of the - * coins were successfully melted. This also commits the mint to a + * @brief Format of the block signed by the Exchange in response to a successful + * "/refresh/melt" request. Hereby the exchange affirms that all of the + * coins were successfully melted. This also commits the exchange to a * particular index to not be revealed during the refresh. */ struct TALER_RefreshMeltConfirmationPS { /** - * Purpose is #TALER_SIGNATURE_MINT_CONFIRM_MELT. Signed - * by a `struct TALER_MintPublicKeyP` using EdDSA. + * Purpose is #TALER_SIGNATURE_EXCHANGE_CONFIRM_MELT. Signed + * by a `struct TALER_ExchangePublicKeyP` using EdDSA. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -469,14 +469,14 @@ struct TALER_RefreshMeltConfirmationPS /** - * @brief Information about a signing key of the mint. Signing keys are used - * to sign mint messages other than coins, i.e. to confirm that a + * @brief Information about a signing key of the exchange. Signing keys are used + * to sign exchange messages other than coins, i.e. to confirm that a * deposit was successful or that a refresh was accepted. */ -struct TALER_MintSigningKeyValidityPS +struct TALER_ExchangeSigningKeyValidityPS { /** - * Signature over the signing key (by the master key of the mint). + * Signature over the signing key (by the master key of the exchange). * * FIXME: should be moved outside of the "PS" struct, this is ugly. * (and makes this struct different from all of the others) @@ -489,8 +489,8 @@ struct TALER_MintSigningKeyValidityPS struct GNUNET_CRYPTO_EccSignaturePurpose purpose; /** - * Master public key of the mint corresponding to @e signature. - * This is the long-term offline master key of the mint. + * Master public key of the exchange corresponding to @e signature. + * This is the long-term offline master key of the exchange. */ struct TALER_MasterPublicKeyP master_public_key; @@ -501,7 +501,7 @@ struct TALER_MintSigningKeyValidityPS /** * When does this signing key expire? Note: This is currently when - * the Mint will definitively stop using it. Signatures made with + * the Exchange will definitively stop using it. Signatures made with * the key remain valid until @e end. When checking validity periods, * clients should allow for some overlap between keys and tolerate * the use of either key during the overlap time (due to the @@ -512,31 +512,31 @@ struct TALER_MintSigningKeyValidityPS /** * When do signatures with this signing key become invalid? After * this point, these signatures cannot be used in (legal) disputes - * anymore, as the Mint is then allowed to destroy its side of the + * anymore, as the Exchange is then allowed to destroy its side of the * evidence. @e end is expected to be significantly larger than @e * expire (by a year or more). */ struct GNUNET_TIME_AbsoluteNBO end; /** - * The public online signing key that the mint will use + * The public online signing key that the exchange will use * between @e start and @e expire. */ - struct TALER_MintPublicKeyP signkey_pub; + struct TALER_ExchangePublicKeyP signkey_pub; }; /** - * @brief Signature made by the mint over the full set of keys, used - * to detect cheating mints that give out different sets to + * @brief Signature made by the exchange over the full set of keys, used + * to detect cheating exchanges that give out different sets to * different users. */ -struct TALER_MintKeySetPS +struct TALER_ExchangeKeySetPS { /** - * Purpose is #TALER_SIGNATURE_MINT_KEY_SET. Signed - * by a `struct TALER_MintPublicKeyP` using EdDSA. + * Purpose is #TALER_SIGNATURE_EXCHANGE_KEY_SET. Signed + * by a `struct TALER_ExchangePublicKeyP` using EdDSA. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -565,7 +565,7 @@ struct TALER_DenominationKeyValidityPS struct GNUNET_CRYPTO_EccSignaturePurpose purpose; /** - * The long-term offline master key of the mint that was + * The long-term offline master key of the exchange that was * used to create @e signature. */ struct TALER_MasterPublicKeyP master; @@ -576,14 +576,14 @@ struct TALER_DenominationKeyValidityPS struct GNUNET_TIME_AbsoluteNBO start; /** - * The mint will sign fresh coins between @e start and this time. + * The exchange will sign fresh coins between @e start and this time. * @e expire_withdraw will be somewhat larger than @e start to * ensure a sufficiently large anonymity set, while also allowing - * the Mint to limit the financial damage in case of a key being - * compromised. Thus, mints with low volume are expected to have a - * longer withdraw period (@e expire_withdraw - @e start) than mints + * the Exchange to limit the financial damage in case of a key being + * compromised. Thus, exchanges with low volume are expected to have a + * longer withdraw period (@e expire_withdraw - @e start) than exchanges * with high transaction volume. The period may also differ between - * types of coins. A mint may also have a few denomination keys + * types of coins. A exchange may also have a few denomination keys * with the same value with overlapping validity periods, to address * issues such as clock skew. */ @@ -592,7 +592,7 @@ struct TALER_DenominationKeyValidityPS /** * Coins signed with the denomination key must be spent or refreshed * between @e start and this expiration time. After this time, the - * mint will refuse transactions involving this key as it will + * exchange will refuse transactions involving this key as it will * "drop" the table with double-spending information (shortly after) * this time. Note that wallets should refresh coins significantly * before this time to be on the safe side. @e expire_spend must be @@ -604,7 +604,7 @@ struct TALER_DenominationKeyValidityPS /** * When do signatures with this denomination key become invalid? * After this point, these signatures cannot be used in (legal) - * disputes anymore, as the Mint is then allowed to destroy its side + * 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). */ @@ -616,19 +616,19 @@ struct TALER_DenominationKeyValidityPS struct TALER_AmountNBO value; /** - * The fee the mint charges when a coin of this type is withdrawn. + * The fee the exchange charges when a coin of this type is withdrawn. * (can be zero). */ struct TALER_AmountNBO fee_withdraw; /** - * The fee the mint charges when a coin of this type is deposited. + * The fee the exchange charges when a coin of this type is deposited. * (can be zero). */ struct TALER_AmountNBO fee_deposit; /** - * The fee the mint charges when a coin of this type is refreshed. + * The fee the exchange charges when a coin of this type is refreshed. * (can be zero). */ struct TALER_AmountNBO fee_refresh; @@ -645,18 +645,18 @@ struct TALER_DenominationKeyValidityPS /** * @brief Information signed by an auditor affirming * the master public key and the denomination keys - * of a mint. + * of a exchange. */ -struct TALER_MintKeyValidityPS +struct TALER_ExchangeKeyValidityPS { /** - * Purpose is #TALER_SIGNATURE_AUDITOR_MINT_KEYS. + * Purpose is #TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; /** - * The long-term offline master key of the mint, affirmed by the + * The long-term offline master key of the exchange, affirmed by the * auditor. */ struct TALER_MasterPublicKeyP master; @@ -667,14 +667,14 @@ struct TALER_MintKeyValidityPS struct GNUNET_TIME_AbsoluteNBO start; /** - * The mint will sign fresh coins between @e start and this time. + * The exchange will sign fresh coins between @e start and this time. * @e expire_withdraw will be somewhat larger than @e start to * ensure a sufficiently large anonymity set, while also allowing - * the Mint to limit the financial damage in case of a key being - * compromised. Thus, mints with low volume are expected to have a - * longer withdraw period (@e expire_withdraw - @e start) than mints + * the Exchange to limit the financial damage in case of a key being + * compromised. Thus, exchanges with low volume are expected to have a + * longer withdraw period (@e expire_withdraw - @e start) than exchanges * with high transaction volume. The period may also differ between - * types of coins. A mint may also have a few denomination keys + * types of coins. A exchange may also have a few denomination keys * with the same value with overlapping validity periods, to address * issues such as clock skew. */ @@ -683,7 +683,7 @@ struct TALER_MintKeyValidityPS /** * Coins signed with the denomination key must be spent or refreshed * between @e start and this expiration time. After this time, the - * mint will refuse transactions involving this key as it will + * exchange will refuse transactions involving this key as it will * "drop" the table with double-spending information (shortly after) * this time. Note that wallets should refresh coins significantly * before this time to be on the safe side. @e expire_spend must be @@ -695,7 +695,7 @@ struct TALER_MintKeyValidityPS /** * When do signatures with this denomination key become invalid? * After this point, these signatures cannot be used in (legal) - * disputes anymore, as the Mint is then allowed to destroy its side + * 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). */ @@ -707,19 +707,19 @@ struct TALER_MintKeyValidityPS struct TALER_AmountNBO value; /** - * The fee the mint charges when a coin of this type is withdrawn. + * The fee the exchange charges when a coin of this type is withdrawn. * (can be zero). */ struct TALER_AmountNBO fee_withdraw; /** - * The fee the mint charges when a coin of this type is deposited. + * The fee the exchange charges when a coin of this type is deposited. * (can be zero). */ struct TALER_AmountNBO fee_deposit; /** - * The fee the mint charges when a coin of this type is refreshed. + * The fee the exchange charges when a coin of this type is refreshed. * (can be zero). */ struct TALER_AmountNBO fee_refresh; @@ -737,7 +737,7 @@ struct TALER_MintKeyValidityPS * @brief For each (old) coin being melted, we have a `struct * RefreshCommitLinkP` that allows the user to find the shared secret * to decrypt the respective refresh links for the new coins in the - * `struct TALER_MINTDB_RefreshCommitCoin`. + * `struct TALER_EXCHANGEDB_RefreshCommitCoin`. * * Part of the construction of the refresh session's hash and * thus of what is signed there. @@ -759,8 +759,8 @@ struct TALER_RefreshCommitLinkP /** - * @brief Information signed by the mint's master - * key affirming the SEPA details for the mint. + * @brief Information signed by the exchange's master + * key affirming the SEPA details for the exchange. */ struct TALER_MasterWireSepaDetailsPS { @@ -780,19 +780,19 @@ struct TALER_MasterWireSepaDetailsPS /** - * @brief Information signed by a mint's online signing key affirming - * the wire formats supported by the mint. + * @brief Information signed by a exchange's online signing key affirming + * the wire formats supported by the exchange. */ -struct TALER_MintWireSupportMethodsPS +struct TALER_ExchangeWireSupportMethodsPS { /** - * Purpose is #TALER_SIGNATURE_MINT_WIRE_TYPES. + * Purpose is #TALER_SIGNATURE_EXCHANGE_WIRE_TYPES. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; /** - * Hash over the various wire formats supported by this mint + * Hash over the various wire formats supported by this exchange * (all as 0-terminated strings). */ struct GNUNET_HashCode h_wire_types GNUNET_PACKED; @@ -841,7 +841,7 @@ struct TALER_DepositTrackPS /** * The coin's public key. This is the value that must have been - * signed (blindly) by the Mint. + * signed (blindly) by the Exchange. */ struct TALER_CoinSpendPublicKeyP coin_pub; @@ -896,14 +896,14 @@ struct TALER_ContractPS /** - * Details affirmed by the mint about a wire transfer the mint + * Details affirmed by the exchange about a wire transfer the exchange * claims to have done with respect to a deposit operation. */ struct TALER_ConfirmWirePS { /** * Purpose header for the signature over the contract with - * purpose #TALER_SIGNATURE_MINT_CONFIRM_WIRE. + * purpose #TALER_SIGNATURE_EXCHANGE_CONFIRM_WIRE. */ struct GNUNET_CRYPTO_EccSignaturePurpose purpose; @@ -924,7 +924,7 @@ struct TALER_ConfirmWirePS /** * The coin's public key. This is the value that must have been - * signed (blindly) by the Mint. + * signed (blindly) by the Exchange. */ struct TALER_CoinSpendPublicKeyP coin_pub; @@ -941,7 +941,7 @@ struct TALER_ConfirmWirePS uint64_t transaction_id GNUNET_PACKED; /** - * When did the mint execute this transfer? Note that the + * When did the exchange execute this transfer? Note that the * timestamp may not be exactly the same on the wire, i.e. * because the wire has a different timezone or resolution. */ -- cgit v1.2.3