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