[taler-docs] branch master updated: libeufin section

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 7b4d3fd5 libeufin section
7b4d3fd5 is described below

commit 7b4d3fd5e33197b747e5a9bff15834da8c2a8325
Author: MS <ms@taler.net>
AuthorDate: Wed Nov 1 11:22:14 2023 +0100

    libeufin section
    
    addressing feedbacks from the last meeting
---
 libeufin/ebics3-test-tutorial.rst       | 217 --------------------------------
 libeufin/index.rst                      |   9 +-
 libeufin/nexus-manual.rst               |  82 ++++++------
 libeufin/setup-ebics-at-postfinance.rst |  90 +++++++++++++
 4 files changed, 135 insertions(+), 263 deletions(-)

diff --git a/libeufin/ebics3-test-tutorial.rst 
b/libeufin/ebics3-test-tutorial.rst
deleted file mode 100644
index fba32a5b..00000000
--- a/libeufin/ebics3-test-tutorial.rst
+++ /dev/null
@@ -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
index 2f1ef49c..5e7fdf6d 100644
--- 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
index 3ea55ce1..1faf725d 100644
--- 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
new file mode 100644
index 00000000..161bc6d3
--- /dev/null
+++ 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.

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.