anastasis_service.h (26202B)
1 /* 2 This file is part of Anastasis 3 Copyright (C) 2019-2022 Anastasis SARL 4 5 Anastasis 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 Anastasis 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 Anastasis; see the file COPYING.LIB. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/anastasis_service.h 18 * @brief C interface of libanastasisrest, a C library to use merchant's HTTP API 19 * @author Christian Grothoff 20 * @author Dennis Neufeld 21 * @author Dominik Meister 22 */ 23 #ifndef ANASTASIS_SERVICE_H 24 #define ANASTASIS_SERVICE_H 25 26 #include "anastasis_crypto_lib.h" 27 #include "anastasis_util_lib.h" 28 #include <gnunet/gnunet_curl_lib.h> 29 #include <jansson.h> 30 31 32 /** 33 * Anastasis authorization method configuration 34 */ 35 struct ANASTASIS_AuthorizationMethodConfig 36 { 37 /** 38 * Type of the method, i.e. "question". 39 */ 40 const char *type; 41 42 /** 43 * Fee charged for accessing key share using this method, in the 44 * provider's primary currency. Kept because a provider speaking 45 * protocol version 2 offers nothing else. 46 */ 47 struct TALER_Amount usage_fee; 48 49 /** 50 * Fee charged for accessing key share using this method, one entry 51 * per currency the provider accepts. Synthesized from @e usage_fee 52 * for a provider that does not offer the plural field yet. Empty 53 * means the method is free. 54 */ 55 struct TALER_AmountList usage_fees; 56 }; 57 58 59 /** 60 * @brief Anastasis configuration data. 61 */ 62 struct ANASTASIS_Config 63 { 64 65 /** 66 * HTTP status returned. 67 */ 68 unsigned int http_status; 69 70 /** 71 * Taler-specific error code, #TALER_EC_NONE on success. 72 */ 73 enum TALER_ErrorCode ec; 74 75 /** 76 * Full response in JSON, if provided. 77 */ 78 const json_t *response; 79 80 /** 81 * Details depending on @e http_status. 82 */ 83 union 84 { 85 86 /** 87 * Details on #MHD_HTTP_OK. 88 */ 89 struct 90 { 91 92 /** 93 * Protocol version supported by the server. 94 */ 95 const char *version; 96 97 /** 98 * Business name of the anastasis provider. 99 */ 100 const char *business_name; 101 102 /** 103 * Array of authorization methods supported by the server. 104 */ 105 const struct ANASTASIS_AuthorizationMethodConfig *methods; 106 107 /** 108 * Length of the @e methods array. 109 */ 110 unsigned int methods_length; 111 112 /** 113 * Maximum size of an upload in megabytes. 114 */ 115 uint32_t storage_limit_in_megabytes; 116 117 /** 118 * Currencies the provider prices its service in, primary 119 * currency first. For a provider speaking protocol version 2 120 * this is the single currency of @e annual_fee. 121 */ 122 const char **currencies; 123 124 /** 125 * Length of the @e currencies array. 126 */ 127 unsigned int currencies_len; 128 129 /** 130 * Annual fee for an account / policy upload, in the primary 131 * currency. 132 */ 133 struct TALER_Amount annual_fee; 134 135 /** 136 * Annual fee for an account / policy upload, per currency. 137 * Synthesized from @e annual_fee for a provider speaking 138 * protocol version 2. 139 */ 140 struct TALER_AmountList annual_fees; 141 142 /** 143 * Fee for a truth upload, in the primary currency. 144 */ 145 struct TALER_Amount truth_upload_fee; 146 147 /** 148 * Fee for a truth upload, per currency. 149 */ 150 struct TALER_AmountList truth_upload_fees; 151 152 /** 153 * Maximum legal liability for data loss covered by the 154 * provider, in the primary currency. 155 */ 156 struct TALER_Amount liability_limit; 157 158 /** 159 * Maximum legal liability for data loss covered by the 160 * provider, per currency. 161 */ 162 struct TALER_AmountList liability_limits; 163 164 /** 165 * Provider salt. 166 */ 167 struct ANASTASIS_CRYPTO_ProviderSaltP provider_salt; 168 } ok; 169 170 } details; 171 172 }; 173 174 175 /** 176 * Function called with the result of a /config request. 177 * Note that an HTTP status of #MHD_HTTP_OK is no guarantee 178 * that @a acfg is non-NULL. @a acfg is non-NULL only if 179 * the server provided an acceptable response. 180 * 181 * @param cls closure 182 * @param acfg configuration obtained, NULL if we could not parse it 183 */ 184 #ifndef ANASTASIS_CONFIG_RESULT_CLOSURE 185 /** 186 * Type of the closure for #ANASTASIS_ConfigCallback. 187 */ 188 #define ANASTASIS_CONFIG_RESULT_CLOSURE void 189 #endif 190 typedef void 191 (*ANASTASIS_ConfigCallback)(ANASTASIS_CONFIG_RESULT_CLOSURE *cls, 192 const struct ANASTASIS_Config *acfg); 193 194 195 /** 196 * @brief A Config Operation Handle 197 */ 198 struct ANASTASIS_ConfigOperation; 199 200 201 /** 202 * Run a GET /config request against the Anastasis backend. 203 * 204 * @param ctx CURL context to use 205 * @param base_url base URL of the Anastasis backend 206 * @param cb function to call with the results 207 * @param cb_cls closure for @a cb 208 * @return handle to cancel the operation 209 */ 210 struct ANASTASIS_ConfigOperation * 211 ANASTASIS_get_config (struct GNUNET_CURL_Context *ctx, 212 const char *base_url, 213 ANASTASIS_ConfigCallback cb, 214 ANASTASIS_CONFIG_RESULT_CLOSURE *cb_cls); 215 216 217 /** 218 * Cancel ongoing #ANASTASIS_get_config() request. 219 * 220 * @param co configuration request to cancel. 221 */ 222 void 223 ANASTASIS_config_cancel (struct ANASTASIS_ConfigOperation *co); 224 225 226 /****** POLICY API ******/ 227 228 229 /** 230 * Detailed meta data result. 231 */ 232 struct ANASTASIS_MetaDataEntry 233 { 234 235 /** 236 * Timestamp of the backup at the server. 237 */ 238 struct GNUNET_TIME_Timestamp server_time; 239 240 /** 241 * The encrypted meta data we downloaded. 242 */ 243 const void *meta_data; 244 245 /** 246 * Number of bytes in @e meta_data. 247 */ 248 size_t meta_data_size; 249 250 /** 251 * Policy version this @e meta_data is for. 252 */ 253 uint32_t version; 254 }; 255 256 257 /** 258 * Detailed results for meta data download. 259 */ 260 struct ANASTASIS_MetaDownloadDetails 261 { 262 263 /** 264 * HTTP status returned. 265 */ 266 unsigned int http_status; 267 268 /** 269 * Taler-specific error code, #TALER_EC_NONE on success. 270 */ 271 enum TALER_ErrorCode ec; 272 273 /** 274 * Full response in JSON, if provided. 275 */ 276 const json_t *response; 277 278 /** 279 * Details depending on @e http_status. 280 */ 281 union 282 { 283 284 /** 285 * Details on #MHD_HTTP_OK. 286 */ 287 struct 288 { 289 290 /** 291 * Version-sorted array of meta data we downloaded. 292 */ 293 const struct ANASTASIS_MetaDataEntry *metas; 294 295 /** 296 * Number of entries in @e metas. 297 */ 298 size_t metas_length; 299 300 } ok; 301 302 } details; 303 }; 304 305 306 /** 307 * Callback to process a GET /policy/$POL/meta request 308 * 309 * @param cls closure 310 * @param dd the response details 311 */ 312 #ifndef ANASTASIS_POLICY_META_LOOKUP_RESULT_CLOSURE 313 /** 314 * Type of the closure for #ANASTASIS_PolicyMetaLookupCallback. 315 */ 316 #define ANASTASIS_POLICY_META_LOOKUP_RESULT_CLOSURE void 317 #endif 318 typedef void 319 (*ANASTASIS_PolicyMetaLookupCallback) ( 320 ANASTASIS_POLICY_META_LOOKUP_RESULT_CLOSURE *cls, 321 const struct ANASTASIS_MetaDownloadDetails *dd); 322 323 324 /** 325 * Does a GET /policy/$POL/meta. 326 * 327 * @param ctx execution context 328 * @param backend_url base URL of the merchant backend 329 * @param anastasis_pub public key of the user's account 330 * @param max_version maximum version number to fetch 331 * @param cb callback which will work the response gotten from the backend 332 * @param cb_cls closure to pass to the callback 333 * @return handle for this operation, NULL upon errors 334 */ 335 struct ANASTASIS_PolicyMetaLookupOperation * 336 ANASTASIS_policy_meta_lookup ( 337 struct GNUNET_CURL_Context *ctx, 338 const char *backend_url, 339 const struct ANASTASIS_CRYPTO_AccountPublicKeyP *anastasis_pub, 340 uint32_t max_version, 341 ANASTASIS_PolicyMetaLookupCallback cb, 342 ANASTASIS_POLICY_META_LOOKUP_RESULT_CLOSURE *cb_cls); 343 344 345 /** 346 * Cancel a GET /policy/$POL/meta request. 347 * 348 * @param plo cancel the policy lookup operation 349 */ 350 void 351 ANASTASIS_policy_meta_lookup_cancel ( 352 struct ANASTASIS_PolicyMetaLookupOperation *plo); 353 354 355 /** 356 * Detailed results from the successful download. 357 */ 358 struct ANASTASIS_DownloadDetails 359 { 360 361 /** 362 * HTTP status returned. 363 */ 364 unsigned int http_status; 365 366 /** 367 * Taler-specific error code, #TALER_EC_NONE on success. 368 */ 369 enum TALER_ErrorCode ec; 370 371 /** 372 * Details depending on @e http_status. 373 */ 374 union 375 { 376 377 /** 378 * Details on #MHD_HTTP_OK. 379 */ 380 struct 381 { 382 383 /** 384 * Signature (already verified). 385 */ 386 struct ANASTASIS_AccountSignatureP sig; 387 388 /** 389 * Hash over @e policy and @e policy_size. 390 */ 391 struct GNUNET_HashCode curr_policy_hash; 392 393 /** 394 * The backup we downloaded. 395 */ 396 const void *policy; 397 398 /** 399 * Number of bytes in @e backup. 400 */ 401 size_t policy_size; 402 403 /** 404 * Policy version returned by the service. 405 */ 406 uint32_t version; 407 } ok; 408 409 } details; 410 411 }; 412 413 414 /** 415 * Handle for a GET /policy operation. 416 */ 417 struct ANASTASIS_PolicyLookupOperation; 418 419 420 /** 421 * Callback to process a GET /policy request 422 * 423 * @param cls closure 424 * @param dd the response details 425 */ 426 #ifndef ANASTASIS_POLICY_LOOKUP_RESULT_CLOSURE 427 /** 428 * Type of the closure for #ANASTASIS_PolicyLookupCallback. 429 */ 430 #define ANASTASIS_POLICY_LOOKUP_RESULT_CLOSURE void 431 #endif 432 typedef void 433 (*ANASTASIS_PolicyLookupCallback) (ANASTASIS_POLICY_LOOKUP_RESULT_CLOSURE *cls, 434 const struct ANASTASIS_DownloadDetails *dd); 435 436 437 /** 438 * Does a GET /policy. 439 * 440 * @param ctx execution context 441 * @param backend_url base URL of the merchant backend 442 * @param anastasis_pub public key of the user's account 443 * @param cb callback which will work the response gotten from the backend 444 * @param cb_cls closure to pass to the callback 445 * @return handle for this operation, NULL upon errors 446 */ 447 struct ANASTASIS_PolicyLookupOperation * 448 ANASTASIS_policy_lookup ( 449 struct GNUNET_CURL_Context *ctx, 450 const char *backend_url, 451 const struct ANASTASIS_CRYPTO_AccountPublicKeyP *anastasis_pub, 452 ANASTASIS_PolicyLookupCallback cb, 453 ANASTASIS_POLICY_LOOKUP_RESULT_CLOSURE *cb_cls); 454 455 456 /** 457 * Does a GET /policy for a specific version. 458 * 459 * @param ctx execution context 460 * @param backend_url base URL of the merchant backend 461 * @param anastasis_pub public key of the user's account 462 * @param cb callback which will work the response gotten from the backend 463 * @param cb_cls closure to pass to the callback 464 * @param version version of the policy to be requested 465 * @return handle for this operation, NULL upon errors 466 */ 467 struct ANASTASIS_PolicyLookupOperation * 468 ANASTASIS_policy_lookup_version ( 469 struct GNUNET_CURL_Context *ctx, 470 const char *backend_url, 471 const struct ANASTASIS_CRYPTO_AccountPublicKeyP *anastasis_pub, 472 ANASTASIS_PolicyLookupCallback cb, 473 ANASTASIS_POLICY_LOOKUP_RESULT_CLOSURE *cb_cls, 474 unsigned int version); 475 476 477 /** 478 * Cancel a GET /policy request. 479 * 480 * @param plo cancel the policy lookup operation 481 */ 482 void 483 ANASTASIS_policy_lookup_cancel ( 484 struct ANASTASIS_PolicyLookupOperation *plo); 485 486 487 /** 488 * Handle for a POST /policy operation. 489 */ 490 struct ANASTASIS_PolicyStoreOperation; 491 492 493 /** 494 * High-level ways how an upload may conclude. 495 */ 496 enum ANASTASIS_UploadStatus 497 { 498 /** 499 * Backup was successfully made. 500 */ 501 ANASTASIS_US_SUCCESS = 0, 502 503 /** 504 * Account expired or payment was explicitly requested 505 * by the client. 506 */ 507 ANASTASIS_US_PAYMENT_REQUIRED, 508 509 /** 510 * HTTP interaction failed, see HTTP status. 511 */ 512 ANASTASIS_US_HTTP_ERROR, 513 514 /** 515 * We had an internal error (not sure this can happen, 516 * but reserved for HTTP 400 status codes). 517 */ 518 ANASTASIS_US_CLIENT_ERROR, 519 520 /** 521 * Server had an internal error. 522 */ 523 ANASTASIS_US_SERVER_ERROR, 524 525 /** 526 * Truth already exists. Not applicable for policy uploads. 527 */ 528 ANASTASIS_US_CONFLICTING_TRUTH 529 }; 530 531 532 /** 533 * Result of an upload. 534 */ 535 struct ANASTASIS_UploadDetails 536 { 537 /** 538 * High level status of the upload operation. Determines @e details. 539 */ 540 enum ANASTASIS_UploadStatus us; 541 542 /** 543 * HTTP status code. 544 */ 545 unsigned int http_status; 546 547 /** 548 * Taler error code. 549 */ 550 enum TALER_ErrorCode ec; 551 552 union 553 { 554 555 struct 556 { 557 /** 558 * Hash of the stored recovery data, returned if 559 * @e us is #ANASTASIS_US_SUCCESS. 560 */ 561 const struct GNUNET_HashCode *curr_backup_hash; 562 563 /** 564 * At what time is the provider set to forget this 565 * policy (because the account expires)? 566 */ 567 struct GNUNET_TIME_Timestamp policy_expiration; 568 569 /** 570 * Version number of the resulting policy. 571 */ 572 unsigned long long policy_version; 573 574 } success; 575 576 /** 577 * Details about required payment. 578 */ 579 struct 580 { 581 /** 582 * A taler://pay/-URI with a request to pay the annual fee for 583 * the service. Returned if @e us is #ANASTASIS_US_PAYMENT_REQUIRED. 584 */ 585 const char *payment_request; 586 587 /** 588 * The payment secret (aka order ID) extracted from the @e payment_request. 589 */ 590 struct ANASTASIS_PaymentSecretP ps; 591 } payment; 592 593 } details; 594 }; 595 596 597 /** 598 * Callback to process a POST /policy request 599 * 600 * @param cls closure 601 * @param up the decoded response body 602 */ 603 #ifndef ANASTASIS_POLICY_STORE_RESULT_CLOSURE 604 /** 605 * Type of the closure for #ANASTASIS_PolicyStoreCallback. 606 */ 607 #define ANASTASIS_POLICY_STORE_RESULT_CLOSURE void 608 #endif 609 typedef void 610 (*ANASTASIS_PolicyStoreCallback) (ANASTASIS_POLICY_STORE_RESULT_CLOSURE *cls, 611 const struct ANASTASIS_UploadDetails *up); 612 613 614 /** 615 * Store policies, does a POST /policy/$ACCOUNT_PUB 616 * 617 * @param ctx the CURL context used to connect to the backend 618 * @param backend_url backend's base URL, including final "/" 619 * @param anastasis_priv private key of the user's account 620 * @param recovery_data policy data to be stored 621 * @param recovery_data_size number of bytes in @a recovery_data 622 * @param recovery_meta_data policy meta data to be stored 623 * @param recovery_meta_data_size number of bytes in @a recovery_meta_data 624 * @param payment_years_requested for how many years would the client like the service to store the truth? 625 * @param payment_secret payment identifier of last payment 626 * @param payment_timeout how long to wait for the payment, use 627 * #GNUNET_TIME_UNIT_ZERO to let the server pick 628 * @param cb callback processing the response from /policy 629 * @param cb_cls closure for @a cb 630 * @return handle for the operation 631 */ 632 struct ANASTASIS_PolicyStoreOperation * 633 ANASTASIS_policy_store ( 634 struct GNUNET_CURL_Context *ctx, 635 const char *backend_url, 636 const struct ANASTASIS_CRYPTO_AccountPrivateKeyP *anastasis_priv, 637 const void *recovery_data, 638 size_t recovery_data_size, 639 const void *recovery_meta_data, 640 size_t recovery_meta_data_size, 641 uint32_t payment_years_requested, 642 const struct ANASTASIS_PaymentSecretP *payment_secret, 643 struct GNUNET_TIME_Relative payment_timeout, 644 ANASTASIS_PolicyStoreCallback cb, 645 ANASTASIS_POLICY_STORE_RESULT_CLOSURE *cb_cls); 646 647 648 /** 649 * Cancel a POST /policy request. 650 * 651 * @param pso the policy store operation to cancel 652 */ 653 void 654 ANASTASIS_policy_store_cancel ( 655 struct ANASTASIS_PolicyStoreOperation *pso); 656 657 658 /****** TRUTH API ******/ 659 660 661 /** 662 * Handle for a POST /truth operation. 663 */ 664 struct ANASTASIS_TruthStoreOperation; 665 666 667 /** 668 * Callback to process a POST /truth request 669 * 670 * @param cls closure 671 * @param obj the response body 672 */ 673 #ifndef ANASTASIS_TRUTH_STORE_RESULT_CLOSURE 674 /** 675 * Type of the closure for #ANASTASIS_TruthStoreCallback. 676 */ 677 #define ANASTASIS_TRUTH_STORE_RESULT_CLOSURE void 678 #endif 679 typedef void 680 (*ANASTASIS_TruthStoreCallback) (ANASTASIS_TRUTH_STORE_RESULT_CLOSURE *cls, 681 const struct ANASTASIS_UploadDetails *up); 682 683 684 /** 685 * Store Truth, does a POST /truth/$UUID 686 * 687 * @param ctx the CURL context used to connect to the backend 688 * @param backend_url backend's base URL, including final "/" 689 * @param uuid unique identification of the Truth Upload 690 * @param type type of the authorization method 691 * @param encrypted_keyshare key material to return to the client upon authorization 692 * @param truth_mime mime type of @e encrypted_truth (after decryption) 693 * @param encrypted_truth_size number of bytes in @e encrypted_truth 694 * @param encrypted_truth contains the @a type-specific authorization data 695 * @param payment_years_requested for how many years would the client like the service to store the truth? 696 * @param payment_timeout how long to wait for the payment, use 697 * #GNUNET_TIME_UNIT_ZERO to let the server pick 698 * @param cb callback processing the response from /truth 699 * @param cb_cls closure for cb 700 * @return handle for the operation 701 */ 702 struct ANASTASIS_TruthStoreOperation * 703 ANASTASIS_truth_store ( 704 struct GNUNET_CURL_Context *ctx, 705 const char *backend_url, 706 const struct ANASTASIS_CRYPTO_TruthUUIDP *uuid, 707 const char *type, 708 const struct ANASTASIS_CRYPTO_EncryptedKeyShareP *encrypted_keyshare, 709 const char *truth_mime, 710 size_t encrypted_truth_size, 711 const void *encrypted_truth, 712 uint32_t payment_years_requested, 713 struct GNUNET_TIME_Relative payment_timeout, 714 ANASTASIS_TruthStoreCallback cb, 715 ANASTASIS_TRUTH_STORE_RESULT_CLOSURE *cb_cls); 716 717 718 /** 719 * Cancel a POST /truth request. 720 * 721 * @param tso the truth store operation 722 */ 723 void 724 ANASTASIS_truth_store_cancel ( 725 struct ANASTASIS_TruthStoreOperation *tso); 726 727 728 /** 729 * Possible ways how to proceed with a challenge. 730 */ 731 enum ANASTASIS_ChallengeDetailType 732 { 733 734 /** 735 * A challenge TAN was written to a file. 736 * The name of the file is provided. 737 */ 738 ANASTASIS_CS_FILE_WRITTEN, 739 740 /** 741 * A challenge TAN was sent to the customer. 742 * A hint may be provided as to the address used. 743 */ 744 ANASTASIS_CS_TAN_SENT, 745 746 /** 747 * A challenge TAN was already recently sent to the customer. 748 * A hint may be provided as to the address used. 749 */ 750 ANASTASIS_CS_TAN_ALREADY_SENT, 751 752 /** 753 * The customer should wire funds to the bank 754 * account address provided. 755 */ 756 ANASTASIS_CS_WIRE_FUNDS 757 758 }; 759 760 761 /** 762 * This structure contains information about where to wire the funds 763 * to authenticate as well as a hint as to which bank account to send 764 * the funds from. 765 */ 766 struct ANASTASIS_WireFundsDetails 767 { 768 769 /** 770 * Answer code expected. 771 */ 772 uint64_t answer_code; 773 774 /** 775 * How much should be sent. 776 */ 777 struct TALER_Amount amount; 778 779 /** 780 * IBAN where to send the funds. 781 */ 782 const char *target_iban; 783 784 /** 785 * Name of the business receiving the funds. 786 */ 787 const char *target_business_name; 788 789 /** 790 * Wire transfer subject to use. 791 */ 792 const char *wire_transfer_subject; 793 794 }; 795 796 797 /** 798 * Information returned for a POST /truth/$TID/challenge request. 799 */ 800 struct ANASTASIS_TruthChallengeDetails 801 { 802 /** 803 * HTTP status returned by the server. 804 */ 805 unsigned int http_status; 806 807 /** 808 * Taler-specific error code, #TALER_EC_NONE on success. 809 */ 810 enum TALER_ErrorCode ec; 811 812 /** 813 * Full response in JSON, if provided. 814 */ 815 const json_t *response; 816 817 /** 818 * Details depending on @e http_status. 819 */ 820 union 821 { 822 823 /** 824 * Information for @e http_status of #MHD_HTTP_OK. 825 */ 826 struct 827 { 828 /** 829 * Meta-state about how the challenge was 830 * initiated and what is to be done next. 831 */ 832 enum ANASTASIS_ChallengeDetailType cs; 833 834 /** 835 * Details depending on @e cs. 836 */ 837 union 838 { 839 840 /** 841 * If @e cs is #ANASTASIS_CS_FILE_WRITTEN, this 842 * is the filename with the challenge code. 843 */ 844 const char *challenge_filename; 845 846 /** 847 * If @e cs is #ANASTASIS_CS_TAN_SENT, this 848 * is human-readable information as to where 849 * the TAN was sent. 850 */ 851 const char *tan_address_hint; 852 853 /** 854 * If @e cs is #ANASTASIS_CS_WIRE_FUNDS, this 855 * structure contains information about where 856 * to wire the funds to authenticate as well 857 * as a hint as to which bank account to send 858 * the funds from. 859 */ 860 struct ANASTASIS_WireFundsDetails wire_funds; 861 862 } details; 863 864 } success; 865 866 /** 867 * Information returned if @e http_status is #MHD_HTTP_PAYMENT_REQUIRED 868 */ 869 struct 870 { 871 /** 872 * A taler://pay/-URI with a request to pay the annual fee for 873 * the service. Returned if @e us is #ANASTASIS_US_PAYMENT_REQUIRED. 874 */ 875 const char *payment_request; 876 877 /** 878 * The payment secret (aka order ID) extracted from the @e payment_request. 879 */ 880 struct ANASTASIS_PaymentSecretP ps; 881 882 /** 883 * Data extracted from the payto:// URI. 884 */ 885 const struct TALER_MERCHANT_PayUriData *pd; 886 887 } payment_required; 888 889 } details; 890 891 }; 892 893 894 /** 895 * Handle for a POST /truth/$TID/challenge operation. 896 */ 897 struct ANASTASIS_TruthChallengeOperation; 898 899 900 /** 901 * Callback to process a POST /truth/$TID/challenge response. 902 * 903 * @param cls closure 904 * @param tcd details about the key share 905 */ 906 #ifndef ANASTASIS_TRUTH_CHALLENGE_RESULT_CLOSURE 907 /** 908 * Type of the closure for #ANASTASIS_TruthChallengeCallback. 909 */ 910 #define ANASTASIS_TRUTH_CHALLENGE_RESULT_CLOSURE void 911 #endif 912 typedef void 913 (*ANASTASIS_TruthChallengeCallback) ( 914 ANASTASIS_TRUTH_CHALLENGE_RESULT_CLOSURE *cls, 915 const struct ANASTASIS_TruthChallengeDetails *tcd); 916 917 918 /** 919 * Makes a POST /truth/$TID/challenge request. 920 * 921 * @param ctx execution context 922 * @param backend_url base URL of the merchant backend 923 * @param truth_uuid identification of the Truth 924 * @param truth_key Key used to Decrypt the Truth on the Server 925 * @param payment_secret secret from the previously done payment NULL to trigger payment 926 * @param cb callback which will work the response gotten from the backend 927 * @param cb_cls closure to pass to the callback 928 * @return handle for this operation, NULL upon errors 929 */ 930 struct ANASTASIS_TruthChallengeOperation * 931 ANASTASIS_truth_challenge ( 932 struct GNUNET_CURL_Context *ctx, 933 const char *backend_url, 934 const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_uuid, 935 const struct ANASTASIS_CRYPTO_TruthKeyP *truth_key, 936 const struct ANASTASIS_PaymentSecretP *payment_secret, 937 ANASTASIS_TruthChallengeCallback cb, 938 ANASTASIS_TRUTH_CHALLENGE_RESULT_CLOSURE *cb_cls); 939 940 941 /** 942 * Cancel a POST /truth/$TID/challenge request. 943 * 944 * @param[in] tco operation to cancel 945 */ 946 void 947 ANASTASIS_truth_challenge_cancel ( 948 struct ANASTASIS_TruthChallengeOperation *tco); 949 950 951 /** 952 * Information returned for a POST /truth/$TID/solve request. 953 */ 954 struct ANASTASIS_TruthSolveReply 955 { 956 957 /** 958 * HTTP status returned by the server. 959 */ 960 unsigned int http_status; 961 962 /** 963 * Taler-specific error code, #TALER_EC_NONE on success. 964 */ 965 enum TALER_ErrorCode ec; 966 967 /** 968 * Details depending on @e http_status. 969 */ 970 union 971 { 972 973 /** 974 * Information returned if @e http_status is #MHD_HTTP_OK. 975 */ 976 struct 977 { 978 979 /** 980 * The encrypted key share. 981 */ 982 struct ANASTASIS_CRYPTO_EncryptedKeyShareP eks; 983 984 } success; 985 986 /** 987 * Information returned if @e http_status is #MHD_HTTP_PAYMENT_REQUIRED 988 */ 989 struct 990 { 991 /** 992 * A taler://pay/-URI with a request to pay the annual fee for 993 * the service. Returned if @e us is #ANASTASIS_US_PAYMENT_REQUIRED. 994 */ 995 const char *payment_request; 996 997 /** 998 * The payment secret (aka order ID) extracted from the @e payment_request. 999 */ 1000 struct ANASTASIS_PaymentSecretP ps; 1001 1002 /** 1003 * Data extracted from the payto:// URI. 1004 */ 1005 const struct TALER_MERCHANT_PayUriData *pd; 1006 1007 } payment_required; 1008 1009 /** 1010 * Information returned if @e http_status is #MHD_HTTP_TOO_MANY_REQUESTS. 1011 */ 1012 struct 1013 { 1014 1015 /** 1016 * How many requests are allowed at most per @e request_frequency? 1017 */ 1018 uint32_t request_limit; 1019 1020 /** 1021 * Frequency at which requests are allowed / new challenges are 1022 * created. 1023 */ 1024 struct GNUNET_TIME_Relative request_frequency; 1025 } too_many_requests; 1026 1027 } details; 1028 1029 }; 1030 1031 1032 /** 1033 * Handle for a POST /truth/$TID/solve operation. 1034 */ 1035 struct ANASTASIS_TruthSolveOperation; 1036 1037 1038 /** 1039 * Callback to process a POST /truth/$TID/solve response. 1040 * 1041 * @param cls closure 1042 * @param kdd details about the key share 1043 */ 1044 #ifndef ANASTASIS_TRUTH_SOLVE_RESULT_CLOSURE 1045 /** 1046 * Type of the closure for #ANASTASIS_TruthSolveCallback. 1047 */ 1048 #define ANASTASIS_TRUTH_SOLVE_RESULT_CLOSURE void 1049 #endif 1050 typedef void 1051 (*ANASTASIS_TruthSolveCallback) ( 1052 ANASTASIS_TRUTH_SOLVE_RESULT_CLOSURE *cls, 1053 const struct ANASTASIS_TruthSolveReply *trs); 1054 1055 1056 /** 1057 * Makes a POST /truth/$TID/solve request. 1058 * 1059 * @param ctx execution context 1060 * @param backend_url base URL of the merchant backend 1061 * @param truth_uuid identification of the Truth 1062 * @param truth_key Key used to Decrypt the Truth on the Server 1063 * @param payment_secret secret from the previously done payment NULL to trigger payment 1064 * @param timeout how long to wait for the payment, use 1065 * #GNUNET_TIME_UNIT_ZERO to let the server pick 1066 * @param hashed_answer hashed answer to the challenge 1067 * @param cb callback which will work the response gotten from the backend 1068 * @param cb_cls closure to pass to the callback 1069 * @return handle for this operation, NULL upon errors 1070 */ 1071 struct ANASTASIS_TruthSolveOperation * 1072 ANASTASIS_truth_solve ( 1073 struct GNUNET_CURL_Context *ctx, 1074 const char *backend_url, 1075 const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_uuid, 1076 const struct ANASTASIS_CRYPTO_TruthKeyP *truth_key, 1077 const struct ANASTASIS_PaymentSecretP *payment_secret, 1078 struct GNUNET_TIME_Relative timeout, 1079 const struct GNUNET_HashCode *hashed_answer, 1080 ANASTASIS_TruthSolveCallback cb, 1081 ANASTASIS_TRUTH_SOLVE_RESULT_CLOSURE *cb_cls); 1082 1083 1084 /** 1085 * Cancel a POST /truth/$TID/solve request. 1086 * 1087 * @param[in] tso handle of the operation to cancel 1088 */ 1089 void 1090 ANASTASIS_truth_solve_cancel ( 1091 struct ANASTASIS_TruthSolveOperation *tso); 1092 1093 1094 #endif /* _ANASTASIS_SERVICE_H */