Advanced Admin Guide

Introduction

This guide describes how the TRI-D Systems One-Time Password server software operates, to help you deploy and administer it. It assumes you have read and understand the architecture of our system.

In most cases, we do not point out the specific configuration file directives and settings required to choose any specific feature. This is because the configuration files are largely self-documenting once the concepts explained here are understood.

This document is written with the advanced security administrator in mind.

Time vs. Event

TRI-D offers both time- and event-based tokens.

Time-based tokens generate OTPs by using the current time as [one of] the inputs to the OTP algorithm. Soft tokens (winOTP and mobileOTP) use "absolute time" and hard tokens (keyfob or card) use "offset time".

For soft tokens, the device that runs the token software needs to have an accurate idea of the current time, relative to the server that otpd is running on.

For winOTP, this means that both desktop computers and the OTP server must sync to the same time source. For mobileOTP, this means that the OTP server must sync to a GPS or UTC time source (since cell phones sync to GPS time). Note that this is generally desirable, and even more so, practically an absolute requirement in any enterprise anyway. The skew between soft tokens and the OTP server can generally be about 32 seconds, whereas the skew between any two computers in an enterprise network can generally only tolerate a few milliseconds, if network filesystems are to operate correctly. So this time sync requirement presents no additional burden to deployment of a time-based token. Further discussion of time sync is beyond the scope of this documentation, however Professional and Enterprise Edition customers are free to contact us for further assistance.

Unlike soft tokens, hard tokens have no way to contact an external time source and so cannot maintain time sync with the OTP server. Therefore these tokens use "offset time", meaning they have an internal clock which runs at a different rate and has a different idea of the time of day than the OTP server. otpd is able to determine the clock offset when a user first logs in, and the relative drift rate as the token gets used over its lifetime.

Event-based tokens use an event count, based on the number of times the token has been used, instead of the time, as input to the OTP algorithm. Therefore this type of token does not need a clock. However, the OTP server does still need to sync with the token—it needs to know how many times the token has been used.

Time-based tokens (either type, absolute or offset time), have several advantages over event-based tokens:

• The user cannot pre-generate a list of OTPs, thus strengthening the assurance that the token is actually in the user's possession, and reducing the likelihood of token sharing.
• The user can play with the token all they want and it cannot get out of sync with the server, thus eliminating the need for administrative resets of the token.
• It is possible for users to be issued multiple tokens.

Event-based tokens have the advantage that they are cheaper, and have a longer lifetime.

User Database

The first thing to decide is where you will store user data (username, token type, secret key, and optional PIN). Also, you will have to decide how to secure the sensitive user data components (secret key and PIN).

The choices for where to keep the user database are in a flat file or in an LDAP directory.

The choices for protecting the sensitive user data are to encrypt them with a fixed key, or to encrypt the secret key with the user PIN. Or to just leave them in the clear.

The Community Edition has full support for decrypting data, but since it does not come with a provisioning tool you will have to write your own tool to encrypt data. (The method of encryption is easily seen in the source code; also feel free to contact us for guidance.) The Professional and Enterprise Editions make encryption support trivially easy to use.

Let's compare the two encryption methods briefly.

Encrypting the secret key and PIN with a (different) fixed key has the disadvantage that anyone with access to the encrypting key can decrypt the data. Typically the only people with access to the secret key (encrypted or not) are the same people that have access to the encrypting key, so this severely limits the effectivenss of this method.

Using PIN encryption eliminates this problem—with PIN encryption neither the PIN nor the token secret is available to any administrator. However, with PIN encryption, if the user forgets their PIN, it is not recoverable/resettable and the user must be issued a new token. Also, certain types of authentication are not possible when using PIN encryption. We will discuss this in more detail in later sections.

Files

The main advantage of using files is that optd will not depend on the directory being available. However there are three main disadvantages:

1. Users cannot change their PINs without administrator assistance, because changing the PIN requires privileged access to the OTP server (where the user database file exists).
2. When using time-based hard tokens, users must perform their first login within 15 minutes of activating the token. This is because the clock on the token does not start until it is activated, and the OTP server must have a limit on how far back in time to "scan" for the clock offset. This is really only a problem because most people will not read documentation before trying out the token.
3. The user database file must be backed up, and the security of the backup must be as good as the original.

Besides the LDAP availability concern, there is an advantage that there is no need to worry about LDAP access controls being correct.

The default file is /etc/otppasswd. It is a plain text file, and its format is documented in the otppasswd(5) manual page.

When using files, the entire file must use the same type of protection for the secret key and PIN. Using PIN encryption is a bit difficult; you will have to write your own specialized tool. Using fixed key encryption is mostly pointless; anyone that can read the user data can also read the config file, which contains the encryption key. The only reason to use fixed key encryption with the files user database is to prevent accidental disclosure of the token secrets and user PINs. We recommended simply keeping user data in cleartext when using the files backend.

LDAP

We recommend using the LDAP backend in all but the smallest deployments. Advantages of LDAP are:

• Users can change their PINs without administrator assistance.
• No time limit between hard token activation and first login.
• PIN encryption mode for user data can be used.
• When using fixed key encryption for user data, multiple keys can be used.
• Management of user data can be performed from any workstation (with files, user data must be managed directly on the OTP server).
• Additional backup of user data is not a concern; it is backed up with the rest of the LDAP data.

To use LDAP, add the otp.schema file included with otpd to your OpenLDAP schema directory (typically /etc/openldap/schema), and 'include' it in your OpenLDAP server configuration file (typically /etc/openldap/slapd.conf). Then configure otpd appropriately, based on how user info can be found in your directory.

Most of the LDAP fields do not require any special protection. When using encyrption for the key and PIN fields, these do not require protection, however we recommend it anyway. You should apply an ACI so that only authorized users (administrators and the OTP server) can access them.

If you are not running load balanced, highly available LDAP servers (shame on you), you can address the availability concern by making the OTP servers into LDAP slaves/replicas.

Provisioning

The Professional and Enterprise Editions of our software include the TRI-D Provisioning tool (tpt), used to program, provision and deprovision users. Community Edition users can still perform the provisioning and deprovisioning functions manually.

This section is written in general terms and is required reading for all software Editions. tpt-specific documentation is included with the Professional and Enterprise Edition software. First, a couple of definitions.

Hard Tokens

Programming is the process of setting the secret key as well as the operating mode of a hard token. When using LDAP, it also adds this info to the LDAP directory, in a special area known as the pool. This is done with 'tpt program'.

Provisioning is the process of assigning a token to a user, and is accomplished by migrating data from the pool to a user's DSE. This is done with 'tpt provision'.

These two steps can also be performed at the same time, thereby skipping the intermediate step of adding data to the LDAP pool. This is done with 'tpt assign'.

When programming a token, the token key should be considered to be available to the administrator doing the programming. Even if the token secret key is encrypted in LDAP, the administrator doing the programming will necessarily have access to tpt's configuration file, which must, of course, contain the encryption key. Even if special (and very difficult) measures are taken so that only the tpt program itself, and not the user, can read tpt.conf, the administrator must have physical access to the card programmer, and this will allow him to intercept the programming commands and have access to the keys.

Because large or even medium-size sites are likely to want lower level helpdesk or physical security staff to provision tokens, the programming and provisioning steps are split into two distinct steps so that staff doing the provisioning will never have access to the key material. This way, the high value step of programming tokens can be performed by high value employees, and the low value step of provisioning tokens can be performed by lower value or even transient employees without risk of key compromise. Unfortunately, this does still mean that high value employees will have to take on the rote work of programming tokens, but there is no avoiding that if key material is to be protected. Once programmed, tokens can be distributed to multiple, even global, locations for local provisioning.

For preprogrammed (non-programmable) tokens, while tokens aren't actually programmed by your staff, at some point the key material must be imported into your LDAP directory, and so the process is identical except that the programming step is replaced with the import step ('tpt import').

Soft Tokens

For soft tokens (winOTP and mobileOTP), there is no programming step per se, but a key must still be generated at the time the token is configured, and it is very difficult to prevent the person configuring the token from knowing the key. We highly recommend using the Self Provisioning System (sps), which can run on an unattended server and thus avoid this problem.

In addition, since keys must be transmitted to the user, there is the problem of protecting the key in transit. To address this issue, the key is encrypted using an "unlock code", which is simply another key used to encrypt the token key. The unlock code consists of a configurable number of decimal digits and a 2 digit checksum; the checksum is necessary to catch typos when entering the unlock code into the token.

The unlock code protects the token key perfectly, that is, even if intercepted, an attacker cannot determine the original unencrypted key, not even by brute force, because there is no way to tell if any given trial decryption was correct. At least not from the contents of the provisioning message itself.

But if an attacker can intercept the provisioning message, and can monitor any cleartext OTP login from that user, he can use the witnessed OTP to brute force the unlock code. For this reason, the unlock code must contain at least as much entropy as the key itself in order to protect it. All TRI-D tokens use 160-bit (20 byte) keys, which requires 26 decimal digits (28, with checksum) to protect.

If the channel over which the provisioning message is transmitted can be protected, then the unlock code can be dispensed with altogether, or at least made very short. So for winOTP, you would need full protection over the complete email path (i.e., both TLS protected SMTP and IMAP/MAPI). For mobileOTP, the SMS channel cannot be protected.

This brings up an interesting problem. For winOTP, when using sps, long unlock codes are not a problem, since the unlock code can simply be copied from the browser into winOTP. But there is no way to copy/paste into mobileOTP, and the SMS channel is insecure. Therefore, in order to protect the key, the user must manually enter a very long unlock code into their phone. Thankfully, this need only be done once per user.

If this (long unlock codes) becomes or is anticipated to be a problem, it may be "solved" by considering the threat model. In order to compromise a mobileOTP key, an attacker must witness the single provisioning message sent to a user, and then must witness a cleartext OTP login (even if you are strictly using secure VPN technologies, a keystroke logger is enough to accomplish this) by that specific user. So, this is not an opportunistic attack, but rather a targeted attack. In addition, it is "multimodal"; an attacker must compromise multiple technologies. An attacker that is motivated enough and that can actually pull this off is likely to have other, easier points of entry. For instance, tailgating into the building and plugging a device into your network.

Self Provisioning

In addition to tpt, the Professional and Enterprise Editions also include sps, the Self Provisioning System. It is a simple tool, just a web interface to tpt, however it provides powerful capabilities.

With sps, zero administrator/helpdesk assistance is required to provision tokens. Users simply go to an internal web page, enter either the serial number of their hard token, or their cell phone number or email address for soft tokens, and are ready to go.

Complete sps documentation is provided with the Professional and Enterprise Editions.

Encryption Modes

As noted above (in the User Database section), there are multiple encryption modes available to protect the sensitive user data, the key and the PIN. The different modes exist because they have different qualities; there is no single "best" mode. These were discussed above but we will review here as well.

First there is cleartext mode. This is recommended when using files as the user database, or with LDAP when absolute maximum performance is required. Please contact support@tri-dsystems.com if you are considering using this mode with LDAP, so that we can discuss the performance aspects in detail. If you are just thinking about this, and don't already know you have performance problems, you don't need it.

Then there is keyid mode, where the key and PIN are encrypted with a fixed key, referenced by a "keyid". With the files database, all entries must be encrypted with the same keyid. With LDAP, each entry is marked individually with the keyid used. This allows for key migration or for regional partitioning/compartmentalization.

Lastly, there is PIN mode, where the key is encrypted with the PIN. This allows for "perfect" encryption, where access to the user data itself does not provide enough information to launch an attack. A disadvantage of this mode is that if the user forgets his PIN, it is not recoverable and a new token must be issued.

Outside of provisioning, keyid mode largely exists to prevent accidental disclosure of the token key and PIN. Normally, the token key and PIN is either restricted to folks who can login directly to the OTP authentication server (when using files), or to the binddn or IP of the authentication server (when using LDAP, via ACI protection).

But with our 2-stage programming+provisioning method, keyid mode is also useful to protect key material from inspection by the provisioning staff (unlike the general population, the folks provisioning cards must necessarily have access to the key data in LDAP). In fact, while card data is in the "pool" of programmed but not-yet-provisioned cards, no PIN is associated with the card and so PIN mode cannot be used. However, if PIN mode is desirable, then users can be assigned an initial PIN which they must change on initial login (when using manual, i.e. administrator assisted, provisioning) or sps can set to use use PIN mode, which will automatically convert data from keyid mode if needed.

Depending on the authentication or VPN technology you use, you may not be able to use PIN mode encryption. If you use challenge/response authentication (e.g. as is required with Microsoft PPTP VPNs), neither the PIN nor the OTP are sent to otpd. Instead, an encrypted blob is sent along with the challenge value. otpd takes the challenge value and does its own encryption, using the PIN and OTP as the key, to obtain its own candidate blob. If the two blobs match, the user must have entered the correct PIN and OTP. This method of authentication has the advantage that the "password" is not transmitted to the authentication server, thus in theory preventing someone from monitoring the transmission to obtain any useful information, however it has the disadvantage that the authentication server must have access to the cleartext password (PIN+OTP in our case). So in order for PIN mode to work, otpd must know what the user's PIN is, and with PIN mode encryption, that information is not available.

When using cleartext authentication methods, otpd is able to determine which part of the passcode is the PIN, and use it to decrypt the key. Then the key can be used to determine if the OTP part of the passcode is correct.

Further Assistance

For any questions on topics not covered in this document, or for clarification, please contact support@tri-dsystems.com.