Domino on Linux/Unix, Troubleshooting, Best Practices, Tips and more ...


Daniel Nashed


Adding TOTP to your own application

Daniel Nashed  15 April 2024 08:32:07

The oathtool is the standard tool on Linux. It comes as a command-line tool or a dynamic and static link lib to be used in your own applications.

You can statically link the code into your application and generate TOTP codes and also validate them.

The homepage contains information about the command line tool "oathtool" and also the lib "liboath".

Example how to use it on command-line.

The example used the base32 encoded secret for "test".

oathtool --totp -b  ORSXG5AK

Key URI Format

When importing TOTP secrets into a TOTP client it is very conventient to use a QR code.

Some clients don't even let you specify parameters like signing algorithm manually.

There is a URI format documented here:

To create a QR code you can use the qrencode Linux tool, which can generate an ASCII graphics QR code.

Example code to generate a QR code for TOTP setup

echo "otpauth://totp/$(echo test | base32)&issuer=NashCom&algorithm=SHA1&digits=6&period=30" | qrencode -tANSI256 -o -

Image:Adding TOTP to your own application

Example C code

Without error checking the C code to generate a TOTP code drills down to this:


oath_base32_decode (SecretB32, strlen (SecretB32), &pSecret, &len);

oath_totp_generate2 (pSecret, len, now, OATH_TOTP_DEFAULT_TIME_STEP_SIZE, OATH_TOTP_DEFAULT_START_TIME , 6, flags, szOTP);


It took me a moment to bring all those pieces together.

Specially on the C code side the important part is to that you want the Base32 encoded secret to be stored and use the conversion routine to convert it back as an imput.

Don't try to store the decoded string and pass it manually.


Now you have all your pieces to generate and verify TOTP digits either on command line or in your own application.

For security reasons I would not invoke the command-line tool from an application and instead statically link the lib into your application as show in my simple example.

My first use case will be my own sudo su - implementation to use TOTP to switch to root instead of using a password.

The tricky part will be now to store the secret in a way, that nobody can read it. But that's a different story.



    • [HCL Domino]
    • [Domino on Linux]
    • [Nash!Com]
    • [Daniel Nashed]