challenger-send-sms.1.rst (6656B)
1 challenger-send-sms(1) 2 ###################### 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **challenger-send-sms** - transmit a Challenger TAN by SMS 10 11 12 Synopsis 13 ======== 14 15 **challenger-send-sms** *ADDRESS* 16 17 18 Description 19 =========== 20 21 **challenger-send-sms** transmits a TAN to a mobile phone number. It is not 22 itself an SMS sender: it validates the number, then tries each installed 23 provider helper in turn until one of them accepts the message. 24 25 The command is not normally invoked by hand. It is named in the 26 ``AUTH_COMMAND`` option of a ``[challenger]`` configuration section (see 27 challenger.conf(5)), and is executed by challenger-httpd(1) whenever a TAN must 28 be delivered. The same invocation contract is used by the Anastasis 29 authorization plugins and by the GNU Taler merchant backend, so the helper may 30 be executed by any of those services. 31 32 *ADDRESS* is the user-supplied address object, as compact JSON. The field 33 consulted is ``CONTACT_PHONE``, and its name derives from the 34 ``enter-$ADDRESS_TYPE-form`` template on the Challenger side; an address object 35 without that field is rejected. 36 37 The message to transmit — including the TAN itself — is read from **standard 38 input**. It is the ``MESSAGE_TEMPLATE_FILE`` of challenger-httpd(1) after 39 expansion. **The TAN is never passed on the command line**, so that it does not 40 appear in the process table. 41 42 Standard error is inherited from the invoking daemon and is used for 43 diagnostics. 44 45 Before contacting any provider, the number is checked against the general 46 E.164 form: a leading ``+`` followed by 7 to 15 digits. This is deliberately a 47 generic check. It rejects grossly malformed input such as ``+41`` without 48 consulting a provider, but it cannot enforce per-country lengths, so a number 49 that is merely one digit short or long, or that has a transposed digit, is 50 passed on and will be reported by whichever provider first classifies it. 51 52 Providers are resolved by name from the directory holding 53 **challenger-send-sms** itself, as ``challenger-send-sms-``\ *PROVIDER*, and are 54 tried in the order ``telesign``, ``clicksend``, ``aspsms``. A provider whose 55 helper is absent or not executable is skipped silently. 56 57 Three further provider helpers are installed but not in that list: 58 ``seven`` (challenger-send-sms-seven(1)), ``gatewayapi`` 59 (challenger-send-sms-gatewayapi(1)) and ``budgetsms`` 60 (challenger-send-sms-budgetsms(1)). All three are operated inside the European 61 Economic Area, which avoids the transfer of a phone number and a TAN to a third 62 country that the other three providers involve. They have been written against 63 the published specifications of their APIs and are covered by the offline test 64 suite, but have not been exercised against a live account, which is why they 65 are not enabled by default. To use one, add its name to the ``PROVIDERS`` 66 variable near the top of the **challenger-send-sms** script, in the order in 67 which it should be tried; the credentials listed in each helper's manual page 68 must be present in the environment of the invoking daemon. 69 70 Whether a failing provider causes the next one to be tried depends on the class 71 of the failure. An address that one provider rejects will be rejected by all of 72 them, so such a failure is reported immediately; a provider that is 73 misconfigured, out of credit, rate limited or down does not prevent another 74 provider from succeeding, so those cause a fall-through. 75 76 If every provider has been tried without success, the most actionable code seen 77 is reported, preferring address errors, then recipient errors, then 78 configuration errors, then provider errors. 79 80 81 Environment 82 =========== 83 84 **challenger-send-sms** itself reads no environment variables, but the provider 85 helpers it invokes require credentials to be present in the environment of the 86 invoking daemon. See challenger-send-sms-telesign(1), 87 challenger-send-sms-clicksend(1), challenger-send-sms-aspsms(1), 88 challenger-send-sms-seven(1), challenger-send-sms-gatewayapi(1) and 89 challenger-send-sms-budgetsms(1). 90 91 92 Exit Status 93 =========== 94 95 An exit status of 0, or in the 200 to 210 band, means the TAN was 96 transmitted, or will be. Any other status means it was not. The success 97 band starts at 200 rather than at 1 because GNUnet reports a helper it 98 could not execute as exit status 1, which must not be mistaken for a 99 delivery. 100 101 **0** 102 The TAN was delivered and receipt on the handset was confirmed. 103 104 **201** 105 A provider accepted the TAN for delivery, but delivery was not confirmed 106 within the polling window. This is a success: the message is in flight. 107 108 **202** 109 A provider suppressed the message as a duplicate, because an identical 110 message was recently accepted for the same recipient. The earlier copy is in 111 flight, so this too is a success. 112 113 **10** 114 The address is malformed: the ``CONTACT_PHONE`` field is missing, or its 115 value is not of the form ``+`` followed by digits. 116 117 **11** 118 The phone number is too short. 119 120 **12** 121 The phone number is too long. 122 123 **13** 124 The number is not a mobile subscription. Reported only on a best-effort 125 basis; most providers cannot make this distinction. 126 127 **14** 128 The number is syntactically plausible but unallocated, or the subscriber is 129 unknown. This is the status reported for a number with a missing, extra or 130 transposed digit that the local check cannot catch. 131 132 **15** 133 Delivery to this number is blocked, barred, or the number is on a blocklist. 134 135 **20** 136 The handset is switched off or out of coverage. 137 138 **21** 139 The message expired before it could be delivered to the handset. 140 141 **22** 142 The mobile operator or an intermediate carrier failed. 143 144 **30** 145 The SMS provider is down or reported an internal error. 146 147 **31** 148 The SMS provider rejected the request. 149 150 **32** 151 A provider rate limit was exceeded. 152 153 **33** 154 No verdict: the outcome of the submission could not be determined. 155 156 **40** 157 Local configuration or invocation error: a required credential is absent 158 from the environment, or the helper was called with the wrong arguments. 159 160 **41** 161 A provider refused the configured credentials. 162 163 **42** 164 A provider account has insufficient balance. All supported providers are 165 pre-paid. 166 167 **50** 168 The transmission failed for a reason that could not be classified. 169 170 171 See Also 172 ======== 173 174 challenger-send-sms-aspsms(1), challenger-send-sms-budgetsms(1), 175 challenger-send-sms-clicksend(1), challenger-send-sms-gatewayapi(1), 176 challenger-send-sms-seven(1), challenger-send-sms-telesign(1), 177 challenger-send-email(1), challenger-send-post(1), challenger-httpd(1), 178 challenger.conf(5). 179 180 181 Bugs 182 ==== 183 184 Report bugs by using https://bugs.taler.net or by sending electronic 185 mail to <taler@gnu.org>.