diff options
Diffstat (limited to 'design-documents/006-extensions.rst')
| -rw-r--r-- | design-documents/006-extensions.rst | 100 |
1 files changed, 64 insertions, 36 deletions
diff --git a/design-documents/006-extensions.rst b/design-documents/006-extensions.rst index 7692bb68..25afe3bc 100644 --- a/design-documents/006-extensions.rst +++ b/design-documents/006-extensions.rst @@ -1,5 +1,5 @@ -Design Doc 006: Extensions for GNU Taler -############################################# +DD 06: Extensions for GNU Taler +############################### Summary ======= @@ -18,6 +18,7 @@ of 2021 and 2022: * Peer-to-peer payments * Anonymous age-restriction * Escrow service for anonymous auctions +* A general escrow service We call a feature an *extension* when it is *optional* for either the exchange, wallet or merchant to enable and support it. (However, enabling @@ -47,16 +48,17 @@ The exchange will add two new *optional* fields in response to ``/keys``: SHA256-hash of the normalized JSON-string of the ``extensions`` object. -The necessary changes to ``ExchangeKeysResponse`` are highlighted here: +The necessary changes to ``ExtensionsManifestsResponse`` are highlighted here: -.. ts:def:: ExchangeKeysResponse +.. ts:def:: ExtensionsManifestsResponse - interface ExchangeKeysResponse { + interface ExtensionsManifestsResponse { //... // Optional field with a dictionary of (name, object) pairs defining the - // supported extensions. The name MUST be non-empty and unique. - extensions?: { name: Extension }; + // supported and enabled extensions. + // The name MUST be non-empty and unique. + extensions?: { name: ExtensionManifest }; // Signature by the exchange master key of the SHA-256 hash of the // normalized JSON-object of field ``extensions``, if it was set. @@ -79,11 +81,11 @@ GANA_ along with a full description of the extension. versions of the "same" feature in parallel, multiple unique names MUST be used, f.e. ``age_restriction`` an ``age_restriction.v2``.) -Extension object ----------------- +ExtensionManifest object +--------------------------- -The definition of ``Extension`` object itself is mostly up to the particular -feature. **However**, it MUST have +The definition of ``ExtensionManifest`` object itself is mostly up to the +particular feature. **However**, it MUST have #. the boolean field ``critical`` that has the same semantics as as "critical" has for extensions in X.509_: if true, the client must "understand" the @@ -92,15 +94,14 @@ feature. **However**, it MUST have #. the field ``version`` of type `LibtoolVersion` which contains the version information of the extension in Taler's `protocol version ranges notation`_. - + .. _X.509: https://datatracker.ietf.org/doc/html/rfc5280#section-4.2 .. _`protocol version ranges notation`: https://docs.taler.net/core/api-common.html#protocol-version-ranges +.. ts:def:: ExtensionManifest -.. ts:def:: Extension - - interface Extension { + interface ExtensionManifest { // The criticality of the extension MUST be provided. It has the same // semantics as "critical" has for extensions in X.509: // - if "true", the client must "understand" the extension before @@ -115,32 +116,41 @@ feature. **However**, it MUST have // https://docs.taler.net/core/api-common.html#protocol-version-ranges version: LibtoolVersion; - // Additional fields defined by the feature itself - ... - + // Optional configuration object, defined by the feature itself + config?: object; } Configuration ------------- -Extensions are *disabled* per default and must *explicetly* be enabled via the -tool ``taler-exchange-offline``. +Extensions are *disabled* per default and must *explicetly* be enabled in the +the TALER configuration manually. The configurations of all enabled extensions +are signed with the master key and uploaded to the exchange with the tool +``taler-exchange-offline``. + +Each extension has its own section in the configuration, starting with the +prefix ``exchange-extension-``, like ``[exchange-extension-age_restriction]``. +The field ``ENABLED = YES|NO`` is used to enable or disable the corresponding +extension. If the extension has its own configuration parameters, they MAY be +optional, in which case the ``taler-exchange-offline`` tool MUST fill them with +safe default values. -The ``taler-exchange-offline-tool`` MUST offer the subcommand ``extensions`` -for enabling/disabling and setting up particular extensions. For this purpose, -the following sub-subcommands MUST be available: +The ``taler-exchange-offline`` tool MUST offer the subcommand ``extensions`` +for showing and signing extensions. For this purpose, the following +sub-subcommands MUST be available: -* ``list``: List all available extensions, their versions and criticality -* ``enable <name>``: Enable the extension with the given name. -* ``disable <name>``: disable the extension with the given name. +* ``extensions show``: List all available extensions, their versions, + criticality and whether they are enabled. +* ``extensions sign``: Sign the configuration of all enabled extensions with + the master key and prepare a JSON-object for the ``upload`` command. -When extensions are offered by an exchange the ``extensions`` object MUST be -signed by the exchange's master signing key. Whenever extensions are enabled -or disabled, the offline tool MUST sign the SHA256 hash of the normalized -JSON-string of the ``extensions`` object, if it is not empty. +When extensions are offered and enabled by an exchange, the ``extensions`` +object MUST be signed by the exchange's master signing key. Whenever +extensions are enabled or disabled, the offline tool MUST sign the SHA256 hash +of the normalized JSON-string of the ``extensions`` object, if it is not empty. -In order to do so, the ``taler-exchange-offline`` tool MUST +In order to do so, the ``taler-exchange-offline`` tool MUST #. have the complete list of all available optional features/extensions and their versions builtin and @@ -156,13 +166,23 @@ In order to do so, the ``taler-exchange-offline`` tool MUST Similarly, the exchange MUST reject a signed configuration with extensions it does not know or understand. - Examples -------- -**TODO**: +A configuration for age-restriction in the taler configuration would look like +this: + +.. code:: none + + [exchange-extension-age_restriction] + ENABLED = true + # default: + AGE_GROUPS = "8:10:12:14:16:18:21" + -* Add examples for age-restriction and p2p. + [exchange-extension-policy_brandt_vickery_auction] + ENABLED = true + REPLAY_PROGRAM = "/usr/local/bin/taler-exchange-auction_replay" Merchant @@ -172,6 +192,16 @@ TODO: * Needs to express support for particular extensions, too. F.e. age-restriction. +Extension Plugins +================== + +TODO: + +* describe ``struct TALER_Extension`` +* describe the plugin loading mechanism for extensions +* describe the various handlers + + Alternatives ============ @@ -191,5 +221,3 @@ Discussion / Q&A The initial ideas presented here are based on discussions between Özgür Kesim and Christian Grothoff. - - |