006-extensions.rst (7293B)
1 DD 06: Extensions for GNU Taler 2 ############################### 3 4 Summary 5 ======= 6 7 This design document describes a generic framework for how extensions (i.e. 8 optional features) to GNU Taler can be offered and used by the exchange, 9 merchants and wallets. 10 11 Motivation 12 ========== 13 14 GNU Taler's list of supported features evolves over time. For example, the 15 following features are going to be designed and implemented during the course 16 of 2021 and 2022: 17 18 * Peer-to-peer payments 19 * Anonymous age-restriction 20 * Escrow service for anonymous auctions 21 * A general escrow service 22 23 We call a feature an *extension* when it is *optional* for either the 24 exchange, wallet or merchant to enable and support it. (However, enabling 25 a feature might *require* the other parties to support the feature, too) 26 27 For optional features we therefore need a mechanism to express the 28 availability, version and configuration of a particular feature, f.e. p2p or 29 age-restriction offered by an exchange, and make it verifiable by the other 30 participants. 31 32 Requirements 33 ============ 34 35 36 Proposed Solution 37 ================= 38 39 Exchange 40 ^^^^^^^^ 41 42 The exchange will add two new *optional* fields in response to ``/keys``: 43 44 #. The field ``extensions`` which contains a dictionary of 45 extension-names and their configuration, see below. 46 47 #. The field ``extensions_sig`` that contains the EdDSA signature of the 48 SHA256-hash of the normalized JSON-string of the ``extensions`` object. 49 50 51 The necessary changes to ``ExtensionsManifestsResponse`` are highlighted here: 52 53 .. ts:def:: ExtensionsManifestsResponse 54 55 interface ExtensionsManifestsResponse { 56 //... 57 58 // Optional field with a dictionary of (name, object) pairs defining the 59 // supported and enabled extensions. 60 // The name MUST be non-empty and unique. 61 extensions?: { name: ExtensionManifest }; 62 63 // Signature by the exchange master key of the SHA-256 hash of the 64 // normalized JSON-object of field ``extensions``, if it was set. 65 // The signature MUST have purpose ``TALER_SIGNATURE_MASTER_EXTENSIONS``. 66 extensions_sig?: EddsaSignature; 67 68 //... 69 } 70 71 72 Extension names 73 --------------- 74 75 The names of extensions MUST be unique. The full name MUST be registered with 76 GANA_ along with a full description of the extension. 77 78 .. _GANA: https://git.gnunet.org/gana.git 79 80 (In the rare situation that the exchange might have to provide *multiple* 81 versions of the "same" feature in parallel, multiple unique names MUST be used, 82 f.e. ``age_restriction`` an ``age_restriction.v2``.) 83 84 ExtensionManifest object 85 --------------------------- 86 87 The definition of ``ExtensionManifest`` object itself is mostly up to the 88 particular feature. **However**, it MUST have 89 90 #. the boolean field ``critical`` that has the same semantics as as "critical" 91 has for extensions in X.509_: if true, the client must "understand" the 92 extension before proceeding, if "false" clients can safely skip extensions 93 they do not understand. 94 95 #. the field ``version`` of type `LibtoolVersion` which contains the version 96 information of the extension in Taler's `protocol version ranges notation`_. 97 98 .. _X.509: https://datatracker.ietf.org/doc/html/rfc5280#section-4.2 99 100 .. _`protocol version ranges notation`: https://docs.taler.net/core/api-common.html#protocol-version-ranges 101 102 .. ts:def:: ExtensionManifest 103 104 interface ExtensionManifest { 105 // The criticality of the extension MUST be provided. It has the same 106 // semantics as "critical" has for extensions in X.509: 107 // - if "true", the client must "understand" the extension before 108 // proceeding, 109 // - if "false", clients can safely skip extensions they do not 110 // understand. 111 // (see https://datatracker.ietf.org/doc/html/rfc5280#section-4.2) 112 critical: boolean; 113 114 // The version information MUST be provided in Taler's protocol version 115 // ranges notation, see 116 // https://docs.taler.net/core/api-common.html#protocol-version-ranges 117 version: LibtoolVersion; 118 119 // Optional configuration object, defined by the feature itself 120 config?: object; 121 } 122 123 124 Configuration 125 ------------- 126 127 Extensions are *disabled* per default and must *explicetly* be enabled in the 128 the TALER configuration manually. The configurations of all enabled extensions 129 are signed with the master key and uploaded to the exchange with the tool 130 ``taler-exchange-offline``. 131 132 Each extension has its own section in the configuration, starting with the 133 prefix ``exchange-extension-``, like ``[exchange-extension-age_restriction]``. 134 The field ``ENABLED = YES|NO`` is used to enable or disable the corresponding 135 extension. If the extension has its own configuration parameters, they MAY be 136 optional, in which case the ``taler-exchange-offline`` tool MUST fill them with 137 safe default values. 138 139 The ``taler-exchange-offline`` tool MUST offer the subcommand ``extensions`` 140 for showing and signing extensions. For this purpose, the following 141 sub-subcommands MUST be available: 142 143 * ``extensions show``: List all available extensions, their versions, 144 criticality and whether they are enabled. 145 * ``extensions sign``: Sign the configuration of all enabled extensions with 146 the master key and prepare a JSON-object for the ``upload`` command. 147 148 When extensions are offered and enabled by an exchange, the ``extensions`` 149 object MUST be signed by the exchange's master signing key. Whenever 150 extensions are enabled or disabled, the offline tool MUST sign the SHA256 hash 151 of the normalized JSON-string of the ``extensions`` object, if it is not empty. 152 153 In order to do so, the ``taler-exchange-offline`` tool MUST 154 155 #. have the complete list of all available optional features/extensions and 156 their versions builtin and 157 158 #. understand them (including the version). For example, the extension for 159 age-restriction will require the exchange to perform particular steps when 160 this extension is enabled (i.e. signing denominations with support with age 161 restriction *together* with the string of age groups). 162 163 #. reject a configuration that refers to any extension that the tool does not 164 know or understand. 165 166 Similarly, the exchange MUST reject a signed configuration with extensions it 167 does not know or understand. 168 169 Examples 170 -------- 171 172 A configuration for age-restriction in the taler configuration would look like 173 this: 174 175 .. code:: none 176 177 [exchange-extension-age_restriction] 178 ENABLED = true 179 # default: 180 AGE_GROUPS = "8:10:12:14:16:18:21" 181 182 183 [exchange-extension-policy_brandt_vickery_auction] 184 ENABLED = true 185 REPLAY_PROGRAM = "/usr/local/bin/taler-exchange-auction_replay" 186 187 188 Merchant 189 ^^^^^^^^ 190 191 TODO: 192 193 * Needs to express support for particular extensions, too. F.e. age-restriction. 194 195 Extension Plugins 196 ================== 197 198 TODO: 199 200 * describe ``struct TALER_Extension`` 201 * describe the plugin loading mechanism for extensions 202 * describe the various handlers 203 204 205 Alternatives 206 ============ 207 208 TODO. None yet. 209 210 211 Drawbacks 212 ========= 213 214 * We do not offer (yet) any lifetime cycle of a feature, that is: There are 215 only two states that a feature can be in: "available" or "not-available". 216 217 * The existing design for peer-to-peer payments must be adapted to this. 218 219 Discussion / Q&A 220 ================ 221 222 The initial ideas presented here are based on discussions between Özgür Kesim 223 and Christian Grothoff.