taler-merchant-httpd_exchanges.h (7512B)
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_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 * Return the currency of the given @a exchange. 156 * Will be returned from configuration for trusted 157 * exchanges. 158 * 159 * @param exchange exchange to get master public key for 160 * @return the currency of @a exchange 161 */ 162 const char * 163 TMH_EXCHANGES_get_currency ( 164 const struct TMH_Exchange *exchange); 165 166 167 /** 168 * Check if the given operation and amount would 169 * violate any hard limits of the exchange. 170 * Only useful for transaction and refund limits. 171 * 172 * @param keys the keys of the exchange to check limit for 173 * @param operation_type the kind of operation we perform 174 * @param amount the amount we want to transact 175 * @return true if this is allowed 176 */ 177 bool 178 TMH_EXCHANGES_is_below_limit ( 179 const struct TALER_EXCHANGE_Keys *keys, 180 enum TALER_KYCLOGIC_KycTriggerEvent operation_type, 181 const struct TALER_Amount *amount); 182 183 184 /** 185 * Lookup current wire fee by @a exchange_url and @a wire_method. 186 * 187 * @param exchange the exchange to check 188 * @param wire_method wire method to lookup fee by 189 * @param[out] wire_fee set to the wire fee 190 * @return #GNUNET_OK on success 191 * #GNUNET_NO if @a wire_method is not supported 192 * #GNUNET_SYSERR if @a exchange_url did not yet respond properly to our /wire request 193 */ 194 enum GNUNET_GenericReturnValue 195 TMH_EXCHANGES_lookup_wire_fee ( 196 const struct TMH_Exchange *exchange, 197 const char *wire_method, 198 struct TALER_Amount *wire_fee); 199 200 201 /** 202 * Check if we would trust @a ex to deposit funds into our account @a 203 * wm. Checks that both @a ex is trusted and that @a ex allows wire transfers 204 * into the account given in @a wm. 205 * 206 * @param instance_id the instance to check for 207 * @param exchange the exchange to check 208 * @param wm the wire method to check with 209 * @param[in,out] max_amount maximum amount we may deposit at this 210 * exchange; input is an existing maximum, that 211 * can be lowered by this function due to transaction 212 * limits and deposit limits of the exchange 213 * @return #TMH_ES_OK if such a debit can happen 214 * #TMH_ES_NO_ACC if the exchange cannot 215 * be used due to account restrictions 216 * #TMH_ES_NO_CURR if the exchange cannot be used 217 * because it is for a different currency 218 * #TMH_ES_NO_KEYS if the exchange cannot be used 219 * because we do not even know its keys 220 * #TMH_ES_RETRY_OK if the exchange keys request 221 * could be retried (OR-bit!) 222 */ 223 enum TMH_ExchangeStatus 224 { 225 TMH_ES_OK = 0, 226 TMH_ES_NO_ACC = 1, 227 TMH_ES_NO_CURR = 2, 228 TMH_ES_NO_KEYS = 3, 229 TMH_ES_RETRY_OK = 16, 230 TMH_ES_NO_ACC_RETRY_OK = TMH_ES_NO_ACC | TMH_ES_RETRY_OK, 231 TMH_ES_NO_CURR_RETRY_OK = TMH_ES_NO_CURR | TMH_ES_RETRY_OK, 232 TMH_ES_NO_KEYS_RETRY_OK = TMH_ES_NO_KEYS | TMH_ES_RETRY_OK, 233 } 234 TMH_exchange_check_debit ( 235 const char *instance_id, 236 const struct TMH_Exchange *exchange, 237 const struct TMH_WireMethod *wm, 238 struct TALER_Amount *max_amount); 239 240 241 /** 242 * Check if we support the given currency (by having an 243 * exchange configured with it). 244 * 245 * @param currency currency to check 246 * @return true if the currency is supported 247 */ 248 bool 249 TMH_test_exchange_configured_for_currency ( 250 const char *currency); 251 252 253 /** 254 * Determines the legal limit for a given @a operation_type 255 * at a given @a exchange_url. 256 * 257 * @param exchange_url base URL of the exchange to get 258 * the refund limit for 259 * @param operation_type type of operation 260 * @param[in,out] amount lowered to the maximum 261 * allowed at the exchange 262 */ 263 void 264 TMH_EXCHANGES_get_limit ( 265 const char *exchange_url, 266 enum TALER_KYCLOGIC_KycTriggerEvent operation_type, 267 struct TALER_Amount *amount); 268 269 #endif