[taler-docs] branch master updated: Adjustments to extensions

[gnunet]

This is an automated email from the git hooks/post-receive script.

oec pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 2c0db9f  Adjustments to extensions
2c0db9f is described below

commit 2c0db9f9f2d62f49363f0b049fb91db1d5d9bdd3
Author: Özgür Kesim <oec-taler@kesim.org>
AuthorDate: Fri Jan 21 13:52:08 2022 +0100

    Adjustments to extensions
    
    - 006: Extensions object now contains opaque ``config``
      - Example for Taler-configuration with extension added
    - 024: age_restriction updated according to changes in 006
---
 design-documents/006-extensions.rst      | 56 +++++++++++++++++++++-----------
 design-documents/024-age-restriction.rst |  9 +++--
 2 files changed, 44 insertions(+), 21 deletions(-)

diff --git a/design-documents/006-extensions.rst 
b/design-documents/006-extensions.rst
index 7692bb6..42a0e57 100644
--- a/design-documents/006-extensions.rst
+++ b/design-documents/006-extensions.rst
@@ -55,7 +55,8 @@ The necessary changes to ``ExchangeKeysResponse`` are 
highlighted here:
    //...
 
    // Optional field with a dictionary of (name, object) pairs defining the
-   // supported extensions.  The name MUST be non-empty and unique.
+   // supported and enabled extensions.
+   // The name MUST be non-empty and unique.
    extensions?: { name: Extension };
 
    // Signature by the exchange master key of the SHA-256 hash of the
@@ -115,30 +116,39 @@ 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 
 
@@ -156,13 +166,21 @@ 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.
+* TODO: Add examples for p2p.
 
 
 Merchant
diff --git a/design-documents/024-age-restriction.rst 
b/design-documents/024-age-restriction.rst
index 884ab27..107ba71 100644
--- a/design-documents/024-age-restriction.rst
+++ b/design-documents/024-age-restriction.rst
@@ -143,8 +143,13 @@ registering the extension ``age_restriction`` with a value 
type
       // `LibtoolVersion`.
       version: "1";
 
-      // Age restriction specific fields
-     
+      // Age restriction specific configuration
+      config: ConfigAgeRestriction;
+   }
+
+.. ts:def:: ConfigAgeRestriction
+
+   interface ConfigAgeRestriction {
       // The age groups.  This field is mandatory and binding in the sense
       // that its value is taken into consideration when signing the
       // denominations in `ExchangeKeysResponse`.``age_restricted_denoms``.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.