diff options
Diffstat (limited to 'libeufin/bank-manual.rst')
| -rw-r--r-- | libeufin/bank-manual.rst | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst new file mode 100644 index 00000000..ab793b2b --- /dev/null +++ b/libeufin/bank-manual.rst @@ -0,0 +1,307 @@ +.. + This file is part of GNU TALER. + 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 + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Florian Dold + @author Marcello Stanisci + @author Christian Grothoff + +.. target audience: operator, developer + +.. _libeufin-bank: + +Bank Setup Manual +################# + +libeufin-bank implements a simple core banking system with +account and REST APIs, including REST APIs for a Web interface +and REST APIs to interact with GNU Taler components. + +In this manual, we explain how to setup a bank. + +.. contents:: Table of Contents + :local: + + +Installing LibEuFin Bank +======================== + +The following section was tested on an *OpenJDK 17* environment. + +Installing the libeufin-bank binary packages on Debian +------------------------------------------------------ + +.. include:: ../frags/installing-debian.rst + +.. include:: ../frags/apt-install-libeufin-bank.rst + + +Installing the libeufin-bank binary packages on Ubuntu +------------------------------------------------------ + +.. include:: ../frags/installing-ubuntu.rst + +.. include:: ../frags/apt-install-libeufin-bank.rst + + +Building from source +-------------------- + +Bank belongs to the LibEuFin project, and can be downloaded via Git: + +.. code-block:: console + + $ git clone git://git.taler.net/libeufin + +Note that Kotlin and Gradle should already work on the host system. + +Navigate into the *libeufin* local repository, and from top-level run: + +.. code-block:: console + + $ ./bootstrap + $ ./configure --prefix=$PREFIX + $ make install + +If the previous steps succeeded, the ``libeufin-bank`` command should +be found in the $PATH. + + +Minimal Configuration for LibEuFin Bank +======================================= + +The following snippet shows the mandatory configuration values: + +.. code-block:: ini + + [libeufin-bank] + CURRENCY = KUDOS + + # Supported payment target type + WIRE_TYPE = iban or x-taler-bank + # If WIRE_TYPE = iban + IBAN_PAYTO_BIC = SANDBOXX + # If WIRE_TYPE = x-taler-bank + X_TALER_BANK_PAYTO_HOSTNAME = https://bank.taler.net + +.. note:: + Refer to the manpage ``libeufin-man.conf(5)`` + for the full array of configuration values. + +.. _libeufin-mfa: + +Configuring multi-factor authentication +--------------------------------------- + +libeufin-bank supports two-factor authentication. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. We provide two default helper scripts: ``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send SMS. To enable two-factor authentication you need to configure at least one TAN channel. + +SMS TAN channel ++++++++++++++++ + +The default ``libeufin-tan-sms.sh`` script is based on the `Telesign <https://www.telesign.com>`_ SMS provider. It requires an additional ``AUTH_TOKEN`` environment variable for `Telesign Basic authentication <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_. + +To test your setup run: + +.. code-block:: console + + $ AUTH_TOKEN=$TELESIGN_TOKEN + $ echo "Test 1234" | libeufin-tan-sms.sh $PHONE + +If you received an SMS containing "Test 1234" you can enable this channel in the config: + +.. code-block:: ini + + [libeufin-bank] + TAN_SMS = libeufin-tan-sms.sh + TAN_SMS_ENV = "AUTH_TOKEN=$TELESIGN_TOKEN" + +Mail TAN channel +++++++++++++++++ + +The default ``libeufin-tan-email.sh`` script is based on the ``mail`` Linux command. It requires a working local mail transfer agent. + +To test your setup run: + +.. code-block:: console + + $ echo "Test 1234" | libeufin-tan-email.sh $EMAIL + +If you received an email containing "Test 1234" you can enable this channel in the config: + +.. code-block:: ini + + [libeufin-bank] + TAN_EMAIL = libeufin-tan-email.sh + +Custom TAN channel scripts +++++++++++++++++++++++++++ + +It is possible to replace these scripts with use custom scripts to send +the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the ``$1`` parameter and the message content to be transmitted in their standard input. They should return 0 to indicate successful transmission of the challenge and non-zero on failure. + +To change the scripts used for multi-factor authentication, change the following +options in the configuration file: + +.. code-block:: ini + + [libeufin-bank] + TAN_SMS = custom-tan-sms.sh + TAN_SMS_ENV = + TAN_EMAIL = custom-tan-email.sh + TAN_EMAIL_ENV = + +Launching libeufin-bank +======================= + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command initializes (or upgrades) the database schema: + +.. code-block:: console + + $ libeufin-bank-dbinit -c "$CONFIG_FILE" + +Once this is done, you can start the libeufin-bank HTTP server: + +.. code-block:: console + + $ libeufin-bank serve -c "$CONFIG_FILE" + + + +Using the bank Web interface +============================ + +To be able to use the Web interface, you must set a password for the "admin" +account. You can set (or reset) the account password to ``$PASSWORD`` using +the following command: + +.. code-block:: console + + $ libeufin-bank passwd -c "$CONFIG_FILE admin "$PASSWORD" + +You can also use the same command to reset the passwords of other accounts by +replacing "admin" with the respective login. + + +Setting up accounts +------------------- + +Using the above "$PASSWORD", log into the Web interface as "admin". To setup +regular accounts, search for the button "Create account" near the list of all +existing bank accounts in the Web interface of libeufin-bank. + +You will be asked to specify: + +Username + A unique account name the user will use to access the bank account. + +Name + Legal name of the user or business owning the account. + +Email + E-mail address of the account owner. Can be used to send a TAN message for 2-factor authentication (if enabled). + +Phone + Mobile phone number of the account owner. Can be used to send a TAN message for 2-factor authentication (if enabled). + +Max debt + Maximum amount the account is allowed to go into debt. Non-zero settings **must** be used for the "admin" account where this setting effectively creates a limit on the amount of money managed by the bank. + +Is this a Taler Exchange? + Should be disabled except if you are setting up an account for a GNU Taler exchange. If enabled, transactions that are not compatible with a GNU Taler exchange will be automatically refused by the bank. + +XXX Cashout channel + Used in a regional currency setup to specify the external account number of a bank account in fiat currency that belongs the merchant. Allows the merchant to exchange its regional currency money for wire transfers in fiat currency into this account. Optional. Not available unless the bank is configured for regional currencies. + +Is this account public? + Public accounts can be viewed without access control, their balance and transaction history becomes public. + +After submitting the form, a randomly created password for the new account +will be shown in a notification. The administrator can also change passwords +for any account in the system using the "change password" link in the account +list. To change other details about an account, select the "Username" in the +account list. + + +Account introspection +--------------------- + +Users can see (and possibly change) the settings of their bank account and +also their IBAN by clicking on the "Welcome, $USERNAME" text after logging +into their bank account using their username and password. + +The IBAN field has a convenient "copy to clipboard" button next to it. + + +Making transfers between accounts +--------------------------------- + +First, you need to know the IBAN of the account to credit, and log in as the +user of the account to be debited. Then select "Using a form", enter the IBAN +under "Recipient" and specify a wire transfer subject and the total amount to +be wired. After pressing "Send", you may have to pass a 2-FA check. + + +Integration with the Taler Exchange +=================================== + +.. note:: + + This step is fully automated if you use the :doc:`automated setup manual<regional-automated-manual>`. + +You must have an exchange account with username ``exchange`` for conversion to work. +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command would create one: + +.. code-block:: console + + $ libeufin-bank create-account '{"username":"exchange","password":"$EXCHANGE_PASSWORD","name":"Cashout Exchange","is_taler_exchange":true}' -c "$CONFIG_FILE" + +.. note:: + + You can also set up the exchange account as "admin" using the Web interface of libeufin-bank. + +Having done so, take note of two key pieces of information, namely the ``$EXCHANGE_PASSWORD`` and the "payto://"-URI of the exchange bank account. This information must then be used to configure the exchange as described in +:ref:`exchange bank account configuration <exchange-account-signing>`. When using the libeufin-bank in the context +of a regional currency with conversion, you must +additionally specify a "conversion-url" when setting +up the exchange account. See the section on :ref:`conversion setup <regional-conversion-setup>` in the regional currency setup chapter for details. + + +Withdrawing e-cash to a Taler wallet +==================================== + +.. note:: + + This step is fully automated if you use the :doc:`automated setup manual<regional-automated-manual>`. + +Users can withdraw digital cash from their bank account starting from their +online banking as implemented by the libeufin-bank. However, in this scenario, +the Taler wallet may not already know about an exchange that works with the +respective currency. Thus, the protocol includes the possibility of the bank +*recommending* an exchange service to the wallet, thus providing a sane +default for the wallet to suggest to the user. To do so, the base URL of the +exchange API must be specified in the libeufin-bank configuration: + +.. code-block:: ini + + [libeufin-bank] + DEFAULT_EXCHANGE=${PROTO}://exchange.${DOMAIN_NAME} + +After changing this value, the libeufin-bank service needs to be restarted +to make the change effective. + +.. note:: + + The user may change the default exchange from within the wallet, assuming they know of an alternative exchanges for the currency. |