OTPasswd - One-Time Password Authentication System
              --------------------------------------------------
                https://savannah.nongnu.org/projects/otpasswd
                        Updated: 15-Sep-10 (v0.7beta)

                                    README



Contents
========
  0. Package Status
  1. Motivation
  2. Introduction
  3. Package Features
  4. Security Advisory
  5. Installation
  6. Demo (Screenshot!)
  7. Documentation
  8. Contact Information
  9. History
 10. Licensing



0. Package Status
=================
OTPasswd is under development.  In the ChangeLog there's a list of things
I'd like to implement before publishing the package as version 1.0.  Most
features currently work (as of v0.7) but, of course, testing is still
required.  Think of this as a beta software.

It is a goal of OTPasswd development to create a source package which can
readily be compiled on a variety of *nix platforms, including Linux, BSD,
Mac OSX, and Solaris.  In addition, it is hoped that pre-compiled binary
packages can be maintained for major Linux distributions, as well as a
Gentoo ebuild.

View the most recent version of this document on the web at:

   http://git.savannah.gnu.org/cgit/otpasswd.git/plain/README



1. Motivation
=============
FIXME: To be written.



2. Introduction
===============
A one-time password (OTP) is a password that is only valid for a single login
session or transaction (normally used along with a normal static password).
Using an OTP reduces the risks associated with logging into your system
from insecure (eg, key logged) workstations.

The OTPasswd package consists of three primary components, a user utility,
agent which performs operation on behalf of the utility, and a PAM module
(Pluggable Authentication Module).  The utility allows the management of a
user's interaction with the OTPasswd system.  Its primary functions are to
generate the user's cryptographic key, manage options affecting OTPasswd
behavior, and to print passcards with one-time passwords.  The user's OTPasswd
configuration is known as the user's "state", and can either be stored in the
user's home directory or in a system-wide database. User never interacts 
directly with the agent. Instead utility calls agent functions each time 
user runs utility. It's existance is solely due to security.

The third primary component of the OTPasswd system, the PAM module, enables
"PAM aware" applications, such as OpenSSH, to do OTP authentications using
the user's OTPasswd "state" information.

OTPasswd is written in C (C99) and implements an OTP system as described
by Steve Gibson's "Perfect Paper Passwords" specification.  An excellent
description may be found at: <https://www.grc.com/ppp.htm>.  While OTPasswd
is designed to be completely compliant with the PPPv3.1 specification,
it does optionally extend the specification by allowing the use of a
cryptographic "salt" to the passcode counter.  OTPasswd does not support
earlier versions of the PPP specification.



3. Package Features
===================
Current:
   * Use of Pluggable Authentication Module (PAM) allows great flexibility
   * Rijndael (AES) cipher is modern, robust, and efficient
   * User state information may be maintained in global DB, or in user home
   * Compatible with the well-documented PPP (Perfect Paper Passwords) standard
   * Interoperable with other PPP-compliant applications
   * Capable of enforcing system OTP security policy decisions
   * User-selectable passcode entry alphabet to suit language, or keyboard
   * High entropy passcodes for rapid entry, reducing Over-The-Shoulder attacks
   * Passcards may be generated in either plain ASCII or LaTeX
   * Secure locking of state files to resolve race conditions
   * Many user options: display entered passcodes, passcode length, etc.
   * Many sysadmin options: enforcement or overriding user options, etc.
   * Warnings issued when user passcard supply is running low
   * Support for cryptographic salt to increase attack resistance (optional)
   * Designed and written with emphasis on secure code
   * Out-of-band passcode transmission with customizable scripts (SMS, IM, etc)

Planned:
   * Wide variety of supported platforms (Linux, Unix, BSD, Solaris)
   * Comprehensive documentation
   * Pre-compiled binary packages for major distributions; Also, Gentoo ebuild
   * Flexible layout of printed passcards through customizable scripts
   * Flexible choice of DB backend, including flat file, MySQL & LDAP



4. Security Advisory
====================
It is very important that the user has a good understanding of the following
issues related to any system security software:

   A.  The intent and purpose of the design
   B.  The limitations of the implementation
   C.  The points of vulnerability
   D.  The general principles of operation

The user is encouraged to read the documentation provided in the <docs>
directory of this package.  In particular, the <docs/security> document
covers a number of security concerns related to this package.  The user
is also encouraged to read the information on the GRC website (above)
regarding PPP.

The user is also advised to take the following two warnings to heart:

   CAUTION #1.  OTPasswd is NOT designed to replace standard system
   passwords, rather, it is intended to provide a "second factor" to
   a "first factor" authentication system.  Do not use it as your only
   authentication system.  Really.

   CAUTION #2.  No OTP authentication system can protect you if you have not
   first authenticated the endpoint of your communication channel.  Prior
   to providing your password, it is essential to authenticate the host.
   Failure to do so exposes you to the risk of a Man-In-The-Middle attack.
   In other words: use SSH and validate the host key fingerprint!



5. Installation
===============
OTPasswd installation is covered in the INSTALLATION GUIDE, included with
this distribution in the INSTALL file.

A few of the more important issues related to OTPasswd installation are
worth noting, however.

Operational Mode
----------------
OTPasswd is able to run in two slightly different modes, which are
distinguished by the location of the stored user state configuration.
This is a deliberate and essential configuration choice that must be
made by the system administrator.  Each choice carries with it certain
consequences with respect to system security.

In the 'USER DB' mode, a user's configuration is stored in the user's
home directory.  Because of this, the OTPasswd agent does not need
escalated SUID privileges to access and modify the user's configuration.
As a consequence, however, the user's configuration may be changed by
the user at will.  This prevents OTPasswd from effectively enforcing
various security policies.  Among other things, it permits a user to
create a situation where one-time passwords (passcodes) are reused, which
could be interpreted as effectively defeating the entire point behind
OTP authentication.  It should be noted that if the system user-base is
trusted, competent, and conversant in IT security issues, this may not be
a relevant concern.  In any event, the USER DB mode effectively implies
that OTPasswd security is optional.

In the second operational mode, the 'GLOBAL DB' mode, every user's
configuration is stored in a single database under system control.
This operational mode may use a number of backend database interfaces,
such as a flat-file in the /etc filesystem hierarchy, an LDAP database, or a
MySQL database.  The user has no read/write access to the configuration data,
and hence the system is capable of enforcing OTPasswd security policies.
As an example, GLOBAL DB mode ensures that passcodes are never reused.
This mode of operation does require that the OTPasswd agent be installed
as SUID root, which may be viewed by some as being undesirable since this
may present a security exposure in its own right.  It should be stressed,
however, that the OTPasswd software was written in a manner observant of
secure coding practices, and while the agent is installed SUID root,
it merely uses these privileges to read its configuration files and then
it promptly drops the root privileges.  Or, put another way, the OTPasswd
agent only holds root privileges for a brief time during which it never
processes any user input.  The benefit of this approach is that the GLOBAL
DB mode allows the system administrator to choose whether OTPasswd security
is optional, or mandatory.

It is important to note that this is the first critical decision that
a system administrator must make in configuring OTPasswd.  No default
is provided for this choice, and OTPasswd will not operate until the
operational mode has been configured.


6. Demo (Screenshot!)
=====================
Everybody loves it, so here is an example of key generation, run by a user
who has previously generated a key, and has also set some optional flags
(3-character long passcodes, extended algorithm):

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   reactor ~ % otpasswd -c codelength=3 -c label=Home -k
   *********************************************************
   * This will irreversibly erase your current key, making *
   *    all already printed passcards worthless!           *
   *********************************************************
   
   Are you sure you want to continue? (yes/no): yes
   
   Your current set of flags:
   show=on disabled=off alphabet=1 code_length=3 (salt=on)
   Passcard label="Home", no contact information.
   
   
   HINT: To generate key we need to gather lots of random data.
   To make this process faster you can move your mouse or cause
   some network or disc activity
   Key generated successfully.
   
   *****************************************************
   * Print following passcard or at least make a note  *
   * with a few first passcodes so you won't loose     *
   * ability to log into your system!                  *
   *****************************************************
   
   Home                            [1]
       A   B   C   D   E   F   G   H  
    1: 2dM =78 o6! f8A uHF uHP Y%P :e+
    2: bq@ ff6 wSu ?LY TZf MB% coe MKR
    3: Xt8 R%r thT kav pmH zLo =mD V%?
    4: XhN %jD 8Fd dfs 56t qGR pDr %uy
    5: +y! 9s? 7?r MCC +By U=9 2A= ECC
    6: e8F Ejk n#i i#w e6R :Xm HhP XbK
    7: DPJ #3s D!p qTD d#x khz CF8 Jt%
    8: bLK MV: %Jr Vp4 rF@ Fby 8!! VTV
    9: cvJ 7z: kwR A=3 RmC tMh NT? u6o
   10: 8Fg 6qa JRD u4P =F@ #Y2 SsR SPA
   
   Are you ready to start using this one-time passwords? (yes/no): yes
   
   Key stored! One-time passwords enabled for this account.

To display the current user configuration:

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   * Your current state:
   Current card        = 1
   Current code        = 0
   Latest printed card = 1
   Max card            = 53687090
   Max code            = 4294967200
   All auth failures   = 0
   Recent failures     = 0
   
   * Your current flags:
   show=on disabled=off alphabet=1 code_length=3 (salt=on)
   Passcard label="Home", no contact information.
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Example usage:

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   user@host $ ssh user@cirrus
   Password: <user unix password>
   Passcode G6 [1]: Jw%

   user@cirrus $
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



7. Documentation
================
In addition to this README, various other documents are included with the
source distribution of this package.  Depending upon the OTPasswd package
that was installed, these documents may be available in the /usr/share
hierarchy of your system.

OTPasswd also is documented by a series of on-line man pages:

   otpasswd(7)      - OTPasswd Principles of Operation
   otpasswd(1)      - OTP Management Utility
   pam_otpasswd(8)  - PAM Module
   otpasswd.conf(5) - System Configuration File
   otpasswd(5)      - User State Information File
   otshadow(5)      - System User State Information File

An excellent description of PPPv3 is available on the Gibson Research
Corporation website at <https://www.grc.com/ppp.htm>.

The evolving design of Perfect Paper Passwords was discussed extensively by
Steve Gibson and Leo LaPorte on the TWiT Security Now! netcast in episodes
#113, #115, and #117 during the fall of 2007.

The GRC grc.thinktank newsgroup was the site of a great deal of activity
regarding the design and development of Perfect Paper Passwords during
this same time period.  Quite a number of developers posted articles,
as did Steve Gibson, himself.  More information regarding GRC newsgroups
is available at <http://www.grc.com/discussions.htm>.  To view the
grc.thinktank newsgroup itself, point your favorite NNTP newsreader at
<news://news.grc.com/grc.thinktank>.

Most of the documentation we owe to Hannes Beinert who has devoted plenty
of his time to make it look good.

8. Contact Information
======================
You may contact the author with questions, support, praise or curses at
<mailto:bla@thera.be>.  Any feedback will be welcomed (even faint praise).
And no, I don't get a lot of feedback, so don't think "nah, I won't write
anything since he's probably pissed at us anyway".



9. History
==========
The creation of this program was inspired by the ppp-pam project
(http://code.google.com/p/ppp-pam/).  The idea is basically the same.
I started development by contributing to ppp-pam, but there were plenty of
things to fix, and when the author didn't respond (during first month) I
just decided I'd be better off rewriting everything from scratch.  The two
projects share some of my code, like locking functions, but nothing more.
It would be reasonable to think of OTPasswd as a remote fork of ppp-pam.



10. Licensing
=============
This README file, the examples and the source code of the OTPasswd
program are all licensed under GNU General Public License version 3.
The license should be included with the project inside LICENSE file.
Copyright notice follows:

Copyright (C) 2009, 2010 by Tomasz bla Fortuna <bla@thera.be>

This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with OTPasswd.  If not, see <http://www.gnu.org/licenses/>.

                                     ###