revise exchange manual

1 files changed, 238 insertions, 214 deletions

diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index b3b10ed3..15086c24 100644
--- a/taler-exchange-manual.rst
+++ b/taler-exchange-manual.rst
@@ -637,8 +637,8 @@ Finally we need to grant the other accounts limited access:
    does not know which users will be used for which processes.
 
 
-Basic Setup: Currency and Denominations
-=======================================
+Basic Setup: Currency, Denominations and Keys
+=============================================
 
 A Taler exchange only supports a single currency.  The currency
 and the smallest currency unit supported by the bank system
@@ -658,8 +658,85 @@ must be specified in ``/etc/taler/taler.conf``.
    When editing ``/etc/taler/taler.conf``, take care to not accidentally remove
    the ``@inline-matching@`` directive to include the configuration files in ``conf.d``.
 
+ .. _Coins-denomination-keys:
+
+Coins (denomination keys)
+-------------------------
+
 Next, the electronic cash denominations that the exchange offers must be
-specified.  The ``taler-wallet-cli`` has a helper command that generates a
+specified.
+
+Sections specifying denomination (coin) information start with ``coin_``.  By
+convention, the name continues with ``$CURRENCY_[$SUBUNIT]_$VALUE_$REVISION``,
+i.e. ``[coin_eur_ct_10_0]`` for a 10 cent piece. However, only the ``coin_``
+prefix is mandatory.  Once configured, these configuration values must not
+change.  The ``$REVISION`` part of the section name should be incremented if
+any of the coin attributes in the section changes.  Each ``coin_``-section
+must then have the following options:
+
+-  ``VALUE``: How much is the coin worth, the format is
+   CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10".
+
+-  ``DURATION_WITHDRAW``: How long can a coin of this type be withdrawn?
+   This limits the losses incurred by the exchange when a denomination
+   key is compromised.
+
+-  ``DURATION_SPEND``: How long is a coin of the given type valid? Smaller
+   values result in lower storage costs for the exchange.
+
+-  ``DURATION_LEGAL``: How long is the coin of the given type legal?
+
+-  ``FEE_WITHDRAW``: What does it cost to withdraw this coin? Specified
+   using the same format as value.
+
+-  ``FEE_DEPOSIT``: What does it cost to deposit this coin? Specified using
+   the same format as value.
+
+-  ``FEE_REFRESH``: What does it cost to refresh this coin? Specified using
+   the same format as value.
+
+-  ``FEE_REFUND``: What does it cost to refund this coin?
+   Specified using the same format as value.
+
+-  ``CIPHER``: Which cipher to use for this coin? Must be either ``RSA`` or
+   ``CS``.
+
+-  ``RSA_KEYSIZE``: How many bits should the RSA modulus (product of the two
+   primes) have for this type of coin.
+
+- ``AGE_RESTRICTED``: Set to ``YES`` to make this a denomination with support
+   for age restrictions. See age restriction extension below for details.
+   This option is optional and defaults to ``NO``.
+
+See :doc:`manpages/taler.conf.5` for information on *duration* values
+(i.e. ``DURATION_WITHDRAW`` and ``DURATION_SPEND`` above,
+and ``OVERLAP_DURATION`` and ``DURATION`` below).
+Additionally, there are two global configuration options of note:
+
+-  ``[taler-exchange-secmod-rsa/OVERLAP_DURATION]``: What is the overlap of the
+   withdrawal timespan for denomination keys?  The value given here must
+   be smaller than any of the ``DURATION_WITHDRAW`` values for any of the coins.
+
+-  ``[taler-exchange-secmod-rsa/LOOKAHEAD_SIGN]``: For how far into the future
+   should denomination keys be pre-generated?  This allows the exchange and
+   auditor operators to download, offline-sign, and upload denomination key
+   signatures for denomination keys that will be used in the future by the
+   exchange.
+
+.. index:: maintenance
+.. note::
+   We recommend setting the ``LOOKAHEAD_SIGN`` value to at least one year and
+   then to perform the offline-signing procedure at least once every 6 months
+   to ensure that there is sufficient time for wallets to learn the new keys
+   and to avoid unavailability in case this critical maintenance procedure is
+   delayed.
+
+.. note::
+   It is crucial that the configuration provided in these sections is identical (!)
+   for the exchange and the crypto helpers.  We recommend pointing both users
+   to the same configuration file!
+
+The ``taler-wallet-cli`` has a helper command that generates a
 reasonable denomination structure.
 
 .. code-block:: shell-session
@@ -670,7 +747,87 @@ reasonable denomination structure.
                             > /etc/taler/conf.d/exchange-coins.conf
 
 You can manually review and edit the generated configuration file. The main
-change that is possibly required is updating the various fees.
+change that is possibly required is updating the various fees.  Note that you
+MUST NOT edit a coin configuration section after the initial setup. If you
+must ``change`` the values, you must instead create a new section with a
+different unique name (still with the ``coin-`` prefix) and comment out or
+remove the existing section.  Do take care to not introduce the name of the
+disabled section again in the future.
+
+
+.. _Sign-keys:
+
+Sign keys
+---------
+
+There are three global configuration options of note for sign keys:
+
+-  ``[taler-exchange-secmod-eddsa/DURATION]``: How long are sign keys
+   used to sign messages? After this time interval expires, a fresh
+   sign key will be used (key rotation).  We recommend using
+   a ``DURATION`` of a few weeks to a few months for sign keys.
+
+-  ``[taler-exchange-secmod-eddsa/OVERLAP_DURATION]``: What is the overlap of the
+   timespan for sign keys?  We recommend a few minutes or hours.  Must
+   be smaller than ``DURATION``.
+
+-  ``[taler-exchange-secmod-eddsa/LOOKAHEAD_SIGN]``: For how far into the future
+   should sign keys be pre-generated?  This allows the exchange and
+   auditor operators to download, offline-sign, and upload sign key
+   signatures for sign keys that will be used in the future by the exchange.
+
+.. note::
+   We recommend setting the ``LOOKAHEAD_SIGN`` value to at least one year and
+   then to perform the offline-signing procedure at least once every 6 months
+   to ensure that there is sufficient time for wallets to learn the new keys
+   and to avoid unavailability in case this critical maintenance procedure is
+   delayed.
+
+
+.. _OfflineConfiguration:
+
+Setting up the offline signing key
+----------------------------------
+
+Before launching an exchange, the offline signing (master) key must be
+generated and set in the configuration.  The offline signing keys of the
+exchange should be stored on a different machine.  The responsibilities of
+this offline signing machine are:
+
+* Generation of the exchange's offline master signing key.
+* Secure storage of the exchange's offline master signing key.
+* Generation of certificates (signed with the offline master signing key) that will be imported by the exchange.
+* Revocation of keys when the online system was compromised or is being terminated
+
+
+Configuration file options related to the master key are:
+
+- ``[exchange-offline/MASTER_PRIV_FILE]``: Path to the exchange’s master
+   private file.  Only needs to be provided on the offline system where the
+   ``taler-exchange-offline`` command is used.  The default value is usually
+   fine and does not require adjustment.
+
+- ``[exchange/MASTER_PUBLIC_KEY]``: Must specify the exchange’s master public
+   key.  Needed for the exchange to verify information signed by the offline
+   system.  This value must almost always be set explicitly by hand.
+
+
+
+.. code-block:: shell-session
+
+  [root@exchange-offline]# taler-exchange-offline setup
+  < ... prints the exchange master public key >
+
+The public key printed as the output of this command must be put into the
+configuration of the online machine:
+
+.. code-block:: ini
+  :caption: /etc/taler/conf.d/exchange-business.conf
+
+   [exchange]
+   MASTER_PUBLIC_KEY = YE6Q6TR1ED...
+
+   # ... rest of file ...
 
 
 Wire Gateway Setup
@@ -1131,173 +1288,16 @@ Such a Wire Gateway configuration can be tested with the following commands:
      --section exchange-accountcredentials-1 --credit-history
 
 
-.. _Deployment:
-
-Deployment
-==========
-
-This chapter describes how to deploy the exchange once the basic installation
-and configuration are completed.
-
-.. _Serving:
-
-Serving
--------
-
-The exchange can serve HTTP over both TCP and UNIX domain socket.
-
-The following options are to be configured in the section ``[exchange]``:
-
--  ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve
-   HTTP over a UNIX domain socket.
-
--  ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``.
-
--  ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is
-   ``unix``.
-
-- ``UNIXPATH_MODE``: Number giving the mode with the access permission mask
-   for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such
-   a way that your reverse proxy has permissions to access the UNIX domain
-   socket.  The default (660) assumes that the reverse proxy is a member of
-   the group under which the exchange HTTP server is running.
-
-.. _ReverseProxy:
 
-Reverse Proxy Setup
--------------------
+.. _LegalSetup:
 
-By default, the ``taler-exchange-httpd`` service listens for HTTP connections
-on a UNIX domain socket.  To make the service publicly available, a reverse
-proxy such as nginx should be used.  We strongly recommend to configure nginx
-to use TLS.
+Legal Setup
+===========
 
-The public URL that the exchange will be served under should
-be put in ``/etc/taler/conf.d/exchange-business.conf`` configuration file.
-
-.. code-block:: ini
-  :caption: /etc/taler/conf.d/exchange-business.conf
-
-   [exchange]
-   BASE_URL = https://example.com/
-
-   # ... rest of file ...
-
-The ``taler-exchange`` package ships with a sample configuration that can be
-enabled in nginx:
-
-.. code-block:: shell-session
-
-  [root@exchange-online]# vim /etc/nginx/sites-available/taler-exchange
-  < ... customize configuration ... >
-  [root@exchange-online]# ln -s /etc/nginx/sites-available/taler-exchange \
-                                /etc/nginx/sites-enabled/taler-exchange
-  [root@exchange-online]# systemctl reload nginx
-
-
- .. _Coins-denomination-keys:
-
-Coins (denomination keys)
--------------------------
-
-Sections specifying denomination (coin) information start with ``coin_``.  By
-convention, the name continues with ``$CURRENCY_[$SUBUNIT]_$VALUE_$REVISION``,
-i.e. ``[coin_eur_ct_10_0]`` for a 10 cent piece. However, only the ``coin_``
-prefix is mandatory.  Once configured, these configuration values must not
-change.  The ``$REVISION`` part of the section name should be incremented if
-any of the coin attributes in the section changes.  Each ``coin_``-section
-must then have the following options:
-
--  ``VALUE``: How much is the coin worth, the format is
-   CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10".
-
--  ``DURATION_WITHDRAW``: How long can a coin of this type be withdrawn?
-   This limits the losses incurred by the exchange when a denomination
-   key is compromised.
-
--  ``DURATION_SPEND``: How long is a coin of the given type valid? Smaller
-   values result in lower storage costs for the exchange.
-
--  ``DURATION_LEGAL``: How long is the coin of the given type legal?
-
--  ``FEE_WITHDRAW``: What does it cost to withdraw this coin? Specified
-   using the same format as value.
-
--  ``FEE_DEPOSIT``: What does it cost to deposit this coin? Specified using
-   the same format as value.
-
--  ``FEE_REFRESH``: What does it cost to refresh this coin? Specified using
-   the same format as value.
-
--  ``FEE_REFUND``: What does it cost to refund this coin?
-   Specified using the same format as value.
-
--  ``CIPHER``: Which cipher to use for this coin? Must be either ``RSA`` or
-   ``CS``.
-
--  ``RSA_KEYSIZE``: How many bits should the RSA modulus (product of the two
-   primes) have for this type of coin.
-
-- ``AGE_RESTRICTED``: Set to ``YES`` to make this a denomination with support
-   for age restrictions. See age restriction extension below for details.
-   This option is optional and defaults to ``NO``.
-
-See :doc:`manpages/taler.conf.5` for information on *duration* values
-(i.e. ``DURATION_WITHDRAW`` and ``DURATION_SPEND`` above,
-and ``OVERLAP_DURATION`` and ``DURATION`` below).
-Additionally, there are two global configuration options of note:
-
--  ``[taler-exchange-secmod-rsa/OVERLAP_DURATION]``: What is the overlap of the
-   withdrawal timespan for denomination keys?  The value given here must
-   be smaller than any of the ``DURATION_WITHDRAW`` values for any of the coins.
-
--  ``[taler-exchange-secmod-rsa/LOOKAHEAD_SIGN]``: For how far into the future
-   should denomination keys be pre-generated?  This allows the exchange and
-   auditor operators to download, offline-sign, and upload denomination key
-   signatures for denomination keys that will be used in the future by the
-   exchange.
-
-.. index:: maintenance
-.. note::
-   We recommend setting the ``LOOKAHEAD_SIGN`` value to at least one year and
-   then to perform the offline-signing procedure at least once every 6 months
-   to ensure that there is sufficient time for wallets to learn the new keys
-   and to avoid unavailability in case this critical maintenance procedure is
-   delayed.
-
-.. note::
-   It is crucial that the configuration provided in these sections is identical (!)
-   for the exchange and the crypto helpers.  We recommend pointing both users
-   to the same configuration file!
-
-
-.. _Sign-keys:
-
-Sign keys
----------
-
-There are three global configuration options of note for sign keys:
-
--  ``[taler-exchange-secmod-eddsa/DURATION]``: How long are sign keys
-   used to sign messages? After this time interval expires, a fresh
-   sign key will be used (key rotation).  We recommend using
-   a ``DURATION`` of a few weeks to a few months for sign keys.
-
--  ``[taler-exchange-secmod-eddsa/OVERLAP_DURATION]``: What is the overlap of the
-   timespan for sign keys?  We recommend a few minutes or hours.  Must
-   be smaller than ``DURATION``.
-
--  ``[taler-exchange-secmod-eddsa/LOOKAHEAD_SIGN]``: For how far into the future
-   should sign keys be pre-generated?  This allows the exchange and
-   auditor operators to download, offline-sign, and upload sign key
-   signatures for sign keys that will be used in the future by the exchange.
-
-.. note::
-   We recommend setting the ``LOOKAHEAD_SIGN`` value to at least one year and
-   then to perform the offline-signing procedure at least once every 6 months
-   to ensure that there is sufficient time for wallets to learn the new keys
-   and to avoid unavailability in case this critical maintenance procedure is
-   delayed.
+This chapter describes how to setup certain legal aspects of
+a GNU Taler exchange. Users that just want to set up an
+exchange as an experiment without legal requirements can
+safely skip these steps.
 
 
 Terms of Service
@@ -1611,52 +1611,75 @@ exchange to notify the exchange about the completion of KYC processes.
   KYC_KYCAID_POST_URL = "https://taler.net/"
 
 
+.. _Deployment:
 
-.. _OfflineConfiguration:
+Deployment
+==========
 
-Setting up the offline signing key
-----------------------------------
+This chapter describes how to deploy the exchange once the basic installation
+and configuration are completed.
 
-Before launching an exchange, the offline signing (master) key must be
-generated and set in the configuration.  The offline signing keys of the
-exchange should be stored on a different machine.  The responsibilities of
-this offline signing machine are:
+.. _Serving:
 
-* Generation of the exchange's offline master signing key.
-* Secure storage of the exchange's offline master signing key.
-* Generation of certificates (signed with the offline master signing key) that will be imported by the exchange.
-* Revocation of keys when the online system was compromised or is being terminated
+Serving
+-------
 
+The exchange can serve HTTP over both TCP and UNIX domain socket.
 
-Configuration file options related to the master key are:
+The following options are to be configured in the section ``[exchange]``:
 
-- ``[exchange-offline/MASTER_PRIV_FILE]``: Path to the exchange’s master
-   private file.  Only needs to be provided on the offline system where the
-   ``taler-exchange-offline`` command is used.  The default value is usually
-   fine and does not require adjustment.
+-  ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve
+   HTTP over a UNIX domain socket.
 
-- ``[exchange/MASTER_PUBLIC_KEY]``: Must specify the exchange’s master public
-   key.  Needed for the exchange to verify information signed by the offline
-   system.  This value must almost always be set explicitly by hand.
+-  ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``.
 
+-  ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is
+   ``unix``.
 
+- ``UNIXPATH_MODE``: Number giving the mode with the access permission mask
+   for the ``UNIXPATH`` (i.e. 660 = ``rw-rw---``). Make sure to set it in such
+   a way that your reverse proxy has permissions to access the UNIX domain
+   socket.  The default (660) assumes that the reverse proxy is a member of
+   the group under which the exchange HTTP server is running.
 
-.. code-block:: shell-session
+.. _ReverseProxy:
 
-  [root@exchange-offline]# taler-exchange-offline setup
-  < ... prints the exchange master public key >
+Reverse Proxy Setup
+-------------------
 
-The public key printed as the output of this command must be put into the
-configuration of the online machine:
+By default, the ``taler-exchange-httpd`` service listens for HTTP connections
+on a UNIX domain socket.  To make the service publicly available, a reverse
+proxy such as nginx should be used.  We strongly recommend to configure nginx
+to use TLS.
+
+The public URL that the exchange will be served under should
+be put in ``/etc/taler/conf.d/exchange-business.conf`` configuration file.
 
 .. code-block:: ini
   :caption: /etc/taler/conf.d/exchange-business.conf
 
    [exchange]
-   MASTER_PUBLIC_KEY = YE6Q6TR1ED...
+   BASE_URL = https://example.com/
 
    # ... rest of file ...
 
+The ``taler-exchange`` package ships with a sample configuration that can be
+enabled in nginx:
+
+.. code-block:: shell-session
+
+  [root@exchange-online]# vim /etc/nginx/sites-available/taler-exchange
+  < ... customize configuration ... >
+  [root@exchange-online]# ln -s /etc/nginx/sites-available/taler-exchange \
+                                /etc/nginx/sites-enabled/taler-exchange
+  [root@exchange-online]# systemctl reload nginx
+
+Note that the reverse proxy must set a HTTP ``X-Forwarded-Host`` header to
+refer to the hostname used by nginx and a HTTP ``X-Forwarded-Proto`` header to
+inform the exchange whether the external protocol was ``http`` or ``https``.
+Thus, depending on your setup, you will likely have to edit those parts of the
+provided ``taler-exchange`` configuration file.
+
 With this last step, we are finally ready to launch the
 main exchange process.
 
@@ -1748,13 +1771,13 @@ without offline keys its not fully operational.  To make the exchange HTTP
 service fully operational, the following steps involving the offline signing
 machine must be completed:
 
-1. The public keys of various online keys used by the exchange service are exported
-   via a management HTTP API.
-2. The offline signing system validates this request and signs it.
-   Additionally, the offline signing system signs policy messages
-   to configure the exchange's bank accounts and associated fees.
-3. The messages generated by the offline signing system are uploaded
-   via the management API of the exchange HTTP service.
+  1. The public keys of various online keys used by the exchange service are exported
+     via a management HTTP API.
+  2. The offline signing system validates this request and signs it.
+     Additionally, the offline signing system signs policy messages
+     to configure the exchange's bank accounts and associated fees.
+  3. The messages generated by the offline signing system are uploaded
+     via the management API of the exchange HTTP service.
 
 A typical minimal setup would look something like this:
 
@@ -2248,23 +2271,29 @@ exists and will launch all required services locally as needed.
 You can run a first simple benchmark using:
 
 .. note::
-   FIXME-TTN/CG: these instructions are incomplete and untested for the
+   FIXME-CG: these instructions are incomplete and untested for the
    current iteration of the code...
 
 .. code-block:: console
 
    $ createdb talercheck # if it does not yet exist
-   $ taler-exchange-dbinit -c benchmark.conf
-   $ taler-exchange-httpd -c benchmark.conf &
+   $ export CIPHER="rsa" # or cs
+   $ export CONF="benchmark-${CIPHER}.conf"
+   $ taler-exchange-dbinit -c "$CONF"
+   $ taler-exchange-secmod-rsa -c "$CONF" &
+   $ taler-exchange-secmod-cs -c "$CONF" &
+   $ taler-exchange-secmod-eddsa -c "$CONF" &
+   $ taler-exchange-httpd -c "$CONF" &
    $ HTTPD_PID=$!
-   $ taler-exchange-offline -c benchmark.conf \
+   $ taler-exchange-offline -c "$CONF" \
      download sign \
-     enable-account payto://iban/CH9300762011623852957 \
-     wire-fee iban EUR:0 EUR:0 \
-     global-fee EUR:0 EUR:0 EUR:0 4w 6y 4 \
+     enable-account \
+       payto://iban/CH9300762011623852957?receiver-name=exchange \
+     wire-fee now iban EUR:0 EUR:0 \
+     global-fee now EUR:0 EUR:0 EUR:0 4w 6a 42 \
      upload
-   $ kill -TERM $HTTPD_PID
-   $ taler-exchange-benchmark -c benchmark.conf -p 4 -r 1 -n 10
+   $ kill -TERM $(jobs -p)
+   $ taler-exchange-benchmark -c "$CONF" -p 4 -r 1 -n 10
 
 This will run 4 parallel clients withdrawing 10 coins from 1 reserve and then
 depositing those coins. The default refresh probability is 10 percent.  Note
@@ -2287,10 +2316,5 @@ FIXMEs
 * We should have some summary with the inventory of services that should be
   running.  Systemd by default doesn't show this nicely.  Maybe suggest running
   "systemd list-dependencies taler-exchange.target"?
-* When multiple TWGs are configured, which one will be used by the taler-exchange-transfer? CG: ALL!
-
-  * FD:  Sure, for incoming transactions.  But how does taler-exchange-transfer decide which TWG to use for an outgoing transaction?
-
 * What happens when the TWG doesn't like one particular outgoing transaction?
   How to recover from that as a sysadmin when it happens in practice?
-* This document (still) duplicates some details, should be de-duplicated!