From c44a3f45de839e8b8512f9ec1f78a5a5a66530c3 Mon Sep 17 00:00:00 2001 From: scito Date: Sat, 10 Dec 2022 12:23:13 +0100 Subject: [PATCH] add pip installation; improve README - improve README - add Installation section - add Features section - add Glossary - add related projects - add setup.py for pip installation: pip install git+https://github.com/scito/extract_otp_secret_keys --- .gitignore | 2 ++ README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++--- setup.py | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 120 insertions(+), 3 deletions(-) create mode 100644 setup.py diff --git a/.gitignore b/.gitignore index f038e9f..3edc334 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,5 @@ venv/ !.devcontainer/ !.devcontainer/*.json *.whl +build/ +extract_otp_secret_keys.egg-info/ diff --git a/README.md b/README.md index 520e5db..2e4cbf0 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,14 @@ --- -Extract two-factor authentication (2FA, TFA, one time passwords, otp) secret keys from export QR codes of "Google Authenticator" app. +Extract two-factor authentication (2FA, TFA, OTP) secret keys from export QR codes of "Google Authenticator" app. The secret and otp values can be printed and exported to json or csv. The QR codes can be printed or saved as PNG images. +## Installation + +git clone https://github.com/scito/extract_otp_secret_keys.git +cd extract_otp_secret_keys + ## Usage 1. Open "Google Authenticator" app on the mobile phone @@ -22,7 +27,7 @@ The secret and otp values can be printed and exported to json or csv. The QR cod 5. Transfer the file to the computer where his script is installed. 6. Call this script with the file as input: - python extract_otp_secret_keys.py example_export.txt + python extract_otp_secret_keys.py example_export.txt ## Program help: arguments and options @@ -48,7 +53,7 @@ options: Known to work with * Python 3.10.8, protobuf 4.21.9, qrcode 7.3.1, and pillow 9.2 -* Python 3.11.0, protobuf 4.21.10, qrcode 7.3.1, and pillow 9.2 +* Python 3.11.1, protobuf 4.21.10, qrcode 7.3.1, and pillow 9.2 For protobuf versions 3.14.0 or similar or Python 3.6, use the extract_otp_secret_keys version 1.4.0. @@ -58,6 +63,27 @@ For printing QR codes, the qrcode module is required, otherwise it can be omitte pip install qrcode[pil] +## Features + +* Free and open source +* Supports Google Authenticator export +* All functionality in one Python script: extract_otp_secret_keys.py (except protobuf generated code in protobuf_generated_python) +* Supports TOTP and HOTP +* Generates QR codes +* Various export formats: + * CSV + * JSON + * Dedicated CSV for KeePass + * QR code images +* Many ways to run the script: + * Native Python + * pipenv + * venv + * Docker + * VSCode devcontainer + * devbox + * pip + ## KeePass [KeePass 2.51](https://keepass.info/news/n220506_2.51.html) (released in May 2022) and newer [support the generation of OTPs (TOTP and HOTP)](https://keepass.info/help/base/placeholders.html#otp). @@ -112,8 +138,31 @@ The generated protobuf Python code was generated by protoc 21.10 (https://github * Proto3 documentation: https://developers.google.com/protocol-buffers/docs/pythontutorial * Template code: https://github.com/beemdevelopment/Aegis/pull/406 +## Glossary + +* OTP = One-time password +* TOTP = Time-based one-time password +* HOTP = HMAC-based one-time password (using a counter) +* 2FA = Second factor authentication +* TFA = Two factor authentication +* QR code = Quick response code + ## Alternative installation methods +### pip + +``` +pip install git+https://github.com/scito/extract_otp_secret_keys +python -m extract_otp_secret_keys +``` + +#### Example + +``` +wget https://raw.githubusercontent.com/scito/extract_otp_secret_keys/master/example_export.txt +python -m extract_otp_secret_keys example_export.txt +``` + ### pipenv You can you use [Pipenv](https://github.com/pypa/pipenv) for running extract_otp_secret_keys. @@ -212,6 +261,12 @@ Setup for running the tests in VSCode. pip install -U -r requirements.txt ``` +## Related projects + +* [ZBar](https://github.com/mchehab/zbar) is an open source software suite for reading bar codes from various sources, including webcams. +* [Aegis Authenticator](https://github.com/beemdevelopment/Aegis) is a free, secure and open source 2FA app for Android. +* [Android OTP Extractor](https://github.com/puddly/android-otp-extractor) can extract your tokens from popular Android OTP apps and export them in a standard format or just display them as QR codes for easy importing. [Requires a _rooted_ Android phone.] + *** # #StandWithUkraine πŸ‡ΊπŸ‡¦ diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..2613dad --- /dev/null +++ b/setup.py @@ -0,0 +1,60 @@ +import pathlib +from setuptools import setup + +setup( + name='extract_otp_secret_keys', + version='1.6.0', + description='Extract two-factor authentication (2FA, TFA, OTP) secret keys from export QR codes of "Google Authenticator" app', + + long_description=(pathlib.Path(__file__).parent / 'README.md').read_text(), + long_description_content_type='text/markdown', + + url='https://github.com/scito/extract_otp_secret_keys', + author='scito', + author_email='info@scito.ch', + + classifiers=[ + 'Development Status :: 5 - Production/Stable', + + 'Environment :: Console', + 'Topic :: System :: Archiving :: Backup', + 'Topic :: Utilities', + + 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Programming Language :: Python :: 3.11', + + 'Intended Audience :: End Users/Desktop', + 'Intended Audience :: Developers', + 'Intended Audience :: System Administrators', + + 'Programming Language :: Python' + 'Natural Language :: English', + 'License :: OSI Approved :: GNU General Public License v3 (GPLv3)', + ], + + keywords='python security json otp csv protobuf qrcode two-factor totp google-authenticator recovery proto3 mfa two-factor-authentication tfa qr-codes otpauth 2fa security-tools', + + py_modules=['extract_otp_secret_keys', 'protobuf_generated_python.google_auth_pb2'], + entry_points={ + 'console_scripts': [ + 'extract_otp_secret_keys = extract_otp_secret_keys:sys_main', + ] + }, + + python_requires='>=3.7, <4', + install_requires=[ + 'protobuf', + 'qrcode', + 'Pillow' + ], + + project_urls={ + 'Bug Reports': 'https://github.com/scito/extract_otp_secret_keys/issues', + 'Source': 'https://github.com/scito/extract_otp_secret_keys', + }, + + license='GNU General Public License v3 (GPLv3)', +)