diff options
Diffstat (limited to 'texinfo')
-rw-r--r-- | texinfo/taler-auditor.texi | 498 | ||||
-rw-r--r-- | texinfo/taler-bank-figures/merchant-db.png | bin | 459305 -> 469419 bytes | |||
-rw-r--r-- | texinfo/taler-bank.texi | 2 | ||||
-rw-r--r-- | texinfo/taler-developer-manual-figures/merchant-db.png | bin | 459305 -> 469419 bytes | |||
-rw-r--r-- | texinfo/taler-developer-manual.texi | 77 | ||||
-rw-r--r-- | texinfo/taler-exchange.texi | 94 | ||||
-rw-r--r-- | texinfo/taler-merchant-api-tutorial-figures/merchant-db.png | bin | 459305 -> 469419 bytes | |||
-rw-r--r-- | texinfo/taler-merchant-api-tutorial.texi | 8 | ||||
-rw-r--r-- | texinfo/taler-merchant-figures/merchant-db.png | bin | 459305 -> 469419 bytes | |||
-rw-r--r-- | texinfo/taler-merchant.texi | 105 |
10 files changed, 572 insertions, 212 deletions
diff --git a/texinfo/taler-auditor.texi b/texinfo/taler-auditor.texi index e1a0b384..4a99aed8 100644 --- a/texinfo/taler-auditor.texi +++ b/texinfo/taler-auditor.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 @@ -50,17 +50,17 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @anchor{taler-auditor-manual doc}@anchor{0} @c This file is part of GNU TALER. @c -@c Copyright (C) 2019-2020 Taler Systems SA +@c Copyright (C) 2019-2021 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 @@ -68,6 +68,7 @@ Copyright @copyright{} 2014-2021 Taler Systems SA (GPLv3+ or GFDL 1.3+) @menu * Introduction:: * Installation:: +* System setup:: * Configuration:: * Deployment:: * Operation:: @@ -88,13 +89,20 @@ Installation * Installing from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Ubuntu:: + +System setup + +* UNIX accounts:: +* Databases and users:: Configuration * Configuration format:: * Using taler-config:: +* Initial configuration:: * Keys:: -* Serving:: +* Configuring the auditor's REST endpoint:: * Bank account:: * Database:: @@ -326,7 +334,7 @@ of the report is required, as not every detail in the report is necessarily indicative of a problem. @end itemize -@node Installation,Configuration,Introduction,Top +@node Installation,System setup,Introduction,Top @anchor{taler-auditor-manual installation}@anchor{7} @chapter Installation @@ -334,6 +342,7 @@ indicative of a problem. @menu * Installing from source:: * Installing the GNU Taler binary packages on Debian:: +* Installing the GNU Taler binary packages on Ubuntu:: @end menu @@ -432,7 +441,7 @@ which requires you to run the last step as @code{root}. You have to specify @code{--with-gnunet=/usr/local} if you installed GNUnet to @code{/usr/local} in the previous step. -@node Installing the GNU Taler binary packages on Debian,,Installing from source,Installation +@node Installing the GNU Taler binary packages on Debian,Installing the GNU Taler binary packages on Ubuntu,Installing from source,Installation @anchor{taler-auditor-manual installing-the-gnu-taler-binary-packages-on-debian}@anchor{9} @section Installing the GNU Taler binary packages on Debian @@ -463,23 +472,77 @@ 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 +@end example + +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/taler-systems.gpg.key | apt-key add - +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems key out-of-band. +@end quotation +@end cartouche + +Now your system is ready to install the official GNU Taler binary packages +using apt. + +To install the Taler auditor, you can now simply run: + +@example +# apt install -t sid taler-auditor +@end example + +For the auditor, you must manually configure access to the exchange database, +the HTTP reverse proxy (typically with TLS certificates) and offline signing. + +Sample configuration files for the HTTP reverse proxy can be found in +@code{/etc/taler-auditor/}. + +@node Installing the GNU Taler binary packages on Ubuntu,,Installing the GNU Taler binary packages on Debian,Installation +@anchor{taler-auditor-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{a} +@section Installing the GNU Taler binary packages on Ubuntu + + +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.d/taler.list} file for this setup +would look like this: + +@example +deb https://deb.taler.net/apt/ubuntu/ focal-fossa main +@end example + The last line is crucial, as it adds the GNU Taler packages. 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 @@ -492,20 +555,138 @@ You may want to verify the correctness of the Taler Systems key out-of-band. Now your system is ready to install the official GNU Taler binary packages using apt. -To install the Taler auditor, you can now simply run: +To install the Taler exchange, you can now simply run: @example -# apt install taler-auditor +# apt install -t focal-fossa taler-auditor @end example For the auditor, you must manually configure access to the exchange database, the HTTP reverse proxy (typically with TLS certificates) and offline signing. Sample configuration files for the HTTP reverse proxy can be found in -@code{/etc/taler-exchange/}. +@code{/etc/taler-auditor/}. + +@node System setup,Configuration,Installation,Top +@anchor{taler-auditor-manual system-setup}@anchor{b} +@chapter System setup + + +@menu +* UNIX accounts:: +* Databases and users:: + +@end menu + +@node UNIX accounts,Databases and users,,System setup +@anchor{taler-auditor-manual unix-accounts}@anchor{c} +@section UNIX accounts + + +For maximum security, you should setup multiple different users (possibly +on different machines) to run Taler auditor components. While it is possible +to skip some of these entirely, or to run all of them as the same user, this +is not recommended for security. The recommended set of users includes: + +@quotation + + +@itemize * + +@item +auditor --- runs the main auditing process and HTTP backend + +@item +sync --- synchronizes the ingres database with the production database + +@item +helper --- runs taler-auditor-offline download and upload commands + +@item +auditor-ingres --- imports database from exchange production system + +@item +auditor-wire --- imports wire transfer data from bank production system + +@item +offline --- manages the offline key, on a separate @emph{offline} machine +@end itemize +@end quotation + +It is suggested that you setup the first five users on the target system(s) +using: + +@example +# add-user --disabled-password $USERNAME +@end example + +Additionally, there are two canonical system users of relevance (which your +distribution would typically create for you): + +@quotation + + +@itemize * + +@item +www-data --- runs the HTTPS frontend (usually nginx or Apache) + +@item +postgres --- runs the Postgres database +@end itemize +@end quotation + +@node Databases and users,,UNIX accounts,System setup +@anchor{taler-auditor-manual databases-and-users}@anchor{d} +@section Databases and users + -@node Configuration,Deployment,Installation,Top -@anchor{taler-auditor-manual configuration}@anchor{a} +We recommend using the following databases for the auditor: + +@quotation + + +@itemize * + +@item +exchange-ingres --- synchronized exchange database over the network + +@item +exchange-production --- local copy of exchange database with trusted schema + +@item +auditor --- auditor production database with current state of the audit + +@item +libeufin --- local state of the auditor-wire tool for the bank transfer data import +@end itemize +@end quotation + +As the @emph{postgres} user, you can create these databases using: + +@example +# As the 'postgres' user: +$ createdb -O auditor-ingres exchange-ingres +$ createdb -O sync exchange-production +$ createdb -O auditor auditor +$ createdb -O auditor-wire libeufin +@end example + +This will ensure that the correct users have write-access to their +respective database. Next, you need to grant read-only access to +some users to databases owned by other users: + +@example +# As the 'auditor-ingres' user: +$ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO sync;' | psql exchange-ingres +# As the 'sync' user: +$ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO auditor;' | psql exchange-production +# As the 'auditor-wire' user: +$ echo 'GRANT SELECT ON ALL TABLES IN SCHEMA public TO auditor;' | psql libeufin +@end example + +@node Configuration,Deployment,System setup,Top +@anchor{taler-auditor-manual configuration}@anchor{e} @chapter Configuration @@ -516,15 +697,16 @@ This section discusses configuration options related to the auditor. @menu * Configuration format:: * Using taler-config:: +* Initial configuration:: * Keys:: -* Serving:: +* Configuring the auditor's REST endpoint:: * Bank account:: * Database:: @end menu @node Configuration format,Using taler-config,,Configuration -@anchor{taler-auditor-manual configuration-format}@anchor{b} +@anchor{taler-auditor-manual configuration-format}@anchor{f} @section Configuration format @@ -598,8 +780,8 @@ values, as their work is often interdependent. For example, a merchant needs to know an exchange URL, or a database name. @end quotation -@node Using taler-config,Keys,Configuration format,Configuration -@anchor{taler-auditor-manual using-taler-config}@anchor{c} +@node Using taler-config,Initial configuration,Configuration format,Configuration +@anchor{taler-auditor-manual using-taler-config}@anchor{10} @section Using taler-config @@ -651,8 +833,34 @@ While the configuration file is typically located at to @code{taler-merchant-httpd} and @code{taler-config} using the @code{-c} option. -@node Keys,Serving,Using taler-config,Configuration -@anchor{taler-auditor-manual auditorkeys}@anchor{d}@anchor{taler-auditor-manual keys}@anchor{e} +@node Initial configuration,Keys,Using taler-config,Configuration +@anchor{taler-auditor-manual initial-configuration}@anchor{11}@anchor{taler-auditor-manual setupbaseurl}@anchor{12} +@section Initial configuration + + +You need to tell the Taler auditor configuration where the +REST API of the auditor will be available to the public: + +@example +# Both for the 'offline' *and* the 'auditor' user: +$ taler-config -s auditor -o BASE_URL -V https://auditor.example.com/ +@end example + +The @code{helper} user that is used to download information from the exchange +needs to know details about the exchange. Similarly, the @code{offline} user +needs to check signatures signed with the exchange's offline key. Hence, you +need to obtain the @code{MASTER_PUBLIC_KEY} from the exchange operator (they need +to run taler-exchange-offline setup) and the REST endpoint of the exchange +and configure these: + +@example +# As the 'helper' and 'offline' users: +$ taler-config -s exchange -o BASE_URL -V https://exchange.example.com/ +$ taler-config -s exchange -o MASTER_PUBLIC_KEY -V $SOMELONGBASE32VALUEHERE +@end example + +@node Keys,Configuring the auditor's REST endpoint,Initial configuration,Configuration +@anchor{taler-auditor-manual auditorkeys}@anchor{13}@anchor{taler-auditor-manual keys}@anchor{14} @section Keys @@ -670,15 +878,42 @@ The following values are to be configured in the section @code{[auditor]}: @item @code{AUDITOR_PRIV_FILE}: Path to the auditor’s private key file. +@end itemize + +Note that the default value here should be fine and there is no clear +need to change it. What you do need to do as the @code{offine} user +is to extract the public key: + +@example +# As the 'offline' user: +$ taler-auditor-offline setup +@end example + +This public key must then be provided in the configuration file +of the @code{auditor} user in the @code{[auditor]]} configuration section: + + +@itemize - @item @code{PUBLIC_KEY}: Public key of the auditor, in Base32 encoding. -Set from value printed by @code{taler-auditor-offline setup}. @end itemize -@node Serving,Bank account,Keys,Configuration -@anchor{taler-auditor-manual auditorserving}@anchor{f}@anchor{taler-auditor-manual serving}@anchor{10} -@section Serving +@quotation + +Set from value printed by @code{taler-auditor-offline setup}. +@end quotation + +You can set this configuration value using: + +@example +# As the 'auditor' and 'helper' users: +$ taler-config -s auditor -o PUBLIC_KEY -V $SOMELONGBASE32VALUEHERE +@end example + +@node Configuring the auditor's REST endpoint,Bank account,Keys,Configuration +@anchor{taler-auditor-manual auditorserving}@anchor{15}@anchor{taler-auditor-manual configuring-the-auditor-s-rest-endpoint}@anchor{16} +@section Configuring the auditor's REST endpoint The auditor can serve HTTP over both TCP and UNIX domain socket. @@ -704,17 +939,17 @@ HTTP over a UNIX domain socket for @code{unixpath} (i.e. 660 = @code{rw-rw----}). @end itemize -@node Bank account,Database,Serving,Configuration -@anchor{taler-auditor-manual auditorbank-account}@anchor{11}@anchor{taler-auditor-manual bank-account}@anchor{12} +@node Bank account,Database,Configuring the auditor's REST endpoint,Configuration +@anchor{taler-auditor-manual auditorbank-account}@anchor{17}@anchor{taler-auditor-manual bank-account}@anchor{18} @section Bank account -Bank accounts for the auditor are configured in exactly the -same way as bank accounts for the exchange. See the exchange -documentation for details. +Bank accounts for the auditor (user @code{auditor-wire}) are configured in +exactly the same way as bank accounts for the exchange. See the exchange (and +LibEuFin) documentation for details. @node Database,,Bank account,Configuration -@anchor{taler-auditor-manual auditordatabaseconfiguration}@anchor{13}@anchor{taler-auditor-manual database}@anchor{14} +@anchor{taler-auditor-manual auditordatabaseconfiguration}@anchor{19}@anchor{taler-auditor-manual database}@anchor{1a} @section Database @@ -730,7 +965,7 @@ choosing the backend, it is mandatory to supply the connection string via an environment variable: @code{TALER_AUDITORDB_POSTGRES_CONFIG}. @item -via configuration option @code{CONFIG}, under section @code{[auditordb-BACKEND]}. +via configuration option @code{CONFIG}, under section @code{[auditordb-$BACKEND]}. For example, the demo exchange is configured as follows: @example @@ -770,14 +1005,15 @@ CONFIG = postgres:///exchangedemo @end quotation @node Deployment,Operation,Configuration,Top -@anchor{taler-auditor-manual auditordeployment}@anchor{15}@anchor{taler-auditor-manual deployment}@anchor{16} +@anchor{taler-auditor-manual auditordeployment}@anchor{1b}@anchor{taler-auditor-manual deployment}@anchor{1c} @chapter Deployment -@anchor{taler-auditor-manual wallets}@anchor{17} -Before GNU Taler wallets will happily interact with an exchange, -the respective auditor's public key (to be obtained via @code{taler-auditor-offline setup}) -must be added under the respective currency to the wallet. This -is usually expected to be hard-coded into the Taler wallet. +@anchor{taler-auditor-manual wallets}@anchor{1d} +Before GNU Taler wallets will happily interact with an exchange, the +respective auditor's public key (as obtained via @code{taler-auditor-offline +setup} from the @code{offline} user) must be added under the respective currency +to the wallet. This is usually expected to be hard-coded into the Taler +wallet. Users can also manually add auditors for a particular currency via a Web page offering the respective pairing. @@ -792,49 +1028,52 @@ FIXME-DOLD: explain how that Web page works, once it works... @end menu @node Exchange,Signing Denominations,,Deployment -@anchor{taler-auditor-manual auditorexchange}@anchor{18}@anchor{taler-auditor-manual exchange}@anchor{19} +@anchor{taler-auditor-manual auditorexchange}@anchor{1e}@anchor{taler-auditor-manual exchange}@anchor{1f} @section Exchange -The next step is to add the exchange's master public key and the base -URL of the exchange to the list of exchanges audited by the auditor. -This is done using the @code{taler-auditor-exchange} tool. The tool -basically creates the respective record in the auditor's database. +The next step is to add the exchange's master public key and the base URL of +the exchange to the list of exchanges audited by the auditor. This is done +using the @code{taler-auditor-exchange} tool. The tool basically creates the +respective record in the auditor's database. -If this step is skipped, the auditor will malfunction at all future -stages with a foreign key violation, as it doesn't know the exchange's -master public key. +If this step is skipped, the auditor will malfunction at all future stages +with a foreign key violation, as it does not know the exchange's master public +key. @example +# As the 'auditor' user: $ taler-auditor-exchange -m $MASTER_PUB -u $EXCHANGE_BASE_URL @end example -The equivalent step must be performed by the exchange operator. -Here, the exchange operator must use the @code{taler-exchange-offline} -tool to add the auditor's public key, base URL and (business) name -to the list of approved auditors of the exchange. For details, -see Auditor-configuration in the exchange operator manual. +An equivalent step must be performed by the exchange operator. Here, the +exchange operator must use the @code{taler-exchange-offline} tool to add the +auditor's public key, base URL and (business) name to the list of approved +auditors of the exchange. For details, see Auditor-configuration in the +exchange operator manual. @node Signing Denominations,Database<2>,Exchange,Deployment -@anchor{taler-auditor-manual signing-denominations}@anchor{1a}@anchor{taler-auditor-manual signingdenominations}@anchor{1b} +@anchor{taler-auditor-manual signing-denominations}@anchor{20}@anchor{taler-auditor-manual signingdenominations}@anchor{21} @section Signing Denominations @geindex maintenance -This step must be performed regularly whenever the exchange is +These steps must be performed @emph{regularly} whenever the exchange is deploying new denomination keys. After the exchange operator has signed new keys using the @code{taler-exchange-offline} tool, each auditor should run: @example +# As the 'helper' user: $ taler-auditor-offline download > input.json @end example -to import the latest set of denomination keys. The key data -should then be inspected using: +to import the latest set of denomination keys. The key data should then be +copied to the offline system and there be inspected using: @example +# As the 'offline' user: $ taler-auditor-offline show < input.json @end example @@ -854,6 +1093,7 @@ Given the verified JSON input, the auditor can then sign it (typically on its offline system) using: @example +# As the 'offline' user: $ taler-auditor-offline sign < input.json > output.json @end example @@ -861,6 +1101,7 @@ The resulting @code{output.json} should then be copied to an online system, and from there uploaded to the exchange using: @example +# As the 'helper' user: $ taler-auditor-offline upload < output.json @end example @@ -875,7 +1116,7 @@ Commands, like @code{taler-auditor-offline}, that support the @code{-l LOGFILE} command-line option, send logging output to standard error by default. @node Database<2>,,Signing Denominations,Deployment -@anchor{taler-auditor-manual auditordatabaseinitialization}@anchor{1c}@anchor{taler-auditor-manual id1}@anchor{1d} +@anchor{taler-auditor-manual auditordatabaseinitialization}@anchor{22}@anchor{taler-auditor-manual id1}@anchor{23} @section Database @@ -906,10 +1147,14 @@ mechanism driven by the exchange operator. @end menu @node Ingres replication of the exchange production database,Safe replication of the ingres database into the auditor production database,,Database<2> -@anchor{taler-auditor-manual ingres-replication-of-the-exchange-production-database}@anchor{1e} +@anchor{taler-auditor-manual ingres-replication-of-the-exchange-production-database}@anchor{24} @subsection Ingres replication of the exchange production database +Ingres operation should be done using the @code{auditor-ingres} user --- or +depending on the setup parts of the operation may be done by the @code{postgres} +user directly. + The full copy can be obtained in various ways with Postgres. It is possible to use log shipping with streaming replication as described in @indicateurl{https://www.postgresql.org/docs/13/warm-standby.html}, or to use @@ -925,6 +1170,60 @@ replicate schema changes), @code{taler-exchange-dbinit} can be used to migrate the schema(s) in both the ingres and production copies of the exchange's database as well. +On the exchange side, a database user must be created that has the right +to perform database replication. This is done using: + +@example +# As the 'postgres' user of the exchange: +$ createuser --replication egress +$ echo "ALTER ROLE egress WITH PASSWORD '$PASSWORD'; | psql +$ echo "CREATE PUBLICATION $NAME FOR ALL TABLES;" | psql taler-exchange +@end example + +The exchange must share the password of the publication with the auditor. A +good @code{$NAME} relates to the auditor's buisness unit name. A secure tunnel +must be setup between the exchange and the auditor, for example using SSH or +Wireguard. + +It is also necessary to edit @code{main.cf} of the exchange and on the auditor +side to enable logical replication. If an exchange has multiple auditors, it +should setup multiple @code{egress} accounts. The exchange must ensure that +the following lines are in the @code{main.cf} Postgres configuaration (the port +may differ) to enable replication over the network: + +@example +listen_addresses='*' +port = 5432 +wal_level= logical +@end example + +Equally, the auditor must configure logical replication in the @code{main.cf} +Postgres configuaration: + +@example +wal_level= logical +@end example + +Next, the @code{postgres} user of the auditor's system must first initialize the +local tables: + +@example +# As the 'ingress' user of the exchange: +$ taler-config -s exchange -o DB -V "postgres" +$ taler-config -s exchangedb-postgres -o CONFIG -V "postgres:///taler-ingress" +$ taler-exchange-dbinit +@end example + +To complete the replication, the @code{postgres} user of the auditor's +system must subscribe: + +@example +# As the 'postgres' user of the exchange: +$ createuser --replication egress +$ echo "ALTER ROLE egress WITH PASSWORD '$PASSWORD'; | psql +$ echo "CREATE PUBLICATION $NAME FOR ALL TABLES;" | psql taler-exchange +@end example + For details, we refer to the Postgres manual. @cartouche @@ -942,17 +1241,18 @@ process, from its actual operational data. @end cartouche @node Safe replication of the ingres database into the auditor production database,,Ingres replication of the exchange production database,Database<2> -@anchor{taler-auditor-manual safe-replication-of-the-ingres-database-into-the-auditor-production-database}@anchor{1f} +@anchor{taler-auditor-manual safe-replication-of-the-ingres-database-into-the-auditor-production-database}@anchor{25} @subsection Safe replication of the ingres database into the auditor production database -Using @code{taler-auditor-sync}, the auditor should make a second "safe" copy of -the exchange's ingres database. @code{taler-auditor-sync} basically reads from one -exchange database and inserts all records found into a second exchange -database. If the source database violates invariants, the tool halts with an -error. This way, records violating invariants are never even copied, and in -particular schema changes and deletions or updates are not propagated into the -auditor's production database. +Using @code{taler-auditor-sync} as the @code{sync} user, the auditor should +make a second "safe" copy of the exchange's ingres database. +@code{taler-auditor-sync} basically reads from one exchange database and inserts +all records found into a second exchange database. If the source database +violates invariants, the tool halts with an error. This way, records violating +invariants are never even copied, and in particular schema changes and +deletions or updates are not propagated into the auditor's production +database. While @code{taler-auditor-sync} could in theory be run directly against the exchange's production system, this is likely a bad idea due to the high @@ -970,6 +1270,25 @@ database, and a second with the options for accessing the destination database. In both cases, likely only the @code{[exchangedb]/CONFIG} option needs to be changed. +To run @code{taler-auditor-sync}, you must first configure two configuration +files that identify the source and destination databases: + +@example +# As the 'sync' user: +$ taler-config -c src.conf -s exchangedb -o CONFIG -V "postgres:///auditor-ingres/" +$ taler-config -c dst.conf -s exchangedb -o CONFIG -V "postgres:///auditor/" +@end example + +Now you should be able to launch the synchronization process. You can run +the process via systemd in the background. For a first one-off test, you should +use the @code{-t} option which will cause the process to terminate once the two +databases are synchronized: + +@example +# As the 'sync' user: +$ taler-auditor-sync -s src.conf -d dst.cfg -t +@end example + When the exchange performs garbage collection to @code{DELETE} obsolete records, this change should be automatically replicated to the auditors untrusted ingress database. However, as @code{taler-auditor-sync} tries to be "safe", @@ -980,7 +1299,7 @@ auditor's production copy. We note that this does not have to be done at the same time when the exchange runs its garbage collection. @node Operation,Auditor implementation guide,Deployment,Top -@anchor{taler-auditor-manual id2}@anchor{20}@anchor{taler-auditor-manual operation}@anchor{21} +@anchor{taler-auditor-manual id2}@anchor{26}@anchor{taler-auditor-manual operation}@anchor{27} @chapter Operation @@ -996,7 +1315,7 @@ at the same time when the exchange runs its garbage collection. @end menu @node Web service,Audit,,Operation -@anchor{taler-auditor-manual id3}@anchor{22}@anchor{taler-auditor-manual web-service}@anchor{23} +@anchor{taler-auditor-manual id3}@anchor{28}@anchor{taler-auditor-manual web-service}@anchor{29} @section Web service @@ -1005,22 +1324,29 @@ service must have @code{INSERT} (and @code{SELECT}) rights on the @code{deposit_confirmations} table in the auditor's database. We expect that in future versions additional rights may be required. +For now, we recommend simply running the @code{taler-auditor-httpd} under the +@code{auditor} user. However, it is also possible (and might be more secure) to +create a separate user with more restrictive permissions for this purpose. + As the @code{taler-auditor-httpd} does not include HTTPS-support, it is advisable to run it behind a reverse proxy that offers TLS termination. @node Audit,Reading the report,Web service,Operation -@anchor{taler-auditor-manual audit}@anchor{24}@anchor{taler-auditor-manual id4}@anchor{25} +@anchor{taler-auditor-manual audit}@anchor{2a}@anchor{taler-auditor-manual id4}@anchor{2b} @section Audit -Performing an audit is done by invoking the @code{taler-auditor} shell script. +Performing an audit is done by invoking the @code{taler-auditor} shell script as +the @code{auditor} user. + The shell script invokes the various helper processes. For additional performance and security, one may want to run the various helpers individually and with the respective minimal set of access rights (only @code{taler-helper-auditor-wire} needs the credentials to query the bank for wire -transfers). The shell script combines the final JSON outputs of the various -helpers using the @code{taler-helper-auditor-render.py} script into the TeX -report. Regardless, the simplest way to obtain a report is to run: +transfers, alas if @code{auditor-wire} is used to talk to the bank, this issue is +already addressed). The shell script combines the final JSON outputs of the +various helpers using the @code{taler-helper-auditor-render.py} script into the +TeX report. Regardless, the simplest way to obtain a report is to run: @example $ taler-audit @@ -1041,7 +1367,7 @@ interactions with the bank (which may not even have the wire transfer records anymore), this is not recommended in a production setup. @node Reading the report,Database upgrades,Audit,Operation -@anchor{taler-auditor-manual reading-the-report}@anchor{26} +@anchor{taler-auditor-manual reading-the-report}@anchor{2c} @section Reading the report @@ -1077,7 +1403,7 @@ Configuration issues (such was wire fees unavailable). @end itemize @node Database upgrades,Database reset,Reading the report,Operation -@anchor{taler-auditor-manual auditordatabaseupgrades}@anchor{27}@anchor{taler-auditor-manual database-upgrades}@anchor{28} +@anchor{taler-auditor-manual auditordatabaseupgrades}@anchor{2d}@anchor{taler-auditor-manual database-upgrades}@anchor{2e} @section Database upgrades @@ -1132,7 +1458,7 @@ Regardless, the above is merely the general rule. Please review the specific release notes to ensure this procedure is correct for the specific upgrade. @node Database reset,Revocations,Database upgrades,Operation -@anchor{taler-auditor-manual database-reset}@anchor{29} +@anchor{taler-auditor-manual database-reset}@anchor{2f} @section Database reset @@ -1150,7 +1476,7 @@ next launched, as it will re-download and re-verify all historic transactions. Hence this should not be done in a production system. @node Revocations,Failures,Database reset,Operation -@anchor{taler-auditor-manual auditorrevocations}@anchor{2a}@anchor{taler-auditor-manual revocations}@anchor{2b} +@anchor{taler-auditor-manual auditorrevocations}@anchor{30}@anchor{taler-auditor-manual revocations}@anchor{31} @section Revocations @@ -1168,7 +1494,7 @@ additional information to demonstrate that these coins were not forged from the compromised private key but obtained via a legitimate withdraw operation. @node Failures,,Revocations,Operation -@anchor{taler-auditor-manual failures}@anchor{2c} +@anchor{taler-auditor-manual failures}@anchor{32} @section Failures @@ -1201,7 +1527,7 @@ loss/gain calculations will be meaningful and actually indicative of the scope of the error created by the corrupted data. @node Auditor implementation guide,Index,Operation,Top -@anchor{taler-auditor-manual auditor-implementation-guide}@anchor{2d} +@anchor{taler-auditor-manual auditor-implementation-guide}@anchor{33} @chapter Auditor implementation guide @@ -1233,7 +1559,7 @@ JSON reports into LaTeX and then into PDF. @end menu @node The auditor's database,Invariants checked by the auditor,,Auditor implementation guide -@anchor{taler-auditor-manual the-auditor-s-database}@anchor{2e} +@anchor{taler-auditor-manual the-auditor-s-database}@anchor{34} @section The auditor's database @@ -1242,7 +1568,7 @@ The database scheme used by the exchange looks as follows: @image{taler-auditor-figures/auditor-db,,,,png} @node Invariants checked by the auditor,Testing the auditor,The auditor's database,Auditor implementation guide -@anchor{taler-auditor-manual invariants-checked-by-the-auditor}@anchor{2f} +@anchor{taler-auditor-manual invariants-checked-by-the-auditor}@anchor{35} @section Invariants checked by the auditor @@ -1262,7 +1588,7 @@ pass where it might seem applicable. @end menu @node Invariants checked by the taler-helper-auditor-aggregation,Invariants checked by the taler-helper-auditor-coins,,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-aggregation}@anchor{30} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-aggregation}@anchor{36} @subsection Invariants checked by the taler-helper-auditor-aggregation @@ -1374,7 +1700,7 @@ wire fee unavailable for given time @end itemize @node Invariants checked by the taler-helper-auditor-coins,Invariants checked by the taler-helper-auditor-deposits,Invariants checked by the taler-helper-auditor-aggregation,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-coins}@anchor{31} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-coins}@anchor{37} @subsection Invariants checked by the taler-helper-auditor-coins @@ -1470,7 +1796,7 @@ recoup, denomination not revoked @end itemize @node Invariants checked by the taler-helper-auditor-deposits,Invariants checked by the taler-helper-auditor-reserves,Invariants checked by the taler-helper-auditor-coins,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-deposits}@anchor{32} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-deposits}@anchor{38} @subsection Invariants checked by the taler-helper-auditor-deposits @@ -1480,7 +1806,7 @@ exchange at the auditor. This is to ensure that the exchange cannot defraud merchants by simply not reporting deposits to the auditor. @node Invariants checked by the taler-helper-auditor-reserves,Invariants checked by the taler-helper-auditor-wire,Invariants checked by the taler-helper-auditor-deposits,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-reserves}@anchor{33} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-reserves}@anchor{39} @subsection Invariants checked by the taler-helper-auditor-reserves @@ -1541,7 +1867,7 @@ target account does not match origin account @end itemize @node Invariants checked by the taler-helper-auditor-wire,,Invariants checked by the taler-helper-auditor-reserves,Invariants checked by the auditor -@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-wire}@anchor{34} +@anchor{taler-auditor-manual invariants-checked-by-the-taler-helper-auditor-wire}@anchor{3a} @subsection Invariants checked by the taler-helper-auditor-wire @@ -1606,7 +1932,7 @@ closing fee above total amount @end itemize @node Testing the auditor,,Invariants checked by the auditor,Auditor implementation guide -@anchor{taler-auditor-manual testing-the-auditor}@anchor{35} +@anchor{taler-auditor-manual testing-the-auditor}@anchor{3b} @section Testing the auditor diff --git a/texinfo/taler-bank-figures/merchant-db.png b/texinfo/taler-bank-figures/merchant-db.png Binary files differindex cd5f7bd6..ef7e1d05 100644 --- a/texinfo/taler-bank-figures/merchant-db.png +++ b/texinfo/taler-bank-figures/merchant-db.png diff --git a/texinfo/taler-bank.texi b/texinfo/taler-bank.texi index 74c701c3..15959e1a 100644 --- a/texinfo/taler-bank.texi +++ b/texinfo/taler-bank.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 diff --git a/texinfo/taler-developer-manual-figures/merchant-db.png b/texinfo/taler-developer-manual-figures/merchant-db.png Binary files differindex cd5f7bd6..ef7e1d05 100644 --- a/texinfo/taler-developer-manual-figures/merchant-db.png +++ b/texinfo/taler-developer-manual-figures/merchant-db.png diff --git a/texinfo/taler-developer-manual.texi b/texinfo/taler-developer-manual.texi index 4b51194f..26be432a 100644 --- a/texinfo/taler-developer-manual.texi +++ b/texinfo/taler-developer-manual.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-2021 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 @@ -996,6 +996,15 @@ For tests in the exchange and merchant to run, make sure that a database @emph{talercheck} is accessible by @emph{$USER}. Otherwise tests involving the database logic are skipped. +@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 Exchange merchant,Wallet WebExtension,Database for tests,Releases @anchor{taler-developer-manual exchange-merchant}@anchor{24} @section Exchange, merchant @@ -1238,7 +1247,7 @@ Under @emph{https://weblate.taler.net/create/component/vcs/}: @strong{Merge style} - @emph{Rebase}, in line with GNU Taler development procedures @item -@strong{Translation license} - @emph{GNU General Public License v3.0 or Later} +@strong{Translation license} - @emph{GNU Affero General Public License v3.0 or Later} @item @strong{Adding new translation} - Decide how to handle adding new translations @@ -2627,21 +2636,21 @@ developer. @strong{taler-config-generate} - tool to simplify Taler configuration generation @strong{taler-config-generate} -[@strong{-C} @emph{CURRENCY} | @strong{––currency=}@emph{CURRENCY}] -[@strong{-c} @emph{FILENAME} | @strong{––config=}@emph{FILENAME}] -[@strong{-e} | @strong{––exchange}] -[@strong{-f} @emph{AMOUNT} | @emph{––wirefee=}@emph{AMOUNT}] -[@strong{-h} | @strong{––help}] -[@strong{-J} @emph{JSON} | @strong{––wire-json-exchange=}@emph{JSON}] -[@strong{-j} @emph{JSON} | @strong{––wire-json-merchant=}@emph{JSON}] -[@strong{-L} @emph{LOGLEVEL} | @strong{––loglevel=}@emph{LOGLEVEL}] -[@strong{-m} | @strong{––merchant}] -[@strong{-t} | @strong{––trusted}] -[@strong{-v} | @strong{––version}] -[@strong{-w} @emph{WIREFORMAT} | @strong{––wire} @emph{WIREFORMAT}] -[@strong{––bank-uri}] -[@strong{––exchange-bank-account}] -[@strong{––merchant-bank-account}] +[@strong{-C} @emph{CURRENCY} | @strong{--currency=}@emph{CURRENCY}] +[@strong{-c} @emph{FILENAME} | @strong{--config=}@emph{FILENAME}] +[@strong{-e} | @strong{--exchange}] +[@strong{-f} @emph{AMOUNT} | @emph{--wirefee=}@emph{AMOUNT}] +[@strong{-h} | @strong{--help}] +[@strong{-J} @emph{JSON} | @strong{--wire-json-exchange=}@emph{JSON}] +[@strong{-j} @emph{JSON} | @strong{--wire-json-merchant=}@emph{JSON}] +[@strong{-L} @emph{LOGLEVEL} | @strong{--loglevel=}@emph{LOGLEVEL}] +[@strong{-m} | @strong{--merchant}] +[@strong{-t} | @strong{--trusted}] +[@strong{-v} | @strong{--version}] +[@strong{-w} @emph{WIREFORMAT} | @strong{--wire} @emph{WIREFORMAT}] +[@strong{--bank-uri}] +[@strong{--exchange-bank-account}] +[@strong{--merchant-bank-account}] @strong{taler-config-generate} can be used to generate configuration files for the Taler exchange or Taler merchants. @@ -2649,16 +2658,16 @@ for the Taler exchange or Taler merchants. @table @asis -@item @strong{-C} @emph{CURRENCY} | @strong{––currency=}@emph{CURRENCY} +@item @strong{-C} @emph{CURRENCY} | @strong{--currency=}@emph{CURRENCY} Which currency should we use in the configuration. -@item @strong{-c} @emph{FILENAME} | @strong{––config=}@emph{FILENAME} +@item @strong{-c} @emph{FILENAME} | @strong{--config=}@emph{FILENAME} Location where to write the generated configuration. Existing file will be updated, not overwritten. -@item @strong{-e} | @strong{––exchange} +@item @strong{-e} | @strong{--exchange} Generate configuration for a Taler exchange. @@ -2667,53 +2676,53 @@ Generate configuration for a Taler exchange. Setup wire transfer fees for the next 5 years for the exchange (for all wire methods). -@item @strong{-h} | @strong{––help} +@item @strong{-h} | @strong{--help} Shows this man page. -@item @strong{-J} @emph{JSON} | @strong{––wire-json-exchange=}@emph{JSON} +@item @strong{-J} @emph{JSON} | @strong{--wire-json-exchange=}@emph{JSON} Wire configuration to use for the exchange. -@item @strong{-j} @emph{JSON} | @strong{––wire-json-merchant=}@emph{JSON} +@item @strong{-j} @emph{JSON} | @strong{--wire-json-merchant=}@emph{JSON} Wire configuration to use for the merchant. -@item @strong{-L} @emph{LOGLEVEL} | @strong{––loglevel=}@emph{LOGLEVEL} +@item @strong{-L} @emph{LOGLEVEL} | @strong{--loglevel=}@emph{LOGLEVEL} Use LOGLEVEL for logging. Valid values are DEBUG, INFO, WARNING and ERROR. -@item @strong{-m} | @strong{––merchant} +@item @strong{-m} | @strong{--merchant} Generate configuration for a Taler merchant. -@item @strong{-t} | @strong{––trusted} +@item @strong{-t} | @strong{--trusted} Setup current exchange as trusted with current merchant. Generally only useful when configuring for testcases. -@item @strong{-v} | @strong{––version} +@item @strong{-v} | @strong{--version} Print version information. -@item @strong{-w} @emph{WIREFORMAT} | @strong{––wire} @emph{WIREFORMAT} +@item @strong{-w} @emph{WIREFORMAT} | @strong{--wire} @emph{WIREFORMAT} Specifies which wire format to use (i.e. “test” or “sepa”) -@item @strong{––bank-uri} +@item @strong{--bank-uri} Alternative to specify wire configuration to use for the exchange and merchant for the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the URI of the bank. -@item @strong{––exchange-bank-account} +@item @strong{--exchange-bank-account} Alternative to specify wire configuration to use for the exchange for the “test” wire method. Only useful if WIREFORMAT was set to “test”. Specifies the bank account number of the exchange. -@item @strong{––merchant-bank-account} +@item @strong{--merchant-bank-account} Alternative to specify wire configuration to use for the merchant for the “test” wire method. Only useful if WIREFORMAT was set to “test”. 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 diff --git a/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png b/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png Binary files differindex cd5f7bd6..ef7e1d05 100644 --- a/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png +++ b/texinfo/taler-merchant-api-tutorial-figures/merchant-db.png diff --git a/texinfo/taler-merchant-api-tutorial.texi b/texinfo/taler-merchant-api-tutorial.texi index 3f51b138..e0acd921 100644 --- a/texinfo/taler-merchant-api-tutorial.texi +++ b/texinfo/taler-merchant-api-tutorial.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 @@ -52,14 +52,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 Lesser 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 Lesser 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 Marcello Stanisci diff --git a/texinfo/taler-merchant-figures/merchant-db.png b/texinfo/taler-merchant-figures/merchant-db.png Binary files differindex cd5f7bd6..ef7e1d05 100644 --- a/texinfo/taler-merchant-figures/merchant-db.png +++ b/texinfo/taler-merchant-figures/merchant-db.png diff --git a/texinfo/taler-merchant.texi b/texinfo/taler-merchant.texi index 4cc52001..23e70812 100644 --- a/texinfo/taler-merchant.texi +++ b/texinfo/taler-merchant.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 @@ -348,7 +348,7 @@ the main Taler configuration (accepted currency, exchanges and auditors). To receive payments, an instance must have configured one or more bank @emph{accounts}. The backend does not have accounts for users, and instances are -also not really ‘accounts’. So whenever we use the term @emph{account}, it is about +also not really 'accounts'. So whenever we use the term @emph{account}, it is about a bank account of a merchant. @node Inventory,Orders and Contracts,Accounts,Terminology @@ -447,7 +447,7 @@ decade), contract information is deleted. The Taler backend can be used to verify that the exchange correctly wired all of the funds to the merchant. However, the backend does not have access to the -incoming wire transfers of the merchant’s bank account. Thus, merchants must +incoming wire transfers of the merchant's bank account. Thus, merchants must manually provide the backend with wire @emph{transfer} data that specifies the wire transfer subject and the amount that was received. Given this information, the backend can detect and report any irregularities that might arise. @@ -621,7 +621,7 @@ shared object libraries (@code{.so} files) visible to the various installed programs. There is no need to actually run a GNUnet peer to use the Taler merchant -backend – all the merchant needs from GNUnet is a number of headers and +backend -- all the merchant needs from GNUnet is a number of headers and libraries! @node Installing the GNU Taler exchange,Installing the GNU Taler merchant backend,Installing GNUnet,Generic instructions for installation from source @@ -649,7 +649,7 @@ which requires you to run the last step as @code{root}. You have to specify previous step. There is no need to actually run a Taler exchange to use the Taler merchant -backend – all the merchant needs from the Taler exchange is a few headers and +backend -- all the merchant needs from the Taler exchange is a few headers and libraries! @node Installing the GNU Taler merchant backend,,Installing the GNU Taler exchange,Generic instructions for installation from source @@ -730,23 +730,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 @@ -781,20 +788,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 @@ -804,7 +801,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 @@ -1218,6 +1215,15 @@ Commands, like @code{taler-merchant-dbinit}, that support the @code{-l LOGFILE} command-line option, send logging output to standard error by default. See manpages/taler-merchant-dbinit.1 for more information. +@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 + @c index: MASTER_KEY @node Exchange,Auditor,Database,Backend options @@ -1284,7 +1290,7 @@ that section, the following options need to be configured: @item The @code{AUDITOR_BASE_URL} option specifies the auditor’s base URL. -For example, to use the Taler demonstrator’s auditor, specify: +For example, to use the Taler demonstrator's auditor, specify: @example $ taler-config -s MERCHANT-AUDITOR-demo \ @@ -1293,7 +1299,7 @@ $ taler-config -s MERCHANT-AUDITOR-demo \ @end example @item -The @code{AUDITOR_KEY} option specifies the auditor’s public key +The @code{AUDITOR_KEY} option specifies the auditor's public key in base32 encoding. For the Taler demonstrator, use: @example @@ -1390,17 +1396,30 @@ system for how to start and stop daemons. If everything worked as expected, the command @example -$ curl http://localhost:8888/ +$ curl http://localhost:8888/config @end example -should return the message +should return some basic configuration status data about the service. -@example -Hello, I'm a merchant's Taler backend. This HTTP server is not for humans. -@end example +Please note that your backend is right now likely globally reachable. You can either: + +@quotation + + +@itemize * + +@item +Use the @code{--auth=$TOKEN} command-line option to set an access token to be provided in an @code{Authorize: Bearer $TOKEN} HTTP header. Note that this can be used at anytime to override access control, but remains only in effect until a first instance is created or an existing instance authentication setting is modified. + +@item +Set the @code{TALER_MERCHANT_TOKEN} environment variable to @code{$TOKEN} for the same effect. This method has the advantage of @code{$TOKEN} not being visible as a command-line interface to other local users on the same machine. + +@item +Set up an instance with an authentication token before some unauthorized person has a chance to access the backend. As the backend is useless without any instance and the chances of remote attackers during the initial configuration is low, this is probably sufficient for most use-cases. Still, keep the first two scenarios in mind in case you ever forget your access token! +@end itemize +@end quotation -Please note that your backend is right now likely globally reachable. -Production systems should be configured to bind to a UNIX domain socket +Production systems should additionally be configured to bind to a UNIX domain socket and use TLS for improved network privacy, see @ref{9,,Secure setup}. @geindex instance @@ -1410,7 +1429,7 @@ and use TLS for improved network privacy, see @ref{9,,Secure setup}. @chapter Instance setup -Before using the backend, you must at least configure the “default” instance. +Before using the backend, you must at least configure the "default" instance. @menu * KUDOS Accounts:: @@ -1481,7 +1500,7 @@ create a file @code{instance.json} with an InstanceConfigurationMessage In the text above, you must replace @code{$PAYTO_URI} with your actual @code{payto://}-URI. Also, be sure to replace @code{KUDOS} with the fiat currency if the setup is for an actual bank. The @code{name} field will be shown as the name of -your shop. The @code{address} field is expected to contain your shop’s physical +your shop. The @code{address} field is expected to contain your shop's physical address. The various defaults specify defaults for transaction fees your shop is willing to cover, how long offers made to the customer are valid, and how long the exchange has before it must wire the funds to your bank @@ -1537,9 +1556,9 @@ $ taler-config -s MERCHANT -o SERVE -V UNIX $ taler-config -s MERCHANT -o UNIXPATH -V /some/path/here.sock @end example -Do not use a UNIX domain socket path in “/tmp”: systemd (or other init -systems) may give Web servers a private “/tmp” thereby hiding UNIX domain -sockets created by other users/processes in “/tmp”. +Do not use a UNIX domain socket path in "/tmp": systemd (or other init +systems) may give Web servers a private "/tmp" thereby hiding UNIX domain +sockets created by other users/processes in "/tmp". If UNIX domain sockets are for some reason not possible, you @emph{may} use a host-based firewall to block access to the TCP port of the merchant backend, @@ -1813,7 +1832,7 @@ process to hold open file handles for all of these files. You may want to increase the @code{ulimit} of the @code{taler-merchant-httpd} process if you have templates for many languages. -The backend determines the MIME type based on the file’s extension. The list +The backend determines the MIME type based on the file's extension. The list of supported extensions is hard-coded and includes common text and image formats. @@ -1913,7 +1932,7 @@ You now need to make a wire transfer to the exchange’s bank account using the given wire transfer subject. Make your wire transfer and (optionally) check at -“@indicateurl{https://exchange/reserves/QPE24X}…” whether your transfer has arrived at the +“@indicateurl{https://exchange/reserves/QPE24X}...” whether your transfer has arrived at the exchange. Once the funds have arrived, you can start to use the reserve for @@ -2184,13 +2203,13 @@ start. The @code{taler-merchant-benchmark} tool will automatically launch and configure the exchange, (Python) bank and other tools required for the benchmark. However, the configuration file must be provided and have consistent options set. The -options that require special care include the exchange’s public key (which +options that require special care include the exchange's public key (which must match the private key in the file specified by the configuration), the currency (which must be consistent across the file), the denomination structure (which must enable payments in the range of 100ths of the unit currency (often called cents)). Furthermore, the benchmark will set the -Exchange bank account password to be “x”, so the configuration must also -specify “x” for the passphrase. Finally, the bank must be configured to allow +Exchange bank account password to be "x", so the configuration must also +specify "x" for the passphrase. Finally, the bank must be configured to allow for substantial debt least the transactions by the benchmark run out of digital cash. @@ -2322,10 +2341,10 @@ rsa_keysize = 1024 @end example -Note that the public key must match the exchange’s +Note that the public key must match the exchange's private key and that the Postgres database must exist before launching the benchmark. You also -will need to ensure that the Exchange’s +will need to ensure that the Exchange's details are set up. For details, see the Exchange Operator Manual. @@ -2394,7 +2413,7 @@ options: @item @code{--tracks-number=TN} Instructs the tool to perform @emph{TN} tracking operations. Note that the @strong{total} amount of operations will be two -times @emph{TN}, since “one” tracking operation accounts for +times @emph{TN}, since "one" tracking operation accounts for @code{/track/transaction} and @code{/track/transfer}. This command should only be used to see if the operation ends without problems, as no actual measurement of performance is provided (despite of the |