taler-docs

bank-manual.rst (11644B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2014-2025 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
 
 In order to build and run LibEuFin, you must have GNU Make and the JDK 17
 installed and configured in your system. Note that the correct versions of
 Kotlin and Gradle will be installed automatically by the GNU Make script.
 
 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
 
   # THe public URL that the bank will be served under
   BASE_URL = https://bank.taler.net
   
   # Supported payment target type
   WIRE_TYPE = iban or x-taler-bank
   # If WIRE_TYPE = iban
   IBAN_PAYTO_BIC = SANDBOXX
 
 .. note::
   Refer to the manpage ``libeufin-man.conf(5)``
   for the full array of configuration values.
 
 Configuring password storage
 ----------------------------
 
 libeufin-bank uses secure password hashing algorithms to store user passwords. For the moment, only ``bcrypt`` is supported. The default configuration is:
 
 .. code-block:: ini
 
   [libeufin-bank]
   PWD_HASH_ALGORITHM = bcrypt
   PWD_HASH_CONFIG = { "cost": 8 }
 
 As password authentication is used frequently, password hashing should only take a few milliseconds. If your server's CPU is too weak, you should reduce the ``cost`` and you may want to increase it otherwise. You can measure the password hashing speed using the following command:
 
 .. code-block:: console
 
   $ libeufin-bank bench-pwh -c "$CONFIG_FILE"
 
 .. _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 ``TELESIGN_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
 
   $ TELESIGN_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 = "TELESIGN_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.