post-withdraw_blinded.h (11401B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2026 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-exchange/post-withdraw_blinded.h 18 * @brief low-level C interface for POST /withdraw 19 * @author Christian Grothoff 20 */ 21 #ifndef _TALER_EXCHANGE__POST_WITHDRAW_BLINDED_H 22 #define _TALER_EXCHANGE__POST_WITHDRAW_BLINDED_H 23 24 #include <taler/taler-exchange/common.h> 25 #include <taler/taler-exchange/post-withdraw.h> 26 27 28 /** 29 * @brief Information needed to withdraw coins (low-level, pre-blinded). 30 */ 31 struct TALER_EXCHANGE_WithdrawBlindedCoinInput 32 { 33 /** 34 * The denomination of the coin. 35 */ 36 const struct TALER_EXCHANGE_DenomPublicKey *denom_pub; 37 38 /** 39 * Blinded planchet for a single coin. 40 */ 41 struct TALER_PlanchetDetail planchet_details; 42 }; 43 44 /** 45 * @brief Information needed to withdraw age-restricted coins (low-level, pre-blinded). 46 */ 47 struct TALER_EXCHANGE_WithdrawBlindedAgeRestrictedCoinInput 48 { 49 /** 50 * The denomination of the coin. MUST support age restriction. 51 */ 52 const struct TALER_EXCHANGE_DenomPublicKey *denom_pub; 53 54 /** 55 * Tuple of length kappa of planchet candidates for a single coin. 56 */ 57 struct TALER_PlanchetDetail planchet_details[TALER_CNC_KAPPA]; 58 }; 59 60 61 /** 62 * Handle for an operation to POST /withdraw (low-level, pre-blinded variant). 63 */ 64 struct TALER_EXCHANGE_PostWithdrawBlindedHandle; 65 66 67 /** 68 * Set up POST /withdraw operation (low-level variant with pre-blinded 69 * planchets). 70 * Note that you must explicitly start the operation after setup. 71 * 72 * This variant does not do the blinding/unblinding and only 73 * fetches the blind signatures on the already blinded planchets. 74 * 75 * For age-restricted coins requiring a proof, pass @a blinded_input as NULL 76 * and supply the age-restricted input via the 77 * #TALER_EXCHANGE_POST_WITHDRAW_BLINDED_OPTION_WITH_AGE_PROOF option. 78 * 79 * @param curl_ctx The curl context to use 80 * @param keys The /keys material from the exchange 81 * @param exchange_url The base-URL of the exchange 82 * @param reserve_priv private key of the reserve to withdraw from 83 * @param blinding_seed seed used for blinding of CS denominations, might be NULL 84 * @param num_input number of entries in the @a blinded_input array 85 * @param blinded_input array of planchet details to withdraw, or NULL if using WITH_AGE_PROOF option 86 * @return handle to operation, NULL on error 87 */ 88 struct TALER_EXCHANGE_PostWithdrawBlindedHandle * 89 TALER_EXCHANGE_post_withdraw_blinded_create ( 90 struct GNUNET_CURL_Context *curl_ctx, 91 struct TALER_EXCHANGE_Keys *keys, 92 const char *exchange_url, 93 const struct TALER_ReservePrivateKeyP *reserve_priv, 94 const struct TALER_BlindingMasterSeedP *blinding_seed, 95 size_t num_input, 96 const struct TALER_EXCHANGE_WithdrawBlindedCoinInput *blinded_input); 97 98 99 /** 100 * Possible options we can set for the POST /withdraw request 101 * (low-level, pre-blinded variant). 102 */ 103 enum TALER_EXCHANGE_PostWithdrawBlindedOption 104 { 105 /** 106 * End of list of options. 107 */ 108 TALER_EXCHANGE_POST_WITHDRAW_BLINDED_OPTION_END = 0, 109 110 /** 111 * Upgrade to an age-proof withdrawal for age-restricted coins, requiring 112 * an additional call to POST /reveal-withdraw. 113 * The @e details.with_age_proof.max_age field gives the maximum age to 114 * (provably) commit to. 115 * The @e details.with_age_proof.input field gives the KAPPA planchet 116 * candidates per coin. 117 */ 118 TALER_EXCHANGE_POST_WITHDRAW_BLINDED_OPTION_WITH_AGE_PROOF 119 120 }; 121 122 123 /** 124 * Value for an option we can set for the POST /withdraw request 125 * (low-level, pre-blinded variant). 126 */ 127 struct TALER_EXCHANGE_PostWithdrawBlindedOptionValue 128 { 129 /** 130 * Type of the option being set. 131 */ 132 enum TALER_EXCHANGE_PostWithdrawBlindedOption option; 133 134 /** 135 * Specific option value. 136 */ 137 union 138 { 139 /** 140 * Value if @e option is 141 * #TALER_EXCHANGE_POST_WITHDRAW_BLINDED_OPTION_WITH_AGE_PROOF. 142 */ 143 struct 144 { 145 /** 146 * The maximum age to commit to. 147 */ 148 uint8_t max_age; 149 150 /** 151 * Array of KAPPA planchet candidates per coin, length matches 152 * the @e num_input given to _create(). 153 */ 154 const struct TALER_EXCHANGE_WithdrawBlindedAgeRestrictedCoinInput *input; 155 156 } with_age_proof; 157 158 } details; 159 160 }; 161 162 163 /** 164 * Terminate the list of options. 165 * 166 * @return the terminating object 167 */ 168 #define TALER_EXCHANGE_post_withdraw_blinded_option_end_() \ 169 (const struct TALER_EXCHANGE_PostWithdrawBlindedOptionValue) \ 170 { \ 171 .option = TALER_EXCHANGE_POST_WITHDRAW_BLINDED_OPTION_END \ 172 } 173 174 /** 175 * Upgrade to an age-proof withdrawal for age-restricted coins. 176 * 177 * @param age the maximum age to commit to 178 * @param inp pointer to array of KAPPA planchet candidates per coin 179 * @return representation of the option 180 */ 181 #define TALER_EXCHANGE_post_withdraw_blinded_option_with_age_proof(age, inp) \ 182 (const struct TALER_EXCHANGE_PostWithdrawBlindedOptionValue) \ 183 { \ 184 .option = TALER_EXCHANGE_POST_WITHDRAW_BLINDED_OPTION_WITH_AGE_PROOF, \ 185 .details.with_age_proof.max_age = (age), \ 186 .details.with_age_proof.input = (inp) \ 187 } 188 189 190 /** 191 * Set the requested options for the operation. 192 * 193 * If any option fails, other options may or may not be applied. 194 * 195 * @param pwbh the request to set the options for 196 * @param num_options length of the @a options array 197 * @param options an array of options 198 * @return #GNUNET_OK on success, 199 * #GNUNET_NO on failure, 200 * #GNUNET_SYSERR on internal error 201 */ 202 enum GNUNET_GenericReturnValue 203 TALER_EXCHANGE_post_withdraw_blinded_set_options_ ( 204 struct TALER_EXCHANGE_PostWithdrawBlindedHandle *pwbh, 205 unsigned int num_options, 206 const struct TALER_EXCHANGE_PostWithdrawBlindedOptionValue options[]); 207 208 209 /** 210 * Set the requested options for the operation. 211 * 212 * If any option fails, other options may or may not be applied. 213 * 214 * @param pwbh the request to set the options for 215 * @param ... the list of the options, each created by a 216 * TALER_EXCHANGE_post_withdraw_blinded_option_NAME(VALUE) macro 217 * @return #GNUNET_OK on success, 218 * #GNUNET_NO on failure, 219 * #GNUNET_SYSERR on internal error 220 */ 221 #define TALER_EXCHANGE_post_withdraw_blinded_set_options(pwbh,...) \ 222 TALER_EXCHANGE_post_withdraw_blinded_set_options_ ( \ 223 pwbh, \ 224 TALER_EXCHANGE_COMMON_OPTIONS_ARRAY_MAX_SIZE, \ 225 ((const struct TALER_EXCHANGE_PostWithdrawBlindedOptionValue[]) \ 226 {__VA_ARGS__, \ 227 TALER_EXCHANGE_post_withdraw_blinded_option_end_ ()} \ 228 )) 229 230 231 /** 232 * Response from a POST /withdraw request (low-level, pre-blinded variant). 233 */ 234 struct TALER_EXCHANGE_PostWithdrawBlindedResponse 235 { 236 /** 237 * HTTP response data. 238 */ 239 struct TALER_EXCHANGE_HttpResponse hr; 240 241 /** 242 * Details about the response 243 */ 244 union 245 { 246 /** 247 * Details if the status is #MHD_HTTP_OK 248 */ 249 struct 250 { 251 /** 252 * Number of signatures returned. 253 */ 254 unsigned int num_sigs; 255 256 /** 257 * Array of @e num_sigs blinded denomination signatures, giving each 258 * coin its value and validity. The array gives these coins in the same 259 * order (and should have the same length) in which the original 260 * withdraw request specified the respective denomination keys. 261 */ 262 const struct TALER_BlindedDenominationSignature *blinded_denom_sigs; 263 264 /** 265 * The commitment of the withdraw request, needed for the later calls to /recoup 266 */ 267 struct TALER_HashBlindedPlanchetsP planchets_h; 268 269 } ok; 270 271 /** 272 * Details if the status is MHD_HTTP_CREATED, i.e. in case of 273 * age-restriction. The response is input to prepare the required 274 * follow-up call to /reveal-withdraw. 275 */ 276 struct TALER_EXCHANGE_WithdrawCreated created; 277 278 /** 279 * Details if the status is #MHD_HTTP_CONFLICT. 280 */ 281 struct 282 { 283 /** 284 * Details depending on the EC. 285 */ 286 union 287 { 288 289 /** 290 * Further details if the EC is 291 * #TALER_EC_EXCHANGE_GENERIC_INSUFFICIENT_FUNDS. 292 */ 293 struct 294 { 295 /** 296 * Balance of the reserve. 297 */ 298 struct TALER_Amount balance; 299 300 /** 301 * Amount that was requested. 302 */ 303 struct TALER_Amount requested_amount; 304 } generic_insufficient_funds; 305 306 } details; 307 308 } conflict; 309 310 /** 311 * Details if the status is #MHD_HTTP_UNAVAILABLE_FOR_LEGAL_REASONS. 312 */ 313 struct TALER_EXCHANGE_KycNeededRedirect unavailable_for_legal_reasons; 314 315 } details; 316 }; 317 318 319 #ifndef TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE 320 /** 321 * Type of the closure used by 322 * the #TALER_EXCHANGE_PostWithdrawBlindedCallback. 323 */ 324 #define TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE void 325 #endif /* TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE */ 326 327 /** 328 * Type of the function that receives the result of a 329 * POST /withdraw request (low-level, pre-blinded variant). 330 * 331 * @param cls closure 332 * @param result result returned by the HTTP server 333 */ 334 typedef void 335 (*TALER_EXCHANGE_PostWithdrawBlindedCallback)( 336 TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE *cls, 337 const struct TALER_EXCHANGE_PostWithdrawBlindedResponse *result); 338 339 340 /** 341 * Start POST /withdraw operation (low-level, pre-blinded variant). 342 * 343 * @param[in,out] pwbh operation to start 344 * @param cb function to call with the exchange's result 345 * @param cb_cls closure for @a cb 346 * @return status code, #TALER_EC_NONE on success 347 */ 348 enum TALER_ErrorCode 349 TALER_EXCHANGE_post_withdraw_blinded_start ( 350 struct TALER_EXCHANGE_PostWithdrawBlindedHandle *pwbh, 351 TALER_EXCHANGE_PostWithdrawBlindedCallback cb, 352 TALER_EXCHANGE_POST_WITHDRAW_BLINDED_RESULT_CLOSURE *cb_cls); 353 354 355 /** 356 * Cancel POST /withdraw operation (low-level, pre-blinded variant). This 357 * function must not be called by clients after the 358 * TALER_EXCHANGE_PostWithdrawBlindedCallback has been invoked (as in those 359 * cases it'll be called internally by the implementation already). 360 * 361 * @param[in] pwbh operation to cancel 362 */ 363 void 364 TALER_EXCHANGE_post_withdraw_blinded_cancel ( 365 struct TALER_EXCHANGE_PostWithdrawBlindedHandle *pwbh); 366 367 368 #endif /* _TALER_EXCHANGE__POST_WITHDRAW_H */