Introducing the OATH Toolkit

Posted on by

I am happy to announce a project that I have been working quietly on for about a year: the OATH Toolkit. OATH stands for Open AuTHentication and is an organization that specify standards around authentication. That is a pretty broad focus, but practically it has translated into work on specifying standards around deploying and using electronic token based user authentication such as the YubiKey.

YubiKey

OATH’s most visible specification has been the HOTP algorithm which is a way to generate event-based one-time passwords from a shared secret using HMAC-SHA1. HOTP has been published through the IETF as RFC 4226. Built on top of HOTP is the time-based variant called TOTP, which requires a clock in the token. OATH do some other work too, like specifying a data format for transferring the token configuration data (e.g., serial number and shared secret) called PSKC.

The aim of my project OATH Toolkit is to provide an implementation of various OATH related technologies. I’m intentionally leaving it open ended because you never know what they may specify that I find interesting. However, the primary goal has been to focus on HOTP and TOTP. Throughout 2010, the project was called HOTP Toolkit but that name made it difficult to support TOTP in a non-confusing way. During the last month, after discussion with Daniel Pocock on Dynalogin which is a potential consumer of my package, I took the time to create a fork of the HOTP Toolkit and the OATH Toolkit was born.

Now what does the OATH Toolkit actually do? Primarily it provides a library called liboath that implements HOTP and TOTP. Liboath is a relatively small library, and my goal is to keep it well documented and of high quality. There is GTK-DOC generated API documentation. Of course there is a command line tool to go with it, called oathtool which makes working with HOTP/TOTP from the command line easier. It can generate and validate one-time passwords. Let’s say you want to generate the first four OTP based on the dummy key 1234.

jas@latte:~$ oathtool -w4 1234
376439
299783
041392
819202
158134
jas@latte:~$

By default the tool is using HOTP, but you can switch it into TOTP mode with the –totp parameter. The output OTP will now depend on the current time on your machine, unless you specify the time manually using the –now parameter.

jas@latte:~$ oathtool –now=”2011-01-20 15:46 UTC” –totp 1234
527971
jas@latte:~$

The tool can do more, check the oathtool man page for all the details.

The final component of the OATH Toolkit is a PAM module pam_oath. With it, you can login to your machine using an OTP and optionally a password. Right now the user and password management is simplistic, but that should improve over time. To setup single-factor authentication for su you would create a file containing the user information and HOTP key as /etc/users.oath like this:

HOTP root – 1234

Then configure PAM to use the pam_oath module like this in /etc/pam.d/su:

auth requisite pam_oath.so debug usersfile=/etc/users.oath window=20

The user file will be rewritten every time you su to hold the current state. There is a README for the PAM-module with more documentation.

That’s it for an intro! From the OATH Toolkit webpage we link to binary packages for Debian and Ubuntu so please try the OATH Toolkit yourself and provide feedback to the oath-toolkit-help mailing list.

20 Replies to “Introducing the OATH Toolkit”

  1. I’m a long-time user of libpam-opie. Can you compare oauth to it? I only briefly look ed at the RFC but came up with something like

    Pros:
    + oauth passwords are a lot shorter to type than opie passwords
    + passwords change based on time

    Cons:
    – passwords change based on time (I can’t carry a list of passwords with me?)
    – server needs to know the secret? How should I deploy this with 25 different servers?

    If I use my laptop or PDA as a “token” is there some way to protect the secret at least so that a bug in a web browser or PDF reader alone won’t be able to steal it? Buying
    a separate physical token is not nice especially if I need multiple tokens to use multiple different servers.

  2. First, OATH is different from OAuth — unfortunately highly confusing acronyms.

    HOTP is event-based and TOTP is time-based. Only TOTP changes based on time, HOTP acts as a counter. HOTP is more common than TOTP out there.

    One advantage with OATH is that you are more likely to be able to buy physical tokens that implement the algorithm. I must admit that I’m not familiar with the OPIE algorithm, but I haven’t seen such tokens around.

    The way to use OATH with multiple servers is to use a client-server model and validate the OTPs in one central place. For example, you can use FreeRadius with PAM-OATH as a backend and then use PAM-RADIUS on the clients. I haven’t tried this, but that is a better general approach to go about verifying OTPs. I have plans to add client+server to OATH Toolkit so that it is easy to set this up.

    HOTP/TOTP is based on symmetric encryption, so you really need to store the secret securely. On a laptop, maybe the client could be run as a different user to avoid having a web browser bug affect the security of the OATH secret. A physical token will always provide better security, and by using a central server you only need one physical token for all services connected to that central server.

    Hope this helps!

    /Simon

  4. This is awesome.

    oathtool indeed returns the digits on my totp token.

    One question, does the pam-module support totp-tokens? If so, where do I set the time-step of the token in the configuration of the pam module?

    Cheers,
    —
    Rien

  5. Oh sorry, I just noticed that support for totp tokens was added to the api and the tool, but not yet to the pam module. Do you have any ideas when you will have the time to implement this? (If you want, I’d be happy to spend some time and contribute it myself?)

    Cheers,
    —
    Rien

    • For reference — support for TOTP in the PAM module was added in version 1.10.0 released on 2011-05-24.

  6. I think OATH require a secert key stored on server. OPIE only use the secert key to generate pwd list.and store the last password.User input the N-1 password, server check if hash(N-1 password) == stored password then success. and store user inputed password for next authentication.

  7. Thanks Simon:

    BTW – How do we generate PSKC file? Is there a tool we can use.

    I have seed files with the shared secret etc but wanted to wrap it into PSKC.

    Cheers
    M

  8. Tried to build on Centos 5.6. Configuration stage fails:

    ]$ make
    test -f configure || autoreconf –force –install
    aclocal:configure.ac:24: warning: macro `AM_SILENT_RULES’ not found in library
    aclocal:configure.ac:25: warning: macro `AM_SILENT_RULES’ not found in library
    Putting files in AC_CONFIG_AUX_DIR, `build-aux’.
    aclocal:configure.ac:25: warning: macro `AM_SILENT_RULES’ not found in library
    configure.ac:25: error: possibly undefined macro: AM_SILENT_RULES
    If this token and others are legitimate, please use m4_pattern_allow.
    See the Autoconf documentation.
    autoreconf: /usr/bin/autoconf failed with exit status: 1
    make: *** [buildit] Error 1

  9. Philip: Your automake is too old, it doesn’t have the AM_SILENT_RULES. Try a tarball instead. I have fixed configure.ac to make the automake 1.11 requirement explicit, thanks!

  10. M: There is no PSKC support in OATH Toolkit. Yet. I have something cooking here, but it is a while until it can be pushed into the project. If you want to help out, I’m interested…

    /Simon

  11. I am interested in using the OATH toolkit with our C/C++ front end. However we have a Java backend Server which we cannot put the toolkit on. Does anyone know of a Java equivalent which could be used on the Server Side to read the token generated from this toolkit? I guess if I had to I could review the C code and try to write a Java port for the backend. But I thought I might ask before attempting to re-invent the wheel if this same functionality already exists somewhere else, especially if it is open source. If not how difficult would you guesstimate the Java port to be for someone proficient with both languages?

    Thanks for any guidance you can provide. Derek

    • hi derek,
      did u get any reference for c++ client side for OATH algorithm. it will be great if you can share it. i am also looking for the same.
      regards,

      • Vikram, oath-toolkit supports C and C++ for both client and server side.

  12. Pingback: Using OATH Toolkit with Dropbox « Simon Josefsson's blog

  13. Derek: There is sample java code in the RFCs. If you or anyone wants to contribute a Java API for dealing with HOTP/TOTP to the OATH Toolkit project, that would be great!

  14. Pingback: Gooze token OTP(OneTimePassword) c200 をPAM認証に使ってみる | 瀬戸内農業ブログ

  15. Pingback: One-Time-Passwords using oathtool on Ubuntu 14.04(+) | ramblings

  16. What about support for OCRA (RFC 6287)? That is basically HOTP authentication using challenge/response tokens (plus some optional stuff) instead of the counter. Any suggestions for an implementation library, or know if this is in the stars to be added? Thanks.