taler-exchange-httpd_responses.h (9319B)
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 taler-exchange-httpd_responses.h 18 * @brief API for generating generic replies of the exchange; these 19 * functions are called TEH_RESPONSE_reply_ and they generate 20 * and queue MHD response objects for a given connection. 21 * @author Florian Dold 22 * @author Benedikt Mueller 23 * @author Christian Grothoff 24 */ 25 #ifndef TALER_EXCHANGE_HTTPD_RESPONSES_H 26 #define TALER_EXCHANGE_HTTPD_RESPONSES_H 27 28 #include <gnunet/gnunet_util_lib.h> 29 #include <jansson.h> 30 #include <microhttpd.h> 31 #include "taler/taler_error_codes.h" 32 #include "taler-exchange-httpd.h" 33 #include "taler-exchange-httpd_db.h" 34 #include "exchangedb_lib.h" 35 #include "exchange-database/do_insert_known_coin.h" 36 37 38 /** 39 * Send assertion that the given denomination key hash 40 * is unknown to us at this time. 41 * 42 * @param connection connection to the client 43 * @param dph denomination public key hash 44 * @return MHD result code 45 */ 46 enum MHD_Result 47 TEH_RESPONSE_reply_unknown_denom_pub_hash ( 48 struct MHD_Connection *connection, 49 const struct TALER_DenominationHashP *dph); 50 51 52 /** 53 * Return error message indicating that a reserve had 54 * an insufficient balance for the given operation. 55 * 56 * @param connection connection to the client 57 * @param ec specific error code to return with the reserve history 58 * @param reserve_balance balance remaining in the reserve 59 * @param balance_required the balance required for the operation 60 * @param reserve_pub the reserve with insufficient balance 61 * @return MHD result code 62 */ 63 enum MHD_Result 64 TEH_RESPONSE_reply_reserve_insufficient_balance ( 65 struct MHD_Connection *connection, 66 enum TALER_ErrorCode ec, 67 const struct TALER_Amount *reserve_balance, 68 const struct TALER_Amount *balance_required, 69 const struct TALER_ReservePublicKeyP *reserve_pub); 70 71 /** 72 * Return error message indicating that a reserve requires age 73 * restriction to be set during withdraw, that is: the age-withdraw 74 * protocol MUST be used with commitment to an admissible age. 75 * 76 * @param connection connection to the client 77 * @param maximum_allowed_age the balance required for the operation 78 * @return MHD result code 79 */ 80 enum MHD_Result 81 TEH_RESPONSE_reply_reserve_age_restriction_required ( 82 struct MHD_Connection *connection, 83 uint16_t maximum_allowed_age); 84 85 86 /** 87 * Send information that a KYC check must be 88 * satisfied to proceed to client. 89 * 90 * @param connection connection to the client 91 * @param h_payto account identifier to include in reply 92 * @param kyc details about the KYC requirements 93 * @param bad_kyc_auth true if the target_pub of the 94 * @a h_payto account does not match the merchant_pub 95 * from the operation and thus a KYC AUTH transfer is 96 * required 97 * @return MHD result code 98 */ 99 enum MHD_Result 100 TEH_RESPONSE_reply_kyc_required ( 101 struct MHD_Connection *connection, 102 const struct TALER_NormalizedPaytoHashP *h_payto, 103 const struct TALER_EXCHANGEDB_KycStatus *kyc, 104 bool bad_kyc_auth); 105 106 107 /** 108 * Send assertion that the given denomination key hash 109 * is not usable (typically expired) at this time. 110 * 111 * @param connection connection to the client 112 * @param dph denomination public key hash 113 * @param ec error code to use 114 * @param oper name of the operation that is not allowed at this time 115 * @return MHD result code 116 */ 117 enum MHD_Result 118 TEH_RESPONSE_reply_expired_denom_pub_hash ( 119 struct MHD_Connection *connection, 120 const struct TALER_DenominationHashP *dph, 121 enum TALER_ErrorCode ec, 122 const char *oper); 123 124 125 /** 126 * Send assertion that the given denomination cannot be used for this operation. 127 * 128 * @param connection connection to the client 129 * @param dph denomination public key hash 130 * @return MHD result code 131 */ 132 enum MHD_Result 133 TEH_RESPONSE_reply_invalid_denom_cipher_for_operation ( 134 struct MHD_Connection *connection, 135 const struct TALER_DenominationHashP *dph); 136 137 138 /** 139 * Send proof that a request is invalid to client because of 140 * insufficient funds. This function will create a message with all 141 * of the operations affecting the coin that demonstrate that the coin 142 * has insufficient value. 143 * 144 * @param connection connection to the client 145 * @param ec error code to return 146 * @param h_denom_pub hash of the denomination of the coin 147 * @param coin_pub public key of the coin 148 * @return MHD result code 149 */ 150 enum MHD_Result 151 TEH_RESPONSE_reply_coin_insufficient_funds ( 152 struct MHD_Connection *connection, 153 enum TALER_ErrorCode ec, 154 const struct TALER_DenominationHashP *h_denom_pub, 155 const struct TALER_CoinSpendPublicKeyP *coin_pub); 156 157 /** 158 * Send proof that a request is invalid to client because of 159 * an conflict with the provided denomination (the exchange had seen 160 * this coin before, signed by a different denomination). 161 * This function will create a message with the denomination's public key 162 * that was seen before. 163 * 164 * @param connection connection to the client 165 * @param ec error code to return 166 * @param coin_pub the public key of the coin 167 * @param prev_denom_pub the denomination of the coin, as seen previously 168 * @param prev_denom_sig the signature with the denomination key over the coin 169 * @return MHD result code 170 */ 171 enum MHD_Result 172 TEH_RESPONSE_reply_coin_denomination_conflict ( 173 struct MHD_Connection *connection, 174 enum TALER_ErrorCode ec, 175 const struct TALER_CoinSpendPublicKeyP *coin_pub, 176 const struct TALER_DenominationPublicKey *prev_denom_pub, 177 const struct TALER_DenominationSignature *prev_denom_sig); 178 179 /** 180 * Send the salted hash of the merchant's bank account from conflicting 181 * contract. With this information, the merchant's private key and 182 * the hash of the contract terms, the client can retrieve more details 183 * about the conflicting deposit 184 * 185 * @param connection connection to the client 186 * @param ec error code to return 187 * @param h_wire the salted hash of the merchant's bank account 188 * @return MHD result code 189 */ 190 enum MHD_Result 191 TEH_RESPONSE_reply_coin_conflicting_contract ( 192 struct MHD_Connection *connection, 193 enum TALER_ErrorCode ec, 194 const struct TALER_MerchantWireHashP *h_wire); 195 196 /** 197 * Send proof that a request is invalid to client because of 198 * a conflicting value for the age commitment hash of a coin. 199 * This function will create a message with the conflicting 200 * hash value for the age commitment of the given coin. 201 * 202 * @param connection connection to the client 203 * @param ec error code to return 204 * @param cks specific conflict type 205 * @param h_denom_pub hash of the denomination of the coin 206 * @param coin_pub public key of the coin 207 * @param h_age_commitment hash of the age commitment as found in the database 208 * @return MHD result code 209 */ 210 enum MHD_Result 211 TEH_RESPONSE_reply_coin_age_commitment_conflict ( 212 struct MHD_Connection *connection, 213 enum TALER_ErrorCode ec, 214 enum TALER_EXCHANGEDB_CoinKnownStatus cks, 215 const struct TALER_DenominationHashP *h_denom_pub, 216 const struct TALER_CoinSpendPublicKeyP *coin_pub, 217 const struct TALER_AgeCommitmentHashP *h_age_commitment); 218 219 /** 220 * Fundamental details about a purse. 221 */ 222 struct TEH_PurseDetails 223 { 224 /** 225 * When should the purse expire. 226 */ 227 struct GNUNET_TIME_Timestamp purse_expiration; 228 229 /** 230 * Hash of the contract terms of the purse. 231 */ 232 struct TALER_PrivateContractHashP h_contract_terms; 233 234 /** 235 * Public key of the purse we are creating. 236 */ 237 struct TALER_PurseContractPublicKeyP purse_pub; 238 239 /** 240 * Total amount to be put into the purse. 241 */ 242 struct TALER_Amount target_amount; 243 }; 244 245 246 /** 247 * Send confirmation that a purse was created with 248 * the current purse balance. 249 * 250 * @param connection connection to the client 251 * @param pd purse details 252 * @param exchange_timestamp our time for purse creation 253 * @param purse_balance current balance in the purse 254 * @return MHD result code 255 */ 256 enum MHD_Result 257 TEH_RESPONSE_reply_purse_created ( 258 struct MHD_Connection *connection, 259 struct GNUNET_TIME_Timestamp exchange_timestamp, 260 const struct TALER_Amount *purse_balance, 261 const struct TEH_PurseDetails *pd); 262 263 264 /** 265 * Callback used to set headers in a response. 266 * 267 * @param cls closure 268 * @param[in,out] resp response to modify 269 */ 270 typedef void 271 (*TEH_RESPONSE_SetHeaders)(void *cls, 272 struct MHD_Response *resp); 273 274 275 /** 276 * Generate a HTTP "Not modified" response with the 277 * given @a etags. 278 * 279 * @param connection connection to queue response on 280 * @param etags ETag header to set 281 * @param cb callback to modify response headers 282 * @param cb_cls closure for @a cb 283 * @return MHD result code 284 */ 285 enum MHD_Result 286 TEH_RESPONSE_reply_not_modified ( 287 struct MHD_Connection *connection, 288 const char *etags, 289 TEH_RESPONSE_SetHeaders cb, 290 void *cb_cls); 291 292 293 #endif