src/config.ml

@@ -25,16 +25,12 @@ type payto_uri = string
    some maybe are relevant
    idk *)
 type not_relevant
-type not_implemented
 type url = string
 type seconds = int
 
 (* not relevant for mirage *)
-(*
+(* this contains path that can be referenced in other with $PATH
-The “[PATHS]” section is special in that it contains paths that can be
+   (unsupported) *)
-referenced using “$” in other configuration values that specify
-filenames. For Taler exchange, it commonly contains the following paths:
-  *)
 module type Global = sig
   val taler_home : dir_path
   val taler_data_home : dir_path
@@ -47,256 +43,57 @@ end
    see DD51 *)
 module type Currency = sig
   val enabled : [ `YES | `NO ]
-
-  (* at most 11 characters, only A-Z *)
   val code : string
-
-  (* official name in English *)
   val name : string
   val fractional_input_digits : int
   val fractional_normal_digits : int
   val fractional_trailing_zero_digits : int
-
-  (*
-  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). *)
   val alt_unit_names : (int * string) list
 end
 
 (* section "[exchange]" *)
 module type Exchange = sig
-  (*
-  Name of the currency, e.g. “EUR” for Euro. *)
   val currency : string
-
-  (*
-  Smallest amount in this currency that can be transferred using the
-  underlying RTGS. For example: "EUR:0.01" or "JPY:1". *)
   val currency_round_unit : amount
-
-  (*
-  Plugin to use for the database, e.g. “postgres”. *)
   val db : string
-
-  (*
-  Attribute encryption key for storing attributes encrypted
-  in the database. Should be a high-entropy nonce. *)
   val attribute_encryption_key : string
-
-  (*
-  Should the HTTP server listen on a UNIX domain socket (set option to "unix"), or on a TCP socket (set option to "tcp"), or be activated via systemd (set option to "systemd"). *)
   val serve : [ `Unix | `Tcp | `Systemd ]
-
-  (*
-  Path to listen on if we "SERVE" is set to "unix". *)
   val unixpath : file_path
-
-  (*
-  Access permission mask to use for the "UNIXPATH". *)
   val unixpath_mode : int
-
-  (*
-  Port on which the HTTP server listens, e.g. 8080. *)
   val port : int
-
-  (*
-  Hostname to which the exchange HTTP server should be bound to, e.g. "localhost". *)
   val bind_to : string
-
-  (*
-  Crockford Base32-encoded master public key, public version of the
-  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. *)
   val master_public_key : string
-
-  (*
-  Small amount that can be transferred to the exchange for the
-  KYC authentication wire transfers. Should be given as a hint
-  for merchants what amount they need to transfer to begin the
-  KYC transfer. Note that the amount is not enforced by the
-  exchange *and* that this option is optional. However, if it is
-  not given, merchants will have to guess what amount to transfer,
-  so it really should be configured. *)
   val tiny_amount : amount option
-
-  (*
-  Web URL where users can discover shops that accept digital cash
-  offered by this exchange. Optional, but highly recommended. *)
   val shopping_url : url option
-
-  (*
-  URL where wallets can find an open banking gateway to
-  initiate wire transfers when withdrawing digital cash
-  from this exchange. Optional (as obviously not every
-  exchange will have an open banking gateway attached). *)
   val open_banking_gateway_url : url option
-
-  (*
-  Determines the variant of the AML SPA that should be shown. This
-  will determine the set of forms shown to AML staff, statistics to
-  be displayed on the main page, and influence the default set of
-  properties/events the AML forms show when AML staff makes decisions.
-  Possible values for now include "gls", "tops" and "magnet".
-  Optional. The AML SPA will only show certain default forms and
-  generic decisions if this option is not set. *)
   val aml_spa_dialect : string option
-
-  (*
-  Determines the legal language (and possibly other UI/UX aspects)
-  wallets should use when providing the user interface for this bank.
-  Allows banks to communicate the desired compliance language they
-  want to see used to the wallet. Wallets SHOULD follow the guidance
-  provided by the bank, but some wallets MAY not understand all compliance
-  languages. Optional, if not set wallets will use their default UI/UX. *)
   val bank_compliance_language : string option
-
-  (*
-  Absolute amount to add as an offset in the STEFAN fee approximation
-  curve (see DD47).  Defaults to CURRENCY:0 if not specified. *)
   val stefan_abs : amount
-
-  (*
-  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. *)
   val stefan_log : amount
-
-  (*
-  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. *)
   val stefan_lin : float
-
-  (*
-  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. *)
   val base_url : 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". *)
   val toplevel_redirect_url : string option
-
-  (*
-  For how long should the taler-exchange-aggregator sleep when it is idle
-  before trying to look for more work? Default is 60 seconds. *)
   val aggregator_idle_sleep_interval : seconds
-
-  (*
-  For how long should the taler-exchange-closer sleep when it is idle
-  before trying to look for more work? Default is 60 seconds. *)
   val closer_idle_sleep_interval : seconds
-
-  (*
-  For how long should the taler-exchange-transfer sleep when it is idle
-  before trying to look for more work? Default is 60 seconds. *)
   val transfer_idle_sleep_interval : seconds
-
-  (*
-  For how long should the taler-exchange-wirewatch sleep when it is idle
-  before trying to look for more work? Default is 60 seconds. *)
   val wirewatch_idle_sleep_interval : seconds
-
-  (*
-  Which share of the range from [0,..2147483648] should be processed by one of the shards of the aggregator. Useful only for Taler exchanges with ultra high-performance needs. When changing this value, you must stop all aggregators and run "taler-exchange-dbinit -s" before resuming. Default is 2147483648 (no sharding). *)
   val aggregator_shard_size : int option
-
-  (*
-  For how long are signatures with signing keys legally valid? *)
   val signkey_legal_duration : duration
-
-  (*
-  For how long should clients cache ``/keys`` responses at most? *)
   val max_keys_caching : duration
-
-  (*
-  How many requests should the HTTP server process at most before committing suicide? *)
   val max_requests : int
-
-  (*
-  Directory where the terms of service of the exchange operator can be fund.
-  The directory must contain sub-directories for every supported language,
-  using the two-character language code in lower case, e.g. "en/" or "fr/".
-  Each subdirectory must then contain files with the terms of service in
-  various formats.  The basename of the file of the current policy must be
-  specified under ``TERMS_ETAG``.  The extension defines the mime type.
-  Supported extensions include "html", "htm", "txt", "pdf", "jpg", "jpeg",
-  "png" and "gif".  For example, using a ``TERMS_ETAG`` of "0", the structure
-  could be the following:
-
-  - $TERMS_DIR/en/0.pdf
-  - $TERMS_DIR/en/0.html
-  - $TERMS_DIR/en/0.txt
-  - $TERMS_DIR/fr/0.pdf
-  - $TERMS_DIR/fr/0.html
-  - $TERMS_DIR/de/0.txt *)
   val terms_dir : dir_path
-
-  (*
-  Basename of the file(s) in the ``TERMS_DIR`` with the current terms of service.
-  The value is also used for the "Etag" in the HTTP request to control
-  caching.  Whenever the terms of service change, the ``TERMS_ETAG`` MUST also
-  change, and old values MUST NOT be repeated.  For example, the date or
-  version number of the terms of service SHOULD be used for the Etag.  If
-  there are minor (e.g. spelling) fixes to the terms of service, the
-  ``TERMS_ETAG`` probably SHOULD NOT be changed. However, whenever users must
-  approve the new terms, the ``TERMS_ETAG`` MUST change. *)
   val terms_etag : string
-
-  (*
-  Works the same as ``TERMS_DIR``, just for the privacy policy. *)
   val privacy_dir : dir_path
-
-  (*
-  Works the same as ``TERMS_ETAG``, just for the privacy policy. *)
   val privacy_etag : string
-
-  (*
-  Must be set to ``YES`` to enable AML/KYC rule enforcement. Note that the administrative endpoints will always work, even if the flag is set to ``NO``. *)
   val enable_kyc : [ `YES | `NO ]
 end
 
 (* section "[taler-exchange-secmod-{rsa|cs|eddsa}]". *)
 module type Secmod = sig
-  (*
-  How long do we generate denomination and signing keys ahead of time?
-  *)
   val lookahead_sign : 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.
-  *)
   val overlap_duration : duration
-
-  (*
-  Where should the security module store its long-term private key?
-  *)
   val sm_priv_key : file_path
-
-  (*
-  Where should the security module store the private keys it manages?
-  *)
   val key_dir : dir_path
-
-  (*
-  On which path should the security module listen for signing requests?
-  *)
   val unixpath : not_relevant
 end
 
@@ -304,55 +101,23 @@ module type Secmod_rsa = Secmod
 module type Secmod_cs = Secmod
 module type Secmod_eddsa = Secmod
 
+(* TODO config
+   what is the time/duration unit used here? *)
 (* section "[exchangedb]". *)
 module type Database = sig
-  (* TODO not sure about what unit of time/duration is used in here *)
-
-  (*
-  After which time period should reserves be closed if they are idle? *)
   val idle_reserve_expiration_time : seconds
-
-  (*
-  After what time do we forget about (drained) reserves during garbage collection? *)
   val legal_reserve_expiration_time : seconds
-
-  (*
-  Delay between a deposit being eligible for aggregation and
-  the aggregator actually triggering. *)
   val aggregator_shift : seconds
-
-  (*
-  Number of concurrent purses that a reserve may have active
-  if it is paid to be opened for a year. *)
   val default_purse_limit : int
-
-  (*
-  Maximum time an AML program is allowed to run.
-  (Optional for taler-auditor.) *)
   val max_aml_program_runtime : int option
 
-  (*
-The following options must be in section “[exchangedb-postgres]” if the
-“postgres” plugin was selected for the database. *)
   module type Postgres_backend = sig
-    (*
-  How to access the database, e.g. “postgres:///taler-exchange” to use the
-  “taler-exchange” database. Testcases use “talercheck”. *)
     val config : string
   end
 end
 
-(*
+(* sections "[coin_XXX]"
-The following options must be in sections starting with ``"[coin_]"`` and are
+   used by secmods *)
-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-secmod-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).
-*)
 module type Coin = sig
   val value : amount
   val duration_withdraw : duration
@@ -362,35 +127,24 @@ module type Coin = sig
   val fee_deposit : amount
   val fee_refresh : amount
   val fee_refund : amount
-
-  (*
-   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. *)
   val cipher : [ `CS | `RSA ]
-
+  val rsa_keysize : int option (*only if `RSA *)
-  (*What is the RSA keysize modulos (in bits)?  Only used if "CIPHER=RSA".*)
-  val rsa_keysize : int
-
-  (*
-   For this option to be accepted the extension for age
-   restriction MUST be enabled. *)
   val age_restricted : [ (*`YES|*) `NO ]
 end
 
-(*
+(* sections "[exchange-account-XXX]" *)
-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.  These options are used by the **taler-exchange-aggregator**, **taler-exchange-closer**, **taler-exchange-transfer** and **taler-exchange-wirewatch** tools. *)
 module type Account = sig
   val payto_uri : payto_uri
   val enable_debit : [ `YES | `NO ]
   val enable_credit : [ `YES | `NO ]
 end
 
-(*
+(* sections "[exchange-accountcredentials-XXX]"
-Additionally, for each enabled account there MUST be another matching section named “[exchange-accountcredentials-SOMETHING]”.  This section SHOULD be in a ``secret/`` configuration file that is only readable for the **taler-exchange-wirewatch** and **taler-exchange-transfer** processes. It contains the credentials to access the bank account: *)
+   must exists for each "[exchange-account-XXX]" section
+
+   ! credentials to access the bank account
+   should be in a secret configuration file
+   only redable for `taler-exchange-wirewatch` `taler-exchange-transfer` processes *)
 module type Account_secret = sig
   val wire_gateway_url : url
   val wire_gateway_auth_method : string
@@ -399,49 +153,20 @@ module type Account_secret = sig
   val token : string
 end
 
-(*
+(* section "[exchange-extension-<extensionname>]" *)
-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:
-  *)
 module type Extensions = sig
-  (*
-  If set to ``YES`` the extension ``<extensionsname>`` is enabled.  Extension-specific
-  options might be set in the same section. *)
   val enabled : [ (*`YES|*) `NO ]
 end
 
-(* The following options must be in the section "[exchange-offline]". *)
+(* section "[exchange-offline]". *)
 module type Offline_signing = sig
-  (*
-  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. *)
   val master_priv_file : file_path
 
   (* TODO
-   - we need two different file
+   - we need two different file here
    - there is three, not two, crypto helper modules
      is it only two, because the eddsa one is not comptabilized as a "crypto helper" here? *)
-  (*
-  Where to store the public keys of both crypto helper modules.
-  Used to persist the keys after the first invocation of the tool,
-  so that if they ever change in the future, this is detected and
-  the tool can abort.
-  Mandatory. *)
   val secm_tofu_file : file_path
-
-  (*
-  Public key of the (RSA) crypto helper module. Optional. If not given,
-  we will rely on TOFU.  Note that once TOFU has been established,
-  this option will also be ignored. *)
   val secm_denom_pubkey : string option
-
-  (*
-  Public key of the (EdDSA) crypto helper module. Optional. If not given,
-  we will rely on TOFU.  Note that once TOFU has been established,
-  this option will also be ignored. *)
   val secm_esign_pubkey : string option
 end