taler-docs

bank-manual.rst (13366B)

---

 ..
   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 3.0, 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.
 
 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.
 
 Authentication lockout and throttling
 ++++++++++++++++++++++++++++++++++++++
 
 Password authentication is used to obtain access tokens; normal Core Bank API
 operations use those tokens.  A wrong password by itself does not lock an
 account, because usernames are public and that policy would let an attacker
 lock out another user.  Deployments must rate-limit the token-creation endpoint
 at the ingress layer to bound password-hashing work.
 
 For an account protected by multi-factor authentication, repeated failed
 confirmation of token-creation challenges can lock creation of new tokens.
 Existing tokens remain usable.  An authenticated user with an existing token
 can recover by changing the password; otherwise an administrator must set a
 new password.  Clients can observe the account's ``locked`` status and the
 token endpoint reports ``TALER_EC_BANK_ACCOUNT_LOCKED``.
 
 The bank permits concurrent challenges for use on multiple devices, but caps
 the number of pending challenges per account as well as retransmissions and
 confirmation attempts.  Challenge hints must not expose a complete email
 address or telephone number.  Operators must still throttle challenge
 creation and delivery at the ingress layer to protect external SMS and mail
 services.  The exact endpoint responses are specified by the
 :doc:`../core/api-corebank`.
 
 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 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 to 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, payto
   URI and complete existing and future transaction history become public.
   Transaction disclosure includes wire subjects and both parties' payto URIs;
   it is not redacted.  Changing an account from private to public immediately
   exposes its old history as well.  Accounts that were already public before
   this Core Bank API v12 correction are automatically subject to the same
   disclosure, so operators should review them before upgrading.
 
 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/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/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 exchange for the currency.