common.h (6162B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2025 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/exchange/common.h 18 * @brief C interface of libtalerexchange, a C library to use exchange'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 * @author Özgür Kesim 24 */ 25 #ifndef _TALER_EXCHANGE__COMMON_H 26 #define _TALER_EXCHANGE__COMMON_H 27 28 #include <jansson.h> 29 #include <taler/taler_util.h> 30 #include <taler/taler_error_codes.h> 31 #include <gnunet/gnunet_curl_lib.h> 32 33 34 /** 35 * Maximum number of options that can be set in one set_options 36 * call. Used as a dummy for "infinite" in the varargs case. 37 */ 38 #define TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE UINT_MAX 39 40 41 /** 42 * Global options for HTTP requests made to the exchange. 43 */ 44 enum TALER_EXCHANGE_GlobalOptions 45 { 46 47 /** 48 * Use defaults. In particular, this means that HTTP/1.1 is used, as 49 * that is the conservative, best-tested option. 50 */ 51 TALER_EXCHANGE_GO_NONE = 0, 52 53 /** 54 * Force use of HTTP/1.1. As HTTP/1.1 is already the default, this 55 * flag only matters to override an otherwise given 56 * #TALER_EXCHANGE_GO_ENABLE_HTTP3. 57 */ 58 TALER_EXCHANGE_GO_FORCE_HTTP1_1 = 1, 59 60 /** 61 * Allow the use of HTTP/2 and HTTP/3. Note that HTTP/3 is only 62 * actually enabled if the libcurl we run against is deemed suitable 63 * (see #TALER_curl_set_http_version()). Ignored if 64 * #TALER_EXCHANGE_GO_FORCE_HTTP1_1 is also set. 65 */ 66 TALER_EXCHANGE_GO_ENABLE_HTTP3 = 2, 67 68 }; 69 70 71 /** 72 * Set global options for HTTP requests made with libtalerexchange. 73 * Note that this also applies the equivalent options to 74 * libtalerauditor, as libtalerexchange uses libtalerauditor to 75 * talk to the auditors of an exchange. 76 * 77 * @param go global options to use 78 */ 79 void 80 TALER_EXCHANGE_setup (enum TALER_EXCHANGE_GlobalOptions go); 81 82 83 /** 84 * Forward declaration for the exchange's set of online signing keys and 85 * denomination keys. Several endpoint headers reference this type in their 86 * function signatures; declaring it here keeps those headers self-contained 87 * when they are included early (e.g. to override a *_RESULT_CLOSURE macro). 88 * Both types are fully defined in get-keys.h. 89 */ 90 struct TALER_EXCHANGE_Keys; 91 struct TALER_EXCHANGE_DenomPublicKey; 92 93 /** 94 * Forward declaration for the input to a melt operation, defined in 95 * post-reveal-melt.h but also referenced (by pointer) from post-melt.h. 96 */ 97 struct TALER_EXCHANGE_MeltInput; 98 99 100 /** 101 * General information about the HTTP response we obtained 102 * from the exchange for a request. 103 */ 104 struct TALER_EXCHANGE_HttpResponse 105 { 106 107 /** 108 * The complete JSON reply. NULL if we failed to parse the 109 * reply (too big, invalid JSON). 110 */ 111 const json_t *reply; 112 113 /** 114 * Set to the human-readable 'hint' that is optionally 115 * provided by the exchange together with errors. NULL 116 * if no hint was provided or if there was no error. 117 */ 118 const char *hint; 119 120 /** 121 * HTTP status code for the response. 0 if the 122 * HTTP request failed and we did not get any answer, or 123 * if the answer was invalid and we set @a ec to a 124 * client-side error code. 125 */ 126 unsigned int http_status; 127 128 /** 129 * Taler error code. #TALER_EC_NONE if everything was 130 * OK. Usually set to the "code" field of an error 131 * response, but may be set to values created at the 132 * client side, for example when the response was 133 * not in JSON format or was otherwise ill-formed. 134 */ 135 enum TALER_ErrorCode ec; 136 137 }; 138 139 140 /** 141 * Information returned when a client needs to pass 142 * a KYC check before the transaction may succeed. 143 */ 144 struct TALER_EXCHANGE_KycNeededRedirect 145 { 146 147 /** 148 * Hash of the payto-URI of the account to KYC; 149 */ 150 struct TALER_NormalizedPaytoHashP h_payto; 151 152 /** 153 * Public key needed to access the KYC state of 154 * this account. All zeros if a wire transfer 155 * is required first to establish the key. 156 */ 157 union TALER_AccountPublicKeyP account_pub; 158 159 /** 160 * Legitimization requirement that the merchant should use 161 * to check for its KYC status, 0 if not known. 162 */ 163 uint64_t requirement_row; 164 165 /** 166 * Set to true if the KYC AUTH public key known to the exchange does not 167 * match the merchant public key associated with the deposit operation. 168 */ 169 bool bad_kyc_auth; 170 }; 171 172 173 /** 174 * We received an #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS response code. 175 * Parse the JSON response and initialize the @a uflr object. 176 * 177 * @param[out] uflr data structure to initialize 178 * @param j JSON response to parse 179 * @return #GNUNET_OK on success 180 */ 181 enum GNUNET_GenericReturnValue 182 TALER_EXCHANGE_parse_451 (struct TALER_EXCHANGE_KycNeededRedirect *uflr, 183 const json_t *j); 184 185 186 /** 187 * Information about a coin to be deposited into a purse or reserve. 188 */ 189 struct TALER_EXCHANGE_PurseDeposit 190 { 191 /** 192 * Age commitment data, might be NULL. 193 */ 194 const struct TALER_AgeCommitmentProof *age_commitment_proof; 195 196 /** 197 * Private key of the coin. 198 */ 199 struct TALER_CoinSpendPrivateKeyP coin_priv; 200 201 /** 202 * Signature proving the validity of the coin. 203 */ 204 struct TALER_DenominationSignature denom_sig; 205 206 /** 207 * Hash of the denomination's public key. 208 */ 209 struct TALER_DenominationHashP h_denom_pub; 210 211 /** 212 * Amount of the coin to transfer into the purse. 213 */ 214 struct TALER_Amount amount; 215 216 }; 217 218 219 #endif