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