[taler-docs] branch master updated: required -> critical; description out

[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 fae2d3f  required -> critical; description out
fae2d3f is described below

commit fae2d3ff5e801b5bdb848c260684a1a71889237f
Author: Özgür Kesim <oec@codeblau.de>
AuthorDate: Thu Oct 14 14:26:17 2021 +0200

    required -> critical; description out
---
 design-documents/006-extensions.rst      | 42 ++++++++++++++++++++------------
 design-documents/024-age-restriction.rst | 15 +++---------
 2 files changed, 31 insertions(+), 26 deletions(-)

diff --git a/design-documents/006-extensions.rst 
b/design-documents/006-extensions.rst
index ee3a287..6c5a42d 100644
--- a/design-documents/006-extensions.rst
+++ b/design-documents/006-extensions.rst
@@ -49,12 +49,6 @@ The exchange will add two new REQUIRED fields in response to 
``/keys``:
 #. The field ``extensions_sig`` that contains the EdDSA signature of the 
SHA256-hash
    of the normalized JSON-string of the ``extenstions`` object.
 
-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 necessary changes to ``ExchangeKeysResponse`` are highlighted here:
 
@@ -79,22 +73,40 @@ 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)
+
+.. _GANA: https://git.gnunet.org/gana.git
+
 The definition of ``Extension`` object itself is mostly up to the particular
-feature.  However, it MUST contain the following fields:
+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.
 
-* ``description`` ― a short description of the feature itself.  Can be used by 
wallets to display information about the feature to the customer.
+.. _X.509: https://datatracker.ietf.org/doc/html/rfc5280#section-4.2
 
-*  ``required`` ― a boolean that indicates if this feature MUST be supported 
by the wallets and/or merchants in order to use this exchange.
+
+Extension object
+----------------
 
 .. ts:def:: Extension
 
    interface Extension {
-     // Short description of the feature.
-     description: string;
-
-     // Set to ``true`` if this extension MUST be supported by wallets and/or
-     // merchants.
-     required: boolean;
+     // 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.
+     critical: boolean;
 
      // Additional fields defined by the feature itself
      ...
diff --git a/design-documents/024-age-restriction.rst 
b/design-documents/024-age-restriction.rst
index ccc2a84..fc0c030 100644
--- a/design-documents/024-age-restriction.rst
+++ b/design-documents/024-age-restriction.rst
@@ -89,17 +89,10 @@ registering the extension ``age_restriction.v1`` with a 
value type
 .. ts:def:: ExtensionAgeRestriction
 
    interface ExtensionAgeRestriction {
-      // The fields ``description`` and ``required`` are mandatory for each
-      // extension.
-      
-      // Description will be something like:
-      // "Support for age restriction version 1 enabled. See
-      //  https://docs.taler.net/design-documents/024-age-restriction.html";;
-      description: string;
-
-      // Age restriction is not required to be supported by a wallet or
-      // merchant, so ``required`` will be set to ``false``.
-      required: boolean;
+      // The field ``critical`` is mandatory for an extension.
+      // Age restriction is not required to be understood by an client, so
+      // ``critical`` will be set to ``false``.
+      critical: false;
 
       // Age restriction specific fields.
 

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