refined extensions: versioning and configuration

1 files changed, 79 insertions, 32 deletions

diff --git a/design-documents/006-extensions.rst b/design-documents/006-extensions.rst
index d701c6da..7692bb68 100644
--- a/design-documents/006-extensions.rst
+++ b/design-documents/006-extensions.rst
@@ -31,9 +31,6 @@ participants.
 Requirements
 ============
 
-TODO. Not sure if we have any requirements - other than particular
-ideas/designs for extensions?
-
 
 Proposed Solution
 =================
@@ -41,13 +38,13 @@ Proposed Solution
 Exchange
 ^^^^^^^^
 
-The exchange will add two new REQUIRED fields in response to ``/keys``:
+The exchange will add two new *optional* fields in response to ``/keys``:
 
-#. The (but maybe empty) field ``extensions`` which contains a dictionary of
+#. The field ``extensions`` which contains a dictionary of
    extension-names and their configuration, see below.
 
-#. The field ``extensions_sig`` that contains the EdDSA signature of the SHA256-hash
-   of the normalized JSON-string of the ``extenstions`` object.
+#. The field ``extensions_sig`` that contains the EdDSA signature of the
+   SHA256-hash of the normalized JSON-string of the ``extensions`` object.
 
 
 The necessary changes to ``ExchangeKeysResponse`` are highlighted here:
@@ -57,17 +54,14 @@ The necessary changes to ``ExchangeKeysResponse`` are highlighted here:
    interface ExchangeKeysResponse {
    //...
 
-   // Required (but maybe emtpy) field with a dictionary of (name, object)
-   // pairs defining the supported extensions.
-   // The name MUST be unique and SHOULD include version information in Taler's
-   // protocol version ranges notation as suffix, starting with letter 'v',
-   // f.e.: "age_restriction.v1" or "p2p.v1:2:3".
-   extensions: { name: Extension };
+   // Optional field with a dictionary of (name, object) pairs defining the
+   // supported extensions.  The name MUST be non-empty and unique.
+   extensions?: { name: Extension };
 
-   // Signature by the exchange master key of the SHA-512 hash of the
-   // normalized JSON-object of field ``extenstions``.
+   // Signature by the exchange master key of the SHA-256 hash of the
+   // normalized JSON-object of field ``extensions``, if it was set.
    // The signature MUST have purpose ``TALER_SIGNATURE_MASTER_EXTENSIONS``.
-   extensions_sig: EddsaSignature;
+   extensions_sig?: EddsaSignature;
 
    //...
    }
@@ -76,49 +70,101 @@ The necessary changes to ``ExchangeKeysResponse`` are highlighted here:
 Extension names
 ---------------
 
-The names of extensions MUST be unique and SHOULD include a version information
-in Taler's `protocol version ranges notation`_ as suffix starting with letter
-'``v``', f.e.: ``age_restriction.v1`` or ``p2p.v1:2:3``.
-
-.. _protocol version ranges notation: https://docs.taler.net/core/api-common.html#protocol-version-ranges
-
-The full name MUST be registered with GANA_ along with a full description of
-the extension. (TODO: be more specific)
+The names of extensions MUST be unique.  The full name MUST be registered with
+GANA_ along with a full description of the extension.
 
 .. _GANA: https://git.gnunet.org/gana.git
 
+(In the rare situation that the exchange might have to provide *multiple*
+versions of the "same" feature in parallel, multiple unique names MUST be used,
+f.e. ``age_restriction`` an ``age_restriction.v2``.)
 
 Extension object
 ----------------
 
 The definition of ``Extension`` object itself is mostly up to the particular
-feature.  **However**, it MUST contain 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 extension before proceeding, if "false" clients
-can safely skip extensions they do not understand.
+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
+   extension before proceeding, if "false" clients can safely skip extensions
+   they do not understand.
+
+#. 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:: Extension
 
    interface Extension {
-     // Same semantics as "critical" for extensions in X.509, see
-     // https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.
-     // If "true", the client must "understand" the extension before proceeding.
-     // If "false", clients can safely skip extensions they do not understand.
+     // 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
+     //   proceeding,
+     // - if "false", clients can safely skip extensions they do not
+     //   understand.
+     // (see https://datatracker.ietf.org/doc/html/rfc5280#section-4.2)
      critical: boolean;
 
+     // The version information MUST be provided in Taler's protocol version
+     // ranges notation, see
+     // https://docs.taler.net/core/api-common.html#protocol-version-ranges
+     version: LibtoolVersion;
+
      // Additional fields defined by the feature itself
      ...
 
    }
 
 
+Configuration
+-------------
+
+Extensions are *disabled* per default and must *explicetly* be enabled via the
+tool ``taler-exchange-offline``.
+
+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:
+
+* ``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.
+
+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.
+
+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
+
+#. understand them (including the version). For example, the extension for
+   age-restriction will require the exchange to perform particular steps when
+   this extension is enabled (i.e. signing denominations with support with age
+   restriction *together* with the string of age groups).
+
+#. reject a configuration that refers to any extension that the tool does not
+   know or understand.
+
+Similarly, the exchange MUST reject a signed configuration with extensions it
+does not know or understand.
+
+
+Examples
+--------
+
 **TODO**:
 
 * Add examples for age-restriction and p2p.
 
+
 Merchant
 ^^^^^^^^
 
@@ -146,3 +192,4 @@ Discussion / Q&A
 The initial ideas presented here are based on discussions between Özgür Kesim
 and Christian Grothoff.
 
+