One Time Passwords

This document gives a few tips on using FreeOTP to generate one time passwords.

TOTP URI Format

  otpauth://TYPE/LABEL?PARAMETERS

See https://github.com/google/google-authenticator/wiki/Key-Uri-Format

Using oathtool to Generate TOTP Tokens

oathtool is a command line tool for handling one-time passwords. Some more info and shell scripts at www.cyberciti.biz. The project is hosted at https://www.nongnu.org/oath-toolkit/.

Available on MacPorts as oath-toolkit package.

Encrypt a key token with, E.g.:

$ echo -n "VVBYXXT3KIUT4IMCMGDTCCSTRZ3X6OTN" >my.key
$ gpg --encrypt my.key
$ shred -u my.key

Note that the above method is for demonstration purposes. It exposes the secret in the process stack visible to all other users on the system, and may also leave it in your command history. Use a text editor to create the my.key file instead.

Generate a one-time TOTP token for the current time with:

$ gpg --quiet --decrypt my.key.gpg | oathtool -b --totp -

or for a specific time:

$ gpg -q -d my.key.gpg | \
oathtool -b --totp --now="2025-06-08 15:21:30" -

Note: The --now parameter can be a relative term such as “1 minute ago”, “-1 minute”, “now”, “+30 seconds”. It is the same datestr as used by the --date parameter in the GNU date utility.

Generating a Random Base32 String

The following command will generate a random key which can be used to create TOTP tokens with oathtool:

$ LC_ALL=C tr -dc 'A-Z2-7' </dev/urandom | head -c 32; echo

See https://support.yubico.com/hc/en-us/articles/360015668699-Generating-Base32-string-examples

Manually Creating FreeOTP Entries

FreeOTP provides options to add a new URI either via a QR code or by entering values into a form.

Entering the details into FreeOTP manually from a URI can be confusing, as the input field names do not match the URI format clearly. Some examples may help decide which values to use. The first seems more widely accepted:

  1. otpauth://totp/ISSUER:USER_ID?secret=MY_SECRET&issuer=ISSUER

    Enter as

      Issuer: ISSUER
  ID:     USER_ID
  Secret: MY_SECRET
Example using [qrencode][libqrencode]:

  $ qrencode -o image.png otpauth://totp/ISSUER:USER_ID?secret=MY_SECRET&issuer=ISSUER

  1. otpauth://totp/MY_LABEL?secret=MY_SECRET

    Enter as

      Issuer:
  ID:     MY_LABEL
  Secret: MY_SECRET
Example using [qrencode][libqrencode]:

  $ qrencode -o image.png otpauth://totp/MY_LABEL?secret=MY_SECRET

The Issuer field should be optional, but FreeOTP on iOS (version 1.1) will not let you save it until something has been entered in all three fields. It will accept a single space character in the Issuer field. Additionally, you may need to click in the secret field before the save button is enabled. The value of the Issuer field doesn’t appear to make any difference to the generated codes.

See QRCodeTips on for information on tools for reading and creating QR Codes.

– Frank Dean - 21 Dec 2017

Related Topics: PasswordGeneration, QRCodeTips