From f169eeadde1b90bbf378c5f8ec8064054b65772a Mon Sep 17 00:00:00 2001 From: Özgür Kesim Date: Wed, 20 Oct 2021 11:30:57 +0200 Subject: refined extensions: versioning and configuration --- design-documents/006-extensions.rst | 111 +++++++++++++++++++++++++----------- 1 file 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 ``: Enable the extension with the given name. +* ``disable ``: 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. + -- cgit v1.2.3