From da16cc31bd1136ab202e048368ff69a13ee612d0 Mon Sep 17 00:00:00 2001 From: Sebastian Date: Fri, 12 Apr 2024 10:17:21 -0300 Subject: fix #8731 --- core/api-challenger.rst | 160 +++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 151 insertions(+), 9 deletions(-) (limited to 'core/api-challenger.rst') diff --git a/core/api-challenger.rst b/core/api-challenger.rst index 914d8d01..be8a36c3 100644 --- a/core/api-challenger.rst +++ b/core/api-challenger.rst @@ -168,6 +168,16 @@ Login endpoint is used by the user-agent. It will return a form to enter the address. + The NONCE is a unique value identifying the challenge, should be shown to + the user so that they can recognize it when they receive the TAN code. + + This endpoint typically also supports requests with the "Accept" header + requesting "text/html". In this case, an HTML response using the template + :ref:`enter-$ADDRESS_TYPE-form ` is + returned. If the backend installation does not include the required HTML + templates, a 406 status code is returned. + + **Request:** :query response_type: Must be ``code`` @@ -179,10 +189,55 @@ Login **Response:** :http:statuscode:`200 OK`: - The body contains a form to be submitted by the user-agent. + If the request ask for application/json then the response is + a `ChallengeStatus`. Since protocol **vSPA**. + Otherwise, the body contains a form to be submitted by the user-agent + using the template :ref:`enter-$ADDRESS_TYPE-form `. The form will ask the user to specify their address. + :http:statuscode:`406 Not Acceptable`: + The client ask for "text/html" and the backend installation does + not include the required HTML templates. + :http:statuscode:`400 Bad Request`: + The request does not follow the spec. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`invalid-request `. + :http:statuscode:`500 Internal Server Error`: + Server is not able to respond due to internal problems. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`internal-error `. :http:statuscode:`404 Not found`: - The backup service is unaware of a matching $NONCE. + The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`validation-unknown `. + + .. ts:def:: ChallengeStatus + + interface ChallengeStatus { + // 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. + restrictions: Object; + + // indicates if the given address cannot be changed anymore, the + // form should be read-only if set to true. + fix_address: boolean; + + // form values from the previous submission if available, details depend + // on the ``ADDRESS_TYPE``, should be used to pre-populate the form + last_address: Object; + + // number of times the address can still be changed, may or may not be + // shown to the user + changes_left: Integer; + } .. _challenger-challenge: @@ -204,15 +259,57 @@ Challenge **Response:** :http:statuscode:`200 OK`: - The body contains a form asking for the answer to - the challenge to be entered by the user. - :http:statuscode:`404 Not found`: - The challenger service is unaware of a matching nonce. + If the request ask for application/json the response is `ChallengeCreateResponse`. Since protocol **vSPA**. + Otherwise, the body contains a form asking for the answer to + the challenge to be entered by the user using the + template :ref:`enter-tan-form `. + :http:statuscode:`406 Not Acceptable`: + The client ask for "text/html" and the backend installation does + not include the required HTML templates. :http:statuscode:`429 Too Many Requests`: There have been too many attempts to request challenge transmissions for this $NONCE. The user-agent should wait and (eventually) request a fresh nonce to be set up by the client. + :http:statuscode:`400 Bad Request`: + The request does not follow the spec. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`invalid-request `. + :http:statuscode:`500 Internal Server Error`: + Server is not able to respond due to internal problems. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`internal-error `. + :http:statuscode:`404 Not found`: + The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`validation-unknown `. + + .. ts:def:: ChallengeCreateResponse + + interface ChallengeCreateResponse { + + // 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) + attempts_left: Integer; + + // the address that is being validated, might be shown or not + address: Object; + + // 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 + transmitted: boolean; + + // timestamp explaining when we would re-transmit the challenge the next + // time (at the earliest) if requested by the user + next_tx_time: String; + + } + .. _challenger-solve: @@ -240,15 +337,60 @@ Solve plus a ``code`` argument with the authorization code, and the ``state`` argument from the ``/authorize`` endpoint. :http:statuscode:`403 Forbidden`: - The solution of the user to the challenge is invalid. - :http:statuscode:`404 Not found`: - The service is unaware of a matching challenge. + If the request ask for application/json the response is `InvalidPinResponse`. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`invalid-pin `. :http:statuscode:`429 Too Many Requests`: There have been too many attempts to solve the challenge for this address (and $NONCE). The user-agent should either try a different address (or wait and (eventually) request a fresh nonce to be set up by the client). + :http:statuscode:`400 Bad Request`: + The request does not follow the spec. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`invalid-request `. + :http:statuscode:`500 Internal Server Error`: + Server is not able to respond due to internal problems. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`internal-error `. + :http:statuscode:`404 Not found`: + The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **vSPA**. + Otherwise, the body contains information using the template :ref:`validation-unknown `. + + .. ts:def:: InvalidPinResponse + interface InvalidPinResponse { + // numeric Taler error code, should be shown to indicate the error + // compactly for reporting to developers + ec: Integer; + + // human-readable Taler error code, should be shown for the user to + // understand the error + hint: String; + + // 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 + addresses_left: Integer; + + // how many times might the PIN still be retransmitted + pin_transmissions_left: Integer; + + // how many times might the user still try entering the PIN code + auth_attempts_left: Integer; + + // if true, the PIN was not even evaluated as the user previously + // exhausted the number of attempts + exhausted: boolean; + + // 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!) + no_challenge: boolean; + } .. _challenger-auth: -- 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 'core/api-challenger.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 d42bdf0462531aca3f4bcf5f17f7bb94b5245789 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 15 Apr 2024 11:10:50 +0200 Subject: vSPA is now protocol v1 --- core/api-challenger.rst | 74 ++++++++++++++++++++++++------------------------- 1 file changed, 37 insertions(+), 37 deletions(-) (limited to 'core/api-challenger.rst') diff --git a/core/api-challenger.rst b/core/api-challenger.rst index 25c84d3e..f8631977 100644 --- a/core/api-challenger.rst +++ b/core/api-challenger.rst @@ -1,6 +1,6 @@ .. This file is part of GNU TALER. - Copyright (C) 2023 Taler Systems SA + Copyright (C) 2023, 2024 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 @@ -99,7 +99,7 @@ Receiving Configuration .. http:get:: /config Obtain the key configuration settings of the storage service. - This specification corresponds to ``current`` protocol being version **0**. + This specification corresponds to ``current`` protocol being version **1**. **Response:** @@ -190,28 +190,28 @@ Login :http:statuscode:`200 OK`: If the request ask for application/json then the response is - a `ChallengeStatus`. Since protocol **vSPA**. + a `ChallengeStatus`. Since protocol **v1**. Otherwise, the body contains a form to be submitted by the user-agent using the template :ref:`enter-$ADDRESS_TYPE-form `. The form will ask the user to specify their address. - :http:statuscode:`406 Not Acceptable`: - The client ask for "text/html" and the backend installation does - not include the required HTML templates. :http:statuscode:`400 Bad Request`: The request does not follow the spec. If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. + code, hint and detail. Since protocol **v1**. Otherwise, the body contains information using the template :ref:`invalid-request `. - :http:statuscode:`500 Internal Server Error`: - Server is not able to respond due to internal problems. - If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. - Otherwise, the body contains information using the template :ref:`internal-error `. :http:statuscode:`404 Not found`: The service is unaware of a matching challenge. If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. + code, hint and detail. Since protocol **v1**. Otherwise, the body contains information using the template :ref:`validation-unknown `. + :http:statuscode:`406 Not Acceptable`: + The client ask for "text/html" and the backend installation does + not include the required HTML templates. + :http:statuscode:`500 Internal Server Error`: + Server is not able to respond due to internal problems. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`internal-error `. .. ts:def:: ChallengeStatus @@ -259,10 +259,20 @@ Challenge **Response:** :http:statuscode:`200 OK`: - If the request ask for application/json the response is `ChallengeCreateResponse`. Since protocol **vSPA**. + If the request ask for application/json the response is `ChallengeCreateResponse`. Since protocol **v1**. Otherwise, the body contains a form asking for the answer to the challenge to be entered by the user using the template :ref:`enter-tan-form `. + :http:statuscode:`400 Bad Request`: + The request does not follow the spec. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`invalid-request `. + :http:statuscode:`404 Not Found`: + The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`validation-unknown `. :http:statuscode:`406 Not Acceptable`: The client ask for "text/html" and the backend installation does not include the required HTML templates. @@ -271,21 +281,11 @@ Challenge transmissions for this $NONCE. The user-agent should wait and (eventually) request a fresh nonce to be set up by the client. - :http:statuscode:`400 Bad Request`: - The request does not follow the spec. - If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. - Otherwise, the body contains information using the template :ref:`invalid-request `. :http:statuscode:`500 Internal Server Error`: Server is not able to respond due to internal problems. If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. + code, hint and detail. Since protocol **v1**. Otherwise, the body contains information using the template :ref:`internal-error `. - :http:statuscode:`404 Not found`: - The service is unaware of a matching challenge. - If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. - Otherwise, the body contains information using the template :ref:`validation-unknown `. .. ts:def:: ChallengeCreateResponse @@ -336,29 +336,29 @@ Solve by the client (during registration and again upon ``/authorize``), plus a ``code`` argument with the authorization code, and the ``state`` argument from the ``/authorize`` endpoint. + :http:statuscode:`400 Bad Request`: + The request does not follow the spec. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`invalid-request `. :http:statuscode:`403 Forbidden`: - If the request ask for application/json the response is `InvalidPinResponse`. Since protocol **vSPA**. + If the request ask for application/json the response is `InvalidPinResponse`. Since protocol **v1**. Otherwise, the body contains information using the template :ref:`invalid-pin `. + :http:statuscode:`404 Not found`: + The service is unaware of a matching challenge. + If the request ask for application/json the response will include error + code, hint and detail. Since protocol **v1**. + Otherwise, the body contains information using the template :ref:`validation-unknown `. :http:statuscode:`429 Too Many Requests`: There have been too many attempts to solve the challenge for this address (and $NONCE). The user-agent should either try a different address (or wait and (eventually) request a fresh nonce to be set up by the client). - :http:statuscode:`400 Bad Request`: - The request does not follow the spec. - If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. - Otherwise, the body contains information using the template :ref:`invalid-request `. :http:statuscode:`500 Internal Server Error`: Server is not able to respond due to internal problems. If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. + code, hint and detail. Since protocol **v1**. Otherwise, the body contains information using the template :ref:`internal-error `. - :http:statuscode:`404 Not found`: - The service is unaware of a matching challenge. - If the request ask for application/json the response will include error - code, hint and detail. Since protocol **vSPA**. - Otherwise, the body contains information using the template :ref:`validation-unknown `. .. ts:def:: InvalidPinResponse -- cgit v1.2.3