[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: ebics-setup config section.
|
From: |
gnunet |
|
Subject: |
[taler-docs] branch master updated: ebics-setup config section. |
|
Date: |
Thu, 02 Nov 2023 09:05:01 +0100 |
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 864d6252 ebics-setup config section.
864d6252 is described below
commit 864d62529a0146a41492a2a48881391622affd7e
Author: MS <ms@taler.net>
AuthorDate: Thu Nov 2 09:02:51 2023 +0100
ebics-setup config section.
Plus deleting documents not directly targeted at users.
---
libeufin/banking-protocols.rst | 127 -------
libeufin/ebics.rst | 598 --------------------------------
libeufin/frontend.rst | 47 ---
libeufin/iso20022.rst | 112 ------
libeufin/nexus-manual.rst | 4 +
libeufin/performance.rst | 114 ------
libeufin/sepa.rst | 26 --
libeufin/transaction-identification.rst | 87 -----
manpages/libeufin-nexus.conf.5.rst | 40 ++-
9 files changed, 37 insertions(+), 1118 deletions(-)
diff --git a/libeufin/banking-protocols.rst b/libeufin/banking-protocols.rst
deleted file mode 100644
index 2eaffb3d..00000000
--- a/libeufin/banking-protocols.rst
+++ /dev/null
@@ -1,127 +0,0 @@
-.. target audience: core developer
-
-Banking Protocols
-#################
-
-This page collects information we have about banking protocols available around
-the world.
-
-
-Open Financial Exchange (OFX) Direct Connect
-============================================
-
-`OFX <https://www.ofx.net/>`__ is widely used in the US. It defines a
completely
-custom protocol (based on HTTP) and data formats (**not** based on ISO20022)
for banking.
-
-
-Electronic Banking Internet Communication Standard (EBICS)
-==========================================================
-
-EBICS is used primarily in Germany, France and Switzerland. Some banks (such
as BNPParibas
-with their `Global Ebics
<https://cashmanagement.bnpparibas.com/our-solutions/solution/global-ebics>`__)
-also allow EBICS access to accounts in other countries.
-
-EBICS is just a transfer layer for communicating with banks. Banks define what
-messages they support. In practice, EBICS is very often used to transfer
-ISO20022 messages.
-
-German banks that are part of the German Banking Industry Committee all must
offer EBICS access.
-Thus this protocol is a good choice for the German market.
-
-
-FinTS / HBCI
-============
-
-German home-banking standard. FinTS is the successor of the Home Banking
-Computer Interface (HBCI), but older versions of FinTS are often still called
-HBCI.
-
-The current version, FinTS 4.0, is not widely supported by banks yet.
Starting with FinTS,
-XML is used as a data format. Previous versions used a custom text/binary
format.
-
-Only some banks allow authentication based on key pairs.
-Due to different interpretation of PSD2, other banks now only allow
authentication
-methods that require interaction from the customer (SCA / Strong Customer
Authentication).
-
-Payloads these days can be ISO20022 messages.
-
-Examples:
- * `GLS
<https://www.gls.de/geschaefts-firmenkunden/zahlungsverkehr/onlinebankingverfahren-und-programme/daten-zum-onlinebanking/>`__
-
-
-PSD2
-====
-
-PSD2 is not a technical standard, but high-level legal requirements on
(amongst other things) APIs
-that banks have to offer.
-
-There are many implementations of PSD2 APIs. The `Berlin Group
<https://www.berlin-group.org/>`__
-provides a framework that somewhat standardizes technical details, but the use
of this standard
-is by no means necessary.
-
-Unfortunately, it focuses on *other* parties accessing *your* bank account. It
-does not give customers access to their own bank account. Customers can manage
-third party access they give to their bank account in their online banking
-system. That mechanism is conceptually similar to OAuth2. In fact, some
-implementations of PSD2 even use OAuth2 directly.
-
-PSD2 APIs usually use JSON as a data format. Often the schema and terminology
is "inspired" by ISO20022
-messages, but no actual ISO20022 XML message formats are used.
-
-PSD2 requires two main services to be available via an API:
-
-* AIS (Account Information Service).
-* PIS (Payment Initiation Service).
-
-Together, they're often called XS2A ("access to account").
-
-An entity that wants to use AIS has to be registered with the financial
-oversight authority in its country (BAFIN in Germany). PIS has even stronger
-legal prerequisites.
-
-On a technical level, using PSD2 APIs usually requires having an `EIDAS
<https://en.wikipedia.org/wiki/EIDAS>`__ certificate.
-
-Examples (bank offerings):
- * `Sparkasse <https://xs2a.sparkassen-hub.com/home>`__ (Berlin Group based)
- * `Deutsche Bank <https://developer.db.com/products/psd2>`__
-
-Examples (standards):
- * `STET PSD2 API <https://www.stet.eu/en/psd2/>`__
- * `Berlin Group NextGenPSD2
<https://www.berlin-group.org/nextgenpsd2-downloads>`__
-
-
-
-Bank-Proprietary APIs
-=====================
-
-Some banks offer completely custom APIs to access services of the bank. These
often include services
-not available via more standardized APIs, such as account creation.
-
-Often banks frame PSD2 as just another API available in their portfolio of API
offerings.
-
-Examples:
-
-* `Deutsche Bank <https://developer.db.com/products>`__
-* `ING Group <https://developer.ing.com/api-marketplace/marketplace>`__
-* `Revolut <https://revolut-engineering.github.io/api-docs/business-api/>`__
-* `PayPal <https://developer.paypal.com/classic-home/>`__
-
-
-Open Bank Project
-=================
-
-The `Open Bank Project <https://www.openbankproject.com/>`__ provides a free
software implementation of
-banking middleware that supports various APIs, including PSD2-compatible APIs
(based on Berlin Group).
-
-API Docs:
`<https://github.com/OpenBankProject/OBP-API/wiki/Open-Bank-Project-Architecture>`__
-
-
-UK Open Banking
-===============
-
-Open Banking is the (quite confusing!) name of a UK-based open banking
initiative.
-
-What's nice about Open Banking is that their APIs are really close to ISO
20022, unlike many
-similar HTTP+JSON APIs.
-
-`<https://openbanking.atlassian.net/wiki/spaces/DZ/pages/16385802/Specifications>`__
diff --git a/libeufin/ebics.rst b/libeufin/ebics.rst
deleted file mode 100644
index 7c1fa2ae..00000000
--- a/libeufin/ebics.rst
+++ /dev/null
@@ -1,598 +0,0 @@
-.. target audience: core developer
-
-EBICS Implementation Notes
-##########################
-
-.. warning::
-
- This document summarizes and clarifies some aspects of the EBICS protocol
- that are important to LibEuFin. Both version 3.0 and 2.5 are discussed here.
-
- It is not a specification, and it does not replace the official EBICS
specification.
-
-.. contents:: Table of Contents
-
-EBICS Glossary
-==============
-
-.. glossary::
- :sorted:
-
- A004
- Electronic signature process, used in :term:`H004`, deprecated in
:term:`H005` with EBICS 3.0.
-
- A005
- Electronic signature process. Used in :term:`H004` and :term:`H005`.
-
- A006
- Electronic signature process. Used in :term:`H004` and :term:`H005`.
-
- BTF
- *Business Transaction Formats.* Before EBICS 3.0, many different order
types were
- used for business-related messages. With EBICS 3.0, the more generic BTU
and BTD
- order types are used for all business-related messages.
-
- EBICS
- The *Electronic Banking Internet Communication Standard*.
-
- ES
- Electronic Signature. This abbreviation is commonly used in the context
of EBICS.
-
- The following signature classes are defined (in descending order from
- strongest to weakest):
-
- E
- Single signature (German "Einzeln").
- A
- First signature.
- B
- Second signature.
- T
- Transport signature. Only used to verify authorized submission,
- but not to verify the bank-technical authorization.
-
- In H004 and H005, the ES of the bank is specified as a "planned feature"
that
- is not actually implemented yet. Thus banks in practice only use their
- encryption key pair and authentication/identity key pair.
-
- EDS
- Distributed Electronic Signature. Allows multiple subscribers to
authorize an existing order.
-
- FTAM
- Historical predecessor protocol to EBICS (*file transfer, access and
management*).
-
- HEV
- The *Host EBICS Version*. Queried by the client with an HEV request
message.
-
- Human Subscriber
-
- See :term:`Subscriber`.
-
- H004
- Host protocol version 4. Refers to the XML Schema defined in *EBICS 2.5*.
-
- H005
- Host protocol version 5. Refers to the XML Schema defined in *EBICS 3.0*.
-
- Host ID
- Alphanumeric identifier for the EBICS Host. One EBICS server can
- host multiple banks, and each bank is identified by the Host ID.
- This concept is similar to Taler's merchant backend instance identifiers.
-
- Order Number
- Interchangeably called "Order ID".
-
- Each upload transaction gets a unique order number assigned by the bank
server.
- The Order Number is used to match VEUs in a second upload to the original
order.
- An Order Number matches the format ``[A-Z][A-Z0-9]{3}`` (and is not really
a number!).
-
- Must be unique per customer ID and per order type.
-
- Transaction ID
- A transaction ID is a 128-bit cryptographically strong random number.
- It is assigned by the bank server for every transaction, i.e. upload or
download
- of an order.
-
- The transaction ID must not be guessable, as it would allow a potential
- attacker to upload segments of an upload that do not match the whole
message's digest.
-
- Transaction key
- Symmetric encryption key for the data uploaded/downloaded in a transaction.
-
- Partner ID
- In German, this is called "Kunden ID" (= Customer ID).
- One partner can have multiple "participants", which are identified by user
IDs.
-
- Practical example: A company has one Partner ID. Each person at the
company
- that can access the company's bank accounts gets their own User ID.
- When the person is indirectly accessing the bank server (for example via
- a client server application), an additional "System ID" is created for this
- "technical subscriber". When there is no technical subscriber, the System
ID
- must be the same as the User ID. Usually the System ID is optional though.
-
- The ``(partner, user, system)`` triple uniquely identifies a subscriber.
-
- User ID
- See :term:`Partner ID`.
-
- System ID
- See :term:`Partner ID`.
-
- ISO 20022
- *ISO 20022: Financial Services - Universal financial industry message
scheme*. Rather important
- standard for financial industry **business-related** messages. In
contrast, EBICS takes
- care of message transmission, segmentation, authentication, key
management, etc.
-
- The full catalogue of messages is `available gratis
<https://www.iso20022.org/full_catalogue.page>`_.
-
- UNIFI
- UNIversal Financial Industry message scheme. Sometimes used to refer to
- :term:`ISO 20022`.
-
- Segmentation
- EBICS implements its own protocol-level segmentation of business-related
messages.
- The segmentation can be seen as an alternative to the HTTP facilities of
``Accept-Ranges``.
-
- The order data of an EBICS message may not exceed 1 MB. The segmentation
applies both
- to requests and responses.
-
- Subscriber
- Entity that wishes to communicate with the financial institution via EBICS.
-
- Subscribers can be *technical* or *human*. Technical subscribers are
typically
- a server in client-server applications, where the server talks to a
financial institution
- via EBICS.
-
- Requests from technical subscribers have a ``SystemID`` in addition to a
``PartnerID``
- and ``UserId``. A technical subscriber cannot sign a bank-technical
request.
-
- Technical Subscriber
- See :term:`Subscriber`.
-
- TLS
- *Transport Layer Security*. All messages in EBICS are sent over HTTP with
TLS.
- In the current version of the standard, only server certificates are
required.
-
- VEU
- Distributed Electronic Signature (from German "Verteilte Elektronische
Unterschrift").
-
- V001
- FTAM encryption algorithm ("Verschlüsselung"), superseded in EBICS by E002.
-
- E002
- EBICS encryption process, used to encrypt the order payload.
-
- X002
- Identification and authentication signature in H004 and H005.
-
-
-Order Types
-===========
-
-By convention, order types beginning with "H" are administrative order types,
and other ones are
-bank-technical order types. This convention isn't always followed
consistently by EBICS.
-
-Relevant Order Types
---------------------
-
-.. ebics:orders::
- :sorted:
-
- BTD
- **Only EBICS3.0+**. Business Transaction Format Download.
- Administrative order type to download a file, described in more detail by
the BTF structure.
-
- BTU
- **Only EBICS3.0+**. Business Transaction Format Upload.
- Administrative order type to upload a file, described in more detail by
the BTF structure.
-
- C52
- **Before EBICS 3.0**. Download bank-to-customer account report (intra-day
information).
-
- C53
- **Before EBICS 3.0**. Download bank-to-customer statement report (prior
day bank statement).
-
- CRZ
- Type: Download.
-
- Fetch payment status report (pain.002).
-
- CCC
- Type: Upload.
-
- Send SEPA Credit Transfer Initiation (pain.001) via XML container.
- This is the DFÜ variant (Appendix 3 DFÜ-Agreement).
-
- CCT
- Type: Upload.
-
- Send SEPA Credit Transfer Initiation (pain.001) directly.
- This is the DFÜ variant (Appendix 3 DFÜ-Agreement).
-
- CIZ
- Type: Download.
-
- Payment Status Report for Credit Transfer Instant.
-
- FUL
- **Before EBICS 3.0, France**. File Upload. Mainly used by France-style
EBICS.
-
- FDL
- **Before EBICS 3.0, France**. File Download. Mainly used by France-style
EBICS.
-
- HAA
- Type: Download, Optional.
-
- Download order types for which there is new data available.
-
- HTD
- Type: Download.
-
- Download information about a subscriber. From German "Teilnehmerdaten".
-
- HKD
- Type: Download, Optional.
-
- Download information about a customer (=partner). From German
"Kundendaten".
-
- HIA
- Transmission of the subscriber keys for (1) identification and
authentication and (2)
- encryption within the framework of subscriber initialisation.
-
- HPB
- Query the three RSA keys of the financial institute.
-
- HPD
- Host Parameter Data. Used to query the capabilities of the financial
institution.
-
- INI
- Transmission of the subscriber keys for bank-technical electronic
signatures.
-
- HAC
- Customer acknowledgement. Allows downloading a detailed "log" of the
activities
- done via EBICS, in the pain.002 XML format.
-
- HCS
- Change keys without having to send a new INI/HIA letter.
-
- SPR
- From German "sperren". Suspend a subscriber. Used when a key compromise is
- suspected.
-
- HCS
- Change the subscribers keys (``K_SIG``, ``K_IA`` and ``K_ENC``).
-
-Other Order Types
------------------
-
-The following order types are, for now, not relevant for LibEuFin:
-
-
-.. ebics:orders::
- :sorted:
-
- AZV
- Type: Upload.
-
- From German "Auslandszahlungsverkehr". Used to submit
- cross-border payments in a legacy format.
-
- CDZ
- Type: Download.
-
- Download payment status report for direct debit.
-
- CCU
- Type: Upload.
-
- German "Eilüberweisung".
-
- H3K
- Type: Upload.
-
- Send all three RSA key pairs for initialization at once, accompanied
- by a CA certificate for the keys. This is (as far as we know) used in
France,
- but not used by any German banks. When initializing a subscriber with H3K,
- no INI and HIA letters are required.
-
- HVE
- Type: Upload.
-
- Host Verification of Electronic Signature. Used to submit an electronic
signature separately
- from a previously uploaded order.
-
- HVD
- Type: Download.
-
- Retrieve VEU state.
-
- HVU
- Type: Download.
-
- Retrieve VEU overview.
-
- HVU
- Type: Download.
-
- Retrieve VEU extra information. From German "Zusatzinformationen".
-
- HVS
- Type: Upload.
-
- Cancel Previous Order (from German "Storno"). Used to submit an
electronic signature separately
- from a previously uploaded order.
-
- HSA
- Type: Optional
-
- Order to migrate from FTAM to EBICS. **Removed in EBICS 3.0**.
-
- PUB
- Type: Upload.
-
- Change of the bank-technical key (``K_SIG``).
- Superseded by HSA.
-
- HCA
- Type: Upload.
-
- Change the identification and authentication key as well as the encryption
key (``K_IA`` and ``K_ENC``).
- Superseded by HCS.
-
- PTK
- Type: Download.
-
- Download a human-readable protocol of operations done via EBICS.
- Mandatory for German banks. Superseded by the machine-readable
- HAC order type.
-
-
-EBICS Message Format
-====================
-
-The following elements are the allowed root elements of EBICS request/response
messages:
-
-* ``ebicsHEVRequest`` / ``ebicsHEVResponse``: Always unauthenticated and
unencrypted. Used
- **only** for query/response of the host's EBICS version.
-* ``ebicsUnsecuredRequest``: Request without signature or encryption (beyond
TLS). Used for INI and HIA.
-* ``ebicsKeyManagementResponse``: Unauthenticated response. Used for key
management responses and
- sometimes **also** to deliver error messages that are not signed by the bank
(such as "invalid request").
-* ``ebicsNoPubKeyDigestsRequest``: Signed request that *does not* contain the
hash of the bank's
- public key that the client expects. Used for key management, specifically
only the HPB order type.
-* ``ebicsRequest`` / ``ebicsResponse``
-* ``ebicsUnsignedRequest``: Not used anymore. Was used in FTAM migration with
the HSA order type.
-
-
-Order ID Allocation
-===================
-
-In practice, the Order ID seems to be allocated via number of counters at the
level of the **PartnerID**.
-
-
-EBICS Transaction
-=================
-
-A transaction in EBICS simply refers to the process of uploading or downloading
-a file. Whether it is an upload or download transaction depends on the order
-type. Each transaction is either an upload transaction or a download
-transaction, neither both.
-
-Uploads and downloads must proceed in segments of at most ``1 MB``. The
-segmentation happens after (1) encryption, (2) zipping, and (3) base64-encoding
-of the order data.
-
-The number of segments is always fixed starting from the first message sent
-(for uploads) or received (for downloads) by the subscriber. The digest of the
-whole message is also sent/received with the first message of a transaction.
-The EBICS host generates a 128-bit transaction ID. This ID is used to
-correlate uploads/downloads of segments for the same transaction.
-
-If an attacker would be able to guess the transaction ID, they could upload a
-bogus segment. This would only be detected after the whole file has been
-transmitted.
-
-An upload transaction is finished when the subscriber has sent the last
-segment. A download transaction is only finished when the subscriber has sent
-an additional acknowledgement message to the EBICS host.
-
-When upload/download of a segment fails, the client can always re-try. There
-are some conditions for that:
-
-* Segment ``n`` can only be downloaded/uploaded when segments ``[0..n-1]`` have
- been downloaded/uploaded.
-* The (implementation-defined) retry limit may not be exceeded.
-
-
-Formats
-=======
-
-ISO 20022
----------
-
-`ISO 20022 <https://www.iso20022.org/>`_
-is XML-based and defines the message format for many finance-related
activities.
-
-ISO 20022 messages are identified by a message identifier in the following
format:
-
- <business area> . <message identifier> . <variant> . <version>
-
-Some financial instututions (such as the Deutsche Kreditwirtschaft) have
decided to use
-a subset of elements/attributes in a message, this is what the ``<variant>``
part is for.
-"Standard" ISO20022 have variant ``001``.
-
-The most important message types for LibEuFin are:
-
-camt - Cash Management
- Particularly camt.053 (BankToCustomerStatement)
-
-pain - Payment Initiation
- Particularly pain.001 (CustomerCreditTransferInitiation) to initiate a
payment and
- pain.002 (CustomerPaymentStatus) to get the status of a payment.
-
-
-SWIFT Proprietary
-=================
-
-SWIFT Proprietary messages are in a custom textual format.
-The relevant messages are MT940 and MT942.
-
-* MT940 contains *pre-advice*, in the sense that transactions in it might still
- change or be reversed.
-* MT942 contains the settled transactions by the end of the day.
-
-SWIFT will eventually transition from MT messages to ISO20022,
-but some banks might still only give us account statements in the old
-SWIFT format.
-
-
-
-Key Management
-==============
-
-RSA key pairs are used for three purposes:
-
-1. Authorization of requests by signing the order data. Called the
*bank-technical key pair*,
- abbreviated here as ``K_SIG``.
-2. Identification/authentication of the subscriber. Called the
*identification and authentication key pair*,
- abbreviated here as ``K_IA``.
-3. Decryption of the symmetric key used to decrypt the bank's response.
Called the *encryption key pair*,
- abbreviated here as ``K_ENC``.
-
-One subscriber *may* use three different key pairs for these purposes.
-The identification and authentication key pair may be the same as the
encryption key pair.
-The bank-technical key pair may not be used for any other purpose.
-
-
-Real-time Transactions
-======================
-
-Real-time transactions will be supported with EBICS starting November 2019.
-That's the earliest date, some banks may offer it later or not at all.
-
-For us, :ebics:order:`CIZ` is the relevant order type that we need to ask banks
-for.
-
-
-Payment Reversal
-================
-
-It looks like there is no way to "reject" payments, unless you are the bank.
-
-There is a concept of payment reversal (with ``pain.007`` for direct debit and
``camt.055`` for SEPA Credit Transfer),
-but they are a way for the *payer / sender* to reverse a payment before it is
finalized.
-
-
-Bank Support
-============
-
-All German banks that are part of the Deutsche Kreditwirtschaft *must* support
EBICS.
-
-The exact subset of EBICS order types must be agreed on contractually by the
bank and customer.
-The following subsections list the message types that we know are supported by
particular banks.
-
-GLS Bank
---------
-
-According to publicly available `forms
-<https://www.gls-laden.de/media/pdf/f1/c6/f2/nderungsauftrag.pdf>`_, GLS Bank
-supports the following order types:
-
-* :ebics:order:`AZV`
-* :ebics:order:`PTK`
-* :ebics:order:`CDZ`
-* :ebics:order:`CRZ`
-* :ebics:order:`CCC`
-* :ebics:order:`CCT`
-* :ebics:order:`CCU`
-* :ebics:order:`HVE`
-* :ebics:order:`HVS`
-* ... and mandatory administrative messages
-
-Sparkasse München
------------------
-
-See `this document
<https://www.sskm.de/content/dam/myif/ssk-muenchen/work/dokumente/pdf/allgemein/ebics-default-geschaeftsvorfaelle.pdf>`__.
-
-
-HypoVereinsbank
----------------
-
-See `this document
<https://www.hypovereinsbank.de/content/dam/hypovereinsbank/shared/pdf/Auftragsarten_Internet_Nov2018_181118.pdf>`__.
-
-
-Cryptography
-============
-
-EBICS uses the XML Signature standard for signatures. It does *not* use XML
encryption.
-
-The EBICS specification doesn't directly reference the standardized URIs for
the various
-signing algorithms. Some of these URIs are defined
-in `RFC 6931 <https://tools.ietf.org/html/rfc6931>`__.
-
-* A005 is `<http://www.w3.org/2001/04/xmldsig-more#rsa-sha256>`__.
-
- * The ``RSASSA-PKCS1-v1_5`` signature scheme contains the
``EMSA-PKCS1-v1_5`` encoding scheme
- mentioned in the EBICS spec.
-
-* A006 is `<http://www.w3.org/2007/05/xmldsig-more#rsa-pss>`__ as defined in
RFC 6931.
-
-XML Signatures
---------------
-
-XML Signatures can be a combination of:
-
-* detached (referencing another document)
-* enveloping (signs over ``Object`` tags *within* the ``Signature`` elements)
-* enveloped (signs over arbitrary data (via XPath expression) in other parts
of the document
- that contains the signature).
-
-In EBICS, only **enveloped** signatures are used.
-
-In the XML Signature standard, the element for a signature is ``Signature``.
EBICS violates this
-standard by always mandating ``AuthSignature`` as the name. ``AuthSignature``
is an alias to
-the ``SignatureType`` XSD type in the XML Schema.
-
-Canonicalization vs transforms:
- * Canonicalization refers to the processing of the ``SignedInfo`` element.
- * Transformations apply to the data that ``Reference`` elements reference.
Canonicalization
- algorithms can be used as a transformation on referenced data.
-
-Standards and Resources
-=======================
-
-EBICS
------
-
-The EBICS standard documents are available at `<http://www.ebics.org>`_.
-
-EBICS 3.0:
-
-* The main EBICS 3.0 specification
- (``2017-03-29-EBICS_V_3.0-FinalVersion.pdf``).
-* Annex 1 specifies EBICS return codes, as EBICS doesn't use HTTP status codes
directly
- (``2017-03-29-EBICS_V_3.0_Annex1_ReturnCodes-FinalVersion.pdf``) .
-* Annex BTF contains the registry of BTF codes.
-
-DFÜ Agreement
--------------
-
-The DFÜ Agreement is the set of standards used by the German Banking Industry
Committee (Deutsche Kreditwirtschaft).
-
-The following Annexes (also see the `DK Website
<https://die-dk.de/zahlungsverkehr/electronic-banking/dfu-verfahren-ebics/>`_)
are
-relevant for implementing EBICS:
-
-* Annex 1 is the EBICS specification
-* (Annex 2 is deprecated)
-* Annex 3 describes the data formats used by German banks within EBICS.
-
-EBICS Compendium
-----------------
-
-The `EBICS Compendium
<https://www.ppi.de/en/payments/ebics/ebics-compendium/>`_ has some additional
info on EBICS.
-It is published by a company that sells a proprietary EBICS server
implementation.
-
-Others
-------
-
-* `<https://wiki.windata.de/index.php?title=EBICS-Auftragsarten>`_
-* `<https://www.gls-laden.de/media/pdf/f1/c6/f2/nderungsauftrag.pdf>`_
diff --git a/libeufin/frontend.rst b/libeufin/frontend.rst
deleted file mode 100644
index 1fe1c83f..00000000
--- a/libeufin/frontend.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-.. target audience: core developer
-
-###################
-LibEuFin Frontend
-###################
-
-Introduction
-================
-
-LibEuFin Frontend is a Single Page Application (SPA) built using React that
facilitates setting up access to bank accounts, querying/displaying the
transaction history of bank accounts and initiating payments.
-
-Architecture
-===============
-
-The frontend code sits in the */frontend* folder. Files in the subfolders are
highlighted below.
-
-/actions, /reducers folder
---------------------------
-Contains code that uses Redux to store the login state. Prevents user from
relogging in every time they closed the browser or browser tab.
-
-/routes folder
---------------
-Directs the user to the respective pages according to the URL route. Routes
are broken down into *UnauthenticatedRoute* and *AuthenticatedRoute*, which
corresponds to the user's login state.
-
-/components/login
------------------
-The login page for the user.
-
-/components/navbar
-------------------
-Reusable navbar component that appears on every page of the project.
-
-/components/footer
-------------------
-Reusable footer component that appears on every page of the project.
-
-components/home
----------------
-The home page showing general information of the users for e.g. bank accounts
set up.
-
-/components/activity
---------------------
-Shows activity of payments and its transaction history (WIP).
-
-/components/bank-accounts
--------------------------
-Shows bank accounts that are imported. A bank account drawer is shown to
facilitate setting up of bank accounts. Each bank account is displayed in a
card to display extra details for e.g its print document.
diff --git a/libeufin/iso20022.rst b/libeufin/iso20022.rst
deleted file mode 100644
index 3484c77d..00000000
--- a/libeufin/iso20022.rst
+++ /dev/null
@@ -1,112 +0,0 @@
-.. target audience: core developer
-
-ISO 20022
-#########
-
-ISO 20022 is the standard that defines many XML messages for FinTech. It is
-very general, and often countries/orgs define subsets (TVS, technical
-validation subset) of the schema.
-
-Documentation for message fields can be viewed at
`<https://www.iso20022.org/standardsrepository>`__.
-
-The primary syntax for ISO 20022 messages is XML. To avoid LibEuFin clients
-having to deal with XML, we define a mapping from ISO 20022 messages into JSON.
-
-The specifics of this mapping are:
-
- * The JSON should be "idiomatic" and easy to process.
- * When possible, the highly nested structures of ISO 20022 should be
flattened.
- * It must be possible round-trip between the LibEuFin JSON and ISO 20022
- XML messages. The mapping of message types is not 1-to-1, as some ISO 20022
messages are
- very similar and can be mapped to the same JSON structure.
- * JSON-mapped messages are not explicitly versioned. Instead, changes
- are made in a backwards-compatible way, possibly preserving old versions
- of message elements in the same schema.
-
-
-How does LibEuFin leverage ISO 20022?
-=====================================
-
-While LibEuFin can communicate ISO 20022 messages (camt.05x, pain.001) to
-other parties, it does **not** model its own authored API and internal data
-after the ISO 20022 standard.
-
-Objections to ISO20022:
-
-1. Impedance mismatch. ISO 20022 messages do not map well to query/response
- APIs.
-2. Cumbersome to use. Even when ISO 20022 messages are directly mapped
- to JSON, they are difficult to use due to their verbosity.
-3. Underspecification. Messages like camt.05x leave many "degrees of freedom"
- when translating the underlying data into a message.
-4. No interoperability. As a result of underspecification, different
countries/organizations
- define their own subset and interpretation rules for ISO 20022 messages.
This can
- lead to even contradictory usage rules. An example for this is how the
Swiss and EPC
- interpretations handle transaction amounts in the presence of multiple
currencies.
-5. Redundancy. ISO 20022 are redundant, and often mix aspects of the
"presentation logic"
- with the underlying data model. An example of this is the optional
"summary" information
- in camt.05x messages.
-
-Instead of using ISO 20022 messages directly, LibEuFin leverages the standard
in other ways:
-
-* As the data exchange format with banks
-* As a guideline for naming in data formats
-* As a guideline for which concepts need to be understood by LibEuFin
-
-
-Implementation notes for camt.05x
-=================================
-
-Types of amounts in camt messages
----------------------------------
-
-* Entry amount
-
- * ISO 20022: Mandatory, with debit/credit indicator. Indicates money
- moving in/out of the account in the account's currency.
- * LibEuFin: Same.
-
-* Entry transaction amount
-
- * ISO 20022: Optional, direction-less. Amount of money
- moving between the debtor and creditor bank, may not be
- in the account's currency (but the "native" currency between
- the two banks).
- * LibEuFin: Same.
-
-* Entry instructed amount
-
- * ISO 20022: Optional, direction-less. Amount of money specified in the
- payment initiation message. Usually only specified when the amount is in a
- different currency than the account currency.
- * LibEuFin: Same.
-
-* Entry counter value amount
-
- * ISO 20022: Optional, direction-less. Amount in the account's
- currency before charges.
- * LibEuFin: Same.
-
-* Entry announced posting amount
-
- * (not used by LibEuFin)
-
-* EntryDetails amount
-
- * ISO 20022: Optional, with debit-credit indicator. Same as "Entry amount"
- but for EntryDetails (= logical transactions).
- * LibEuFin: Always present. In Swiss camt messages, the element is always
- present. In German/Swedish/... camt, we take the "Entry amount" for
- non-batch entries, whereas in batch entries we use the "EntryDetails
- transaction amount" with the same debit credit indicator as the whole
- entry, which by local rules is always in the bank account currency.
-
-* EntryDetails (transaction / instructed / counter value) amount
-
- * ISO 20022: Optional, direction-less. Same as "Entry ... amount"
- but for EntryDetails (= logical transactions).
- * Same.
-
-* EntryDetails announced posting amount
-
- * (not used by LibEuFin)
diff --git a/libeufin/nexus-manual.rst b/libeufin/nexus-manual.rst
index c027e691..70ac5e05 100644
--- a/libeufin/nexus-manual.rst
+++ b/libeufin/nexus-manual.rst
@@ -68,6 +68,10 @@ The following snippet shows the mandatory configuration
values.
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
diff --git a/libeufin/performance.rst b/libeufin/performance.rst
deleted file mode 100644
index a0af25a8..00000000
--- a/libeufin/performance.rst
+++ /dev/null
@@ -1,114 +0,0 @@
-Performance demonstrators
-#########################
-
-This document explains how to prove the following performance
-requirements implemented in LibEuFin.
-
-1. Long-polling offered by Nexus to the Exchange Wirewatch.
-2. Reduced usage of disk space by the database.
-3. PostgreSQL short-lived database sessions.
-4. Participation in the Taler benchmark.
-
-It is worth noting that point 2 and 3 will be proved *via*
-point 4. In particular, because the benchmark is a resource
-demanding activity, its impact on the database should be
-enough to reflect a worst case scenario with regard to points
-2 and 3.
-
-The following two sections will describe how to run
-`point 1 <Long-polling>`_, and `points 2, 3, 4 <Benchmark>`_
-altogether.
-
-Long-polling
-^^^^^^^^^^^^
-
-This demonstrator is a Docker image that installs LibEuFin
-and registers one user at both Sandbox and Nexus. The Nexus
-user is set up to use the Taler Wire Gateway, to let ``curl``
-emulate the Taler exchange (wire-watch).
-
-To run the demonstrator, clone the following repository:
-
-.. code-block:: shell-session
-
- git://git.taler.net/deployment
-
-and build the Docker image:
-
-.. code-block:: shell-session
-
- $ cd deployment/nlnet/task5/long-poll
- $ docker build -t long-poller .
-
-Start the ``long-poller`` image and wait after the installation
-and configuration complete. The completion should end with a message
-starting by ``Services are online!``. At this point, it is possible
-to request Taler incoming payments and observe how such request returns
-**only after** we manually send Taler money to the long-polling client.
-
-Give the following command to request Taler incoming payment
-with the long-polling feature:
-
-.. code-block:: shell-session
-
- $ curl -v -u test-user:x
'http://localhost:5001/facades/test-facade/taler-wire-gateway/history/incoming?delta=5&long_poll_ms=100000'
-
-After having observed that the previous command *actually*
-long-polls, send it to the background by pressing CTRL-Z. Send
-now a Taler payment to ``test-user`` with the following command.
-
-.. code-block:: shell-session
-
- $ wire_transfer
-
-Bring now the ``curl`` process again in the foreground, and if
-it got the payment, now it shows the payment data.
-
-Benchmark
-^^^^^^^^^
-
-This demonstrator runs the Taler benchmark that relies on LibEuFin.
-
-Clone the following repository:
-
-.. code-block:: shell-session
-
- git://git.taler.net/deployment
-
-and build the Docker image:
-
-.. code-block:: shell-session
-
- $ cd deployment/nlnet/task5/benchmark
- $ docker build -t benchmark .
-
-Run the ``benchmark`` image and wait for its completion. At this
-point, the demonstrator prints the benchmark result regarding all
-the components, and lastly the database disk usage and the LibEuFin
-database session(s) duration(s).
-
-The database disk usage is complessive, therefore it shows how all
-the services occupy database disk space. Hence if this quantity is
-acceptable, then also LibEuFin's share is.
-
-On the other hand, the database session duration concerns only LibEuFin,
-and compares the *longest* database session with the whole benchmark
-duration. In particular, it shows what percentage of the whole benchmark
-duration is represented by the longest LibEuFin session. Therefore
-'low' percentages mean 'short' database sessions, as it is requested
-in point 3.
-
-..
- Clone the following repository:
-
- .. code-block:: shell-session
-
- git://git.taler.net/deployment
-
- and build the Docker image:
-
- .. code-block:: shell-session
-
- $ cd deployment/nlnet/task5/date-range
- $ docker build -t date-range .
-
diff --git a/libeufin/sepa.rst b/libeufin/sepa.rst
deleted file mode 100644
index 29baca00..00000000
--- a/libeufin/sepa.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. target audience: core developer
-
-SEPA Payments
-#############
-
-This page collects reference materials and details for specifics of SEPA
payments.
-
-SEPA Credit Transfer (SCT)
-==========================
-
-SCT is a "normal" bank transfer. Details (terminology, data definitions, flow
diagrams) can be found in the EPC's
-`SCT rulebook
<https://www.europeanpaymentscouncil.eu/document-library/rulebooks/sepa-credit-transfer-rulebook>`__.
-
-
-Reject vs Return vs Recall
---------------------------
-
-* A **rejected** payment is refused by the originator bank or the
- clearing and settlement layer.
-* A **returned** payment is refused by the beneficiary's bank via a
- counter-transaction over the settlement layer.
-* A payment is **recalled** when the originator's bank (potentially
- requested by the originator) wants to "undo" a SCT.
-
-SEPA currently does **not** directly support a mechanism for the
**beneficiary** to return
-a payment.
diff --git a/libeufin/transaction-identification.rst
b/libeufin/transaction-identification.rst
deleted file mode 100644
index 6c88a727..00000000
--- a/libeufin/transaction-identification.rst
+++ /dev/null
@@ -1,87 +0,0 @@
-.. target audience: developer, core developer
-
-Transaction Identification
-##########################
-
-This page describes how bank transactions are **identified** in various
banking protocols and
-data formats.
-
-**Why is transaction identification necessary?**
-When a client downloads the transaction history from some data source, it has
to know
-whether a transaction is new, or whether the transaction is already part of the
-client's local records.
-
-Protocol-specific Details
-=========================
-
-ISO 20022 camt.05X
-------------------
-
-The camt52/53/54 messages defined by ISO 20022 do not have a mandatory
transaction
-identifier. Instead it defines a handful of optional references.
-
-Two identifiers seem to be used in practice: The *Account Servicer Reference*
and the
-*Entry Reference*. Of these, only the *Account Servicer Reference* seems to
be useful
-for transaction identification.
-
-The Account Servicer Reference is assigned by the bank to a transaction. In
-practice, all banks assign the **same** Account Servicer Reference to the same
-transaction showing up in camt52 (the account report), camt53 (the account
-statement) and camt53 (credit notifications).
-
-The Account Servicer Reference is assigned by the bank that reports the
transaction,
-and does **not** serve as a globally unique identifier for the transaction.
-
-However, in rare cases, a transaction can be reported that does not yet have an
-Account Servicer Reference assigned to it by the bank yet. This can happen
-when the bank only received a (SWIFT) pre-notification for the transaction,
but decides
-to already pass on this information to the customer. In this case, banks seem
to
-assign an *Entry Reference* to the corresponding entry.
-
-Most other transactions, however, do **not** have an *Entry Reference*
assigned to it.
-Some banks document that the *Entry Reference* is only unique within one
report for one account.
-
-OFX
----
-
-OFX assigns a transaction identifier to each reported transactions, allowing
the client
-to know which transactions it has already seen.
-
-Problems and Possible Solutions
-===============================
-
-Sometimes the same bank can offer **multiple** ways to download transactions.
-In Germany, most banks offer EBICS and FinTS access, which delivers
transactions
-in the camt.52/53 format. However, some also offer access via PSD2 APIs and
completely custom APIs.
-
-Two APIs from the same bank do not necessarily need to support the same
transaction identification scheme.
-This could lead to the same transaction showing up multiple times in the
account transaction history, which
-is clearly bad!
-
-LibEuFin intends to solve this problem in the following ways:
-
-1. Each local account has a single "transaction identification scheme".
- Importing transactions via a bank connection that has a different
transaction
- identifier scheme will fail.
-2. When a bank connection reports a transaction that is missing the expected
transaction identifier,
- the status (booked, pending, info) is examined:
-
- 1. When the status is booked, an error is reported, and corresponding bank
message
- will be made available for review.
- 2. When the status is "pending" or "info", the entry will simply be ignored.
-
-In the future, this might be extended to be less restrictive:
-
-* An account could be configured to do transaction identification based on a
"core attributes hash",
- i.e. a cryptographic hash of core attributes of the transactions that are
expected to not change.
- This should only apply to booked transactions.
-* Un-identifiable pending/info transactions could be managed in a separate
- "informational" transactions table that is purged as soon as a *booked
statement closing transaction*
- is reported with a higher booking date.
-
-Others
-======
-
-* `UETR
<https://www.swift.com/your-needs/industry-themes/unique-end-to-end-transaction-reference-uetr>`__
is
- a unique identifier used on the SWIFT level. It doesn't help for
transaction identification
- as not every transaction goes over SWIFT, even for SEPA accounts.
diff --git a/manpages/libeufin-nexus.conf.5.rst
b/manpages/libeufin-nexus.conf.5.rst
index d6609943..b38c3436 100644
--- a/manpages/libeufin-nexus.conf.5.rst
+++ b/manpages/libeufin-nexus.conf.5.rst
@@ -31,10 +31,29 @@ comments from the configuration file!
GLOBAL OPTIONS
--------------
+Setting the database belongs to the “[nexus-postgres]” section and the
+following value.
+
+CONFIG
+ PostgreSQL connection string. Note: this option is NOT used by the
+ ebics-setup subcommand, as it stores the key files directly on the
+ filesystem.
+
+The “[paths]” section is special in that it contains paths that can be
+referenced using “$” in other configuration values that specify
+filenames. For Taler, it commonly contains the following paths:
+
+LIBEUFIN_HOME
+ Home directory of the user, usually “${HOME}”. Can be overwritten by
+ testcases by setting ${LIBEUFIN_TEST_HOME}.
+
+
+EBICS SETUP OPTIONS
+-------------------
+
The following options are from the “[nexus-ebics]” section and used by
the ``libeufin-nexus ebics-setup`` command.
-
CURRENCY
Name of the currency, e.g. “EUR” for Euro.
@@ -74,14 +93,21 @@ NAME
Legal entity that is associated with the EBICS subscriber.
-The “[PATHS]” section is special in that it contains paths that can be
-referenced using “$” in other configuration values that specify
-filenames. For Taler, it commonly contains the following paths:
+EBICS SUBMIT OPTIONS
+--------------------
-LIBEUFIN_HOME
- Home directory of the user, usually “${HOME}”. Can be overwritten by
- testcases by setting ${LIBEUFIN_TEST_HOME}.
+The following configuration value(s) belong to the “[nexus-submit]” section.
+FREQUENCY
+ Duration value to instruct the ``ebics-submit`` subcommand how much to wait
+ before checking the database again to find new unsubmitted payments. The
duration
+ must be expressed with a number followed (without space) by the time unit.
+ The following time units are supported: 's' (seconds), 'm' (minutes), 'h'
(hours).
+ For example, the value *5m* causes retries to be run every five minutes.
Whenever
+ the given number is zero, the retries are long-polled. Note: the current
version
+ does NOT support long-polling but would instead run in transient mode,
whenever
+ the duration number is zero. Finally, even with a duration number of zero,
the
+ duration unit must be specified.
SEE ALSO
========
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [taler-docs] branch master updated: ebics-setup config section.,
gnunet <=