path: root/libeufin/bank-manual.rst

..
  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.