post-challenge-NONCE.rst (8151B)
1 .. http:post:: /challenge/$NONCE 2 3 This endpoint is used by the user-agent to submit the address to which a 4 challenge should be sent by the challenger service. 5 6 **Request:** 7 8 Body should use the mime-type "application/x-www-form-urlencoded"; 9 ``multipart/form-data`` is accepted as well. Alternatively, the address 10 may be uploaded directly as a JSON object using the mime-type 11 ``application/json``. In the form encodings, each field name/value pair 12 becomes one string-valued member of the address object, and each field is 13 limited to 1024 bytes. The total request body is limited to 1024 bytes 14 for the form encodings. 15 16 The posted form data must contain an address JSON object 17 that follow the restrictions 18 defined in :ref:`config <challenger-config>`. 19 If the address provided in the `ChallengeSetupRequest` 20 of ``/setup`` was set to be ``read_only`` and 21 that was subsequently returned in the 22 `ChallengeStatusResponse`, then the body 23 must not change that address. The ``read_only`` field itself is 24 ignored when comparing the addresses and is re-inserted by the service, 25 so the client need not (but may) preserve it. 26 27 **Response:** 28 29 :http:statuscode:`200 OK`: 30 The response is `ChallengeResponse`. Since protocol **v2**. 31 The ``created`` variant carries ``Cache-Control: no-store,no-cache``. 32 :http:statuscode:`400 Bad Request`: 33 The request does not follow the spec. Since protocol **v1**. 34 Error codes used are: 35 36 * ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` --- the ``$NONCE`` in the URL 37 is not a valid 52-character Crockford-base32 value (``detail`` is 38 ``"nonce"``), the ``Content-Length`` header is not a number 39 (``detail`` is ``"Content-Length"``), an ``application/json`` body is 40 valid JSON but not an object (``detail`` is ``"address"``), or a 41 submitted field name or value is not valid UTF-8. 42 * ``TALER_EC_CHALLENGER_ADDRESS_RESTRICTION_VIOLATED`` --- a field is 43 absent or violates the regular expression configured for it in 44 ``restrictions``, see :ref:`config <challenger-config>`; ``detail`` 45 names the offending field, so the user agent can highlight it and 46 show the corresponding ``hint``/``hint_i18n``. Since protocol 47 **v8**. 48 * ``TALER_EC_GENERIC_JSON_INVALID`` --- an ``application/json`` body is 49 not well-formed JSON. 50 :http:statuscode:`403 Forbidden`: 51 The address being submitted differs from the previously 52 submitted address but the validation process was set up 53 as ``read_only`` and thus the address cannot be changed. 54 Returned with 55 ``TALER_EC_CHALLENGER_CLIENT_FORBIDDEN_READ_ONLY``. 56 Since protocol **v4**. 57 :http:statuscode:`404 Not Found`: 58 The service is unaware of a matching challenge. Since protocol **v1**. 59 Returned with ``TALER_EC_CHALLENGER_GENERIC_VALIDATION_UNKNOWN`` when 60 the nonce is well-formed but unknown, or the validation has expired. 61 These two cases are not distinguished. 62 :http:statuscode:`405 Method Not Allowed`: 63 The request used a method other than ``POST`` or ``OPTIONS``. 64 Returned by the request router with an ``Allow`` header and an 65 **empty body**; in particular there is no Taler error code. 66 :http:statuscode:`410 Gone`: 67 The validation failed permanently: the user exhausted every address 68 change, TAN transmission and TAN attempt (an address the client set 69 as ``read_only`` counts as one that cannot be changed), so it can never 70 succeed. Returned with ``TALER_EC_CHALLENGER_VALIDATION_FAILED``; the 71 response is a `ValidationFailedResponse`. The user-agent must send the 72 user to its ``redirect_url`` so that the client learns about the 73 failure. If the request asked for ``text/html``, the service instead 74 redirects to that URL with a ``302 Found`` right away. 75 Since protocol **v10**. 76 :http:statuscode:`413 Request entity too large`: 77 The request body exceeds the 1024 byte limit. 78 Returned with ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 79 :http:statuscode:`415 Unsupported Media Type`: 80 The ``Content-Type`` is missing or is not one the service can parse. 81 Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` and ``detail`` 82 set to ``"Content-Type"``. 83 Since protocol **v8**; previously reported as ``400``. 84 :http:statuscode:`429 Too Many Requests`: 85 There have been too many attempts to request challenge 86 transmissions for this $NONCE. The user-agent should 87 wait and (eventually) request a fresh nonce to be set 88 up by the client. 89 Since protocol **v2**. Two distinct situations are distinguished, 90 since the appropriate recovery differs. Since protocol **v8**: 91 92 * ``TALER_EC_CHALLENGER_TOO_MANY_ADDRESS_CHANGES`` --- the number of 93 permitted *address changes* was exhausted. The user must obtain a 94 fresh nonce from the client. 95 * ``TALER_EC_CHALLENGER_TOO_MANY_PIN_TRANSMISSIONS`` --- the number of 96 permitted *TAN transmissions* for the current address was exhausted. 97 The user may still try a different address if address changes remain. 98 99 Note that merely being within the retransmission cooldown is 100 **not** an error: it is reported as ``200 OK`` with ``transmitted`` 101 set to false. 102 :http:statuscode:`500 Internal Server Error`: 103 Server is not able to respond due to internal problems. 104 Since protocol **v1**. Error codes used are: 105 106 * ``TALER_EC_GENERIC_DB_FETCH_FAILED`` --- reading the previously stored 107 address failed (``detail`` is ``"get_validation_address"``). 108 * ``TALER_EC_GENERIC_DB_STORE_FAILED`` --- storing the address or 109 confirming the transmitted TAN failed (``detail`` is 110 ``"do_challenge_address"`` or ``"do_challenge_address_confirm_pin"``). 111 * ``TALER_EC_GENERIC_FAILED_TO_EXPAND_TEMPLATE`` --- expanding 112 ``MESSAGE_TEMPLATE_FILE`` for the challenge message failed. 113 * ``TALER_EC_GENERIC_PARSER_OUT_OF_MEMORY`` --- the service ran out of 114 memory while buffering an ``application/json`` body. 115 * ``TALER_EC_CHALLENGER_ADDRESS_RESTRICTION_MALFORMED`` --- the 116 ``ADDRESS_RESTRICTIONS`` configuration for the field named in 117 ``detail`` has no regular expression, or one that failed to compile. 118 This is an operator error, not a client error; the request is 119 refused because a restriction that cannot be evaluated must not be 120 treated as "no restriction". Since protocol **v8**. 121 :http:statuscode:`502 Bad Gateway`: 122 The challenger service failed to launch or communicate with 123 its helper process for delivering the challenge (SMS, e-mail, 124 postal mail). Returned with 125 ``TALER_EC_CHALLENGER_HELPER_EXEC_FAILED``. 126 The ``detail`` distinguishes the failure: ``"pipe"``, ``"exec"``, 127 ``"write"``, or ``"$EXIT_CODE/$PROCESS_STATUS"`` when the helper 128 terminated abnormally or with a non-zero exit code. 129 130 .. ts:def:: ChallengeResponse 131 132 // Union discriminated by the "type" field. 133 type ChallengeResponse = ChallengeRedirect | ChallengeCreateResponse 134 135 .. ts:def:: ChallengeRedirect 136 137 // @since **v2** 138 interface ChallengeRedirect { 139 // Union discriminator field. 140 type: "completed"; 141 142 // challenge is completed, use should redirect here 143 redirect_url: WebURL; 144 } 145 146 .. ts:def:: ChallengeCreateResponse 147 148 interface ChallengeCreateResponse { 149 // Union discriminator field. 150 type: "created" 151 152 // how many more attempts are allowed, might be shown to the user, 153 // highlighting might be appropriate for low values such as 1 or 2 (the 154 // form will never be used if the value is zero) 155 attempts_left: Integer; 156 157 // the address that is being validated, might be shown or not 158 address: Object; 159 160 // true if we just retransmitted the challenge, false if we sent a 161 // challenge recently and thus refused to transmit it again this time; 162 // might make a useful hint to the user 163 transmitted: boolean; 164 165 // when we would re-transmit the challenge the next 166 // time (at the earliest) if requested by the user 167 // @since **v2** 168 retransmission_time: Timestamp; 169 }