diff options
Diffstat (limited to 'src/include/taler_extensions.h')
| -rw-r--r-- | src/include/taler_extensions.h | 180 |
1 files changed, 149 insertions, 31 deletions
diff --git a/src/include/taler_extensions.h b/src/include/taler_extensions.h index f81b9653..646d5a84 100644 --- a/src/include/taler_extensions.h +++ b/src/include/taler_extensions.h @@ -31,11 +31,11 @@ enum TALER_Extension_Type { - TALER_Extension_AgeRestriction = 0, - TALER_Extension_PolicyRefund = 1, - TALER_Extension_PolicyAuction = 2, - TALER_Extension_PolicyEscrow = 3, - TALER_Extension_MaxPredefined = 4 // Must be last of the predefined + TALER_Extension_AgeRestriction = 0, + TALER_Extension_PolicyMerchantRefund = 1, + TALER_Extension_PolicyBrandtVickeryAuction = 2, + TALER_Extension_PolicyEscrowedPayment = 3, + TALER_Extension_MaxPredefined = 4 // Must be last of the predefined }; @@ -52,42 +52,149 @@ struct TALER_Extensions /* * @brief Represents the implementation of an extension. * - * TODO: add documentation + * An "Extension" is an optional feature for the Exchange. + * There are only two types of extensions: + * + * a) Age restriction: This is a special feature that directly interacts with + * denominations and coins, but is not define policies during deposits, see b). + * The implementation of this extension doesn't have to implement any of the + * http- or depost-handlers in the struct. + * + * b) Policies for deposits: These are extensions that define policies (such + * as refund, escrow or auctions) for deposit requests. These extensions have + * to implement at least the deposit- and post-http-handler in the struct to be + * functional. + * + * In addition to the handlers defined in this struct, an extension must also + * be a plugin in the GNUNET_Plugin sense. That is, it must implement the + * functions + * 1: (void *ext)libtaler_extension_<name>_init(void *cfg) + * and + * 2: (void *)libtaler_extension_<name>_done(void *) + * + * In 1:, the input will be the GNUNET_CONFIGURATION_Handle to the TALER + * configuration and the output must be the struct TALER_Extension * on + * success, NULL otherwise. + * + * In 2:, no arguments are passed and NULL is expected to be returned. */ struct TALER_Extension { + /** + * Type of the extension. Only one extension of a type can be loaded + * at any time. + */ enum TALER_Extension_Type type; + + /** + * The name of the extension, must be unique among all loaded extensions. It + * is used in URLs for /extension/$NAME as well. + */ char *name; + + /** + * Criticality of the extension. It has the same semantics as "critical" has + * for extensions in X.509: + * - if "true", the client must "understand" the extension before proceeding, + * - if "false", clients can safely skip extensions they do not understand. + * (see https://datatracker.ietf.org/doc/html/rfc5280#section-4.2) + */ bool critical; + + /** + * Version of the extension must be provided in Taler's protocol verison ranges notation, see + * https://docs.taler.net/core/api-common.html#protocol-version-ranges + */ char *version; - void *config; + + /** + * If the extension is marked as enabled, it will be listed in the + * "extensions" field in the "/keys" response. + */ bool enabled; - bool has_config; /* some extension might not have a configuration */ - json_t *config_json; - void (*disable)(struct TALER_Extension *ext); + /** + * Opaque (public) configuration object, set by the extension. + */ + void *config; - enum GNUNET_GenericReturnValue (*test_json_config)( - const json_t *config); - enum GNUNET_GenericReturnValue (*load_json_config)( + /** + * @brief Handler to to disable the extension. + * + * @param ext The current extension object + */ + void (*disable)(struct TALER_Extension *ext); + + /** + * @brief Handler to read an extension-specific configuration in JSON + * encoding and enable the extension. Must be implemented by the extension. + * + * @param ext The extension object. If NULL, the configuration will only be checked. + * @param config A JSON blob + * @return GNUNET_OK if the json was a valid configuration for the extension. + */ + enum GNUNET_GenericReturnValue (*load_config)( struct TALER_Extension *ext, json_t *config); - json_t *(*config_to_json)( + /** + * @brief Handler to return the manifest of the extension in JSON encoding. + * + * See + * https://docs.taler.net/design-documents/006-extensions.html#tsref-type-Extension + * for the definition. + * + * @param ext The extension object + * @return The JSON encoding of the extension, if enabled, NULL otherwise. + */ + json_t *(*manifest)( const struct TALER_Extension *ext); + /** + * @brief Handler for /{batch}-deposit requests. Can be NULL. + * + * When a deposit request refers to this extension in its policy + * (see https://docs.taler.net/core/api-exchange.html#deposit), this handler + * will be called during the deposit operation. + * + * @param[in] input The policy/extension specific data, provided by the client in + * the policy-field of the deposit request. + * @param[out] output Potential output by the extension to be provided to the + * client as part of the response to the deposit request. Can be NULL. + * @return GNUNET_OK if the data was accepted by the extension. + */ + enum GNUNET_GenericReturnValue (*deposit_handler)( + json_t *input, + json_t **output); + + /** + * @brief Handler for POST-requests to the /policy/$name endpoint. Can be NULL. + * + * @param connection The current connection + * @param root The JSON body from the request + * @param args Additional query parameters of the request. + * @return MDH result + */ MHD_RESULT (*http_post_handler)( struct MHD_Connection *connection, const json_t *root, const char *const args[]); + /** + * @brief Handler for GET-requests to the /policy/$name endpoint. Can be NULL. + * + * @param connection The current connection + * @param root The JSON body from the request + * @param args Additional query parameters of the request. + * @return MDH result + */ MHD_RESULT (*http_get_handler)( struct MHD_Connection *connection, const char *const args[]); - }; + /** * Generic functions for extensions */ @@ -101,39 +208,38 @@ struct TALER_Extension * or any particular configuration couldn't be parsed. */ enum GNUNET_GenericReturnValue -TALER_extensions_load ( +TALER_extensions_init ( const struct GNUNET_CONFIGURATION_Handle *cfg); /* - * @brief Checks the given obj to be a valid extension object and fill the - * fields accordingly. + * @brief Parses a given JSON object as an extension manifest. * - * @param[in] obj Object to verify is a valid extension + * @param[in] obj JSON object to parse as an extension manifest * @param{out] critical will be set to 1 if the extension is critical according to obj * @param[out] version will be set to the version of the extension according to obj * @param[out] config will be set to the configuration of the extension according to obj * @return OK on success, Error otherwise */ enum GNUNET_GenericReturnValue -TALER_extensions_is_json_config ( +TALER_extensions_parse_manifest ( json_t *obj, int *critical, const char **version, json_t **config); /* - * @brief Sets the configuration of the extensions from a given JSON object. + * @brief Loads extensions according to the manifests. * - * The JSON object must be of type ExchangeKeysResponse as described in - * https://docs.taler.net/design-documents/006-extensions.html#exchange + * The JSON object must be of type ExtensionsManifestsResponse as described + * in https://docs.taler.net/design-documents/006-extensions.html#exchange * - * @param cfg JSON object containing the configuration for all extensions + * @param cfg JSON object containing the manifests for all extensions * @return #GNUNET_OK on success, #GNUNET_SYSERR if unknown extensions were * found or any particular configuration couldn't be parsed. */ enum GNUNET_GenericReturnValue -TALER_extensions_load_json_config ( - json_t *cfg); +TALER_extensions_load_manifests ( + json_t *manifests); /* * @brief Returns the head of the linked list of extensions. @@ -186,7 +292,7 @@ TALER_extensions_is_enabled ( * Verify the signature of a given JSON object for extensions with the master * key of the exchange. * - * The JSON object must be of type ExchangeKeysResponse as described in + * The JSON object must be of type ExtensionsManifestsResponse as described in * https://docs.taler.net/design-documents/006-extensions.html#exchange * * @param extensions JSON object with the extension configuration @@ -196,8 +302,8 @@ TALER_extensions_is_enabled ( * and GNUNET_NO if the signature couldn't be verified. */ enum GNUNET_GenericReturnValue -TALER_extensions_verify_json_config_signature ( - json_t *extensions, +TALER_extensions_verify_manifests_signature ( + json_t *manifests, struct TALER_MasterSignatureP *extensions_sig, struct TALER_MasterPublicKeyP *master_pub); @@ -207,6 +313,8 @@ TALER_extensions_verify_json_config_signature ( * * This extension is special insofar as it directly interacts with coins and * denominations. + * + * At the same time, it doesn't implement and http- or deposit-handlers. */ #define TALER_EXTENSION_SECTION_AGE_RESTRICTION (TALER_EXTENSION_SECTION_PREFIX \ @@ -228,7 +336,6 @@ TALER_extensions_verify_json_config_signature ( */ struct TALER_AgeRestrictionConfig { - bool enabled; struct TALER_AgeMask mask; uint8_t num_groups; }; @@ -260,7 +367,18 @@ TALER_extensions_get_age_restriction_mask (); /* - * TODO: Add Peer2Peer Extension + * ================================ + * Brandt-Vickrey Auctions + * ================================ + */ +/* + * @brief Configuration for Brandt-Vickrey auctions */ +struct TALER_BrandtVickreyAuction +{ + uint16_t max_bidders; + uint16_t max_prices; + struct TALER_Amount auction_fee; +}; #endif |