CLI client for RFC 4226's HOTP and RFC 6238's TOTP.

Overview

One Time Password (OTP, TOTP/HOTP)

Python 3.10 Code style: black pdm-managed pre-commit


OTP serves as additional protection in case of password leaks.

onetimepass allows you to manage OTP codes and generate a master key. The master key allows the base to be decrypted and encrypted. Make sure to keep it in a safe place, otherwise it will not be possible to recover the data.

onetimepass supports as an optional dependency the integration with the system keychain (cross-platform) in which the application saves the master key.

Requirements

  • Python 3.10+
  • PDM 1.11+

Installation

$ pdm install

To include the optional keychain support:

$ pdm install -G keyring

Usage

Initialize database

At the very beginning, the database must be initialised, which additionally creates the master key. It will save it to the keychain if this has been installed.

By default, it will print the generated key to the STDOUT. You need this behavior if you don't use the optional keychain integration.

If you do, you can pass the -q, --quiet option to silence the output.

Keychain integration

The application will automatically detect if you have the keychain integration installed, however, if you want to force enable/disable it, you can by using respectively the -k, --keyring and -K, --no-keyring options.

Although, if you don't have the keychain integration installed, enabling it won't work:

Print the master key

It is possible to print the current master key stored in the keychain (if you need this for e.g. migrating the app to the different device).

This of course won't work if you don't use the keychain integration.

Adding new OTP alias

onetimepass identifies the added OTP codes via the user-specified aliases, which should be short, easy-to-remember names.

onetimepass allows you to add new alias in two ways, either by specifying all the parameters manually, using add hotp or add totp commands (depending on which type of the OTP you want to add), or by providing the de facto standard URI invented by the Google.

Adding via URI (command will aks interactively for the URI)

$ pdm run otp add uri AWS-root
Enter URI:
Repeat for confirmation:

Example URIs

Adding via totp/hotp subcommand (command will ask interactively for the secret):

$ pdm run otp add totp AWS-root
Enter secret:
Repeat for confirmation:
$ pdm run otp add hotp AWS-root
Enter secret:
Repeat for confirmation:

Removing OTP alias

$ pdm run otp rm <alias>
Are you sure? [y/N]:

To omit the interactive confirmation ( ⚠️ unsafe!), pas the --yes option.

Showing OTP code

Show single OTP identified by alias

$ pdm run otp show <alias>

You can force the app to wait until the new OTP code is valid, in case the current one will be invalid in a short period of time (so you won't have to rush with copy-pasting the code, or wait manually), using -w, --wait-for-next option.

$ pdm run otp show -w <seconds> <alias>

This will accept the seconds of tolerance (if the remaining time of the current code to be valid is less than seconds, the app will wait, otherwise it will show the current code).

You can easily automate it even more:

$ pdm run otp show -w 10 <alias> | cut -d' ' -f2 | pbcopy; alert

To extract the code when it's ready, then copy it to the system clipboard (pbcopy for macOS, xclip for Linux), and send the system notification to yourself when it's all finished (assuming you have the alert alias configured, available by default e.g. on Ubuntu Linux).

Show all codes

$ pdm run otp show-all

You can emulate the view known from the Google Authenticator (list of all the codes, refreshed dynamically) by wrapping the application in the external watcher (e.g. watch):

$ watch -c -p -n 1 pdm run otp show-all

Database import/export

In case you want to migrate the application to the different device, you can export the local database to the format of choice (currently only the json is supported) and then import it.

You can use this not only to transfer the application between the devices, but also to create backups: because onetimepass is a CLI-based tool, you can even implement the cronjob that will periodically run the export in the background ( ⚠️ just remember to encrypt the resulting file and store it somewhere safe).

Shell Completion

onetimepass can provide tab completion for commands, options, and choice values. Bash, Zsh, and Fish are supported

$ pdm run zsh
$ eval "$(_OTP_COMPLETE=zsh_source otp)"
$ pdm run bash
$ eval "$(_OTP_COMPLETE=bash_source otp)"

Rationale

As the onetimepass have multiple alternatives, you may ask why bother with reinventing the wheel instead of using any existing solution.
This section addresses that.

Existing alternatives

Google Authenticator

The main issue with this app is that it does not offer any way to backup the secrets, and synchronize them between the devices.

If you don't have the backup of the original QR codes, and you'll lose your mobile phone, you're screwed. Yes, services that provide the 2FA often offer the backup codes, but not every one of them, and this is not the optimal solution.

In theory, if you root the device, you can access the local database, but not everyone wants or can root their mobile phone, as this can e.g. void a device's warranty.

Besides, if you root the device, you can see the local database is stored in the plain text, which is a big security risk.

Authy

It does allow synchronizing secrets between the devices, but this happens through the provider servers. The application neither sent nor store your backup password, but it can still be non-optimal for some people to trust the external provider to handle such sensitive data.

Also, Authy does not support export or import of the secrets.

pass or gopass

pass is an extensible CLI-based password manager, and there is a pass-otp plugin to handle TOTP (although, HOTP is not supported).

One issue is that it uses GnuPG for encrypting the local database, which can be tedious to configure:

To be honest, a few first times I tried to configure it, I failed miserably. This should be much easier and faster. ~ Daniel Staśczak

The second issue is that, as mentioned above, pass is primarily the password manager. If one wants only the TOTP client, it's a little bit of an overkill to install the whole password manager for that.

The GUI clients in general

This is more of a personal preference, but if you use the GUI-based OTP client, especially on your mobile phone, there are some extra steps everytime you need to use it:

  1. You have to get your phone.
  2. You have to open the app.
  3. You have to type the code manually, if you need to enter the code on another device (e.g. to authorize on the desktop).

This is not very inconvenient, but I bet there were at least few times when you didn't had your phone with you while you had to authorize into the AWS account while working on something urgent, or get your phone out of the pocket every few hours, because the Keeper logged out you out of a sudden once again in a day.

If you're CLI power-user, using the CLI-based tool is just much quicker and convenient. And you can create some crazy pipelines (see the examples in the Usage section).

Security

While onetimepass does reinvent a wheel in general, one of the main goals of the project is to still be a secure solution, and do not reinvent the wheel in regard to the security. Because of this reason, for generating the master key and encrypting the local database, the high-level cryptographic library is used.

The main algorithm for the HOTP/TOTP is implemented based on the official RFC and the reference implementation.

There are some functionalities which can be a security hole if used in an irresponsible manner (e.g. export, key), but the same can be said about the sudo rm -rf --np-preserve-root /, right?

Nevertheless, if you see any security issue, please feel free to report it, we're more than happy to consider it.

Owner
Apptension
We are a fellow custom software development company for Startups, Investors and Agencies.
Apptension
A CLI application for storing contacts as a csv file written in Python.

Contacter A CLI application for storing contacts as a csv file written in Python. You can use this to save your contacts with a special relations tag

nostalgicnerdpenguin 1 Oct 23, 2021
Convert shellcode into :sparkles: different :sparkles: formats!

Bluffy Convert shellcode into ✨ different ✨ formats! Bluffy is a utility which was used in experiments to bypass Anti-Virus products (statically) by f

AD995 305 Dec 17, 2022
A command line interface to interact with the Hypixel api allowing the user to get stats, leaderboards, etc

HyConsole is a way to get data on players and leaderboards from the Hypixel Minecraft server from the command line. Keep in mind I have no a

1 Feb 14, 2022
A multipurpose discord bot with more than 220 commands

Welcome WM Bot A advanced bot with more than 220 commands to fit your needs Explore the commands » View Demo · Report Bug · Request Feature Table of C

Wasi Master 12 Dec 16, 2022
dcargs is a tool for generating portable, reusable, and strongly typed CLI interfaces from dataclass definitions.

dcargs is a tool for generating portable, reusable, and strongly typed CLI interfaces from dataclass definitions.

Brent Yi 119 Jan 09, 2023
A project designed to make taking notes easier than ever - by doing it all on command line

A project designed to make taking notes easier than ever - by doing it all on command line! Yes, all of your files are easily accessible through one command interface, and can be written to at any ti

1 Dec 10, 2021
GoogleFormSpammer - A simple CLI script to spam Google Forms used by Crypto Wallet scammers to collect stolen data

GoogleFormSpammer - A simple CLI script to spam Google Forms used by Crypto Wallet scammers to collect stolen data

14 Dec 17, 2022
A minimal ascii-representation of your local weather.

Ascii-Weather A simple, ascii-based weather visualizer for the terminal. The ascii-art updates to match the current weather and conditions. Uses ipinf

Aaron R. 12 Jan 29, 2022
My dotfiles -My configuration, with installations steps.

.dotfiles My configuration, with installations steps. Installation Oh My ZSH Install with this command: sh -c "$(curl -fsSL https://raw.githubusercont

Luca Angioloni 4 Dec 14, 2022
Squirrel - A cli program to track writing progress

Squirrel Very much a WIP project squirrel is a command line program that tracks you writing progress and gives you useful information and cute and pic

3 Mar 23, 2022
A CLI tool for creating disposable environments.

dispenv - Disposable Python Environments ⚠️ WIP Need to make an environment to work on a GitHub issue? Want to try out a new package and not leave the

Peter Baumgartner 3 Mar 14, 2022
xonsh is a Python-powered, cross-platform, Unix-gazing shell

xonsh is a Python-powered, cross-platform, Unix-gazing shell language and command prompt.

xonsh 6.7k Dec 31, 2022
A command-line tool to upload local files and pastebin pastes to your mega account, without signing in anywhere

A command-line tool to upload local files and pastebin pastes to your mega account, without signing in anywhere

ADI 4 Nov 17, 2022
eBay's TSV Utilities: Command line tools for large, tabular data files. Filtering, statistics, sampling, joins and more.

Command line utilities for tabular data files This is a set of command line utilities for manipulating large tabular data files. Files of numeric and

eBay 1.4k Jan 09, 2023
A simple cli utility for importing or exporting dashboard json definitions using the Grafana HTTP API.

P4CMD 🌴 A Python Perforce package that doesn't bring in any other packages to work. Relies on p4cli installed on the system. p4cmd The p4cmd module h

Beam Connectivity 31 Jan 06, 2023
Simple script to download OTA packages from Realme's endpoint.

Realme OTA Downloader CLI tool (based on this C# program) to create requests to the Realme's endpoint. Requirements Python 3.9. pycryptodome. Installa

Roger Ortiz 64 Dec 28, 2022
ghfetch is ai customizable CLI GitHub personal README generator.

ghfetch is ai customizable CLI GitHub personal README generator. Inspired by famous fetch such as screenfetch, neofetch and ufetch, the purpose of this tool is to introduce yourself as if you were a

Alessio Celentano 3 Sep 10, 2021
The WalletsNet CLI helps you connect to WalletsNet

WalletsNet CLI The WalletsNet CLI helps you connect to WalletsNet. With the CLI, you can: Trigger webhook events or resend events for easy testing Tai

WalletsClub 8 Dec 22, 2021
EODAG is a command line tool and a plugin-oriented Python framework for searching, aggregating results and downloading remote sensed images while offering a unified API for data access regardless of the data provider

EODAG (Earth Observation Data Access Gateway) is a command line tool and a plugin-oriented Python framework for searching, aggregating results and downloading remote sensed images while offering a un

CS GROUP 205 Jan 03, 2023
Lexeme - CLI to play a word-guessing game like Wordle

What is this? Python program to play a word-guessing game like Wordle, but… More addictive because you can play it over and over and over, not just on

Dan Lenski 6 Oct 26, 2022