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