summaryrefslogtreecommitdiff
path: root/manpages/taler.conf.5.rst
diff options
context:
space:
mode:
Diffstat (limited to 'manpages/taler.conf.5.rst')
-rw-r--r--manpages/taler.conf.5.rst432
1 files changed, 382 insertions, 50 deletions
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
index a671ffd5..3074f68b 100644
--- a/manpages/taler.conf.5.rst
+++ b/manpages/taler.conf.5.rst
@@ -32,11 +32,19 @@ GLOBAL OPTIONS
--------------
The following options are from the “[taler]” section and used by
-virtually all Taler components.
+virtually all Taler components. Note: work is ongoing to obsolete
+these options, but for now they are in use.
+
CURRENCY
Name of the currency, e.g. “EUR” for Euro.
+CURRENCY_ROUND_UNIT
+ Smallest amount in this currency that can be transferred using the
+ underlying RTGS. For example: "EUR:0.01" or "JPY:1".
+
+
+
The “[PATHS]” section is special in that it contains paths that can be
referenced using “$” in other configuration values that specify
filenames. For Taler, it commonly contains the following paths:
@@ -61,6 +69,62 @@ TALER_RUNTIME_DIR
Where should Taler store system runtime data (like UNIX domain
sockets). Usually “${TMP}/taler-system-runtime”.
+
+CURRENCY SPECIFICATIONS
+-----------------------
+
+Sections with a name of the form “[currency-$NAME]” (where "$NAME" could
+be any unique string) are used to specify details about how currencies
+should be handled (and in particularly rendered) by the user interface.
+A detailed motivation for this section can be found in DD51.
+Different components can have different rules for the same currency. For
+example, a bank or merchant may decide to render Euros or Dollars with
+always exactly two fractional decimals, while an Exchange for the same
+currency may support additional decimals. The required options in each
+currency specification section are:
+
+ENABLED
+ Set to YES or NO. If set to NO, the currency specification
+ section is ignored. Can be used to disable currencies or
+ select alternative sections for the same CODE with different
+ choices.
+
+CODE
+ Code name for the currency. Can be at most 11 characters,
+ only the letters A-Z are allowed. Primary way to identify
+ the currency in the protocol.
+
+NAME
+ Long human-readable name for the currency. No restrictions,
+ but should match the official name in English.
+
+FRACTIONAL_INPUT_DIGITS
+ Number of fractional digits that users are allowed to enter
+ manually in the user interface.
+
+FRACTIONAL_NORMAL_DIGITS
+ Number of fractional digits that will be rendered normally
+ (in terms of size and placement). Digits shown beyond this
+ number will typically be rendered smaller and raised (if
+ possible).
+
+FRACTIONAL_TRAILING_ZERO_DIGITS
+ Number of fractional digits to pad rendered amounts with
+ even if these digits are all zero. For example, use 2 to
+ render 1 USD as $1.00.
+
+ALT_UNIT_NAMES
+ JSON map determining how to encode very large or very tiny
+ amounts in this currency. Maps a base10 logarithm to the
+ respective currency symbol. Must include at least an
+ entry for 0 (currency unit). For example, use
+ {"0":"€"} for Euros or "{"0":"$"} for Dollars. You could
+ additionally use {"0":"€","3":"k€"} to render 3000 EUR
+ as 3k€. For BTC a typical map would be
+ {"0":"BTC","-3":"mBTC"}, informing the UI to render small
+ amounts in milli-Bitcoin (mBTC).
+
+
EXCHANGE OPTIONS
----------------
@@ -70,22 +134,60 @@ exchange tools.
DB
Plugin to use for the database, e.g. “postgres”.
+SERVE
+ Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+UNIXPATH
+ Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+ Access permission mask to use for the "UNIXPATH".
+
PORT
Port on which the HTTP server listens, e.g. 8080.
+BIND_TO
+ Hostname to which the exchange HTTP server should be bound to, e.g. "localhost".
+
MASTER_PUBLIC_KEY
Crockford Base32-encoded master public key, public version of the
- exchange's long-time offline signing key.
+ exchange's long-time offline signing key. This configuration option
+ is also used by the **auditor** to determine the public key of the
+ exchange which it is auditing.
-MASTER_PRIV_FILE
- Location of the master private key on disk. Only used by tools that
- can be run offline (as the master key is for offline signing).
+AML_THRESHOLD
+ Largest amount in this currency that can be transferred per month without
+ an AML staff member doing a (manual) AML check. For example: "USD:1000000".
+
+KYC_AML_TRIGGER
+ Program to run on KYC attribute data to decide whether we should immediately flag an account for AML review. Program must return 0 if a manual AML review is not needed, and non-zero to trigger an AML review. The KYC attribute data of the new user will be passed on standard-input.
+
+STEFAN_ABS
+ Absolute amount to add as an offset in the STEFAN fee approximation
+ curve (see DD47). Defaults to CURRENCY:0 if not specified.
+
+STEFAN_LOG
+ Amount to multiply by the base-2 logarithm of the total amount
+ divided by the amount of the smallest denomination
+ in the STEFAN fee approximation curve (see DD47).
+ Defaults to CURRENCY:0 if not specified.
+
+STEFAN_LIN
+ Linear floating point factor to be multiplied by the total amount
+ to use in the STEFAN fee approximation curve (see DD47).
+ Defaults to 0.0 if not specified.
BASE_URL
The base URL under which the exchange can be reached.
Added to wire transfers to enable tracking by merchants.
Used by the KYC logic when interacting with OAuth 2.0.
+TOPLEVEL_REDIRECT_URL
+ Where to redirect visitors that access the top-level
+ "/" endpoint of the exchange. Should point users to
+ information about the exchange operator.
+ Optional setting, defaults to "/terms".
+
AGGREGATOR_IDLE_SLEEP_INTERVAL
For how long should the taler-exchange-aggregator sleep when it is idle
before trying to look for more work? Default is 60 seconds.
@@ -148,48 +250,158 @@ PRIVACY_DIR
PRIVACY_ETAG
Works the same as ``TERMS_ETAG``, just for the privacy policy.
-KYC_MODE
- Set to "NONE" to disable KYC for this exchange (but check with your lawyer first).
- Set to "OAUTH2" to use OAuth2 for KYC.
-KYC_WITHDRAW_LIMIT
- Maximum amount that can be withdrawn in
- KYC_WITHDRAW_PERIOD without needing KYC.
- Only used if KYC_MODE is not "NONE".
+EXCHANGE KYC PROVIDER OPTIONS
+-----------------------------
-KYC_WITHDRAW_PERIOD
- The time period over which transactions
- are considered for the KYC_WITHDRAW_LIMIT.
- Only used if KYC_MODE is not "NONE".
+The following options must be in the section "[kyc-provider-XXX]" sections.
-KYC_WALLET_BALANCE_LIMIT
- Maximum amount that a wallet is allowed to hold without
- having to undergo the KYC process of the issuing
- exchange. Optional option, if not given there
- is no limit.
+COST
+ Relative cost of the KYC provider, non-negative number.
+
+LOGIC
+ API type of the KYC provider.
+
+USER_TYPE
+ Type of user this provider is for, either INDIVIDUAL or BUSINESS.
+
+PROVIDED_CHECKS
+ List of checks performed by this provider. Space-separated names of checks, must match check names in legitimization rules.
EXCHANGE KYC OAUTH2 OPTIONS
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The following options must be in the section "[exchange-kyc-oauth2]".
+The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = oauth2".
-KYC_OAUTH2_URL
- URL of the OAuth2 endpoint to be used for KYC checks. Requires KYC_ENABLED to be "OAUTH2". Example: "http://localhost:8888/oauth/v2/login"
+KYC_OAUTH2_VALIDITY
+ Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
-KYC_INFO_URL
- URL of the endpoint where the OAuth 2.0 token can be used to download the user's details. Requires KYC_ENABLED to be "OAUTH2". Example: "http://localhost:8888/api/user/me"
+KYC_OAUTH2_AUTHORIZE_URL
+ URL of the OAuth2 endpoint to be used for KYC checks. The authorize URL is where the exchange will redirect the client to begin the authorization process. Example: "http://localhost:8888/oauth/v2/authorize". To use the plugin in combination with the Challenger service's ``/setup`` step, append "#setup", thus "https://challenger.example.com/authorize#setup". Here, "#setup" is not a fragment but merely a hint to the logic to determine the full authorization URL via the ``/setup/$CLIENT_ID`` handler.
+
+KYC_OAUTH2_TOKEN_URL
+ URL of the OAuth2 endpoint to be used for KYC checks. This is where the server will ultimately send the authorization token from the client and obtain its access token (which currently must be a "bearer" token). Example: "http://localhost:8888/oauth/v2/token" (or just "/token")
+
+KYC_OAUTH2_INFO_URL
+ URL of the OAuth2-protected resource endpoint, where the OAuth 2.0 token can be used to download information about the user that has undergone the KYC process. The exchange will use the access token obtained from the KYC_AUTH2_AUTH_URL to show that it is authorized to obtain the details. Example: "http://localhost:8888/api/user/me" or "http://localhost:8888/oauth/v2/info"
KYC_OAUTH2_CLIENT_ID
- Client ID of the exchange when it talks to the KYC OAuth2 endpoint. Requires KYC_ENABLED to be "OAUTH2".
+ Client ID of the exchange when it talks to the KYC OAuth2 endpoint.
KYC_OAUTH2_CLIENT_SECRET
- Client secret of the exchange to use when talking to the KYC Oauth2 endpoint. Requires KYC_ENABLED to be "OAUTH2".
+ Client secret of the exchange to use when talking to the KYC Oauth2 endpoint.
KYC_OAUTH2_POST_URL
+ URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process. Example: "http://example.com/thank-you"
+
+KYC_OAUTH2_CONVERTER_HELPER
+ Helper to convert JSON with KYC data returned by the OAuth2.0 info endpoint into GNU Taler internal format. Specific to the OAuth 2.0 provider.
+
+KYC_OAUTH2_DEBUG_MODE
+ Set to YES to allow error responses to include potentially
+ sensitive private information (such as full responses
+ from the OAuth 2.0 server) that might aid in debugging
+ problems. Should be set to "NO" in production.
+
+
+EXCHANGE KYC KYCAID OPTIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = kycaid".
+
+
+KYC_KYCAID_VALIDITY
+ Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
+
+KYC_KYCAID_AUTH_TOKEN
+ Authentication token to access the KYC service.
+
+KYC_KYCAID_FORM_ID
+ ID that specifies the form to use for the KYC process.
+
+KYC_KYCAID_POST_URL
+ URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process.
+
+
+EXCHANGE KYC PERSONA OPTIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following options must be in the section "[kyc-provider-XXX]" sections with "LOGIC = persona".
+
+
+KYC_PERSONA_VALIDITY
+ Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever".
+
+KYC_PERSONA_AUTH_TOKEN
+ Authentication token to access the KYC service.
+
+KYC_PERSONA_SALT
+ Salt value to use for request idempotency. Optional, generated at random per process if not given.
+
+KYC_PERSONA_SUBDOMAIN
+ Subdomain to use under Persona.
+
+KYC_PERSONA_CONVERTER_HELPER
+ Helper to convert JSON with KYC data returned by Persona into GNU Taler internal format. Should probably always be set to "taler-exchange-kyc-persona-converter.sh".
+
+KYC_PERSONA_POST_URL
URL to which the exchange will redirect the client's browser after successful authorization/login for the KYC process.
+KYC_PERSONA_TEMPLATE_ID
+ ID of the Persona template to use.
+
+EXCHANGE KYC PERSONA GLOBAL OPTIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following option must be in the section "[kyclogic-persona]".
+
+
+WEBHOOK_AUTH_TOKEN
+ Authentication token Persona must supply to our webhook. This is an optional setting.
+
+
+EXCHANGE EXTENSIONS OPTIONS
+---------------------------
+
+The functionality of the exchange can be extended by extensions. Those are
+shared libraries which implement the extension-API of the exchange and are
+located under ``$LIBDIR``, starting with prefix ``libtaler_extension_``. Each
+extension can be enabled by adding a dedicated section
+"[exchange-extension-<extensionname>]" and the following option:
+
+ENABLED
+ If set to ``YES`` the extension ``<extensionsname>`` is enabled. Extension-specific
+ options might be set in the same section.
+
+
+EXCHANGE EXTENSION FOR AGE RESTRICTION
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The extension for age restriction support can be enabled by adding a section
+"[exchange-extension-age_restriction]" with the following options:
+
+ENABLE
+ Must be set to ``YES`` in order to activate the extension.
+
+AGE_GROUPS
+ A colon-seperated string of increasing non-negative integers, defining the
+ buckets of age groups supported by the exchange. Each integer marks the
+ beginning of the next age group. The zero'th age group implicitly starts
+ with 0. For example, the string "10:18" would define three age groups:
+
+ 1. Group 0: ages 0 through 9 (including)
+ 2. Group 1: ages 10 through 17 (including)
+ 3. Group 2: ages 18 and above
+
+ If not provided, the default value is "8:10:12:14:16:18:21".
+
+**Note**: Age restriction is bound to specific denominations and must be
+enabled for each selected denomination in the corresponding section by adding
+the option ``AGE_RESTRICTED = YES``, see `EXCHANGE COIN OPTIONS`_. However, the
+age groups are defined globally for all denominations.
+
EXCHANGE OFFLINE SIGNING OPTIONS
@@ -198,7 +410,8 @@ EXCHANGE OFFLINE SIGNING OPTIONS
The following options must be in the section "[exchange-offline]".
MASTER_PRIV_FILE
- Where to store the offline private key of the exchange.
+ Location of the master private key on disk. Only used by tools that
+ can be run offline (as the master key is for offline signing).
Mandatory.
SECM_TOFU_FILE
@@ -247,6 +460,34 @@ Note that the **taler-exchange-secmod-rsa** also evaluates the ``[coin_*]``
configuration sections described below.
+EXCHANGE CS CRYPTO HELPER OPTIONS
+---------------------------------
+
+The following options must be in the section "[taler-exchange-secmod-cs]".
+
+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.
+
+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-secmod-cs** also evaluates the ``[coin_*]``
+configuration sections described below.
+
+
EXCHANGE EDDSA CRYPTO HELPER OPTIONS
------------------------------------
@@ -288,6 +529,14 @@ IDLE_RESERVE_EXPIRATION_TIME
LEGAL_RESERVE_EXPIRATION_TIME
After what time do we forget about (drained) reserves during garbage collection?
+AGGREGATOR_SHIFT
+ Delay between a deposit being eligible for aggregation and
+ the aggregator actually triggering.
+
+DEFAULT_PURSE_LIMIT
+ Number of concurrent purses that a reserve may have active
+ if it is paid to be opened for a year.
+
EXCHANGE POSTGRES BACKEND DATABASE OPTIONS
------------------------------------------
@@ -390,8 +639,19 @@ FEE_REFUND
What fee is charged for refunds? When a coin is refunded, the deposit
fee is returned. Instead, the refund fee is charged to the customer.
+CIPHER
+ What cryptosystem should be used? Must be set to either "CS" or "RSA".
+ The respective crypto-helper will then generate the keys for this
+ denomination.
+
RSA_KEYSIZE
- What is the RSA keysize modulos (in bits)?
+ What is the RSA keysize modulos (in bits)? Only used if "CIPHER=RSA".
+
+AGE_RESTRICTED
+ Setting this option to ``YES`` marks the denomination as age restricted
+ (default is ``NO``). For this option to be accepted the extension for age
+ restriction MUST be enabled (see `EXCHANGE EXTENSION FOR AGE RESTRICTION`_).
+
MERCHANT OPTIONS
----------------
@@ -402,9 +662,24 @@ merchant backend.
DB
Plugin to use for the database, e.g._“postgres”.
+SERVE
+ Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+BASE_URL
+ Which base URL should the merchant backend assume for itself in the protocol. Optional. If not given, the base URL will be constructed from X-Forwarded-Host, X-Forwarded-Port and X-Forwarded-Prefix headers that a reverse-proxy should be setting.
+
+UNIXPATH
+ Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+ Access permission mask to use for the "UNIXPATH".
+
PORT
Port on which the HTTP server listens, e.g. 8080.
+BIND_TO
+ Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
+
LEGAL_PRESERVATION
How long do we keep data in the database for tax audits after the
transaction has completed? Default is 10 years.
@@ -453,25 +728,8 @@ CURRENCY
The entire section is ignored if the currency does not match the currency
we use, which must be given in the ``[taler]`` section.
-KNOWN AUDITORS (for merchants)
-------------------------------
-
-The merchant configuration can include a list of known exchanges if the
-merchant wants to specify that certain auditors are explicitly trusted.
-For each trusted exchange, a section “[merchant-auditor-$NAME]” must exist, where
-``$NAME`` is a merchant-given name for the auditor. The following options
-must be given in each “[merchant-auditor-$NAME]” section.
-
-AUDITOR_BASE_URL
- Base URL of the auditor, e.g. “https://auditor.demo.taler.net/”
-
-AUDITOR_KEY
- Crockford Base32 encoded auditor public key.
-
-CURRENCY
- Name of the currency for which this auditor is trusted, e.g. “KUDOS”
- The entire section is ignored if the currency does not match the currency
- we use, which must be given in the ``[taler]`` section.
+DISABLED
+ Set to YES to disable this exchange. Optional option, defaults to NO.
AUDITOR OPTIONS
@@ -493,6 +751,23 @@ PUBLIC_KEY
BASE_URL
Base URL of the auditor, e.g. “https://auditor.demo.taler.net/”
+SERVE
+ Should the HTTP server listen on a UNIX domain socket (set option to "unix") or on a TCP socket (set option to "tcp")?
+
+UNIXPATH
+ Path to listen on if we "SERVE" is set to "unix".
+
+UNIXPATH_MODE
+ Access permission mask to use for the "UNIXPATH".
+
+PORT
+ Port on which the HTTP server listens, e.g. 8080.
+
+BIND_TO
+ Hostname to which the merchant HTTP server should be bound to, e.g. "localhost".
+
+
+
AUDITOR POSTGRES BACKEND DATABASE OPTIONS
-----------------------------------------
@@ -505,6 +780,63 @@ CONFIG
"taler" database. Testcases use “talercheck”.
+Bank Options
+------------
+
+The following options must be in section "[bank]" for the taler-fakebank-run(1) command. They are not used by the exchange or LibEuFin!
+
+HTTP_PORT
+ On which TCP port should the (fake)bank offer its REST API.
+RAM_LIMIT
+ This gives the number of transactions to keep in memory. Older transactions will be overwritten and history requests for overwritten transactions will fail.
+
+
+Taler-mdb Options
+-----------------
+
+Taler-mdb is a component to run GNU Taler as a payment system on
+vending machines using the multi-drop bus protocol. These options
+are thus not useful for most users. Note that right now, the
+cancel button is hard-coded to be using GPIO pin 23.
+
+ADVERTISEMENT_COMMAND
+ Program to run while not vending, possibly useful to show advertisements on the screen (optional).
+ESSID
+ ESSID to advertise to wallets for use as an open WiFi to make payments (optional).
+FULFILLMENT_MSG
+ Message shown to users by their wallets upon successful payment. If "${PRODUCT_DESCRIPTION}" appears in the message, it will be replaced with the description of the product that was sold.
+BACKEND_BASE_URL
+ Base URL (possibly including instance) for the Taler merchant backend used to process payments.
+BACKEND_AUTHORIZATION
+ Full HTTP "Authorization" header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Mandatory.
+FRAMEBUFFER_BACKLIGHT
+ Name of the file used to control brightness of the display. Optional. Defaults to "/sys/class/backlight/soc:backlight/brightness" if not given.
+FRAMEBUFFER_DEVICE
+ Name of the framebuffer device to use. Defaults to "/dev/fb1" if not given.
+UART_DEVICE
+ Name of the UART device to use. Defaults to "/dev/ttyAMA0" if not given.
+FAIL_COMMAND
+ Command to run to display a failure to the user. If not given, errors will not be properly shown.
+
+Each products being sold must be configured in a section where the name starts with "product-".
+In these sections, the options that must be provided are:
+
+NUMBER
+ Number identifying the slot in the vending machine that corresponds to this product.
+INSTANCE
+ Instance to use for the payment. Optional. If not given, the BACKEND_BASE_URL from "[taler-mdb]" will be used.
+BACKEND_AUTHORIZATION
+ Full HTTP "Authorization" header (usually with a Bearer token) to be send to the merchant backend for authorization of requests. Optional, will use global BACKEND_AUTHORIZATION setting from "[taler-mdb]" if missing.
+DESCRIPTION
+ Human-readable description of the product. Use "empty" if the product is known to be sold out (only effective if selling out is enabled via command-line).
+PRICE
+ Actual price of the product, as a Taler amount ("$CURRENCY:$VALUE.$FRACTION").
+KEY
+ Key used to select the product from the console during testing. Optional.
+THUMBNAIL
+ Name of a filename with a preview image of the product to be given to the wallet. Optional. Only ".png", ".jpg", ".jpeg" and ".svg" are supported at this time.
+
+
SEE ALSO
========