diff options
Diffstat (limited to 'libeufin/bank-manual.rst')
| -rw-r--r-- | libeufin/bank-manual.rst | 237 |
1 files changed, 177 insertions, 60 deletions
diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst index af977492..ab793b2b 100644 --- a/libeufin/bank-manual.rst +++ b/libeufin/bank-manual.rst @@ -1,21 +1,60 @@ +.. + 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 ################# -.. contents:: Table of Contents - -LibEuFin Bank implements a simple core banking system with +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 -------------------- @@ -38,8 +77,9 @@ Navigate into the *libeufin* local repository, and from top-level run: If the previous steps succeeded, the ``libeufin-bank`` command should be found in the $PATH. -Setting up the LibEuFin Bank -============================ + +Minimal Configuration for LibEuFin Bank +======================================= The following snippet shows the mandatory configuration values: @@ -47,79 +87,119 @@ The following snippet shows the mandatory configuration values: [libeufin-bank] CURRENCY = KUDOS - - # Server - SERVE = tcp - PORT = 8080 - - [libeufin-bankdb-postgres] - CONFIG = postgresql:///libeufinbank + + # 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. -Assuming that the configuration file exists at ``$config_file``, the following -command would define the database schema and create an admin account. +.. _libeufin-mfa: -.. code-block:: console +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. - $ libeufin-bank dbinit -c $config_file +SMS TAN channel ++++++++++++++++ -If you wish to authenticate as admin, you must change the account password with the following command. +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 - $ libeufin-bank passwd -c $config_file admin $PASSWORD + $ AUTH_TOKEN=$TELESIGN_TOKEN + $ echo "Test 1234" | libeufin-tan-sms.sh $PHONE -Then you can start the HTTP server. +If you received an SMS containing "Test 1234" you can enable this channel in the config: -.. code-block:: console +.. code-block:: ini - $ libeufin-bank serve -c $config_file + [libeufin-bank] + TAN_SMS = libeufin-tan-sms.sh + TAN_SMS_ENV = "AUTH_TOKEN=$TELESIGN_TOKEN" +Mail TAN channel +++++++++++++++++ -Using custom e-mail / SMS TAN scripts -------------------------------------- +The default ``libeufin-tan-email.sh`` script is based on the ``mail`` Linux command. It requires a working local mail transfer agent. -The guided setup installs the TAN scripts found in ``libeufin/contrib/``: -``libeufin-tan-email.sh`` and ``libeufin-tan-sms.sh``, but should you want to -use custom scripts to send the e-mail or SMS TAN, set the configuration like -follows: +To test your setup run: -.. note:: +.. code-block:: console - The default SMS TAN script is based on the `Telesign <https://www.telesign.com>`_ provider. + $ 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" -The scripts TAN_SMS/EMAIL must accept the phone number / e-mail address as the -``$1`` parameter and the message content to be transmitted in their standard -input. -Using the Bank Web Interface +Using the bank Web interface ============================ -Before you can use the Web interface, you must set -a password for the "admin" account. You can do this -using: +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" + $ 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 +Setting up accounts ------------------- -Using the above "$PASSWORD", log into the Web interface as "admin". Then -search for the button "Create account" near the list of all existing bank -accounts in the Web interface of libeufin-bank. +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: @@ -147,27 +227,24 @@ XXX Cashout channel 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. +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 +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. +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. +The IBAN field has a convenient "copy to clipboard" button next to it. -Making Transfers between Accounts +Making transfers between accounts --------------------------------- First, you need to know the IBAN of the account to credit, and log in as the @@ -179,12 +256,52 @@ be wired. After pressing "Send", you may have to pass a 2-FA check. Integration with the Taler Exchange =================================== -Exchange Configuration ----------------------- +.. 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. -TODO. 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:: -TODO. + The user may change the default exchange from within the wallet, assuming they know of an alternative exchanges for the currency. |