The TOTP Secrets Adapter is a short script written entirely in Python to help you to setup an authenticator environment on your (trusted) personal computer (notebook, laptop, desktop) to generate the same time-based one-time passwords (TOTP) as the authenticator on your smartphone does. Actually it
- reads exported TOTP secrets
- stores those TOTP secrets secretly by calling the interface of a target authenticator
- saves time, is less error-prone and more secure, as no manual copying/pasting of secrets is required
Supported TOTP secrets exctractors and supported authenticators are listed in section Software.
With the Google Authenticator app on your smartphone you can gather time-based one-time passwords (TOTP) secrets from two-factor authentication (2FA) servers. On User's request, the Google Authenticator takes the gathered secrets and the current time and calculates short-lived TOTP which are shown to the User. Goolge Authenticator generates 6 digit codes. The User can read the codes with the user's eyes and enter those codes to authenticate with the 2FA server.
In order to generate those TOTPs not only by your smartphone, but also with your (trusted) computer, you have to export the secrets. This can be done by using the extract_otp_secrets program which reads the exported QR codes from Google Authenticator by the camera and stores those as .json files. The .json files are being read by the TOTP secrets adapter (this project) which calls the CLI of the authenticator cli. The authenticator cli stores the secrets to an encrypted file called authenticator.data, and the authenticator cli can then produce the same TOTP on your computer as the Google Authenticator on your smartphone does.
- any hardware that can run Python programs
- Microsoft Windows, macOS, or GNU/Linux
- an authenticator app on your smartphone that can export TOTP secrets (e.g. Google Authenticator)
- a supported TOTP secret extractor
- a supported target authenticator
- Pyhton
- the TOTP secrets adapter
| TOTP Extractor | Written in | License | Supported interfaces for the export |
|---|---|---|---|
| Roland's extract_otp_secrets | Python | GPLv3 | JSON |
| Authenticator | Written in | License | Supported interfaces for the import |
|---|---|---|---|
| Dave's authenticator | Pyhton | MIT | CLI + stdin |
To run the script you need Python. You can get it from https://phyton.org
In order to get input data for the totp-secretes-adapter script, you need to export the TOTP secrets. This can be done by the extract_otp_secrets program.
If you want an authenticator with a CLI running on your computer, go to Dave's authenticator and follow the instructions there for installation. It is very easy ...
> pip install authenticator
Go to the releases section, and download the script. To test it, run it by entering ...
> python ./totpsa.py
Usage: ./totpsa.py [json file]...
Google Authenticator can export the TOTP secrets.
- Open the extract_otp_secrets app
- Open the Google Authenticator app on your smartphone
- Select export accounts from the Hamburger menu
- Generate QR-Codes, and for each QR-Code
- Show your smartphone to your webcam and hit 'j' to save the secets as .json
- Enter a suitable filename to save the .json
- Depending on the number of exported accounts, you may have to store more than one .json
You should now have one ore more .json files
> ls *.json
Import the secrets to the target authenticator
> python ./totpsa.py *.json
> authenticator list
> authenticator generate
This adapter only supports authenticators with a command line interface (CLI) if it takes the following security concepts into account:
- the authenticator accepts secrets on the console (user input) and not (only) as program arguments or pipes, because we do not want to see the secret in plain text in process tables in multi-user environments. We also do not want to see secrets in plain text in command line history files.
- the authenticator encrypts its own database with a password and a secure state-of-the-art algorithm
Use the protection mechanism of your authenticator and set a good password. If you don't know how to set good passwords read this article.
To transfer TOTP secrets you should prefer to use cameras only to read QR codes that contain the secrets. Do not store the TOTP secrets on unencryted media such as paper or USB thumb drives, because it is impossible to remove data from them securely without destroying them.
You should remove the exported files after the import is done, because secrets should not be stored without encryption.
The German Federal Office for Information Security (BSI) recommends always using two different devices for the login and the second factor. This significantly increases the protection of user accounts and data.
The factors should always originate from more than one device. So you should not confirm payments with the device you use to initiate the transfer, for example. This makes it much more difficult for criminals to intercept your second factor.
Source: BSI
and
If you no longer have access to your possession-based factor or it breaks, you will usually lose access to the corresponding service or its functionality will be restricted. Take precautions for this scenario by — where possible — storing several 'second' factors.
Source: BSI
If you use multiple devices with an authentication it is important that you protect each of those devices. Enabling disk encryption is best practice.
If your smartphone is not too old, the smartphone operating system has encryption enabled by default. However, this might not be the case for notebooks, laptops, or desktop PCs. If your notebook or laptop gets stolen, the thief could bypass the operating system protective measures and gain access to the disk hardware directly. Disk encryption can prevent that threat. On Windows you could use Bitlocker or Veracrypt.