diff options
Diffstat (limited to 'texinfo/taler-exchange.texi')
| -rw-r--r-- | texinfo/taler-exchange.texi | 55 |
1 files changed, 31 insertions, 24 deletions
diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi index ed44281e..4163e74f 100644 --- a/texinfo/taler-exchange.texi +++ b/texinfo/taler-exchange.texi @@ -21,11 +21,11 @@ @copying @quotation -GNU Taler 0.8.0pre0, Jan 27, 2021 +GNU Taler 0.8.0pre0, Apr 26, 2021 GNU Taler team -Copyright @copyright{} 2014-2020 Taler Systems SA (GPLv3+ or GFDL 1.3+) +Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @end quotation @end copying @@ -265,7 +265,7 @@ binary is the @code{taler-exchange-httpd}. @item Crypto-Helpers The @code{taler-exchange-secmod-rsa} and @code{taler-exchange-secmod-eddsa} -are two programs that are responsible for managing the exchange’s +are two programs that are responsible for managing the exchange's online signing keys. They must run on the same machine as the @code{taler-exchange-httpd} as the HTTP frontend communicates with the crypto helpers using UNIX Domain Sockets. @@ -284,7 +284,7 @@ Closer The @code{taler-exchange-closer} tool check that reserves are properly closed. If a customer wires funds to an exchange and then fails to withdraw them, the closer will (eventually) trigger a wire -transfer that sends the customer’s funds back to the originating +transfer that sends the customer's funds back to the originating wire account. @item @@ -325,7 +325,7 @@ the Python bank provides a bank that directly provides the wire adapter API. @item -For production, libeufin’s Nexus component implements a wire +For production, libeufin's Nexus component implements a wire adapter towards the traditional SEPA banking system with IBAN accounts. @end enumerate @@ -362,7 +362,7 @@ copy of the database. The exchange (and ideally also auditors) uses a long-term offline master siging key that identifies the operator and is used to authenticate critical -information, such as the exchange’s bank account and the actual keys the +information, such as the exchange's bank account and the actual keys the exchange uses online. Interactions with the offline system are performed using the @@ -407,7 +407,7 @@ integration support. The UNIX domain sockets have mode 0620 (u+rw, g+w). The exchange process -MUST be in the same group as the the crypto helper processes. +MUST be in the same group as the crypto helper processes. The two helper processes will create the required private keys, and allow anyone with access to the UNIX domain socket to sign arbitrary messages with @@ -421,7 +421,7 @@ expires or if they are informed about a key having been revoked. From a security point of view, the helpers are designed to @emph{only} make it -harder for an attacker who took control of the HTTP daemon’s account to +harder for an attacker who took control of the HTTP daemon's account to extract the private keys, limiting the attackers ability to creating signatures to the duration of their control of that account. @@ -441,8 +441,8 @@ The helper processes should be run under a user ID that is separate from that of the user running the main @code{taler-exchange-httpd} service. For security, it is important that helpers run under a different user ID than the main HTTP frontend, in fact ideally each helper should run under its own user ID. The -@code{taler-exchange-httpd} service’s will securely communicate with the helpers -using UNIX domain sockets. To enable access to the keys, the service’s user +@code{taler-exchange-httpd} service's will securely communicate with the helpers +using UNIX domain sockets. To enable access to the keys, the service's user must be in the group of the helper processes (and no other users should be in that group). @@ -884,9 +884,9 @@ denomination keys (signs electronic coins, see section Coins) security module keys (signs sign keys and denomination keys) @end itemize -Additionally, the exchange is sometimes concerned with the auditor’s public +Additionally, the exchange is sometimes concerned with the auditor's public key (to verify messages signed by auditors approved by the exchange operator) -and the merchant’s public key (to verify refunds are authorized by the +and the merchant's public key (to verify refunds are authorized by the merchant). Key options include: @@ -1003,7 +1003,7 @@ must then have the following options: @item @code{VALUE}: How much is the coin worth, the format is -CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is “EUR:0.10”. +CURRENCY:VALUE.FRACTION. For example, a 10 cent piece is "EUR:0.10". @item @code{DURATION_WITHDRAW}: How long can a coin of this type be withdrawn? @@ -1015,6 +1015,9 @@ key is compromised. values result in lower storage costs for the exchange. @item +@code{DURATION_LEGAL}: How long is the coin of the given type legal? + +@item @code{FEE_WITHDRAW}: What does it cost to withdraw this coin? Specified using the same format as value. @@ -1027,6 +1030,10 @@ the same format as value. the same format as value. @item +@code{FEE_REFUND}: What does it cost to refund this coin? +Specified using the same format as value. + +@item @code{RSA_KEYSIZE}: How many bits should the RSA modulus (product of the two primes) have for this type of coin. @end itemize @@ -1115,7 +1122,7 @@ delayed. @section Terms of Service -The exchange has an endpoint “/terms” to return the terms of service +The exchange has an endpoint "/terms" to return the terms of service (in legal language) of the exchange operator. The wallet will show those terms of service to the user when the user is first withdrawing coins. Terms of service are optional for experimental deployments, @@ -1129,7 +1136,7 @@ in the @code{[exchange]} section: @itemize - @item -@code{TERMS_ETAG}: The current “Etag” to return for the terms of service. +@code{TERMS_ETAG}: The current "Etag" to return for the terms of service. This value must be changed whenever the terms of service are updated. A common value to use would be a version number. Note that if you change the @code{TERMS_ETAG}, you MUST also provide @@ -1143,7 +1150,7 @@ process. The @code{TERMS_DIR} directory structure must follow a particular layout. First, inside of @code{TERMS_DIR}, there should be sub-directories using -two-letter language codes like “en”, “de”, or “jp”. Each of these +two-letter language codes like "en", "de", or "jp". Each of these directories would then hold translations of the current terms of service into the respective language. Empty directories are permitted in case translations are not available. @@ -1165,7 +1172,7 @@ present, the exchange may show a warning on startup. @subsection Example -A sample file structure for a @code{TERMS_ETAG} of “v1” would be: +A sample file structure for a @code{TERMS_ETAG} of "v1" would be: @itemize - @@ -1192,7 +1199,7 @@ TERMS_DIR/de/v1.pdf TERMS_DIR/fr/v1.pdf @end itemize -If the user requests an HTML format with language preferences “fr” followed by “en”, +If the user requests an HTML format with language preferences "fr" followed by "en", the exchange would return @code{TERMS_DIR/en/v1.html} lacking an HTML version in French. @@ -1318,7 +1325,7 @@ The exchange must be informed about any auditor that is expected to provision it with auditor signatures. This is also done using the @code{taler-exchange-offline} tool on the offline system. First, the auditor must be configured and provide the exchange operator with its public key and -the URL of it’s REST API. The exchange operator also needs a human-readable +the URL of it's REST API. The exchange operator also needs a human-readable name that may be shown to users to identify the auditor. Given this information, the exchange operator can enable the auditor: @@ -1575,7 +1582,7 @@ helpful for diagnostics. While an exchange should use an external auditor to attest to regulators that -it is operating correctly, an exchange operator can also use the auditor’s +it is operating correctly, an exchange operator can also use the auditor's logic to perform internal checks. For this, an exchange opeator can generally follow the auditor guide. However, instead of using @code{taler-auditor-sync}, an internal audit can and likely should be performed either directly against @@ -1621,14 +1628,14 @@ The database scheme used by the exchange looks as follows: This chapter describes how to run the Taler exchange benchmark. The benchmark can be used to measure the performance of the exchange by running a (possibly large) number of simulated clients against one Taler deployment with a bank, -exchange and auditor. For the bank, both a “fakebank” (@code{-f}) and a -“Pythonbank” deployment are currently supported. The +exchange and auditor. For the bank, both a "fakebank" (@code{-f}) and a +"Pythonbank" deployment are currently supported. The @code{taler-exchange-benchmark} program can launch all required services and clients, or only launch the parallel clients (@code{-m}), for example for distributed testing over a network. For each @emph{parallel} (@code{-p}) client, a number of @emph{reserves} (@code{-r}) is first established by -@strong{transferring} money from a “user” account (42) to the Exchange’s account +@strong{transferring} money from a "user" account (42) to the Exchange's account with the respective reserve public key as wire subject. Next, the client will @strong{withdraw} a @emph{number of coins} (@code{-n}) from the reserve and @strong{deposit} them. Additionally, a @emph{fraction} (@code{-R}) of the dirty coins will then be @@ -1648,7 +1655,7 @@ You can run a first simple benchmark using: @cartouche @quotation Note FIXME-TTN/CG: these instructions are incomplete and untested for the -current iteration of the code… +current iteration of the code... @end quotation @end cartouche |