From 4b82b7c171068c4722f10855391b9ca3a6ea20a9 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Thu, 29 Aug 2019 13:32:36 +0200 Subject: texinfo support --- taler-exchange.rst | 869 ----------------------------------------------------- 1 file changed, 869 deletions(-) delete mode 100644 taler-exchange.rst (limited to 'taler-exchange.rst') 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-' 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-' 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 = - - # 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 - -- cgit v1.2.3