path: root/texinfo/challenger.texi

\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.9.4, Mar 07, 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 Jammy use this instead:

@example
deb [signed-by=/etc/apt/keyrings/taler-systems.gpg] https://deb.taler.net/apt/ubuntu/ jammy taler-jammy
@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 /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:

@quotation


@enumerate 

@item 
by defining them under a @code{[paths]} section:
@end enumerate

@quotation

@example
[paths]
TALER_DEPLOYMENT_SHARED = $@{HOME@}/shared-data
..
[section-x]
path-x = $@{TALER_DEPLOYMENT_SHARED@}/x
@end example
@end quotation


@enumerate 2

@item 
or by setting them in the environment:
@end enumerate

@quotation

@example
$ export VAR=/x
@end example
@end quotation
@end quotation

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:

@quotation


@itemize *

@item 
phone numbers (via SMS)

@item 
e-mail addresses (via SMTP)

@item 
mail addresses (via postal service)
@end itemize
@end quotation

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.

@quotation


@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
@end quotation


@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.

@quotation

..note:

@example
We strongly welcome contributions for additional scripts with alternative
providers or for new types of addresses.
@end example
@end quotation

@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

..note::

  To run this command, the user must have `@w{`}CREATE TABLE`@w{`}, `@w{`}CREATE
  INDEX`@w{`}, `@w{`}ALTER TABLE`@w{`} and (in the future possibly even) `@w{`}DROP TABLE`@w{`}
  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 `@w{`}CREATE`@w{`} or `@w{`}ALTER`@w{`} tables are not
  required by Challenger and thus should not be granted.  For more
  information, see :doc:`manpages/challenger-dbinit.1`.
@end example

@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

@quotation

..note:

@example
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 example
@end quotation

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!

@quotation

..note:

@example
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 example
@end quotation

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


@quotation

@cartouche
@quotation Note 
We advise to make good backups before experimenting with
the database.
@end quotation
@end cartouche
@end quotation

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 Mustach@footnote{https://gitlab.com/jbol/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 enter-address-type-form}@anchor{24}
@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:

@quotation


@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
@end quotation

@node enter-tan-form,invalid-pin,enter-$ADDRESS_TYPE-form,Template Customization
@anchor{taler-challenger-manual enter-tan-form}@anchor{25}
@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:

@quotation


@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
@end quotation

@node invalid-pin,validation-unknown,enter-tan-form,Template Customization
@anchor{taler-challenger-manual invalid-pin}@anchor{26}
@section invalid-pin


The user has provided an invalid TAN code (HTTP 403 Forbidden).

The template is instantiated using the following information:

@quotation


@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
@end quotation

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 validation-unknown}@anchor{27}
@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:

@quotation


@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
@end quotation

@node invalid-request,internal-error,validation-unknown,Template Customization
@anchor{taler-challenger-manual invalid-request}@anchor{28}
@section invalid-request


The request of the client is invalid (HTTP 400 Bad Request).

The template is instantiated using the following information:

@quotation


@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
@end quotation

@node internal-error,,invalid-request,Template Customization
@anchor{taler-challenger-manual internal-error}@anchor{29}
@section internal-error


The service experienced an internal error (HTTP 500 Internal Server Error).

The template is instantiated using the following information:

@quotation


@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
@end quotation

@c %**end of body
@bye