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
1 year ago · c44a3f45de
parent 5783d086ad
commit c44a3f45de
3 changed files with 120 additions and 3 deletions
--- a/.gitignore
+++ b/.gitignore
@ -14,3 +14,5 @@ venv/
 !.devcontainer/
 !.devcontainer/*.json
 *.whl
+build/
+extract_otp_secret_keys.egg-info/
--- 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 🇺🇦
--- a/setup.py
+++ 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)',
+)