MinTOTP

MinTOTP is a minimal TOTP generator written in Python.

[ PyPI Package ][pypi] [ PyPI Hits ][pypi] [][L]

Introduction
Source Code
Install
- From PyPI
- From GitHub
Get Started
- With Base32 Key
- With QR Code
Protect Key with GPG
Usage
- Multiple Keys
- Command Line Arguments
Tradeoff
Alternative: OATH Toolkit
Resources
License
Thanks

Introduction

TOTP stands for Time-Based One-Time Password. Many websites and services require two-factor authentication (2FA) or multi-factor authentication (MFA) where the user is required to present two or more pieces of evidence:

Something only the user knows, e.g., password, passphrase, etc.
Something only the user has, e.g., hardware token, mobile phone, etc.
Something only the user is, e.g., biometrics.

A TOTP value serves as the second factor, i.e., it proves that the user has a device (e.g., mobile phone) that contains a TOTP secret key from which the TOTP value is generated. Usually the service provider that provides a user's account also issues a secret key encoded either as a Base32 string or as a QR code. This secret key is added to an authenticator app (e.g., Google Authenticator) on a mobile device. The app can then generate TOTP values based on the current time. By default, it generates a new TOTP value every 30 seconds.

MinTOTP is a Python tool that can be used to generate TOTP values from a secret key. Additionally, it exposes its functionality as module-level functions for Python developers. It can be used on any system with Python 3.4 or later installed on it.

Source Code

At the heart of the TOTP algorithm lies the HOTP algorithm. HOTP stands for HMAC-based One-Time Password. HMAC stands for Hash-based Message Authentication Code. Here are the relevant RFCs to learn more about these algorithms:

RFC 2104: HMAC: Keyed-Hashing for Message Authentication
RFC 4226: HOTP: An HMAC-Based One-Time Password Algorithm
RFC 6238: TOTP: Time-Based One-Time Password Algorithm

The source code in mintotp.py generates TOTP values from a secret key and current time. It's just 30 lines of code (actually 20 lines if we ignore the shebang and blank lines). There are no comments in the code, so a brief description of the code is presented in this section. Here is the entire code presented once again for convenience:

#!/usr/bin/env python3

import base64
import hmac
import struct
import sys
import time


def hotp(key, counter, digits=6, digest='sha1'):
    key = base64.b32decode(key.upper() + '=' * ((8 - len(key)) % 8))
    counter = struct.pack('>Q', counter)
    mac = hmac.new(key, counter, digest).digest()
    offset = mac[-1] & 0x0f
    binary = struct.unpack('>L', mac[offset:offset+4])[0] & 0x7fffffff
    return str(binary)[-digits:].zfill(digits)


def totp(key, time_step=30, digits=6, digest='sha1'):
    return hotp(key, int(time.time() / time_step), digits, digest)


def main():
    args = [int(x) if x.isdigit() else x for x in sys.argv[1:]]
    for key in sys.stdin:
        print(totp(key.strip(), *args))


if __name__ == '__main__':
    main()

In the code above, we use the hmac module available in the Python standard library to implement HOTP. The implementation can be found in the hotp() function. It is a pretty straightforward implementation of RFC 2104: Section 5: HOTP Algorithm. It takes a Base32-encoded secret key and a counter as input. It returns a 6-digit HOTP value as output.

The totp() function implements the TOTP algorithm. It is a thin wrapper around the HOTP algorithm. The TOTP value is obtained by invoking the HOTP function with the secret key and the number of time intervals (30-second intervals by default) that have elapsed since Unix epoch (1970-01-01 00:00:00 UTC).

Install

MinTOTP requires Python 3.4 or later. If Python 3.4 or later is present on your system, follow one of the two sections below to get MinTOTP on your system.

From PyPI

If you want to install the MinTOTP package from [PyPI][pypi] as a Python module on your system, then follow the steps provided below. Doing so makes MinTOTP available as the mintotp command that you can run on the terminal. A module named mintotp also becomes available that you can import in your own Python code.

Enter the following command to install MinTOTP on your system:
```
pip3 install mintotp
```
Test that MinTOTP works fine as a command:
```
mintotp <<< ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS
```
A 6-digit TOTP value should appear as the output.
Test that MinTOTP can be used as a library module:
```
$ python3
>>> import mintotp
>>> mintotp.totp('ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS')
>>> mintotp.hotp('ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS', 42)
```
The totp() function call should return a 6-digit TOTP value based on the current time. The hotp() call should return the following HOTP value: 626854.

From GitHub

If you do not want to install MinTOTP to your system as a command but you want to work with the mintotp.py source file directly clone the GitHub repository of this project.

Clone GitHub repository of this project and enter its top-level directory.
```
git clone https://github.com/susam/mintotp.git
cd mintotp
```
Test that mintotp.py works fine:
```
python3 mintotp.py <<< ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS
```
A 6-digit TOTP value should appear as the output.
Test that mintotp.py can be imported as a module:
```
$ python3
>>> import mintotp
>>> mintotp.totp('ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS')
>>> mintotp.hotp('ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS', 42)
```
The totp() function call should return a 6-digit TOTP value based on the current time. The hotp() call should return the following HOTP value: 626854.

All examples provided in the sections below assume that MinTOTP has been installed from PyPI. If you choose to use MinTOTP from GitHub instead, replace all occurrences of mintotp in the example commands below with python3 mintotp.py.

Get Started

This section presents a few examples to quickly get started with MinTOTP.

Note that this section uses a few example secret keys and QR codes. They are merely examples that come with this project for you to quickly test the program with. They should not be used for any real account that requires TOTP-based two-factor authentication. Usually, the issuer of a real account (such as an account on a website or an organization) would also issue a secret key or a secret QR code to you which you must use to generate TOTP values for the purpose of logging into that account.

With Base32 Key

Enter this command:
```
mintotp <<< ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS
```
The output should be a 6-digit TOTP value.
Add the following key to a TOTP-based authenticator app:
```
ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS
```
For example, if you have Google Authenticator on your mobile phone, open it, tap the button with plus sign, select "Enter a provided key", enter any account name and "Time-based" and enter the above key. Set the dropdown menu to "Time-based" and tap the "Add" button. A 6-digit TOTP value should appear for the new key.
Run the command in step 1 again and verify that the TOTP value printed by the Python program matches the TOTP value that appears in the authenticator app.

With QR Code

Install zbarimg to scan QR codes:

# On macOS
brew install zbar

# On Debian, Ubuntu, etc.
apt-get install zbar-tools

Download and save the following QR code on your system:

The QR code above can also be found in this file: secret1.png.
Enter this command to read the data in the QR code:
```
zbarimg -q secret1.png
```
The output should be:
```
QR-Code:otpauth://totp/alice:bob?secret=ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS
```
Note that the secret key in the URI is the same as the secret key we used in the previous sections.
Now enter this command to extract the secret key from the QR code and feed it to MinTOTP.
```
zbarimg -q secret1.png | sed 's/.*secret=$[^&]*$.*/\1/' | mintotp
```
Scan the QR code shown above in step 3 with a TOTP-based authenticator app. For example, if you have Google Authenticator on your mobile phone, open it, tap the button with plus sign, select "Scan a barcode", and scan the QR code shown above in step 3. A 6-digit TOTP value should appear for the new key.
Run the command in step 4 again and verify that the TOTP value printed by MinTOT

Mintotp

Install / Use

README