summaryrefslogtreecommitdiff
path: root/taler-exchange.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2019-08-29 13:02:55 +0200
committerFlorian Dold <florian.dold@gmail.com>2019-08-29 13:02:55 +0200
commitba9335ec4c3578fdebfbec3072396bcda29d3425 (patch)
tree6d44f540797cba9ed77f28548714ff874141da66 /taler-exchange.rst
parentc3a6698c48f315e124bfd89bbb98564966f89434 (diff)
downloaddocs-ba9335ec4c3578fdebfbec3072396bcda29d3425.tar.gz
docs-ba9335ec4c3578fdebfbec3072396bcda29d3425.tar.bz2
docs-ba9335ec4c3578fdebfbec3072396bcda29d3425.zip
initial rough import of other docs
Diffstat (limited to 'taler-exchange.rst')
-rw-r--r--taler-exchange.rst869
1 files changed, 869 insertions, 0 deletions
diff --git a/taler-exchange.rst b/taler-exchange.rst
new file mode 100644
index 0000000..363a8f9
--- /dev/null
+++ b/taler-exchange.rst
@@ -0,0 +1,869 @@
+The GNU Taler Exchange Operator Manual
+######################################
+
+Introduction
+============
+
+This manual is an early draft that still needs significant editing work
+to become readable.
+
+About GNU Taler
+---------------
+
+GNU Taler is an open protocol for an electronic payment system with a
+free software reference implementation. GNU Taler offers secure, fast
+and easy payment processing using well understood cryptographic
+techniques. GNU Taler allows customers to remain anonymous, while
+ensuring that merchants can be held accountable by governments. Hence,
+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
+-----------------
+
+This tutorial targets system administrators who want to install and
+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.
+
+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.). [1]_ This manual will not cover these aspects of operating a
+payment service provider.
+
+We will assume that you can operate a (high-availability,
+high-assurance) Postgres 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. An exchange uses an *offline* master key as well as *online*
+keys. You are 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. [2]_
+
+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.
+
+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
+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.
+
+*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
+ 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``.
+
+- 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
+ exchange may be charge a fee per wire transfer to discourage
+ excessively frequent transfers. The binary is the
+ ``taler-exchange-aggregator``.
+
+- 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
+ computes the expected bank balance, revenue and risk exposure of the
+ exchange operator. The main binary is the ``taler-auditor``.
+
+- Wire plugin
+ A wire plugin enables the HTTP frontend to talk to the bank. Its role
+ is to allow the exchange to validate bank addresses (i.e. IBAN
+ numbers), for the aggregator to execute wire transfers and for the
+ auditor to query bank transaction histories. Wire plugins are
+ *plugins* as there can be many different implementations to deal with
+ different banking standards. Wire plugins are automatically located
+ and used by the exchange, aggregator and auditor.
+
+- DBMS
+ Postgres
+ 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 implemenation
+ only supports Postgres, but the code could be easily extended to
+ support another DBMS.
+
+Installation
+============
+
+Please install the following packages before proceeding with the
+exchange compilation.
+
+- GNU autoconf >= 2.69
+
+- GNU automake >= 1.14
+
+- GNU libtool >= 2.4
+
+- GNU autopoint >= 0.19
+
+- GNU libltdl >= 2.4
+
+- GNU libunistring >= 0.9.3
+
+- libcurl >= 7.26 (or libgnurl >= 7.26)
+
+- GNU libmicrohttpd >= 0.9.59
+
+- GNU libgcrypt >= 1.6
+
+- libjansson >= 2.7
+
+- Postgres >= 9.6, including libpq
+
+- libgnunetutil (from Git)
+
+- GNU Taler exchange (from Git)
+
+Except for the last two, these are available in most GNU/Linux
+distributions and should just be installed using the respective package
+manager.
+
+The following instructions will show how to install libgnunetutil and
+the GNU Taler exchange.
+
+Before you install libgnunetutil, you must download and install the
+dependencies mentioned above, otherwise the build may succeed but fail
+to export some of the tooling required by Taler.
+
+To download and install libgnunetutil, proceed as follows:
+
+::
+
+ $ git clone https://git.gnunet.org/gnunet/
+ $ cd gnunet/
+ $ ./bootstrap
+ $ ./configure [--prefix=GNUNETPFX]
+ $ # Each dependency can be fetched from non standard locations via
+ $ # the '--with-<LIBNAME>' option. See './configure --help'.
+ $ make
+ # make install
+
+If you did not specify a prefix, GNUnet will install to ``/usr/local``,
+which requires you to run the last step as ``root``.
+
+To download and install the GNU Taler exchange, proceeds as follows:
+
+::
+
+ $ git clone git://git.taler.net/exchange
+ $ cd exchange
+ $ ./bootstrap
+ $ ./configure [--prefix=EXCHANGEPFX] \
+ [--with-gnunet=GNUNETPFX]
+ $ # Each dependency can be fetched from non standard locations via
+ $ # the '--with-<LIBNAME>' option. See './configure --help'.
+ $ make
+ # make install
+
+If you did not specify a prefix, the exchange will install to
+``/usr/local``, which requires you to run the last step as ``root``.
+Note that you have to specify ``--with-gnunet=/usr/local`` if you
+installed GNUnet to ``/usr/local`` in the previous step.
+
+Configuration
+=============
+
+This chapter provides an overview of the exchange configuration. Or at
+least eventually will do so, for now it is a somewhat wild description
+of some of the options.
+
+Configuration format
+--------------------
+
+configuration
+In Taler realm, any component obeys to the same pattern to get
+configuration values. According to this pattern, once the component has
+been installed, the installation deploys default values in
+${prefix}/share/taler/config.d/, in .conf files. In order to override
+these defaults, the user can write a custom .conf file and either pass
+it to the component at execution time, or name it taler.conf and place
+it under $HOME/.config/.
+
+A config file is a text file containing sections, and each section
+contains its values. The right format follows:
+
+::
+
+ [section1]
+ value1 = string
+ value2 = 23
+
+ [section2]
+ value21 = string
+ value22 = /path22
+
+Throughout any configuration file, it is possible to use ``$``-prefixed
+variables, like ``$VAR``, especially when they represent filesystem
+paths. It is also possible to provide defaults values for those
+variables that are unset, by using the following syntax:
+``${VAR:-default}``. However, there are two ways a user can set
+``$``-prefixable variables:
+
+by defining them under a ``[paths]`` section, see example below,
+
+::
+
+ [paths]
+ TALER_DEPLOYMENT_SHARED = ${HOME}/shared-data
+ ..
+ [section-x]
+ path-x = ${TALER_DEPLOYMENT_SHARED}/x
+
+or by setting them in the environment:
+
+::
+
+ $ export VAR=/x
+
+The configuration loader will give precedence to variables set under
+``[path]``, though.
+
+The utility ``taler-config``, which gets installed along with the
+exchange, serves to get and set configuration values without directly
+editing the .conf. The option ``-f`` is particularly useful to resolve
+pathnames, when they use several levels of ``$``-expanded variables. See
+``taler-config --help``.
+
+Note that, in this stage of development, the file
+``$HOME/.config/taler.conf`` can contain sections for *all* the
+component. For example, both an exchange and a bank can read values from
+it.
+
+The repository ``git://taler.net/deployment`` contains examples of
+configuration file used in our demos. See under ``deployment/config``.
+
+ **Note**
+
+ Expectably, some components will not work just by using default
+ values, as their work is often interdependent. For example, a
+ merchant needs to know an exchange URL, or a database name.
+
+.. _Using-taler_002dconfig-exchange:
+
+Using taler-config
+------------------
+
+The tool ``taler-config`` can be used to extract or manipulate
+configuration values; however, the configuration use the well-known INI
+file format and can also be edited by hand.
+
+Run
+
+::
+
+ $ taler-config -s $SECTION
+
+to list all of the configuration values in section ``$SECTION``.
+
+Run
+
+::
+
+ $ taler-config -s $section -o $option
+
+to extract the respective configuration value for option ``$option`` in
+section ``$section``.
+
+Finally, to change a setting, run
+
+::
+
+ $ taler-config -s $section -o $option -V $value
+
+to set the respective configuration value to ``$value``. Note that you
+have to manually restart the Taler backend after you change the
+configuration to make the new configuration go into effect.
+
+Some default options will use $-variables, such as ``$DATADIR`` within
+their value. To expand the ``$DATADIR`` or other $-variables in the
+configuration, pass the ``-f`` option to ``taler-config``. For example,
+compare:
+
+::
+
+ $ taler-config -s ACCOUNT-bank \
+ -o WIRE_RESPONSE
+ $ taler-config -f -s ACCOUNT-bank \
+ -o WIRE_RESPONSE
+
+While the configuration file is typically located at
+``$HOME/.config/taler.conf``, an alternative location can be specified
+to ``taler-merchant-httpd`` and ``taler-config`` using the ``-c``
+option.
+
+.. _Keying:
+
+Keying
+------
+
+The exchange works with three types of keys:
+
+- master key
+
+- sign keys
+
+- denomination keys (see section Coins)
+
+- MASTER_PRIV_FILE: Path to the exchange’s master private file.
+
+- MASTER_PUBLIC_KEY: Must specify the exchange’s master public key.
+
+.. _Serving:
+
+Serving
+-------
+
+The exchange can serve HTTP over both TCP and UNIX domain socket.
+
+The following values 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—-).
+
+.. _Currency:
+
+Currency
+--------
+
+The exchange supports only one currency. This data is set under the
+respective option currency in section [taler].
+
+.. _Bank-account:
+
+Bank account
+------------
+
+To configure a bank account in Taler, we need to furnish four pieces of
+information:
+
+- The ``payto://`` URL of the bank account, which uniquely idenfies the
+ account. Examples for such URLs include
+ ``payto://sepa/CH9300762011623852957`` for a bank account in the
+ single European payment area (SEPA) or
+ ``payto://x-taler-bank/localhost:8080/2`` for the 2nd bank account a
+ the Taler bank demonstrator running at ``localhost`` on port 8080.
+ The first part of the URL following ``payto://`` (“sepa” or
+ “x-taler-bank”) is called the wire method.
+
+- A matching wire plugin that implements a protocol to interact with
+ the banking system. For example, the EBICS plugin can be used for
+ SEPA transfers, or the “taler-bank” plugin can interact with the
+ Taler bank demonstrator. A wire plugin only supports one particular
+ wire method. Thus, you must make sure to pick a plugin that supports
+ the wire method used in the URL.
+
+- A file containing the signed JSON-encoded bank account details for
+ the /wire API. This is necessary as Taler supports offline signing
+ for bank accounts for additional security.
+
+- Finally, the plugin needs to be provided resources for authentication
+ to the respective banking service. The format in which the
+ authentication information must be provided depends on the wire
+ plugin.
+
+You can configure multiple accounts for an exchange by creating sections
+starting with “account-” for the section name. You can ENABLE for each
+account whether it should be used, and for what (incoming or outgoing
+wire transfers):
+
+::
+
+ [account-1]
+ URL = "payto://sepa/CH9300762011623852957"
+ WIRE_RESPONSE = ${TALER_CONFIG_HOME}/account-1.json
+
+ # Currently, only the 'taler_bank' plugin is implemented.
+ PLUGIN = <plugin_name_here>
+
+ # Use for exchange-aggregator (outgoing transfers)
+ ENABLE_DEBIT = YES
+ # Use for exchange-wirewatch (and listed in /wire)
+ ENABLE_CREDIT = YES
+
+ # Authentication options for the chosen plugin go here.
+ # (Next sections have examples of authentication mechanisms)
+
+The command line tool taler-exchange-wire is used to create the
+``account-1.json`` file. For example, the utility may be invoked as
+follows to create all of the WIRE_RESPONSE files (in the locations
+specified by the configuration):
+
+::
+
+ $ taler-exchange-wire
+
+The generated file will be echoed by the exchange when serving
+/wire [3]_ requests.
+
+.. _Wire-plugin-_0060_0060taler_005fbank_0027_0027:
+
+Wire plugin “taler_bank”
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+x-taler-bank
+taler_bank plugin
+The ``taler_bank`` plugin implements the wire method “x-taler-bank”.
+
+The format of the ``payto://`` URL is
+``payto://x-taler-bank/HOSTNAME[:PORT]``.
+
+For basic authentication, the ``taler_bank`` plugin only supports simple
+password-based authentication. For this, the configuration must contain
+the “USERNAME” and “PASSWORD” of the respective account at the bank.
+
+::
+
+ [account-1]
+
+ # Bank account details here..
+ # ..
+
+ # Authentication options for the taler_bank plugin below:
+
+ TALER_BANK_AUTH_METHOD = basic
+ USERNAME = exchange
+ PASSWORD = super-secure
+
+.. _Wire-plugin-_0060_0060ebics_0027_0027:
+
+Wire plugin “ebics”
+~~~~~~~~~~~~~~~~~~~
+
+The “ebics” wire plugin is not fully implemented and today does not
+support actual wire transfers.
+
+ **Note**
+
+ The rationale behind having multiple bank accounts is that the
+ exchange operator, as a security measure, may want to instruct the
+ bank that the incoming bank account is only supposed to *receive*
+ money.
+
+.. _Wire-fee-structure:
+
+Wire fee structure
+~~~~~~~~~~~~~~~~~~
+
+wire fee
+fee
+For each wire method (“sepa” or “x-taler-wire”, but not per plugin!) the
+exchange configuration must specify applicable wire fees. This is done
+in configuration sections of the format ``fees-METHOD``. There are two
+types of fees, simple wire fees and closing fees. Wire fees apply
+whenever the aggregator transfers funds to a merchant. Closing fees
+apply whenever the exchange closes a reserve (sending back funds to the
+customer). The fees must be constant for a full year, which is specified
+as part of the name of the option.
+
+::
+
+ [fees-iban]
+ WIRE-FEE-2018 = EUR:0.01
+ WIRE-FEE-2019 = EUR:0.01
+ CLOSING-FEE-2018 = EUR:0.01
+ CLOSING-FEE-2019 = EUR:0.01
+
+ [fees-x-taler-bank]
+ WIRE-FEE-2018 = KUDOS:0.01
+ WIRE-FEE-2019 = KUDOS:0.01
+ CLOSING-FEE-2018 = KUDOS:0.01
+ CLOSING-FEE-2019 = KUDOS:0.01
+
+.. _Database:
+
+Database
+--------
+
+The option db under section [exchange] gets the DB backend’s name the
+exchange is going to use. So far, only db = postgres is supported. After
+choosing the backend, it is mandatory to supply the connection string
+(namely, the database name). This is possible in two ways:
+
+- via an environment variable: TALER_EXCHANGEDB_POSTGRES_CONFIG.
+
+- via configuration option CONFIG, under section [exchangedb-BACKEND].
+ For example, the demo exchange is configured as follows:
+
+::
+
+ [exchange]
+ ...
+ DB = postgres
+ ...
+
+ [exchangedb-postgres]
+ CONFIG = postgres:///talerdemo
+
+.. _Coins-denomination-keys:
+
+Coins (denomination keys)
+-------------------------
+
+Sections specifying denomination (coin) information start with ``coin_``.
+By convention, the name continues with "$CURRENCY_[$SUBUNIT]_$VALUE",
+i.e. ``[coin_eur_ct_10]`` for a 10 cent piece. However, only the ``coin_``
+prefix is mandatory. 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_overlap: What is the overlap of the withdrawal timespan for
+ this coin type?
+
+- duration_spend: How long is a coin of the given type valid? Smaller
+ values result in lower storage costs for the exchange.
+
+- 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.
+
+- rsa_keysize: How many bits should the RSA modulus (product of the two
+ primes) have for this type of coin.
+
+.. _Keys-duration:
+
+Keys duration
+-------------
+
+Both signkeys and denom keys have a starting date. The option
+lookahead_provide, under section [exchange], is such that only keys
+whose starting date is younger than lookahead_provide will be issued by
+the exchange.
+
+signkeys. The option lookahead_sign is such that, being t the time when
+taler-exchange-keyup is run, taler-exchange-keyup will generate n
+signkeys, where t + (n \* signkey_duration) = t + lookahead_sign. In
+other words, we generate a number of keys which is sufficient to cover a
+period of lookahead_sign. As for the starting date, the first generated
+key will get a starting time of t, and the j-th key will get a starting
+time of x + signkey_duration, where x is the starting time of the
+(j-1)-th key.
+
+denom keys. The option lookahead_sign is such that, being t the time
+when taler-exchange-keyup is run, taler-exchange-keyup will generate n
+denom keys for each denomination, where t + (n \* duration_withdraw) = t
++ lookahead_sign. In other words, for each denomination, we generate a
+number of keys which is sufficient to cover a period of lookahead_sign.
+As for the starting date, the first generated key will get a starting
+time of t, and the j-th key will get a starting time of x +
+duration_withdraw, where x is the starting time of the (j-1)-th key.
+
+To change these settings, edit the following values in section
+[exchange]:
+
+- SIGNKEY_DURATION: How long should one signing key be used?
+
+- LOOKAHEAD_SIGN: How much time we want to cover with our signing keys?
+ Note that if SIGNKEY_DURATION is bigger than LOOKAHEAD_SIGN,
+ ``taler-exchange-keyup`` will generate a quantity of signing keys
+ which is sufficient to cover all the gap.
+
+.. _Deployment:
+
+Deployment
+==========
+
+.. _Keys-generation:
+
+Keys generation
+---------------
+
+Once the configuration is properly set up, all the keys can be generated
+by the tool ``taler-exchange-keyup``. The following command generates
+denomkeys and signkeys, plus the "blob" that is to be signed by the
+auditor.
+
+::
+
+ taler-exchange-keyup -o blob
+
+*blob* contains data about denomkeys that the exchange operator needs to
+get signed by every auditor he wishes (or is forced to) work with.
+
+In a normal scenario, an auditor must have some way of receiving the
+blob to sign (Website, manual delivery, ..). Nonetheless, the exchange
+admin can fake an auditor signature — for testing purposes — by running
+the following command
+
+::
+
+ taler-auditor-sign -m EXCHANGE_MASTER_PUB -r BLOB -u AUDITOR_URL -o OUTPUT_FILE
+
+Those arguments are all mandatory.
+
+- ``EXCHANGE_MASTER_PUB`` the base32 Crockford-encoded exchange’s
+ master public key. Tipically, this value lies in the configuration
+ option ``[exchange]/master_public_key``.
+
+- ``BLOB`` the blob generated in the previous step.
+
+- ``AUDITOR_URL`` the URL that identifies the auditor.
+
+- ``OUTPUT_FILE`` where on the disk the signed blob is to be saved.
+
+``OUTPUT_FILE`` must then be copied into the directory specified by the
+option ``AUDITOR_BASE_DIR`` under the section ``[exchangedb]``. Assuming
+``AUDITOR_BASE_DIR = ${HOME}/.local/share/taler/auditors``, the
+following command will "add" the auditor identified by ``AUDITOR_URL``
+to the exchange.
+
+::
+
+ cp OUTPUT_FILE ${HOME}/.local/share/taler/auditors
+
+If the auditor has been correctly added, the exchange’s ``/keys``
+response must contain an entry in the ``auditors`` array mentioning the
+auditor’s URL.
+
+.. _Database-upgrades:
+
+Database upgrades
+-----------------
+
+Currently, there is no way to upgrade the database between Taler
+versions.
+
+The exchange database can be re-initialized using:
+
+::
+
+ $ taler-exchange-dbinit -r
+
+However, running this command will result in all data in the database
+being lost, which may result in significant financial liabilities as the
+exchange can then not detect double-spending. Hence this operation must
+not be performed in a production system.
+
+.. _Diagnostics:
+
+Diagnostics
+===========
+
+This chapter includes various (very unpolished) sections on specific
+topics that might be helpful to understand how the exchange operates,
+which files should be backed up. The information may also be helpful for
+diagnostics.
+
+.. _Reserve-management:
+
+Reserve management
+------------------
+
+Incoming transactions to the exchange’s provider result in the creation
+or update of reserves, identified by their reserve key. The command line
+tool taler-exchange-reservemod allows create and add money to reserves
+in the exchange’s database.
+
+.. _Database-Scheme:
+
+Database Scheme
+---------------
+
+The exchange database must be initialized using taler-exchange-dbinit.
+This tool creates the tables required by the Taler exchange to operate.
+The tool also allows you to reset the Taler exchange database, which is
+useful for test cases but should never be used in production. Finally,
+taler-exchange-dbinit has a function to garbage collect a database,
+allowing administrators to purge records that are no longer required.
+
+The database scheme used by the exchange look as follows:
+
+.. image:: exchange-db.png
+
+.. _Signing-key-storage:
+
+Signing key storage
+-------------------
+
+The private online signing keys of the exchange are stored in a
+subdirectory "signkeys/" of the "KEYDIR" which is an option in the
+"[exchange]" section of the configuration file. The filename is the
+starting time at which the signing key can be used in microseconds since
+the Epoch. The file format is defined by the struct
+TALER_EXCHANGEDB_PrivateSigningKeyInformationP:
+
+::
+
+ struct TALER_EXCHANGEDB_PrivateSigningKeyInformationP {
+ struct TALER_ExchangePrivateKeyP signkey_priv;
+ struct TALER_ExchangeSigningKeyValidityPS issue;
+ };
+
+.. _Denomination-key-storage:
+
+Denomination key storage
+------------------------
+
+The private denomination keys of the exchange are store in a
+subdirectory "denomkeys/" of the "KEYDIR" which is an option in the
+"[exchange]" section of the configuration file. "denomkeys/" contains
+further subdirectories, one per denomination. The specific name of the
+subdirectory under "denomkeys/" is ignored by the exchange. However, the
+name is important for the "taler-exchange-keyup" tool that generates the
+keys. The tool combines a human-readable encoding of the denomination
+(i.e. for EUR:1.50 the prefix would be "EUR_1_5-", or for EUR:0.01 the
+name would be "EUR_0_01-") with a postfix that is a truncated
+Crockford32 encoded hash of the various attributes of the denomination
+key (relative validity periods, fee structure and key size). Thus, if
+any attributes of a coin change, the name of the subdirectory will also
+change, even if the denomination remains the same.
+
+Within this subdirectory, each file represents a particular denomination
+key. The filename is the starting time at which the signing key can be
+used in microseconds since the Epoch. The format on disk begins with a
+struct TALER_EXCHANGEDB_DenominationKeyInformationP giving the
+attributes of the denomination key and the associated signature with the
+exchange’s long-term offline key:
+
+::
+
+ struct TALER_EXCHANGEDB_DenominationKeyInformationP {
+ struct TALER_MasterSignatureP signature;
+ struct TALER_DenominationKeyValidityPS properties;
+ };
+
+This is then followed by the variable-size RSA private key in
+libgcrypt’s S-expression format, which can be decoded using
+GNUNET_CRYPTO_rsa_private_key_decode().
+
+.. _Revocations:
+
+Revocations
+~~~~~~~~~~~
+
+When an exchange goes out of business or detects that the private key of
+a denomination key pair has been compromised, it may revoke some or all
+of its denomination keys. At this point, the hashes of the revoked keys
+must be returned as part of the ``/keys`` response under “payback”.
+Wallets detect this, and then return unspent coins of the respective
+denomination key using the ``/payback`` API.
+
+When a denomination key is revoked, a revocation file is placed into the
+respective subdirectory of “denomkeys/”. The file has the same prefix as
+the file that stores the struct
+TALER_EXCHANGEDB_DenominationKeyInformationP information, but is
+followed by the “.rev” suffix. It contains a 64-byte EdDSA signature
+made with the master key of the exchange with purpose
+``TALER_SIGNATURE_MASTER_DENOMINATION_KEY_REVOKED``. If such a file is
+present, the exchange must check the signature and if it is valid treat
+the respective denomination key as revoked.
+
+Revocation files can be generated using the ``taler-exchange-keyup``
+command-line tool using the ``-r`` option. The Taler auditor will
+instruct operators to generate revocations if it detects a key
+compromise (which is possible more coins of a particular denomination
+were deposited than issued).
+
+It should be noted that denomination key revocations should only happen
+under highly unusual (“emergency”) conditions and not under normal
+conditions.
+
+.. _Auditor-signature-storage:
+
+Auditor signature storage
+-------------------------
+
+Signatures from auditors are stored in the directory specified in the
+exchange configuration section "exchangedb" under the option
+"AUDITOR_BASE_DIR". The exchange does not care about the specific names
+of the files in this directory.
+
+Each file must contain a header with the public key information of the
+auditor, the master public key of the exchange, and the number of signed
+denomination keys:
+
+::
+
+ struct AuditorFileHeaderP {
+ struct TALER_AuditorPublicKeyP apub;
+ struct TALER_MasterPublicKeyP mpub;
+ uint32_t dki_len;
+ };
+
+This is then followed by dki_len signatures of the auditor of type
+struct TALER_AuditorSignatureP, which are then followed by another
+dki_len blocks of type struct TALER_DenominationKeyValidityPS. The
+auditor’s signatures must be signatures over the information of the
+corresponding denomination key validity structures embedded in a struct
+TALER_ExchangeKeyValidityPS structure using the
+TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS purpose.
+
+
+.. [1]
+ Naturally, you could operate a Taler exchange for a toy currency
+ without any real value on low-cost setups like a Raspberry Pi, but we
+ urge you to limit the use of such setups to research and education as
+ with GNU Taler data loss instantly results in financial losses.
+
+.. [2]
+ The current implementation does not make provisions for secret
+ splitting. Still, the use of a hardware security module (HSM) for
+ protecting private keys is adviseable, so please contact the
+ developers for HSM integration support.
+
+.. [3]
+ https://api.taler.net/api-exchange.html#wire-req
+