diff options
| -rw-r--r-- | conf.py | 19 | ||||
| -rw-r--r-- | index.rst | 1 | ||||
| -rw-r--r-- | libeufin/api-common.rst | 4 | ||||
| -rw-r--r-- | taler-challenger-manual.rst | 526 | ||||
| -rw-r--r-- | taler-exchange-manual.rst | 7 |
5 files changed, 555 insertions, 2 deletions
@@ -1,6 +1,6 @@ """ This file is part of GNU TALER. - Copyright (C) 2014, 2015, 2016, 2020, 2021 Taler Systems SA + Copyright (C) 2014-2023 Taler Systems SA TALER is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software @@ -17,6 +17,7 @@ @author Benedikt Muller @author Sree Harsha Totakura @author Marcello Stanisci + @author Christian Grothoff """ # -*- coding: utf-8 -*- # @@ -252,6 +253,13 @@ latex_documents = [ "manual", ), ( + "taler-challenger-manual", + "taler-challenger-manual.tex", + "GNU Taler Challenger Manual", + "GNU Taler team", + "manual", + ), + ( "taler-merchant-manual", "taler-merchant-manual.tex", "GNU Taler Merchant Manual", @@ -665,6 +673,15 @@ texinfo_documents = [ "CATEGORY", ), ( + "taler-challenger-manual", + "challenger", + "Taler Challenger Manual", + "GNU Taler team", + "MENU ENTRY", + "DESCRIPTION", + "CATEGORY", + ), + ( "taler-merchant-manual", "taler-merchant", "Taler Merchant Manual", @@ -60,6 +60,7 @@ Documentation Overview taler-merchant-manual taler-merchant-api-tutorial taler-merchant-pos-terminal + taler-challenger-manual taler-auditor-manual taler-developer-manual taler-wallet diff --git a/libeufin/api-common.rst b/libeufin/api-common.rst index 58ae7e37..dcdd87e7 100644 --- a/libeufin/api-common.rst +++ b/libeufin/api-common.rst @@ -26,7 +26,7 @@ Ratios and Fees **Note:** this quantity is normally enforced to have at most two decimal digits. The reason is to preserve the 2-decimal digits policy of the `Amount` type, as `LibeufinNumber` is used -to multiply `Amount`. +to multiply `Amount`. Amounts ^^^^^^^ @@ -54,6 +54,8 @@ apply on a resource. resourceId: string; permissionName: string } + + Fetch params ^^^^^^^^^^^^ diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst new file mode 100644 index 00000000..1497bfed --- /dev/null +++ b/taler-challenger-manual.rst @@ -0,0 +1,526 @@ +.. + This file is part of GNU TALER. + + Copyright (C) 2023 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU Affero General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License along with + TALER; see the file COPYING. If not, see <http://www.gnu.org/licenses/> + + @author Christian Grothoff + @author Florian Dold + +GNU Taler Challenger Operator Manual +#################################### + +Introduction +============ + +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 ``/info`` +endpoint. + + +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 <https://bugs.taler.net>`__. + + +Architecture overview +--------------------- + +TBC. + +.. _ChallengerInstallation: + +Installation +============ + +In this guide's shell-session fragments, the command prompt shows two pieces +of information: + +* Who is performing the command + (``$user`` vs ``root``, and ending character ``$`` vs ``#``). + + +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 <http://ftpmirror.gnu.org/taler/>`__. + +GNU Taler components version numbers follow the ``MAJOR.MINOR.MICRO`` format. +The general rule for compatibility is that ``MAJOR`` and ``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: + +.. include:: frags/list-of-dependencies.rst + +.. include:: frags/installing-gnunet.rst + +.. include:: frags/install-before-check.rst + +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! + +.. include:: frags/installing-taler-exchange.rst + +.. include:: frags/installing-challenger.rst + +.. include:: frags/install-before-check.rst + + + +Installing the Challenger binary packages on Debian +--------------------------------------------------- + +.. include:: frags/installing-debian.rst + +To install the Challenger, you can now simply run: + +.. code-block:: shell-session + + # apt install challenger + +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. + +Installing the GNU Taler binary packages on Trisquel +---------------------------------------------------- + +.. include:: frags/installing-trisquel.rst + +Installing the GNU Taler binary packages on Ubuntu +-------------------------------------------------- + +.. include:: frags/installing-ubuntu.rst + +To install the Taler exchange, you can now simply run: + +.. code-block:: shell-session + + # apt install challenger + +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. + + +Services, users, groups and file system hierarchy +------------------------------------------------- + +The *challenger* package will use several system users +to compartmentalize different parts of the system: + +* ``challenger-httpd``: runs the HTTP daemon with the core business logic. +* ``postgres``: runs the PostgreSQL database (from *postgresql* package). +* ``www-data``: runs the frontend HTTPS service with the TLS keys (from *nginx* package). + +The package will deploy a systemd service files in +``/usr/lib/systemd/system/`` for Challenger: + +* ``challenger-httpd.service``: the Challenger logic with the public REST API. + + +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: ``/etc/challenger/challenger.conf``. + +System defaults are automatically loaded from files in +``/usr/share/challenger/config.d``. These default files should never be modified. + +The default configuration ``challenger.conf`` configuration file also includes all +configuration files in ``/etc/challenger/conf.d``. + +To view the entire configuration annotated with the source of each configuration option, you +can use the ``challenger-config`` helper: + + +.. code-block:: shell-session + + [root@exchange-online]# challenger-config --diagnostics + < ... annotated, full configuration ... > + +.. warning:: + + While ``challenger-config`` also supports rewriting configuration files, we strongly + recommend to edit configuration files manually, as ``challenger-config`` does not + preserve comments and, by default, rewrites ``/etc/challenger/challenger.conf``. + +.. include:: frags/configuration-format.rst + + +Fundamental Setup: Address validation +------------------------------------- + +Each challenger service is designed to validate one type of address. Possible +address types include: + + * phone numbers (via SMS) + * e-mail addresses (via SMTP) + * mail addresses (via postal service) + +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. + + (1) The ``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 ``/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. + + (2) The ``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 (``$1``), + while the text with the challenge is passed to standard input. + The subcommand should terminate with a status code of 0 on success. + +.. code-block:: ini + :caption: /etc/challenger/challenger.conf + + [challenger] + ADDRESS_TYPE = email + AUTH_COMMAND = challenger-send-email.sh + # ... rest of file ... + +Challenger comes with ``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. + + ..note:: + + We strongly welcome contributions for additional scripts with alternative + providers or for new types of addresses. + + +Terms of Service +---------------- + +The exchange has an endpoint "/terms" to return the terms of service +(in legal language) of the Challenger operator. + +To configure the terms of service response, there are two options +in the ``[challenger]`` section: + +- ``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 ``TERMS_ETAG``, you MUST also provide + the respective files in ``TERMS_DIR`` (see below). +- ``TERMS_DIR``: The directory that contains the terms of service. + The files in the directory must be readable to the ``challenger-httpd`` + process. + +The ``TERMS_DIR`` directory structure must follow a particular layout. +First, inside of ``TERMS_DIR``, 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 ``TERMS_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 +exchange, and includes HTML, PDF and TXT files. If other files are +present, Challenger may show a warning on startup. + + +Example +^^^^^^^ + +A sample file structure for a ``TERMS_ETAG`` of "v1" would be: + +- TERMS_DIR/en/v1.txt +- TERMS_DIR/en/v1.html +- TERMS_DIR/en/v1.pdf +- TERMS_DIR/de/v1.txt +- TERMS_DIR/de/v1.html +- TERMS_DIR/de/v1.pdf +- TERMS_DIR/fr/v1.pdf + +If the user requests an HTML format with language preferences "fr" followed by "en", +Challenger would return ``TERMS_DIR/en/v1.html`` lacking an HTML version in +French. + + +Database Configuration +---------------------- + +The access credentials for the Challenger database are configured in +``/etc/challenger/challenger.conf``. Currently, only PostgreSQL is +supported as a database backend. + +To create a database for Challenger on the local system, run: + +.. code-block:: shell-session + + [root@exchange-online]# su - postgres + [postgres@exchange-online]# createuser challenger-httpd + [postgres@exchange-online]# createdb -O challenger-httpd challenger + [postgres@exchange-online]# exit + +This will create a ``challenger`` database owned by the ``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: + +.. code-block:: ini + :caption: /etc/challenger/challenger.conf + + [challenger] + DB = postgres + + [challenger-postgres] + CONFIG = postgres:///challenger + +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: + +.. code-block:: shell-session + + [root@exchange-online]# sudo -u challenger-httpd challenger + + ..note:: + + To run this command, the user must have ``CREATE TABLE``, ``CREATE + INDEX``, ``ALTER TABLE`` and (in the future possibly even) ``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 ``CREATE`` or ``ALTER`` tables are not + required by Challenger and thus should not be granted. For more + information, see :doc:`manpages/challenger-dbinit.1`. + + +Deployment +========== + +This chapter describes how to deploy Challenger once the basic installation +and configuration are completed. + +.. _ChallengerServing: + +Serving +------- + +The Challenger can serve HTTP over both TCP and UNIX domain socket. + +The following options are to be configured in the section ``[challenger]``: + +- ``SERVE``: Must be set to ``tcp`` to serve HTTP over TCP, or ``unix`` to serve + HTTP over a UNIX domain socket. + +- ``PORT``: Set to the TCP port to listen on if ``SERVE`` is ``tcp``. + +- ``UNIXPATH``: Set to the UNIX domain socket path to listen on if ``SERVE`` is + ``unix``. + +- ``UNIXPATH_MODE``: Number giving the mode with the access permission mask + for the ``UNIXPATH`` (i.e. 660 = ``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. + +.. _ChallengerReverseProxy: + +Reverse Proxy Setup +------------------- + +By default, the ``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 ``challenger`` package ships with a sample configuration that can be +enabled in nginx: + +.. code-block:: shell-session + + [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 + + +Launching Challenger +-------------------- + +A running exchange requires starting the following processes: + +- ``challenger-httpd`` (needs database access) + +The processes should be started via a hypervisor like +``systemd`` or ``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. + +.. note:: + The ``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. + +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: + +.. code-block:: shell-session + + # systemctl start challenger-httpd.service + + +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 + + ..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. + +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 +``challenger-admin`` command: + +.. code-block:: shell-session + + # sudo -u challenger-httpd challenger-admin --add=$SECRET $REDIRECT_URI + +Here, ``$SECRET`` is the client secret of OAuth 2.0 which will be used in +various parts of the protocol to authenticate the client. The +``$REDIRECT_URI`` is the URI where the user-agent will be redirected to upon +completion of the process. The ``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: +``Client added. Client ID is: 1``. This client ID, the ``$SECRET`` +and the ``$REDIRECT_URI`` will form the foundation for the OAuth 2.0 +configuration. + + +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 ``/authorize``, ``/token`` and +``/info``. However, the ``/authorize`` endpoint is special, as it is actually +``/authorize/$NONCE`` where ``$NONCE`` is a nonce that must be first requested +by the client using the ``/setup`` endpoint! + + ..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. + +Thus, to generate the authorization URL, a client must first POST to +``/setup`` using their client secret in an ``Authorization: Bearer $SECRET`` +HTTP header to obtain a fresh ``$NONCE``. + +In the GNU Taler exchange configuration, this is indicated by appending +``#setup`` to the ``KYC_OAUTH2_AUTHORIZE_URL`` endpoint. Be careful to quote +the URL, as ``#`` is otherwise interpreted as the beginning of a comment by +the configuration file syntax: + +.. code-block:: ini + :caption: /etc/taler/conf.d/exchange-oauth2.conf + + [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" + + + +Database management +------------------- + + .. note:: + + We advise to make good backups before experimenting with + the database. + +To update the Challenger database after upgrading to a newer +version of Challenger, you should simply re-run ``challenger-dbinit``. +Without further options, this command is expected to preserve +all data and only migrate the existing database to the latest +schema: + +.. code-block:: console + + $ challenger-dbinit + +To delete stale data from the Challenger database, you can use +garbage collection: + +.. code-block:: console + + $ challenger-dbinit --garbagecollect + + +The Challenger database can be re-initialized using: + +.. code-block:: console + + $ taler-exchange-dbinit --reset + +However, running this command will result in all data in the database +being lost. diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst index 55bf6369..0ff1650e 100644 --- a/taler-exchange-manual.rst +++ b/taler-exchange-manual.rst @@ -1530,6 +1530,13 @@ configuration file syntax. KYC_OAUTH2_TOKEN_URL = "http://challenger.example.com/token" KYC_OAUTH2_INFO_URL = "http://challenger.example.com/info" +When using OAuth 2.0, the *CLIENT REDIRECT URI* must be set to the +``/kyc-proof/$PROVIDER_SECTION`` endpoint. For example, given the +configuration above and an exchange running on the host +``exchange.example.com``, the redirect URI would be +``https://exchange.example.com/kyc-proof/kyc-provider-challenger-oauth2/``. + + Persona specifics ^^^^^^^^^^^^^^^^^ |