From cf4b6ebd6de3370da4b16d2f1ef19a2a3d3d0b12 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 2 Mar 2022 23:39:26 +0100 Subject: push new /truth/ API through the entire implementation --- src/include/anastasis.h | 309 ++++++++++++++++++++++++++++++------------------ 1 file changed, 194 insertions(+), 115 deletions(-) (limited to 'src/include/anastasis.h') diff --git a/src/include/anastasis.h b/src/include/anastasis.h index 92c0745..90f3f5d 100644 --- a/src/include/anastasis.h +++ b/src/include/anastasis.h @@ -97,61 +97,38 @@ 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, - - /** - * We encountered an error talking to the Anastasis service. - */ - ANASTASIS_CHALLENGE_STATUS_SERVER_FAILURE, + ANASTASIS_CHALLENGE_START_STATUS_PAYMENT_REQUIRED, /** * The server does not know this truth. */ - ANASTASIS_CHALLENGE_STATUS_TRUTH_UNKNOWN, + ANASTASIS_CHALLENGE_START_STATUS_TRUTH_UNKNOWN, /** - * The rate limit for solving the challenge was exceeded. + * A filename with the TAN has been provided. */ - ANASTASIS_CHALLENGE_STATUS_RATE_LIMIT_EXCEEDED, + ANASTASIS_CHALLENGE_START_STATUS_FILENAME_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 send, address hint is provided. */ - ANASTASIS_CHALLENGE_STATUS_AUTH_TIMEOUT, + ANASTASIS_CHALLENGE_START_STATUS_TAN_SENT_HINT_PROVIDED, /** - * 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 +138,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,36 +167,159 @@ struct ANASTASIS_ChallengeStartResponse /** * Challenge details provided if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_INSTRUCTIONS + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_FILENAME_PROVIDED. + */ + const char *tan_filename; + + /** + * Challenge details provided if + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_TAN_SENT_HINT_PROVIDED. + */ + const char *tan_address_hint; + + /** + * Challenge details provided if + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_BANK_TRANSFER_REQUIRED. + */ + struct ANASTASIS_WireFundsDetails bank_transfer_required; + + /** + * Response with instructions for how to pay, if + * @e cs is #ANASTASIS_CHALLENGE_START_STATUS_PAYMENT_REQUIRED. */ struct { /** - * Response with server-side instructions for the user. + * "taler://pay" URI with details how to pay for the challenge. */ - const void *body; + const char *taler_pay_uri; /** - * Mime type of the data in @e body. + * Payment secret from @e taler_pay_uri. */ - const char *content_type; + struct ANASTASIS_PaymentSecretP payment_secret; - /** - * Number of bytes in @e body - */ - size_t body_size; + } payment_required; + + } details; +}; - /** - * 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; + +/** + * Defines a callback for the response status for a challenge start + * operation. + * + * @param cls closure + * @param csr response details + */ +typedef void +(*ANASTASIS_ChallengeStartFeedback)( + void *cls, + const struct ANASTASIS_ChallengeStartResponse *csr); + + +/** + * 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 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_start (struct ANASTASIS_Challenge *c, + const struct ANASTASIS_PaymentSecretP *psp, + 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, + + /** + * The user did not satisfy the (external) authentication + * challenge in time. The request should be repeated + * later and may then succeed. + */ + ANASTASIS_CHALLENGE_ANSWER_STATUS_AUTH_TIMEOUT + + +}; + + +/** + * 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_STATUS_RATE_LIMIT_EXCEEDED. + * Details for #ANASTASIS_CHALLENGE_ANSWER_STATUS_RATE_LIMIT_EXCEEDED. */ struct { @@ -226,21 +337,9 @@ struct ANASTASIS_ChallengeStartResponse } rate_limit_exceeded; - /** - * Response with details if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_EXTERNAL_INSTRUCTIONS. - */ - const json_t *external_challenge; - - /** - * Response with URL to redirect the user to, if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_REDIRECT_FOR_AUTHENTICATION. - */ - const char *redirect_url; - /** * Response with instructions for how to pay, if - * @e cs is #ANASTASIS_CHALLENGE_STATUS_PAYMENT_REQUIRED. + * @e cs is #ANASTASIS_CHALLENGE_ANSWER_STATUS_PAYMENT_REQUIRED. */ struct { @@ -257,26 +356,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; }; @@ -286,36 +365,12 @@ struct ANASTASIS_ChallengeStartResponse * operation. * * @param cls closure - * @param csr response details + * @param car response details */ typedef void (*ANASTASIS_AnswerFeedback)( void *cls, - const struct ANASTASIS_ChallengeStartResponse *csr); - - -/** - * 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, 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 - */ -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, - void *af_cls); + const struct ANASTASIS_ChallengeAnswerResponse *car); /** @@ -328,8 +383,8 @@ 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 */ enum GNUNET_GenericReturnValue @@ -337,8 +392,8 @@ 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); /** @@ -364,6 +419,30 @@ ANASTASIS_challenge_answer2 (struct ANASTASIS_Challenge *c, void *af_cls); +/** + * 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. * -- cgit v1.2.3