diff options
Diffstat (limited to 'manpages/taler.conf.5.rst')
| -rw-r--r-- | manpages/taler.conf.5.rst | 468 |
1 files changed, 428 insertions, 40 deletions
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst index 3d83b8d4..ee5d3cd1 100644 --- a/manpages/taler.conf.5.rst +++ b/manpages/taler.conf.5.rst @@ -32,7 +32,9 @@ 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. @@ -41,9 +43,6 @@ CURRENCY_ROUND_UNIT Smallest amount in this currency that can be transferred using the underlying RTGS. For example: "EUR:0.01" or "JPY:1". -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". The “[PATHS]” section is special in that it contains paths that can be @@ -70,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 ---------------- @@ -79,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. @@ -161,16 +254,29 @@ PRIVACY_ETAG EXCHANGE KYC PROVIDER OPTIONS ----------------------------- -The following options must be in the section "[kyc-provider-XXX]" sections. +The following options must be in the section "[kyc-provider-$PROVIDER_NAME]" sections. -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. + +CONVERTER + Name of a program to run on the output of the plugin + to convert the result into the desired set of attributes. + The converter must create a log for the system administrator + if the provided inputs do not match expectations. + Note that the converter will be expected to output the + set of attributes listed under the respective ``[kyc-check-*]`` + sections. Calling the converter with ``--list-outputs`` + should generate a (newline-separated) list of attributes + the converter promises to generate in its JSON output + (when run regularly). + +COST + Optional cost, useful if clients want to voluntarily + trigger authentication procedures for attestation. + +Additional logic-specific options may be given in the +section. EXCHANGE KYC OAUTH2 OPTIONS @@ -182,14 +288,14 @@ The following options must be in the section "[kyc-provider-XXX]" sections with KYC_OAUTH2_VALIDITY Duration (e.g. "12 months") of the validity of the performed KYC check. Can be "forever". -KYC_OAUTH2_AUTH_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/auth" (or "/token") +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_LOGIN_URL - URL of the OAuth2 endpoint to be used for KYC checks. The login URL will be encoded as part of the 'redirect_uri' argument of the request to the KYC_AUTH2_AUTH_URL. Typically, the user will then be redirected to this URL to log in. Example: "http://localhost:8888/oauth/v2/login" +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 endpoint where the OAuth 2.0 token can be used to download the user's details. The server 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" + 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. @@ -200,6 +306,15 @@ KYC_OAUTH2_CLIENT_SECRET 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -238,6 +353,9 @@ KYC_PERSONA_SALT 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. @@ -254,6 +372,210 @@ WEBHOOK_AUTH_TOKEN Authentication token Persona must supply to our webhook. This is an optional setting. +EXCHANGE KYC CHECK OPTIONS +-------------------------- + +The following options must be in "[kyc-check-$CHECK_NAME]" sections. + +TYPE + Which type of check is this? Also determines + the SPA form to show to the user for this check. + + * INFO: wait for staff or contact staff out-of band + (only information shown, no SPA action) + * FORM: SPA should show an inline (HTML) form + * LINK: SPA may start external KYC process or upload + +VOLUNTARY + Optional. Set to YES to allow this check be + done voluntarily by a client (they may then + still have to pay for it). Used to offer the + SPA to display checks even if they are + not required. Default is NO. + +PROVIDER_ID + Provider id, present only if type is LINK. + Refers to a ``kyc-provider-$PROVIDER_ID`` section. + +FORM_NAME + Name of the SPA form, if type is FORM + "INFO" and "LINK" are reserved and must not be used. + The exchange server and the SPA must agree on a list + of supported forms and the resulting attributes. + The SPA should include a JSON resource file + "forms.json" mapping form names to arrays of + attribute names each form provides. + The list of possible FORM names is fixed in the SPA + for a particular exchange release. + +DESCRIPTION + Descriptions to use in the SPA to display the check. + +DESCRIPTION_I18N + JSON with internationalized descriptions to use + in the SPA to display the check. + +REQUIRES + ';'-separated list of fields that the CONTEXT must + provide as inputs to this check. For example, + for a FORM of type CHOICE, this might state + ``choices: string[];``. The type after the ":" + is for now purely for documentation and is + not checked. However, it may be shown to AML staff + when they configure measures. + +OUTPUTS = business_name street city country registration + Description of the outputs provided by the check. + Basically, the check's output is expected to + provide the following fields as attribute inputs into + a subsequent AML program. + Only given for type FORM; INFO never has any outputs, + and for type LINK we can obtain the same information + from the CONVERTER via ``--list-outputs``. + +FALLBACK + Name of an **original** measure to take if the check fails + (for any reason, e.g. provider or form fail to + satisfy constraints or provider signals user error) + Usually should point to a measure that requests + AML staff to investigate. The fallback measure + context always includes the reasons for the + failure. + +EXCHANGE KYC RULES +------------------ + +The following options must be in "[kyc-rule-$RULE_NAME]" sections. + +OPERATION_TYPE = WITHDRAW + Operation that triggers this rule. + Must be one of WITHDRAW, DEPOSIT, P2P-RECEIVE + or WALLET-BALANCE. + +NEXT_MEASURES + Space-separated list of next measures to be performed. + The SPA should display *all* of these measures to the user. + (They have a choice of either which ones, or in + which order they are to be performed.) + A special measure name "verboten" is used if the + specified threshold may never be crossed + (under this set of rules). + +IS_AND_COMBINATOR + "YES" if all NEXT_MEASURES will eventually need + to be satisfied, "NO" the user has a choice between + them. Not actually enforced by the exchange, but + primarily used to inform the user whether this is + an "and" or "or". YES for "and". + +EXPOSED + YES if the rule (specifically, operation type, + threshold, timeframe) and the general nature of + the next measure (verboten or approval required) + should be exposed to the client. + Defaults to NO if not set. + +THRESHOLD + Threshold amount above which the rule is + triggered. The total must be exceeded in the given + timeframe. + +TIMEFRAME + Timeframe over which the amount to be compared to + the THRESHOLD is calculated (for example, "30 days"). + Ignored for WALLET-BALANCE. Can be 'forever'. + +ENABLED = NO + Set to YES to enable the rule (default is NO). + + +EXCHANGE AML PROGRAMS +--------------------- + +The following options must be in "[aml-program-$PROG_NAME]" sections. + +COMMAND + Name of the program to run. Must match a binary + on the local machine where the exchange is running. + +DESCRIPTION + Human-readable description of what this + AML helper program will do. Used to show + to the AML staff. + +ENABLED + True if this AML program is enabled (and thus can be + used in measures and exposed to AML staff). + Optional, default is NO. + +FALLBACK + Name of an **original** measure to take if COMMAND fails + Usually points to a measure that asks AML staff + to contact the systems administrator. The fallback measure + context always includes the reasons for the + failure. + +EXCHANGE KYC MEASURES +--------------------- + +The following options must be in "[kyc-measure-$MEASURE_NAME]" sections. These sections define the **original** measures. + +CHECK_NAME + Name of a possible check for this measure. Optional. + If not given, PROGRAM should be run immediately + (on an empty set of attributes). + +CONTEXT = {"choices":["individual","business"]} + Context for the check. The context can be + just an empty JSON object if there is none. + +PROGRAM + Program to run on the context and check data to + determine the outcome and next measure. + Refers to a ``[aml-program-$PROG_NAME]`` section name. + + +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 -------------------------------- @@ -261,7 +583,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 @@ -497,6 +820,11 @@ CIPHER RSA_KEYSIZE 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 ---------------- @@ -507,9 +835,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. @@ -558,25 +901,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 @@ -598,6 +924,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 ----------------------------------------- @@ -621,6 +964,51 @@ 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 ======== |