commit 7b4d3fd5e33197b747e5a9bff15834da8c2a8325
parent 18498990d806cdff2e3d0cd9a627bd913c1f0c25
Author: MS <ms@taler.net>
Date: Wed, 1 Nov 2023 11:22:14 +0100
libeufin section
addressing feedbacks from the last meeting
Diffstat:
4 files changed, 135 insertions(+), 263 deletions(-)
diff --git a/libeufin/ebics3-test-tutorial.rst b/libeufin/ebics3-test-tutorial.rst
@@ -1,217 +0,0 @@
-EBICS 3.0 with PostFinance
-##########################
-
-This tutorial shows how LibEuFin and the PostFinance test platform
-communicate via EBICS 3. LibEuFin acts as the client via the Nexus
-component. To hide the configuration details to the user, all the
-client activity is handled by a Docker image.
-
-The main EBICS 3 operations that the client is expected to complete
-are the following:
-
-* Key exchange: the customer sends their keys to the bank, and then downloads the bank keys.
-* Uploading a payment instruction: the customer sends a payment to another fictional IBAN.
-* Downloading banking records: the customer downloads the banking records that confirm the previous outgoing payment.
-
-Setting up the test platform at PostFinance
--------------------------------------------
-
-Because the test is based on the PostFinance test platform, the first
-requirement is to create one account `there <https://isotest.postfinance.ch>`_.
-It is advised to set the language as English, as this tutorial is meant
-for the international audience.
-
-Set the language in the drop-down menu and navigate to the registration
-section as it is shown below:
-
-.. image:: set-english-and-register.png
-
-Even if the above page doesn't welcome you in English, the two boxes in the
-screenshot will still hold their position, so please look for box #1 to
-set the language and for box #2 to get the page that offers to register.
-
-After a successful registration, an IBAN needs to be associated with
-the user just created. Likely after the first login, the following
-page should appear. Click then on box #2.
-
-.. note::
-
- The navigation bar in the screenshot below is ubiquitous,
- so click on box #1 if the depicted page did not show up automatically.
-
-.. image:: no-accounts.png
-
-If the following page appears, please obtain a checksum-valid but fictitious
-Swiss IBAN and enter it as indicated by box #1 and then save it (box #2).
-
-.. _my-iban:
-
-.. image:: set-IBAN.png
-
-If the bank responds with a successful message, the next step is to enable
-EBICS 3 and set the format of the ISO20022 documents.
-
-.. note::
-
- There is no "use EBICS 3" setting since EBICS 3 is a "side effect"
- of choosing one particular ISO format for banking records.
-
-To use EBICS 3, click the navigation bar item highlighted in the
-following screenshot.
-
-.. image:: set-ISO-2019-0.png
-
-The following page should appear, where the ISO format can be specified
-as it is depicted in the following screenshot.
-
-.. image:: set-ISO-2019-1.png
-
-After having saved the setting, proceed now to set the flavor
-of payment confirmations. This setting instructs the bank to define
-particular XML nodes when it releases the payment confirmations. Even
-if each document is ISO20022, this step is essential because ISO20022
-has many optional fields and client and bank must agree on which fields
-appear in the documents.
-
-Hover on box #1 and then click on box #2.
-
-.. image:: camt.054-style-0.png
-
-If the following page appears, please set everything as it is shown below:
-
-.. FIXME: now trying by NOT selecting the incoming confirmation.
- Change it here if that works (screenshot taken already)!
-
-.. image:: camt.054-style-1.png
-
-.. _get-ebics-ids:
-
-The last step is to retrieve the user's EBICS identifiers, namely the
-EBICS user and partner IDs. Hover on box #1 and then click on box #2.
-
-.. image:: get-EBICS-IDs-0.png
-
-At the first access, the following page should appear. Simply create
-EBICS access and continue to the next step.
-
-.. image:: enable-EBICS.png
-
-After having obtained the following page, finally the EBICS identifiers
-are shown in box #1. The test runner needs them. **Note**: the terms
-'customer' and 'partner' are used as **synonyms** in this tutorial (and
-in the EBICS specifications too).
-
-.. image:: get-EBICS-IDs-1.png
-
-Interestingly, box #2 contains the bank keys fingerprints. These are
-important to check that the client, along the keying process, has obtained
-the right bank keys. The test runner will pause the execution to let
-the user check them.
-
-Setting up the local Docker and run the test
---------------------------------------------
-
-This section shows how to run the test and explains how to interact
-with the test runner.
-
-Clone the following repository:
-
-.. code-block:: shell-session
-
- git://git.taler.net/deployment
-
-navigate in the following directory
-
-.. code-block:: shell-session
-
- deployment/nlnet/task3
-
-and build the Docker image with the following command:
-
-.. code-block:: shell-session
-
- docker build -t pofi .
-
-If the previous steps succeeded, the *pofi* image is ready to be run.
-
-The test runner needs the following three values: EBICS user ID, EBICS
-partner ID and IBAN. The `previous section <get-ebics-ids_>`_ explains how
-to get the EBICS IDs. The IBAN is the one entered `here <my-iban_>`_.
-
-.. code-block:: shell-session
-
- docker run -it pofi $EBICS_USER_ID $EBICS_PARTNER_ID $MY_IBAN
-
-Right after the start, the test runner needs the user intervention to
-confirm the user keys at the bank side. For this reason, it will pause
-the execution until the user is done. The following screenshot shows
-how to navigate to the page where the user has to intervene:
-
-.. image:: get-EBICS-IDs-0.png
-
-Once obtaining the page below, box #1 resets potential previous uploaded
-keys (only required when running the test more than once), and box #2 confirms
-the newly uploaded keys. Note: in production cases, such confirmation happens
-via the traditional paper mail.
-
-.. image:: set-EBICS-keys.png
-
-After having confirmed the new keys, the execution can be resumed to
-for the uploading and downloading operations.
-
-Upload
-======
-
-After the key exchange, the test runner continues by uploading one
-payment instruction. The payment instruction is a ``pain.001`` document
-that complies with the ISO20022 specification, and EBICS is responsible
-to transport the pain.001 from the client to the bank.
-
-The payment instruction causes one outgoing payment from the user
-test platform account to another fictional IBAN and has a random subject.
-A chance to specify a custom subject is also offered by the test runner.
-
-After the upload to the bank, the execution pauses to let the user
-check whether the test platform has received the payment instruction.
-
-To this purpose, click on the following navigation item:
-
-.. image:: check-payment-subject-0.png
-
-the opened page should contain the following view:
-
-.. image:: check-payment-subject-1.png
-
-in this case, open the (archive) file whose timestamp corresponds to the
-test execution and look for one XML file whose name contains "pain.001"
-(likely, this XML file is named after the archive's name). If found,
-the pain.001 file is expected to contain one node called ``Ustrd``: that
-is the payment subject and must match the one that was specified right
-before the upload. If they match, the upload succeeded and the execution
-can be resumed for the `Download`_ operation.
-
-Download
-========
-
-The download tries to get one ``camt.054`` (as well
-ISO20022) document from the bank; this document is expected to account
-for the previous outgoing payment that was created via the pain.001. As
-in the pain.001 case, EBICS is responsible to transport the camt.054 from
-the bank to the client.
-
-The download operation logs its activity to the screen, and if the execution
-is correct, the payment subject that was initially specified in the pain.001
-document must appear.
-
-Please, look for the following line:
-
-.. code-block:: shell-session
-
- $TIME [main] DEBUG tech.libeufin.nexus - Camt NOTIFICATION '$MSG_ID' has new payments:
- - $PAYMENT_SUBJECT
-
-.. note::
- Replace $TIME, $PAYMENT_SUBJECT and $MSG_ID with the particular case.
-
-If $PAYMENT_SUBJECT equals the initial payment subject from the pain.001,
-then the download operation succeeded.
diff --git a/libeufin/index.rst b/libeufin/index.rst
@@ -7,12 +7,5 @@ LibEuFin is a project providing free software tooling for European FinTech.
:maxdepth: 1
:glob:
- ebics
- sepa
- iso20022
- banking-protocols
- frontend
nexus-manual
- ebics3-test-tutorial
- performance
- transaction-identification
+ setup-ebics-at-postfinance
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
@@ -1,7 +1,7 @@
.. target audience: operator, developer
-LibEuFin Manual
-###############
+Nexus Manual
+############
.. contents:: Table of Contents
@@ -11,8 +11,34 @@ Future versions will offer a Web API to allow Taler Exchanges to talk to their
banks.
In this manual, we explain how to setup an EBICS subscriber. We assume that
-the bank had already granted EBICS access to the subscriber. The installation
-is described at `Installing Nexus`_.
+the bank had already granted EBICS access to the subscriber.
+
+Installing Nexus
+================
+
+The following section was tested on an *OpenJDK 17* environment.
+
+Building from source
+--------------------
+
+Nexus 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-nexus
+
+If the previous steps succeeded, the ``libeufin-nexus`` command should
+be found in the $PATH.
Setting up the EBICS subscriber
===============================
@@ -22,17 +48,25 @@ The following snippet shows the mandatory configuration values.
.. code-block:: console
[nexus-ebics]
- CURRENCY = EUR
+ 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_DATA_HOME}/bank-keys.json
+ CLIENT_PRIVATE_KEYS_FILE = ${LIBEUFIN_DATA_HOME}/subscriber-keys.json
+
+ # Account information
IBAN = myiban
BIC = mybic
NAME = myname
- BANK_PUBLIC_KEYS_FILE = enc-auth-keys.json
- CLIENT_PRIVATE_KEYS_FILE = private-keys-again.json
- BANK_DIALECT = postfinance
Assuming that the configuration file exists at ``$config_file``, the following
command would start the EBICS setup process. The files CLIENT_PRIVATE_KEYS_FILE
@@ -44,7 +78,7 @@ setup ('$HOME' is currently not supported along paths).
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_AUTHENTICATION_FAILED`` error code. That happens because
+**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.
@@ -59,32 +93,4 @@ order to download the bank keys and let the user accept them.
libeufin-nexus ebics-setup -c $config_file
-The setup is considered finished once both party have accepted the counterpart keys.
-
-Installing Nexus
-================
-
-The following section was tested on an *OpenJDK 17* environment.
-
-Building from source
---------------------
-
-Nexus 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-nexus
-
-If the previous steps succeeded, the ``libeufin-nexus`` command should
-be found in the $PATH.
-
+The setup is considered finished once the user accepts the bank keys.
diff --git a/libeufin/setup-ebics-at-postfinance.rst b/libeufin/setup-ebics-at-postfinance.rst
@@ -0,0 +1,90 @@
+Setup EBICS at PostFinance test platform
+########################################
+
+In this tutorial, we will set up one EBICS 3 account at the PostFinance
+test platform, in order to test the ``postfinance`` dialect from ``libeufin-nexus``.
+
+The first requirement is to create one account `there <https://isotest.postfinance.ch>`_.
+It is advised to set the language as English, as this tutorial is meant
+for the international audience.
+
+Set the language in the drop-down menu and navigate to the registration
+section as it is shown below:
+
+.. image:: set-english-and-register.png
+
+Even if the above page doesn't welcome you in English, the two boxes in the
+screenshot will still hold their position, so please look for box #1 to
+set the language and for box #2 to get the page that offers to register.
+
+After a successful registration, an IBAN needs to be associated with
+the user just created. Likely after the first login, the following
+page should appear. Click then on box #2.
+
+.. note::
+
+ The navigation bar in the screenshot below is ubiquitous,
+ so click on box #1 if the depicted page did not show up automatically.
+
+.. image:: no-accounts.png
+
+If the following page appears, please obtain a checksum-valid but fictitious
+Swiss IBAN and enter it as indicated by box #1 and then save it (box #2).
+
+.. _my-iban:
+
+.. image:: set-IBAN.png
+
+If the bank responds with a successful message, the next step is to enable
+EBICS 3 and set the format of the ISO20022 documents.
+
+.. note::
+
+ There is no "use EBICS 3" setting since EBICS 3 is a "side effect"
+ of choosing one particular ISO format for banking records.
+
+To use EBICS 3, click the navigation bar item highlighted in the
+following screenshot.
+
+.. image:: set-ISO-2019-0.png
+
+The following page should appear, where the ISO format can be specified
+as it is depicted in the following screenshot.
+
+.. image:: set-ISO-2019-1.png
+
+After having saved the setting, proceed now to set the flavor
+of payment confirmations. This setting instructs the bank to define
+particular XML nodes when it releases the payment confirmations. Even
+if each document is ISO20022, this step is essential because ISO20022
+has many optional fields and client and bank must agree on which fields
+appear in the documents.
+
+Hover on box #1 and then click on box #2.
+
+.. image:: camt.054-style-0.png
+
+If the following page appears, please set everything as it is shown below:
+
+.. image:: camt.054-style-1.png
+
+.. _get-ebics-ids:
+
+The last step is to retrieve the user's EBICS identifiers, namely the
+EBICS user and partner IDs. Hover on box #1 and then click on box #2.
+
+.. image:: get-EBICS-IDs-0.png
+
+At the first access, the following page should appear. Simply create
+EBICS access and continue to the next step.
+
+.. image:: enable-EBICS.png
+
+After having obtained the following page, finally the EBICS identifiers
+are shown in box #1.
+
+.. image:: get-EBICS-IDs-1.png
+
+Finally, box #2 contains the bank keys fingerprints. These are
+important to check that the client, along the keying process, has obtained
+the right bank keys.
