Minimal TOTP generator in 20 lines of Python
MinTOTP is a minimal TOTP generator written in Python.
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:
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.
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:
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:
…
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).
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.
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.
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.
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.
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.
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 MinTOTP matches the TOTP value that appears in the authenticator app.
The previous sections use an example key and QR code to show how this tool works. If you use this tool to generate TOTP values from a real secret key for a real account, you must encrypt your secret key to keep it safe. The next two subsections explain how to protect the key with GNU Privacy Guard (also known as GnuPG or GPG).
Install GNU Privacy Guard:
# On macOS
brew install gnupg
# On Debian, Ubuntu, etc.
apt-get update
apt-get install gnupg
Enter the following command to ensure that GPG is installed.
gpg --version
If GPG is installed properly, the command above should print its version, license details, and cipher details.
The steps below show the usage of GPG to encrypt our example secret key. You would have to replace this example secret key with a real secret key that you want to use to generate TOTP values.
Encrypt the secret key using GPG. First enter this command:
gpg -c -o secret.gpg
Then enter a strong passphrase when it prompts for it. Re-enter the passphrase to confirm it. Then paste the following key as input:
ZYTYYE5FOAGW5ML7LRWUL4WTZLNJAMZS
Press enter to end the line. Press ctrl +
d to end input. The encrypted secret key would be saved
in a file named secret.gpg.
Generate TOTP value from the encrypted key:
gpg -q -o - secret.gpg | mintotp
You can also generate TOTP value and copy it to system clipboard:
# On macOS
gpg -q -o - secret.gpg | mintotp | tr -d '\n' | pbcopy
# On Linux
gpg -q -o - secret.gpg | mintotp | tr -d '\n' | xclip
Now you can easily paste the TOTP value to any login form that
requires it. On Linux, of course, you need to have xclip installed
to use it. On Debian, Ubuntu, etc. it can be installed with the
apt-get install xclip command. To paste the value copied into the
clipboard by xclip, middle-click on your mouse.
In case you want to see the TOTP value on the terminal while it is also copied to the system clipboard, use one of these commands:
# On macOS
gpg -q -o - secret.gpg | mintotp | tee /dev/stderr | tr -d '\n' | pbcopy
# On Linux
gpg -q -o - secret.gpg | mintotp | tee /dev/stderr | tr -d '\n' | xclip
The steps below show the usage of GPG to encrypt our example QR code. You would have to replace the example QR code with a
No open issues yet, or sync has not completed.