exchangedb_lib.h (33498B)
1 /* 2 This file is part of TALER 3 Copyright (C) 2014-2020 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/exchangedb_lib.h 18 * @brief IO operations for the exchange's private keys 19 * @author Florian Dold 20 * @author Benedikt Mueller 21 * @author Christian Grothoff 22 */ 23 #ifndef TALER_EXCHANGEDB_LIB_H 24 #define TALER_EXCHANGEDB_LIB_H 25 26 #include <taler/taler_signatures.h> 27 #include <taler/taler_bank_service.h> 28 #include <taler/taler_kyclogic_lib.h> 29 #include <taler/taler_util.h> 30 31 32 /** 33 * Detailed status for persisting an AML program result. 34 */ 35 enum TALER_EXCHANGEDB_PersistProgramResultStatus 36 { 37 TALER_EXCHANGEDB_PPRS_OK = 0, 38 TALER_EXCHANGEDB_PPRS_BAD_OUTCOME = 1, 39 }; 40 41 42 /** 43 * Why the aggregator decided against executing a wire transfer it had 44 * already computed. Stored in the @e deferral_reason column of the 45 * append-only `aggregation_deferrals` table, which is the exchange's claim 46 * to the auditor about money it is holding on to. Values are part of the 47 * replicated database format and must not be renumbered. 48 */ 49 enum TALER_EXCHANGEDB_DeferralReason 50 { 51 52 /** 53 * The exchange gave no reason. Never written; this is what the auditor 54 * books a pending transfer under when it finds no `aggregation_deferrals` 55 * row for it at all. 56 */ 57 TALER_EXCHANGEDB_DR_NONE = 0, 58 59 /** 60 * What was aggregated does not survive the wire fee and the rounding to 61 * the smallest unit the wire method supports, so the exchange is waiting 62 * for further deposits to the same account to make the transfer worth 63 * making. 64 */ 65 TALER_EXCHANGEDB_DR_AMOUNT_TOO_SMALL = 1, 66 67 /** 68 * A legitimization requirement against the recipient account is open, so 69 * the exchange must not pay out yet. The measure in question is named by 70 * the @e legitimization_requirement_serial_id column. 71 */ 72 TALER_EXCHANGEDB_DR_KYC = 2 73 }; 74 75 76 /** 77 * Information about a denomination key. 78 */ 79 struct TALER_EXCHANGEDB_DenominationKeyInformation 80 { 81 82 /** 83 * Signature over this struct to affirm the validity of the key. 84 */ 85 struct TALER_MasterSignatureP signature; 86 87 /** 88 * Start time of the validity period for this key. 89 */ 90 struct GNUNET_TIME_Timestamp start; 91 92 /** 93 * The exchange will sign fresh coins between @e start and this time. 94 * @e expire_withdraw will be somewhat larger than @e start to 95 * ensure a sufficiently large anonymity set, while also allowing 96 * the Exchange to limit the financial damage in case of a key being 97 * compromised. Thus, exchanges with low volume are expected to have a 98 * longer withdraw period (@e expire_withdraw - @e start) than exchanges 99 * with high transaction volume. The period may also differ between 100 * types of coins. A exchange may also have a few denomination keys 101 * with the same value with overlapping validity periods, to address 102 * issues such as clock skew. 103 */ 104 struct GNUNET_TIME_Timestamp expire_withdraw; 105 106 /** 107 * Coins signed with the denomination key must be spent or refreshed 108 * between @e start and this expiration time. After this time, the 109 * exchange will refuse transactions involving this key as it will 110 * "drop" the table with double-spending information (shortly after) 111 * this time. Note that wallets should refresh coins significantly 112 * before this time to be on the safe side. @e expire_deposit must be 113 * significantly larger than @e expire_withdraw (by months or even 114 * years). 115 */ 116 struct GNUNET_TIME_Timestamp expire_deposit; 117 118 /** 119 * When do signatures with this denomination key become invalid? 120 * After this point, these signatures cannot be used in (legal) 121 * disputes anymore, as the Exchange is then allowed to destroy its side 122 * of the evidence. @e expire_legal is expected to be significantly 123 * larger than @e expire_deposit (by a year or more). 124 */ 125 struct GNUNET_TIME_Timestamp expire_legal; 126 127 /** 128 * The value of the coins signed with this denomination key. 129 */ 130 struct TALER_Amount value; 131 132 /** 133 * Fees for the coin. 134 */ 135 struct TALER_DenomFeeSet fees; 136 137 /** 138 * Hash code of the denomination public key. (Used to avoid having 139 * the variable-size RSA key in this struct.) 140 */ 141 struct TALER_DenominationHashP denom_hash; 142 143 /** 144 * If denomination was setup for age restriction, non-zero age mask. 145 * Note that the mask is not part of the signature. 146 */ 147 struct TALER_AgeMask age_mask; 148 }; 149 150 151 GNUNET_NETWORK_STRUCT_BEGIN 152 153 /** 154 * Events signalling that a coin deposit status 155 * changed. 156 */ 157 struct TALER_EXCHANGEDB_CoinDepositEventP 158 { 159 /** 160 * Of type #TALER_DBEVENT_EXCHANGE_DEPOSIT_STATUS_CHANGED. 161 */ 162 struct GNUNET_DB_EventHeaderP header; 163 164 /** 165 * Public key of the merchant. 166 */ 167 struct TALER_MerchantPublicKeyP merchant_pub; 168 169 }; 170 171 /** 172 * Events signalling a reserve got funding. 173 */ 174 struct TALER_EXCHANGEDB_ReserveEventP 175 { 176 /** 177 * Of type #TALER_DBEVENT_EXCHANGE_RESERVE_INCOMING. 178 */ 179 struct GNUNET_DB_EventHeaderP header; 180 181 /** 182 * Public key of the reserve the event is about. 183 */ 184 struct TALER_ReservePublicKeyP reserve_pub; 185 }; 186 187 188 /** 189 * Signature of events signalling a purse changed its status. 190 */ 191 struct TALER_EXCHANGEDB_PurseEventP 192 { 193 /** 194 * Of type #TALER_DBEVENT_EXCHANGE_PURSE_MERGED or 195 * #TALER_DBEVENT_EXCHANGE_PURSE_DEPOSITED. 196 */ 197 struct GNUNET_DB_EventHeaderP header; 198 199 /** 200 * Public key of the purse the event is about. 201 */ 202 struct TALER_PurseContractPublicKeyP purse_pub; 203 }; 204 205 206 /** 207 * Signature of events signalling a KYC process was completed. 208 */ 209 struct TALER_EXCHANGEDB_KycCompletedEventP 210 { 211 /** 212 * Of type #TALER_DBEVENT_EXCHANGE_KYC_COMPLETED. 213 */ 214 struct GNUNET_DB_EventHeaderP header; 215 216 /** 217 * Hash of payto://-URI for which the KYC state changed. 218 */ 219 struct TALER_NormalizedPaytoHashP h_payto; 220 }; 221 222 223 GNUNET_NETWORK_STRUCT_END 224 225 /** 226 * Meta data about an exchange online signing key. 227 */ 228 struct TALER_EXCHANGEDB_SignkeyMetaData 229 { 230 /** 231 * Start time of the validity period for this key. 232 */ 233 struct GNUNET_TIME_Timestamp start; 234 235 /** 236 * The exchange will sign messages with this key between @e start and this time. 237 */ 238 struct GNUNET_TIME_Timestamp expire_sign; 239 240 /** 241 * When do signatures with this sign key become invalid? 242 * After this point, these signatures cannot be used in (legal) 243 * disputes anymore, as the Exchange is then allowed to destroy its side 244 * of the evidence. @e expire_legal is expected to be significantly 245 * larger than @e expire_sign (by a year or more). 246 */ 247 struct GNUNET_TIME_Timestamp expire_legal; 248 249 }; 250 251 252 /** 253 * @brief All information about a denomination key (which is used to 254 * sign coins into existence). 255 */ 256 struct TALER_EXCHANGEDB_DenominationKey 257 { 258 /** 259 * The private key of the denomination. Will be NULL if the private 260 * key is not available (this is the case after the key has expired 261 * for signing coins, but is still valid for depositing coins). 262 */ 263 struct TALER_DenominationPrivateKey denom_priv; 264 265 /** 266 * Decoded denomination public key (the hash of it is in 267 * @e issue, but we sometimes need the full public key as well). 268 */ 269 struct TALER_DenominationPublicKey denom_pub; 270 271 /** 272 * Signed public information about a denomination key. 273 */ 274 struct TALER_EXCHANGEDB_DenominationKeyInformation issue; 275 }; 276 277 278 /** 279 * @brief A summary of a Reserve 280 */ 281 struct TALER_EXCHANGEDB_Reserve 282 { 283 /** 284 * The reserve's public key. This uniquely identifies the reserve 285 */ 286 struct TALER_ReservePublicKeyP pub; 287 288 /** 289 * The balance amount existing in the reserve 290 */ 291 struct TALER_Amount balance; 292 293 /** 294 * The expiration date of this reserve; funds will be wired back 295 * at this time. 296 */ 297 struct GNUNET_TIME_Timestamp expiry; 298 299 /** 300 * The legal expiration date of this reserve; we will forget about 301 * it at this time. 302 */ 303 struct GNUNET_TIME_Timestamp gc; 304 }; 305 306 307 /** 308 * Public key to which a nonce is locked. 309 */ 310 union TALER_EXCHANGEDB_NonceLockTargetP 311 { 312 /** 313 * Nonce is locked to this coin key. 314 */ 315 struct TALER_CoinSpendPublicKeyP coin; 316 317 /** 318 * Nonce is locked to this reserve key. 319 */ 320 struct TALER_ReservePublicKeyP reserve; 321 }; 322 323 324 /** 325 * @brief Data about a coin for a deposit operation. 326 */ 327 struct TALER_EXCHANGEDB_CoinDepositInformation 328 { 329 /** 330 * Information about the coin that is being deposited. 331 */ 332 struct TALER_CoinPublicInfo coin; 333 334 /** 335 * ECDSA signature affirming that the customer intends 336 * this coin to be deposited at the merchant identified 337 * by @e h_wire in relation to the proposal data identified 338 * by @e h_contract_terms. 339 */ 340 struct TALER_CoinSpendSignatureP csig; 341 342 /** 343 * Fraction of the coin's remaining value to be deposited, including 344 * depositing fee (if any). The coin is identified by @e coin_pub. 345 */ 346 struct TALER_Amount amount_with_fee; 347 348 }; 349 350 351 /** 352 * @brief Data from a batch deposit operation. 353 */ 354 struct TALER_EXCHANGEDB_BatchDeposit 355 { 356 357 /** 358 * Public key of the merchant. Enables later identification 359 * of the merchant in case of a need to rollback transactions. 360 */ 361 struct TALER_MerchantPublicKeyP merchant_pub; 362 363 /** 364 * Signature of the merchant over the contract, of purpose 365 * #TALER_SIGNATURE_MERCHANT_CONTRACT. 366 */ 367 struct TALER_MerchantSignatureP merchant_sig; 368 369 /** 370 * Hash over the proposal data between merchant and customer 371 * (remains unknown to the Exchange). 372 */ 373 struct TALER_PrivateContractHashP h_contract_terms; 374 375 /** 376 * Hash over additional inputs by the wallet. 377 */ 378 struct GNUNET_HashCode wallet_data_hash; 379 380 /** 381 * Unsalted hash over @e receiver_wire_account. 382 */ 383 struct TALER_FullPaytoHashP wire_target_h_payto; 384 385 /** 386 * Salt used by the merchant to compute "h_wire". 387 */ 388 struct TALER_WireSaltP wire_salt; 389 390 /** 391 * Time when this request was generated. Used, for example, to 392 * assess when (roughly) the income was achieved for tax purposes. 393 * Note that the Exchange will only check that the timestamp is not "too 394 * far" into the future (i.e. several days). The fact that the 395 * timestamp falls within the validity period of the coin's 396 * denomination key is irrelevant for the validity of the deposit 397 * request, as obviously the customer and merchant could conspire to 398 * set any timestamp. Also, the Exchange must accept very old deposit 399 * requests, as the merchant might have been unable to transmit the 400 * deposit request in a timely fashion (so back-dating is not 401 * prevented). 402 */ 403 struct GNUNET_TIME_Timestamp wallet_timestamp; 404 405 /** 406 * How much time does the merchant have to issue a refund request? 407 * Zero if refunds are not allowed. After this time, the coin 408 * cannot be refunded. 409 */ 410 struct GNUNET_TIME_Timestamp refund_deadline; 411 412 /** 413 * How much time does the merchant have to execute the wire transfer? 414 * This time is advisory for aggregating transactions, not a hard 415 * constraint (as the merchant can theoretically pick any time, 416 * including one in the past). 417 */ 418 struct GNUNET_TIME_Timestamp wire_deadline; 419 420 /** 421 * Row ID of the policy details; 0 if no policy applies. 422 */ 423 uint64_t policy_details_serial_id; 424 425 /** 426 * Information about the receiver for executing the transaction. URI in 427 * payto://-format. 428 */ 429 struct TALER_FullPayto receiver_wire_account; 430 431 /** 432 * Optional extra information to include in the wire transfer 433 * subject. 434 */ 435 const char *extra_wire_subject_metadata; 436 437 /** 438 * Array about the coins that are being deposited. 439 */ 440 const struct TALER_EXCHANGEDB_CoinDepositInformation *cdis; 441 442 /** 443 * Length of the @e cdis array. 444 */ 445 unsigned int num_cdis; 446 447 /** 448 * False if @e wallet_data_hash was provided 449 */ 450 bool no_wallet_data_hash; 451 452 /** 453 * True if further processing is blocked by policy. 454 */ 455 bool policy_blocked; 456 457 }; 458 459 460 /** 461 * @brief Data from a deposit operation. The combination of 462 * the coin's public key, the merchant's public key and the 463 * transaction ID must be unique. While a coin can (theoretically) be 464 * deposited at the same merchant twice (with partial spending), the 465 * merchant must either use a different public key or a different 466 * transaction ID for the two transactions. The same coin must not 467 * be used twice at the same merchant for the same transaction 468 * (as determined by transaction ID). 469 */ 470 struct TALER_EXCHANGEDB_Deposit 471 { 472 /** 473 * Information about the coin that is being deposited. 474 */ 475 struct TALER_CoinPublicInfo coin; 476 477 /** 478 * ECDSA signature affirming that the customer intends 479 * this coin to be deposited at the merchant identified 480 * by @e h_wire in relation to the proposal data identified 481 * by @e h_contract_terms. 482 */ 483 struct TALER_CoinSpendSignatureP csig; 484 485 /** 486 * Public key of the merchant. Enables later identification 487 * of the merchant in case of a need to rollback transactions. 488 */ 489 struct TALER_MerchantPublicKeyP merchant_pub; 490 491 /** 492 * Hash over the proposal data between merchant and customer 493 * (remains unknown to the Exchange). 494 */ 495 struct TALER_PrivateContractHashP h_contract_terms; 496 497 /** 498 * Salt used by the merchant to compute "h_wire". 499 */ 500 struct TALER_WireSaltP wire_salt; 501 502 /** 503 * Hash over inputs from the wallet to customize the contract. 504 */ 505 struct GNUNET_HashCode wallet_data_hash; 506 507 /** 508 * Hash over the policy data for this deposit (remains unknown to the 509 * Exchange). Needed for the verification of the deposit's signature 510 */ 511 struct TALER_ExtensionPolicyHashP h_policy; 512 513 /** 514 * Time when this request was generated. Used, for example, to 515 * assess when (roughly) the income was achieved for tax purposes. 516 * Note that the Exchange will only check that the timestamp is not "too 517 * far" into the future (i.e. several days). The fact that the 518 * timestamp falls within the validity period of the coin's 519 * denomination key is irrelevant for the validity of the deposit 520 * request, as obviously the customer and merchant could conspire to 521 * set any timestamp. Also, the Exchange must accept very old deposit 522 * requests, as the merchant might have been unable to transmit the 523 * deposit request in a timely fashion (so back-dating is not 524 * prevented). 525 */ 526 struct GNUNET_TIME_Timestamp timestamp; 527 528 /** 529 * How much time does the merchant have to issue a refund request? 530 * Zero if refunds are not allowed. After this time, the coin 531 * cannot be refunded. 532 */ 533 struct GNUNET_TIME_Timestamp refund_deadline; 534 535 /** 536 * How much time does the merchant have to execute the wire transfer? 537 * This time is advisory for aggregating transactions, not a hard 538 * constraint (as the merchant can theoretically pick any time, 539 * including one in the past). 540 */ 541 struct GNUNET_TIME_Timestamp wire_deadline; 542 543 /** 544 * Fraction of the coin's remaining value to be deposited, including 545 * depositing fee (if any). The coin is identified by @e coin_pub. 546 */ 547 struct TALER_Amount amount_with_fee; 548 549 /** 550 * Depositing fee. 551 */ 552 struct TALER_Amount deposit_fee; 553 554 /** 555 * Information about the receiver for executing the transaction. URI in 556 * payto://-format. 557 */ 558 struct TALER_FullPayto receiver_wire_account; 559 560 /** 561 * True if @e policy_json was provided 562 */ 563 bool has_policy; 564 565 /** 566 * True if @e wallet_data_hash is not in use. 567 */ 568 bool no_wallet_data_hash; 569 570 }; 571 572 573 /** 574 * @brief Specification for coin in a melt operation. 575 */ 576 struct TALER_EXCHANGEDB_Refresh 577 { 578 /** 579 * Information about the coin that is being melted. 580 */ 581 struct TALER_CoinPublicInfo coin; 582 583 /** 584 * Signature over the melting operation. 585 */ 586 struct TALER_CoinSpendSignatureP coin_sig; 587 588 /** 589 * Refresh commitment this coin is melted into. 590 */ 591 struct TALER_RefreshCommitmentP rc; 592 593 /** 594 * How much value is being melted? This amount includes the fees, 595 * so the final amount contributed to the melt is this value minus 596 * the fee for melting the coin. We include the fee in what is 597 * being signed so that we can verify a reserve's remaining total 598 * balance without needing to access the respective denomination key 599 * information each time. 600 */ 601 struct TALER_Amount amount_with_fee; 602 603 /** 604 * Index (smaller #TALER_CNC_KAPPA) which the exchange has chosen to not 605 * have revealed during cut and choose. 606 */ 607 uint32_t noreveal_index; 608 609 }; 610 611 612 /** 613 * Information about a /purses/$PID/deposit operation. 614 */ 615 struct TALER_EXCHANGEDB_PurseDeposit 616 { 617 618 /** 619 * Exchange hosting the purse, NULL for this exchange. 620 */ 621 char *exchange_base_url; 622 623 /** 624 * Public key of the purse. 625 */ 626 struct TALER_PurseContractPublicKeyP purse_pub; 627 628 /** 629 * Contribution of the coin to the purse, including 630 * deposit fee. 631 */ 632 struct TALER_Amount amount; 633 634 /** 635 * Depositing fee. 636 */ 637 struct TALER_Amount deposit_fee; 638 639 /** 640 * Signature by the coin affirming the deposit. 641 */ 642 struct TALER_CoinSpendSignatureP coin_sig; 643 644 /** 645 * Public key of the coin. 646 */ 647 struct TALER_CoinSpendPublicKeyP coin_pub; 648 649 /** 650 * Hash of the age commitment used to sign the coin, if age restriction was 651 * applicable to the denomination. May be all zeroes if no age restriction 652 * applies. 653 */ 654 struct TALER_AgeCommitmentHashP h_age_commitment; 655 656 /** 657 * Set to true if @e h_age_commitment is not available. 658 */ 659 bool no_age_commitment; 660 661 }; 662 663 664 /** 665 * Information about a melt operation since vDOLDPLUS of the protocol. 666 * This also includes the information for the reveal phase. 667 */ 668 struct TALER_EXCHANGEDB_Refresh_vDOLDPLUS 669 { 670 /** 671 * Information about the coin that is being melted. 672 */ 673 struct TALER_CoinPublicInfo coin; 674 675 /** 676 * Signature over the melting operation. 677 */ 678 struct TALER_CoinSpendSignatureP coin_sig; 679 680 /** 681 * Refresh commitment this coin is melted into. 682 */ 683 struct TALER_RefreshCommitmentP rc; 684 685 /** 686 * Version of the refresh commitment @e rc that the client used. 687 * For #TALER_REFRESH_COMMITMENT_VERSION_LEGACY_V27, the client did 688 * not provide transfer public keys and @e refresh_seed is the v27 689 * refresh seed; for all later versions, @e refresh_seed is the 690 * vDOLDPLUS master refresh seed and @e transfer_pubs is set. 691 */ 692 enum TALER_RefreshCommitmentVersion rc_version; 693 694 /** 695 * Public seed from which the refresh nonces (v27) or transfer secrets (vDOLDPLUS) 696 * per coin candidate were derived from. 697 */ 698 struct TALER_PublicRefreshMasterSeedP refresh_seed; 699 700 /** 701 * How much value is being melted? This amount includes the fees, 702 * so the final amount contributed to the melt is this value minus 703 * the fee for melting the coin. We include the fee in what is 704 * being signed so that we can verify a reserve's remaining total 705 * balance without needing to access the respective denomination key 706 * information each time. 707 */ 708 struct TALER_Amount amount_with_fee; 709 710 /** 711 * Number of coins to be refreshed into 712 */ 713 size_t num_coins; 714 715 /** 716 * The running hash over all kappa * @a num_coins blinded coin envelopes, provided by 717 * the client. 718 */ 719 struct TALER_HashBlindedPlanchetsP planchets_h; 720 721 /** 722 * The running hash over all chosen (noreveal_index) @a num_coins blinded coin envelopes. 723 */ 724 struct TALER_HashBlindedPlanchetsP selected_h; 725 726 /** 727 * Array of @a num_coins denomination signatures of the blinded coins. 728 */ 729 struct TALER_BlindedDenominationSignature *denom_sigs; 730 731 /** 732 * If @a rc_version is not #TALER_REFRESH_COMMITMENT_VERSION_LEGACY_V27, 733 * the client performed a vDOLDPLUS refresh, 734 * and has provided @a num_coins * kappa transfer public keys. 735 * This is the chosen (at index @a noreveal_index) array of @a num_coins transfer public keys. 736 */ 737 struct TALER_TransferPublicKeyP *transfer_pubs; 738 739 /** 740 * Array of @a num_coins serial id's of the denominations. 741 * If @e coin.no_age_commitment is false, the denominations 742 * MUST support age restriction. 743 */ 744 uint64_t *denom_serials; 745 746 /** 747 * Index (smaller #TALER_CNC_KAPPA) which the exchange chose to not 748 * to be revealed during cut and choose. 749 */ 750 uint32_t noreveal_index; 751 752 /** 753 * True, if the client has successfully performed the reveal step 754 */ 755 bool revealed; 756 757 /** 758 * If true, no @e blinding_seed is set and @e num_cs_r_values is 0. 759 */ 760 bool no_blinding_seed; 761 762 /** 763 * If @e no_blinding_seed is false, the blinding seed for the nonces needed for 764 * blind CS signatures. 765 */ 766 struct TALER_BlindingMasterSeedP blinding_seed; 767 768 /** 769 * Number of elements in @e cs_r_values. 770 */ 771 size_t num_cs_r_values; 772 773 /** 774 * Array @e num_cs_r_values of public R-values for CS that were generated from the 775 * @e blinding_seed, a coin's index and the denomination's private key during the 776 * the /melt request, to ensure idempotency in case of expiration of a denomination. 777 * NULL if @e num_cs_r_values is 0. 778 */ 779 struct GNUNET_CRYPTO_CSPublicRPairP *cs_r_values; 780 781 /** 782 * If @e num_cs_r_values is not 0, the bitvector of choices for the pairs 783 * in @e cs_r_values that was made by the exchange. The vector is in NBO 784 * and the lowest bit represents the choice for the pair at index 0 into @e cs_r_values; 785 */ 786 uint64_t cs_r_choices; 787 788 /** 789 * [out]-Array of @a num_coins hashes of the public keys of the denominations 790 * identified by @e denom_serials. This field is set when calling 791 * get_refresh 792 */ 793 struct TALER_DenominationHashP *denom_pub_hashes; 794 795 /** 796 * [out]-Row of this operation in the `refresh` table. 797 * Set by get_refresh(), zero otherwise. 798 */ 799 uint64_t refresh_id; 800 }; 801 802 803 /** 804 * Generic KYC status for some operation. 805 */ 806 struct TALER_EXCHANGEDB_KycStatus 807 { 808 809 /** 810 * Account public key that is currently associated 811 * with the account. Only set if @e have_account_pub 812 * is true. 813 */ 814 union TALER_AccountPublicKeyP account_pub; 815 816 /** 817 * Number that identifies the KYC requirement the operation 818 * was about. 819 */ 820 uint64_t requirement_row; 821 822 /** 823 * True if @e account_pub is set. 824 */ 825 bool have_account_pub; 826 827 /** 828 * True if the KYC status is "satisfied". 829 */ 830 bool ok; 831 832 }; 833 834 835 /** 836 * Function called with details about incoming wire transfers. 837 * 838 * @param cls closure 839 * @param rowid unique serial ID for the refresh session in our DB 840 * @param reserve_pub public key of the reserve (also the wire subject) 841 * @param credit amount that was received 842 * @param sender_account_details information about the sender's bank account, in payto://-format 843 * @param wire_reference unique identifier for the wire transfer 844 * @param execution_date when did we receive the funds 845 * @return #GNUNET_OK to continue to iterate, #GNUNET_SYSERR to stop 846 */ 847 #ifndef TALER_EXCHANGEDB_RESERVE_IN_RESULT_CLOSURE 848 #define TALER_EXCHANGEDB_RESERVE_IN_RESULT_CLOSURE void 849 #endif 850 typedef enum GNUNET_GenericReturnValue 851 (*TALER_EXCHANGEDB_ReserveInCallback)( 852 TALER_EXCHANGEDB_RESERVE_IN_RESULT_CLOSURE *cls, 853 uint64_t rowid, 854 const struct TALER_ReservePublicKeyP *reserve_pub, 855 const struct TALER_Amount *credit, 856 const struct TALER_FullPayto sender_account_details, 857 uint64_t wire_reference, 858 struct GNUNET_TIME_Timestamp execution_date); 859 860 861 /** 862 * Function called with the results of the lookup of the 863 * wire transfer data of the exchange. 864 * 865 * @param cls closure 866 * @param rowid identifier of the respective row in the database 867 * @param date timestamp of the wire transfer (roughly) 868 * @param wtid wire transfer subject 869 * @param payto_uri details of the receiver, URI in payto://-format 870 * @param amount amount that was wired 871 * @return #GNUNET_OK to continue, #GNUNET_SYSERR to stop iteration 872 */ 873 #ifndef TALER_EXCHANGEDB_WIRE_TRANSFER_OUT_RESULT_CLOSURE 874 #define TALER_EXCHANGEDB_WIRE_TRANSFER_OUT_RESULT_CLOSURE void 875 #endif 876 typedef enum GNUNET_GenericReturnValue 877 (*TALER_EXCHANGEDB_WireTransferOutCallback)( 878 TALER_EXCHANGEDB_WIRE_TRANSFER_OUT_RESULT_CLOSURE *cls, 879 uint64_t rowid, 880 struct GNUNET_TIME_Timestamp date, 881 const struct TALER_WireTransferIdentifierRawP *wtid, 882 const struct TALER_FullPayto payto_uri, 883 const struct TALER_Amount *amount); 884 885 886 /** 887 * Function called with details about expired reserves. 888 * 889 * @param cls closure 890 * @param reserve_pub public key of the reserve 891 * @param left amount left in the reserve 892 * @param account_details information about the reserve's bank account, in payto://-format 893 * @param expiration_date when did the reserve expire 894 * @param close_request_row row that caused the reserve 895 * to be closed, 0 if it expired without request 896 * @return #GNUNET_OK on success, 897 * #GNUNET_NO to retry 898 * #GNUNET_SYSERR on hard failures (exit) 899 */ 900 #ifndef TALER_EXCHANGEDB_RESERVE_EXPIRED_RESULT_CLOSURE 901 #define TALER_EXCHANGEDB_RESERVE_EXPIRED_RESULT_CLOSURE void 902 #endif 903 typedef enum GNUNET_GenericReturnValue 904 (*TALER_EXCHANGEDB_ReserveExpiredCallback)( 905 TALER_EXCHANGEDB_RESERVE_EXPIRED_RESULT_CLOSURE *cls, 906 const struct TALER_ReservePublicKeyP *reserve_pub, 907 const struct TALER_Amount *left, 908 const struct TALER_FullPayto account_details, 909 struct GNUNET_TIME_Timestamp expiration_date, 910 uint64_t close_request_row); 911 912 913 /** 914 * Callback that is given AML-relevant transfer data. 915 * 916 * @param cls closure 917 * @param row_id current row in AML status table 918 * @param payto_uri account involved with the wire transfer 919 * @param execution_time when was the transfer made 920 * @param amount wire amount of the transfer 921 */ 922 #ifndef TALER_EXCHANGEDB_AML_TRANSFER_RESULT_CLOSURE 923 #define TALER_EXCHANGEDB_AML_TRANSFER_RESULT_CLOSURE void 924 #endif 925 typedef void 926 (*TALER_EXCHANGEDB_AmlTransferCallback)( 927 TALER_EXCHANGEDB_AML_TRANSFER_RESULT_CLOSURE *cls, 928 uint64_t row_id, 929 const char *payto_uri, 930 struct GNUNET_TIME_Absolute execution_time, 931 const struct TALER_Amount *amount); 932 933 934 /** 935 * Initialize the database connection. 936 * 937 * @param cfg configuration to use 938 * @return NULL on failure 939 */ 940 struct TALER_EXCHANGEDB_PostgresContext * 941 TALER_EXCHANGEDB_connect ( 942 const struct GNUNET_CONFIGURATION_Handle *cfg); 943 944 945 /** 946 * Initialize the database connection for administration. 947 * Disables the check that the database schema is current. 948 * 949 * @param cfg configuration to use 950 * @return NULL on failure 951 */ 952 struct TALER_EXCHANGEDB_PostgresContext * 953 TALER_EXCHANGEDB_connect_admin ( 954 const struct GNUNET_CONFIGURATION_Handle *cfg); 955 956 957 /** 958 * Shutdown the database connection. 959 * 960 * @param[in] pg connection to drop 961 */ 962 void 963 TALER_EXCHANGEDB_disconnect (struct TALER_EXCHANGEDB_PostgresContext *pg); 964 965 966 /** 967 * Meta data about a denomination public key. 968 * If this is changed, you must also adjust 969 * taler-exchange-httpd-post-management-keys.c::denomination_meta_cmp(). 970 */ 971 struct TALER_EXCHANGEDB_DenominationKeyMetaData 972 { 973 /** 974 * Serial of the denomination key as in the DB. 975 * Can be used calls to stored procedures in order to spare 976 * additional lookups. 977 */ 978 uint64_t serial; 979 980 /** 981 * Start time of the validity period for this key. 982 */ 983 struct GNUNET_TIME_Timestamp start; 984 985 /** 986 * The exchange will sign fresh coins between @e start and this time. 987 * @e expire_withdraw will be somewhat larger than @e start to 988 * ensure a sufficiently large anonymity set, while also allowing 989 * the Exchange to limit the financial damage in case of a key being 990 * compromised. Thus, exchanges with low volume are expected to have a 991 * longer withdraw period (@e expire_withdraw - @e start) than exchanges 992 * with high transaction volume. The period may also differ between 993 * types of coins. A exchange may also have a few denomination keys 994 * with the same value with overlapping validity periods, to address 995 * issues such as clock skew. 996 */ 997 struct GNUNET_TIME_Timestamp expire_withdraw; 998 999 /** 1000 * Coins signed with the denomination key must be spent or refreshed 1001 * between @e start and this expiration time. After this time, the 1002 * exchange will refuse transactions involving this key as it will 1003 * "drop" the table with double-spending information (shortly after) 1004 * this time. Note that wallets should refresh coins significantly 1005 * before this time to be on the safe side. @e expire_deposit must be 1006 * significantly larger than @e expire_withdraw (by months or even 1007 * years). 1008 */ 1009 struct GNUNET_TIME_Timestamp expire_deposit; 1010 1011 /** 1012 * When do signatures with this denomination key become invalid? 1013 * After this point, these signatures cannot be used in (legal) 1014 * disputes anymore, as the Exchange is then allowed to destroy its side 1015 * of the evidence. @e expire_legal is expected to be significantly 1016 * larger than @e expire_deposit (by a year or more). 1017 */ 1018 struct GNUNET_TIME_Timestamp expire_legal; 1019 1020 /** 1021 * The value of the coins signed with this denomination key. 1022 */ 1023 struct TALER_Amount value; 1024 1025 /** 1026 * The fees the exchange charges for operations with 1027 * coins of this denomination. 1028 */ 1029 struct TALER_DenomFeeSet fees; 1030 1031 /** 1032 * Age restriction for the denomination. (can be zero). If not zero, the bits 1033 * set in the mask mark the edges at the beginning of a next age group. F.e. 1034 * for the age groups 1035 * 0-7, 8-9, 10-11, 12-14, 14-15, 16-17, 18-21, 21-* 1036 * the following bits are set: 1037 * 1038 * 31 24 16 8 0 1039 * | | | | | 1040 * oooooooo oo1oo1o1 o1o1o1o1 ooooooo1 1041 * 1042 * A value of 0 means that the denomination does not support the extension for 1043 * age-restriction. 1044 */ 1045 struct TALER_AgeMask age_mask; 1046 }; 1047 1048 1049 /** 1050 * Information about an account from the configuration. 1051 */ 1052 struct TALER_EXCHANGEDB_AccountInfo 1053 { 1054 /** 1055 * Authentication data. Only parsed if 1056 * #TALER_EXCHANGEDB_ALO_AUTHDATA was set. 1057 */ 1058 const struct TALER_BANK_AuthenticationData *auth; 1059 1060 /** 1061 * Section in the configuration file that specifies the 1062 * account. Must start with "exchange-account-". 1063 */ 1064 const char *section_name; 1065 1066 /** 1067 * Name of the wire method used by this account. 1068 */ 1069 const char *method; 1070 1071 /** 1072 * Full payto://-URI of the account. Do not free(), aliased 1073 * with the underlying `struct WireAccount`. 1074 */ 1075 struct TALER_FullPayto payto_uri; 1076 1077 /** 1078 * true if this account is enabled to be debited 1079 * by the taler-exchange-aggregator. 1080 */ 1081 bool debit_enabled; 1082 1083 /** 1084 * true if this account is enabled to be credited by wallets 1085 * and needs to be watched by the taler-exchange-wirewatch. 1086 * Also, the account will only be included in /wire if credit 1087 * is enabled. 1088 */ 1089 bool credit_enabled; 1090 }; 1091 1092 1093 /** 1094 * Function called with information about a wire account. 1095 * 1096 * @param cls closure 1097 * @param ai account information 1098 */ 1099 #ifndef TALER_EXCHANGEDB_ACCOUNT_RESULT_CLOSURE 1100 #define TALER_EXCHANGEDB_ACCOUNT_RESULT_CLOSURE void 1101 #endif 1102 typedef void 1103 (*TALER_EXCHANGEDB_AccountCallback)( 1104 TALER_EXCHANGEDB_ACCOUNT_RESULT_CLOSURE *cls, 1105 const struct TALER_EXCHANGEDB_AccountInfo *ai); 1106 1107 1108 /** 1109 * Return information about all accounts that 1110 * were loaded by #TALER_EXCHANGEDB_load_accounts(). 1111 * 1112 * @param cb callback to invoke 1113 * @param cb_cls closure for @a cb 1114 */ 1115 void 1116 TALER_EXCHANGEDB_find_accounts (TALER_EXCHANGEDB_AccountCallback cb, 1117 TALER_EXCHANGEDB_ACCOUNT_RESULT_CLOSURE *cb_cls) 1118 ; 1119 1120 1121 /** 1122 * Find the wire plugin for the given payto:// URL. 1123 * Only useful after the accounts have been loaded 1124 * using #TALER_EXCHANGEDB_load_accounts(). 1125 * 1126 * @param method wire method we need an account for 1127 * @return NULL on error 1128 */ 1129 const struct TALER_EXCHANGEDB_AccountInfo * 1130 TALER_EXCHANGEDB_find_account_by_method (const char *method); 1131 1132 1133 /** 1134 * Find the wire plugin for the given payto:// URL 1135 * Only useful after the accounts have been loaded 1136 * using #TALER_EXCHANGEDB_load_accounts(). 1137 * 1138 * @param url wire address we need an account for 1139 * @return NULL on error 1140 */ 1141 const struct TALER_EXCHANGEDB_AccountInfo * 1142 TALER_EXCHANGEDB_find_account_by_payto_uri ( 1143 const struct TALER_FullPayto url); 1144 1145 1146 /** 1147 * Options for #TALER_EXCHANGEDB_load_accounts() 1148 */ 1149 enum TALER_EXCHANGEDB_AccountLoaderOptions 1150 { 1151 TALER_EXCHANGEDB_ALO_NONE = 0, 1152 1153 /** 1154 * Load accounts enabled for DEBITs. 1155 */ 1156 TALER_EXCHANGEDB_ALO_DEBIT = 1, 1157 1158 /** 1159 * Load accounts enabled for CREDITs. 1160 */ 1161 TALER_EXCHANGEDB_ALO_CREDIT = 2, 1162 1163 /** 1164 * Load authentication data from the 1165 * "taler-accountcredentials-" section 1166 * to access the account at the bank. 1167 */ 1168 TALER_EXCHANGEDB_ALO_AUTHDATA = 4 1169 }; 1170 1171 1172 /** 1173 * Load account information op the exchange from @a cfg. 1174 * 1175 * @param cfg configuration to load from 1176 * @param options loader options 1177 * @return #GNUNET_OK on success, #GNUNET_NO if no accounts are configured 1178 */ 1179 enum GNUNET_GenericReturnValue 1180 TALER_EXCHANGEDB_load_accounts ( 1181 const struct GNUNET_CONFIGURATION_Handle *cfg, 1182 enum TALER_EXCHANGEDB_AccountLoaderOptions options); 1183 1184 1185 /** 1186 * Free resources allocated by 1187 * #TALER_EXCHANGEDB_load_accounts(). 1188 */ 1189 void 1190 TALER_EXCHANGEDB_unload_accounts (void); 1191 1192 1193 #endif