From da16cc31bd1136ab202e048368ff69a13ee612d0 Mon Sep 17 00:00:00 2001 From: Sebastian Date: Fri, 12 Apr 2024 10:17:21 -0300 Subject: fix #8731 --- taler-challenger-manual.rst | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) (limited to 'taler-challenger-manual.rst') diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index 39b06710..dab1d954 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -532,8 +532,8 @@ Template Customization ====================== The Challenger service comes with various HTML templates that are shown to -guide users through the process. Challenger uses `Mustach -`__ as the templating engine. This section +guide users through the process. Challenger uses `C implementation of mustache +`__ 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 +545,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 ------------------------ @@ -571,6 +573,8 @@ The template is instantiated using the following information: * 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 -------------- @@ -597,6 +601,8 @@ The template is instantiated using the following information: the challenge the next time (at the earliest) if requested by the user +.. _challenger_invalid-pin: + invalid-pin ----------- @@ -631,6 +637,8 @@ values are zero. (Thus there is always at least one valid choice when the form is shown.) +.. _challenger_validation-unknown: + validation-unknown ------------------ @@ -648,6 +656,7 @@ The template is instantiated using the following information: * 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 --------------- @@ -665,6 +674,7 @@ The template is instantiated using the following information: * 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 -------------- -- cgit v1.2.3 From 689b15e48caaa6aabf6b14b7bb7b4ad2940a34c0 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 15 Apr 2024 01:00:15 +0200 Subject: -fix notes --- core/api-challenger.rst | 32 +++++++++++++-------------- taler-challenger-manual.rst | 53 +++++++++++++++++++++++---------------------- 2 files changed, 43 insertions(+), 42 deletions(-) (limited to 'taler-challenger-manual.rst') diff --git a/core/api-challenger.rst b/core/api-challenger.rst index be8a36c3..25c84d3e 100644 --- a/core/api-challenger.rst +++ b/core/api-challenger.rst @@ -29,19 +29,19 @@ The high-level flow is that an OAuth 2.0 client is first registered with the challenger service (via command-line). Using the command-line tool will print the resulting client ID to the console. - .. note:: +.. note:: - The current service mandates that redirection URIs - start with "http://" or "https://". See issue #7838 - for what should be done to lift this restriction. + The current service mandates that redirection URIs + start with "http://" or "https://". See issue #7838 + for what should be done to lift this restriction. - .. note:: +.. note:: - Right now, registration of a unique redirection URI is *mandatory* for - each client. If multiple redirection URIs are needed, it is suggested to - just register additional clients. (While OAuth 2.0 would support not - registering fixed redirection URIs with a client, this is not recommended - as it would create an open redirector.) + Right now, registration of a unique redirection URI is *mandatory* for + each client. If multiple redirection URIs are needed, it is suggested to + just register additional clients. (While OAuth 2.0 would support not + registering fixed redirection URIs with a client, this is not recommended + as it would create an open redirector.) Once a client is registered, that client can use the challenger service when it needs a user to prove that the user is able to receive messages at a @@ -61,13 +61,13 @@ of the challenger service, adding its ``state``, ``client_id`` and redirect URI registered with the client. From this endpoint, the challenger service will return a Web page asking the user to provide its address. - .. note:: +.. note:: - Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL - makes the authorization endpoint URL (deliberately) unpredictable, while - for many other OAuth 2.0 APIs this endpoint is static. However, this is - compliant with OAuth 2.0 as determining the authorization URL is left out - of the scope of the standard. + Challenger is a bit unusual in that the ``$NONCE`` in the endpoint URL + makes the authorization endpoint URL (deliberately) unpredictable, while + for many other OAuth 2.0 APIs this endpoint is static. However, this is + compliant with OAuth 2.0 as determining the authorization URL is left out + of the scope of the standard. When the user has filled in the form with their address, it will be submitted to the ``/challenge/$NONCE`` endpoint and the challenger service will send a diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index dab1d954..4ff2b40e 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -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``. -- cgit v1.2.3 From 0aadbd53ba08f672280aac1c040776e4982c8f64 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 15 Apr 2024 01:02:22 +0200 Subject: -fix notes --- taler-challenger-manual.rst | 134 +++++++++++++++++++++----------------------- 1 file changed, 63 insertions(+), 71 deletions(-) (limited to 'taler-challenger-manual.rst') diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index 4ff2b40e..45225ecb 100644 --- a/taler-challenger-manual.rst +++ b/taler-challenger-manual.rst @@ -561,18 +561,23 @@ 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: @@ -584,22 +589,18 @@ 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 - - * next_tx_time: String; timestamp explaining when we would re-transmit - the challenge the next time (at the earliest) if requested by 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 .. _challenger_invalid-pin: @@ -611,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 @@ -648,14 +646,12 @@ 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: @@ -666,14 +662,12 @@ 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: @@ -684,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 -- cgit v1.2.3 From f56753c083eab08a3c4aa9a0b82d3ade0d253375 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 15 Apr 2024 01:08:24 +0200 Subject: -fix notes --- taler-challenger-manual.rst | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) (limited to 'taler-challenger-manual.rst') diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst index 45225ecb..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 -- cgit v1.2.3