From a810ed59f7fd7eaaca75a58d6d8f0970b3452e1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maximilian=20Ke=C3=9Fler?= Date: Sat, 25 Jun 2022 13:51:19 +0200 Subject: [PATCH] more explanation in README --- README.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2b98fb3..37e0006 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,28 @@ 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][FreeOTP]) or devices (e.g. [sct][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. + # Installation You need [zbar][zbar] as a QR-code reader library. @@ -13,8 +35,15 @@ On Ubuntu, install `zbar-tools`. Additionally, you need `python3` and the `pip` packages listed in `requirements.txt`. - # Usage +Call the `totp.py` 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. [zbar]: https://github.com/mchehab/zbar +[freeotp]: https://freeotp.github.io/ +[sct]: https://authenticator.reiner-sct.com/en/