anastasis.h (32707B)
1 /* 2 This file is part of Anastasis 3 Copyright (C) 2020, 2021 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.GPL. If not, see <http://www.gnu.org/licenses/> 15 */ 16 /** 17 * @file include/anastasis.h 18 * @brief anastasis high-level client api 19 * @author Christian Grothoff 20 * @author Dominik Meister 21 * @author Dennis Neufeld 22 */ 23 #ifndef ANASTASIS_H 24 #define ANASTASIS_H 25 26 #include "anastasis_service.h" 27 #include <taler/taler_json_lib.h> 28 #include <gnunet/gnunet_util_lib.h> 29 #include <stdbool.h> 30 31 32 /* ********************* Recovery api *********************** */ 33 34 /** 35 * Defines the instructions for a challenge, what does the user have 36 * to do to fulfill the challenge. Also defines the method and other 37 * information for the challenge like a link for the video indent or a 38 * information to which address an e-mail was sent. 39 */ 40 struct ANASTASIS_Challenge; 41 42 43 /** 44 * Defines the instructions for a challenge, what does the user have 45 * to do to fulfill the challenge. Also defines the method and other 46 * information for the challenge like a link for the video indent or a 47 * information to which address an e-mail was sent. 48 */ 49 struct ANASTASIS_ChallengeDetails 50 { 51 52 /** 53 * UUID which identifies this challenge 54 */ 55 struct ANASTASIS_CRYPTO_TruthUUIDP uuid; 56 57 /** 58 * Which type is this challenge (E-Mail, Security Question, SMS...) 59 */ 60 const char *type; 61 62 /** 63 * Defines the base URL of the Anastasis provider used for the challenge. 64 */ 65 const char *provider_url; 66 67 /** 68 * Instructions for solving the challenge (generic, set client-side 69 * when challenge was established). 70 */ 71 const char *instructions; 72 73 /** 74 * true if challenge was already solved, else false. 75 */ 76 bool solved; 77 78 /** 79 * true if challenge is awaiting asynchronous 80 * resolution by the user. 81 */ 82 bool async; 83 84 }; 85 86 87 /** 88 * Return public details about a challenge. 89 * 90 * @param challenge the challenge to inspect 91 * @return public details about the challenge 92 */ 93 const struct ANASTASIS_ChallengeDetails * 94 ANASTASIS_challenge_get_details (struct ANASTASIS_Challenge *challenge); 95 96 97 /** 98 * Possible outcomes of trying to start a challenge operation. 99 */ 100 enum ANASTASIS_ChallengeStartStatus 101 { 102 103 /** 104 * We encountered an error talking to the Anastasis service. 105 */ 106 ANASTASIS_CHALLENGE_START_STATUS_SERVER_FAILURE, 107 108 /** 109 * Payment is required before the challenge can be answered. 110 */ 111 ANASTASIS_CHALLENGE_START_STATUS_PAYMENT_REQUIRED, 112 113 /** 114 * The server does not know this truth. 115 */ 116 ANASTASIS_CHALLENGE_START_STATUS_TRUTH_UNKNOWN, 117 118 /** 119 * A filename with the TAN has been provided. 120 */ 121 ANASTASIS_CHALLENGE_START_STATUS_FILENAME_PROVIDED, 122 123 /** 124 * A TAN has been send, address hint is provided. 125 */ 126 ANASTASIS_CHALLENGE_START_STATUS_TAN_SENT_HINT_PROVIDED, 127 128 /** 129 * A TAN has been sent before. 130 */ 131 ANASTASIS_CHALLENGE_START_STATUS_TAN_ALREADY_SENT, 132 133 /** 134 * Wire transfer required, banking details provided. 135 */ 136 ANASTASIS_CHALLENGE_START_STATUS_BANK_TRANSFER_REQUIRED 137 138 }; 139 140 141 /** 142 * Response from an #ANASTASIS_challenge_start() operation. 143 */ 144 struct ANASTASIS_ChallengeStartResponse 145 { 146 147 /** 148 * HTTP status returned by the server. 149 */ 150 unsigned int http_status; 151 152 /** 153 * Taler-specific error code. 154 */ 155 enum TALER_ErrorCode ec; 156 157 /** 158 * What is our status on satisfying this challenge. Determines @e details. 159 */ 160 enum ANASTASIS_ChallengeStartStatus cs; 161 162 /** 163 * Which challenge is this about? 164 */ 165 struct ANASTASIS_Challenge *challenge; 166 167 /** 168 * Details depending on @e cs 169 */ 170 union 171 { 172 173 /** 174 * Challenge details provided if 175 * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_FILENAME_PROVIDED. 176 */ 177 const char *tan_filename; 178 179 /** 180 * Challenge details provided if 181 * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_TAN_SENT_HINT_PROVIDED. 182 */ 183 const char *tan_address_hint; 184 185 /** 186 * Challenge details provided if 187 * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_BANK_TRANSFER_REQUIRED. 188 */ 189 struct ANASTASIS_WireFundsDetails bank_transfer_required; 190 191 /** 192 * Response with instructions for how to pay, if 193 * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_PAYMENT_REQUIRED. 194 */ 195 struct 196 { 197 198 /** 199 * "taler://pay" URI with details how to pay for the challenge. 200 */ 201 const char *taler_pay_uri; 202 203 /** 204 * Payment secret from @e taler_pay_uri. 205 */ 206 struct ANASTASIS_PaymentSecretP payment_secret; 207 208 } payment_required; 209 210 } details; 211 }; 212 213 214 /** 215 * Defines a callback for the response status for a challenge start 216 * operation. 217 * 218 * @param cls closure 219 * @param csr response details 220 */ 221 typedef void 222 (*ANASTASIS_ChallengeStartFeedback)( 223 void *cls, 224 const struct ANASTASIS_ChallengeStartResponse *csr); 225 226 227 /** 228 * User starts a challenge which reponds out of bounds (E-Mail, SMS, 229 * Postal..) If the challenge is zero cost, the challenge 230 * instructions will be sent to the client. If the challenge needs 231 * payment a payment link is sent to the client. After payment the 232 * challenge start method has to be called again. 233 * 234 * @param c reference to the escrow challenge which is started 235 * @param psp payment secret, NULL if no payment was yet made 236 * @param af reference to the answerfeedback which is passed back to the user 237 * @param af_cls closure for @a af 238 * @return #GNUNET_OK if the challenge was successfully started 239 */ 240 enum GNUNET_GenericReturnValue 241 ANASTASIS_challenge_start (struct ANASTASIS_Challenge *c, 242 const struct ANASTASIS_PaymentSecretP *psp, 243 ANASTASIS_ChallengeStartFeedback af, 244 void *af_cls); 245 246 247 /** 248 * Possible outcomes of trying to start a challenge operation. 249 */ 250 enum ANASTASIS_ChallengeAnswerStatus 251 { 252 253 /** 254 * The challenge has been solved. 255 */ 256 ANASTASIS_CHALLENGE_ANSWER_STATUS_SOLVED, 257 258 /** 259 * Payment is required before the challenge can be answered. 260 */ 261 ANASTASIS_CHALLENGE_ANSWER_STATUS_PAYMENT_REQUIRED, 262 263 /** 264 * We encountered an error talking to the Anastasis service. 265 */ 266 ANASTASIS_CHALLENGE_ANSWER_STATUS_SERVER_FAILURE, 267 268 /** 269 * The server does not know this truth. 270 */ 271 ANASTASIS_CHALLENGE_ANSWER_STATUS_TRUTH_UNKNOWN, 272 273 /** 274 * The answer was wrong. 275 */ 276 ANASTASIS_CHALLENGE_ANSWER_STATUS_INVALID_ANSWER, 277 278 /** 279 * The rate limit for solving the challenge was exceeded. 280 */ 281 ANASTASIS_CHALLENGE_ANSWER_STATUS_RATE_LIMIT_EXCEEDED 282 283 }; 284 285 286 /** 287 * Response from an #ANASTASIS_challenge_start() operation. 288 */ 289 struct ANASTASIS_ChallengeAnswerResponse 290 { 291 292 /** 293 * HTTP status returned by the server. 294 */ 295 unsigned int http_status; 296 297 /** 298 * Taler-specific error code. 299 */ 300 enum TALER_ErrorCode ec; 301 302 /** 303 * What is our status on satisfying this challenge. Determines @e details. 304 */ 305 enum ANASTASIS_ChallengeAnswerStatus cs; 306 307 /** 308 * Which challenge is this about? 309 */ 310 struct ANASTASIS_Challenge *challenge; 311 312 /** 313 * Details depending on @e cs 314 */ 315 union 316 { 317 318 /** 319 * Details for #ANASTASIS_CHALLENGE_ANSWER_STATUS_RATE_LIMIT_EXCEEDED. 320 */ 321 struct 322 { 323 324 /** 325 * How many requests are allowed at most per @e request_frequency? 326 */ 327 uint32_t request_limit; 328 329 /** 330 * Frequency at which requests are allowed / new challenges are 331 * created. 332 */ 333 struct GNUNET_TIME_Relative request_frequency; 334 335 } rate_limit_exceeded; 336 337 /** 338 * Response with instructions for how to pay, if 339 * @e cs is #ANASTASIS_CHALLENGE_ANSWER_STATUS_PAYMENT_REQUIRED. 340 */ 341 struct 342 { 343 344 /** 345 * "taler://pay" URI with details how to pay for the challenge. 346 */ 347 const char *taler_pay_uri; 348 349 /** 350 * Payment secret from @e taler_pay_uri. 351 */ 352 struct ANASTASIS_PaymentSecretP payment_secret; 353 354 } payment_required; 355 356 } details; 357 }; 358 359 360 /** 361 * Defines a callback for the response status for a challenge start 362 * operation. 363 * 364 * @param cls closure 365 * @param car response details 366 */ 367 typedef void 368 (*ANASTASIS_AnswerFeedback)( 369 void *cls, 370 const struct ANASTASIS_ChallengeAnswerResponse *car); 371 372 373 /** 374 * Challenge answer for a security question. Is referenced to 375 * a challenge and sends back an AnswerFeedback. Convenience 376 * wrapper around #ANASTASIS_challenge_start that hashes @a answer 377 * for security questions. 378 * 379 * @param c reference to the challenge which is answered 380 * @param psp information about payment made for the recovery 381 * @param timeout how long to wait for payment 382 * @param answer user input instruction defines which input is needed 383 * @param csf function to call with the result 384 * @param csf_cls closure for @a csf 385 * @return #GNUNET_OK on success 386 */ 387 enum GNUNET_GenericReturnValue 388 ANASTASIS_challenge_answer (struct ANASTASIS_Challenge *c, 389 const struct ANASTASIS_PaymentSecretP *psp, 390 struct GNUNET_TIME_Relative timeout, 391 const char *answer, 392 ANASTASIS_AnswerFeedback csf, 393 void *csf_cls); 394 395 396 /** 397 * Challenge answer from the user like input SMS TAN or e-mail wpin. Is 398 * referenced to a challenge and sends back an AnswerFeedback. 399 * Convenience wrapper around #ANASTASIS_challenge_start that hashes 400 * numeric (unsalted) @a answer. Variant for numeric answers. 401 * 402 * @param c reference to the challenge which is answered 403 * @param psp information about payment made for the recovery 404 * @param timeout how long to wait for payment 405 * @param answer user input instruction defines which input is needed 406 * @param af reference to the answerfeedback which is passed back to the user 407 * @param af_cls closure for @a af 408 * @return #GNUNET_OK on success 409 */ 410 enum GNUNET_GenericReturnValue 411 ANASTASIS_challenge_answer2 (struct ANASTASIS_Challenge *c, 412 const struct ANASTASIS_PaymentSecretP *psp, 413 struct GNUNET_TIME_Relative timeout, 414 uint64_t answer, 415 ANASTASIS_AnswerFeedback af, 416 void *af_cls); 417 418 419 /** 420 * User starts a challenge which reponds out of bounds (E-Mail, SMS, 421 * Postal..) If the challenge is zero cost, the challenge 422 * instructions will be sent to the client. If the challenge needs 423 * payment a payment link is sent to the client. After payment the 424 * challenge start method has to be called again. 425 * 426 * @param c reference to the escrow challenge which is started 427 * @param psp payment secret, NULL if no payment was yet made 428 * @param timeout how long to wait for payment 429 * @param hashed_answer answer to the challenge 430 * @param af reference to the answerfeedback which is passed back to the user 431 * @param af_cls closure for @a af 432 * @return #GNUNET_OK if the challenge was successfully started 433 */ 434 enum GNUNET_GenericReturnValue 435 ANASTASIS_challenge_answer3 (struct ANASTASIS_Challenge *c, 436 const struct ANASTASIS_PaymentSecretP *psp, 437 struct GNUNET_TIME_Relative timeout, 438 const struct GNUNET_HashCode *hashed_answer, 439 ANASTASIS_AnswerFeedback af, 440 void *af_cls); 441 442 443 /** 444 * Abort answering challenge. 445 * 446 * @param c reference to the escrow challenge which was started 447 */ 448 void 449 ANASTASIS_challenge_abort (struct ANASTASIS_Challenge *c); 450 451 452 /** 453 * Handle for an operation to get available recovery 454 * document versions. 455 */ 456 struct ANASTASIS_VersionCheck; 457 458 459 /** 460 * Callback which passes back meta data about one of the 461 * recovery documents available at the provider. 462 * 463 * @param cls closure for the callback 464 * @param version version number of the policy document, 465 * 0 for the end of the list 466 * @param server_time time of the backup at the provider 467 * @param recdoc_id hash of the compressed recovery document, uniquely 468 * identifies the document; NULL for the end of the list 469 * @param secret_name name of the secret as chosen by the user, 470 * or NULL if the user did not provide a name 471 */ 472 typedef void 473 (*ANASTASIS_MetaPolicyCallback)(void *cls, 474 uint32_t version, 475 struct GNUNET_TIME_Timestamp server_time, 476 const struct GNUNET_HashCode *recdoc_id, 477 const char *secret_name); 478 479 480 /** 481 * Obtain an overview of available recovery policies from the 482 * specified provider. 483 * 484 * @param ctx context for making HTTP requests 485 * @param id_data contains the users identity, (user account on providers) 486 * @param version defines the version which will be downloaded, 0 for latest version 487 * @param anastasis_provider_url provider url 488 * @param provider_salt the server salt 489 * @param mpc function called with the available versions 490 * @param mpc_cls closure for @a mpc callback 491 * @return recovery operation handle 492 */ 493 struct ANASTASIS_VersionCheck * 494 ANASTASIS_recovery_get_versions ( 495 struct GNUNET_CURL_Context *ctx, 496 const json_t *id_data, 497 unsigned int max_version, 498 const char *anastasis_provider_url, 499 const struct ANASTASIS_CRYPTO_ProviderSaltP *provider_salt, 500 ANASTASIS_MetaPolicyCallback mpc, 501 void *mpc_cls); 502 503 504 /** 505 * Cancel version check operation. 506 * 507 * @param vc operation to cancel 508 */ 509 void 510 ANASTASIS_recovery_get_versions_cancel (struct ANASTASIS_VersionCheck *vc); 511 512 513 /** 514 * Defines a Decryption Policy with multiple escrow methods 515 */ 516 struct ANASTASIS_DecryptionPolicy 517 { 518 /** 519 * Array of challenges needed to solve for this decryption policy. 520 */ 521 struct ANASTASIS_Challenge **challenges; 522 523 /** 524 * Length of the @a challenges in this policy. 525 */ 526 unsigned int challenges_length; 527 528 }; 529 530 531 /** 532 * Defines the recovery information (possible policies and version of the recovery document) 533 */ 534 struct ANASTASIS_RecoveryInformation 535 { 536 537 /** 538 * Array of @e dps_len policies that would allow recovery of the core secret. 539 */ 540 struct ANASTASIS_DecryptionPolicy **dps; 541 542 /** 543 * Array of all @e cs_len challenges to be solved (for any of the policies). 544 */ 545 struct ANASTASIS_Challenge **cs; 546 547 /** 548 * Name of the secret being recovered, possibly NULL. 549 */ 550 const char *secret_name; 551 552 /** 553 * Length of the @e dps array. 554 */ 555 unsigned int dps_len; 556 557 /** 558 * Length of the @e cs array. 559 */ 560 unsigned int cs_len; 561 562 /** 563 * Actual recovery document version obtained. 564 */ 565 unsigned int version; 566 }; 567 568 569 /** 570 * Callback which passes back the recovery document and its possible 571 * policies. Also passes back the version of the document for the user 572 * to check. 573 * 574 * @param cls closure for the callback 575 * @param ri recovery information struct which contains the policies 576 */ 577 typedef void 578 (*ANASTASIS_PolicyCallback)(void *cls, 579 const struct ANASTASIS_RecoveryInformation *ri); 580 581 582 /** 583 * Possible outcomes of a recovery process. 584 */ 585 enum ANASTASIS_RecoveryStatus 586 { 587 588 /** 589 * Recovery succeeded. 590 */ 591 ANASTASIS_RS_SUCCESS = 0, 592 593 /** 594 * The HTTP download of the policy failed. 595 */ 596 ANASTASIS_RS_POLICY_DOWNLOAD_FAILED, 597 598 /** 599 * We did not get a valid policy document. 600 */ 601 ANASTASIS_RS_POLICY_DOWNLOAD_NO_POLICY, 602 603 /** 604 * The decompressed policy document was too big for available memory. 605 */ 606 ANASTASIS_RS_POLICY_DOWNLOAD_TOO_BIG, 607 608 /** 609 * The decrypted policy document was not compressed. 610 */ 611 ANASTASIS_RS_POLICY_DOWNLOAD_INVALID_COMPRESSION, 612 613 /** 614 * The decompressed policy document was not in JSON. 615 */ 616 ANASTASIS_RS_POLICY_DOWNLOAD_NO_JSON, 617 618 /** 619 * The decompressed policy document was in malformed JSON. 620 */ 621 ANASTASIS_RS_POLICY_MALFORMED_JSON, 622 623 /** 624 * The Anastasis server reported a transient error. 625 */ 626 ANASTASIS_RS_POLICY_SERVER_ERROR, 627 628 /** 629 * The Anastasis server no longer has a policy (likely expired). 630 */ 631 ANASTASIS_RS_POLICY_GONE, 632 633 /** 634 * The Anastasis server reported that the account is unknown. 635 */ 636 ANASTASIS_RS_POLICY_UNKNOWN 637 }; 638 639 640 /** 641 * This function is called whenever the recovery process ends. 642 * On success, the secret is returned in @a secret. 643 * 644 * @param cls closure 645 * @param ec error code 646 * @param secret contains the core secret which is passed to the user 647 * @param secret_size defines the size of the core secret 648 */ 649 typedef void 650 (*ANASTASIS_CoreSecretCallback)(void *cls, 651 enum ANASTASIS_RecoveryStatus rc, 652 const void *secret, 653 size_t secret_size); 654 655 656 /** 657 * stores provider URIs, identity key material, decrypted recovery document (internally!) 658 */ 659 struct ANASTASIS_Recovery; 660 661 662 /** 663 * Starts the recovery process by opening callbacks for the coresecret and a policy callback. A list of 664 * providers is checked for policies and passed back to the client. 665 * 666 * @param ctx context for making HTTP requests 667 * @param id_data contains the users identity, (user account on providers) 668 * @param version defines the version which will be downloaded, 0 for latest version 669 * @param anastasis_provider_url provider REST API endpoint url 670 * @param provider_salt the provider's salt 671 * @param pc opens the policy call back which holds the downloaded version and the policies 672 * @param pc_cls closure for callback 673 * @param csc core secret callback is opened, with this the core secert is passed to the client after the authentication 674 * @param csc_cls handle for the callback 675 * @return recovery operation handle 676 */ 677 struct ANASTASIS_Recovery * 678 ANASTASIS_recovery_begin ( 679 struct GNUNET_CURL_Context *ctx, 680 const json_t *id_data, 681 unsigned int version, 682 const char *anastasis_provider_url, 683 const struct ANASTASIS_CRYPTO_ProviderSaltP *provider_salt, 684 ANASTASIS_PolicyCallback pc, 685 void *pc_cls, 686 ANASTASIS_CoreSecretCallback csc, 687 void *csc_cls); 688 689 690 /** 691 * Serialize recovery operation state and returning it. 692 * The recovery MAY still continue, applications should call 693 * #ANASTASIS_recovery_abort() to truly end the recovery. 694 * 695 * @param r recovery operation to suspend. 696 * @return JSON serialized state of @a r 697 */ 698 json_t * 699 ANASTASIS_recovery_serialize (const struct ANASTASIS_Recovery *r); 700 701 702 /** 703 * Deserialize recovery operation. 704 * 705 * @param ctx context for making HTTP requests 706 * @param input result from #ANASTASIS_recovery_serialize() 707 * @param pc opens the policy call back which holds the downloaded version and the policies 708 * @param pc_cls closure for callback 709 * @param csc core secret callback is opened, with this the core secert is passed to the client after the authentication 710 * @param csc_cls handle for the callback 711 * @return recovery operation handle 712 */ 713 struct ANASTASIS_Recovery * 714 ANASTASIS_recovery_deserialize (struct GNUNET_CURL_Context *ctx, 715 const json_t *input, 716 ANASTASIS_PolicyCallback pc, 717 void *pc_cls, 718 ANASTASIS_CoreSecretCallback csc, 719 void *csc_cls); 720 721 722 /** 723 * Cancels the recovery process 724 * 725 * @param r handle to the recovery struct 726 */ 727 void 728 ANASTASIS_recovery_abort (struct ANASTASIS_Recovery *r); 729 730 731 /* ************************* Backup API ***************************** */ 732 733 734 /** 735 * Represents a truth object, which is a key share and the respective 736 * challenge to be solved with an Anastasis provider to recover the 737 * key share. 738 */ 739 struct ANASTASIS_Truth; 740 741 742 /** 743 * Extracts truth data from JSON. 744 * 745 * @param json JSON encoding to decode; truth returned ONLY valid as long 746 * as the JSON remains valid (do not decref until the truth 747 * is truly finished) 748 * @return decoded truth object, NULL on error 749 */ 750 struct ANASTASIS_Truth * 751 ANASTASIS_truth_from_json (const json_t *json); 752 753 754 /** 755 * Returns JSON-encoded truth data. 756 * Creates a policy with a set of truth's. Creates the policy key 757 * with the different key shares from the @a truths. The policy key 758 * will then be used to encrypt/decrypt the escrow master key. 759 * 760 * @param t object to return JSON encoding for 761 * @return JSON encoding of @a t 762 */ 763 json_t * 764 ANASTASIS_truth_to_json (const struct ANASTASIS_Truth *t); 765 766 767 /** 768 * Handle for the operation to establish a truth object by sharing 769 * an encrypted key share with an Anastasis provider. 770 */ 771 struct ANASTASIS_TruthUpload; 772 773 774 /** 775 * Upload result information. The resulting truth object can be used 776 * to create policies. If payment is required, the @a taler_pay_url 777 * is returned and the operation must be retried after payment. 778 * Callee MUST free @a t using ANASTASIS_truth_free(). 779 * 780 * @param cls closure for callback 781 * @param t truth object to create policies, NULL on failure 782 * @param ud upload details, useful to continue in case of errors, NULL on success 783 */ 784 typedef void 785 (*ANASTASIS_TruthCallback)(void *cls, 786 struct ANASTASIS_Truth *t, 787 const struct ANASTASIS_UploadDetails *ud); 788 789 790 /** 791 * Uploads truth data to an escrow provider. The resulting truth object 792 * is returned via the @a tc function. If payment is required, it is 793 * requested via the @a tcp callback. 794 * 795 * @param ctx the CURL context used to connect to the backend 796 * @param user_id user identifier derived from user data and backend salt 797 * @param provider_url base URL of the provider to upload to 798 * @param type defines the type of the challenge (secure question, sms, email) 799 * @param instructions depending on @a type! usually only for security question/answer! 800 * @param mime_type format of the challenge 801 * @param provider_salt the providers salt 802 * @param truth_data contains the truth for this challenge i.e. phone number, email address 803 * @param truth_data_size size of the @a truth_data 804 * @param payment_years_requested for how many years would the client like the service to store the truth? 805 * @param pay_timeout how long to wait for payment 806 * @param tc opens the truth callback which contains the status of the upload 807 * @param tc_cls closure for the @a tc callback 808 */ 809 struct ANASTASIS_TruthUpload * 810 ANASTASIS_truth_upload ( 811 struct GNUNET_CURL_Context *ctx, 812 const struct ANASTASIS_CRYPTO_UserIdentifierP *user_id, 813 const char *provider_url, 814 const char *type, 815 const char *instructions, 816 const char *mime_type, 817 const struct ANASTASIS_CRYPTO_ProviderSaltP *provider_salt, 818 const void *truth_data, 819 size_t truth_data_size, 820 uint32_t payment_years_requested, 821 struct GNUNET_TIME_Relative pay_timeout, 822 ANASTASIS_TruthCallback tc, 823 void *tc_cls); 824 825 826 /** 827 * Retries upload of truth data to an escrow provider. The resulting 828 * truth object is returned via the @a tc function. If payment is 829 * required, it is requested via the @a tcp callback. 830 * 831 * @param ctx the CURL context used to connect to the backend 832 * @param user_id user identifier derived from user data and backend salt 833 * @param provider_url base URL of the provider to upload to 834 * @param type defines the type of the challenge (secure question, sms, email) 835 * @param instructions depending on @a type! usually only for security question/answer! 836 * @param mime_type format of the challenge 837 * @param provider_salt the providers salt 838 * @param truth_data contains the truth for this challenge i.e. phone number, email address 839 * @param truth_data_size size of the @a truth_data 840 * @param payment_years_requested for how many years would the client like the service to store the truth? 841 * @param pay_timeout how long to wait for payment 842 * @param nonce nonce to use for symmetric encryption 843 * @param uuid truth UUID to use 844 * @param salt salt to use to hash security questions 845 * @param truth_key symmetric encryption key to use to encrypt @a truth_data 846 * @param key_share share of the overall key to store in this truth object 847 * @param tc opens the truth callback which contains the status of the upload 848 * @param tc_cls closure for the @a tc callback 849 */ 850 struct ANASTASIS_TruthUpload * 851 ANASTASIS_truth_upload2 ( 852 struct GNUNET_CURL_Context *ctx, 853 const struct ANASTASIS_CRYPTO_UserIdentifierP *user_id, 854 const char *provider_url, 855 const char *type, 856 const char *instructions, 857 const char *mime_type, 858 const struct ANASTASIS_CRYPTO_ProviderSaltP *provider_salt, 859 const void *truth_data, 860 size_t truth_data_size, 861 uint32_t payment_years_requested, 862 struct GNUNET_TIME_Relative pay_timeout, 863 const struct ANASTASIS_CRYPTO_NonceP *nonce, 864 const struct ANASTASIS_CRYPTO_TruthUUIDP *uuid, 865 const struct ANASTASIS_CRYPTO_QuestionSaltP *salt, 866 const struct ANASTASIS_CRYPTO_TruthKeyP *truth_key, 867 const struct ANASTASIS_CRYPTO_KeyShareP *key_share, 868 ANASTASIS_TruthCallback tc, 869 void *tc_cls); 870 871 872 /** 873 * Retries upload of truth data to an escrow provider using an 874 * existing truth object. If payment is required, it is requested via 875 * the @a tc callback. 876 * 877 * @param ctx the CURL context used to connect to the backend 878 * @param user_id user identifier derived from user data and backend salt 879 * @param[in] t truth details, reference is consumed 880 * @param truth_data contains the truth for this challenge i.e. phone number, email address 881 * @param truth_data_size size of the @a truth_data 882 * @param payment_years_requested for how many years would the client like the service to store the truth? 883 * @param pay_timeout how long to wait for payment 884 * @param tc opens the truth callback which contains the status of the upload 885 * @param tc_cls closure for the @a tc callback 886 */ 887 struct ANASTASIS_TruthUpload * 888 ANASTASIS_truth_upload3 (struct GNUNET_CURL_Context *ctx, 889 const struct ANASTASIS_CRYPTO_UserIdentifierP *user_id, 890 struct ANASTASIS_Truth *t, 891 const void *truth_data, 892 size_t truth_data_size, 893 uint32_t payment_years_requested, 894 struct GNUNET_TIME_Relative pay_timeout, 895 ANASTASIS_TruthCallback tc, 896 void *tc_cls); 897 898 899 /** 900 * Cancels a truth upload process. 901 * 902 * @param tu handle for the upload 903 */ 904 void 905 ANASTASIS_truth_upload_cancel (struct ANASTASIS_TruthUpload *tu); 906 907 908 /** 909 * Free's the truth object which was returned to a #ANASTASIS_TruthCallback. 910 * 911 * @param t object to clean up 912 */ 913 void 914 ANASTASIS_truth_free (struct ANASTASIS_Truth *t); 915 916 917 /** 918 * Policy object, representing a set of truths (and thus challenges 919 * to satisfy) to recover a secret. 920 */ 921 struct ANASTASIS_Policy; 922 923 924 /** 925 * Creates a policy with a set of truth's. Creates the policy key 926 * with the different key shares from the @a truths. The policy key 927 * will then be used to encrypt/decrypt the escrow master key. 928 * 929 * @param truths array of truths which are stored on different providers 930 * @param truths_len length of the @a truths array 931 */ 932 struct ANASTASIS_Policy * 933 ANASTASIS_policy_create (const struct ANASTASIS_Truth *truths[], 934 unsigned int truths_len); 935 936 937 /** 938 * Destroys a policy object. 939 * 940 * @param p handle for the policy to destroy 941 */ 942 void 943 ANASTASIS_policy_destroy (struct ANASTASIS_Policy *p); 944 945 946 /** 947 * Information about a provider requesting payment for storing a policy. 948 */ 949 struct ANASTASIS_SharePaymentRequest 950 { 951 /** 952 * Payment request URL. 953 */ 954 const char *payment_request_url; 955 956 /** 957 * Base URL of the provider requesting payment. 958 */ 959 const char *provider_url; 960 961 /** 962 * The payment secret (aka order ID) extracted from the @e payment_request_url. 963 */ 964 struct ANASTASIS_PaymentSecretP payment_secret; 965 }; 966 967 968 /** 969 * Result of uploading share data. 970 */ 971 enum ANASTASIS_ShareStatus 972 { 973 /** 974 * Upload successful. 975 */ 976 ANASTASIS_SHARE_STATUS_SUCCESS = 0, 977 978 /** 979 * Upload requires payment. 980 */ 981 ANASTASIS_SHARE_STATUS_PAYMENT_REQUIRED, 982 983 /** 984 * Failure to upload secret share at the provider. 985 */ 986 ANASTASIS_SHARE_STATUS_PROVIDER_FAILED 987 }; 988 989 990 /** 991 * Per-provider status upon successful backup. 992 */ 993 struct ANASTASIS_ProviderSuccessStatus 994 { 995 /** 996 * Base URL of the provider. 997 */ 998 const char *provider_url; 999 1000 /** 1001 * When will the policy expire? 1002 */ 1003 struct GNUNET_TIME_Timestamp policy_expiration; 1004 1005 /** 1006 * Version number of the policy at the provider. 1007 */ 1008 unsigned long long policy_version; 1009 1010 }; 1011 1012 1013 /** 1014 * Complete result of a secret sharing operation. 1015 */ 1016 struct ANASTASIS_ShareResult 1017 { 1018 /** 1019 * Status of the share secret operation. 1020 */ 1021 enum ANASTASIS_ShareStatus ss; 1022 1023 /** 1024 * Details about the result, depending on @e ss. 1025 */ 1026 union 1027 { 1028 1029 struct 1030 { 1031 1032 /** 1033 * Array of status details for each provider. 1034 */ 1035 const struct ANASTASIS_ProviderSuccessStatus *pss; 1036 1037 /** 1038 * Length of the @e policy_version and @e provider_urls arrays. 1039 */ 1040 unsigned int num_providers; 1041 1042 } success; 1043 1044 struct 1045 { 1046 /** 1047 * Array of URLs with requested payments. 1048 */ 1049 struct ANASTASIS_SharePaymentRequest *payment_requests; 1050 1051 /** 1052 * Length of the payment_requests array. 1053 */ 1054 unsigned int payment_requests_length; 1055 } payment_required; 1056 1057 struct 1058 { 1059 /** 1060 * Base URL of the failed provider. 1061 */ 1062 const char *provider_url; 1063 1064 /** 1065 * HTTP status returned by the provider. 1066 */ 1067 unsigned int http_status; 1068 1069 /** 1070 * Upload status of the provider. 1071 */ 1072 enum ANASTASIS_UploadStatus ec; 1073 1074 } provider_failure; 1075 1076 } details; 1077 1078 }; 1079 1080 1081 /** 1082 * Function called with the results of a #ANASTASIS_secret_share(). 1083 * 1084 * @param cls closure 1085 * @param sr share result 1086 */ 1087 typedef void 1088 (*ANASTASIS_ShareResultCallback)(void *cls, 1089 const struct ANASTASIS_ShareResult *sr); 1090 1091 1092 /** 1093 * Defines a recovery document upload process (recovery document 1094 * consists of multiple policies) 1095 */ 1096 struct ANASTASIS_SecretShare; 1097 1098 1099 /** 1100 * Details of a past payment 1101 */ 1102 struct ANASTASIS_ProviderDetails 1103 { 1104 /** 1105 * URL of the provider backend. 1106 */ 1107 const char *provider_url; 1108 1109 /** 1110 * Payment order ID / secret of a past payment. 1111 */ 1112 struct ANASTASIS_PaymentSecretP payment_secret; 1113 1114 /** 1115 * Server salt. Points into a truth object from which we got the 1116 * salt. 1117 */ 1118 struct ANASTASIS_CRYPTO_ProviderSaltP provider_salt; 1119 }; 1120 1121 1122 /** 1123 * Creates a recovery document with the created policies and uploads it to 1124 * all servers. 1125 * 1126 * @param ctx the CURL context used to connect to the backend 1127 * @param id_data used to create a account identifier on the escrow provider 1128 * @param providers array of providers with URLs to upload the policies to 1129 * @param pss_length length of the @a providers array 1130 * @param policies list of policies which are included in this recovery document 1131 * @param policies_len length of the @a policies array 1132 * @param payment_years_requested for how many years would the client like the service to store the truth? 1133 * @param pay_timeout how long to wait for payment 1134 * @param src callback for the upload process 1135 * @param src_cls closure for the @a src upload callback 1136 * @param secret_name name of the core secret 1137 * @param core_secret input of the user which is secured by anastasis e.g. (wallet private key) 1138 * @param core_secret_size size of the @a core_secret 1139 * @return NULL on error 1140 */ 1141 struct ANASTASIS_SecretShare * 1142 ANASTASIS_secret_share (struct GNUNET_CURL_Context *ctx, 1143 const json_t *id_data, 1144 const struct ANASTASIS_ProviderDetails providers[], 1145 unsigned int pss_length, 1146 const struct ANASTASIS_Policy *policies[], 1147 unsigned int policies_len, 1148 uint32_t payment_years_requested, 1149 struct GNUNET_TIME_Relative pay_timeout, 1150 ANASTASIS_ShareResultCallback src, 1151 void *src_cls, 1152 const char *secret_name, 1153 const void *core_secret, 1154 size_t core_secret_size); 1155 1156 1157 /** 1158 * Cancels a secret share request. 1159 * 1160 * @param ss handle to the request 1161 */ 1162 void 1163 ANASTASIS_secret_share_cancel (struct ANASTASIS_SecretShare *ss); 1164 1165 1166 #endif