summaryrefslogtreecommitdiff
path: root/design-documents/006-extensions.rst
blob: d701c6da2703715e67455d8cf82ae9616f93a527 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
Design Doc 006: Extensions for GNU Taler
#############################################

Summary
=======

This design document describes a generic framework for how extensions (i.e.
optional features) to GNU Taler can be offered and used by the exchange,
merchants and wallets.

Motivation
==========

GNU Taler's list of supported features evolves over time.  For example, the
following features are going to be designed and implemented during the course
of 2021 and 2022:

* Peer-to-peer payments
* Anonymous age-restriction
* Escrow service for anonymous auctions

We call a feature an *extension* when it is *optional* for either the
exchange, wallet or merchant to enable and support it. (However, enabling
a feature might *require* the other parties to support the feature, too)

For optional features we therefore need a mechanism to express the
availability, version and configuration of a particular feature, f.e. p2p or
age-restriction offered by an exchange, and make it verifiable by the other
participants.

Requirements
============

TODO. Not sure if we have any requirements - other than particular
ideas/designs for extensions?


Proposed Solution
=================

Exchange
^^^^^^^^

The exchange will add two new REQUIRED fields in response to ``/keys``:

#. The (but maybe empty) 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 necessary changes to ``ExchangeKeysResponse`` are highlighted here:

.. ts:def:: ExchangeKeysResponse

   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 };

   // Signature by the exchange master key of the SHA-512 hash of the
   // normalized JSON-object of field ``extenstions``.
   // The signature MUST have purpose ``TALER_SIGNATURE_MASTER_EXTENSIONS``.
   extensions_sig: EddsaSignature;

   //...
   }


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


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.

.. _X.509: https://datatracker.ietf.org/doc/html/rfc5280#section-4.2


.. 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.
     critical: boolean;

     // Additional fields defined by the feature itself
     ...

   }


**TODO**:

* Add examples for age-restriction and p2p.

Merchant
^^^^^^^^

TODO:

* Needs to express support for particular extensions, too.  F.e. age-restriction.

Alternatives
============

TODO.  None yet.


Drawbacks
=========

* We do not offer (yet) any lifetime cycle of a feature, that is:  There are
  only two states that a feature can be in: "available" or "not-available".

* The existing design for peer-to-peer payments must be adapted to this.

Discussion / Q&A
================

The initial ideas presented here are based on discussions between Özgür Kesim
and Christian Grothoff.