diff options
Diffstat (limited to 'manpages/taler-exchange-offline.1.rst')
| -rw-r--r-- | manpages/taler-exchange-offline.1.rst | 124 |
1 files changed, 109 insertions, 15 deletions
diff --git a/manpages/taler-exchange-offline.1.rst b/manpages/taler-exchange-offline.1.rst index 21d0275b..bd8cd793 100644 --- a/manpages/taler-exchange-offline.1.rst +++ b/manpages/taler-exchange-offline.1.rst @@ -258,11 +258,10 @@ 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 +This subcommand informs an exchange that it should advertise a bank account as +belonging to the exchange on its ``/keys`` 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 @@ -271,18 +270,61 @@ front for the actual internal business accounts. The ``payto://`` URI (RFC 8905) of the exchange's bank account must be given as the first argument to the subcommand. +Afterwards, optional arguments can be given: + + * ``conversion-url`` $URL: specifies that using this bank account is subject + to currency conversion. $URL must be the address of a currency conversion + REST API that allows merchants and wallets to determine the current + conversion rate. + + * ``display-hint`` $PRIORITY $LABEL: specifies that this bank account should + be shown to the user with the given numeric $PRIORITY (higher is earlier) + and with the given $LABEL. This is useful to ensure that if an exchange + has multiple bank accounts, we can show the user those that are most likely + useful first, and give them appropriately labeled hints for selecting other + accounts as well. A display hint is optional, if missing the priority is 0 + and the wallet must pick some appropriate label itself somehow. + + * ``credit-restriction`` $TYPE [$ARGS]: Specifies that there are + restrictions in place when crediting this bank account. Details depend on + the restriction $TYPE. This argument may be given multiple times, in which + case debitor accounts must satisfy all restrictions. Restriction types are + discussed below. + + * ``debit-restriction`` $TYPE [$ARGS]: Specifies that there are restrictions + in place when receiving money from the exchange. Wallets and merchants + must check that their target bank account satisfies these restrictions + before sending deposit requests to the exchange. Details depend on the + restriction $TYPE. This argument may be given multiple times, in which + case debitor accounts must satisfy all restrictions. Restriction types are + discussed below. + +The following types of credit- and debit-restrictions are supported: + + * ``deny``: A $TYPE of ``deny`` means that this bank account cannot be used + for the given operation. ``deny`` takes no further arguments. + + * ``regex`` $EXPR $HINT $JSON: A $TYPE of ``regex`` means that the partner's + bank account ``payto``-URI representation must follow a certain regular + expression given in $EXPR where the syntax follows posix-egrep, but + without support for character classes, GNU extensions, back-references or + intervals. See + `Findutils Manual <https://www.gnu.org/software/findutils/manual/html_node/find_html/posix_002degrep-regular-expression-syntax.html>`_ + for a description of the posix-egrep syntax. The $HINT must be a + human-readable description of the $EXPR. $JSON should be a JSON array + mapping IETF BCP 47 language tags to localized versions of $HINT. + 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. +belonging to the exchange on its ``/keys`` endpoint. The ``payto://`` URI (RFC 8905) of the exchange's (former) bank account must be given as the first argument to the subcommand. @@ -456,25 +498,58 @@ Upload signatures about future public keys (online) Download, sign and upload, all in one (online) ---------------------------------------------- -Note that doing this is only recommended in non-production deployments. +Note that doing this is only recommended in non-production deployments, +as this requires putting the "offline" key onto a system that is actually +online! .. code-block:: console - $ taler-exchange-offline download sign upload + $ taler-exchange-offline \ + download \ + sign \ + upload Here is a variant that shows the output of ``download``, but does not consume it, so that ``sign`` can see it as input, as in the variant without ``show``. .. code-block:: console - $ taler-exchange-offline download show - sign upload + $ taler-exchange-offline \ + download \ + show - \ + sign \ + upload + Create signature to enable bank account (offline) ------------------------------------------------- +The following command sets up an unrestricted simple exchange bank account +without conversion: + .. code-block:: console - $ taler-exchange-offline enable-account payto://iban/DE24242 > account.json + $ taler-exchange-offline \ + enable-account payto://iban/DE24242?receiver-name=operator > account.json + +The following command would set up an exchange bank account with conversion +and restrict it to only receive money from Switzerland and deny its use for +debit operations: + +.. code-block:: shell-session + + $ taler-exchange-offline \ + enable-account payto://x-taler-bank/example.com/?receiver-name=name \ + conversion-url http://conversion.exchange.com/ \ + debit-restriction \ + deny \ + credit-restriction \ + regex \ + 'payto://iban/.*/CH.*?receiver-name=.*' \ + 'Swiss only' \ + '{ "de" : "nur Schweiz", \ + "fr" : "Suisse uniquement" }' + Upload bank account signature (online) -------------------------------------- @@ -487,9 +562,19 @@ Upload bank account signature (online) Combine signing keys and enabling bank account (offline) -------------------------------------------------------- +You can chain multiple commands into one invocation: + .. code-block:: console - $ taler-exchange-offline sign enable-account payto://iban/DE24242 < keys.json > combo.json + $ taler-exchange-offline \ + sign \ + enable-account \ + payto://iban/DE24242 < keys.json > combo.json + +Note that ``sign`` must be first as it consumes the ``keys.json`` +input. The resulting output combines the outputs of the ``sign`` +and ``enable-account`` subcommands. + Upload various signatures (online) ---------------------------------- @@ -501,11 +586,20 @@ Upload various signatures (online) Create multiple revocation messages in one pass (offline) --------------------------------------------------------- +You can freely combine almost all commands, including those for +key revocation: + .. 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 + $ 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. |