taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

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>.