otpcli - One Time Password Command Line Interface

The otpcli utility provides a command line interface to generate one time hash-based or time-based passwords using the techniques specified in [RFC 4226] and [RFC 6238].

This suffices to provide an "Authentication App" service using solely the otpcli command line utility.

Limitations

The otpcli utility is completely standalone with no dependencies (other than a POSIX make and C99 compiler to build it).

It does NOT include a QR code decoder!

Using otpcli

If the service you are attempting to use otpcli with as an "Authentication App" provides only a QR code to set up your "Authentication App", then you will need a separate QR code decoder to decode that QR code into the otpauth: URI that contains the shared secret you will need in order to use otpcli.

In other words, if all you have to set up your "Authentication App" is a QR code like this:

It must first be decoded using a QR code decoding helper program. In this case it decodes to this:

otpauth://totp/ACME%20Co:bob@otp.example?secret=JBSWY3DPWIZR4IFU&issuer=ACME%20Co

Details regarding the otpauth: URI format can be found via reference [3] of https://www.iana.org/assignments/uri-schemes/prov/otpauth.

In almost every case, only the value of the secret parameter is actually needed. (Some enlightened services provide a link next to the QR code image that allows the Base 32 shared secret to be copied without needing to use a QR code decoder.)

In the unlikely event that you have a URI that starts with otpauth://hotp/ instead of otpauth://totp/ then you will also need the value of the counter parameter (which can only be used with hotp URIs) and it must be provided to otpcli using the -c option.

(See the output of otpcli -hh for a complete list of all available otpcli options.) The default values of sha1, 30 second period and 6 digits mean that in almost every case, only the shared secret needs to be supplied.

The shared secret from an otpauth: URI secret parameter is always supplied in Base 32 (see [RFC 3548]) and in the above example, the Base 32 shared secret is JBSWY3DPWIZR4IFU.

To use otpcli with this shared secret, this is the command (-3 indicates that the shared secret is being provided in Base 32):

otpcli -3 JBSWY3DPWIZR4IFU

It will output something like this:

187877 23s

The 187877 part is the 6-digit pass code to use and it is valid for the next 23 seconds. If the -i option is added like so:

otpcli -i -3 JBSWY3DPWIZR4IFU

Then otpcli will continually update the time remaining and update the pass code to the next one once the current pass code has expired (the -i interactive mode can be exited by simply pressing <return> or by pressing <Ctrl-C>).

Protecting Your Secrets

Specifying your shared secret on the command line can expose it via a list of running processes. In other words, not the best idea.

However, otpcli can read the shared secret from a file by simply prepending an @ sign to the file name.

Suppose that we want to save our shared secrets in a .otpcli directory in our "$HOME" directory and prevent any other users from being able to read the files in that directory.

We can do that like so:

mkdir -p "$HOME/.otpcli"    # create directory if it does not exist
chmod 0700 "$HOME/.otpcli"  # make sure only we can read and search it

Now we add our above shared secret to the file "acme" in the new directory:

echo JBSWY3DPWIZR4IFU > "$HOME/.otpcli/acme"
chmod 0600 "$HOME/.otpcli/acme"  # make sure only we can read it

Of course there's the shared secret on the command line again -- using a file editor to save the shared secret in the file instead will avoid that. (Note that the otpcli utility ignores whitespace in the file when reading a Base 32 shared secret.)

To use otpcli with the "acme" shared secret file we just created, we can do this:

otpcli -3 "@$HOME/.otpcli/acme"

Or using the -i interactive mode like so:

otpcli -i -3 "@$HOME/.otpcli/acme"

For scripting purposes, using a file name of - (e.g. -3 @-) will cause the Base 32 shared secret to be read from standard input.

Building otpcli

To build otpcli a POSIX make utility and a C99 compiler are required.

That's it. Just type make in the top-level directory and the otpcli utility will be built. It is completely standalone.

(If for some reason your C99 compiler is not available as cc then use make CC=c99 instead where c99 is the name of your C99 compiler.)

It's a good idea to test otpcli before using it and to do that type make test in the top-level directory which will run a few hashing and otpcli tests to make sure they're producing the expected output. (For anyone automating the tests, make test will fail with a non-zero exit code if any of the tests fail.)

License

The license can be found in the top-level LICENSE.txt file -- it is the three clause BSD license. Note that the functions providing the sha1, sha256 and sha512 functionality are from the LibTomCrypt library and have an even more flexible license which can be found in the lt/lt-LICENSE.txt file.