diff options
Diffstat (limited to 'frags')
| -rw-r--r-- | frags/apt-install-libeufin-bank.rst | 6 | ||||
| -rw-r--r-- | frags/apt-install-libeufin-nexus.rst | 6 | ||||
| -rw-r--r-- | frags/deploying-tos.rst | 45 | ||||
| -rw-r--r-- | frags/ebics-setup.rst | 63 | ||||
| -rw-r--r-- | frags/libeufin-config-cli.rst | 10 | ||||
| -rw-r--r-- | frags/nexus-ebics-setup.rst | 87 | ||||
| -rw-r--r-- | frags/regional-manual-architecture.rst | 48 | ||||
| -rw-r--r-- | frags/regional-manual-use.rst | 99 | ||||
| -rw-r--r-- | frags/regional-system-on.rst | 28 |
9 files changed, 327 insertions, 65 deletions
diff --git a/frags/apt-install-libeufin-bank.rst b/frags/apt-install-libeufin-bank.rst new file mode 100644 index 00000000..97b1bd71 --- /dev/null +++ b/frags/apt-install-libeufin-bank.rst @@ -0,0 +1,6 @@ + +To install libeufin-nexus, you can now simply run: + +.. code-block:: console + + # apt install libeufin-bank diff --git a/frags/apt-install-libeufin-nexus.rst b/frags/apt-install-libeufin-nexus.rst new file mode 100644 index 00000000..25ff8070 --- /dev/null +++ b/frags/apt-install-libeufin-nexus.rst @@ -0,0 +1,6 @@ + +To install libeufin-nexus, you can now simply run: + +.. code-block:: console + + # apt install libeufin-nexus diff --git a/frags/deploying-tos.rst b/frags/deploying-tos.rst new file mode 100644 index 00000000..5b389f44 --- /dev/null +++ b/frags/deploying-tos.rst @@ -0,0 +1,45 @@ +.. + 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/> + + +Configuring exchange terms +========================== + +You can use your own terms of service and privacy policy. You can use the default templates in ``/usr/share/taler/terms`` as a guide. +Assuming you have custom terms of service and privacy policy ``rst`` teamplte files at ``TOS_PATH`` and ``PRIVACY_PATH``, the following commands generate the terms files: + +.. code-block:: console + + # taler-terms-generator -i "$TOS_PATH" + # taler-terms-generator -i "$PRIVACY_PATH" + +You now have to specify the terms file names in the exchange config: + +.. code-block:: console + + # TERMS_ETAG="$(basename "$TOS_PATH" .rst)" + # PRIVACY_ETAG="$(basename "$PRIVACY_PATH" .rst)" + +.. code-block:: ini + + [exchange] + TERMS_ETAG=${TERMS_ETAG} + PRIVACY_ETAG=${PRIVACY_ETAG} + +Make sure to restart taler-exchange after changing these configuration options: + +.. code-block:: console + + # systemctl restart taler-exchange.target diff --git a/frags/ebics-setup.rst b/frags/ebics-setup.rst index c6ff5143..e69de29b 100644 --- a/frags/ebics-setup.rst +++ b/frags/ebics-setup.rst @@ -1,63 +0,0 @@ - -When you sign up for an EBICS-enabled bank account, the bank will provide you -with various credentials. Those must be provided in the -``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the -name of the *fiat* currency. - -The following snippet shows the mandatory configuration values: - -.. _core-config: - -.. code-block:: console - - [nexus-ebics] - CURRENCY = CHF - - # Bank - HOST_BASE_URL = http://bank.example.com/ - BANK_DIALECT = postfinance - - # EBICS IDs - HOST_ID = mybank - USER_ID = myuser - PARTNER_ID = myorg - - # Key files - BANK_PUBLIC_KEYS_FILE = ${LIBEUFIN_HOME}/bank-keys.json - CLIENT_PRIVATE_KEYS_FILE = ${LIBEUFIN_HOME}/subscriber-keys.json - - # Account information - IBAN = myiban - BIC = mybic - NAME = myname - -.. note:: - Refer to the manpage ``libeufin-nexus.conf(5)`` - for the full array of configuration values. - -Assuming that the configuration file exists at ``$config_file``, the following -command would start the EBICS setup process. The files CLIENT_PRIVATE_KEYS_FILE -and BANK_PUBLIC_KEYS_FILE would be created at the CWD. Adjust their path to your -setup ('$HOME' is currently not supported along paths). - -.. code-block:: console - - libeufin-nexus ebics-setup -c $config_file - -If the previous command succeeded, the subscriber keys reached the bank, but the setup -**should** fail with an ``EBICS_INVALID_USER_STATE`` error code. That happens because -the client tries to download the bank keys *before* having confirmed the subscriber keys -via the traditional post service. - -To that purpose, the previous run should have left a PDF document that the subscriber can -print, sign, and send to the bank to confirm their subscriber keys. Look for the message -looking like ``PDF file with keys hex encoding created at: /tmp/libeufin-nexus-keys-$timestamp.pdf``. - -Once the bank received and approved such printed document, run the same command again, in -order to download the bank keys and let the user accept them. - -.. code-block:: console - - libeufin-nexus ebics-setup -c $config_file - -The setup is considered finished once the user accepts the bank keys.
\ No newline at end of file diff --git a/frags/libeufin-config-cli.rst b/frags/libeufin-config-cli.rst index 0852c2aa..5475324e 100644 --- a/frags/libeufin-config-cli.rst +++ b/frags/libeufin-config-cli.rst @@ -19,6 +19,8 @@ It takes two arguments, the section name and the option name Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. **-f** \| **--filename** Interpret value as path with dollar-expansion. @@ -31,15 +33,19 @@ This command dump the configuration. Print short help on options. **-c** \| **--config** *FILENAME* Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. config pathsub -------------- This command substitute variables in a path. -It takes one argument, a path expresion. +It takes one argument, a path expression. **-h** \| **--help** Print short help on options. **-c** \| **--config** *FILENAME* - Specifies the configuration file.
\ No newline at end of file + Specifies the configuration file. +**-L** \| **--log** *LOGLEVEL* + Configure logging to use LOGLEVEL. diff --git a/frags/nexus-ebics-setup.rst b/frags/nexus-ebics-setup.rst new file mode 100644 index 00000000..76f51bfe --- /dev/null +++ b/frags/nexus-ebics-setup.rst @@ -0,0 +1,87 @@ + +When you sign up for an EBICS-enabled bank account, the bank will provide you +with various credentials. Those must be provided in the +``/etc/libeufin/libeufin-nexus.conf`` configuration file together with the +name of the *fiat* currency. + +.. note:: + As legacy transactions in that bank account would likely confuse the system, it is advisable to use a fresh bank account with an empty transaction history. + +The following snippet shows the mandatory configuration values: + +.. _core-config: + +.. code-block:: ini + + [nexus-ebics] + CURRENCY = CHF + + # Bank + HOST_BASE_URL = https://ebics.postfinance.ch/ebics/ebics.aspx + BANK_DIALECT = postfinance + + # EBICS IDs + HOST_ID = PFEBICS + USER_ID = PFC00563 + PARTNER_ID = PFC00563 + + # Account information + IBAN = CH7789144474425692816 + BIC = POFICHBEXXX + NAME = John Smith S.A. + +.. note:: + Refer to the manpage ``libeufin-nexus.conf(5)`` + for the full array of configuration values. + +.. warning:: + This combination of HOST_ID, USER_ID and PARTNER_ID must never be used by another instance of libeufin-nexus or by other EBICS clients, otherwise data will be lost. + +Reuse existing client keys +-------------------------- + +If you have client keys from a previous EBICS setup you can copy the JSON file to the configured path ``CLIENT_PRIVATE_KEYS_FILE`` (``/var/lib/libeufin-nexus/client-ebics-keys.json`` with the default config). + +Make sure this file is accessible to the user running ``libeufin-nexus``, for the default services you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/client-ebics-keys.json + +Create new client keys +---------------------- + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command should start the EBICS setup process: + +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +If the previous command failed when running EBICS INI with an error code of +``EBICS_INVALID_USER_OR_USER_STATE``, you need to confirm your keys to your bank to +activate your account. + +To that end, the previous run should have left a PDF document that you can +print, sign and send to the bank. Look for the message that looks like ``PDF +file with keys created at '/tmp/libeufin-nexus-keys-$TIMESTAMP.pdf'``. + +Once the bank has received and processed this document you can continue. + +Get bank keys +------------- + +Assuming that the configuration file exists at ``$CONFIG_FILE``, the following +command will finish the EBICS setup process: + +.. code-block:: console + + $ libeufin-nexus ebics-setup -c "$CONFIG_FILE" + +The EBICS setup is finished once the bank keys have been accepted. + +Make sure this bank keys are accessible to the user running ``libeufin-nexus``, for the default services you should run: + +.. code-block:: console + + $ chown libeufin-nexus:libeufin-nexus /var/lib/libeufin-nexus/bank-ebics-keys.json diff --git a/frags/regional-manual-architecture.rst b/frags/regional-manual-architecture.rst new file mode 100644 index 00000000..cfb8aacd --- /dev/null +++ b/frags/regional-manual-architecture.rst @@ -0,0 +1,48 @@ +Architecture +============ + +There are several key components needed to operate a regional currency based +on GNU Taler and LibEuFin technology: + +- LibEuFin Nexus: is responsible to drive the master (fiat) bank account both to learn + about incoming payments and to send fiat cash-out payments +- LibEuFin Bank: offers basic banking operations, e.g. wire transfers, Taler withdrawals, + account management, cash-out's +- Taler exchange: server side of Taler operations. +- Taler wallet: client side of Taler operations. +- Taler merchant backend: abstracts Taler details to the shops. + +.. image:: ../images/regional-arch.png + +In this model, the regional currency is backed by the fiat currency and users +are offered two operations: *cash-in* to create regional currency starting +from fiat money, and *cash-out* to convert regional currency into fiat +currency. + +The design assumes that one single unit of regional currency is always backed +by one single unit of fiat currency. + + +Cash-in ++++++++ + +One fundamental entity to create the regional currency is the *master bank account*. +The master bank account is hosted at one fiat bank and whenever it receives a *valid* +fiat payment of N units, it triggers the creation of N units of regional currency. +Such trigger causes the *admin bank account* at the regional bank to wire the N units of +regional currency to the Taler exchange (regional) bank account. At this point, the +Taler exchange is ready to issue the regional coins to the Taler wallet that proves +to own them. + +.. note:: + + *Valid* fiat payments are those with a Taler-relevant subject that should be generated by a Taler wallet. + + +Cash-out +++++++++ + +Once a regional bank user confirms a cash-out operation of N units, the system sends +a regional payment of N units to the *admin bank account*. This latter triggers then +a fiat payment of N units to the fiat bank account owned by the user who initiated the +cash-out.
\ No newline at end of file diff --git a/frags/regional-manual-use.rst b/frags/regional-manual-use.rst new file mode 100644 index 00000000..f33d9010 --- /dev/null +++ b/frags/regional-manual-use.rst @@ -0,0 +1,99 @@ +Using the Regional Currency +=========================== + +The very first step you should check afte the installation process has been +completed successfully, is to make sure all three URLs (bank,backend and exchange), +are available (this means to see a Website, and not any NGINX error). + + +Bank backend walkthrough ++++++++++++++++++++++++++ + +- As stated above, please visit before "https://bank.yourdomain.ltd", to make sure it is available. + +- Now login with the username "admin" and the password you have choosen during the installation process, or use the one which might + have been generated automatically (and shown on your terminal screen), during the installation process. + Once inside the Bank Administrator area, please create the "very first" customer account. + +- Transfer some funds from the "admin" bank account to this new customer account. + +- Now logout from the "admin" account, and login again using the recently "customer" account you have created, and make sure the funds you have transfered from admin, have arrived correctly. + +- Now, please choose the option "Send Money to a Taler Wallet", and try to send for example 100 units of your regional currency to the + wallet installed on your browser or mobile phone. + +- Now try to spend some of these funds from your wallet, and try to buy something somewhere, with the same digital currency you have choosen, during your installation process, let's say Netzbon. + +- Lastly, you can also try to transfer funds to another "bank account",for that you will need to know the recipient's username or the bank account ID. + +If you have successfully accomplished all the previous steps, for the bank administrator +backend and your installed Wallet, you can move now to test other components such +as the Merchant backend (https://backend.yourdomain.ltd). + +Wallet Setup +++++++++++++ + +This section describes the interaction between the Taler graphical wallet (Android, +iOS, WebExtensions) and the regional currency system. + +You need to add your regional currency exchange to the wallet. This can +be done by scanning a QR code with a ``taler://withdraw-exchange/exchange.$DOMAIN/$MASTER_PUB`` +URL or by manually entering the URL into the respective ``Add exchange`` +dialogue. + + +Cash-In ++++++++ + +Next, start the withdraw process in the Taler wallet for the respective +currency and specify the desired amount. The wallet will then show you the +details of the fiat wire transfer that must be made for the cash-in to be +completed. Once the money has arrived at the fiat bank account, Nexus will +obtain the transaction data and the regional currency bank will create the +corresponding amount in regional currency, crediting the GNU Taler exchange +account. In turn, the exchange will issue the respective amount to your +wallet. + +.. note:: + + Cash-in operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. + + +Making payments ++++++++++++++++ + +For testing, you should be able to *deposit* regional currency directly into +your regional currency libeufin-bank account directly from the Taler wallet. +For this, you primarily need to know your bank account details (which should +be accessible by clicking on your name in the bank Web site after logging in). + +.. note:: + + There may be a short delay between the wallet making the deposit and + the exchange crediting your bank account. This is because the wallet + uses a small wire transfer delay by default when initiating a deposit + into a bank account. + +For production, it is more common for a shop to configure a :ref:`Taler +merchant backend <taler-merchant-backend-operator-manual>` or at least use an +instance within such a setup. To configure an instance, you primarily need +again the bank account details to :ref:`setup instance bank accounts +<instance-bank-account>`. + + +Cash-Out +++++++++ + +Regional currency accounts that have a positive balance could be eligible for +cash-out. Cash-out operations may again be restricted by the regional +currency operator and will *only* be made to the respective pre-configured +fiat currency bank account. To cash-out, simply log into your regional +currency account, select cash-out, specify the desired amount and pass the +second-factor authorization challenge by entering the TAN you receive at the +registered e-mail address or mobile phone number. + +.. note:: + + Cash-out operations may be subject to conversion rates, conversion fees and + minimum amounts to be transferred. diff --git a/frags/regional-system-on.rst b/frags/regional-system-on.rst new file mode 100644 index 00000000..7a150cbf --- /dev/null +++ b/frags/regional-system-on.rst @@ -0,0 +1,28 @@ +.. + 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/> + + +System ON! +========== + +The last step is to enable libeufin-nexus to :ref:`import incoming bank +transactions <receive-transaction-data>` (cash in) and to :ref:`trigger +outgoing bank transactions <sending-payments>` (cash out). + +.. code-block:: console + + # systemctl enable --now libeufin-nexus.target + +.. FIXME: explain how to test if libeufin is working! |