diff options
Diffstat (limited to 'texinfo/taler-exchange.texi')
| -rw-r--r-- | texinfo/taler-exchange.texi | 94 |
1 files changed, 50 insertions, 44 deletions
diff --git a/texinfo/taler-exchange.texi b/texinfo/taler-exchange.texi index b953b187..b6104ffd 100644 --- a/texinfo/taler-exchange.texi +++ b/texinfo/taler-exchange.texi @@ -21,7 +21,7 @@ @copying @quotation -GNU Taler 0.8.0pre0, Apr 28, 2021 +GNU Taler 0.8.0pre0, Aug 03, 2021 GNU Taler team @@ -53,14 +53,14 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @c Copyright (C) 2014-2020 Taler Systems SA @c @c TALER is free software; you can redistribute it and/or modify it under the -@c terms of the GNU General Public License as published by the Free Software +@c terms of the GNU Affero General Public License as published by the Free Software @c Foundation; either version 2.1, or (at your option) any later version. @c @c TALER is distributed in the hope that it will be useful, but WITHOUT ANY @c WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR -@c A PARTICULAR PURPOSE. See the GNU General Public License for more details. +@c A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. @c -@c You should have received a copy of the GNU General Public License along with +@c You should have received a copy of the GNU Affero General Public License along with @c TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> @c @c @author Christian Grothoff @@ -209,6 +209,15 @@ packages. You need to understand the cryptographic concepts of private and public keys and must be able to protect private keys stored in files on disk. +@cartouche +@quotation Note +The Taler merchant backend stores private keys and other sensitive +business and customer data in the database. The backend operator +SHOULD ensure that backup operations are encrypted and secured from +unauthorized access. +@end quotation +@end cartouche + @node Architecture overview,Offline keys,Organizational prerequisites,Introduction @anchor{taler-exchange-manual architecture-overview}@anchor{6} @section Architecture overview @@ -265,7 +274,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 +293,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 +334,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 +371,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 @@ -421,7 +430,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 +450,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). @@ -599,23 +608,30 @@ Pin-Priority: 1000 @end example A typical @code{/etc/apt/sources.list} file for this setup -would look like this: +which combines Debian stable with more recent packages +from testing and unstable would look like this: @example deb http://ftp.ch.debian.org/debian/ buster main deb http://security.debian.org/debian-security buster/updates main deb http://ftp.ch.debian.org/debian/ testing main deb http://ftp.ch.debian.org/debian/ unstable main -deb https://deb.taler.net/apt/debian sid main @end example -The last line is crucial, as it adds the GNU Taler packages. +Naturally, you may want to use different mirrors depending on your region. +Additionally, you must add a file to import the GNU Taler packages. Typically, +this is done by adding a file @code{/etc/apt/sources.list.d/taler.list} that +looks like this: + +@example +deb https://deb.taler.net/apt/debian sid main +@end example Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists: @example -# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-key add - +# wget -O - https://taler.net/taler-systems.gpg.key | apt-key add - # apt update @end example @@ -631,7 +647,7 @@ using apt. To install the Taler exchange, you can now simply run: @example -# apt install taler-exchange +# apt install -t sid taler-exchange @end example Note that the package does not perform any configuration work except for @@ -652,20 +668,10 @@ To install the GNU Taler Ubuntu packages, first ensure that you have the right Ubuntu distribution. At this time, the packages are built for Ubuntu 20.04 LTS (Focal Fossa). -A typical @code{/etc/apt/sources.list} file for this setup +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup would look like this: @example -deb http://ch.archive.ubuntu.com/ubuntu/ focal main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security main restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security universe restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal multiverse restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-updates multiverse restricted -deb http://ch.archive.ubuntu.com/ubuntu/ focal-security multiverse restricted - deb https://deb.taler.net/apt/ubuntu/ focal-fossa main @end example @@ -675,7 +681,7 @@ Next, you must import the Taler Systems SA public package signing key into your keyring and update the package lists: @example -# wget -O - https://taler.net/static/taler-systems.gpg.key | apt-sign add - +# wget -O - https://taler.net/taler-systems.gpg.key | apt-key add - # apt update @end example @@ -691,7 +697,7 @@ using apt. To install the Taler exchange, you can now simply run: @example -# apt install taler-exchange +# apt install -t focal-fossa taler-exchange @end example Note that the package does not perform any configuration work except for @@ -884,9 +890,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: @@ -954,7 +960,7 @@ choosing the backend, it is mandatory to supply the connection string via an environment variable: @code{TALER_EXCHANGEDB_POSTGRES_CONFIG}. @item -via configuration option @code{CONFIG}, under section @code{[exchangedb-BACKEND]}. +via configuration option @code{CONFIG}, under section @code{[exchangedb-$BACKEND]}. For example, the demo exchange is configured as follows: @end itemize @@ -1003,7 +1009,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? @@ -1122,7 +1128,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, @@ -1136,7 +1142,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 @@ -1150,7 +1156,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. @@ -1172,7 +1178,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 - @@ -1199,7 +1205,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. @@ -1325,7 +1331,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: @@ -1582,7 +1588,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 operator 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 @@ -1628,14 +1634,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 @@ -1655,7 +1661,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 |