Decode and encode TOTP QR-codes to/from json easily.
Go to file
Maximilian Keßler 7c137c218c fix links in readme 2022-06-25 13:59:26 +02:00
.gitignore initial commit 2022-06-25 13:40:44 +02:00 fix links in readme 2022-06-25 13:59:26 +02:00
UNLICENSE rename unlicense 2022-06-25 13:58:08 +02:00
requirements.txt initial commit 2022-06-25 13:40:44 +02:00 initial commit 2022-06-25 13:40:44 +02:00

TOTP Generator

A simple python script used to decode and encode TOTP QR-Codes.

What is TOTP?

TOTP is a a form of two factor authentication known as a 'Time based one time password'. Client and server have to both know a secret, from which they generate time-dependent (one-time) passcodes as a second factor. This is not an implementation of the TOTP protocol, many corresponding apps (e.g. FreeOTP) or devices (e.g. Reiner SCT) exist.

Why do I need this?

Probably you don't, here the authors use-case is explained.

Usually, these apps/devices scan the initial secret along with some metadata using a QR code that will be provided by the web-service when setting up 2FA. This script decodes those QR-codes, enabling plain text editing of them and re-builds QR codes. This way, fully-functional 2FA entries can be produced while allowing to edit metadata.

Additionally, a high error-correction level is chosen to simplify scanning with your authenticator device/app.

The author uses this as some websites don't set their metadata correctly (e.g. not setting a username, prohibiting distinguishing multiple accounts on the same website) or have names too long to be displayed conveniently.


You need zbar as a QR-code reader library. This can usually be installed via your distribution.

On Arch Linux, install the zbar package. On Ubuntu, install zbar-tools.

Additionally, you need python3 and the pip packages listed in requirements.txt.


Call the script. Input QR codes can be placed into the in folder (use screenshots for this). They will be parsed and their data extracted in json format in the json folder. You can then edit the json files to your willings. Calling the script again will produce new QR codes in the out folder which you can scan.

WARNING: obviously, the in, json and out folders will contain sensitive data (your 2FA secrets). You will probably want to delete them after scanning into your app.