OTPasswd - One-Time Password Authentication System
              --------------------------------------------------
                         http://otpasswd.thera.be
                        Updated: 26-Oct-2013 (v0.8)

                                    README


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


1. 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.8) 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
   https://github.com/blaa/OTPasswd/blob/master/README


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

Documentation Index:
  README            - Generic system information
  INSTALL           - Source installation hints 
  Project Webpage   - http://otpasswd.thera.be
  README.Debian     - Things you need to know after Debian installation.

OTPasswd is documented by a following man pages:
  otpasswd(1)       - OTP Management Utility
  pam_otpasswd(8)   - PAM Module
  otpasswd(5)       - 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.


3. Introduction 
=============== 

A one-time password (OTP) is a password that is only valid for a
single login session or transaction. It is normally used along with a
normal password to create a two-factor authentication using something
you have (mobile or passcard) and something you know (a 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 (otpasswd + agent_otp) 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_otp. 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.

When SSH uses certificates for authentication it bypasses the whole
PAM stack. That gives user a great opportunity - one can configure key
authentication from all trusted workstations and get asked one-time
passwords only when logging in from external, untrusted machines.

OTPasswd is written in C (C99) and implements an OTP system as
described by Steve Gibson's "Perfect Paper Passwords" specification
<https://www.grc.com/ppp.htm> version 3.1. In a nutshell one-time
passwords are generated using AES cipher in a counter mode.


4. Main package features
========================
Main features:
   * Use of Pluggable Authentication Module (PAM) allows great flexibility
   * Modern set of crypto algorithms: Rijndael (AES) and SHA-2.
   * Compatible with the well-documented PPP (Perfect Paper Passwords)
   * Highly customizable:
    - user-selectable alphabets,
    - passcode lengths
    - passcard labels, OOB contact
    - key salting on/off
   * Warnings issued when user passcard supply is running low
   * Passcards may be generated in either plain ASCII or LaTeX
   * Out-of-band transmission of codes using external script (Email, SMS)
   * Support for cryptographic salt to increase attack resistance (optional)
   * Designed and written with emphasis on secure code
     - Plenty of testcases
     - Tested with valgrind for memory problems
     - Locking of state files to resolve race conditions
     - Implemented correct-configuration checkers

User mode:
   * Does not require additional SUID binaries in USER mode.
   * Works almost out-of-the-box.

Global mode:
   * Capable of enforcing system OTP security policy decisions:
   * Users can be forced to use OTP
   * Users can't directly access their state and can't easily break security.


5. Security Advisory
====================
It is very important that the user has a good understanding of the
OTPasswd intent, purpose and limitations.

The user is encouraged to read the documentation provided in the
<docs/SECURITY> (or /usr/share/doc/otpasswd/SECURITY if installed).

The user is advised to take the following basic 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.  If you are willing to use it
   as a first or single authentication factor - make sure you know
   what you are doing.

   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!


6. Installation
===============
OTPasswd installation instructions and description of operational
modes is covered in the INSTALL file. 


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


8. Contact Information
======================
You may contact the author with questions, support, praise or curses
at <mailto:bla@thera.be>.  Any feedback will be welcomed and keeps us
going (even a 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-2013 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/>.

IMPORTANT:
It was always planned to relicense this software under BSD-like
license one day. Most changes required for relicensing are already
complete. To contribute to the project you have to agree to relicense
your contribution as well.

                                     ###