diff options
Diffstat (limited to 'src/include')
| -rw-r--r-- | src/include/Makefile.am | 4 | ||||
| -rw-r--r-- | src/include/taler_amount_lib.h | 2 | ||||
| -rw-r--r-- | src/include/taler_bank_service.h | 161 | ||||
| -rw-r--r-- | src/include/taler_crypto_lib.h | 57 | ||||
| -rw-r--r-- | src/include/taler_json_lib.h | 2 | ||||
| -rw-r--r-- | src/include/taler_mint_service.h | 159 | ||||
| -rw-r--r-- | src/include/taler_mintdb_lib.h | 2 | ||||
| -rw-r--r-- | src/include/taler_mintdb_plugin.h | 270 | ||||
| -rw-r--r-- | src/include/taler_pq_lib.h | 14 | ||||
| -rw-r--r-- | src/include/taler_signatures.h | 93 | ||||
| -rw-r--r-- | src/include/taler_util.h | 2 | ||||
| -rw-r--r-- | src/include/taler_util_wallet.h | 2 | ||||
| -rw-r--r-- | src/include/taler_wire_lib.h | 48 | ||||
| -rw-r--r-- | src/include/taler_wire_plugin.h | 180 |
14 files changed, 949 insertions, 47 deletions
diff --git a/src/include/Makefile.am b/src/include/Makefile.am index bfdcbe7ca..4d7ae3cb2 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am @@ -20,7 +20,9 @@ talerinclude_HEADERS = \ taler_mintdb_lib.h \ taler_mintdb_plugin.h \ taler_pq_lib.h \ - taler_signatures.h + taler_signatures.h \ + taler_wire_lib.h \ + taler_wire_plugin.h endif diff --git a/src/include/taler_amount_lib.h b/src/include/taler_amount_lib.h index 8661ed913..094b96f7f 100644 --- a/src/include/taler_amount_lib.h +++ b/src/include/taler_amount_lib.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 diff --git a/src/include/taler_bank_service.h b/src/include/taler_bank_service.h new file mode 100644 index 000000000..a4f33fc97 --- /dev/null +++ b/src/include/taler_bank_service.h @@ -0,0 +1,161 @@ +/* + This file is part of TALER + Copyright (C) 2015, 2016 GNUnet e.V. + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 3, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, If not, see <http://www.gnu.org/licenses/> +*/ +/** + * @file include/taler_bank_service.h + * @brief C interface of libtalerbank, a C library to use the Taler bank's HTTP API + * This is currently ONLY used to provide the "test" wire transfer protocol. + * @author Christian Grothoff + */ +#ifndef _TALER_BANK_SERVICE_H +#define _TALER_BANK_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_BANK_Context; + + +/** + * Initialise a context. A context should be used for each thread and should + * not be shared among multiple threads. + * + * @param url HTTP base URL for the bank + * @return the context, NULL on error (failure to initialize) + */ +struct TALER_BANK_Context * +TALER_BANK_init (const char *url); + + +/** + * Obtain the information for a select() call to wait until + * #TALER_BANK_perform() is ready again. Note that calling + * any other TALER_BANK-API may also imply that the library + * is again ready for #TALER_BANK_perform(). + * + * Basically, a client should use this API to prepare for select(), + * then block on select(), then call #TALER_BANK_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_BANK_perform(). + */ +void +TALER_BANK_get_select_info (struct TALER_BANK_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_BANK_perform (struct TALER_BANK_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_BANK_fini (struct TALER_BANK_Context *ctx); + + +/* ********************* /admin/add/incoming *********************** */ + + +/** + * @brief A /admin/add/incoming Handle + */ +struct TALER_BANK_AdminAddIncomingHandle; + + +/** + * Callbacks of this type are used to serve the result of submitting + * information about an incoming transaction to a bank. + * + * @param cls closure + * @param http_status HTTP response code, #MHD_HTTP_OK (200) for successful status request + * 0 if the bank's reply is bogus (fails to follow the protocol) + */ +typedef void +(*TALER_BANK_AdminAddIncomingResultCallback) (void *cls, + unsigned int http_status); + + +/** + * Notify the bank 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 bank clients, but only + * to the operators of the bank. + * + * @param bank the bank handle; the bank 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 account_no account number (53 bits at most) + * @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_BANK_AdminAddIncomingHandle * +TALER_BANK_admin_add_incoming (struct TALER_BANK_Context *bank, + const struct TALER_WireTransferIdentifierRawP *wtid, + const struct TALER_Amount *amount, + uint64_t account_no, + TALER_BANK_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_BANK_admin_add_incoming_cancel (struct TALER_BANK_AdminAddIncomingHandle *aai); + +#endif /* _TALER_BANK_SERVICE_H */ diff --git a/src/include/taler_crypto_lib.h b/src/include/taler_crypto_lib.h index 16240e5a3..6056270fa 100644 --- a/src/include/taler_crypto_lib.h +++ b/src/include/taler_crypto_lib.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 @@ -428,6 +428,61 @@ struct TALER_RefreshLinkDecrypted }; +/** + * Length of the raw value in the Taler wire transfer identifier + * (in binary representation). + */ +#define TALER_WIRE_TRANSFER_IDENTIFIER_LEN 32 + +/** + * #TALER_WIRE_TRANSFER_IDENTIFIER_LEN as a string. + */ +#define TALER_WIRE_TRANSFER_IDENTIFIER_LEN_STR "32" + +/** + * Raw value of a wire transfer subjects, without the checksum. + */ +struct TALER_WireTransferIdentifierRawP +{ + + /** + * Raw value. Note that typical payment systems (SEPA, ACH) support + * at least two lines of 27 ASCII characters to encode a transaction + * subject or "details", for a total of 54 characters. (The payment + * system protocols often support more lines, but the forms presented + * to customers are usually limited to 54 characters.) + * + * With a Base32-encoding of 5 bit per character, this gives us 270 + * bits or (rounded down) 33 bytes. So we use the first 32 bytes to + * encode the actual value (i.e. a 256-bit / 32-byte public key or + * a hash code), and the last byte for a minimalistic checksum. + */ + uint8_t raw[TALER_WIRE_TRANSFER_IDENTIFIER_LEN]; +}; + + +/** + * 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 + * transfer when needed. + */ +struct TALER_WireTransferIdentifierP +{ + + /** + * Raw value. + */ + struct TALER_WireTransferIdentifierRawP raw; + + /** + * Checksum using CRC8 over the @e raw data. + */ + uint8_t crc8; +}; + + GNUNET_NETWORK_STRUCT_END diff --git a/src/include/taler_json_lib.h b/src/include/taler_json_lib.h index 8bdcf2709..d9fa05188 100644 --- a/src/include/taler_json_lib.h +++ b/src/include/taler_json_lib.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 diff --git a/src/include/taler_mint_service.h b/src/include/taler_mint_service.h index 78650edfe..1502edfbc 100644 --- a/src/include/taler_mint_service.h +++ b/src/include/taler_mint_service.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 @@ -1059,5 +1059,162 @@ 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 index 7dfef8dc5..70e314d9a 100644 --- a/src/include/taler_mintdb_lib.h +++ b/src/include/taler_mintdb_lib.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 diff --git a/src/include/taler_mintdb_plugin.h b/src/include/taler_mintdb_plugin.h index d9a1c6c85..d2cc3d76e 100644 --- a/src/include/taler_mintdb_plugin.h +++ b/src/include/taler_mintdb_plugin.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 @@ -530,20 +530,24 @@ struct TALER_MINTDB_Session; * corresponding wire transaction. * * @param cls closure - * @param id transaction ID (used as future `min_id` to avoid - * iterating over transactions more than once) + * @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 + * @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, - uint64_t id, + 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, @@ -570,21 +574,67 @@ typedef void /** * Function called with the results of the lookup of the - * wire transfer identifier information. - * + * wire transfer identifier information. Only called if + * we are at least aware of the transaction existing. + * * @param cls closure - * @param wtid base32-encoded wire transfer identifier, NULL + * @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); - * #GNUNET_TIME_UNIT_FOREVER_ABS if the /deposit is unknown - * to the mint + * when we expect it to be done (if @a wtid was NULL) */ typedef void (*TALER_MINTDB_DepositWtidCallback)(void *cls, - const char *wtid, + 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 + * @param transfer_value total amount of the wire transfer + */ +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, + const struct TALER_Amount *transfer_value); + + +/** + * 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. @@ -848,27 +898,78 @@ struct TALER_MINTDB_Plugin /** - * Obtain information about deposits. Iterates over all deposits - * above a certain ID. Use a @a min_id of 0 to start at the beginning. - * This operation is executed in its own transaction in transaction - * mode "REPEATABLE READ", i.e. we should only see valid deposits. + * 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 min_id deposit to start at - * @param limit maximum number of transactions to fetch + * @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_deposits) (void *cls, - struct TALER_MINTDB_Session *session, - uint64_t min_id, - uint32_t limit, - TALER_MINTDB_DepositIterator deposit_cb, - void *deposit_cb_cls); + (*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); /** @@ -1112,10 +1213,10 @@ struct TALER_MINTDB_Plugin */ 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); + struct TALER_MINTDB_Session *session, + const struct GNUNET_HashCode *session_hash, + uint16_t newcoin_index, + const struct TALER_DenominationSignature *ev_sig); /** @@ -1195,11 +1296,32 @@ struct TALER_MINTDB_Plugin /** + * 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 @@ -1207,10 +1329,12 @@ struct TALER_MINTDB_Plugin * @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 + * @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, @@ -1219,7 +1343,91 @@ struct TALER_MINTDB_Plugin 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 /* _NEURO_MINT_DB_H */ +#endif /* _TALER_MINT_DB_H */ diff --git a/src/include/taler_pq_lib.h b/src/include/taler_pq_lib.h index 2fe66c52f..c9a9ebdc5 100644 --- a/src/include/taler_pq_lib.h +++ b/src/include/taler_pq_lib.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 @@ -156,7 +156,7 @@ struct TALER_PQ_QueryParam * @param x pointer to the query parameter to pass */ struct TALER_PQ_QueryParam -TALER_PQ_query_param_amount_nbo(const struct TALER_AmountNBO *x); +TALER_PQ_query_param_amount_nbo (const struct TALER_AmountNBO *x); /** @@ -168,7 +168,7 @@ TALER_PQ_query_param_amount_nbo(const struct TALER_AmountNBO *x); * @param x pointer to the query parameter to pass */ struct TALER_PQ_QueryParam -TALER_PQ_query_param_amount(const struct TALER_Amount *x); +TALER_PQ_query_param_amount (const struct TALER_Amount *x); /** @@ -178,7 +178,7 @@ TALER_PQ_query_param_amount(const struct TALER_Amount *x); * @param x the query parameter to pass. */ struct TALER_PQ_QueryParam -TALER_PQ_query_param_rsa_public_key(const struct GNUNET_CRYPTO_rsa_PublicKey *x); +TALER_PQ_query_param_rsa_public_key (const struct GNUNET_CRYPTO_rsa_PublicKey *x); /** @@ -188,7 +188,7 @@ TALER_PQ_query_param_rsa_public_key(const struct GNUNET_CRYPTO_rsa_PublicKey *x) * @param x the query parameter to pass */ struct TALER_PQ_QueryParam -TALER_PQ_query_param_rsa_signature(const struct GNUNET_CRYPTO_rsa_Signature *x); +TALER_PQ_query_param_rsa_signature (const struct GNUNET_CRYPTO_rsa_Signature *x); /** @@ -198,7 +198,7 @@ TALER_PQ_query_param_rsa_signature(const struct GNUNET_CRYPTO_rsa_Signature *x); * @param x pointer to the query parameter to pass */ struct TALER_PQ_QueryParam -TALER_PQ_query_param_absolute_time(const struct GNUNET_TIME_Absolute *x); +TALER_PQ_query_param_absolute_time (const struct GNUNET_TIME_Absolute *x); /** @@ -208,7 +208,7 @@ TALER_PQ_query_param_absolute_time(const struct GNUNET_TIME_Absolute *x); * @param x pointer to the query parameter to pass */ struct TALER_PQ_QueryParam -TALER_PQ_query_param_absolute_time_nbo(const struct GNUNET_TIME_AbsoluteNBO *x); +TALER_PQ_query_param_absolute_time_nbo (const struct GNUNET_TIME_AbsoluteNBO *x); /** diff --git a/src/include/taler_signatures.h b/src/include/taler_signatures.h index fb2916cff..2526597ee 100644 --- a/src/include/taler_signatures.h +++ b/src/include/taler_signatures.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 @@ -106,6 +106,11 @@ */ #define TALER_SIGNATURE_MINT_WIRE_TYPES 1036 +/** + * Signature where the Mint confirms the /deposit/wtid response. + */ +#define TALER_SIGNATURE_MINT_CONFIRM_WIRE 1036 + /*********************/ /* Wallet signatures */ @@ -855,6 +860,33 @@ struct TALER_ContractPS struct GNUNET_CRYPTO_EccSignaturePurpose purpose; /** + * Merchant-generated transaction ID to detect duplicate + * transactions, in big endian. The merchant must communicate a + * merchant-unique ID to the customer for each transaction. Note + * that different coins that are part of the same transaction can + * use the same transaction ID. The transaction ID is useful for + * later disputes, and the merchant's contract offer (@e h_contract) + * with the customer should include the offer's term and transaction + * ID signed with a key from the merchant. This field must match + * the corresponding field in the JSON contract. + */ + uint64_t transaction_id GNUNET_PACKED; + + /** + * The total amount to be paid to the merchant. Note that if deposit + * fees are higher than @e max_fee, the actual total must be higher + * to cover the additional fees. This field must match the + * corresponding field in the JSON contract. + */ + struct TALER_AmountNBO total_amount; + + /** + * The maximum fee the merchant is willing to cover. This field + * must match the corresponding field in the JSON contract. + */ + struct TALER_AmountNBO max_fee; + + /** * Hash of the JSON contract in UTF-8 including 0-termination, * using JSON_COMPACT | JSON_SORT_KEYS */ @@ -863,6 +895,65 @@ struct TALER_ContractPS }; +/** + * Details affirmed by the mint about a wire transfer the mint + * 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. + */ + struct GNUNET_CRYPTO_EccSignaturePurpose purpose; + + /** + * Hash over the wiring information of the merchant. + */ + struct GNUNET_HashCode h_wire GNUNET_PACKED; + + /** + * Hash over the contract for which this deposit is made. + */ + struct GNUNET_HashCode h_contract GNUNET_PACKED; + + /** + * Raw value (binary encoding) of the wire transfer subject. + */ + struct TALER_WireTransferIdentifierRawP wtid; + + /** + * The coin's public key. This is the value that must have been + * signed (blindly) by the Mint. + */ + struct TALER_CoinSpendPublicKeyP coin_pub; + + /** + * Merchant-generated transaction ID to detect duplicate + * transactions, in big endian. The merchant must communicate a + * merchant-unique ID to the customer for each transaction. Note + * that different coins that are part of the same transaction can + * use the same transaction ID. The transaction ID is useful for + * later disputes, and the merchant's contract offer (@e h_contract) + * with the customer should include the offer's term and transaction + * ID signed with a key from the merchant. + */ + uint64_t transaction_id GNUNET_PACKED; + + /** + * When did the mint 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. + */ + struct GNUNET_TIME_AbsoluteNBO execution_time; + + /** + * The contribution of @e coin_pub to the total transfer volume. + * This is the value of the deposit minus the fee. + */ + struct TALER_AmountNBO coin_contribution; + +}; GNUNET_NETWORK_STRUCT_END diff --git a/src/include/taler_util.h b/src/include/taler_util.h index b6dd9596a..380901812 100644 --- a/src/include/taler_util.h +++ b/src/include/taler_util.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 diff --git a/src/include/taler_util_wallet.h b/src/include/taler_util_wallet.h index 4699a469d..87efcddaa 100644 --- a/src/include/taler_util_wallet.h +++ b/src/include/taler_util_wallet.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014, 2015 Christian Grothoff (and other contributing authors) + 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 diff --git a/src/include/taler_wire_lib.h b/src/include/taler_wire_lib.h new file mode 100644 index 000000000..4b0fcbbcc --- /dev/null +++ b/src/include/taler_wire_lib.h @@ -0,0 +1,48 @@ +/* + This file is part of TALER + Copyright (C) 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 <http://www.gnu.org/licenses/> +*/ +/** + * @file include/taler_wire_lib.h + * @brief Interface for loading and unloading wire plugins + * @author Christian Grothoff <christian@grothoff.org> + */ +#ifndef TALER_WIRE_H +#define TALER_WIRE_H + +#include <gnunet/gnunet_util_lib.h> +#include "taler_wire_plugin.h" + + +/** + * Load a WIRE plugin. + * + * @param cfg configuration to use + * @param plugin_name name of the plugin to load + * @return #GNUNET_OK on success + */ +struct TALER_WIRE_Plugin * +TALER_WIRE_plugin_load (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *plugin_name); + +/** + * Unload a WIRE plugin. + * + * @param plugin the plugin to unload + */ +void +TALER_WIRE_plugin_unload (struct TALER_WIRE_Plugin *plugin); + + +#endif diff --git a/src/include/taler_wire_plugin.h b/src/include/taler_wire_plugin.h new file mode 100644 index 000000000..8fb194c57 --- /dev/null +++ b/src/include/taler_wire_plugin.h @@ -0,0 +1,180 @@ +/* + This file is part of TALER + Copyright (C) 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 <http://www.gnu.org/licenses/> +*/ +/** + * @file include/taler_wire_plugin.h + * @brief Plugin API for the handling of wire transactions + * @author Christian Grothoff + */ +#ifndef TALER_WIRE_PLUGIN_H +#define TALER_WIRE_PLUGIN_H + +#include <gnunet/gnunet_util_lib.h> +#include <jansson.h> +#include "taler_util.h" + + +/** + * Callback with prepared transaction. + * + * @param cls closure + * @param buf transaction data to persist, NULL on error + * @param buf_size number of bytes in @a buf, 0 on error + */ +typedef void +(*TALER_WIRE_PrepareTransactionCallback) (void *cls, + const char *buf, + size_t buf_size); + + +/** + * Handle returned for cancelling a preparation step. + */ +struct TALER_WIRE_PrepareHandle; + + +/** + * Handle returned for cancelling an execution step. + */ +struct TALER_WIRE_ExecuteHandle; + + +/** + * Function called with the result from the execute step. + * + * @param cls closure + * @param success #GNUNET_OK on success, #GNUNET_SYSERR on failure + * @param emsg NULL on success, otherwise an error message + */ +typedef void +(*TALER_WIRE_ConfirmationCallback)(void *cls, + int success, + const char *emsg); + + +/** + * @brief The plugin API, returned from the plugin's "init" function. + * The argument given to "init" is simply a configuration handle. + */ +struct TALER_WIRE_Plugin +{ + + /** + * Closure for all callbacks. + */ + void *cls; + + /** + * Name of the library which generated this plugin. Set by the + * plugin loader. + */ + char *library_name; + + /** + * Round amount DOWN to the amount that can be transferred via the wire + * method. For example, Taler may support 0.000001 EUR as a unit of + * payment, but SEPA only supports 0.01 EUR. This function would + * round 0.125 EUR to 0.12 EUR in this case. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param[in,out] amount amount to round down + * @return #GNUNET_OK on success, #GNUNET_NO if rounding was unnecessary, + * #GNUNET_SYSERR if the amount or currency was invalid + */ + int + (*amount_round) (void *cls, + struct TALER_Amount *amount); + + + /** + * Check if the given wire format JSON object is correctly formatted + * + * @param wire the JSON wire format object + * @return #GNUNET_YES if correctly formatted; #GNUNET_NO if not + */ + int + (*wire_validate) (const json_t *wire); + + + /** + * Prepare for exeuction of a wire transfer. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param wire valid wire account information + * @param amount amount to transfer, already rounded + * @param wtid wire transfer identifier to use + * @param ptc function to call with the prepared data to persist + * @param ptc_cls closure for @a ptc + * @return NULL on failure + */ + struct TALER_WIRE_PrepareHandle * + (*prepare_wire_transfer) (void *cls, + const json_t *wire, + const struct TALER_Amount *amount, + const struct TALER_WireTransferIdentifierRawP *wtid, + TALER_WIRE_PrepareTransactionCallback ptc, + void *ptc_cls); + + /** + * Abort preparation of a wire transfer. For example, + * because we are shutting down. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param pth preparation to cancel + */ + void + (*prepare_wire_transfer_cancel) (void *cls, + struct TALER_WIRE_PrepareHandle *pth); + + + /** + * Execute a wire transfer. + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param buf buffer with the prepared execution details + * @param buf_size number of bytes in @a buf + * @param cc function to call upon success + * @param cc_cls closure for @a cc + * @return NULL on error + */ + struct TALER_WIRE_ExecuteHandle * + (*execute_wire_transfer) (void *cls, + const char *buf, + size_t buf_size, + TALER_WIRE_ConfirmationCallback cc, + void *cc_cls); + + + /** + * Abort execution of a wire transfer. For example, because we are + * shutting down. Note that if an execution is aborted, it may or + * may not still succeed. The caller MUST run @e + * execute_wire_transfer again for the same request as soon as + * possilbe, to ensure that the request either ultimately succeeds + * or ultimately fails. Until this has been done, the transaction is + * in limbo (i.e. may or may not have been committed). + * + * @param cls the @e cls of this struct with the plugin-specific state + * @param eh execution to cancel + */ + void + (*execute_wire_transfer_cancel) (void *cls, + struct TALER_WIRE_ExecuteHandle *eh); + + +}; + + +#endif /* TALER_WIRE_PLUGIN_H */ |