challenger-send-sms.1.rst (6694B)
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 ``gatewayapi``, ``budgetsms``, ``aspsms``, ``seven``, 55 ``telesign``, ``clicksend``. A provider whose helper is absent or not executable 56 is skipped silently, and so, in effect, is one whose credentials are missing: 57 it fails with status 40, and the next provider is tried. The credentials are 58 listed in each helper's manual page and must be present in the environment of 59 the invoking daemon. 60 61 ``gatewayapi`` (challenger-send-sms-gatewayapi(1)), ``budgetsms`` 62 (challenger-send-sms-budgetsms(1)) and ``seven`` (challenger-send-sms-seven(1)) 63 are operated inside the European Economic Area, which avoids transferring the 64 phone number and the TAN to a third country; ``aspsms`` 65 (challenger-send-sms-aspsms(1)) is operated in Switzerland, ``telesign`` 66 (challenger-send-sms-telesign(1)) in the United States and ``clicksend`` 67 (challenger-send-sms-clicksend(1)) in Australia. The order is the ``PROVIDERS`` 68 variable near the top of the **challenger-send-sms** script; edit it to change 69 the order or to leave a provider out. 70 71 Whether a failing provider causes the next one to be tried depends on the class 72 of the failure. An address that one provider rejects will be rejected by all of 73 them, so such a failure is reported immediately; a provider that is 74 misconfigured, out of credit, rate limited or down does not prevent another 75 provider from succeeding, so those cause a fall-through. 76 77 If every provider has been tried without success, the most actionable code seen 78 is reported, preferring address errors, then recipient errors, then 79 configuration errors, then provider errors. 80 81 82 Environment 83 =========== 84 85 **challenger-send-sms** itself reads no environment variables, but the provider 86 helpers it invokes require credentials to be present in the environment of the 87 invoking daemon. See challenger-send-sms-telesign(1), 88 challenger-send-sms-clicksend(1), challenger-send-sms-aspsms(1), 89 challenger-send-sms-seven(1), challenger-send-sms-gatewayapi(1) and 90 challenger-send-sms-budgetsms(1). 91 92 93 Exit Status 94 =========== 95 96 An exit status of 0, or in the 200 to 210 band, means the TAN was 97 transmitted, or will be. Any other status means it was not. The success 98 band starts at 200 rather than at 1 because GNUnet reports a helper it 99 could not execute as exit status 1, which must not be mistaken for a 100 delivery. 101 102 **0** 103 The TAN was delivered and receipt on the handset was confirmed. 104 105 **201** 106 A provider accepted the TAN for delivery, but delivery was not confirmed 107 within the polling window. This is a success: the message is in flight. 108 109 **202** 110 A provider suppressed the message as a duplicate, because an identical 111 message was recently accepted for the same recipient. The earlier copy is in 112 flight, so this too is a success. 113 114 **10** 115 The address is malformed: the ``CONTACT_PHONE`` field is missing, or its 116 value is not of the form ``+`` followed by digits. 117 118 **11** 119 The phone number is too short. 120 121 **12** 122 The phone number is too long. 123 124 **13** 125 The number is not a mobile subscription. Reported only on a best-effort 126 basis; most providers cannot make this distinction. 127 128 **14** 129 The number is syntactically plausible but unallocated, or the subscriber is 130 unknown. This is the status reported for a number with a missing, extra or 131 transposed digit that the local check cannot catch. 132 133 **15** 134 Delivery to this number is blocked, barred, or the number is on a blocklist. 135 136 **20** 137 The handset is switched off or out of coverage. 138 139 **21** 140 The message expired before it could be delivered to the handset. 141 142 **22** 143 The mobile operator or an intermediate carrier failed. 144 145 **30** 146 The SMS provider is down or reported an internal error. 147 148 **31** 149 The SMS provider rejected the request. 150 151 **32** 152 A provider rate limit was exceeded. 153 154 **33** 155 No verdict: the outcome of the submission could not be determined. 156 157 **40** 158 Local configuration or invocation error: a required credential is absent 159 from the environment, or the helper was called with the wrong arguments. 160 161 **41** 162 A provider refused the configured credentials. 163 164 **42** 165 A provider account has insufficient balance. All supported providers are 166 pre-paid. 167 168 **50** 169 The transmission failed for a reason that could not be classified. 170 171 172 See Also 173 ======== 174 175 challenger-send-sms-aspsms(1), challenger-send-sms-budgetsms(1), 176 challenger-send-sms-clicksend(1), challenger-send-sms-gatewayapi(1), 177 challenger-send-sms-seven(1), challenger-send-sms-telesign(1), 178 challenger-send-email(1), challenger-send-post(1), challenger-httpd(1), 179 challenger.conf(5). 180 181 182 Bugs 183 ==== 184 185 Report bugs by using https://bugs.taler.net or by sending electronic 186 mail to <taler@gnu.org>.