From ac6d31729594372c193a61e9e810516e4895037c Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Tue, 1 Mar 2022 20:51:20 +0100 Subject: sketch new truth REST API C client --- src/include/anastasis_service.h | 309 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 306 insertions(+), 3 deletions(-) (limited to 'src/include') diff --git a/src/include/anastasis_service.h b/src/include/anastasis_service.h index 3bc8f87..dc0fb12 100644 --- a/src/include/anastasis_service.h +++ b/src/include/anastasis_service.h @@ -1,6 +1,6 @@ /* This file is part of Anastasis - Copyright (C) 2019-2021 Anastasis SARL + Copyright (C) 2019-2022 Anastasis SARL Anastasis is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software @@ -462,8 +462,7 @@ struct ANASTASIS_UploadDetails * Callback to process a POST /policy request * * @param cls closure - * @param http_status HTTP status code for this request - * @param obj the decoded response body + * @param up the decoded response body */ typedef void (*ANASTASIS_PolicyStoreCallback) (void *cls, @@ -830,4 +829,308 @@ ANASTASIS_truth_store_cancel ( struct ANASTASIS_TruthStoreOperation *tso); +/** + * Possible ways how to proceed with a challenge. + */ +enum ANASTASIS_ChallengeDetailType +{ + + /** + * A challenge TAN was sent to the customer. + * A hint may be provided as to the address used. + */ + ANASTASIS_CS_TAN_SENT, + + /** + * The customer should wire funds to the bank + * account address provided. + */ + ANASTASIS_CS_WIRE_FUNDS + +}; + + +/** + * Information returned for a POST /truth/$TID/challenge request. + */ +struct ANASTASIS_TruthChallengeDetails +{ + /** + * HTTP status returned by the server. + */ + unsigned int http_status; + + /** + * Taler-specific error code, #TALER_EC_NONE on success. + */ + enum TALER_ErrorCode ec; + + /** + * Details depending on @e http_status. + */ + union + { + + /** + * Information for @e http_status of #MHD_HTTP_OK. + */ + struct + { + /** + * Meta-state about how the challenge was + * initiated and what is to be done next. + */ + enum ANASTASIS_ChallengeDetailType cs; + + /** + * Details depending on @e cs. + */ + union + { + + /** + * If @e cs is #ANASTASIS_CS_TAN_SENT, this + * is human-readable information as to where + * the TAN was sent. + */ + const char *tan_address_hint; + + /** + * If @e cs is #ANASTASIS_CS_WIRE_FUNDS, this + * structure contains information about where + * to wire the funds to authenticate as well + * as a hint as to which bank account to send + * the funds from. + */ + struct + { + + /** + * How much should be sent. + */ + struct TALER_Amount amount; + + /** + * payto:// URI with the target account number. + */ + const char *target_payto; + + /** + * Human-readable hint about which sender bank + * account must be used. + */ + const char *sender_hint; + + // FIXME: more? Wire transfer subject? + + } wire_funds; + + } details; + + } success; + + /** + * Information returne if @e http_status is #MHD_HTTP_PAYMENT_REQUIRED + */ + struct + { + /** + * A taler://pay/-URI with a request to pay the annual fee for + * the service. Returned if @e us is #ANASTASIS_US_PAYMENT_REQUIRED. + */ + const char *payment_request; + + /** + * The payment secret (aka order ID) extracted from the @e payment_request. + */ + struct ANASTASIS_PaymentSecretP ps; + } payment_required; + + } details; + +}; + + +/** + * Handle for a POST /truth/$TID/challenge operation. + */ +struct ANASTASIS_TruthChallengeOperation; + + +/** + * Callback to process a POST /truth/$TID/challenge response. + * + * @param cls closure + * @param tcd details about the key share + */ +typedef void +(*ANASTASIS_TruthChallengeCallback) ( + void *cls, + const struct ANASTASIS_TruthChallengeDetails *tcd); + + +/** + * Makes a POST /truth/$TID/challenge request. + * + * @param ctx execution context + * @param backend_url base URL of the merchant backend + * @param truth_uuid identification of the Truth + * @param truth_key Key used to Decrypt the Truth on the Server + * @param payment_secret secret from the previously done payment NULL to trigger payment + * @param cb callback which will work the response gotten from the backend + * @param cb_cls closure to pass to the callback + * @return handle for this operation, NULL upon errors + */ +struct ANASTASIS_TruthChallengeOperation * +ANASTASIS_truth_challenge ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_uuid, + const struct ANASTASIS_CRYPTO_TruthKeyP *truth_key, + const struct ANASTASIS_PaymentSecretP *payment_secret, + ANASTASIS_KeyShareLookupCallback cb, + void *cb_cls); + + +/** + * Cancel a POST /truth/$TID/challenge request. + * + * @param[in] tco operation to cancel + */ +void +ANASTASIS_truth_challenge_cancel ( + struct ANASTASIS_TruthChallengeOperation *tco); + + +/** + * Information returned for a POST /truth/$TID/solve request. + */ +struct ANASTASIS_TruthSolveReply +{ + + /** + * HTTP status returned by the server. + */ + unsigned int http_status; + + /** + * Taler-specific error code, #TALER_EC_NONE on success. + */ + enum TALER_ErrorCode ec; + + /** + * Details depending on @e http_status. + */ + union + { + + /** + * Information returned if @e http_status is #MHD_HTTP_OK. + */ + struct + { + + /** + * The encrypted key share. + */ + struct ANASTASIS_CRYPTO_EncryptedKeyShareP eks; + + } success; + + /** + * Information returne if @e http_status is #MHD_HTTP_PAYMENT_REQUIRED + */ + struct + { + /** + * A taler://pay/-URI with a request to pay the annual fee for + * the service. Returned if @e us is #ANASTASIS_US_PAYMENT_REQUIRED. + */ + const char *payment_request; + + /** + * The payment secret (aka order ID) extracted from the @e payment_request. + */ + struct ANASTASIS_PaymentSecretP ps; + } payment_required; + + /** + * Information returne if @e http_status is #MHD_HTTP_TOO_MANY_REQUESTS. + */ + 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; + } too_many_requests; + + } details; + +}; + + +/** + * Handle for a POST /truth/$TID/solve operation. + */ +struct ANASTASIS_TruthSolveOperation; + + +/** + * Callback to process a POST /truth/$TID/solve response. + * + * @param cls closure + * @param kdd details about the key share + */ +typedef void +(*ANASTASIS_TruthSolveCallback) ( + void *cls, + const struct ANASTASIS_TruthSolveReply *trs); + + +/** + * Makes a POST /truth/$TID/solve request. + * + * @param ctx execution context + * @param backend_url base URL of the merchant backend + * @param truth_uuid identification of the Truth + * @param truth_key Key used to Decrypt the Truth on the Server + * @param payment_secret secret from the previously done payment NULL to trigger payment + * @param timeout how long to wait for the payment, use + * #GNUNET_TIME_UNIT_ZERO to let the server pick + * @param hashed_answer hashed answer to the challenge + * @param cb callback which will work the response gotten from the backend + * @param cb_cls closure to pass to the callback + * @return handle for this operation, NULL upon errors + */ +struct ANASTASIS_TruthSolveOperation * +ANASTASIS_truth_solve ( + struct GNUNET_CURL_Context *ctx, + const char *backend_url, + const struct ANASTASIS_CRYPTO_TruthUUIDP *truth_uuid, + const struct ANASTASIS_CRYPTO_TruthKeyP *truth_key, + const struct ANASTASIS_PaymentSecretP *payment_secret, + struct GNUNET_TIME_Relative timeout, + const struct GNUNET_HashCode *hashed_answer, + ANASTASIS_KeyShareLookupCallback cb, + void *cb_cls); + + +/** + * Cancel a POST /truth/$TID/solve request. + * + * @param[in] tso handle of the operation to cancel + */ +void +ANASTASIS_truth_solve_cancel ( + struct ANASTASIS_TruthSolveOperation *tso); + + #endif /* _ANASTASIS_SERVICE_H */ -- cgit v1.2.3