taler_pq_lib.h (14766B)
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 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 include/taler/taler_pq_lib.h 18 * @brief helper functions for DB interactions 19 * @author Sree Harsha Totakura <sreeharsha@totakura.in> 20 * @author Florian Dold 21 * @author Christian Grothoff 22 * @author Özgür Kesim 23 */ 24 #ifndef TALER_PQ_LIB_H_ 25 #define TALER_PQ_LIB_H_ 26 27 #include <libpq-fe.h> 28 #include <jansson.h> 29 #include <gnunet/gnunet_common.h> 30 #include <gnunet/gnunet_pq_lib.h> 31 #include <taler/taler_util.h> 32 33 /** 34 * API version. Bump on every change. 35 */ 36 #define TALER_PQ_VERSION 0x0a040000 37 38 /** 39 * Generate query parameter (as record tuple) for an amount, consisting 40 * of the two components "value" and "fraction" in this order. The 41 * types must be a 64-bit integer and a 32-bit integer 42 * respectively. The currency is dropped. 43 * 44 * @param db The database context for OID lookup 45 * @param amount pointer to the query parameter to pass 46 */ 47 struct GNUNET_PQ_QueryParam 48 TALER_PQ_query_param_amount ( 49 const struct GNUNET_PQ_Context *db, 50 const struct TALER_Amount *amount); 51 52 53 /** 54 * Generate query parameter (as record tuple) for an amount, consisting of the 55 * three components "value", "fraction" and "currency" in this order. The 56 * types must be a 64-bit integer, a 32-bit integer and a TEXT field of 12 57 * characters respectively. 58 * 59 * @param db The database context for OID lookup 60 * @param amount pointer to the query parameter to pass 61 */ 62 struct GNUNET_PQ_QueryParam 63 TALER_PQ_query_param_amount_with_currency ( 64 const struct GNUNET_PQ_Context *db, 65 const struct TALER_Amount *amount); 66 67 68 /** 69 * Generate query parameter for a denomination public 70 * key. Internally, the various attributes of the 71 * public key will be serialized into on variable-size 72 * BLOB. 73 * 74 * @param denom_pub pointer to the query parameter to pass 75 */ 76 struct GNUNET_PQ_QueryParam 77 TALER_PQ_query_param_denom_pub ( 78 const struct TALER_DenominationPublicKey *denom_pub); 79 80 81 /** 82 * Generate query parameter for a denomination signature. Internally, the 83 * various attributes of the signature will be serialized into on 84 * variable-size BLOB. 85 * 86 * @param denom_sig pointer to the query parameter to pass 87 */ 88 struct GNUNET_PQ_QueryParam 89 TALER_PQ_query_param_denom_sig ( 90 const struct TALER_DenominationSignature *denom_sig); 91 92 93 /** 94 * Generate query parameter for a blinded planchet. 95 * Internally, various attributes of the blinded 96 * planchet will be serialized into on 97 * variable-size BLOB. 98 * 99 * @param bp pointer to the query parameter to pass 100 */ 101 struct GNUNET_PQ_QueryParam 102 TALER_PQ_query_param_blinded_planchet ( 103 const struct TALER_BlindedPlanchet *bp); 104 105 106 /** 107 * Generate query parameter for a blinded denomination signature. Internally, 108 * the various attributes of the signature will be serialized into on 109 * variable-size BLOB. 110 * 111 * @param denom_sig pointer to the query parameter to pass 112 */ 113 struct GNUNET_PQ_QueryParam 114 TALER_PQ_query_param_blinded_denom_sig ( 115 const struct TALER_BlindedDenominationSignature *denom_sig); 116 117 118 /** 119 * Generate query parameter for the exchange's contribution during a 120 * withdraw. Internally, the various attributes of the @a blinding_values will be 121 * serialized into on variable-size BLOB. 122 * 123 * @param blinding_values pointer to the query parameter to pass 124 */ 125 struct GNUNET_PQ_QueryParam 126 TALER_PQ_query_param_exchange_blinding_values ( 127 const struct TALER_ExchangeBlindingValues *blinding_values); 128 129 130 /** 131 * Generate query parameter for a JSON object (stored as a string 132 * in the DB). Note that @a x must really be a JSON object or array, 133 * passing just a value (string, integer) is not supported and will 134 * result in an abort. 135 * 136 * @param x pointer to the json object to pass 137 */ 138 struct GNUNET_PQ_QueryParam 139 TALER_PQ_query_param_json (const json_t *x); 140 141 142 /** 143 * Generate query parameter for an array of blinded denomination signatures 144 * 145 * @param num number of elements in @e denom_sigs 146 * @param denom_sigs array of blinded denomination signatures 147 * @param db context for the db-connection 148 */ 149 struct GNUNET_PQ_QueryParam 150 TALER_PQ_query_param_array_blinded_denom_sig ( 151 size_t num, 152 const struct TALER_BlindedDenominationSignature *denom_sigs, 153 struct GNUNET_PQ_Context *db); 154 155 156 /** 157 * Generate query parameter for an array of blinded hashes of coin envelopes 158 * 159 * @param num number of elements in @e denom_sigs 160 * @param coin_evs array of blinded hashes of coin envelopes 161 * @param db context for the db-connection 162 */ 163 struct GNUNET_PQ_QueryParam 164 TALER_PQ_query_param_array_blinded_coin_hash ( 165 size_t num, 166 const struct TALER_BlindedCoinHashP *coin_evs, 167 struct GNUNET_PQ_Context *db); 168 169 170 /** 171 * Generate query parameter for an array of 172 * `struct GNUNET_HashCode`. 173 * 174 * @param num number of elements in @e hash_codes 175 * @param hashes array of hashes 176 * @param db context for the db-connection 177 */ 178 struct GNUNET_PQ_QueryParam 179 TALER_PQ_query_param_array_hash_code ( 180 size_t num, 181 const struct GNUNET_HashCode *hashes, 182 struct GNUNET_PQ_Context *db); 183 184 185 /** 186 * Generate query parameter for an array of 187 * `struct TALER_DenominationHashP` 188 * 189 * @param num number of elements in @e hash_codes 190 * @param denom_hs array of denomination hashes to encode 191 * @param db context for the db-connection 192 */ 193 struct GNUNET_PQ_QueryParam 194 TALER_PQ_query_param_array_denom_hash ( 195 size_t num, 196 const struct TALER_DenominationHashP *denom_hs, 197 struct GNUNET_PQ_Context *db); 198 199 200 /** 201 * Generate query parameter for an array of amounts 202 * 203 * @param num of elements in @e amounts 204 * @param amounts continuous array of amounts 205 * @param db context for db-connection, needed for OID-lookup 206 */ 207 struct GNUNET_PQ_QueryParam 208 TALER_PQ_query_param_array_amount ( 209 size_t num, 210 const struct TALER_Amount *amounts, 211 struct GNUNET_PQ_Context *db); 212 213 214 /** 215 * Generate query parameter for an array of amounts 216 * 217 * @param num of elements in @e amounts 218 * @param amounts continuous array of amounts 219 * @param schema which schema to take the taler_amount_currency data 220 * type from, NULL to use the search_path 221 * @param db context for db-connection, needed for OID-lookup 222 */ 223 struct GNUNET_PQ_QueryParam 224 TALER_PQ_query_param_array_amount_with_currency ( 225 size_t num, 226 const struct TALER_Amount *amounts, 227 const char *schema, 228 struct GNUNET_PQ_Context *db); 229 230 /** 231 * Generate query parameter for an array of public Clause-Schnorr R-values 232 * 233 * @param num of elements in @e cs_r_pubs 234 * @param cs_r_pubs continuous array of public R-values pairs 235 * @param db context fo db-connection, needed for OID-lookup 236 */ 237 struct GNUNET_PQ_QueryParam 238 TALER_PQ_query_param_array_cs_r_pub ( 239 size_t num, 240 const struct GNUNET_CRYPTO_CSPublicRPairP *cs_r_pubs, 241 struct GNUNET_PQ_Context *db); 242 243 244 /** 245 * Generate query parameter for a blind sign public key of variable size. 246 * 247 * @param public_key pointer to the query parameter to pass 248 */ 249 struct GNUNET_PQ_QueryParam 250 TALER_PQ_query_param_blind_sign_pub ( 251 const struct GNUNET_CRYPTO_BlindSignPublicKey *public_key); 252 253 254 /** 255 * Generate query parameter for a blind sign private key of variable size. 256 * 257 * @param private_key pointer to the query parameter to pass 258 */ 259 struct GNUNET_PQ_QueryParam 260 TALER_PQ_query_param_blind_sign_priv ( 261 const struct GNUNET_CRYPTO_BlindSignPrivateKey *private_key); 262 263 264 /* ================ Result handler ==============================*/ 265 266 267 /** 268 * Currency amount expected, from a record-field of (DB) 269 * taler_amount_with_currency type. The currency must be stored in the 270 * database when using this function. 271 * 272 * @param name name of the field in the table 273 * @param[out] amount where to store the result 274 * @return array entry for the result specification to use 275 */ 276 struct GNUNET_PQ_ResultSpec 277 TALER_PQ_result_spec_amount_with_currency ( 278 const char *name, 279 struct TALER_Amount *amount); 280 281 282 /** 283 * Currency amount expected, from a record-field of (DB) taler_amount type. 284 * The currency is NOT stored in the database when using this function, but 285 * instead passed as the @a currency argument. 286 * 287 * @param name name of the field in the table 288 * @param currency currency to use for @a amount 289 * @param[out] amount where to store the result 290 * @return array entry for the result specification to use 291 */ 292 struct GNUNET_PQ_ResultSpec 293 TALER_PQ_result_spec_amount (const char *name, 294 const char *currency, 295 struct TALER_Amount *amount); 296 297 298 /** 299 * Denomination public key expected. 300 * 301 * @param name name of the field in the table 302 * @param[out] denom_pub where to store the public key 303 * @return array entry for the result specification to use 304 */ 305 struct GNUNET_PQ_ResultSpec 306 TALER_PQ_result_spec_denom_pub (const char *name, 307 struct TALER_DenominationPublicKey *denom_pub); 308 309 310 /** 311 * Denomination signature expected. 312 * 313 * @param name name of the field in the table 314 * @param[out] denom_sig where to store the denomination signature 315 * @return array entry for the result specification to use 316 */ 317 struct GNUNET_PQ_ResultSpec 318 TALER_PQ_result_spec_denom_sig (const char *name, 319 struct TALER_DenominationSignature *denom_sig); 320 321 322 /** 323 * Blinded denomination signature expected. 324 * 325 * @param name name of the field in the table 326 * @param[out] denom_sig where to store the denomination signature 327 * @return array entry for the result specification to use 328 */ 329 struct GNUNET_PQ_ResultSpec 330 TALER_PQ_result_spec_blinded_denom_sig ( 331 const char *name, 332 struct TALER_BlindedDenominationSignature *denom_sig); 333 334 335 /** 336 * Exchange withdraw values expected. 337 * 338 * @param name name of the field in the table 339 * @param[out] ewv where to store the exchange values 340 * @return array entry for the result specification to use 341 */ 342 struct GNUNET_PQ_ResultSpec 343 TALER_PQ_result_spec_exchange_withdraw_values ( 344 const char *name, 345 struct TALER_ExchangeBlindingValues *ewv); 346 347 348 /** 349 * Blinded planchet expected. 350 * 351 * @param name name of the field in the table 352 * @param[out] bp where to store the blinded planchet 353 * @return array entry for the result specification to use 354 */ 355 struct GNUNET_PQ_ResultSpec 356 TALER_PQ_result_spec_blinded_planchet ( 357 const char *name, 358 struct TALER_BlindedPlanchet *bp); 359 360 361 /** 362 * json_t expected. 363 * 364 * @param name name of the field in the table 365 * @param[out] jp where to store the result 366 * @return array entry for the result specification to use 367 */ 368 struct GNUNET_PQ_ResultSpec 369 TALER_PQ_result_spec_json (const char *name, 370 json_t **jp); 371 372 373 /** 374 * Array of blinded denomination signature expected 375 * 376 * @param db context of the database connection 377 * @param name name of the field in the table 378 * @param[out] num number of elements in @e denom_sigs 379 * @param[out] denom_sigs where to store the result 380 * @return array entry for the result specification to use 381 */ 382 struct GNUNET_PQ_ResultSpec 383 TALER_PQ_result_spec_array_blinded_denom_sig ( 384 struct GNUNET_PQ_Context *db, 385 const char *name, 386 size_t *num, 387 struct TALER_BlindedDenominationSignature **denom_sigs); 388 389 390 /** 391 * Array of blinded hashes of coin envelopes 392 * 393 * @param db context of the database connection 394 * @param name name of the field in the table 395 * @param[out] num number of elements in @e denom_sigs 396 * @param[out] h_coin_evs where to store the result 397 * @return array entry for the result specification to use 398 */ 399 struct GNUNET_PQ_ResultSpec 400 TALER_PQ_result_spec_array_blinded_coin_hash ( 401 struct GNUNET_PQ_Context *db, 402 const char *name, 403 size_t *num, 404 struct TALER_BlindedCoinHashP **h_coin_evs); 405 406 407 /** 408 * Array of hashes of denominations 409 * 410 * @param db context of the database connection 411 * @param name name of the field in the table 412 * @param[out] num number of elements in @e denom_sigs 413 * @param[out] denom_hs where to store the result 414 * @return array entry for the result specification to use 415 */ 416 struct GNUNET_PQ_ResultSpec 417 TALER_PQ_result_spec_array_denom_hash ( 418 struct GNUNET_PQ_Context *db, 419 const char *name, 420 size_t *num, 421 struct TALER_DenominationHashP **denom_hs); 422 423 424 /** 425 * Array of GNUNET_HashCode 426 * 427 * @param db context of the database connection 428 * @param name name of the field in the table 429 * @param[out] num number of elements in @e denom_sigs 430 * @param[out] hashes where to store the result 431 * @return array entry for the result specification to use 432 */ 433 struct GNUNET_PQ_ResultSpec 434 TALER_PQ_result_spec_array_hash_code ( 435 struct GNUNET_PQ_Context *db, 436 const char *name, 437 size_t *num, 438 struct GNUNET_HashCode **hashes); 439 440 /** 441 * Array of amounts 442 * 443 * @param db context of the database connection 444 * @param name name of the field in the table 445 * @param currency The currency 446 * @param[out] num number of elements in @e amounts 447 * @param[out] amounts where to store the result 448 * @return array entry for the result specification to use 449 */ 450 struct GNUNET_PQ_ResultSpec 451 TALER_PQ_result_spec_array_amount ( 452 struct GNUNET_PQ_Context *db, 453 const char *name, 454 const char *currency, 455 size_t *num, 456 struct TALER_Amount **amounts); 457 458 459 /** 460 * Array of amounts including currency 461 * 462 * @param db context of the database connection 463 * @param schema DB schema in which the "taler_amount_currency" type is 464 * expected to be defined 465 * @param name name of the field in the table 466 * @param[out] num number of elements in @e amounts 467 * @param[out] amounts where to store the result 468 * @return array entry for the result specification to use 469 */ 470 struct GNUNET_PQ_ResultSpec 471 TALER_PQ_result_spec_array_amount_with_currency ( 472 struct GNUNET_PQ_Context *db, 473 const char *schema, 474 const char *name, 475 size_t *num, 476 struct TALER_Amount **amounts); 477 478 479 /** 480 * Array of public R-values for Clause-Schnorr 481 * 482 * @param db context of the database connection 483 * @param name name of the field in the table 484 * @param[out] num number of elements in @e cs_r_pubs 485 * @param[out] cs_r_pubs where to store the result 486 * @return array entry for the result specification to use 487 */ 488 struct GNUNET_PQ_ResultSpec 489 TALER_PQ_result_spec_array_cs_r_pub ( 490 struct GNUNET_PQ_Context *db, 491 const char *name, 492 size_t *num, 493 struct GNUNET_CRYPTO_CSPublicRPairP **cs_r_pubs); 494 495 #endif /* TALER_PQ_LIB_H_ */ 496 497 /* end of include/taler_pq_lib.h */