commit 3f96fb2b8494a48a3a74aa560ad5a8c6a80b9c9e
parent 9729472ef932595c3c82f9fdf13c1f09e5c68ee1
Author: Christian Grothoff <grothoff@gnunet.org>
Date: Sun, 21 May 2023 00:40:08 +0200
revise exchange intro
Diffstat:
3 files changed, 129 insertions(+), 129 deletions(-)
diff --git a/frags/db-stores-sensitive-data.rst b/frags/db-stores-sensitive-data.rst
@@ -1,6 +1,5 @@
.. note::
- The Taler merchant backend stores private keys and other sensitive
- business and customer data in the database. The backend operator
- SHOULD ensure that backup operations are encrypted and secured from
- unauthorized access.
+ Taler may store sensitive business and customer data in the database. Any
+ operator SHOULD thus ensure that backup operations are encrypted and
+ secured from unauthorized access.
diff --git a/frags/install-before-check.rst b/frags/install-before-check.rst
@@ -2,9 +2,5 @@ Please note that unlike most packages, if you want to run the ``make check``
command, you should run it only *after* having done ``make install``. The
latter ensures that necessary binaries are copied to the right place.
-Gratuitous editorial note by TTN: I think this is a quirk that we should
-fix in the long-term as such weirdness might hide other build issues.
-However, this is probably a minority viewpoint.
-
In any case, if ``make check`` fails, please consider filing a
bug report with the Taler `bug tracker <https://bugs.taler.net>`__.
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
@@ -23,9 +23,6 @@ GNU Taler Exchange Operator Manual
Introduction
============
-This manual is an early draft that still needs significant editing work
-to become readable.
-
About GNU Taler
---------------
@@ -38,11 +35,6 @@ GNU Taler is compatible with anti-money-laundering (AML) and
know-your-customer (KYC) regulation, as well as data protection
regulation (such as GDPR).
-GNU Taler is not yet production-ready, after following this manual you
-will have a backend that can process payments in “KUDOS”, but not
-regular currencies. This is not so much because of limitations in the
-backend, but because we are not aware of a Taler exchange operator
-offering regular currencies today.
About this manual
-----------------
@@ -53,22 +45,22 @@ operate a GNU Taler exchange.
Organizational prerequisites
----------------------------
-Operating a GNU Taler exchange means that you are operating a payment
-service provider, which means that you will most likely need a bank
-license and/or follow applicable financial regulation.
+Operating a GNU Taler exchange means that you are operating a payment service
+provider, which means that you will most likely need a bank license and/or
+follow applicable financial regulation. Exceptions may apply, especially if
+you are operating a regional currency or a payment system for an event with a
+closed user group.
-GNU Taler payment service providers generally need to ensure high
-availability and have *really* good backups (synchronous replication,
-asynchronous remote replication, off-site backup, 24/7 monitoring,
-etc.). This manual will not cover these aspects of operating a
-payment service provider.
+GNU Taler payment service providers generally need to ensure high availability
+and should have *really* good backups (synchronous replication, asynchronous
+remote replication, off-site backup, 24/7 monitoring, etc.). This manual will
+not cover these aspects of operating a payment service provider.
-We will assume that you can operate a (high-availability,
+We will assume that you can operate a (sufficiently high-availability,
high-assurance) PostgreSQL database. Furthermore, we expect some moderate
familiarity with the compilation and installation of free software
-packages. You need to understand the cryptographic concepts of private
-and public keys and must be able to protect private keys stored in files
-on disk.
+packages. You need to understand the cryptographic concepts of private and
+public keys and must be able to protect private keys stored in files on disk.
.. include:: frags/db-stores-sensitive-data.rst
@@ -76,58 +68,65 @@ on disk.
Architecture overview
---------------------
-Taler is a pure payment system, not a new crypto-currency. As such, it
-operates in a traditional banking context. In particular, this means
-that in order to receive funds via Taler, the merchant must have a
-regular bank account, and payments can be executed in ordinary
-currencies such as USD or EUR. Similarly, the Taler exchange must
-interact with a bank. The bank of the exchange holds the exchange’s
-funds in an escrow account.
-
-Note that, given the technical burden (XML-based communications,
-additional cryptography, and a vast variety of standards) due to
-interact with banks, the exchange uses an intermediary system to talk
-to its bank. Such intermediary system abstracts the native banking
-protocol by exposing the *Taler Wire Gateway API*; this way, the exchange
-can conduct its banking operations in a simplified and JSON-based style.
-
-When customers wire money to the escrow account, the bank notifies the
-exchange about the incoming wire transfers. The exchange then creates a
-*reserve* based on the subject of the wire transfer. The wallet which
-knows the secret key matching the wire transfer subject can then
-withdraw coins from the reserve, thereby draining it. The liability of
-the exchange against the reserve is thereby converted into a liability
-against digital coins issued by the exchange. When the customer later
-spends the coins at a merchant, and the merchant *deposits* the coins at
+GNU Taler is a pure payment system, not a crypto-currency. As such, it
+operates in a traditional banking context. In particular, this means that
+payments can be executed in ordinary currencies such as USD or EUR.
+Furthermore, a typical merchant in Taler has a regular bank account, and would
+use it to receive funds via Taler.
+
+Consequently, a typical Taler exchange must interact with a bank. The bank of
+the exchange holds funds in an account where the balance is basically
+equivalent to the value of all coins in circulation. (Small mismatches arise
+whenever customers are about to withdraw coins and have already send the funds
+into the bank account, or if merchants just deposited coins and are about to
+receive wire transfers for deposited coins, or due to fees charged by the
+exchange and the operator not yet having drained the fees from the account.)
+
+The exchange uses an intermediary system to talk to its bank. This shifts the
+technical burden (XML-based communications, additional cryptography, and a
+vast variety of standards) for this interaction into another bank-specific
+subsystem. Such intermediary system abstracts the native banking protocol by
+exposing the *Taler Wire Gateway API*; this way, the exchange can conduct its
+banking operations in a simplified and JSON-based style.
+
+When customers wire money to the exchange's bank account, the Taler Wire
+Gateway API must notify the exchange about the incoming wire transfers. The
+exchange then creates a *reserve* based on the subject of the wire
+transfer. The wallet which knows the secret key matching the wire transfer
+subject can then withdraw coins from the reserve, thereby draining it. The
+liability of the exchange against the reserve is thereby converted into a
+liability against digital coins issued by the exchange. When the customer
+later spends the coins at a merchant, and the merchant *deposits* the coins at
the exchange, the exchange first *aggregates* the amount from multiple
-deposits from the same merchant and then instructs its bank to make a
-wire transfer to the merchant, thereby fulfilling its obligation and
-eliminating the liability. The exchange charges *fees* for some or all
-of its operations to cover costs and possibly make a profit.
+deposits from the same merchant and then instructs its bank to make a wire
+transfer to the merchant, thereby fulfilling its obligation and eliminating
+the liability. The exchange charges *fees* for some or all of its operations
+to cover costs and possibly make a profit.
-*Auditors* are third parties, for example financial regulators, that
-verify that the exchange operates correctly. The same software is also
-used to calculate the exchange’s profits, risk and liabilities by the
-accountants of the exchange.
+*Auditors* are third parties, for example financial regulators, that verify
+that the exchange operates correctly. The same software is also used to
+calculate the exchange’s profits, risk and liabilities by the accountants of
+the exchange.
The Taler software stack for an exchange consists of the following
components:
-- HTTP frontend
+- **HTTP frontend**:
The HTTP frontend interacts with Taler wallets and merchant backends.
It is used to withdraw coins, deposit coins, refresh coins, issue
refunds, map wire transfers to Taler transactions, inquire about the
exchange’s bank account details, signing keys and fee structure. The
binary is the ``taler-exchange-httpd``.
-- Crypto-Helpers
- The ``taler-exchange-secmod-rsa`` and ``taler-exchange-secmod-eddsa``
- are two programs that are responsible for managing the exchange's
+- **Crypto-Helpers**:
+ The ``taler-exchange-secmod-rsa``, ``taler-exchange-secmod-cs`` and
+ ``taler-exchange-secmod-eddsa``
+ are three programs that are responsible for managing the exchange's
online signing keys. They must run on the same machine as the
``taler-exchange-httpd`` as the HTTP frontend communicates with the
crypto helpers using UNIX Domain Sockets.
-- Aggregator
+- **Aggregator**:
The aggregator combines multiple deposits made by the same merchant
and (eventually) triggers wire transfers for the aggregate amount.
The merchant can control how quickly wire transfers are made. The
@@ -135,14 +134,14 @@ components:
excessively frequent transfers. The binary is the
``taler-exchange-aggregator``.
-- Closer
+- **Closer**:
The ``taler-exchange-closer`` tool check that reserves are properly
closed. If a customer wires funds to an exchange and then fails
to withdraw them, the closer will (eventually) trigger a wire
transfer that sends the customer's funds back to the originating
wire account.
-- Transfer
+- **Transfer**:
The ``taler-exchange-transfer`` tool is responsible for actually
executing the aggregated wire transfers. It is the only process
that needs to have the credentials to execute outgoing wire
@@ -152,7 +151,7 @@ components:
by LibEuFin. LibEuFin is an adapter which maps the Taler Wire
REST API to traditional banking protocols like EBICS and FinTS.
-- Wirewatch
+- **Wirewatch**:
The ``taler-exchange-wirewatch`` tool is responsible for observing
incoming wire transfers to the exchange. It needs to have the
credentials to obtain a list of incoming wire transfers.
@@ -161,24 +160,28 @@ components:
making outgoing wire transfers is done via different bank accounts
and/or credentials.
-- Wire adapter
+- **Wire adapter**:
A wire adapter is a component that enables exchange to talk to a bank.
-
- (1) The libtalerfakebank implements a bank with a wire adapter API
- inside of a testcase.
- (2) For the demonstration Web site (or local currencies),
- the Python bank provides a bank that directly provides
- the wire adapter API.
- (3) For production, libeufin's Nexus component implements a wire
- adapter towards the traditional SEPA banking system with IBAN
- accounts.
-
- The client-side wire adapter API is implemented in libtalerbank and
- is used by the transfer to execute wire transfers and for the
- auditor to query bank transaction histories.
-
-
-- DBMS
+ Each wire adapter must implement the Taler Wire Gateway API. Three
+ wire adapters are currently provided:
+
+ (1) The **libtalerfakebank** implements a bank with a wire adapter API
+ inside of a testcase. ``taler-fakebank-run`` is a stand-alone
+ process using libtalerfakebank. Note that this adapter is only
+ useful for tests, as all transaction data is kept in memory.
+ (2) For production, **libeufin**'s ``libeufin-nexus`` component
+ implements a wire adapter towards the traditional SEPA banking
+ system with IBAN accounts using the EBICS protocol.
+ (3) To use GNU Taler with blockchains, the **Depolymerization**
+ component provides a wire gateway API that runs on top of
+ blockchains like Bitcoin and Ethereum.
+
+ The client-side wire adapter API is implemented in **libtalerbank** and
+ is used by ``taler-exchange-transfer`` to execute wire transfers and by
+ ``taler-exchange-wirewatch`` and the Taler auditor auditor to query bank
+ transaction histories.
+
+- **DBMS**:
The exchange requires a DBMS to stores the transaction history for
the Taler exchange and aggregator, and a (typically separate) DBMS
for the Taler auditor. For now, the GNU Taler reference implementation
@@ -186,7 +189,7 @@ components:
support another DBMS.
.. index:: PostgreSQL
-- Auditor
+- **Auditor**:
The auditor verifies that the transactions performed by the exchange
were done properly. It checks the various signatures, totals up the
amounts and alerts the operator to any inconsistencies. It also
@@ -194,23 +197,23 @@ components:
exchange operator. The main binary is the ``taler-auditor``.
Aside from the key setup procedures, the most critical setup for
deploying an auditor is providing the auditor with an up-to-date
- copy of the database.
+ copy of the exchange's database.
-.. _Keys:
+.. _KeyTypes:
-Keys
-----
+Key Types
+---------
The exchange works with four types of keys:
-- master key (kept offline)
+- master key (kept offline, configured manually at merchants and wallets)
-- sign keys (signs normal messages from the exchange)
+- online message signing keys (signs normal messages from the exchange)
-- denomination keys (signs electronic coins, see section Coins)
+- denomination keys (signs digital coins)
-- security module keys (signs sign keys and denomination keys)
+- security module keys (signs online message signing keys and denomination keys)
Additionally, the exchange is sometimes concerned with the auditor's public
key (to verify messages signed by auditors approved by the exchange operator)
@@ -218,14 +221,14 @@ and the merchant's public key (to verify refunds are authorized by the
merchant).
Most of the keys are managed fully automatically or configured as part of the
-denomination configuration. However, the exchange master keys (the offline
-keys) have some configuration settings.
+denomination configuration. Some configuration settings must be manually
+set with regards to the exchange's master key.
Offline keys
------------
-The exchange (and ideally also auditors) uses a long-term offline master
+The exchange (and ideally also its auditor(s)) uses a long-term offline master
siging key that identifies the operator and is used to authenticate critical
information, such as the exchange's bank account and the actual keys the
exchange uses online.
@@ -238,11 +241,10 @@ computing power, a Raspberry-Pi is perfectly sufficient and the form-factor
might be good for safe-keeping! (You should keep a copy of the (encrypted)
private offline key on more than one physical medium though.)
-Exchange operators are strongly advised to secure your private master key and
-any copies on encrypted, always-offline computers. Again, we assume that you
-are familiar with good best practices in operational security, including
-securing key material.
-
+Exchange operators are strongly advised to secure their private master key and
+any copies on encrypted, always-offline computers. Again, this manual assumes
+that you are familiar with good best practices in operational security,
+including securing key material.
Online signing key security
@@ -262,8 +264,10 @@ integration support.
Functionality
^^^^^^^^^^^^^
-The UNIX domain sockets have mode 0620 (u+rw, g+w). The exchange process
-MUST be in the same group as the crypto helper processes.
+The UNIX domain sockets of the *secmod* helpers have mode 0620 (u+rw, g+w).
+The exchange process MUST thus be in the same group as the crypto helper
+processes to enable access to the keys. No other users should be in that
+group!
The two helper processes will create the required private keys, and allow
anyone with access to the UNIX domain socket to sign arbitrary messages with
@@ -271,6 +275,7 @@ the keys or to inform them about a key being revoked. The helper processes
are also responsible for deleting the private keys if their validity period
expires or if they are informed about a key having been revoked.
+
Security goals
^^^^^^^^^^^^^^
@@ -287,23 +292,21 @@ Setup
^^^^^
The helper processes should be run under a user ID that is separate from that
-of the user running the main ``taler-exchange-httpd`` service. For security,
-it is important that helpers run under a different user ID than the main HTTP
-frontend, in fact ideally each helper should run under its own user ID. The
-``taler-exchange-httpd`` service's will securely communicate with the helpers
-using UNIX domain sockets. To enable access to the keys, the service's user
-must be in the group of the helper processes (and no other users should be in
-that group).
+of the user running the main ``taler-exchange-httpd`` service. To get any
+security benefit from this, it is important that helpers run under a different
+user ID than the main HTTP frontend. In fact, ideally, each helper should run
+under its own user ID. The ``taler-exchange-httpd`` service's will securely
+communicate with the helpers using UNIX domain sockets.
Configuration
^^^^^^^^^^^^^
-The helpers and the HTTP service need both access to the same configuration
-information. Having divergent configurations may result in run-time failures.
-It is recommended that the configuration file (``-c`` option) is simply shared
-between all of the different processes, even though they run as different
-system users. The configuration does not contain any sensitive information.
-
+The helpers and the exchange HTTP service need both access to the same
+configuration information. Having divergent configurations may result in
+run-time failures. It is recommended that the configuration file (``-c``
+option) is simply shared between all of the different processes, even though
+they run as different system users. The configuration does not contain any
+sensitive information.
.. _ExchangeInstallation:
@@ -311,9 +314,9 @@ system users. The configuration does not contain any sensitive information.
Installation
============
-Before installing a Taler exchange, please make sure that your
-system does not have swap space enabled. Swap space is a security
-risk that Taler does not try to mitigate against.
+Before installing a Taler exchange, please make sure that your system does not
+have swap space enabled. Swap space is a security risk that Taler does not
+try to mitigate against.
We recommend the setup of offline signing keys to be done on a second machine that
does not have Internet access.
@@ -356,11 +359,12 @@ The package sources can be find in our
GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format.
The general rule for compatibility is that ``MAJOR`` and ``MINOR`` must match.
-Exceptions to this general rule are documented in the release notes.
-For example, Taler merchant 1.3.0 should be compatible with Taler exchange 1.4.x
-as the MAJOR version matches. A MAJOR version of 0 indicates experimental
-development, and you are expected to always run all of the *latest* releases
-together (no compatibility guarantees).
+Exceptions to this general rule are documented in the release notes. For
+example, according to the general rule, a Taler merchant 1.3.0 should be
+compatible with Taler exchange 1.4.x as the MAJOR version matches. A MAJOR
+version of 0 indicates experimental development, and you are expected to
+always run all of the *latest* releases together (no compatibility
+guarantees).
First, the following packages need to be installed before we can compile the
backend:
@@ -442,10 +446,12 @@ to compartmentalize different parts of the system:
* ``taler-exchange-httpd``: runs the HTTP daemon with the core business logic.
* ``taler-exchange-secmod-rsa``: manages the RSA private online signing keys.
+* ``taler-exchange-secmod-cs``: manages the CS private online signing keys.
* ``taler-exchange-secmod-eddsa``: manages the EdDSA private online signing keys.
* ``taler-exchange-closer``: closes idle reserves by triggering wire transfers that refund the originator.
* ``taler-exchange-aggregator``: aggregates deposits into larger wire transfer requests.
-* ``taler-exchange-wire``: performs wire transfers with the bank (via LibEuFin/Nexus).
+* ``taler-exchange-transfer``: performs wire transfers with the bank (via LibEuFin/Nexus).
+* ``taler-exchange-wirewatch``: checks for incoming wire transfers with the bank (via LibEuFin/Nexus).
* ``postgres``: runs the PostgreSQL database (from *postgresql* package).
* ``www-data``: runs the frontend HTTPS service with the TLS keys (from *nginx* package).
@@ -458,11 +464,10 @@ to compartmentalize different parts of the system:
The exchange setup uses the following system groups:
* ``taler-exchange-db``: group for all Taler users with direct database access, specifically taler-exchange-httpd, taler-exchange-wire, taler-exchange-closer and taler-exchange-aggregator.
-* ``taler-exchange-secmod``: group for processes with access to online signing keys; this group must have three users: taler-exchange-secmod-rsa, taler-exchange-secmod-eddsa and taler-exchange-httpd.
+* ``taler-exchange-secmod``: group for processes with access to online signing keys; this group must have four users: taler-exchange-secmod-rsa, taler-exchange-secmod-cs, taler-exchange-secmod-eddsa and taler-exchange-httpd.
* ``taler-exchange-offline``: group for the access to the offline private key (only used on the offline host and not used on the online system).
-
-
+
The package will deploy systemd service files in
``/usr/lib/systemd/system/`` for the various components:
@@ -486,7 +491,7 @@ The deployment creates the following key locations in the system:
* ``/var/lib/taler/``: serves as the $HOME for all Taler users and contains sub-directories
with the private keys; which keys are stored here depends on the host:
- * online system: exchange-secmod-eddsa and exchange-secmod-rsa keys.
+ * online system: exchange-secmod-eddsa, exchange-secmod-cs and exchange-secmod-rsa keys.
* offline system: exchange-offline keys.
