diff options
Diffstat (limited to 'texinfo/challenger.texi')
| -rw-r--r-- | texinfo/challenger.texi | 1501 |
1 files changed, 1501 insertions, 0 deletions
diff --git a/texinfo/challenger.texi b/texinfo/challenger.texi new file mode 100644 index 00000000..9dd4654f --- /dev/null +++ b/texinfo/challenger.texi @@ -0,0 +1,1501 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename challenger.info +@documentencoding UTF-8 +@ifinfo +@*Generated by Sphinx 5.3.0.@* +@end ifinfo +@settitle Taler Challenger Manual +@defindex ge +@paragraphindent 0 +@exampleindent 4 +@finalout +@dircategory Network applications +@direntry +* GNU Taler Challenger: (challenger.info). Customer address validation service +@end direntry + +@c %**end of header + +@copying +@quotation +GNU Taler 0.10.0, May 15, 2024 + +GNU Taler team + +Copyright @copyright{} 2014-2024 Taler Systems SA (GPLv3+ or GFDL 1.3+) +@end quotation + +@end copying + +@titlepage +@title Taler Challenger Manual +@insertcopying +@end titlepage +@contents + +@c %** start of user preamble + +@c %** end of user preamble + +@ifnottex +@node Top +@top Taler Challenger Manual +@insertcopying +@end ifnottex + +@c %**start of body +@anchor{taler-challenger-manual doc}@anchor{0} +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2023, 2024 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@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 Affero General Public License for more details. +@c +@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 +@c @author Florian Dold + +@menu +* Introduction:: +* Installation:: +* Configuration Fundamentals:: +* Deployment:: +* Template Customization:: + +@detailmenu + --- The Detailed Node Listing --- + +Introduction + +* About Challenger:: +* About this manual:: +* Architecture overview:: + +Installation + +* Installing from source:: +* Installing the Challenger binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: +* Installing the GNU Taler binary packages on Ubuntu:: +* Services@comma{} users@comma{} groups and file system hierarchy: Services users groups and file system hierarchy. + +Configuration Fundamentals + +* Configuration format:: +* Fundamental Setup; Address validation: Fundamental Setup Address validation. +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: +* Database Configuration:: + +Legal policies directory layout + +* Example:: + +Deployment + +* Serving:: +* Reverse Proxy Setup:: +* Launching Challenger:: +* Authorizing clients:: +* OAuth 2.0 integration: OAuth 2 0 integration. +* Database management:: + +Template Customization + +* enter-$ADDRESS_TYPE-form:: +* enter-tan-form:: +* invalid-pin:: +* validation-unknown:: +* invalid-request:: +* internal-error:: + +@end detailmenu +@end menu + +@node Introduction,Installation,Top,Top +@anchor{taler-challenger-manual challenger-operator-manual}@anchor{1}@anchor{taler-challenger-manual introduction}@anchor{2} +@chapter Introduction + + +@menu +* About Challenger:: +* About this manual:: +* Architecture overview:: + +@end menu + +@node About Challenger,About this manual,,Introduction +@anchor{taler-challenger-manual about-challenger}@anchor{3} +@section About Challenger + + +Challenger is an OAuth 2.0-compatible address validation service. +By redirecting a user-agent to a Challenger service a client can +have Challenger validate that the user is able to receive messages +at a particular address and obtain that address via the @code{/info} +endpoint. + +@node About this manual,Architecture overview,About Challenger,Introduction +@anchor{taler-challenger-manual about-this-manual}@anchor{4} +@section About this manual + + +This manual targets system administrators who want to install, +operate or integrate a challenger service. To report issues +or learn about known limitations, please check our +bug tracker@footnote{https://bugs.taler.net}. + +@node Architecture overview,,About this manual,Introduction +@anchor{taler-challenger-manual architecture-overview}@anchor{5} +@section Architecture overview + + +The following picture gives an overview of the Challenger +architecture and the main interactions: + +@image{challenger-figures/challenger,,,,png} + +Here, the `resource owner' is a user that is in control +of some `address' at a messaging service. This could be +an e-mail account, a mobile phone number (for SMS), or +a physical mail address (using the post office as the +messaging service). + +The `resource owner' makes some request that requires +some `client' to be in need of address validation. The +`client' is registered with the Challenger OAuth 2.0 +service and first authorizes an address validation to +be initiated. The client then redirects the resource +owner to the Challenger service. In step (2), the resource +owner submits the address that they claim to own. + +The Challenger service then creates a TAN code and +submits it to the given address via a configurable +`helper script' that is specific to the type of address +being validated. When the resource owner submits the +correct TAN code in step (6), they are given a token +that they can provide to the client. Using this token +the client can then finally obtain the now validated +address in step (8). + +Address data, TAN codes and meta-data such as the number +of failed attempts to submit a TAN code are recorded +in a Postgres database by the Challenger service. + +@node Installation,Configuration Fundamentals,Introduction,Top +@anchor{taler-challenger-manual challengerinstallation}@anchor{6}@anchor{taler-challenger-manual installation}@anchor{7} +@chapter Installation + + +In this guide’s shell-session fragments, the command prompt shows two pieces +of information: + + +@itemize * + +@item +Who is performing the command +(@code{$user} vs @code{root}, and ending character @code{$} vs @code{#}). +@end itemize + +@menu +* Installing from source:: +* Installing the Challenger binary packages on Debian:: +* Installing the GNU Taler binary packages on Trisquel:: +* Installing the GNU Taler binary packages on Ubuntu:: +* Services@comma{} users@comma{} groups and file system hierarchy: Services users groups and file system hierarchy. + +@end menu + +@node Installing from source,Installing the Challenger binary packages on Debian,,Installation +@anchor{taler-challenger-manual installing-from-source}@anchor{8} +@section Installing from source + + +The following instructions will show how to install libgnunetutil and +the core GNU Taler libraries from source. + +The package sources can be find in our +download directory@footnote{http://ftpmirror.gnu.org/taler/}. + +GNU Taler components version numbers follow the @code{MAJOR.MINOR.MICRO} format. +The general rule for compatibility is that @code{MAJOR} and @code{MINOR} must match. +Exceptions to this general rule are documented in the release notes. +For example, Challenger 1.3.0 should be compatible with Taler exchange 1.4.x +as the MAJOR version matches. A MAJOR version of 0 indicates experimental +development, and you are expected to always run all of the `latest' releases +together (no compatibility guarantees). + +First, the following packages need to be installed before we can compile the +backend: + + +@itemize - + +@item +“Sphinx RTD Theme” Python package aka @code{python3-sphinx-rtd-theme} +on Debian-based systems (for GNUnet documentation support, can be +omitted if GNUnet is configured with @code{--disable-documentation}) + +@item +libsqlite3 >= 3.16.2 + +@item +GNU libunistring >= 0.9.3 + +@item +libcurl >= 7.26 (or libgnurl >= 7.26) + +@item +libqrencode >= 4.0.0 (Taler merchant only) + +@item +GNU libgcrypt >= 1.6 (1.10 or later highly recommended) + +@item +libsodium >= 1.0 + +@item +libargon2 >= 20171227 + +@item +libjansson >= 2.7 + +@item +PostgreSQL >= 15, including libpq + +@item +GNU libmicrohttpd >= 0.9.71 + +@item +GNUnet >= 0.20 (from source tarball@footnote{http://ftpmirror.gnu.org/gnunet/}) + +@item +Python3 with @code{jinja2} +@end itemize + +If you are on Debian stable or later, the following command may help you +install these dependencies: + +@example +# apt-get install \ + libqrencode-dev \ + libsqlite3-dev \ + libltdl-dev \ + libunistring-dev \ + libsodium-dev \ + libargon2-dev \ + libcurl4-gnutls-dev \ + libgcrypt20-dev \ + libjansson-dev \ + libpq-dev \ + libmicrohttpd-dev \ + python3-jinja2 \ + postgresql-15 +@end example + +Before you install GNUnet, you must download and install the dependencies +mentioned in the previous section, otherwise the build may succeed, but could +fail to export some of the tooling required by GNU Taler. + +On Ubuntu, you also need to install pkg-config, for example: + +@example +$ apt-get install pkg-config +@end example + +To install GNUnet, unpack the tarball and change +into the resulting directory, then proceed as follows: + +@example +$ ./configure [--prefix=GNUNETPFX] +$ # Each dependency can be fetched from non standard locations via +$ # the '--with-<LIBNAME>' option. See './configure --help'. +$ make +# make install +# ldconfig +@end example + +If you did not specify a prefix, GNUnet will install to @code{/usr/local}, +which requires you to run the last step as @code{root}. +The @code{ldconfig} command (also run as @code{root}) makes the +shared object libraries (@code{.so} files) +visible to the various installed programs. + +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + +There is no need to actually run a GNUnet peer or a Taler exchange to use +Challenger – all Challenger needs from GNUnet and Taler are a number of +headers and libraries! + +After installing GNUnet, unpack the GNU Taler exchange tarball, +change into the resulting directory, and proceed as follows: + +@example +$ ./configure [--prefix=EXCHANGEPFX] \ + [--with-gnunet=GNUNETPFX] +$ # Each dependency can be fetched from non standard locations via +$ # the '--with-<LIBNAME>' option. See './configure --help'. +$ make +# make install +@end example + +If you did not specify a prefix, the exchange will install to @code{/usr/local}, +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. + +TBD. + +Please note that unlike most packages, if you want to run the @code{make check} +command, you should run it only `after' having done @code{make install}. The +latter ensures that necessary binaries are copied to the right place. + +In any case, if @code{make check} fails, please consider filing a +bug report with the Taler bug tracker@footnote{https://bugs.taler.net}. + +@node Installing the Challenger binary packages on Debian,Installing the GNU Taler binary packages on Trisquel,Installing from source,Installation +@anchor{taler-challenger-manual installing-the-challenger-binary-packages-on-debian}@anchor{9} +@section Installing the Challenger binary packages on Debian + + +To install the GNU Taler Debian packages, first ensure that you have +the right Debian distribution. At this time, the packages are built for +Debian bookworm. + +You need to 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 [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/debian bookworm 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 /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# apt update +@end example + +@cartouche +@quotation Note +You may want to verify the correctness of the Taler Systems SA 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 Challenger, you can now simply run: + +@example +# apt install challenger +@end example + +Note that the package does not perform any configuration work except for +setting up the various users and the systemd service scripts. You still must +configure at least the database, HTTP reverse proxy (typically with TLS +certificates) and the terms of service. + +@node Installing the GNU Taler binary packages on Trisquel,Installing the GNU Taler binary packages on Ubuntu,Installing the Challenger binary packages on Debian,Installation +@anchor{taler-challenger-manual installing-the-gnu-taler-binary-packages-on-trisquel}@anchor{a} +@section Installing the GNU Taler binary packages on Trisquel + + +To install the GNU Taler Trisquel packages, first ensure that you have +the right Trisquel distribution. Packages are currently available for +Trisquel GNU/Linux 10.0. Simply follow the same instructions provided +for Ubuntu. + +@node Installing the GNU Taler binary packages on Ubuntu,Services users groups and file system hierarchy,Installing the GNU Taler binary packages on Trisquel,Installation +@anchor{taler-challenger-manual installing-the-gnu-taler-binary-packages-on-ubuntu}@anchor{b} +@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 Lunar and Ubuntu Jammy. Make sure to have @code{universe} in your +@code{/etc/apt/sources.list} (after @code{main}) as we depend on some packages +from Ubuntu @code{universe}. + +A typical @code{/etc/apt/sources.list.d/taler.list} file for this setup +would look like this for Ubuntu Lunar: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ lunar taler-lunar +@end example + +For Ubuntu Mantic use this instead: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ mantic taler-mantic +@end example + +For Ubuntu Noble use this instead: + +@example +deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ noble taler-noble +@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 /etc/apt/keyrings/taler-systems.gpg \ + https://taler.net/taler-systems.gpg +# 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 exchange, you can now simply run: + +@example +# apt install challenger +@end example + +Note that the package does not perform any configuration work except for +setting up the various users and the systemd service scripts. You still must +configure at least the database, HTTP reverse proxy (typically with TLS +certificates), and the terms of service. + +@node Services users groups and file system hierarchy,,Installing the GNU Taler binary packages on Ubuntu,Installation +@anchor{taler-challenger-manual services-users-groups-and-file-system-hierarchy}@anchor{c} +@section Services, users, groups and file system hierarchy + + +The `challenger' package will use several system users +to compartmentalize different parts of the system: + + +@itemize * + +@item +@code{challenger-httpd}: runs the HTTP daemon with the core business logic. + +@item +@code{postgres}: runs the PostgreSQL database (from `postgresql' package). + +@item +@code{www-data}: runs the frontend HTTPS service with the TLS keys (from `nginx' package). +@end itemize + +The package will deploy a systemd service files in +@code{/usr/lib/systemd/system/} for Challenger: + + +@itemize * + +@item +@code{challenger-httpd.service}: the Challenger logic with the public REST API. +@end itemize + +@node Configuration Fundamentals,Deployment,Installation,Top +@anchor{taler-challenger-manual configuration-fundamentals}@anchor{d} +@chapter Configuration Fundamentals + + +This chapter provides fundamental details about the exchange configuration. + +The configuration for all Taler components uses a single configuration file +as entry point: @code{/etc/challenger/challenger.conf}. + +System defaults are automatically loaded from files in +@code{/usr/share/challenger/config.d}. These default files should never be modified. + +The default configuration @code{challenger.conf} configuration file also includes all +configuration files in @code{/etc/challenger/conf.d}. + +To view the entire configuration annotated with the source of each configuration option, you +can use the @code{challenger-config} helper: + +@example +[root@@exchange-online]# challenger-config --diagnostics +< ... annotated, full configuration ... > +@end example + +@cartouche +@quotation Warning +While @code{challenger-config} also supports rewriting configuration files, we strongly +recommend to edit configuration files manually, as @code{challenger-config} does not +preserve comments and, by default, rewrites @code{/etc/challenger/challenger.conf}. +@end quotation +@end cartouche + +@menu +* Configuration format:: +* Fundamental Setup; Address validation: Fundamental Setup Address validation. +* Legal conditions for using the service:: +* Terms of Service:: +* Privacy Policy:: +* Legal policies directory layout:: +* Generating the Legal Terms:: +* Adding translations:: +* Updating legal documents:: +* Database Configuration:: + +@end menu + +@node Configuration format,Fundamental Setup Address validation,,Configuration Fundamentals +@anchor{taler-challenger-manual configuration-format}@anchor{e} +@section Configuration format + + +All GNU Taler components are designed to possibly share the same +configuration files. When installing a GNU Taler component, the +installation deploys default values in configuration files located +at $@{prefix@}/share/taler/config.d/ where $@{prefix@} is the installation +prefix. Different components must be installed to the same prefix. + +In order to override these defaults, the user can write a custom configuration +file and either pass it to the component at execution time using the `-c' +option, or name it taler.conf and place it under $HOME/.config/ which is where +components will look by default. Note that the systemd service files pass @code{-c +/etc/taler/taler.conf}, thus making @code{/etc/taler/taler.conf} +the primary location for the configuration. + +A config file is a text file containing sections, and each section +contains maps options to their values. Configuration files follow +basically the INI syntax: + +@example +[section1] +value1 = string +value2 = 23 + +[section2] +value21 = string +value22 = /path22 +@end example + +Comments start with a hash (@code{#}). Throughout the configuration, it is +possible to use @code{$}-substitution for options relating to names of files or +directories. It is also possible to provide defaults values for those +variables that are unset, by using the following syntax: +@code{$@{VAR:-default@}}. There are two ways a user can set the value +of @code{$}-prefixable variables: + + +@enumerate + +@item +by defining them under a @code{[paths]} section: + +@example +[paths] +TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data +.. +[section-x] +path-x = $@{TALER_DEPLOYMENT_SHARED@}/x +@end example + +@item +or by setting them in the environment: + +@example +$ export VAR=/x +@end example +@end enumerate + +The configuration loader will give precedence to variables set under +@code{[path]} over environment variables. + +The utility @code{taler-config}, which gets installed along with the exchange, +can be used get and set configuration values without directly editing the +configuration file. The option @code{-f} is particularly useful to resolve +pathnames, when they use several levels of @code{$}-expanded variables. See +@code{taler-config --help}. + +The repository @code{git://git.taler.net/deployment} contains example code +for generating configuration files under @code{deployment/netzbon/}. + +@node Fundamental Setup Address validation,Legal conditions for using the service,Configuration format,Configuration Fundamentals +@anchor{taler-challenger-manual fundamental-setup-address-validation}@anchor{f} +@section Fundamental Setup: Address validation + + +Each challenger service is designed to validate one type of address. Possible +address types include: + + +@itemize * + +@item +phone numbers (via SMS) + +@item +e-mail addresses (via SMTP) + +@item +mail addresses (via postal service) +@end itemize + +In principle, additional types of addresses can easily be added by extending +the respective HTML and programs to send challenges to the new address type. + +To make different types of address validations possible, the Challenger +configuration contains two configuration options. + + +@enumerate + +@item +The @code{ADDRESS_TYPE} configuration option informs Challenger about the +type of address it is expected to validate. It is returned as part of +the OAuth 2.0 @code{/info} endpoint to the client, and is typically also +used when deciding how to render the HTML form for address entry that is +shown to the user. + +@item +The @code{AUTH_COMMAND} configuration option specifies which command +Challenger should run to send a challenge to an address. The actual +address is given to this subcommand as the first argument (@code{$1}), +while the text with the challenge is passed to standard input. +The subcommand should terminate with a status code of 0 on success. +@end enumerate + + +@float LiteralBlock + +@caption{/etc/challenger/challenger.conf} + +@example + [challenger] + ADDRESS_TYPE = email + AUTH_COMMAND = challenger-send-email.sh + # ... rest of file ... +@end example + +@end float + + +Challenger comes with @code{AUTH_COMMAND} shell scripts for sending e-mail, SMS +and postal mail. Note that for SMS and postal mail the Challenger scripts uses +third party services to actually send the SMS or print and mail the postal +mail. These third parties naturally charge money for their services, and thus +the Challenger administrator will need to add the respective credentials to +the SMS and postal mail scripts before they can function. In any case, these +scripts should be primarily seen as `examples' on how to write authentication +commands. + +@cartouche +@quotation Note +We strongly welcome contributions for additional scripts with alternative +providers or for new types of addresses. +@end quotation +@end cartouche + +@node Legal conditions for using the service,Terms of Service,Fundamental Setup Address validation,Configuration Fundamentals +@anchor{taler-challenger-manual legal-conditions-for-using-the-service}@anchor{10} +@section Legal conditions for using the service + + +@c This file is part of GNU TALER. +@c +@c Copyright (C) 2014-2023 Taler Systems SA +@c +@c TALER is free software; you can redistribute it and/or modify it under the +@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 Affero General Public License for more details. +@c +@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 + +The service has well-known API endpoints to return its legal conditions to the +user in various languages and various formats. This section describes how to +setup and configure the legal conditions. + +@node Terms of Service,Privacy Policy,Legal conditions for using the service,Configuration Fundamentals +@anchor{taler-challenger-manual terms-of-service}@anchor{11} +@section Terms of Service + + +The service has an endpoint “/terms” to return the terms of service (in legal +language) of the service operator. Client software show these terms of +service to the user when the user is first interacting with the service. +Terms of service are optional for experimental deployments, if none are +configured, the service will return a simple statement saying that there are +no terms of service available. + +To configure the terms of service response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@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 +the respective files in @code{TERMS_DIR} (see below). + +@item +@code{TERMS_DIR}: The directory that contains the terms of service. +The files in the directory must be readable to the service +process. +@end itemize + +@node Privacy Policy,Legal policies directory layout,Terms of Service,Configuration Fundamentals +@anchor{taler-challenger-manual privacy-policy}@anchor{12} +@section Privacy Policy + + +The service has an endpoint “/pp” to return the terms privacy policy (in legal +language) of the service operator. Clients should show the privacy policy to +the user when the user explicitly asks for it, but it should not be shown by +default. Privacy policies are optional for experimental deployments, if none +are configured, the service will return a simple statement saying that there +is no privacy policy available. + +To configure the privacy policy response, there are two options +in the configuration file for the service: + + +@itemize - + +@item +@code{PRIVACY_ETAG}: The current “Etag” to return for the privacy policy. +This value must be changed whenever the privacy policy is +updated. A common value to use would be a version number. +Note that if you change the @code{PRIVACY_ETAG}, you MUST also provide +the respective files in @code{PRIVACY_DIR} (see below). + +@item +@code{PRIVACY_DIR}: The directory that contains the privacy policy. +The files in the directory must be readable to the service +process. +@end itemize + +@node Legal policies directory layout,Generating the Legal Terms,Privacy Policy,Configuration Fundamentals +@anchor{taler-challenger-manual legal-policies-directory-layout}@anchor{13} +@section Legal policies directory layout + + +The @code{TERMS_DIR} and @code{PRIVACY_DIR} directory structures must follow a +particular layout. You may use the same directory for both the terms of +service and the privacy policy, as long as you use different ETAGs. Inside of +the directory, there should be sub-directories using 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. + +Then, inside each language directory, files with the name of the value set as +the @code{TERMS_ETAG} or @code{PRIVACY_ETAG} must be provided. The extension of each +of the files should be typical for the respective mime type. The set of +supported mime types is currently hard-coded in the service, and includes +“.epub”, “.html”, “.md”, “.pdf” and “.txt” files. If other files are present, +the service may show a warning on startup. + +@menu +* Example:: + +@end menu + +@node Example,,,Legal policies directory layout +@anchor{taler-challenger-manual example}@anchor{14} +@subsection Example + + +A sample file structure for a @code{TERMS_ETAG} of “tos-v0” would be: + + +@itemize - + +@item +TERMS_DIR/en/tos-v0.txt + +@item +TERMS_DIR/en/tos-v0.html + +@item +TERMS_DIR/en/tos-v0.pdf + +@item +TERMS_DIR/en/tos-v0.epub + +@item +TERMS_DIR/en/tos-v0.md + +@item +TERMS_DIR/de/tos-v0.txt + +@item +TERMS_DIR/de/tos-v0.html + +@item +TERMS_DIR/de/tos-v0.pdf + +@item +TERMS_DIR/de/tos-v0.epub + +@item +TERMS_DIR/de/tos-v0.md +@end itemize + +If the user requests an HTML format with language preferences “fr” followed by +“en”, the service would return @code{TERMS_DIR/en/tos-v0.html} lacking a version in +French. + +@node Generating the Legal Terms,Adding translations,Legal policies directory layout,Configuration Fundamentals +@anchor{taler-challenger-manual generating-the-legal-terms}@anchor{15} +@section Generating the Legal Terms + + +The @code{taler-terms-generator} script can be used to generate directories with +terms of service and privacy policies in multiple languages and all required +data formats from a single source file in @code{.rst} format and GNU gettext +translations in @code{.po} format. + +To use the tool, you need to first write your legal conditions in English in +reStructuredText (rst). You should find a templates in +@code{$PREFIX/share/terms/*.rst} where @code{$PREFIX} is the location where you +installed the service to. Whenever you make substantive changes to the legal +terms, you must use a fresh filename and change the respective @code{ETAG}. The +resulting file must be called @code{$ETAG.rst} and the first line of the file should be the title of the document. + +Once you have written the @code{$ETAG.rst} file in English, you can +generate the first set of outputs: + +@example +$ taler-terms-generator -i $ETAG +@end example + +Afterwards, you should find the terms in various formats for all configured +languages (initially only English) in @code{$PREFIX/share/terms/}. The generator +has a few options which are documented in its man page. + +@node Adding translations,Updating legal documents,Generating the Legal Terms,Configuration Fundamentals +@anchor{taler-challenger-manual adding-translations}@anchor{16} +@section Adding translations + + +Translations must be available in subdirectories +@code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po}. +To start translating, you first need to add a new +language: + +@example +$ taler-terms-generator -i $ETAG -l $LANGUAGE +@end example + +Here, @code{$LANGUAGE} should be a two-letter language +code like @code{de} or @code{fr}. The command will generate +a file @code{locale/$LANGUAGE/LC_MESSAGES/$ETAG.po} +which contains each English sentence or paragraph +in the original document and an initially empty +translation. Translators should update the @code{.po} +file. Afterwards, simply re-run + +@example +$ taler-terms-generator -i $ETAG +@end example + +to make the current translation(s) available to the +service. + +@cartouche +@quotation Note +You must restart the service whenever adding or updating legal documents or their translations. +@end quotation +@end cartouche + +@node Updating legal documents,Database Configuration,Adding translations,Configuration Fundamentals +@anchor{taler-challenger-manual updating-legal-documents}@anchor{17} +@section Updating legal documents + + +When making minor changes without legal implications, edit the @code{.rst} file, +then re-run the step to add a new language for each existing translation to +produce an updated @code{.po} file. Translate the sentences that have changed and +finally run the generator (without @code{-l}) on the ETAG (@code{-i $ETAG}) to +create the final files. + +When making major changes with legal implications, you should first rename (or +copy) the existing @code{.rst} file and the associated translation files to a new +unique name. Afterwards, make the major changes, update the @code{.po} files, +complete the translations and re-create the final files. Finally, do not +forget to update the @code{ETAG} configuration option to the new name and to +restart the service. + +@node Database Configuration,,Updating legal documents,Configuration Fundamentals +@anchor{taler-challenger-manual database-configuration}@anchor{18} +@section Database Configuration + + +The access credentials for the Challenger database are configured in +@code{/etc/challenger/challenger.conf}. Currently, only PostgreSQL is +supported as a database backend. + +@cartouche +@quotation Note +The `challenger-dbconfig' tool can be used to automate the database +setup. When using the Debian/Ubuntu packages, the user should already have +been created, so you can just run the tool without any arguments and should +have a working database configuration. Subsequently, you should still run +`taler-challenger-dbinit' as the @code{challenger-httpd} user to +initialize the database schema. +@end quotation +@end cartouche + +To create a database for Challenger on the local system, run: + +@example +[root@@exchange-online]# su - postgres +[postgres@@exchange-online]# createuser challenger-httpd +[postgres@@exchange-online]# createdb -O challenger-httpd challenger +[postgres@@exchange-online]# exit +@end example + +This will create a @code{challenger} database owned by the @code{taler-httpd} user. +We will use that user later to perform database maintenance operations. + +Assuming the above database setup, the database credentials to configure +in the configuration file would simply be: + + +@float LiteralBlock + +@caption{/etc/challenger/challenger.conf} + +@example +[challenger] +DB = postgres + +[challenger-postgres] +CONFIG = postgres:///challenger +@end example + +@end float + + +If the database is run on a different host, please follow the instructions +from the PostgreSQL manual for configuring remote access. + +After configuring the database credentials, the Challenger database needs +to be initialized with the following command: + +@example +[root@@exchange-online]# sudo -u challenger-httpd challenger-dbinit +@end example + +@cartouche +@quotation Note +To run this command, the user must have @code{CREATE TABLE}, @code{CREATE +INDEX}, @code{ALTER TABLE} and (in the future possibly even) @code{DROP TABLE} +permissions. Those permissions are only required for this step (which may +have to be repeated when upgrading a deployment). Afterwards, during +normal operation, permissions to @code{CREATE} or @code{ALTER} tables are not +required by Challenger and thus should not be granted. For more +information, see manpages/challenger-dbinit.1. +@end quotation +@end cartouche + +@node Deployment,Template Customization,Configuration Fundamentals,Top +@anchor{taler-challenger-manual deployment}@anchor{19} +@chapter Deployment + + +This chapter describes how to deploy Challenger once the basic installation +and configuration are completed. + +@menu +* Serving:: +* Reverse Proxy Setup:: +* Launching Challenger:: +* Authorizing clients:: +* OAuth 2.0 integration: OAuth 2 0 integration. +* Database management:: + +@end menu + +@node Serving,Reverse Proxy Setup,,Deployment +@anchor{taler-challenger-manual challengerserving}@anchor{1a}@anchor{taler-challenger-manual serving}@anchor{1b} +@section Serving + + +The Challenger can serve HTTP over both TCP and UNIX domain socket. + +The following options are to be configured in the section @code{[challenger]}: + + +@itemize - + +@item +@code{SERVE}: Must be set to @code{tcp} to serve HTTP over TCP, or @code{unix} to serve +HTTP over a UNIX domain socket. + +@item +@code{PORT}: Set to the TCP port to listen on if @code{SERVE} is @code{tcp}. + +@item +@code{UNIXPATH}: Set to the UNIX domain socket path to listen on if @code{SERVE} is +@code{unix}. + +@item + +@table @asis + +@item @code{UNIXPATH_MODE}: Number giving the mode with the access permission mask + +for the @code{UNIXPATH} (i.e. 660 = @code{rw-rw---}). Make sure to set it in such +a way that your reverse proxy has permissions to access the UNIX domain +socket. The default (660) assumes that the reverse proxy is a member of +the group under which the exchange HTTP server is running. +@end table +@end itemize + +@node Reverse Proxy Setup,Launching Challenger,Serving,Deployment +@anchor{taler-challenger-manual challengerreverseproxy}@anchor{1c}@anchor{taler-challenger-manual reverse-proxy-setup}@anchor{1d} +@section Reverse Proxy Setup + + +By default, the @code{challenger-httpd} service listens for HTTP connections +on a UNIX domain socket. To make the service publicly available, a reverse +proxy such as nginx should be used. You must configure the reverse proxy +to use TLS as this is required by OAuth 2.0. + +The @code{challenger} package ships with a sample configuration that can be +enabled in nginx: + +@example +[root@@exchange-online]# vim /etc/nginx/sites-available/challenger +< ... customize configuration ... > +[root@@exchange-online]# ln -s /etc/nginx/sites-available/challenger \ + /etc/nginx/sites-enabled/challenger +[root@@exchange-online]# systemctl reload nginx +@end example + +@node Launching Challenger,Authorizing clients,Reverse Proxy Setup,Deployment +@anchor{taler-challenger-manual launching-challenger}@anchor{1e} +@section Launching Challenger + + +A running exchange requires starting the following processes: + + +@itemize - + +@item +@code{challenger-httpd} (needs database access) +@end itemize + +The processes should be started via a hypervisor like +@code{systemd} or @code{gnunet-arm} that automatically re-starts them should they +have terminated unexpectedly. Furthermore, the hypervisor +`should' periodically re-start the service (say once per hour) +to limit Postgres database memory utilization. + +@cartouche +@quotation Note +The @code{challenger-httpd} does not ship with HTTPS enabled by default. +It must thus be run behind an HTTPS reverse proxy that performs +TLS termination on the same system. Thus, it would typically be configured +to listen on a UNIX domain socket. +@end quotation +@end cartouche + +Given proper packaging, all of the above are realized via a simple systemd +target. This enables Challenger to be properly started using a simple command: + +@example +# systemctl start challenger-httpd.service +@end example + +@node Authorizing clients,OAuth 2 0 integration,Launching Challenger,Deployment +@anchor{taler-challenger-manual authorizing-clients}@anchor{1f} +@section Authorizing clients + + +Before clients can use Challenger, they must be explicitly configured. Each +client is identified via its OAuth 2.0 REDIRECT URI. Thus, a client must have +exactly one REDIRECT URI + +@cartouche +@quotation Note +The OAuth 2.0 specification allows for a client to register +zero or multiple REDIRECT URIs. However, zero is insecure +as it creates an open redirector, and multiple REDIRECT URIs +can trivially be implemented with Challenger by adding more +clients. +@end quotation +@end cartouche + +You can add or remove clients at any time; the Challenger service does not +need to be running, but if it is you can still add or remove clients without +restarting the service. To add (or remove) a client, you must use the +@code{challenger-admin} command: + +@example +# sudo -u challenger-httpd challenger-admin --add=$SECRET $REDIRECT_URI +@end example + +Here, @code{$SECRET} is the client secret of OAuth 2.0 which will be used in +various parts of the protocol to authenticate the client. The +@code{$REDIRECT_URI} is the URI where the user-agent will be redirected to upon +completion of the process. The @code{challenger-admin} command will +then output the `client ID', which will be a unique positive number. +The first time you run the command, you will thus likely see: +@code{Client added. Client ID is: 1}. This client ID, the @code{$SECRET} +and the @code{$REDIRECT_URI} will form the foundation for the OAuth 2.0 +configuration. + +@node OAuth 2 0 integration,Database management,Authorizing clients,Deployment +@anchor{taler-challenger-manual oauth-2-0-integration}@anchor{20} +@section OAuth 2.0 integration + + +When integrating Challenger into an OAuth 2.0 process, you need to provide the +three options from the previous section, but also the authorization, token and +info endpoints. For Challenger, these are @code{/authorize}, @code{/token} and +@code{/info}. However, the @code{/authorize} endpoint is special, as it is actually +@code{/authorize/$NONCE} where @code{$NONCE} is a nonce that must be first requested +by the client using the @code{/setup/$CLIENT_ID} endpoint! + +@cartouche +@quotation Note +This extra step prevents user-agents from (ab)using the Challenger service +to send challenges to addresses even when there is no authorized client +that desires address validation. This is an important feature as address +validation could be expensive. +@end quotation +@end cartouche + +Thus, to generate the authorization URL, a client must first POST to +@code{/setup/$CLIENT_ID} using their client secret in an @code{Authorization: Bearer $SECRET} +HTTP header to obtain a fresh @code{$NONCE}. + +In the GNU Taler exchange configuration, this is indicated by appending +@code{#setup} to the @code{KYC_OAUTH2_AUTHORIZE_URL} endpoint. Be careful to quote +the URL, as @code{#} is otherwise interpreted as the beginning of a comment by +the configuration file syntax: + + +@float LiteralBlock + +@caption{/etc/taler/conf.d/exchange-oauth2.conf} + +@example +[kyc-provider-example-oauth2] +LOGIC = oauth2 +# (generic options omitted) +KYC_OAUTH2_AUTHORIZE_URL = "https://challenger.example.com/authorize#setup" +KYC_OAUTH2_TOKEN_URL = "https://challenger.example.com/token" +KYC_OAUTH2_INFO_URL = "https://challenger.example.com/info" +KYC_OAUTH2_CLIENT_ID = 1 +KYC_OAUTH2_CLIENT_SECRET = "$SECRET" +@end example + +@end float + + +@node Database management,,OAuth 2 0 integration,Deployment +@anchor{taler-challenger-manual database-management}@anchor{21} +@section Database management + + +@cartouche +@quotation Note +We advise to make good backups before experimenting with +the database. +@end quotation +@end cartouche + +To update the Challenger database after upgrading to a newer +version of Challenger, you should simply re-run @code{challenger-dbinit}. +Without further options, this command is expected to preserve +all data and only migrate the existing database to the latest +schema: + +@example +$ challenger-dbinit +@end example + +To delete stale data from the Challenger database, you can use +garbage collection: + +@example +$ challenger-dbinit --garbagecollect +@end example + +The Challenger database can be re-initialized using: + +@example +$ challenger-dbinit --reset +@end example + +However, running this command will result in all data in the database +being lost. + +@node Template Customization,,Deployment,Top +@anchor{taler-challenger-manual challengercustomization}@anchor{22}@anchor{taler-challenger-manual template-customization}@anchor{23} +@chapter Template Customization + + +The Challenger service comes with various HTML templates that are shown to +guide users through the process. Challenger uses C implementation of mustache@footnote{https://gitlab.com/jobol/mustach} as the templating engine. This section +describes the various templates. In general, the templates must be installed +to the @code{share/challenger/templates/} directory. The file names must be of +the form @code{$NAME.$LANG.must} where @code{$NAME} is the name of the template and +@code{$LANG} is the 2-letter language code of the template. English templates +must exist and will be used as a fallback. If the browser (user-agent) has +provided language preferences in the HTTP header and the respective language +exists, the correct language will be automatically served. + +The following subsections give details about each of the templates. The +subsection title is the @code{$NAME} of the respective template. + +@menu +* enter-$ADDRESS_TYPE-form:: +* enter-tan-form:: +* invalid-pin:: +* validation-unknown:: +* invalid-request:: +* internal-error:: + +@end menu + +@node enter-$ADDRESS_TYPE-form,enter-tan-form,,Template Customization +@anchor{taler-challenger-manual challenger-enter-address-type-form}@anchor{24}@anchor{taler-challenger-manual enter-address-type-form}@anchor{25} +@section enter-$ADDRESS_TYPE-form + + +These templates are used to ask the user to enter the address that challenger +is expected to validate. Here, @code{$ADDRESS_TYPE} will be replaced by the +@code{ADDRESS_TYPE} configuration option in the @code{[challenger]} section of the +configuration file. Typical values include @code{address} (for physical mailing +addresses), @code{phone} (for mobile phone numbers) and @code{email} (for email +addresses). For testing, @code{file} (where the TAN code is written into a local +file) is also supported. + +The template is instantiated using the following information: + + +@itemize * + +@item +restrictions: Object; map of keys (names of the fields of the +address to be entered by the user) to objects with a “regex” +(string) containing an extended Posix regular expression for +allowed address field values, and a “hint”/”hint_i18n” giving +a human-readable explanation to display if the value entered +by the user does not match the regex. Keys that are not mapped +to such an object have no restriction on the value provided by +the user. See “ADDRESS_RESTRICTIONS” in the challenger +configuration. + +@item +fix_address: boolean; indicates if the given address cannot be changed +anymore, the form should be read-only if set to true. + +@item +nonce: String; unique value identifying the challenge, should be shown +to the user so that they can recognize it when they receive the TAN code + +@item +last_address: Object; form values from the previous submission if available, +details depend on the @code{ADDRESS_TYPE}, should be used to pre-populate the form + +@item +changes_left: Integer; number of times the address can still be changed, +may or may not be shown to the user +@end itemize + +@node enter-tan-form,invalid-pin,enter-$ADDRESS_TYPE-form,Template Customization +@anchor{taler-challenger-manual challenger-enter-tan-form}@anchor{26}@anchor{taler-challenger-manual enter-tan-form}@anchor{27} +@section enter-tan-form + + +This page should generate the HTML form for the user to enter the TAN code +that they received at the respective address. + +The template is instantiated using the following information: + + +@itemize * + +@item +nonce: String; unique value identifying the challenge, should be shown +to the user so that they can match it to the TAN code they received + +@item +attempts_left: Integer; how many more attempts are allowed, might be +shown to the user, highlighting might be appropriate for low values +such as 1 or 2 (the form will never be used if the value is zero) + +@item +address: Object; the address that is being validated, might be shown +or not + +@item +transmitted: boolean; true if we just retransmitted the challenge, +false if we sent a challenge recently and thus refused to transmit it +again this time; might make a useful hint to the user + +@item +next_tx_time: String; timestamp explaining when we would re-transmit +the challenge the next time (at the earliest) if requested by the user +@end itemize + +@node invalid-pin,validation-unknown,enter-tan-form,Template Customization +@anchor{taler-challenger-manual challenger-invalid-pin}@anchor{28}@anchor{taler-challenger-manual invalid-pin}@anchor{29} +@section invalid-pin + + +The user has provided an invalid TAN code (HTTP 403 Forbidden). + +The template is instantiated using the following information: + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +addresses_left: Integer; how many times is the user still allowed to +change the address; if 0, the user should not be shown a link to jump +to the address entry form + +@item +pin_transmissions_left: Integer; how many times might the PIN still +be retransmitted + +@item +auth_attempts_left: Integer; how many times might the user still try +entering the PIN code + +@item +exhausted: Bool; if true, the PIN was not even evaluated as the user +previously exhausted the number of attempts + +@item +no_challenge: Bool; if true, the PIN was not even evaluated as no +challenge was ever issued (the user must have skipped the step of +providing their address first!) +@end itemize + +If both `pin_transmissions_left' and `auth_attempts_left' are zero, the link +to re-enter the PIN should be hidden and the user should only be allowed to +specify a different address. The form will never be generated if all three +values are zero. (Thus there is always at least one valid choice when the form +is shown.) + +@node validation-unknown,invalid-request,invalid-pin,Template Customization +@anchor{taler-challenger-manual challenger-validation-unknown}@anchor{2a}@anchor{taler-challenger-manual validation-unknown}@anchor{2b} +@section validation-unknown + + +The user has tried to access a validation process that is not known to the +backend (HTTP 404 Not Found). + +The template is instantiated using the following information: + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +detail: String; optional, extended human-readable text provided to elaborate +on the error, should be shown to provide additional context +@end itemize + +@node invalid-request,internal-error,validation-unknown,Template Customization +@anchor{taler-challenger-manual challenger-invalid-request}@anchor{2c}@anchor{taler-challenger-manual invalid-request}@anchor{2d} +@section invalid-request + + +The request of the client is invalid (HTTP 400 Bad Request). + +The template is instantiated using the following information: + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +detail: String; optional, extended human-readable text provided to elaborate +on the error, should be shown to provide additional context +@end itemize + +@node internal-error,,invalid-request,Template Customization +@anchor{taler-challenger-manual challenger-internal-error}@anchor{2e}@anchor{taler-challenger-manual internal-error}@anchor{2f} +@section internal-error + + +The service experienced an internal error (HTTP 500 Internal Server Error). + +The template is instantiated using the following information: + + +@itemize * + +@item +ec: Integer; numeric Taler error code, should be shown to indicate the +error compactly for reporting to developers + +@item +hint: String; human-readable Taler error code, should be shown for the +user to understand the error + +@item +detail: String; optional, extended human-readable text provided to elaborate +on the error, should be shown to provide additional context +@end itemize + +@c %**end of body +@bye |