From a02fda277f0c7704d71a2f8b38fc2506b68d3df0 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Thu, 17 Dec 2020 15:52:55 +0100 Subject: update taler.conf man page --- manpages/taler.conf.5.rst | 131 +++++++++++++++++++++++++++++----------------- 1 file changed, 83 insertions(+), 48 deletions(-) diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 001dd1fd..98c941d1 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -111,18 +111,11 @@ AGGREGATOR_IDLE_SLEEP_INTERVAL For how long should the aggregator sleep when it is idle before trying to look for more work? Default is 60 seconds. -SIGNKEY_DURATION - For how long is a signing key valid? - -LEGAL_DURATION +SIGNKEY_LEGAL_DURATION For how long are signatures with signing keys legally valid? -LOOKAHEAD_SIGN - How long do we generate denomination and signing keys ahead of time? - -LOOKAHEAD_PROVIDE - How long into the future do we provide signing and denomination keys - to clients? +MAX_KEYS_CACHING + For how long should clients cache ``/keys`` responses at most? TERMS_DIR Directory where the terms of service of the exchange operator can be fund. @@ -159,18 +152,74 @@ PRIVACY_ETAG Works the same as ``TERMS_ETAG``, just for the privacy policy. -EXCHANGE DATABASE OPTIONS -------------------------- +EXCHANGE OFFLINE SIGNING OPTIONS +-------------------------------- -The following options must be in the section "[exchangedb]". +The following options must be in the section "[exchange-offline]". + +EXCHANGE RSA CRYPTO HELPER OPTIONS +------------------------------ + +The following options must be in the section "[taler-helper-crypto-rsa]". + +LOOKAHEAD_SIGN + How long do we generate denomination and signing keys ahead of time? -DURATION_OVERLAP +OVERLAP_DURATION How much should validity periods for coins overlap? Should be long enough to avoid problems with wallets picking one key and then due to network latency another key being valid. The ``DURATION_WITHDRAW`` period must be longer than this value. +SM_PRIV_KEY + Where should the security module store its long-term private key? + +KEY_DIR + Where should the security module store the private keys it manages? + +UNIXPATH + On which path should the security module listen for signing requests? + +Note that the **taler-exchange-helper-rsa** also evaluates the ``[coin-*]`` +configuration sections described below. + + + +EXCHANGE EDDSA CRYPTO HELPER OPTIONS +------------------------------------ + +The following options must be in the section "[taler-helper-crypto-eddsa]". + +LOOKAHEAD_SIGN + How long do we generate denomination and signing keys ahead of time? + +OVERLAP_DURATION + How much should validity periods for coins overlap? + Should be long enough to avoid problems with + wallets picking one key and then due to network latency + another key being valid. The ``DURATION_WITHDRAW`` period + must be longer than this value. + +DURATION + For how long should EdDSA keys be valid for signing? + +SM_PRIV_KEY + Where should the security module store its long-term private key? + +KEY_DIR + Where should the security module store the private keys it manages? + +UNIXPATH + On which path should the security module listen for signing requests? + + + +EXCHANGE DATABASE OPTIONS +------------------------- + +The following options must be in the section "[exchangedb]". + IDLE_RESERVE_EXPIRATION_TIME After which time period should reserves be closed if they are idle? @@ -195,7 +244,8 @@ EXCHANGE ACCOUNT OPTIONS An exchange (or merchant) can have multiple bank accounts. The following options are for sections named “[exchange-account-SOMETHING]”. The ``SOMETHING`` is arbitrary and should be chosen to uniquely identify the bank account for -the operator. +the operator. These options are used by the **taler-exchange-transfer** +and **taler-exchange-wirewatch** tools. PAYTO_URI Specifies the payto://-URL of the account. The general format is @@ -203,6 +253,7 @@ PAYTO_URI ``payto://x-taler-bank/localhost:8899/Exchange`` or ``payto://iban/GENODEF1SLR/DE67830654080004822650/`` or ``payto://iban/DE67830654080004822650/`` (providing the BIC is optional). + Note: only the wire-method is actually used from the URI. WIRE_GATEWAY_URL URL of the wire gateway. Typically of the form @@ -223,49 +274,29 @@ USERNAME PASSWORD Password for ``basic`` authentication with the wire gateway. -WIRE_RESPONSE - Specifies the name of the file in which the /wire response for this - account should be located. Used by the Taler exchange service and the - taler-exchange-wire tool. Example: - ``${TALER_DATA_HOME}/exchange/wire-sigs/SOMETHING.json``. Note that - the file names must differ between all of the exchange bank accounts. - It is suggested to use the section name for ``SOMETHING`` to ensure - uniqueness. - ENABLE_DEBIT Must be set to ``YES`` for the accounts that the - taler-exchange-aggregator and taler-exchange-closer should debit. + **taler-exchange-aggregator** and **taler-exchange-closer** should debit. ENABLE_CREDIT - Must be set to ``YES`` for the accounts that the taler-exchange-wirewatch + Must be set to ``YES`` for the accounts that the **taler-exchange-wirewatch** should check for credits. It is yet uncertain if the merchant implementation may check this flag as well. -EXCHANGE WIRE FEE OPTIONS -------------------------- - -For each supported wire method (i.e. “x-taler-bank” or “sepa”), sections -named “[fees-METHOD]” state the (aggregate) wire transfer fee and the -reserve closing fees charged by the exchange. Note that fees are -specified using the name of the wire method, not by the plugin name. You -need to replace “YEAR” in the option name by the calendar year for which -the fee should apply. Usually, fees should be given for several years -in advance. - -WIRE-FEE-YEAR - Aggregate wire transfer fee merchants are charged in YEAR. Specified - as a Taler amount using the usual amount syntax. - -CLOSING-FEE-YEAR - Reserve closing fee customers are charged in YEAR. Specified as a - Taler amount using the usual amount syntax. - EXCHANGE COIN OPTIONS --------------------- -The following options must be in sections starting with ``"[coin_]"`` and -are used by taler-exchange-keyup to create denomination keys. +The following options must be in sections starting with ``"[coin_]"`` and are +largely used by **taler-exchange-httpd** to determine the meta data for the +denomination keys. Some of the options are used by the +**taler-exchange-helper-rsa** to determine which RSA keys to create (and of +what key length). Note that the section names must match, so this part of the +configuration MUST be shared between the RSA helper and the exchange. +Configuration values MUST NOT be changed in a running setup. Instead, if +parameters for a denomination type are to change, a fresh *section name* should +be introduced (and the existing section should be deleted). + VALUE Value of the coin, e.g. “EUR:1.50” for 1 Euro and 50 Cents (per @@ -390,6 +421,10 @@ DB AUDITOR_PRIV_FILE Name of the file containing the auditor’s private key. +PUBLIC_KEY + Crockford Base32 encoded auditor public key. Used by (online) auditor + processes that do not have access to the (offline) auditor private key file. + AUDITOR POSTGRES BACKEND DATABASE OPTIONS ----------------------------------------- @@ -406,7 +441,7 @@ SEE ALSO ======== taler-exchange-dbinit(1), taler-exchange-httpd(1), -taler-exchange-keyup(1), taler-exchange-wire(1). +taler-exchange-offline(1), taler-auditor-offline(1). BUGS ==== -- cgit v1.2.3