feature: users can be enrolled for TOTP one-time passwords.

debian-package/src/usr/lib/vpn-router/vpnrouter_ldap.py

@@ -4,7 +4,12 @@ The package keeps its own database, dc=vpn-router,dc=local in /var/lib/ldap/vpn-
 next to the one slapd's installation creates. Root manages it through the local socket
 with SASL EXTERNAL: the database's root DN is root's peer-credential DN, so there is no
 administrator password. Users and groups are changed by the user-manager service account,
-which the ACLs allow to write ou=users and ou=groups and to set, never read, passwords.
+which the ACLs allow to write ou=users and ou=groups and to set, never read, passwords and
+TOTP secrets.
+
+slapd's otp module is loaded for the OATH-LDAP schema; its overlay is not configured on the
+database, so binds do not check one-time passwords. cn=totp,ou=policies holds the TOTP
+parameters the token of every user points to.
 """
 
 import os
@@ -24,6 +29,7 @@ GROUPS = f'ou=groups,{BASE}'
 SERVICES = f'ou=services,{BASE}'
 POLICIES = f'ou=policies,{BASE}'
 DEFAULT_POLICY = f'cn=default,{POLICIES}'
+TOTP_PARAMS = f'cn=totp,{POLICIES}'
 MANAGER = f'cn=user-manager,{SERVICES}'
 ROOT = 'gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth'
 
@@ -33,12 +39,19 @@ MANAGER_SECRET = SECRET_DIR / 'user-manager.secret'
 SLAPD_DEFAULTS = pathlib.Path('/etc/default/slapd')
 SLAPD_SERVICES = 'SLAPD_SERVICES="ldapi:///"'
 
-MODULES = ('argon2', 'ppolicy')
+MODULES = ('argon2', 'ppolicy', 'otp')
 PASSWORD_HASH = '{ARGON2}'
 
+#: The TOTP parameters: digits, the OID of HMAC-SHA1, seconds per time step, and the time steps accepted before and after now.
+TOTP_DIGITS = 6
+TOTP_ALGORITHM = '1.2.840.113549.2.7'
+TOTP_PERIOD = 30
+TOTP_WINDOW = 1
+
 #: The ACLs of the database, in order.
 ACCESS = (
     f'to attrs=userPassword by dn.exact="{MANAGER}" =wx by self =wx by anonymous auth by * none',
+    f'to attrs=oathSecret by dn.exact="{MANAGER}" =w by * none',
     f'to dn.subtree="{USERS}" by dn.exact="{MANAGER}" manage by * read',
     f'to dn.subtree="{GROUPS}" by dn.exact="{MANAGER}" manage by * read',
     'to * by * read',
@@ -179,6 +192,14 @@ def provision():
             'pwdLockout': [b'TRUE'],
             'pwdMaxFailure': [b'0'],
         })
+        _ensure_entry(connection, TOTP_PARAMS, {
+            'objectClass': [b'organizationalRole', b'oathTOTPParams'],
+            'cn': [b'totp'],
+            'oathOTPLength': [str(TOTP_DIGITS).encode()],
+            'oathHMACAlgorithm': [TOTP_ALGORITHM.encode()],
+            'oathTOTPTimeStepPeriod': [str(TOTP_PERIOD).encode()],
+            'oathTOTPTimeStepWindow': [str(TOTP_WINDOW).encode()],
+        })
         _ensure_manager(connection)
     finally:
         connection.unbind_s()

debian-package/src/usr/lib/vpn-router/vpnrouter_users.py

@@ -10,22 +10,31 @@ optional description and at least one member; a group cannot be empty, so the la
 cannot leave it and a user who is the last member of a group cannot be removed. Groups only
 record membership; nothing on the router reads them.
 
+A user may have a TOTP token: the user entry itself is an oathTOTPUser and oathTOTPToken whose
+oathTOTPToken points to itself, with the secret in oathSecret and the parameters of
+vpnrouter_ldap.TOTP_PARAMS. Enrolment stores nothing until a code of the new secret is
+verified: otp_new makes a secret and its otpauth URI, and otp_enrol stores the secret given a
+code of it. Nothing on the router checks the codes at login.
+
 Every operation runs in a session(), which holds the lock that serializes changes and the
 connection of the user manager account. A request that cannot be done raises Failure, whose
 status says why: 2 the request is invalid, 3 the user does not exist, 4 the user exists, 1
 anything else. Answers are dicts with the keys of the JSON answers.
 """
 
+import base64
 import contextlib
 import fcntl
 import pathlib
 import re
 import subprocess
 import sys
+import time
 
 import ldap
 import ldap.filter
 import ldap.modlist
+import pyotp
 
 import vpnrouter
 import vpnrouter_ldap
@@ -42,7 +51,12 @@ EMAIL_MAX = 254
 #: The keys of the person attributes and their LDAP attributes.
 PERSON = (('first_name', 'givenName'), ('last_name', 'sn'), ('email', 'mail'))
 #: The attributes read for a user.
-ATTRIBUTES = ['uid', 'pwdAccountLockedTime', 'givenName', 'sn', 'mail']
+ATTRIBUTES = ['uid', 'pwdAccountLockedTime', 'givenName', 'sn', 'mail', 'oathTOTPToken']
+#: The readable attributes of a TOTP token; oathSecret is never readable.
+TOKEN_ATTRIBUTES = ['oathTOTPToken', 'oathTOTPParams', 'oathSecretTime', 'oathTOTPLastTimeStep', 'oathTOTPTimeStepDrift',
+                    'oathLastLogin', 'oathLastFailure', 'oathFailureCount']
+#: A TOTP secret as otp_new makes it: 32 base32 characters, 160 bits.
+TOTP_SECRET = re.compile(r'^[A-Z2-7]{32}$')
 #: The attributes read for a group.
 GROUP_ATTRIBUTES = ['cn', 'description', 'member']
 #: The longest group description, in characters.
@@ -145,6 +159,7 @@ def summary(attributes):
         'name': name,
         'enabled': 'pwdAccountLockedTime' not in attributes,
         'certificate': certificate(name)[0].is_file(),
+        'otp': 'oathTOTPToken' in attributes,
     }
     for key, attribute in PERSON:
         values = attributes.get(attribute)
@@ -218,6 +233,49 @@ def enable(connection, name):
     return summary(entry(connection, name))
 
 
+def totp(secret):
+    return pyotp.TOTP(secret, digits=vpnrouter_ldap.TOTP_DIGITS, interval=vpnrouter_ldap.TOTP_PERIOD)
+
+
+def otp_new(connection, name):
+    """A new TOTP secret for the user and its otpauth URI, issued by the router's wan.local_fqdn; nothing is stored."""
+    entry(connection, name)
+    secret = pyotp.random_base32()
+    issuer = vpnrouter.load_config()['wan']['local_fqdn'].strip()
+    return {'name': name, 'secret': secret, 'uri': totp(secret).provisioning_uri(name=name, issuer_name=issuer or None)}
+
+
+def otp_enrol(connection, name, secret, code):
+    """Store the secret of otp_new as the user's TOTP token, replacing one the user has, when code is a code of it."""
+    current = entry(connection, name)
+    if not isinstance(secret, str) or not TOTP_SECRET.match(secret):
+        raise Failure('the secret must be 32 base32 characters, as a new secret has them', 2)
+    if not isinstance(code, str) or not re.fullmatch(rf'\d{{{vpnrouter_ldap.TOTP_DIGITS}}}', code):
+        raise Failure(f'the code must be {vpnrouter_ldap.TOTP_DIGITS} digits', 2)
+    if not totp(secret).verify(code, valid_window=vpnrouter_ldap.TOTP_WINDOW):
+        raise Failure('the code does not match the secret; check the clock of the authenticator', 2)
+    changes = [] if 'oathTOTPToken' in current else [(ldap.MOD_ADD, 'objectClass', [b'oathTOTPUser', b'oathTOTPToken'])]
+    changes += [
+        (ldap.MOD_REPLACE, 'oathTOTPToken', [dn_of(name).encode()]),
+        (ldap.MOD_REPLACE, 'oathTOTPParams', [vpnrouter_ldap.TOTP_PARAMS.encode()]),
+        (ldap.MOD_REPLACE, 'oathSecret', [base64.b32decode(secret)]),
+        (ldap.MOD_REPLACE, 'oathSecretTime', [time.strftime('%Y%m%d%H%M%SZ', time.gmtime()).encode()]),
+    ]
+    connection.modify_s(dn_of(name), changes)
+    return summary(entry(connection, name))
+
+
+def otp_remove(connection, name):
+    """Remove the user's TOTP token, when the user has one."""
+    if 'oathTOTPToken' in entry(connection, name):
+        token = connection.search_s(dn_of(name), ldap.SCOPE_BASE, attrlist=TOKEN_ATTRIBUTES)[0][1]
+        changes = [(ldap.MOD_DELETE, 'objectClass', [b'oathTOTPUser', b'oathTOTPToken']),
+                   (ldap.MOD_DELETE, 'oathSecret', None)]
+        changes += [(ldap.MOD_DELETE, attribute, None) for attribute in token]
+        connection.modify_s(dn_of(name), changes)
+    return summary(entry(connection, name))
+
+
 def remove(connection, name):
     """Remove the user from its groups and the directory, and revoke the certificate.
 

debian-package/src/usr/lib/vpn-router/web

@@ -11,8 +11,8 @@ Pages:
   /config  the configuration without its secrets, and what the router resolved and
            runs, as JSON
   /users   the users in the router's directory, whether or not a P2S system is enabled: list,
-           add, change, set the password, disable, enable, remove, and the OpenVPN client
-           profile (see users())
+           add, change, set the password, disable, enable, remove, the OpenVPN client
+           profile, and TOTP enrolment (see users())
   /groups  the groups of the router's directory: list, add, rename or describe, remove, and
            add and take out members (see groups())
 
@@ -422,6 +422,9 @@ def users(state, method, path, body):
       POST   /users/<name>/enable     let the user in again
       DELETE /users/<name>            remove the user and revoke the certificate
       GET    /users/<name>/profile    the OpenVPN client profile
+      POST   /users/<name>/otp        a new TOTP secret and its otpauth URI; nothing is stored
+      PUT    /users/<name>/otp        store a TOTP secret: {"secret", "code"}, code a code of the secret
+      DELETE /users/<name>/otp        remove the TOTP token
     """
     if body == 'invalid' or (body is not None and not isinstance(body, dict)):
         return 400, {'error': 'the body must be a JSON object'}
@@ -438,6 +441,9 @@ def users(state, method, path, body):
         ('POST', 3, 'enable'): lambda connection: vpnrouter_users.enable(connection, name),
         ('DELETE', 2, None): lambda connection: vpnrouter_users.remove(connection, name),
         ('GET', 3, 'profile'): lambda connection: vpnrouter_users.profile(connection, name),
+        ('POST', 3, 'otp'): lambda connection: vpnrouter_users.otp_new(connection, name),
+        ('PUT', 3, 'otp'): lambda connection: vpnrouter_users.otp_enrol(connection, name, body.get('secret'), body.get('code')),
+        ('DELETE', 3, 'otp'): lambda connection: vpnrouter_users.otp_remove(connection, name),
     }
     if route not in actions:
         return 404, {'error': f'no route {method} {path}'}