--- a/mod_auth_token/README.markdown Sun Feb 24 01:02:30 2019 +0100
+++ b/mod_auth_token/README.markdown Tue Feb 26 15:58:58 2019 +0100
@@ -11,10 +11,17 @@
If the token is verified, then the user is authenticated.
-## How to generate the token
+## Luarocks dependencies
+
+You'll need to install the following luarocks
+
+ otp 0.1-5
+ luatz 0.3-1
+
+## How to generate the TOTP seed and shared signing secret
You'll need a shared OTP_SEED value for generating time-based one-time-pin
-values and a shared private key for signing the HMAC token.
+(TOTP) values and a shared private key for signing the HMAC token.
You can generate the OTP_SEED value with Python, like so:
@@ -28,10 +35,24 @@
>>> pyotp.random_base32(length=32)
u'JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7'
-These values then need to go into your Prosody.cfg file:
+## Configuration
+
+Firest you need to enable the relevant modules to your Prosody.cfg file.
+
+Look for the line `modules_enabled` (either globally or for your
+particular `VirtualHost`), and then add the following to tokens:
-token_secret = "JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7"
-otp_seed = "XVGR73KMZH2M4XMY"
+ modules_enabled = {
+ -- Token authentication
+ "auth_token";
+ "sasl_token";
+ }
+
+The previously generated token values also need to go into your Prosody.cfg file:
+
+ authentication = "token";
+ token_secret = "JYXEX4IQOEYFYQ2S3MC5P4ZT4SDHYEA7";
+ otp_seed = "XVGR73KMZH2M4XMY";
The application that generates the tokens also needs access to these values.
@@ -46,3 +67,31 @@
Prosody doesn't automatically pick up this file, so you'll need to update your
configuration file's `plugin_paths` to link to this subdirectory (for example
to `/usr/lib/prosody-modules/mod_auth_token/`).
+
+## Generating the token
+
+Here's a Python snippet showing how you can generate the token that Prosody
+will then verify:
+
+ import base64
+ import pyotp
+ import random
+
+ # Constants
+ OTP_INTERVAL = 30
+ OTP_DIGITS = 8
+
+ jid = '{}@{}'.format(username, domain)
+
+ otp_service = pyotp.TOTP(
+ OTP_SEED, # OTP_SEED must be set to the value generated previously (see above)
+ digits=OTP_DIGITS,
+ interval=OTP_INTERVAL
+ )
+ otp = otp_service.generate_otp(otp_service.timecode(datetime.utcnow()))
+
+ nonce = ''.join([str(random.randint(0, 9)) for i in range(32)])
+ string_to_sign = otp + nonce + jid
+ signature = hmac.new(token_secret, string_to_sign, hashlib.sha256).digest()
+ token = u"{} {}".format(otp+nonce, base64.b64encode(signature))
+