From 7247f9665a35c6d0241169059723869b0807d94f Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 4 Feb 2024 10:44:47 +0100 Subject: fix section 7.6 --- taler-exchange-manual.rst | 404 ++++------------------------------------------ 1 file changed, 35 insertions(+), 369 deletions(-) (limited to 'taler-exchange-manual.rst') diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index ec209f76..79455fec 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1,7 +1,7 @@ .. This file is part of GNU TALER. - Copyright (C) 2014-2023 Taler Systems SA + Copyright (C) 2014-2024 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software @@ -822,369 +822,32 @@ configuration of the online machine: Wire Gateway Setup ================== -The Taler Wire Gateway is an API that connects the Taler exchange to -the underlying core banking system. +The :ref:`Taler Wire Gateway ` is an API that +connects the Taler exchange to the underlying core banking system. There are +several implementations of wire gateways: -LibEuFin is an implementation of the Wire Gateway API for the EBICS protocol. -This section will walk through (1) installing and configuring LibEuFin and -(2) connecting the Taler Exchange to LibEuFin. + * `Project deploymerization `_ implements a wire gateway on top of Bitcoin or Ethereum + * The :ref:`libeufin-bank ` provides a wire gateway interface on top of a regional currency bank + * The **taler-fakebank-run** command is an in-memory bank simulator with a wire gateway interface for testing +.. FIXME :ref:`libeufin-nexus ` is an implementation of the Wire Gateway API for the EBICS protocol. Add to list above once nexus implements the TWG directly! -Installation and Basic Configuration ------------------------------------- +Before continuing, you need to decide which wire gateway you want to use, +and install and configure it on your system. Afterwards, you need to +have two key pieces of information from that setup: -First, install the ``libeufin`` package. This can be done on the ``exchange-online`` -machine or a different one. + * The username and password to access the exchange's account in the system. + * The ``payto://`` URI of that account (see `RFC 8905 `_). -.. code-block:: shell-session - - [root@exchange-online]# apt-get install -y libeufin - -The main component of LibEuFin is called the Nexus. It implements a Web -service that provides a JSON abstraction layer to access bank accounts. - -The HTTP port and database connection string can be edited in the configuration: - -.. code-block:: ini - :caption: /etc/libeufin/nexus.env - - LIBEUFIN_NEXUS_PORT=5017 - LIBEUFIN_NEXUS_DB_CONNECTION=jdbc:sqlite:/var/lib/libeufin/nexus/nexus-db.sqlite3 - -After configuring the database, you can start the service. -The database is initialized automatically. - - -.. code-block:: shell-session - - [root@exchange-online]# systemctl enable libeufin-nexus - [root@exchange-online]# systemctl start libeufin-nexus - -You can now create a superuser account. The command to -create the superuser needs direct database access, thus -the configuration file is sourced first, and the relevant -environment variable is exported. - -.. code-block:: console - - [root@exchange-online]# source /etc/libeufin/nexus.env - [root@exchange-online]# export LIBEUFIN_NEXUS_DB_CONNECTION - [root@exchange-online]# NEXUS_ADMIN_PW=$(tr -dc A-Za-z0-9 ` -becomes offered by the Nexus. The purpose is to let a Taler exchange rely on -Nexus to manage its bank account. - -The base URL of the facade that can be used by the Taler exchange -as the Taler Wire Gateway base URL can be seen by listing the facades: - -.. code-block:: console - - [root@exchange-online]# libeufin-cli facades list - -Managing Permissions and Users -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This guide has so far assumed that a superuser is accessing the LibEuFin Nexus. -However, it is advisable that the Nexus is accessed with users that only have a -minimal set of permissions. - -The Nexus currently only has support for giving non-superusers access to Taler -wire gateway facades. - -To create a new user, use the ``users`` subcommand of the CLI: - -.. code-block:: console - - [root@exchange-online]# libeufin-cli users list - # [ ... shows available users ... ] - - [root@exchange-online]# libeufin-cli users create $USERNAME - # [ ... will prompt for password ... ] - -Permissions are managed with the ``permissions`` subcommand. -The following commands grant permissions to view the transaction history -and create payment initiations with a Taler wire gateway facade: - - -.. code-block:: console - - [root@exchange-online]# libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerwiregateway.history - - [root@exchange-online]# libeufin-cli permissions grant \ - user $USERNAME \ - facade $FACADENAME \ - facade.talerwiregateway.transfer - -.. - FIXME: The two commands above output an empty JSON object - when successful. Possibly, we should suppress that (just like - the other commands do). - -The list of all granted permissions can be reviewed: - -.. code-block:: console - - [root@exchange-online]# libeufin-cli permissions list - - -.. _Bank-account: +.. _exchange-bank-account-configuration: Exchange Bank Account Configuration ----------------------------------- An exchange must be configured with the right settings to access its bank -account via a Taler Wire Gateway. An exchange can be configured to use -multiple bank accounts by using multiple Wire Gateways. Typically only one -Wire Gateway is used. +account via a :ref:`Taler wire gateway `. An +exchange can be configured to use multiple bank accounts by using multiple +wire gateways. Typically only one wire gateway is used. To configure a bank account in Taler, we need to furnish two pieces of information: @@ -1195,8 +858,8 @@ information: an IBAN or ``payto://x-taler-bank/localhost:8080/2`` for the 2nd bank account a the Taler bank demonstrator running at ``localhost`` on port 8080. - The first part of the URI following ``payto://`` (“iban” or - “x-taler-bank”) is called the wire method. + The first part of the URI following ``payto://`` (``iban`` or + ``x-taler-bank``) is called the wire method. - The ``taler-exchange-wirewatch`` and ``taler-exchange-transfer`` tools needs to be provided resources for authentication @@ -1205,20 +868,22 @@ information: for HTTP basic authentication. -A Taler Wire Gateway is configured in a configuration section that follows the -pattern ``exchange-account-$id``, where ``$id`` is an internal identifier for -the bank account accessed by the exchange. The basic information for an +Each Taler wire gateway is configured in a configuration section that follows +the pattern ``exchange-account-$id``, where ``$id`` is an internal identifier +for the bank account accessed by the exchange. The basic information for an account should be put in ``/etc/taler/conf.d/exchange-business.conf``. The secret credentials to access the Taler Wire Gateway API should be put into a corresponding ``exchange-accountcredentials-$id`` section in ``/etc/taler/secrets/exchange-accountcredentials.conf``. The latter file -should already be only readable for the ``taler-exchange-wire`` user. Other -exchange processes should not have access to this information. +should be only readable for the ``taler-exchange-wire`` user. Only the +``taler-exchange-wirewatch`` and ``taler-exchange-transfer`` services should +run as the ``taler-exchange-wire`` user. Other exchange processes do not need +to have access to the account credentials. You can configure multiple accounts for an exchange by creating sections -starting with “exchange-account-” for the section name. You can ENABLE for -each account whether it should be used, and for what (incoming or outgoing -wire transfers): +starting with ``exchange-account-`` for the section name. You must specify +``ENABLE_``-settings for each account whether it should be used, and for what +(incoming or outgoing wire transfers): .. code-block:: ini :caption: /etc/taler/conf.d/exchange-business.conf @@ -1253,15 +918,15 @@ wire transfers): # LibEuFin expects basic auth. WIRE_GATEWAY_AUTH_METHOD = basic - # Username and password set in LibEuFin. + # Username and password to access the Taler wire gateway. USERNAME = ... PASSWORD = ... - # Base URL of the wire gateway set up with LibEuFin. + # Base URL of the Taler wire gateway. WIRE_GATEWAY_URL = ... -Such a Wire Gateway configuration can be tested with the following commands: +Such a wire gateway configuration can be tested with the following commands: .. code-block:: shell-session @@ -1270,7 +935,8 @@ Such a Wire Gateway configuration can be tested with the following commands: [root@exchange-online]# taler-exchange-wire-gateway-client \ --section exchange-accountcredentials-1 --credit-history - +On success, you will see some of your account's transaction history (or an +empty history), while on failure you should see an error message. .. _LegalSetup: @@ -1821,7 +1487,7 @@ The ``enable-account`` step is important to must be used to sign the correct address to wire funds to. Note that for each bank account, additional options **must** be set in the configuration file to tell the exchange how to access the bank account. The offline tool *only* configures the externally -visible portions of the setup. The chapter on `Bank account <_Bank-account>`_ configuration has further details. +visible portions of the setup. The chapter on `bank account configuration <_exchange-bank-account-configuration>`_ has further details. taler-exchange-offline accepts additional options to configure the use of the account. For example, additional options can be used to add currency -- cgit v1.2.3