Improve 2FA documentation

2 files changed, 40 insertions, 13 deletions

diff --git a/libeufin/bank-manual.rst b/libeufin/bank-manual.rst
index 4dd74210..228cbef1 100644
--- a/libeufin/bank-manual.rst
+++ b/libeufin/bank-manual.rst
@@ -104,25 +104,51 @@ The following snippet shows the mandatory configuration values:
 Configuring multi-factor authentication
 ---------------------------------------
 
-libeufin-bank supports two factor authentification. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. By default, those helper scripts are ``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send SMS. To enable two factor authentication you need to configure at least one TAN channel: 
+libeufin-bank supports two-factor authentication. libeufin-bank uses helper scripts to send challenge codes to addresses for multi-factor authentication. We provide two default helper scripts: ``libeufin-tan-email.sh`` to send e-mails and ``libeufin-tan-sms.sh`` to send SMS. To enable two-factor authentication you need to configure at least one TAN channel.
+
+SMS TAN channel
++++++++++++++++
+
+The default ``libeufin-tan-sms.sh`` script is based on the `Telesign <https://www.telesign.com>`_ provider. It requires an additional ``AUTH_TOKEN`` environment variable for the `Telesign API <https://developer.telesign.com/enterprise/docs/authentication#basic-authentication>`_.
+
+To test your setup run:
+
+.. code-block:: console
+
+  $ AUTH_TOKEN=$TELESIGN_TOKEN
+  $ echo "Test 1234" | libeufin-tan-sms.sh $PHONE
+
+If you received an SMS containing "Test 1234" you can enable this channel in the config: 
 
 .. code-block:: ini
 
   [libeufin-bank]
   TAN_SMS = libeufin-tan-sms.sh
-  # And/Or
-  TAN_EMAIL = libeufin-tan-email.sh
+  TAN_SMS_ENV = "AUTH_TOKEN=$TELESIGN_TOKEN"
 
-.. note::
+Mail TAN channel
+++++++++++++++++
 
-  The default ``libeufin-tan-sms.sh`` script is based on the `Telesign <https://www.telesign.com>`_ provider. It requires an additional ``telesign-secrets`` script in the PATH that sets the ``CUSTOMER_ID`` and the ``API_KEY`` for the Telesign API.
+The default ``libeufin-tan-email.sh`` script is based on the ``mail`` Linux command. It requires a working local mail transfer agent.
 
-.. note::
+To test your setup run:
 
-  The default ``libeufin-tan-email.sh`` script is based on the ``mail`` linux command. It requires a working local mail transfer agent.
+.. code-block:: console
+
+  $ echo "Test 1234" | libeufin-tan-email.sh $EMAIL
+
+If you received an email containing "Test 1234" you can enable this channel in the config: 
+
+.. code-block:: ini
+
+  [libeufin-bank]
+  TAN_EMAIL = libeufin-tan-email.sh
+
+Custom TAN channel scripts
+++++++++++++++++++++++++++
 
 It is possible to replace these scripts with use custom scripts to send
-the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the ``$1`` parameter and the message content to be transmitted in their standard input.  They should return 0 to indicate successful transmission of the challenge, and non-zero on failure.
+the e-mail or SMS TAN. Such alternative scripts must accept the phone number / e-mail address as the ``$1`` parameter and the message content to be transmitted in their standard input.  They should return 0 to indicate successful transmission of the challenge and non-zero on failure.
 
 To change the scripts used for multi-factor authentication, change the following
 options in the configuration file:
@@ -131,8 +157,9 @@ options in the configuration file:
 
   [libeufin-bank]
   TAN_SMS = custom-tan-sms.sh
+  TAN_SMS_ENV = 
   TAN_EMAIL = custom-tan-email.sh
-
+  TAN_EMAIL_ENV = 
 
 Launching libeufin-bank
 =======================
diff --git a/libeufin/regional-manual.rst b/libeufin/regional-manual.rst
index e3389a2d..469be164 100644
--- a/libeufin/regional-manual.rst
+++ b/libeufin/regional-manual.rst
@@ -110,7 +110,7 @@ A very good advice when creating these subdomains, and if your domain panel lets
 to specify a very low value (such as 300), so in case of future changes, its value (the IP address), will be propagated quickly.
 
 Once you have added the three required subdomains in your domain control panel, you have to make sure as well, these subdomains have
-propogated over the Internet correctly, and they are currently publicly available.
+propagated over the Internet correctly, and they are currently publicly available.
 
 You can check this from your terminal very easily with the "dig" command, as this:
 
@@ -190,7 +190,7 @@ some of the interactive questions, or you just want to reset the current install
 the script again for having its latest changes, you will have to proceed as follows:
 
 In brief you need to wipe completely the "content" of the file config/user.conf, this doesn't mean
-to remove the file itself, but only its content. Eventhough you can do this manually by editing the file manually
+to remove the file itself, but only its content. Even though you can do this manually by editing the file manually
 with you preferred text editor, you can also do this in one single command.
 
 .. code-block:: console
@@ -202,8 +202,8 @@ with you preferred text editor, you can also do this in one single command.
    In future versions of the program when executed for the second time, the program itself will
    show an option to offer wiping the content of this config/user.conf file, automatically.
 
-Multi-factor authentification
-+++++++++++++++++++++++++++++
+Multi-factor authentication
++++++++++++++++++++++++++++
 
 By default, multi-factor authentication via SMS and email is enabled. You have to manually configure both channels as described in :ref:`multi-factor authentication <libeufin-mfa>`.