taler_auditor_service.h (11809B)
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 * Global options for HTTP requests made to the auditor. 118 */ 119 enum TALER_AUDITOR_GlobalOptions 120 { 121 122 /** 123 * Use defaults. In particular, this means that HTTP/1.1 is used, as 124 * that is the conservative, best-tested option. 125 */ 126 TALER_AUDITOR_GO_NONE = 0, 127 128 /** 129 * Force use of HTTP/1.1. As HTTP/1.1 is already the default, this 130 * flag only matters to override an otherwise given 131 * #TALER_AUDITOR_GO_ENABLE_HTTP3. 132 */ 133 TALER_AUDITOR_GO_FORCE_HTTP1_1 = 1, 134 135 /** 136 * Allow the use of HTTP/2 and HTTP/3. Note that HTTP/3 is only 137 * actually enabled if the libcurl we run against is deemed suitable 138 * (see #TALER_curl_set_http_version()). Ignored if 139 * #TALER_AUDITOR_GO_FORCE_HTTP1_1 is also set. 140 */ 141 TALER_AUDITOR_GO_ENABLE_HTTP3 = 2, 142 143 }; 144 145 146 /** 147 * Set global options for HTTP requests made with libtalerauditor. 148 * 149 * @param go global options to use 150 */ 151 void 152 TALER_AUDITOR_setup (enum TALER_AUDITOR_GlobalOptions go); 153 154 155 /** 156 * General information about the HTTP response we obtained 157 * from the auditor for a request. 158 */ 159 struct TALER_AUDITOR_HttpResponse 160 { 161 162 /** 163 * The complete JSON reply. NULL if we failed to parse the 164 * reply (too big, invalid JSON). 165 */ 166 const json_t *reply; 167 168 /** 169 * Set to the human-readable 'hint' that is optionally 170 * provided by the exchange together with errors. NULL 171 * if no hint was provided or if there was no error. 172 */ 173 const char *hint; 174 175 /** 176 * HTTP status code for the response. 0 if the 177 * HTTP request failed and we did not get any answer, or 178 * if the answer was invalid and we set @a ec to a 179 * client-side error code. 180 */ 181 unsigned int http_status; 182 183 /** 184 * Taler error code. #TALER_EC_NONE if everything was 185 * OK. Usually set to the "code" field of an error 186 * response, but may be set to values created at the 187 * client side, for example when the response was 188 * not in JSON format or was otherwise ill-formed. 189 */ 190 enum TALER_ErrorCode ec; 191 192 }; 193 194 195 /** 196 * Response to /config request. 197 */ 198 struct TALER_AUDITOR_ConfigResponse 199 { 200 /** 201 * HTTP response. 202 */ 203 struct TALER_AUDITOR_HttpResponse hr; 204 205 /** 206 * Details depending on HTTP status. 207 */ 208 union 209 { 210 211 /** 212 * Details for #MHD_HTTP_OK. 213 */ 214 struct 215 { 216 217 /** 218 * Protocol compatibility evaluation. 219 */ 220 enum TALER_AUDITOR_VersionCompatibility compat; 221 222 /** 223 * Config data returned by /config. 224 */ 225 struct TALER_AUDITOR_ConfigInformation vi; 226 227 } ok; 228 229 } details; 230 231 }; 232 233 234 /** 235 * Function called with information about the auditor. 236 * 237 * @param cls closure 238 * @param vr response data 239 */ 240 typedef void 241 (*TALER_AUDITOR_ConfigCallback) ( 242 void *cls, 243 const struct TALER_AUDITOR_ConfigResponse *vr); 244 245 246 /** 247 * @brief Handle to the auditor. This is where we interact with 248 * a particular auditor and keep the per-auditor information. 249 */ 250 struct TALER_AUDITOR_GetConfigHandle; 251 252 253 /** 254 * Obtain meta data about an auditor. Will connect to the 255 * auditor and obtain information about the auditor's master public 256 * key and the auditor's auditor. The respective information will 257 * be passed to the @a config_cb once available. 258 * 259 * @param ctx the context for CURL requests 260 * @param url HTTP base URL for the auditor 261 * @param config_cb function to call with the auditor's config information 262 * @param config_cb_cls closure for @a config_cb 263 * @return the auditor handle; NULL upon error 264 */ 265 struct TALER_AUDITOR_GetConfigHandle * 266 TALER_AUDITOR_get_config (struct GNUNET_CURL_Context *ctx, 267 const char *url, 268 TALER_AUDITOR_ConfigCallback config_cb, 269 void *config_cb_cls); 270 271 272 /** 273 * Cancel auditor config request. 274 * 275 * @param[in] auditor the auditor handle 276 */ 277 void 278 TALER_AUDITOR_get_config_cancel ( 279 struct TALER_AUDITOR_GetConfigHandle *auditor); 280 281 282 /** 283 * @brief A DepositConfirmation Handle 284 */ 285 struct TALER_AUDITOR_DepositConfirmationHandle; 286 287 288 /** 289 * Response to /deposit-confirmation request. 290 */ 291 struct TALER_AUDITOR_DepositConfirmationResponse 292 { 293 /** 294 * HTTP response. 295 */ 296 struct TALER_AUDITOR_HttpResponse hr; 297 }; 298 299 300 /** 301 * Signature of functions called with the result from our call to the 302 * auditor's /deposit-confirmation handler. 303 * 304 * @param cls closure 305 * @param dcr response data 306 */ 307 typedef void 308 (*TALER_AUDITOR_DepositConfirmationResultCallback)( 309 void *cls, 310 const struct TALER_AUDITOR_DepositConfirmationResponse *dcr); 311 312 313 /** 314 * Submit a deposit-confirmation permission to the auditor and get the 315 * auditor's response. Note that while we return the response 316 * verbatim to the caller for further processing, we do already verify 317 * that the response is well-formed. If the auditor's reply is not 318 * well-formed, we return an HTTP status code of zero to @a cb. 319 * 320 * We also verify that the @a exchange_sig is valid for this 321 * deposit-confirmation request, and that the @a master_sig is a valid 322 * signature for @a exchange_pub. If the check fails, we do NOT initiate the 323 * transaction with the auditor and instead return NULL. 324 * 325 * @param ctx the context for CURL requests 326 * @param url HTTP base URL for the auditor 327 * @param h_wire hash of merchant wire details 328 * @param h_policy hash over the policy, if any 329 * @param h_contract_terms hash of the contact of the merchant with the customer (further details are never disclosed to the auditor) 330 * @param exchange_timestamp timestamp when the contract was finalized, must not be too far in the future 331 * @param wire_deadline date until which the exchange should wire the funds 332 * @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 333 * @param total_without_fee the amount confirmed to be wired by the exchange to the merchant 334 * @param num_coins number of coins involved in the batch deposit 335 * @param coin_pubs array of the coin’s public keys 336 * @param coin_sigs array of the original deposit signatures of the coins in the batch 337 * @param merchant_pub the public key of the merchant (used to identify the merchant for refund requests) 338 * @param exchange_sig the signature made with purpose #TALER_SIGNATURE_EXCHANGE_CONFIRM_DEPOSIT 339 * @param exchange_pub the public key of the exchange that matches @a exchange_sig 340 * @param master_pub master public key of the exchange 341 * @param ep_start when does @a exchange_pub validity start 342 * @param ep_expire when does @a exchange_pub usage end 343 * @param ep_end when does @a exchange_pub legal validity end 344 * @param master_sig master signature affirming validity of @a exchange_pub 345 * @param cb the callback to call when a reply for this request is available 346 * @param cb_cls closure for the above callback 347 * @return a handle for this request; NULL if the inputs are invalid (i.e. 348 * signatures fail to verify). In this case, the callback is not called. 349 */ 350 struct TALER_AUDITOR_DepositConfirmationHandle * 351 TALER_AUDITOR_deposit_confirmation ( 352 struct GNUNET_CURL_Context *ctx, 353 const char *url, 354 const struct TALER_MerchantWireHashP *h_wire, 355 const struct TALER_ExtensionPolicyHashP *h_policy, 356 const struct TALER_PrivateContractHashP *h_contract_terms, 357 struct GNUNET_TIME_Timestamp exchange_timestamp, 358 struct GNUNET_TIME_Timestamp wire_deadline, 359 struct GNUNET_TIME_Timestamp refund_deadline, 360 const struct TALER_Amount *total_without_fee, 361 unsigned int num_coins, 362 const struct TALER_CoinSpendPublicKeyP *coin_pubs[static num_coins], 363 const struct TALER_CoinSpendSignatureP *coin_sigs[static num_coins], 364 const struct TALER_MerchantPublicKeyP *merchant_pub, 365 const struct TALER_ExchangePublicKeyP *exchange_pub, 366 const struct TALER_ExchangeSignatureP *exchange_sig, 367 const struct TALER_MasterPublicKeyP *master_pub, 368 struct GNUNET_TIME_Timestamp ep_start, 369 struct GNUNET_TIME_Timestamp ep_expire, 370 struct GNUNET_TIME_Timestamp ep_end, 371 const struct TALER_MasterSignatureP *master_sig, 372 TALER_AUDITOR_DepositConfirmationResultCallback cb, 373 void *cb_cls); 374 375 376 /** 377 * Cancel a deposit-confirmation permission request. This function cannot be used 378 * on a request handle if a response is already served for it. 379 * 380 * @param deposit_confirmation the deposit-confirmation permission request handle 381 */ 382 void 383 TALER_AUDITOR_deposit_confirmation_cancel ( 384 struct TALER_AUDITOR_DepositConfirmationHandle *deposit_confirmation); 385 386 387 #endif /* _TALER_AUDITOR_SERVICE_H */