diff options
Diffstat (limited to 'src/include/taler_auditor_service.h')
| -rw-r--r-- | src/include/taler_auditor_service.h | 210 |
1 files changed, 100 insertions, 110 deletions
diff --git a/src/include/taler_auditor_service.h b/src/include/taler_auditor_service.h index 30d18e6e9..36ea781b1 100644 --- a/src/include/taler_auditor_service.h +++ b/src/include/taler_auditor_service.h @@ -1,6 +1,6 @@ /* This file is part of TALER - Copyright (C) 2014-2021 Taler Systems SA + Copyright (C) 2014-2023 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -16,6 +16,8 @@ /** * @file include/taler_auditor_service.h * @brief C interface of libtalerauditor, a C library to use auditor's HTTP API + * This library is not thread-safe, all APIs must only be used from a single thread. + * This library calls abort() if it runs out of memory. Be aware of these limitations. * @author Sree Harsha Totakura <sreeharsha@totakura.in> * @author Christian Grothoff */ @@ -28,12 +30,12 @@ #include <gnunet/gnunet_curl_lib.h> -/* ********************* /version *********************** */ +/* ********************* /config *********************** */ /** - * @brief Information we get from the auditor about auditors. + * @brief Information we get from the auditor about itself. */ -struct TALER_AUDITOR_VersionInformation +struct TALER_AUDITOR_ConfigInformation { /** * Public key of the auditing institution. Wallets and merchants @@ -44,6 +46,11 @@ struct TALER_AUDITOR_VersionInformation struct TALER_AuditorPublicKeyP auditor_pub; /** + * Master public key of the audited exchange. + */ + struct TALER_MasterPublicKeyP exchange_master_public_key; + + /** * Supported Taler protocol version by the auditor. * String in the format current:revision:age using the * semantics of GNU libtool. See @@ -147,56 +154,90 @@ struct TALER_AUDITOR_HttpResponse /** + * Response to /config request. + */ +struct TALER_AUDITOR_ConfigResponse +{ + /** + * HTTP response. + */ + struct TALER_AUDITOR_HttpResponse hr; + + /** + * Details depending on HTTP status. + */ + union + { + + /** + * Details for #MHD_HTTP_OK. + */ + struct + { + + /** + * Protocol compatibility evaluation. + */ + enum TALER_AUDITOR_VersionCompatibility compat; + + /** + * Config data returned by /config. + */ + struct TALER_AUDITOR_ConfigInformation vi; + + } ok; + + } details; + +}; + + +/** * Function called with information about the auditor. * * @param cls closure - * @param hr HTTP response data - * @param vi basic information about the auditor - * @param compat protocol compatibility information + * @param vr response data */ typedef void -(*TALER_AUDITOR_VersionCallback) ( +(*TALER_AUDITOR_ConfigCallback) ( void *cls, - const struct TALER_AUDITOR_HttpResponse *hr, - const struct TALER_AUDITOR_VersionInformation *vi, - enum TALER_AUDITOR_VersionCompatibility compat); + const struct TALER_AUDITOR_ConfigResponse *vr); /** * @brief Handle to the auditor. This is where we interact with * a particular auditor and keep the per-auditor information. */ -struct TALER_AUDITOR_Handle; +struct TALER_AUDITOR_GetConfigHandle; /** - * Initialise a connection to the auditor. Will connect to the + * Obtain meta data about an auditor. Will connect to the * auditor and obtain information about the auditor's master public * key and the auditor's auditor. The respective information will - * be passed to the @a version_cb once available, and all future - * interactions with the auditor will be checked to be signed - * (where appropriate) by the respective master key. + * be passed to the @a config_cb once available. * - * @param ctx the context + * @param ctx the context for CURL requests * @param url HTTP base URL for the auditor - * @param version_cb function to call with the auditor's version information - * @param version_cb_cls closure for @a version_cb + * @param config_cb function to call with the auditor's config information + * @param config_cb_cls closure for @a config_cb * @return the auditor handle; NULL upon error */ -struct TALER_AUDITOR_Handle * -TALER_AUDITOR_connect (struct GNUNET_CURL_Context *ctx, - const char *url, - TALER_AUDITOR_VersionCallback version_cb, - void *version_cb_cls); +struct TALER_AUDITOR_GetConfigHandle * +TALER_AUDITOR_get_config (struct GNUNET_CURL_Context *ctx, + const char *url, + TALER_AUDITOR_ConfigCallback config_cb, + void *config_cb_cls); /** - * Disconnect from the auditor. + * Cancel auditor config request. * - * @param auditor the auditor handle + * @param[in] auditor the auditor handle */ void -TALER_AUDITOR_disconnect (struct TALER_AUDITOR_Handle *auditor); +TALER_AUDITOR_get_config_cancel ( + struct TALER_AUDITOR_GetConfigHandle *auditor); /** @@ -206,16 +247,28 @@ struct TALER_AUDITOR_DepositConfirmationHandle; /** + * Response to /deposit-confirmation request. + */ +struct TALER_AUDITOR_DepositConfirmationResponse +{ + /** + * HTTP response. + */ + struct TALER_AUDITOR_HttpResponse hr; +}; + + +/** * Signature of functions called with the result from our call to the * auditor's /deposit-confirmation handler. * * @param cls closure - * @param hr HTTP response data + * @param dcr response data */ typedef void (*TALER_AUDITOR_DepositConfirmationResultCallback)( void *cls, - const struct TALER_AUDITOR_HttpResponse *hr); + const struct TALER_AUDITOR_DepositConfirmationResponse *dcr); /** @@ -225,21 +278,23 @@ typedef void * that the response is well-formed. If the auditor's reply is not * well-formed, we return an HTTP status code of zero to @a cb. * - * We also verify that the @a exchange_sig is valid for this deposit-confirmation - * request, and that the @a master_sig is a valid signature for @a - * exchange_pub. Also, the @a auditor must be ready to operate (i.e. have - * finished processing the /version reply). If either check fails, we do - * NOT initiate the transaction with the auditor and instead return NULL. + * We also verify that the @a exchange_sig is valid for this + * deposit-confirmation request, and that the @a master_sig is a valid + * signature for @a exchange_pub. If the check fails, we do NOT initiate the + * transaction with the auditor and instead return NULL. * - * @param auditor the auditor handle; the auditor must be ready to operate + * @param ctx the context for CURL requests + * @param url HTTP base URL for the auditor * @param h_wire hash of merchant wire details - * @param h_extensions hash over the extensions, if any + * @param h_policy hash over the policy, if any * @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the auditor) * @param exchange_timestamp timestamp when the contract was finalized, must not be too far in the future * @param wire_deadline date until which the exchange should wire the funds * @param refund_deadline date until which the merchant can issue a refund to the customer via the auditor (can be zero if refunds are not allowed); must not be after the @a wire_deadline - * @param amount_without_fee the amount confirmed to be wired by the exchange to the merchant - * @param coin_pub coin’s public key + * @param total_without_fee the amount confirmed to be wired by the exchange to the merchant + * @param num_coins number of coins involved in the batch deposit + * @param coin_pubs array of the coin’s public keys + * @param coin_sigs array of the original deposit signatures of the coins in the batch * @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests) * @param exchange_sig the signature made with purpose #TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT * @param exchange_pub the public key of the exchange that matches @a exchange_sig @@ -255,15 +310,18 @@ typedef void */ struct TALER_AUDITOR_DepositConfirmationHandle * TALER_AUDITOR_deposit_confirmation ( - struct TALER_AUDITOR_Handle *auditor, + struct GNUNET_CURL_Context *ctx, + const char *url, const struct TALER_MerchantWireHashP *h_wire, - const struct TALER_ExtensionContractHashP *h_extensions, + const struct TALER_ExtensionPolicyHashP *h_policy, const struct TALER_PrivateContractHashP *h_contract_terms, struct GNUNET_TIME_Timestamp exchange_timestamp, struct GNUNET_TIME_Timestamp wire_deadline, struct GNUNET_TIME_Timestamp refund_deadline, - const struct TALER_Amount *amount_without_fee, - const struct TALER_CoinSpendPublicKeyP *coin_pub, + const struct TALER_Amount *total_without_fee, + unsigned int num_coins, + const struct TALER_CoinSpendPublicKeyP *coin_pubs[static num_coins], + const struct TALER_CoinSpendSignatureP *coin_sigs[static num_coins], const struct TALER_MerchantPublicKeyP *merchant_pub, const struct TALER_ExchangePublicKeyP *exchange_pub, const struct TALER_ExchangeSignatureP *exchange_sig, @@ -287,72 +345,4 @@ TALER_AUDITOR_deposit_confirmation_cancel ( struct TALER_AUDITOR_DepositConfirmationHandle *deposit_confirmation); -/** - * Handle for /exchanges API returned by - * #TALER_AUDITOR_list_exchanges() so that the operation can be - * cancelled with #TALER_AUDITOR_list_exchanges_cancel() - */ -struct TALER_AUDITOR_ListExchangesHandle; - - -/** - * Information about an exchange kept by the auditor. - */ -struct TALER_AUDITOR_ExchangeInfo -{ - /** - * Master public key of the exchange. - */ - struct TALER_MasterPublicKeyP master_pub; - - /** - * Base URL of the exchange's API. - */ - const char *exchange_url; -}; - - -/** - * Function called with the result from /exchanges. - * - * @param cls closure - * @param hr HTTP response data - * @param num_exchanges length of array at @a ei - * @param ei information about exchanges returned by the auditor - */ -typedef void -(*TALER_AUDITOR_ListExchangesResultCallback)( - void *cls, - const struct TALER_AUDITOR_HttpResponse *hr, - unsigned int num_exchanges, - const struct TALER_AUDITOR_ExchangeInfo *ei); - -/** - * Submit an /exchanges request to the auditor and get the - * auditor's response. If the auditor's reply is not - * well-formed, we return an HTTP status code of zero to @a cb. - * - * @param auditor the auditor handle; the auditor must be ready to operate - * @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_AUDITOR_ListExchangesHandle * -TALER_AUDITOR_list_exchanges (struct TALER_AUDITOR_Handle *auditor, - TALER_AUDITOR_ListExchangesResultCallback cb, - void *cb_cls); - - -/** - * Cancel a list exchanges request. This function cannot be used - * on a request handle if a response is already served for it. - * - * @param leh the list exchanges request handle - */ -void -TALER_AUDITOR_list_exchanges_cancel ( - struct TALER_AUDITOR_ListExchangesHandle *leh); - - #endif /* _TALER_AUDITOR_SERVICE_H */ |