Merge remote-tracking branch 'refs/remotes/origin/master'

1 files changed, 117 insertions, 114 deletions

diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst
index 39b06710..f9d6a793 100644
--- a/taler-challenger-manual.rst
+++ b/taler-challenger-manual.rst
@@ -225,9 +225,9 @@ 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)
+* 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.
@@ -235,17 +235,17 @@ 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.
+(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.
+(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
@@ -264,10 +264,10 @@ 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::
+.. note::
 
-    We strongly welcome contributions for additional scripts with alternative
-    providers or for new types of addresses.
+  We strongly welcome contributions for additional scripts with alternative
+  providers or for new types of addresses.
 
 
 Legal conditions for using the service
@@ -326,15 +326,15 @@ to be initialized with the following command:
 
   [root@exchange-online]# sudo -u challenger-httpd challenger-dbinit
 
-  ..note::
+.. 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`.
+  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
@@ -402,10 +402,11 @@ have terminated unexpectedly.  Furthermore, the hypervisor
 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.
+
+  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:
@@ -422,13 +423,13 @@ 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::
+.. 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.
+  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
@@ -460,12 +461,12 @@ info endpoints.  For Challenger, these are ``/authorize``, ``/token`` and
 ``/authorize/$NONCE`` where ``$NONCE`` is a nonce that must be first requested
 by the client using the ``/setup/$CLIENT_ID`` endpoint!
 
-  ..note::
+.. 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.
+  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/$CLIENT_ID`` using their client secret in an ``Authorization: Bearer $SECRET``
@@ -493,10 +494,10 @@ the configuration file syntax:
 Database management
 -------------------
 
-  .. note::
+.. note::
 
-    We advise to make good backups before experimenting with
-    the database.
+  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``.
@@ -532,8 +533,8 @@ Template Customization
 ======================
 
 The Challenger service comes with various HTML templates that are shown to
-guide users through the process. Challenger uses `Mustach
-<https://gitlab.com/jbol/mustach>`__ as the templating engine.  This section
+guide users through the process. Challenger uses `C implementation of mustache
+<https://gitlab.com/jobol/mustach>`__ as the templating engine.  This section
 describes the various templates.  In general, the templates must be installed
 to the ``share/challenger/templates/`` directory. The file names must be of
 the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template and
@@ -545,6 +546,8 @@ exists, the correct language will be automatically served.
 The following subsections give details about each of the templates. The
 subsection title is the ``$NAME`` of the respective template.
 
+.. _challenger_enter-address_type-form:
+
 enter-$ADDRESS_TYPE-form
 ------------------------
 
@@ -558,18 +561,25 @@ file) is also supported.
 
 The template is instantiated using the following information:
 
-  * 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.
-  * fix_address: boolean; indicates if the given address cannot be changed
-    anymore, the form should be read-only if set to true.
-
-  * 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
-
-  * last_address: Object; form values from the previous submission if available,
-    details depend on the ``ADDRESS_TYPE``, should be used to pre-populate the form
-
-  * changes_left: Integer; number of times the address can still be changed,
-    may or may not be shown to the user
+* 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.
+* fix_address: boolean; indicates if the given address cannot be changed
+  anymore, the form should be read-only if set to true.
+* 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
+* last_address: Object; form values from the previous submission if available,
+  details depend on the ``ADDRESS_TYPE``, should be used to pre-populate the form
+* changes_left: Integer; number of times the address can still be changed,
+  may or may not be shown to the user
+
+.. _challenger_enter-tan-form:
 
 enter-tan-form
 --------------
@@ -579,23 +589,21 @@ that they received at the respective address.
 
 The template is instantiated using the following information:
 
-  * 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
-
-  * 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)
-
-  * address: Object; the address that is being validated, might be shown
-    or not
-
-  * 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
+* 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
+* 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)
+* address: Object; the address that is being validated, might be shown
+  or not
+* 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
+* next_tx_time: String; timestamp explaining when we would re-transmit
+  the challenge the next time (at the earliest) if requested by the user
 
-  * next_tx_time: String; timestamp explaining when we would re-transmit
-    the challenge the next time (at the earliest) if requested by the user
 
+.. _challenger_invalid-pin:
 
 invalid-pin
 -----------
@@ -604,25 +612,22 @@ The user has provided an invalid TAN code (HTTP 403 Forbidden).
 
 The template is instantiated using the following information:
 
-  * ec: Integer; numeric Taler error code, should be shown to indicate the
-    error compactly for reporting to developers
-
-  * hint: String; human-readable Taler error code, should be shown for the
-    user to understand the error
-
-  * 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
-
-  * pin_transmissions_left: Integer; how many times might the PIN still
-    be retransmitted
-
-  * auth_attempts_left: Integer; how many times might the user still try
-    entering the PIN code
-
-  * exhausted: Bool; if true, the PIN was not even evaluated as the user previously exhausted the number of attempts
-
-  * 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!)
+* ec: Integer; numeric Taler error code, should be shown to indicate the
+  error compactly for reporting to developers
+* hint: String; human-readable Taler error code, should be shown for the
+  user to understand the error
+* 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
+* pin_transmissions_left: Integer; how many times might the PIN still
+  be retransmitted
+* auth_attempts_left: Integer; how many times might the user still try
+  entering the PIN code
+* exhausted: Bool; if true, the PIN was not even evaluated as the user
+  previously exhausted the number of attempts
+* 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!)
 
 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
@@ -631,6 +636,8 @@ values are zero. (Thus there is always at least one valid choice when the form
 is shown.)
 
 
+.. _challenger_validation-unknown:
+
 validation-unknown
 ------------------
 
@@ -639,15 +646,14 @@ backend (HTTP 404 Not Found).
 
 The template is instantiated using the following information:
 
-  * ec: Integer; numeric Taler error code, should be shown to indicate the
-    error compactly for reporting to developers
-
-  * hint: String; human-readable Taler error code, should be shown for the
-    user to understand the error
-
-  * detail: String; optional, extended human-readable text provided to elaborate
-    on the error, should be shown to provide additional context
+* ec: Integer; numeric Taler error code, should be shown to indicate the
+  error compactly for reporting to developers
+* hint: String; human-readable Taler error code, should be shown for the
+  user to understand the error
+* detail: String; optional, extended human-readable text provided to elaborate
+  on the error, should be shown to provide additional context
 
+.. _challenger_invalid-request:
 
 invalid-request
 ---------------
@@ -656,15 +662,14 @@ The request of the client is invalid (HTTP 400 Bad Request).
 
 The template is instantiated using the following information:
 
-  * ec: Integer; numeric Taler error code, should be shown to indicate the
-    error compactly for reporting to developers
-
-  * hint: String; human-readable Taler error code, should be shown for the
-    user to understand the error
-
-  * detail: String; optional, extended human-readable text provided to elaborate
-    on the error, should be shown to provide additional context
+* ec: Integer; numeric Taler error code, should be shown to indicate the
+  error compactly for reporting to developers
+* hint: String; human-readable Taler error code, should be shown for the
+  user to understand the error
+* detail: String; optional, extended human-readable text provided to elaborate
+  on the error, should be shown to provide additional context
 
+.. _challenger_internal-error:
 
 internal-error
 --------------
@@ -673,11 +678,9 @@ The service experienced an internal error (HTTP 500 Internal Server Error).
 
 The template is instantiated using the following information:
 
-  * ec: Integer; numeric Taler error code, should be shown to indicate the
-    error compactly for reporting to developers
-
-  * hint: String; human-readable Taler error code, should be shown for the
-    user to understand the error
-
-  * detail: String; optional, extended human-readable text provided to elaborate
-    on the error, should be shown to provide additional context
+* ec: Integer; numeric Taler error code, should be shown to indicate the
+  error compactly for reporting to developers
+* hint: String; human-readable Taler error code, should be shown for the
+  user to understand the error
+* detail: String; optional, extended human-readable text provided to elaborate
+  on the error, should be shown to provide additional context