Brief notes on doing TOTP MFA with oathtool

October 1, 2023

Time-Based One-time Passwords (TOTP) are one of the most common ways of doing multi-factor authentication today and are, roughly speaking, the only one you can use if the machine you're authenticating on is a Linux machine. Especially, I believe they're the only one you can use if you want a command-line way of generating your MFA authentication codes. While there are a number of programs to generate TOTP codes, perhaps the most widely available one is oathtool, part of OATH Toolkit.

There are a variety of tutorials on using oathtool to generate TOTP codes on the Internet, but the ones I read generally slid into gpg, and gpg is about where I nope out in any instructions. So here is the simple version:

oathtool -b --totp @private/asite/totp-seed

(If you want more familiar syntax, oathtool accepts '-' to mean to read from standard input, so you can redirect into it or use cat.)

Most websites give you the text form of their TOTP seed in base32, so we need to tell oathtool that. The totp-seed file should be unreadable by anyone but you, of course.

If we want somewhat more security we can encrypt the TOTP seed at rest and pipe it to oathtool:

magic-decrypt private/asite/totp-seed | oathtool -b --totp -

The 'magic-decrypt' bit is where common instructions drag in gpg and I tune out. If I had to do this today, I would use age, which can encrypt (and decrypt) using a symmetric key with no fuss or muss.

Some TOTP clients have a 'follow' mode where they will print out a new TOTP code when the clock advances enough to require it. I don't think oathtool can do this, but it can print out extra TOTP codes after the current one (with '--window').

And as a little side note, the oathtool in Ubuntu 20.04 appears to be non-functional for generating TOTP codes from base32 input, for at least the one website I tried. The version on Ubuntu 22.04 works. I don't know if this is a bug or some feature that the 20.04 oathtool doesn't have.

PS: Possibly there is a better command line tool for this that's packaged in Debian and Ubuntu, but oathtool is what I found in casual Internet searches. There are definitely other command line tools, eg totp-cli and totp.

Written on 01 October 2023.
« I have questions about MFA push notification fatigue
What we did when we couldn't gracefully roll over an OpenVPN TLS root certificate »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Sun Oct 1 23:12:30 2023
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.