Oathtool

06 OATH Options and Oathtool

The OATH standard has several options.

You need to know which OATH options the site you wish to log into uses in order to use OATH.

07 Options - TOTP versus HOTP

There are two different types of OATH one time passwords, HOTP and TOTP.

HOTP uses a counter. 

I won't go into more detail on HOTP as I haven't come across anyone using it.

TOTP uses the current time instead of a counter.

The time is fed into the OATH algorithm along with the shared secret to generate a new password on both ends of the connection.

All the instances of OATH that I am familiar with use TOTP.

08 TOTP Mode

Totp has different "modes".

These modes are hash encoding algorithms such as SHA1, SHA256, or SHA512.

The correct mode must be selected in order to log in using OATH with TOTP.

09 Encoding - Hex versus Base32

Both ends of the connection must be initialized with a shared secret or key which is required as part of the OATH algorithm.

This key could be encoded in one of two forms, either hexadecimal or base32.

Web sites often do not document which encoding method they are using.

If you cannot determine the encoding of the key by simply looking at it you may need to use trial and error during your first OATH log in attempts to see which type of key has been used.

10 Github and Pypi Options

Github and Pypi are two of the most prominent web sites using OATH.

Both use the same options, TOTP with SHA1 mode, and base32 encoding.

11 Using Oathtool

oathtool is a simple command line application which generates one time passwords for use with OATH.

It can be run in a terminal.

However, can also be turned into a simple GUI application using Zenity. Will discuss this in more detail later.

By default oathtool uses hotp and hex encoding.

To use totp and base32 encoding you must specify these on the command line.

To specify base32 encoding for use with for example Github, pass the "-b" or "--base32" argument on the command line.

To specify TOTP, pass the "--totp" argument on the command line.

By default, oathtool uses SHA1 with totp, so you don't need to specify that if you require SHA1.

If you need a different TOTP mode, you specify that as part of the TOTP argument separated by an "=" character. For example "--totp=SHA256".

12 Oathtool Example

Here is a simple example of using oathtool to create a one time password to use with Github or Pypi.

Open a terminal and type the following.

oathtool -b --totp SOMEBIGBASE32SECRETCODE

The one time password will be printed out in the terminal.

You can try this out without using a valid key so long as it is a valid base32 string.

When used with a valid key you then enter that one time password into Github, Pypi, or other web site where it asks for the one time password.

Note that I have not covered in the above how to store and retrieve the key securely, as that is too big of a topic to cover here. 

13 Zenity Example

Oathtool is a command line application, but if you are using Linux it is simple to convert it into a GUI application by using "Zenity".

Zenity is a simple to use package that creates GUI windows on the command line or in a shell script.

There are two steps to the proceess.

First create the OTP from the key by using oathtool and save it in a variable.

Next, call a Zenity "info" window with the OTP as part of the provided text.

You can now copy and paste the OTP from the window into your web browser.

To close the window, click on the "OK" button.

See the previous note on storing the key securely. 

hprcode=$(oathtool -b --totp SOMEBIGBASE32SECRETCODE)

zenity --info --width=150 --title="HPR 2FA" --text="<big>2FA code is:</big> \n\n $hprcode \n"

If you are using Gnome you can make the script launchable from the desktop by creading a ".desktop" file in the "Desktop" directory.