taler-merchant-httpd_exchanges.h (7786B)
1 /* 2 This file is part of TALER 3 (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 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 General Public License for more details. 12 13 You should have received a copy of the GNU General Public License along with 14 TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file taler-merchant-httpd_get-exchanges.h 18 * @brief logic this HTTPD keeps for each exchange we interact with 19 * @author Marcello Stanisci 20 * @author Christian Grothoff 21 */ 22 #ifndef TALER_MERCHANT_HTTPD_EXCHANGES_H 23 #define TALER_MERCHANT_HTTPD_EXCHANGES_H 24 25 #include <jansson.h> 26 #include <gnunet/gnunet_util_lib.h> 27 #include <curl/curl.h> 28 #include <taler/taler_util.h> 29 #include <taler/taler_exchange_service.h> 30 #include "taler-merchant-httpd.h" 31 32 33 /** 34 * Exchange 35 */ 36 struct TMH_Exchange; 37 38 39 /** 40 * Parses "trusted" exchanges listed in the configuration. 41 * 42 * @param cfg the configuration 43 * @return number of trusted exchanges on success; #GNUNET_SYSERR upon error in 44 * parsing. 45 */ 46 enum GNUNET_GenericReturnValue 47 TMH_EXCHANGES_init (const struct GNUNET_CONFIGURATION_Handle *cfg); 48 49 50 /** 51 * Function called to shutdown the exchanges subsystem. 52 */ 53 void 54 TMH_EXCHANGES_done (void); 55 56 57 /** 58 * Function called with the result of a #TMH_EXCHANGES_keys4exchange() 59 * operation. 60 * 61 * @param cls closure 62 * @param keys the keys of the exchange 63 * @param exchange representation of the exchange 64 */ 65 typedef void 66 (*TMH_EXCHANGES_Find2Continuation)( 67 void *cls, 68 struct TALER_EXCHANGE_Keys *keys, 69 struct TMH_Exchange *exchange); 70 71 72 /** 73 * Information we keep for a pending #MMH_EXCHANGES_keys4exchange() operation. 74 */ 75 struct TMH_EXCHANGES_KeysOperation; 76 77 78 /** 79 * Check if we trust the exchange at @a exchange_url. 80 * 81 * @param exchange_url exchange base url to check 82 * @return true if we trust that exchange (assuming the master 83 * public key matches) 84 */ 85 bool 86 TMH_EXCHANGES_check_trusted ( 87 const char *exchange_url); 88 89 90 /** 91 * Get /keys of the given @a exchange. 92 * 93 * @param exchange URL of the exchange we would like to talk to 94 * @param force_download force /keys download now 95 * @param fc function to call with the handles for the exchange 96 * @param fc_cls closure for @a fc 97 */ 98 struct TMH_EXCHANGES_KeysOperation * 99 TMH_EXCHANGES_keys4exchange ( 100 const char *exchange, 101 bool force_download, 102 TMH_EXCHANGES_Find2Continuation fc, 103 void *fc_cls); 104 105 106 /** 107 * Abort pending keys details lookup operation. 108 * 109 * @param fo handle to operation to abort 110 */ 111 void 112 TMH_EXCHANGES_keys4exchange_cancel (struct TMH_EXCHANGES_KeysOperation *fo); 113 114 115 /** 116 * Callback on an exchange known to us. Does not warrant 117 * that the "keys" information is actually available for 118 * @a exchange. 119 * 120 * @param cls closure 121 * @param url base URL of the exchange 122 * @param exchange internal handle for the exchange 123 */ 124 typedef void 125 (*TMH_ExchangeCallback)(void *cls, 126 const char *url, 127 const struct TMH_Exchange *exchange); 128 129 130 /** 131 * Return all trusted exchanges to @a cb. 132 * 133 * @param cb function to call 134 * @param cb_cls closure for @a cb 135 */ 136 void 137 TMH_exchange_get_trusted (TMH_ExchangeCallback cb, 138 void *cb_cls); 139 140 141 /** 142 * Return the master public key of the given @a exchange. 143 * Will be returned from configuration for trusted 144 * exchanges. 145 * 146 * @param exchange exchange to get master public key for 147 * @return the master public key of @a exchange 148 */ 149 const struct TALER_MasterPublicKeyP * 150 TMH_EXCHANGES_get_master_pub ( 151 const struct TMH_Exchange *exchange); 152 153 154 /** 155 * Lookup exchange by @a exchange_url. Create one 156 * if it does not exist. 157 * 158 * @param exchange_url base URL to match against 159 * @return fresh entry if exchange was not yet known 160 */ 161 struct TMH_Exchange * 162 TMH_EXCHANGES_lookup_exchange (const char *exchange_url); 163 164 165 /** 166 * Return the currency of the given @a exchange. 167 * Will be returned from configuration for trusted 168 * exchanges. 169 * 170 * @param exchange exchange to get master public key for 171 * @return the currency of @a exchange 172 */ 173 const char * 174 TMH_EXCHANGES_get_currency ( 175 const struct TMH_Exchange *exchange); 176 177 178 /** 179 * Check if the given operation and amount would 180 * violate any hard limits of the exchange. 181 * Only useful for transaction and refund limits. 182 * 183 * @param keys the keys of the exchange to check limit for 184 * @param operation_type the kind of operation we perform 185 * @param amount the amount we want to transact 186 * @return true if this is allowed 187 */ 188 bool 189 TMH_EXCHANGES_is_below_limit ( 190 const struct TALER_EXCHANGE_Keys *keys, 191 enum TALER_KYCLOGIC_KycTriggerEvent operation_type, 192 const struct TALER_Amount *amount); 193 194 195 /** 196 * Lookup current wire fee by @a exchange_url and @a wire_method. 197 * 198 * @param exchange the exchange to check 199 * @param wire_method wire method to lookup fee by 200 * @param[out] wire_fee set to the wire fee 201 * @return #GNUNET_OK on success 202 * #GNUNET_NO if @a wire_method is not supported 203 * #GNUNET_SYSERR if @a exchange_url did not yet respond properly to our /wire request 204 */ 205 enum GNUNET_GenericReturnValue 206 TMH_EXCHANGES_lookup_wire_fee ( 207 const struct TMH_Exchange *exchange, 208 const char *wire_method, 209 struct TALER_Amount *wire_fee); 210 211 212 /** 213 * Check if we would trust @a ex to deposit funds into our account @a 214 * wm. Checks that both @a ex is trusted and that @a ex allows wire transfers 215 * into the account given in @a wm. 216 * 217 * @param instance_id the instance to check for 218 * @param exchange the exchange to check 219 * @param wm the wire method to check with 220 * @param[in,out] max_amount maximum amount we may deposit at this 221 * exchange; input is an existing maximum, that 222 * can be lowered by this function due to transaction 223 * limits and deposit limits of the exchange 224 * @return #TMH_ES_OK if such a debit can happen 225 * #TMH_ES_NO_ACC if the exchange cannot 226 * be used due to account restrictions 227 * #TMH_ES_NO_CURR if the exchange cannot be used 228 * because it is for a different currency 229 * #TMH_ES_NO_KEYS if the exchange cannot be used 230 * because we do not even know its keys 231 * #TMH_ES_RETRY_OK if the exchange keys request 232 * could be retried (OR-bit!) 233 */ 234 enum TMH_ExchangeStatus 235 { 236 TMH_ES_OK = 0, 237 TMH_ES_NO_ACC = 1, 238 TMH_ES_NO_CURR = 2, 239 TMH_ES_NO_KEYS = 3, 240 TMH_ES_RETRY_OK = 16, 241 TMH_ES_NO_ACC_RETRY_OK = TMH_ES_NO_ACC | TMH_ES_RETRY_OK, 242 TMH_ES_NO_CURR_RETRY_OK = TMH_ES_NO_CURR | TMH_ES_RETRY_OK, 243 TMH_ES_NO_KEYS_RETRY_OK = TMH_ES_NO_KEYS | TMH_ES_RETRY_OK, 244 } 245 TMH_exchange_check_debit ( 246 const char *instance_id, 247 const struct TMH_Exchange *exchange, 248 const struct TMH_WireMethod *wm, 249 struct TALER_Amount *max_amount); 250 251 252 /** 253 * Check if we support the given currency (by having an 254 * exchange configured with it). 255 * 256 * @param currency currency to check 257 * @return true if the currency is supported 258 */ 259 bool 260 TMH_test_exchange_configured_for_currency ( 261 const char *currency); 262 263 264 /** 265 * Determines the legal limit for a given @a operation_type 266 * at a given @a exchange_url. 267 * 268 * @param exchange_url base URL of the exchange to get 269 * the refund limit for 270 * @param operation_type type of operation 271 * @param[in,out] amount lowered to the maximum 272 * allowed at the exchange 273 */ 274 void 275 TMH_EXCHANGES_get_limit ( 276 const char *exchange_url, 277 enum TALER_KYCLOGIC_KycTriggerEvent operation_type, 278 struct TALER_Amount *amount); 279 280 #endif