post-challenge-NONCE.rst (7519B)
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:`413 Request entity too large`: 67 The request body exceeds the 1024 byte limit. 68 Returned with ``TALER_EC_GENERIC_UPLOAD_EXCEEDS_LIMIT``. 69 :http:statuscode:`415 Unsupported Media Type`: 70 The ``Content-Type`` is missing or is not one the service can parse. 71 Returned with ``TALER_EC_GENERIC_PARAMETER_MALFORMED`` and ``detail`` 72 set to ``"Content-Type"``. 73 Since protocol **v8**; previously reported as ``400``. 74 :http:statuscode:`429 Too Many Requests`: 75 There have been too many attempts to request challenge 76 transmissions for this $NONCE. The user-agent should 77 wait and (eventually) request a fresh nonce to be set 78 up by the client. 79 Since protocol **v2**. Two distinct situations are distinguished, 80 since the appropriate recovery differs. Since protocol **v8**: 81 82 * ``TALER_EC_CHALLENGER_TOO_MANY_ADDRESS_CHANGES`` --- the number of 83 permitted *address changes* was exhausted. The user must obtain a 84 fresh nonce from the client. 85 * ``TALER_EC_CHALLENGER_TOO_MANY_PIN_TRANSMISSIONS`` --- the number of 86 permitted *TAN transmissions* for the current address was exhausted. 87 The user may still try a different address if address changes remain. 88 89 Note that merely being within the retransmission cooldown is 90 **not** an error: it is reported as ``200 OK`` with ``transmitted`` 91 set to false. 92 :http:statuscode:`500 Internal Server Error`: 93 Server is not able to respond due to internal problems. 94 Since protocol **v1**. Error codes used are: 95 96 * ``TALER_EC_GENERIC_DB_FETCH_FAILED`` --- reading the previously stored 97 address failed (``detail`` is ``"get_validation_address"``). 98 * ``TALER_EC_GENERIC_DB_STORE_FAILED`` --- storing the address or 99 confirming the transmitted TAN failed (``detail`` is 100 ``"do_challenge_address"`` or ``"do_challenge_address_confirm_pin"``). 101 * ``TALER_EC_GENERIC_FAILED_TO_EXPAND_TEMPLATE`` --- expanding 102 ``MESSAGE_TEMPLATE_FILE`` for the challenge message failed. 103 * ``TALER_EC_GENERIC_PARSER_OUT_OF_MEMORY`` --- the service ran out of 104 memory while buffering an ``application/json`` body. 105 * ``TALER_EC_CHALLENGER_ADDRESS_RESTRICTION_MALFORMED`` --- the 106 ``ADDRESS_RESTRICTIONS`` configuration for the field named in 107 ``detail`` has no regular expression, or one that failed to compile. 108 This is an operator error, not a client error; the request is 109 refused because a restriction that cannot be evaluated must not be 110 treated as "no restriction". Since protocol **v8**. 111 :http:statuscode:`502 Bad Gateway`: 112 The challenger service failed to launch or communicate with 113 its helper process for delivering the challenge (SMS, e-mail, 114 postal mail). Returned with 115 ``TALER_EC_CHALLENGER_HELPER_EXEC_FAILED``. 116 The ``detail`` distinguishes the failure: ``"pipe"``, ``"exec"``, 117 ``"write"``, or ``"$EXIT_CODE/$PROCESS_STATUS"`` when the helper 118 terminated abnormally or with a non-zero exit code. 119 120 .. ts:def:: ChallengeResponse 121 122 // Union discriminated by the "type" field. 123 type ChallengeResponse = ChallengeRedirect | ChallengeCreateResponse 124 125 .. ts:def:: ChallengeRedirect 126 127 // @since **v2** 128 interface ChallengeRedirect { 129 // Union discriminator field. 130 type: "completed"; 131 132 // challenge is completed, use should redirect here 133 redirect_url: WebURL; 134 } 135 136 .. ts:def:: ChallengeCreateResponse 137 138 interface ChallengeCreateResponse { 139 // Union discriminator field. 140 type: "created" 141 142 // how many more attempts are allowed, might be shown to the user, 143 // highlighting might be appropriate for low values such as 1 or 2 (the 144 // form will never be used if the value is zero) 145 attempts_left: Integer; 146 147 // the address that is being validated, might be shown or not 148 address: Object; 149 150 // true if we just retransmitted the challenge, false if we sent a 151 // challenge recently and thus refused to transmit it again this time; 152 // might make a useful hint to the user 153 transmitted: boolean; 154 155 // when we would re-transmit the challenge the next 156 // time (at the earliest) if requested by the user 157 // @since **v2** 158 retransmission_time: Timestamp; 159 }