You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
108 lines
3.1 KiB
Markdown
108 lines
3.1 KiB
Markdown
# Extract TOTP/HOTP secret keys from Google Authenticator
|
|
|
|
[![CI Status](https://github.com/scito/extract_otp_secret_keys/actions/workflows/ci.yml/badge.svg)](https://github.com/scito/extract_otp_secret_keys/actions/workflows/ci.yml)
|
|
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/protobuf)
|
|
![GitHub Pipenv locked Python version](https://img.shields.io/github/pipenv/locked/python-version/scito/extract_otp_secret_keys)
|
|
![License](https://img.shields.io/github/license/scito/extract_otp_secret_keys)
|
|
|
|
---
|
|
|
|
Extract two-factor authentication (2FA, TFA) secret keys from export QR codes of "Google Authenticator" app
|
|
|
|
## Usage
|
|
|
|
1. Export the QR codes from "Google Authenticator" app
|
|
2. Read QR codes with QR code reader
|
|
3. Save the captured QR codes in a text file. Save each QR code on a new line. (The captured QR codes look like `otpauth-migration://offline?data=...`)
|
|
4. Call this script with the file as input:
|
|
|
|
python extract_otp_secret_keys.py -p example_export.txt
|
|
|
|
## Dependencies
|
|
|
|
pip install -r requirements.txt
|
|
|
|
Known to work with
|
|
|
|
* Python 3.10.6, protobuf 4.21.5, qrcode 7.3.1, and pillow 9.2
|
|
|
|
### Optional
|
|
|
|
For printing QR codes, the qrcode module is required, otherwise it can be omitted.
|
|
|
|
pip install qrcode[pil]
|
|
|
|
## Technical background
|
|
|
|
The export QR code of "Google Authenticator" contains the URL `otpauth-migration://offline?data=...`.
|
|
The data parameter is a base64 encoded proto3 message (Google Protocol Buffers).
|
|
|
|
Command for regeneration of Python code from proto3 message definition file (only necessary in case of changes of the proto3 message definition or new protobuf versions):
|
|
|
|
protoc --python_out=protobuf_generated_python google_auth.proto
|
|
|
|
The generated protobuf Python code was generated by protoc 21.5 (https://github.com/protocolbuffers/protobuf/releases/tag/v21.5).
|
|
|
|
## References
|
|
|
|
* Proto3 documentation: https://developers.google.com/protocol-buffers/docs/pythontutorial
|
|
* Template code: https://github.com/beemdevelopment/Aegis/pull/406
|
|
|
|
## Alternative installation methods
|
|
|
|
### pipenv
|
|
|
|
You can you use [Pipenv](https://github.com/pypa/pipenv) for running extract_otp_secret_keys.
|
|
|
|
```
|
|
pipenv install
|
|
pipenv shell
|
|
python extract_otp_secret_keys.py example_export.txt
|
|
```
|
|
|
|
### venv
|
|
|
|
Alternatively, you can use a python virtual env for the dependencies:
|
|
|
|
python -m venv venv
|
|
. venv/bin/activate
|
|
pip install -r requirements-buildenv.txt
|
|
pip install -r requirements.txt
|
|
|
|
The requirements\*.txt files contain all the dependencies (also the optional ones).
|
|
To leave the python virtual env just call `deactivate`.
|
|
|
|
### devbox
|
|
|
|
Install [devbox](https://github.com/jetpack-io/devbox), which is a wrapper for nix. Then enter the environment with Python and the packages installed with:
|
|
|
|
```
|
|
devbox shell
|
|
```
|
|
|
|
## Tests
|
|
|
|
### PyTest
|
|
|
|
There are basic [pytest](https://pytest.org)s, see `test_extract_otp_secret_keys_pytest.py`.
|
|
|
|
Run tests:
|
|
|
|
```
|
|
pytest
|
|
```
|
|
or
|
|
```
|
|
python -m pytest
|
|
```
|
|
|
|
### unittest
|
|
|
|
There are basic [unittest](https://docs.python.org/3.10/library/unittest.html)s, see `test_extract_otp_secret_keys_unittest.py`.
|
|
|
|
Run tests:
|
|
|
|
```
|
|
python -m unittest
|
|
```
|