OTPasswd - One-Time Password Authentication System
              --------------------------------------------------
                https://savannah.nongnu.org/projects/otpasswd
                        Updated: 08-Jan-10 (v0.5beta)

                                    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.3) but, of course, testing is still
required.  Think of this as 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 two primary components, a user 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.

The second 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 utility 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 utility 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 utility 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
utility 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.

Package Dependencies
--------------------
OTPasswd may be installed either through compilation from source, or
if available, from a pre-compiled binary package.  In the latter case,
OTPasswd operation will only depend on a small set of runtime dependencies.
In the former, additional packages are required to allow compilation.

A thorough description of dependencies is provided in the INSTALLATION GUIDE,
however for the purposes of a quick overview, a summary of dependencies
follows:

   Build Dependencies
      * CMake cross platform build system
      * PAM Pluggable Authentication Modules Library (-dev package)
      * GNU GMP Multi-Precision Library              (-dev package)

   Runtime Dependencies
      * Pluggable Authentication Modules Library
      * GNU GMP Multi-Precision Library



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):

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   Cirrus ~ % otpasswd -k
   *************************************************
   * This will irreversibly erase your key, making *
   *    all already printed passcards worthless!   *
   *************************************************

   Are you sure you want to continue? (yes/no): yes

   This is your previous configuration updated with command line options:
   show=on disabled=off alphabet=3 codelength=3 (salt=on)
   No label, no contact information.
   Static password is not set.
   You can either use it, or start with default one (modified by any --config options).
   Do you want to keep this configuration? (yes/no): yes

   Generating new salted key.

   Hint: Move your mouse, cause some disc activity (`find /` is good)
   or type on keyboard to make the progress faster.

   Gathering entropy...DONE

   *****************************************************
   * 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!                  *
   *****************************************************

   Cirrus                          [1]
       A   B   C   D   E   F   G   H
    1: 8kz Gv? 2zk xV: qjs DX9 WsS NN6
    2: 49L fbK hSr gb? w?5 @bL 3wW :3z
    3: xt2 Cfc TLF x:w 53J frn SB% vwg
    4: gr: :wk TZc =Ks xVJ 9Cv Vxs 2TF
    5: hN6 d%x @h! 6zc S#K hcL #FJ qkn
    6: P29 rcp 6rV v?k =x8 7T2 Jw% N2L
    7: m2w tH8 PR7 MbG !s8 %5Z g%7 +cL
    8: XRG x+H PB! @+! ::M F#x M4: c!8
    9: Sjj MRd cRz cJw Nn3 Sjj TMx LHt
   10: m+% T=4 Hmn ?F+ +8H 8xs k%# F8t

   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:

   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   Cirrus ~ % otpasswd --info
   User    = bla
   Key     = 0AD63608EBC1B4BF498EECF45C30B142AC766B4324291E598CE9090730BC21AE
   Counter = 7251201D2E66F68F821F6EEB00000000
   Current card        = 1
   Current code        = 1
   Latest printed card = 1
   Max card            = 53687090
   Max code            = 4294967200
   show=on disabled=off alphabet=3 codelength=3 (salt=on)
   No label, no contact information.
   Static password is not set.
   %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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>.



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 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/>.

                                     ###