diff options
Diffstat (limited to 'src/include/anastasis.h')
| -rw-r--r-- | src/include/anastasis.h | 370 |
1 files changed, 262 insertions, 108 deletions
diff --git a/src/include/anastasis.h b/src/include/anastasis.h index a950172..ea49ee7 100644 --- a/src/include/anastasis.h +++ b/src/include/anastasis.h @@ -3,14 +3,14 @@ Copyright (C) 2020, 2021 Anastasis SARL Anastasis is free software; you can redistribute it and/or modify it under the - terms of the GNU Lesser General Public License as published by the Free Software + terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version. Anastasis is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR - A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + A PARTICULAR PURPOSE. See the GNU General Public License for more details. - You should have received a copy of the GNU Affero General Public License along with + You should have received a copy of the GNU General Public License along with Anastasis; see the file COPYING.GPL. If not, see <http://www.gnu.org/licenses/> */ /** @@ -97,61 +97,43 @@ ANASTASIS_challenge_get_details (struct ANASTASIS_Challenge *challenge); /** * Possible outcomes of trying to start a challenge operation. */ -enum ANASTASIS_ChallengeStatus +enum ANASTASIS_ChallengeStartStatus { /** - * The challenge has been solved. - */ - ANASTASIS_CHALLENGE_STATUS_SOLVED, - - /** - * Instructions for how to solve the challenge are provided. Also - * used if the answer we provided was wrong (or if no answer was - * provided, but one is needed). - */ - ANASTASIS_CHALLENGE_STATUS_INSTRUCTIONS, - - /** - * A redirection URL needed to solve the challenge is provided. Also - * used if the answer we provided was wrong (or if no answer was - * provided, but one is needed). + * We encountered an error talking to the Anastasis service. */ - ANASTASIS_CHALLENGE_STATUS_REDIRECT_FOR_AUTHENTICATION, + ANASTASIS_CHALLENGE_START_STATUS_SERVER_FAILURE, /** * Payment is required before the challenge can be answered. */ - ANASTASIS_CHALLENGE_STATUS_PAYMENT_REQUIRED, + ANASTASIS_CHALLENGE_START_STATUS_PAYMENT_REQUIRED, /** - * We encountered an error talking to the Anastasis service. + * The server does not know this truth. */ - ANASTASIS_CHALLENGE_STATUS_SERVER_FAILURE, + ANASTASIS_CHALLENGE_START_STATUS_TRUTH_UNKNOWN, /** - * The server does not know this truth. + * A filename with the TAN has been provided. */ - ANASTASIS_CHALLENGE_STATUS_TRUTH_UNKNOWN, + ANASTASIS_CHALLENGE_START_STATUS_FILENAME_PROVIDED, /** - * The rate limit for solving the challenge was exceeded. + * A TAN has been send, address hint is provided. */ - ANASTASIS_CHALLENGE_STATUS_RATE_LIMIT_EXCEEDED, + ANASTASIS_CHALLENGE_START_STATUS_TAN_SENT_HINT_PROVIDED, /** - * The user did not satisfy the (external) authentication - * challenge in time. The request should be repeated - * later and may then succeed. + * A TAN has been sent before. */ - ANASTASIS_CHALLENGE_STATUS_AUTH_TIMEOUT, + ANASTASIS_CHALLENGE_START_STATUS_TAN_ALREADY_SENT, /** - * Plugin-specific ("external") instructions for how to solve the - * challenge are provided. + * Wire transfer required, banking details provided. */ - ANASTASIS_CHALLENGE_STATUS_EXTERNAL_INSTRUCTIONS - + ANASTASIS_CHALLENGE_START_STATUS_BANK_TRANSFER_REQUIRED }; @@ -161,10 +143,21 @@ enum ANASTASIS_ChallengeStatus */ struct ANASTASIS_ChallengeStartResponse { + + /** + * HTTP status returned by the server. + */ + unsigned int http_status; + + /** + * Taler-specific error code. + */ + enum TALER_ErrorCode ec; + /** * What is our status on satisfying this challenge. Determines @e details. */ - enum ANASTASIS_ChallengeStatus cs; + enum ANASTASIS_ChallengeStartStatus cs; /** * Which challenge is this about? @@ -179,50 +172,25 @@ struct ANASTASIS_ChallengeStartResponse /** * Challenge details provided if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_INSTRUCTIONS + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_FILENAME_PROVIDED. */ - struct - { - - /** - * Response with server-side instructions for the user. - */ - const void *body; - - /** - * Mime type of the data in @e body. - */ - const char *content_type; - - /** - * Number of bytes in @e body - */ - size_t body_size; - - /** - * HTTP status returned by the server. #MHD_HTTP_ALREADY_REPORTED - * if the server did already send the challenge to the user, - * #MHD_HTTP_FORBIDDEN if the answer was wrong (or missing). - */ - unsigned int http_status; - } open_challenge; - + const char *tan_filename; /** - * Response with details if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_EXTERNAL_INSTRUCTIONS. + * Challenge details provided if + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_TAN_SENT_HINT_PROVIDED. */ - const json_t *external_challenge; + const char *tan_address_hint; /** - * Response with URL to redirect the user to, if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_REDIRECT_FOR_AUTHENTICATION. + * Challenge details provided if + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_BANK_TRANSFER_REQUIRED. */ - const char *redirect_url; + struct ANASTASIS_WireFundsDetails bank_transfer_required; /** * Response with instructions for how to pay, if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_PAYMENT_REQUIRED. + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_PAYMENT_REQUIRED. */ struct { @@ -239,26 +207,6 @@ struct ANASTASIS_ChallengeStartResponse } payment_required; - - /** - * Response with details about a server-side failure, if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_SERVER_FAILURE. - */ - struct - { - - /** - * HTTP status returned by the server. - */ - unsigned int http_status; - - /** - * Taler-specific error code. - */ - enum TALER_ErrorCode ec; - - } server_failure; - } details; }; @@ -271,7 +219,7 @@ struct ANASTASIS_ChallengeStartResponse * @param csr response details */ typedef void -(*ANASTASIS_AnswerFeedback)( +(*ANASTASIS_ChallengeStartFeedback)( void *cls, const struct ANASTASIS_ChallengeStartResponse *csr); @@ -285,22 +233,144 @@ typedef void * * @param c reference to the escrow challenge which is started * @param psp payment secret, NULL if no payment was yet made - * @param timeout how long to wait for payment - * @param hashed_answer answer to the challenge, NULL if we have none yet * @param af reference to the answerfeedback which is passed back to the user * @param af_cls closure for @a af * @return #GNUNET_OK if the challenge was successfully started */ -int +enum GNUNET_GenericReturnValue ANASTASIS_challenge_start (struct ANASTASIS_Challenge *c, const struct ANASTASIS_PaymentSecretP *psp, - struct GNUNET_TIME_Relative timeout, - const struct GNUNET_HashCode *hashed_answer, - ANASTASIS_AnswerFeedback af, + ANASTASIS_ChallengeStartFeedback af, void *af_cls); /** + * Possible outcomes of trying to start a challenge operation. + */ +enum ANASTASIS_ChallengeAnswerStatus +{ + + /** + * The challenge has been solved. + */ + ANASTASIS_CHALLENGE_ANSWER_STATUS_SOLVED, + + /** + * Payment is required before the challenge can be answered. + */ + ANASTASIS_CHALLENGE_ANSWER_STATUS_PAYMENT_REQUIRED, + + /** + * We encountered an error talking to the Anastasis service. + */ + ANASTASIS_CHALLENGE_ANSWER_STATUS_SERVER_FAILURE, + + /** + * The server does not know this truth. + */ + ANASTASIS_CHALLENGE_ANSWER_STATUS_TRUTH_UNKNOWN, + + /** + * The answer was wrong. + */ + ANASTASIS_CHALLENGE_ANSWER_STATUS_INVALID_ANSWER, + + /** + * The rate limit for solving the challenge was exceeded. + */ + ANASTASIS_CHALLENGE_ANSWER_STATUS_RATE_LIMIT_EXCEEDED + +}; + + +/** + * Response from an #ANASTASIS_challenge_start() operation. + */ +struct ANASTASIS_ChallengeAnswerResponse +{ + + /** + * HTTP status returned by the server. + */ + unsigned int http_status; + + /** + * Taler-specific error code. + */ + enum TALER_ErrorCode ec; + + /** + * What is our status on satisfying this challenge. Determines @e details. + */ + enum ANASTASIS_ChallengeAnswerStatus cs; + + /** + * Which challenge is this about? + */ + struct ANASTASIS_Challenge *challenge; + + /** + * Details depending on @e cs + */ + union + { + + /** + * Details for #ANASTASIS_CHALLENGE_ANSWER_STATUS_RATE_LIMIT_EXCEEDED. + */ + struct + { + + /** + * How many requests are allowed at most per @e request_frequency? + */ + uint32_t request_limit; + + /** + * Frequency at which requests are allowed / new challenges are + * created. + */ + struct GNUNET_TIME_Relative request_frequency; + + } rate_limit_exceeded; + + /** + * Response with instructions for how to pay, if + * @e cs is #ANASTASIS_CHALLENGE_ANSWER_STATUS_PAYMENT_REQUIRED. + */ + struct + { + + /** + * "taler://pay" URI with details how to pay for the challenge. + */ + const char *taler_pay_uri; + + /** + * Payment secret from @e taler_pay_uri. + */ + struct ANASTASIS_PaymentSecretP payment_secret; + + } payment_required; + + } details; +}; + + +/** + * Defines a callback for the response status for a challenge start + * operation. + * + * @param cls closure + * @param car response details + */ +typedef void +(*ANASTASIS_AnswerFeedback)( + void *cls, + const struct ANASTASIS_ChallengeAnswerResponse *car); + + +/** * Challenge answer for a security question. Is referenced to * a challenge and sends back an AnswerFeedback. Convenience * wrapper around #ANASTASIS_challenge_start that hashes @a answer @@ -310,17 +380,17 @@ ANASTASIS_challenge_start (struct ANASTASIS_Challenge *c, * @param psp information about payment made for the recovery * @param timeout how long to wait for payment * @param answer user input instruction defines which input is needed - * @param af reference to the answerfeedback which is passed back to the user - * @param af_cls closure for @a af + * @param csf function to call with the result + * @param csf_cls closure for @a csf * @return #GNUNET_OK on success */ -int +enum GNUNET_GenericReturnValue ANASTASIS_challenge_answer (struct ANASTASIS_Challenge *c, const struct ANASTASIS_PaymentSecretP *psp, struct GNUNET_TIME_Relative timeout, const char *answer, - ANASTASIS_AnswerFeedback af, - void *af_cls); + ANASTASIS_AnswerFeedback csf, + void *csf_cls); /** @@ -337,7 +407,7 @@ ANASTASIS_challenge_answer (struct ANASTASIS_Challenge *c, * @param af_cls closure for @a af * @return #GNUNET_OK on success */ -int +enum GNUNET_GenericReturnValue ANASTASIS_challenge_answer2 (struct ANASTASIS_Challenge *c, const struct ANASTASIS_PaymentSecretP *psp, struct GNUNET_TIME_Relative timeout, @@ -347,6 +417,30 @@ ANASTASIS_challenge_answer2 (struct ANASTASIS_Challenge *c, /** + * User starts a challenge which reponds out of bounds (E-Mail, SMS, + * Postal..) If the challenge is zero cost, the challenge + * instructions will be sent to the client. If the challenge needs + * payment a payment link is sent to the client. After payment the + * challenge start method has to be called again. + * + * @param c reference to the escrow challenge which is started + * @param psp payment secret, NULL if no payment was yet made + * @param timeout how long to wait for payment + * @param hashed_answer answer to the challenge + * @param af reference to the answerfeedback which is passed back to the user + * @param af_cls closure for @a af + * @return #GNUNET_OK if the challenge was successfully started + */ +enum GNUNET_GenericReturnValue +ANASTASIS_challenge_answer3 (struct ANASTASIS_Challenge *c, + const struct ANASTASIS_PaymentSecretP *psp, + struct GNUNET_TIME_Relative timeout, + const struct GNUNET_HashCode *hashed_answer, + ANASTASIS_AnswerFeedback af, + void *af_cls); + + +/** * Abort answering challenge. * * @param c reference to the escrow challenge which was started @@ -356,6 +450,67 @@ ANASTASIS_challenge_abort (struct ANASTASIS_Challenge *c); /** + * Handle for an operation to get available recovery + * document versions. + */ +struct ANASTASIS_VersionCheck; + + +/** + * Callback which passes back meta data about one of the + * recovery documents available at the provider. + * + * @param cls closure for the callback + * @param version version number of the policy document, + * 0 for the end of the list + * @param server_time time of the backup at the provider + * @param recdoc_id hash of the compressed recovery document, uniquely + * identifies the document; NULL for the end of the list + * @param secret_name name of the secret as chosen by the user, + * or NULL if the user did not provide a name + */ +typedef void +(*ANASTASIS_MetaPolicyCallback)(void *cls, + uint32_t version, + struct GNUNET_TIME_Timestamp server_time, + const struct GNUNET_HashCode *recdoc_id, + const char *secret_name); + + +/** + * Obtain an overview of available recovery policies from the + * specified provider. + * + * @param ctx context for making HTTP requests + * @param id_data contains the users identity, (user account on providers) + * @param version defines the version which will be downloaded, 0 for latest version + * @param anastasis_provider_url provider url + * @param provider_salt the server salt + * @param mpc function called with the available versions + * @param mpc_cls closure for @a mpc callback + * @return recovery operation handle + */ +struct ANASTASIS_VersionCheck * +ANASTASIS_recovery_get_versions ( + struct GNUNET_CURL_Context *ctx, + const json_t *id_data, + unsigned int max_version, + const char *anastasis_provider_url, + const struct ANASTASIS_CRYPTO_ProviderSaltP *provider_salt, + ANASTASIS_MetaPolicyCallback mpc, + void *mpc_cls); + + +/** + * Cancel version check operation. + * + * @param vc operation to cancel + */ +void +ANASTASIS_recovery_get_versions_cancel (struct ANASTASIS_VersionCheck *vc); + + +/** * Defines a Decryption Policy with multiple escrow methods */ struct ANASTASIS_DecryptionPolicy @@ -510,9 +665,9 @@ struct ANASTASIS_Recovery; * * @param ctx context for making HTTP requests * @param id_data contains the users identity, (user account on providers) - * @param version defines the version which will be downloaded NULL for latest version - * @param anastasis_provider_url NULL terminated list of possible provider urls - * @param provider_salt the server salt + * @param version defines the version which will be downloaded, 0 for latest version + * @param anastasis_provider_url provider REST API endpoint url + * @param provider_salt the provider's salt * @param pc opens the policy call back which holds the downloaded version and the policies * @param pc_cls closure for callback * @param csc core secret callback is opened, with this the core secert is passed to the client after the authentication @@ -845,7 +1000,7 @@ struct ANASTASIS_ProviderSuccessStatus /** * When will the policy expire? */ - struct GNUNET_TIME_Absolute policy_expiration; + struct GNUNET_TIME_Timestamp policy_expiration; /** * Version number of the policy at the provider. @@ -916,7 +1071,6 @@ struct ANASTASIS_ShareResult */ enum ANASTASIS_UploadStatus ec; - } provider_failure; } details; |