INSTALL

              OTPasswd - One-Time Password Authentication System
              --------------------------------------------------
                https://savannah.nongnu.org/projects/otpasswd
                        Updated: 02-Oct-13 (v0.8)

                              INSTALLATION GUIDE


Contents
========
  0. Introduction
  1. Installation Overview
  2. Package Dependencies
  3. Installation - Source Package
  4. System Configuration
  5. User Configuration
  6. PAM Configuration
  9. Copyright


0. Introduction
===============
OTPasswd can easily be configured to work in conjunction with any text-based
PAM-aware application, such as sudo, su, ftp, or any standard *nix console
login.  The typical use case for OTPasswd by far, however, is to secure
non-publickey SSH logins, which is what will be described in this section.

Short installation steps:
$ cmake . -DNLS=1
$ make
# make install
# Set ChallengeResponseAuthentication and UsePAM to yes in sshd_config
# Enable otpasswd in PAM (see examples).
You need cmake and libpam-dev.

In case of problems you can always check your configuration with:
$(which agent_otp) --check-config


Operational Mode
----------------
OTPasswd is able to run in two slightly different modes, which are
distinguished by the location of the stored user data (called `the
state').  By default OTPasswd works in a less intrusive mode called
`USER DB'.  Changing mode is an essential configuration choice that
must be understood well by the system administrator.  

In the 'USER DB' mode, a user's state 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 state.  As a consequence, however, the user's
data 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 state 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, usually
/etc/otpasswd/otshadow, or (not yet implemented) LDAP/MySQL database.  The
user has no read/write access to the configuration and state 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.

To even increase security the OTPasswd console utility was split into two
executables: utility (otpasswd) and agent (agent_otp). Only the latter is given
the root privileges, but it's completely bereft of any user interface, which is
implemented in the utility. This division ensures the user won't be able to
suspend execution of the agent while it has locked the global database.


1. Installation Overview
========================
To compile, install, and configure OTPasswd to work with SSH you must
complete the following steps:

   0. Have all required dependencies
   1. Install the package
   2. Tweak OTPasswd configuration
   3. Generate a user key (and print at least one passcard)
   4. Enable OTPasswd in /etc/pam.d
   5. Configure SSH to use PAM authentication

Be aware that if OTPasswd is installed over an SSH connection, it is possible
to inadvertently become "locked-out".  This can happen if OTPasswd is enabled
for SSH logins prior to having generated an initial set of passcodes, which
in turn requires the generation of a OTPasswd user key.  The installation
procedure outlined above is intended to minimize the likelihood that this
will happen.


2. Package Dependencies
=======================
OTPasswd may be installed either through compilation from source, or
if available, from a pre-compiled binary package.  Prefer distribution
packages if possible.

OTPasswd has no external runtime dependencies except for
PAM. Additional packages are required when OTPasswd is compiled from
source, namely, the CMake cross-platform build system, as well as the
corresponding development packages for PAM.  To generate documentation
of internal API one is required to install Doxygen.  All of these
packages should be available in your distribution's repositories.

Packages you need:
* cmake
* libpam-dev (usually libpam0g-dev)
* compilers (build-essential for Debian / Ubuntu)
* doxygen


3. Installation (Source Package)
================================
Check to see if a pre-compiled binary package is available for OTPasswd
in your distribution's package manager.  If so, then install it as you
would any other package.  Otherwise, you will need to compile OTPasswd
from source, as follows:

   $ cd otpasswd
   $ cmake -DNLS=1 .    # Generate makefiles (You can add -DDEBUG=1)
   $ make               # Compile everything

   On Linux distributions you can install OTPasswd into the system 
   by running as root a following command:
   $ make install

If you would prefer to perform the final installation step manually,
then instead of using 'make install' you can copy the following files:

   a) PAM module 'pam_otpasswd.so'
      Linux: /lib/security/ 
      FreeBSD: /usr/lib
      
   b) Utility program 'otpasswd' and agent 'otp_agent'
      Linux: /usr/bin/
      FreeBSD: /usr/local/bin/

   c) PAM configuration
      Copy into /etc/pam.d one of files:        
      Linux:      example/otpasswd-login
      FreeBSD:    example/otpasswd-login_FreeBSD

   d) OTPasswd configuration    
      'example/otpasswd.conf'  -> /etc/otpasswd/otpasswd.conf


Using GLOBAL DB
---------------

When using 'GLOBAL DB' mode you should: 

* Create a unique system user exclusively for OTPasswd, 'otpasswd' is
  recommended.
  **    adduser --system --no-create-home otpasswd
* Directory /etc/otpasswd should be owned by this selected user.
* `agent_otp' and `otpasswd' should be owned by root.
* `agent_otp' should be SETUID root.  
* Set DB option to GLOBAL in otpasswd configuration file.

By default, no OTPasswd binaries are SUID. If choosing a non-standard
name for user please remember to update config file accordingly.

To run test suite you'd best install the otpasswd in the system
(before updating PAM configuration) and then run tests. To run them in
the source directory you need to compile otpasswd with -DDEBUG and
place default config in /etc directory.


4. System Configuration
=======================
OTPasswd is configured via the /etc/otpasswd/otpasswd.conf file.  Upon
initial installation, otpasswd.conf located in this directory will
contain a template of all valid configuration options along with
copious commentary.  A pristine version of this file should be
available in the OTPasswd package documentation directory of your
system's /usr/share hierarchy. Default file should allow for
out-of-the-box usage with USER DB mode.

The most important configuration setting is the "DB" option.  The DB option
can be set as follows:

   DB=user
   -------
   In this mode, OTPasswd stores user state information in the user's
   home directory.  As a result, the OTPasswd agent doesn't require
   any SUID privilege, and can be run in the user's security context.
   Note that even if the agent is installed with the SUID flag, it
   will drop privileges immediately after reading the configuration file.
   The major disadvantage of this mode is that since the user has complete
   access to his state file, it is impossible to guarantee all aspects of
   system security policy compliance.  Among other things, a user could cause
   passcode recycling/reuse through manipulation of state file information.

   DB=global
   ---------
   This mode uses a system-wide configuration database.  The default
   location for this database is /etc/otpasswd/otshadow.  The database
   file and directory which contains it must be owned by a special user
   created for OTPasswd use, and it MUST not be readable for normal users.
   Since all critical data is under system control, system security policies
   can be enforced.  However, the OTPasswd agent must be granted SUID
   privilege to the OTPasswd UID to enable access to this database on the
   user's behalf.

   DB=mysql
   --------
   (Not currently implemented) The user state information is stored in a
   MySQL database.  The database access password is stored in the OTPasswd
   configuration file /etc/otpasswd/otpasswd.conf, so this file must be
   readable only by the special OTPasswd UID described above.  The OTPasswd
   utility must be run with SUID privilege to gain access the configuration
   file, however privileges are dropped promptly after reading the file.

   DB=ldap
   -------
   (Not currently implemented) The user state information is stored in an
   LDAP database.  See the DB=mysql description above for more information.


5. User Configuration
=====================

Generate OTPasswd Key & Print Passcard
-----------------------------------------
To use OTPasswd, a user is required to have a cryptographic key, which is
then used to generate the user's passcodes.  To generate this key, ensure
that you are logged in as the user for whom you want to create the key,
then issue the following command:

   $ otpasswd --key

An administrator may generate a key for any user, as follows:

   $ otpasswd --key --user tux

Be aware that OTPasswd, by default, generates a key which is not compatible
with the PPPv3.1 specification.  If you would like to retain compatibility
with the specification and thereby also retain interoperability with other
PPPv3 applications, you may either change the default behavior by modifying
the SALT_DEF parameter in the otpasswd.conf configuration file, or add
the --config salt=off flag during key generation as in the following example:

   $ otpasswd --config salt=off --key

You may also combine other flags with key generation (-k), to set contact 
or label like this:

   $ otpasswd -c label=Home -c contact=012689 -c alphabet=2 -c codelength=6 -k

Note: As mentioned above, if OTPasswd is being configured over an SSH
session, it is conceivable that one can lose one's ability to log back
in after any key change since one will not yet have any valid passcodes.
Because of this, the OTPasswd utility will immediately print a passcard
upon key generation.  The prudent user would be wise to either print
this passcard, or minimally jot down the first few passcodes.  You have
been warned.


6. PAM Configuration
====================

Debian package comes with a PAM otpasswd profile in
<examples/pam-configs/otpasswd> which after installation in
</usr/share/pam-configs> can be easily enabled and disabled using
`pam-auth-update' command. This method of PAM installation is
preferred on all systems which support it.

To enable OTPasswd use with SSH, pam_otpasswd must be called
inside the `auth' PAM stack, right after the default pam_unix module.
An example pam.d configuration file is in <examples/otpasswd-login>.

One can move otpasswd-login example to /etc/pam.d directory and set it
up for ssh instead of the original authentication stack by
substituting:
   From:
         auth       include        system-remote-login
   to:
         auth       include        otpasswd-login

Consult the section titled 'About PAM' in the <docs/security> document
for more detailed information. 


PAM Configuration - OpenSSH
---------------------------
While it would technically also be possible for OTPasswd to be used in
GUI-based PAM applications, as one might find in the KDE or Gnome desktops,
the necessary GUI layers do not presently exist.  The typical use case for
OTPasswd by far, however, is to secure non-publickey SSH logins, which is
what will be described in this section.

The OpenSSH daemon's (SSHD) configuration is usually located in the file
'/etc/ssh/sshd_config'.  Ensure that this file contains the following
two lines:

   ChallengeResponseAuthentication yes
   UsePAM yes

It is entirely possible that these two configuration settings are already
enabled, and that no modification is required.  If the file must be modified,
it should contain no other uncommented instances of either keyword.
Note that it is always advisable to make a backup copy of configuration
files prior to making any changes.


PAM Configuration - su
----------------------
As an example of the flexibility that OTPasswd is able to offer by using
the PAM (Pluggable Authentication Modules) Library, once OTPasswd has
been configured it is easy to incorporate OTP authentication with other
PAM-aware applications.  The su(1) command is easily secured by OTPasswd
by modifying its PAM configuration, as is described in this section.

OTPasswd also works with xscreensaver.


9. Copyright
============
Copyright (c) 2010-2013 Tomasz bla Fortuna

This file is part of OTPasswd. See README file for licensing
information.

                                     ###