summaryrefslogtreecommitdiff
path: root/taler-exchange.rst
diff options
context:
space:
mode:
Diffstat (limited to 'taler-exchange.rst')
-rw-r--r--taler-exchange.rst869
1 files changed, 0 insertions, 869 deletions
diff --git a/taler-exchange.rst b/taler-exchange.rst
deleted file mode 100644
index 363a8f98..00000000
--- a/taler-exchange.rst
+++ /dev/null
@@ -1,869 +0,0 @@
-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
-