summaryrefslogtreecommitdiff
path: root/manpages/taler-exchange-offline.1.rst
blob: 8d62ac5fe51eabc648f6815f4ff11330ed21f19f (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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
taler-exchange-offline(1)
#########################

.. only:: html

   Name
   ====

   **taler-exchange-offline** - perform operations with exchange offline master private key

Synopsis
========

**taler-exchange-offline**
[**-c** *FILENAME* | **––config=**\ ‌\ *FILENAME*]
[**-h** | **––help**]
[**-L** *LOGLEVEL* | **––loglevel=**\ ‌\ *LOGLEVEL*]
[**-o** *FILE* | **––output=**\ ‌\ *FILE*]
[**-v** | **––version**]
[subcommand ...]


Description
===========

**taler-exchange-offline** is a command-line tool to interact with the Taler
exchange's master private key. Most operations of this tool require access to
the exchange’s long-term offline signing key and should be run in a secure
(offline) environment under strict controls.  The tool takes a list of
subcommands as arguments which are then processed sequentially.

The tool includes two subcommands to interact *online* with the exchange's
REST APIs.  The ``download`` subcommand downloads the future public keys from the
running exchange.  The resulting data serves as input to the ``sign`` and ``show``
subcommands.  The ``upload`` subcommand uploads the signatures created with the
private master key to the exchange.  It handles the output of all subcommands
(except ``download``).  The ``download`` and ``upload`` subcommands must naturally be
run "online" and do not require access to the offline key.

All other subcommands are intended to be run "offline". However, especially
when testing, it is of course possible to run the subcommands online as well.
Generally, subcommands read inputs (beyond command-line arguments)
from ``stdin``. However, they may also consume outputs of previous
subcommands.  The outputs of multiple subcommands are automatically combined,
and if not consumed the final output is printed to ``stdout``.


The general options for **taler-exchange-offline** are:

**-c** *FILENAME* \| **––config=**\ ‌\ *FILENAME*
   Use the configuration and other resources for the merchant to operate
   from *FILENAME*.

**-h** \| **––help**
   Print short help on options.

**-L** *LOGLEVEL* \| **––loglevel=**\ ‌\ *LOGLEVEL*
   Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``,
   ``WARNING``, ``ERROR``.

**-o** *FILE* \| **––output=**\ ‌\ *FILE*
   Where to write a denomination key signing request file to be given to
   the auditor.

**-v** \| **––version**
   Print version information.


Configuration
=============

The exchange validates all operations by checking the signatures against the
master public key that must be provided in the exchange configuration. To
obtain the master public key, use:

.. code-block:: console

   $ MASTER_PRIV_FILE=`taler-config -f -c $CONF -s EXCHANGE -o MASTER_PRIV_FILE`
   $ gnunet-ecc -p $MASTER_PRIV_FILE

Note that if the private key file does not yet exist, the above will fail.
In this case, create the private key using:

.. code-block:: console

   $ MASTER_PRIV_FILE=`taler-config -f -c $CONF -s EXCHANGE -o MASTER_PRIV_FILE`
   $ MASTER_PRIV_DIR=`dirname $MASTER_PRIV_FILE`
   $ mkdir -p $MASTER_PRIV_DIR
   $ gnunet-ecc -g1 $MASTER_PRIV_FILE


Relevant configuration options for **taler-exchange-offline** are:

* ``[exchange/BASE_URL]`` --- how to reach the exchange (for download/upload)
* ``[exchange-offline/MASTER_PRIV_FILE]`` --- where to store the private keys
* ``[exchange-offline/SECM_TOFU_FILE]`` --- where to store TOFU data



Subcommands
===========

download
--------

This subcommand must be run online. It downloads future signing and denomination
keys with the associated meta data from the exchange and outputs the resulting
JSON (for consumption by subsequent subcommands, or to ``stdout``).


show
----

This subcommand outputs information about future signing and denomination keys for
manual checking against the business-approved fee structure, lifetimes and
other parameters.

It consumes the output of the ``download`` subcommand, either from ``stdin`` or
directly.

Its output always goes to ``stdout`` for human consumption (not in JSON).  It
is usually a bad idea (but possible) to combine ``show`` with other subcommands,
except maybe for testing.


sign
----

This subcommand signs information about future signing and denomination keys.

It consumes the output of the ``download`` subcommand, either from ``stdin`` or
directly.

It outputs the signatures over *all* denomination and signing keys
present in the input, in a format suitable for the ``upload`` subcommand.


revoke-denomination
-------------------

This subcommand signs a revocation message for a denomination key.

The hash of the denomination public key must be given in the usual
base32-encoding as the first and only argument to the subcommand.

It outputs the signature affirming the revocation of the denomination key,
in a format suitable for the ``upload`` subcommand.


revoke-signkey
--------------

This subcommand signs a revocation message for an exchange online signing key.

The online signing public key must be given in the usual
base32-encoding as the first and only argument to the subcommand.

It outputs the signature affirming the revocation of the online signing key,
in a format suitable for the ``upload`` subcommand.



enable-auditor
--------------

This subcommand
informs an exchange that an auditor is to be activated. Afterwards, the
exchange will accept inputs from that auditor's **taler-auditor-offline**
tool.  Note that the auditor also must add the exchange to the list of
exchanges that it audits via **taler-auditor-exchange**. Furthermore, the
exchange's database will need to be provided to the auditor.  This subcommand
only informs the exchange about the auditor, but does not perform those
additional mandatory steps for a working auditor.

The auditor's public key must be given in the usual base32-encoding as the
first argument.

The auditor's REST API base URL must be given as the second argument. The tool
performs a minimal sanity check, namely that the URL begins with "http"
(this also allows "https"), but as it runs offline does not perform any further
validation!

The third argument must be a human-readable name for the auditor. This may
be shown to users and should identify the auditor's business entity.  If
the name includes spaces, the argument should be quoted.

The subcommand takes no inputs from ``stdin`` or other subcommands.

It outputs the signature affirming the addition of the auditor,
in a format suitable for the ``upload`` subcommand.


disable-auditor
---------------

This subcommand
informs an exchange that an auditor is to be deactivated. Afterwards, the
exchange will refuse inputs from that auditor's **taler-auditor-offline**
tool.

The auditor's public key must be given in the usual base32-encoding as the
first argument.

The subcommand takes no inputs from ``stdin`` or other subcommands.

It outputs the signature affirming the removal of the auditor,
in a format suitable for the ``upload`` subcommand.


enable-account
--------------

This subcommand
informs an exchange that it should advertise a bank account as belonging to
the exchange on its ``/wire`` endpoint.  Note that this does *not* ensure that
the exchange will use this bank account for incoming or outgoing wire
transfers! For this, the **taler-exchange-transfer** and
**taler-exchange-wirewatch** tools must be configured.  Furthermore, the bank
account information advertised could theoretically differ from that which
these tool actually use, for example if the public bank account is only a
front for the actual internal business acounts.

The ``payto://`` URI (RFC 8905) of the exchange's bank account must be given
as the first argument to the subcommand.

The subcommand takes no inputs from ``stdin`` or other subcommands.

It outputs the signature affirming the addition of the wire account,
in a format suitable for the ``upload`` subcommand.


disable-account
---------------

This subcommand
informs an exchange that it should stop advertising a bank account as
belonging to the exchange on its ``/wire`` endpoint.

The ``payto://`` URI (RFC 8905) of the exchange's (former) bank account must be
given as the first argument to the subcommand.

The subcommand takes no inputs from ``stdin`` or other subcommands.

It outputs the signature affirming the deletion of the wire account, in a
format suitable for the ``upload`` subcommand.


wire-fee
--------

This subcommand informs an exchange about the desired wire fee (and closing fee)
structure for particular wire method and a calendar year (!).  The tool does not
permit changing wire fees during a calendar year. Also, once the wire fee has been
set for a calendar year, it cannot be changed.

The subcommand takes the year, wire-method (see RFC 8905, examples include
``x-taler-bank`` or ``iban``), wire fee and closing fee as arguments.
Instead of a year, the string ``now`` can be given for the current year
(this is mostly useful for test cases).  The wire-method should follow the
GANA registry as given in RFC 8905.  The fees must be given in the usual
Taler format of ``CURRENCY:NUMBER.FRACTION``.

The subcommand takes no inputs from ``stdin`` or other subcommands.

It outputs the signature affirming the wire fees, in a format suitable for the
``upload`` subcommand.


upload
------

This subcommand uploads outputs from other subcommands (except ``download`` and ``show``)
to the exchange.  Note that it is possible that some uploads succeed, while others
fail, as the operation is not atomic.

The subcommand takes no arguments and has no output.


help
----

This subcommand shows a summary of all available subcommands with the
required arguments.



Examples
========

Download future public keys from an exchange (online)
-----------------------------------------------------

.. code-block:: console

   $ taler-exchange-offline download > keys.json

Show information about future public keys (offline or online)
-------------------------------------------------------------

.. code-block:: console

   $ taler-exchange-offline show < keys.json

Sign future public keys (offline)
---------------------------------

.. code-block:: console

   $ taler-exchange-offline sign < keys.json > sigs.json

Upload signatures about future public keys (online)
---------------------------------------------------

.. code-block:: console

   $ taler-exchange-offline upload < sigs.json

Download, sign and upload, all in one (online)
----------------------------------------------

Note that doing this is only recommended in non-production deployments.

.. code-block:: console

   $ taler-exchange-offline download sign upload


Create signature to enable bank account (offline)
-------------------------------------------------

.. code-block:: console

   $ taler-exchange-offline enable-account payto://iban/DE24242 > account.json

Upload bank account signature (online)
--------------------------------------

.. code-block:: console

   $ taler-exchange-offline upload < account.json


Combine signing keys and enabling bank account (offline)
--------------------------------------------------------

.. code-block:: console

   $ taler-exchange-offline sign enable-account payto://iban/DE24242 < keys.json > combo.json

Upload various signatures (online)
----------------------------------

.. code-block:: console

   $ taler-exchange-offline upload < combo.json

Create multiple revocation messages in one pass (offline)
---------------------------------------------------------

.. code-block:: console

   $ taler-exchange-offline revoke-denomination $DKH1 revoke-denomination $DKH2 > revoke.json
   $ taler-exchange-offline revoke-signkey $SK1 revoke-signkey $SK2 > revoke.json
   $ taler-exchange-offline revoke-signkey $SK revoke-denomkey $DKH > mix.json

The outputs ("revoke.json", "mix.json") must be uploaded using the ``upload``
subcommand to the exchange to actually revoke the keys.



Security considerations
=======================

The **taler-exchange-offline** tool assumes that it is run on a high-security
system with *monotonic time*. The time does not have to precisely match that
of the exchange, but it must be monotonic across tool invocations. The clock
of the offline system is used in the enable/disable signatures to communicate
an order of the events to the exchange.  This prevents someone from replaying
an older "enable" (or "disable") message after a more recent "disable" (or
"enable") message has been provided to the exchange.  Thus, there is no need
to keep the actual files exchanged with the offline tool secret.

The **taler-exchange-offline** tool tries to make sure that the online signing
keys of the the exchange are always created by the same two security modules.
The goal here is to prevent an attacker who compromised **taler-exchange-httpd**
but *not* the security modules from providing attacker-controlled keys to the
offline signing process.

For this, the **taler-exchange-offline** signing subcommand always
automatically learns the security module's public signing key and *trusts it
on first use* (TOFU), but stores it to disk (see the ``SECM_TOFU_FILE`` option
in the ``[exchange-offline]`` section of the configuration).  If the keys
change subsequently, the tool will refuse to sign.



See Also
========

taler-exchange-httpd(1), taler-auditor-offline(1), taler-auditor-exchange(1), taler.conf(5).

Bugs
====

Report bugs by using https://bugs.taler.net/ or by sending electronic
mail to <taler@gnu.org>.