This README file is from the original project coming off TRI-D Systems. This OTPD is now forked from the original code, you can find all the details on the website http://otpd.googlecode.com.

Copyright 2009-2010 Giuseppe Paterno' (gpaterno@gpaterno.com)

0. INTRODUCTION

   Thank you for using otpd. The latest version can always be found at http://www.tri-dsystems.com/

   Please see the file README.LICENSE for licensing terms.

   otpd is part of a suite of software for authenticating users with handheld OTP tokens. There are five components:

   a. An authentication server. This is provided by you. Examples are FreeRADIUS, unix daemons that use PAM, a krb5 KDC, etc. b. A plugin for your auth server, that talks to otpd. You can download plugins from the TRI-D Systems web site, or write your own. Your authentication server software vendor might also supply plugins for otpd.

   • c. This software, otpd, which does the actual OTP validation. d. A global state manager, gsmd, used in multi-server deployments to coordinate and guarantee globally consistent state. e. An optional LDAP directory server.

   Other vendors' OTP authentication software rolls all of the above into a single piece of software. TRI-D Systems has decided to break it into component pieces to allow for higher integration, higher scalability, and higher security assurance.

   • Integration: By tying directly into the authentication servers you already use, we work with whatever access methods you already have in place. Auditing is also through your existing servers. And since your IT staff already knows how to manage your existing servers, additional support costs are minimized.

   • Scalability: This is acheived by separating the state manager and otpd functions. In the TRI-D Systems design, otpd runs on the same machine as the authentication server, but the state manager can run elsewhere. The authentication server and otpd have to do most of the work of authenticating a user, and can operate standalone, i.e. without knowledge of other auth servers or otpds. The state associated with OTP, however, is a very lightweight piece, and it must be globally consistent. Every otpd has to see the same state in order to prevent replay attacks. By making the lightweight state manager a separate component, the system as a whole scales better. Our competitors do the heavy lifting of OTP verification and state management in the same server, thus decreasing their scalability relative to ours.

   • Assurance: The component model means that the software we provide is small, and of consistent high quality. It also allows us to open source most of the code, since restricted source components can be isolated. We believe there is a fundamental problem with today's OTP vendors: customers must place blind trust in the system component that provides a trust service to the rest of the system! (And it's not just the software; some vendors will not disclose how their token works even in principle, not even under NDA. How can one trust such products?) All the core parts of our software are open source, and all other parts are source-available.

   In addition to providing these benefits, it all comes at a lower cost than the competition. In fact, the software is completely free (both free as in beer and free as in freedom) if you don't need or want any of the optional "enterprise" features.

1. INSTALLATION

   otpd uses the standard CMMI (configure, make, make install) process. Run './configure --help' for brief information on otpd-specific options.

   Post-install, you'll need to create the otpd socket directory, /var/run/otpd by default, which should have permissions such that your authentication server (via a plugin) can access it. Any process that can access this directory can ask otpd to verify an OTP! This directory is not created by the install process because on newer Solaris /var/run is on tmpfs; the directory will not survive a reboot.

   You'll also need to create /etc/otppasswd and make sure it is only readable by the owner (u+r or u+w). otpd verifies the file permissions at startup.

   Lastly, you'll need to create the /etc/otpstate directory, where per-user token [transient] state information is stored.

2. TESTING

   A test program, otpauth, is provided to assist with testing of otpd without requiring any additional authentication infrastructure. It also serves as a [trivial] example of how plugins communicate with otpd.

3. SUPPORTED TOKENS

   Of course, otpd fully supports all TRI-D tokens.

   Also, CRYPTOCard tokens are fully supported, however no support is available for token programming (so you can program known keys) or key extraction from the CRYPTOCard database (so you can extract already generated keys).

   Also, support is available for a generic event-synchronous HOTP token, and a generic challenge/response X9.9 token. The generic X9.9 token should work with any vendor's X9.9 challenge/response token, with the same caveat as for CRYPTOCard: you need to have knowledge of the token's key.

4. TOKEN OPERATION

   In the very old days, the server would present a challenge to the user, which the user would then enter into their token, and give the server the response. We call this async mode. This is "klunky" by modern standards of usability, and for X9.9 tokens is actually unsafe given that DES is weak (see section 3).

   Luckily, all tokens available today support a synchronous mode which lets the user skip the part where they enter the challenge. In this mode, the token and the server generate a "next challenge" which is derived from an event and/or time counter and is implicit. Besides offering better security, this mode also has the advantage of giving a much better user experience.

   For some tokens, the token can display the synchronous challenge. The idea here is that the server would still present a challenge to the user, but the user wouldn't have to enter it--they'd just have to verify it matches. Then they can safely just press some function key to obtain the response. From a security perspective, this is no better than pure async mode, since an attacker can still observe the plaintext/ciphertext pair.

   So when operating in this mixed async-sync mode, instead of presenting the synchronous challenge, the server ALWAYS displays a random challenge. Instead of verifying that the challenge matches the token display, the user should just skip past the token challenge display to obtain the response. This might be confusing; you will need to train users. Even with training, they will forget. Be warned! This mixed mode is useless and stupid. If you can disable token support for this, do so.

   For other tokens, the token does not display the synchronous challenge--only the response is displayed. This is a bit easier on the user; they won't be confused as to which number to enter for the response. I can't recommend this mode highly enough. With tokens like this, you should configure the server to likewise not present a challenge (this is the default). This appears to the user to be close to a normal password authentication.

   It's worth repeating that async mode is vastly inferior to either sync mode, and the mixed async-sync mode is vastly inferior to the pure sync mode. In addition to the shielding of the plaintext, and ease of use, another advantage of sync mode is that it supports authentication methods where a challenge cannot be presented to the user, e.g. PPTP without EAP.

   In sync mode, there are two ways to generate the implied challenge; either event or time based. "Events" are token operations--each time the token is activated an event counter advances.

   Event synchronous tokens have the problem that if users play with the token as a toy (say, to generate winning lottery numbers), the server has no way to know this and so it has a different idea of the counter value. Since there are typically only 1-10 million passcodes (6-7 digit decimal display), the server cannot simply test "many" passcodes in an attempt to discover the event counter value, because a guessing attack is trivial with such a small response space. Our solution for this is to require 2 consecutive passcodes after a limited number of failed attempts. (See otp.conf.)

   Event synchronous tokens are also more susceptible to sharing. Users can give out their passcodes for use at any time in the future.

   Also, a not-uncommon practice with event synchronous tokens is to generate a list of passcodes and carry that list around, instead of the token. (Generally because the tokens are physically inconvenient to carry and use.)

   Time synchronous tokens solve the event sync problem quite nicely by eliminating the user from the equation. As PEBKAC is generally the worst kind of problem, and the most difficult to solve, this is clearly better than event synchronous.

   But they introduce a new problem, that the timer interval (normally one minute) limits login rate. System and network administrators are especially hit by this one, but even "normal" users will complain about this.

   TRI-D tokens are time+event synchronous; for each time interval we produce multiple event-based passcodes.

5. STRONG WARNING SECTION

   ANSI X9.9 has been withdrawn as a standard, due to the weakness of DES. An attacker can learn the token's secret by observing two challenge/response pairs. See ANSI document X9 TG-24-1999, http://www.x9.org/docs/TG24_1999.pdf.

   For X9.9 tokens, the obvious fix is to not issue a challenge; the attacker will not have access to the plaintext. This is possible since all commercially available X9.9 tokens support a synchronous mode (the last holdout was the PassGo/Axent Defender Handheld, a re-re-re-remake of the Digital Pathways SNK/4, and which finally died ca. 2005).

   However, almost all X9.9 tokens support challenge/response (what we call asynchronous) mode, required to resync the token if the event sync is lost, in addition to synchronous mode.

   To protect against key compromise, all TRI-D supplied plugins disable async mode by default. Additionally, the default site transform (see section 4, below) in otpd effectively disables async mode, even if enabled in a plugin.

   In practice, async mode authentication is a poor user experience and should be rare.

   TRI-D tokens use HOTP.

6. SITE-SPECIFIC CHALLENGE TRANSFORM

   Since the normal mode of operation will be sync mode, we really only have async mode support for "last resort" user resync of the event counter. (For "normal" resync see the rwindow description in otp.conf.)

   Note that only some tokens support "user" sync/resync. For others, admin intervention is required for resync.

   Since pure challenge/response with X9.9 is unsafe, we came up with the concept of the "site-specific challenge transform". For the user, this means that instead of entering the challenge as presented to them, they enter something /based on/ the challenge. For example, a simple transform would be to enter the challenge backwards; if the server presents "123456" the user enters "654321". This has the effect that an observer does not have access to the plaintext.

   This is security through obscurity, and is not really "safe", but for an outsider it may present at least some barrier. Even though it presents no advantage in the face of a /determined/ attacker, we recommend using it. It may stop a more opportunistic attacker and isn't difficult to use.

   otpd logs each time a user authenticates via async mode, so we recommend a log scanner which alerts you to this. Tokens should be reprogrammed when users authenticate via async mode.

   site.c implements the site-specific challenge transform. The default transform is to append the first two characters of the username to the challenge. This effectively disables async mode; the user will generally not be able to enter this into their token.

7. STATE

   Synchronous (implied challenge) OTP authentication requires that all authentication servers have a consistent view of token state, to avoid replay attacks. While this can be simply achieved by having only a single OTP authentication server (which other servers could proxy to via, say, RADIUS), this creates a single point of failure, which is generally unacceptable in today's critical computing environments. Additionally, in very large environments, a single server may not be able to handle the load.

   TRI-D Systems addresses this with a 2-part system: local state management integrated into otpd, and a global state management daemon (gsmd), with which otpd communicates. For single server deployments, gsmd is not required.

8. GLOBAL STATE MANAGEMENT DAEMON (gsmd)

   gsmd does ... global state management. It ensures that all authentication servers see the same view of state at all times, by being the single canonical source of state data.

9. STATE FORMAT

   There is one state file per user, with the same name as the user. The default location for state files is in /etc/otpstate. For most filesystems, this probably doesn't scale well, beyond a few ten thousands of users.

   The format is: ver:user:chal:csd:rd:failcount:authtime:mincardtime: for example (note some fields can be empty): 5:bob:12345678:::0:0:0:

   Note that the trailing colon is required.

     ver: 5
    user: this is a sanity check field (matches filename)
    chal: the previous synchronous challenge (for event synchronous modes)
     csd: card-specific data
      rd: rwindow (softfail) data

   failcount: 0 if the last auth was successful, number of consecutive failures if unsucessful authtime: the last time the user authenticated (success or failure) mincardtime: the last time (card clock) the user authenticated successfully

   The challenge and the csd fields comprise the state proper. The other fields are used for password guessing prevention, user resync (for event synchronous modes), and null state initialization.

   If the state file does not exist, the action taken depends on the token.

   For TRI-D, the state will be initialized by the module itself. DO NOT create any initial state data yourself. (We call this condition null state.) For the first authentication, users must give two consecutive passcodes.

   For CRYPTOCard, the user must authenticate asynchronously to initalize the state. If your CRYPTOCard tokens aren't setup for async auth, or if you disallow it in the server config, then you'll (obviously) need to initialize the state manually when you issue tokens. Just create a state file with a blank challenge field.

   To reset locked-out (in hardfail, or too far out of event sync for rwindow mode to work) CRYPTOCard users manually, set the failcount field to 0. The challenge field may also need to be reset if the user is too far out of sync. Note that you must lock the state file before changing it! A utility will be provided for this in the future.

   The same notes (as for CRYPTOCard) apply for the generic hotp and x9.9 token support.