taler_auditor_service.h (10854B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2023 Taler Systems SA 4 5 TALER is free software; you can redistribute it and/or modify it under the 6 terms of the GNU Affero General Public License as published by the Free Software 7 Foundation; either version 3, or (at your option) any later version. 8 9 TALER is distributed in the hope that it will be useful, but WITHOUT ANY 10 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR 11 A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. 12 13 You should have received a copy of the GNU Affero General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/taler/taler_auditor_service.h 18 * @brief C interface of libtalerauditor, a C library to use auditor's HTTP API 19 * This library is not thread-safe, all APIs must only be used from a single thread. 20 * This library calls abort() if it runs out of memory. Be aware of these limitations. 21 * @author Sree Harsha Totakura <sreeharsha@totakura.in> 22 * @author Christian Grothoff 23 */ 24 #ifndef _TALER_AUDITOR_SERVICE_H 25 #define _TALER_AUDITOR_SERVICE_H 26 27 #include <jansson.h> 28 #include <taler/taler_util.h> 29 #include <taler/taler_error_codes.h> 30 #include <gnunet/gnunet_curl_lib.h> 31 32 33 /* ********************* /config *********************** */ 34 35 /** 36 * @brief Information we get from the auditor about itself. 37 */ 38 struct TALER_AUDITOR_ConfigInformation 39 { 40 /** 41 * Public key of the auditing institution. Wallets and merchants 42 * are expected to be configured with a set of public keys of 43 * auditors that they deem acceptable. These public keys are 44 * the roots of the Taler PKI. 45 */ 46 struct TALER_AuditorPublicKeyP auditor_pub; 47 48 /** 49 * Master public key of the audited exchange. 50 */ 51 struct TALER_MasterPublicKeyP exchange_master_public_key; 52 53 /** 54 * Supported Taler protocol version by the auditor. 55 * String in the format current:revision:age using the 56 * semantics of GNU libtool. See 57 * https://www.gnu.org/software/libtool/manual/html_node/Versioning.html#Versioning 58 */ 59 const char *version; 60 61 }; 62 63 64 /** 65 * How compatible are the protocol version of the auditor and this 66 * client? The bits (1,2,4) can be used to test if the auditor's 67 * version is incompatible, older or newer respectively. 68 */ 69 enum TALER_AUDITOR_VersionCompatibility 70 { 71 72 /** 73 * The auditor runs exactly the same protocol version. 74 */ 75 TALER_AUDITOR_VC_MATCH = 0, 76 77 /** 78 * The auditor is too old or too new to be compatible with this 79 * implementation (bit) 80 */ 81 TALER_AUDITOR_VC_INCOMPATIBLE = 1, 82 83 /** 84 * The auditor is older than this implementation (bit) 85 */ 86 TALER_AUDITOR_VC_OLDER = 2, 87 88 /** 89 * The auditor is too old to be compatible with 90 * this implementation. 91 */ 92 TALER_AUDITOR_VC_INCOMPATIBLE_OUTDATED 93 = TALER_AUDITOR_VC_INCOMPATIBLE 94 | TALER_AUDITOR_VC_OLDER, 95 96 /** 97 * The auditor is more recent than this implementation (bit). 98 */ 99 TALER_AUDITOR_VC_NEWER = 4, 100 101 /** 102 * The auditor is too recent for this implementation. 103 */ 104 TALER_AUDITOR_VC_INCOMPATIBLE_NEWER 105 = TALER_AUDITOR_VC_INCOMPATIBLE 106 | TALER_AUDITOR_VC_NEWER, 107 108 /** 109 * We could not even parse the version data. 110 */ 111 TALER_AUDITOR_VC_PROTOCOL_ERROR = 8 112 113 }; 114 115 116 /** 117 * General information about the HTTP response we obtained 118 * from the auditor for a request. 119 */ 120 struct TALER_AUDITOR_HttpResponse 121 { 122 123 /** 124 * The complete JSON reply. NULL if we failed to parse the 125 * reply (too big, invalid JSON). 126 */ 127 const json_t *reply; 128 129 /** 130 * Set to the human-readable 'hint' that is optionally 131 * provided by the exchange together with errors. NULL 132 * if no hint was provided or if there was no error. 133 */ 134 const char *hint; 135 136 /** 137 * HTTP status code for the response. 0 if the 138 * HTTP request failed and we did not get any answer, or 139 * if the answer was invalid and we set @a ec to a 140 * client-side error code. 141 */ 142 unsigned int http_status; 143 144 /** 145 * Taler error code. #TALER_EC_NONE if everything was 146 * OK. Usually set to the "code" field of an error 147 * response, but may be set to values created at the 148 * client side, for example when the response was 149 * not in JSON format or was otherwise ill-formed. 150 */ 151 enum TALER_ErrorCode ec; 152 153 }; 154 155 156 /** 157 * Response to /config request. 158 */ 159 struct TALER_AUDITOR_ConfigResponse 160 { 161 /** 162 * HTTP response. 163 */ 164 struct TALER_AUDITOR_HttpResponse hr; 165 166 /** 167 * Details depending on HTTP status. 168 */ 169 union 170 { 171 172 /** 173 * Details for #MHD_HTTP_OK. 174 */ 175 struct 176 { 177 178 /** 179 * Protocol compatibility evaluation. 180 */ 181 enum TALER_AUDITOR_VersionCompatibility compat; 182 183 /** 184 * Config data returned by /config. 185 */ 186 struct TALER_AUDITOR_ConfigInformation vi; 187 188 } ok; 189 190 } details; 191 192 }; 193 194 195 /** 196 * Function called with information about the auditor. 197 * 198 * @param cls closure 199 * @param vr response data 200 */ 201 typedef void 202 (*TALER_AUDITOR_ConfigCallback) ( 203 void *cls, 204 const struct TALER_AUDITOR_ConfigResponse *vr); 205 206 207 /** 208 * @brief Handle to the auditor. This is where we interact with 209 * a particular auditor and keep the per-auditor information. 210 */ 211 struct TALER_AUDITOR_GetConfigHandle; 212 213 214 /** 215 * Obtain meta data about an auditor. Will connect to the 216 * auditor and obtain information about the auditor's master public 217 * key and the auditor's auditor. The respective information will 218 * be passed to the @a config_cb once available. 219 * 220 * @param ctx the context for CURL requests 221 * @param url HTTP base URL for the auditor 222 * @param config_cb function to call with the auditor's config information 223 * @param config_cb_cls closure for @a config_cb 224 * @return the auditor handle; NULL upon error 225 */ 226 struct TALER_AUDITOR_GetConfigHandle * 227 TALER_AUDITOR_get_config (struct GNUNET_CURL_Context *ctx, 228 const char *url, 229 TALER_AUDITOR_ConfigCallback config_cb, 230 void *config_cb_cls); 231 232 233 /** 234 * Cancel auditor config request. 235 * 236 * @param[in] auditor the auditor handle 237 */ 238 void 239 TALER_AUDITOR_get_config_cancel ( 240 struct TALER_AUDITOR_GetConfigHandle *auditor); 241 242 243 /** 244 * @brief A DepositConfirmation Handle 245 */ 246 struct TALER_AUDITOR_DepositConfirmationHandle; 247 248 249 /** 250 * Response to /deposit-confirmation request. 251 */ 252 struct TALER_AUDITOR_DepositConfirmationResponse 253 { 254 /** 255 * HTTP response. 256 */ 257 struct TALER_AUDITOR_HttpResponse hr; 258 }; 259 260 261 /** 262 * Signature of functions called with the result from our call to the 263 * auditor's /deposit-confirmation handler. 264 * 265 * @param cls closure 266 * @param dcr response data 267 */ 268 typedef void 269 (*TALER_AUDITOR_DepositConfirmationResultCallback)( 270 void *cls, 271 const struct TALER_AUDITOR_DepositConfirmationResponse *dcr); 272 273 274 /** 275 * Submit a deposit-confirmation permission to the auditor and get the 276 * auditor's response. Note that while we return the response 277 * verbatim to the caller for further processing, we do already verify 278 * that the response is well-formed. If the auditor's reply is not 279 * well-formed, we return an HTTP status code of zero to @a cb. 280 * 281 * We also verify that the @a exchange_sig is valid for this 282 * deposit-confirmation request, and that the @a master_sig is a valid 283 * signature for @a exchange_pub. If the check fails, we do NOT initiate the 284 * transaction with the auditor and instead return NULL. 285 * 286 * @param ctx the context for CURL requests 287 * @param url HTTP base URL for the auditor 288 * @param h_wire hash of merchant wire details 289 * @param h_policy hash over the policy, if any 290 * @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the auditor) 291 * @param exchange_timestamp timestamp when the contract was finalized, must not be too far in the future 292 * @param wire_deadline date until which the exchange should wire the funds 293 * @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 294 * @param total_without_fee the amount confirmed to be wired by the exchange to the merchant 295 * @param num_coins number of coins involved in the batch deposit 296 * @param coin_pubs array of the coin’s public keys 297 * @param coin_sigs array of the original deposit signatures of the coins in the batch 298 * @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests) 299 * @param exchange_sig the signature made with purpose #TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT 300 * @param exchange_pub the public key of the exchange that matches @a exchange_sig 301 * @param master_pub master public key of the exchange 302 * @param ep_start when does @a exchange_pub validity start 303 * @param ep_expire when does @a exchange_pub usage end 304 * @param ep_end when does @a exchange_pub legal validity end 305 * @param master_sig master signature affirming validity of @a exchange_pub 306 * @param cb the callback to call when a reply for this request is available 307 * @param cb_cls closure for the above callback 308 * @return a handle for this request; NULL if the inputs are invalid (i.e. 309 * signatures fail to verify). In this case, the callback is not called. 310 */ 311 struct TALER_AUDITOR_DepositConfirmationHandle * 312 TALER_AUDITOR_deposit_confirmation ( 313 struct GNUNET_CURL_Context *ctx, 314 const char *url, 315 const struct TALER_MerchantWireHashP *h_wire, 316 const struct TALER_ExtensionPolicyHashP *h_policy, 317 const struct TALER_PrivateContractHashP *h_contract_terms, 318 struct GNUNET_TIME_Timestamp exchange_timestamp, 319 struct GNUNET_TIME_Timestamp wire_deadline, 320 struct GNUNET_TIME_Timestamp refund_deadline, 321 const struct TALER_Amount *total_without_fee, 322 unsigned int num_coins, 323 const struct TALER_CoinSpendPublicKeyP *coin_pubs[static num_coins], 324 const struct TALER_CoinSpendSignatureP *coin_sigs[static num_coins], 325 const struct TALER_MerchantPublicKeyP *merchant_pub, 326 const struct TALER_ExchangePublicKeyP *exchange_pub, 327 const struct TALER_ExchangeSignatureP *exchange_sig, 328 const struct TALER_MasterPublicKeyP *master_pub, 329 struct GNUNET_TIME_Timestamp ep_start, 330 struct GNUNET_TIME_Timestamp ep_expire, 331 struct GNUNET_TIME_Timestamp ep_end, 332 const struct TALER_MasterSignatureP *master_sig, 333 TALER_AUDITOR_DepositConfirmationResultCallback cb, 334 void *cb_cls); 335 336 337 /** 338 * Cancel a deposit-confirmation permission request. This function cannot be used 339 * on a request handle if a response is already served for it. 340 * 341 * @param deposit_confirmation the deposit-confirmation permission request handle 342 */ 343 void 344 TALER_AUDITOR_deposit_confirmation_cancel ( 345 struct TALER_AUDITOR_DepositConfirmationHandle *deposit_confirmation); 346 347 348 #endif /* _TALER_AUDITOR_SERVICE_H */