Updated documentation and manual pages.

Also fixed Debian package just a bit to better
support documentation and example installation.

docs/SECURITY

@@ -1,20 +1,32 @@
 
               OTPasswd - One-Time Password Authentication System
               --------------------------------------------------
-                https://savannah.nongnu.org/projects/otpasswd
-                        Updated: 29-Dec-09 (v0.5pre1)
+                         http://otpasswd.thera.be
+                        Updated: 02-Nov-2013 (v0.8)
 
                                 SECURITY GUIDE
 
 
-
 Contents
 ========
+  0. Intro
   1. Security Concerns
   2. Passcode Generation Algorithm
   3. About PAM (short lecture)
 
 
+Intro
+-----
+Security is a difficult topic, especially once you give up the notion
+of ultimately `trusted' client while being unable to estimate your
+trust at all.  Use appropriate measures against threats based on their
+probability and risk factor. This file sumarises some topics the
+authors of OTPasswd had in mind while developing it.  Let it inspire
+you to do your own thinking.
+
+How often do you log into your systems from untrusted clients? I don't
+really trust my mobile in the first place, so... the answer for me is
+'often'. OTPasswd lets me reduce the risks a bit.
 
 1. Security Concerns
 ====================
@@ -29,7 +41,7 @@ There are certain security related issues you should be aware of.
      if the attacker manages to discover your UNIX password, for example
      through the use of a key logger or by sniffing the E-M radiation of
      your keyboard's PS/2 connection, the attacker would still need to
-     have access to your passcard.
+     have access to your passcard. 
 
  II. The second issue is that a Denial-of-Service (DoS) attack is possible in
      some configurations.  When an attacker repeatedly tries to authenticate
@@ -57,15 +69,16 @@ There are certain security related issues you should be aware of.
      3) By receiving passcodes on an as-needed basis via a secure channel
         which cannot be blocked by attacker, such as SMS text-messaging.
 
-        In some scenarios this scheme could also be susceptible to a DoS
-        attack.  For example, if a free SMS gateway is used which imposes
-        usage limits, an attacker who is aware of your phone number could
-        easily exhaust your daily quota of text messages.  While this type of
-        attack is technically possible, it's also quite unlikely.  However,
-        it does serve to highlight the fact that every countermeasure has
-        vulnerabilities.  As far as this particular attack is concerned,
-        SMS transmissions could simply be sent using a different method,
-        such as making use of a GSM phone/modem connected to the computer.
+        In some scenarios this scheme could also be susceptible to a
+        DoS attack.  For example, if a free SMS gateway is used which
+        imposes usage limits, an attacker who is aware of your phone
+        number could easily exhaust your daily quota of text messages.
+        While this type of attack is technically possible, it's also
+        quite unlikely.  However, it does serve to highlight the fact
+        that every countermeasure has vulnerabilities.  As far as this
+        particular attack is concerned, SMS transmissions could simply
+        be sent using a different method, such as making use of a GSM
+        phone/modem connected to the computer.
 
 
      NOTE: Early versions of OTPasswd included what was known as the
@@ -81,7 +94,8 @@ There are certain security related issues you should be aware of.
      sessions.  Since this option did not meet its intended design goal,
      it was ultimately removed.
 
-III. If an attacker is able to collect used passcards, it is conceivable
+III. Theoretical attack on cryptographic algorithms:
+     If an attacker is able to collect used passcards, it is conceivable
      that a brute-force attack could be made on the cryptographic key
      which was used to generate the passcodes.  If the key is discovered,
      then future passcodes could be generated at will.  Given the cipher
@@ -103,7 +117,8 @@ III. If an attacker is able to collect used passcards, it is conceivable
 IMPORTANT.  In order to securely login to a system with SSH you still
 must have trusted SSH client software (from a pendrive, for example)
 and you must validate the SSH server key fingerprint.  Also, beware of
-man-from-behind attacks when you're banged in the head after authenticating.
+man-from-behind attacks when you're banged in the head after
+authenticating. 
 
 
 
@@ -227,9 +242,28 @@ and finally:
 
    pam_unix     - checks password according to /etc/shadow
 
-This is an overview of the default PAM authentication schema (for Gentoo).
-Somewhere in this process we will need to add our OTP authentication.
+This is an overview of the default PAM authentication schema (for
+Gentoo).  Somewhere in this process we will need to add our OTP
+authentication.  There exists also alternative way of PAM module
+configuration using [] notation instead of required/requisite
+options. For more information about Linux-PAM, you may consult the
+PAM(7) man page on your system, or read the PAM System Administrator's
+Guide, which can be found at:
+
+   http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/Linux-PAM_SAG.html
+
 
+PAM Profiles
+------------
+Newer systems allows for PAM profile configuration. System keeps
+profiles in (e.g.) /usr/share/pam-configs and a certain tool
+(pam-auth-update) allows one to enable or disable selected
+profile. OTPasswd has a profile included in `examples' directory and
+it's the recommended way of configuring OTPasswd.
+
+
+Manual PAM configuration:
+------------------------
 The easiest approach is just to modify the first file: /etc/pam.d/sshd.
 At the end of all the 'auth' entries, we can just add our pam_otpasswd
 module.  The file would then look like this:
@@ -295,10 +329,5 @@ by modifying auth line:
    password   include        system-remote-login
    session    include        system-remote-login
 
-For more information about Linux-PAM, you may consult the PAM(7) man page
-on your system, or read the PAM System Administrator's Guide, which can
-be found at:
-
-   http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/Linux-PAM_SAG.html
 
                                      ###

docs/agent_otp.1

@@ -19,18 +19,20 @@
 .\"   along with OTPasswd.  If not, see <http://www.gnu.org/licenses/>.
 .\"
 .\"   Author:  R Hannes Beinert & Tomasz bla Fortuna
-.\"   Version: otpasswd v0.7
-.\"   Update:  15-Sep-10
+.\"   Update:  02-Nov-13
 .\"
-.TH OTPASSWD 1 2010-09-15 "OTPasswd v0.7" "OTPasswd User Manual"
+.TH AGENT_OTPASSWD 1 2013-11-02 "OTPasswd v0.8" "OTPasswd User Manual"
 .\"
+
 .SH NAME
 agent_otp \- One-time password agent
 .\"
+
 .SH SYNOPSIS
 .B agent_otp
 [\fIoptions\fR]
 .\"
+
 .SH DESCRIPTION
 The \fIotpasswd\fR agent serves as the backend for otpasswd utility.
 To enhance security in the version 0.7, the utility was split into agent,
@@ -42,6 +44,7 @@ be noted that agent is executed each time user runs the utility.
 That said, agent has a limited interface used solely for diagnostics. 
 You can use it when you're logged as root or then agent is not a SUID binary.
 .\"
+
 .SH OPTIONS
 .TP
 \fB\--testcase\fR
@@ -60,20 +63,11 @@ That said it's vital that this program was written and tested correctly.
 
 .SH SEE ALSO
 \fBotpasswd\fR(1),
-\fBotpasswd\fR(7),
-\fBpam_otpasswd\fR(8),
-\fBotpasswd.conf\fR(5),
-\fBotshadow\fR(5),
 \fBotpasswd\fR(5)
+\fBpam_otpasswd\fR(8),
 .\"
+
 .SH DOCUMENTATION
-The documentation for \fBotpasswd\fR is also maintained as a Texinfo manual.
-If the \fBinfo\fR and \fBotpasswd\fR programs are properly installed at your
-site, the following command should give you access to the manual:
-.PP
-.ti +4m
-$ info otpasswd
-.PP
 In addition to this manual, various other documents are included with the
 source to this package.
 Depending upon the \fBOTPasswd\fR package that was installed,
@@ -97,8 +91,9 @@ NNTP newsreader at <news://news.grc.com/grc.thinktank>.
 .\"
 .\"  *AUTHORS
 .\"
+
 .SH LICENSE
-Copyright (c) 2009, 2010 Tomasz bla Fortuna
+Copyright (c) 2009-2013 Tomasz bla Fortuna
 .PP
 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
@@ -113,11 +108,12 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program in a LICENSE file.
 .\"
+
 .SH AVAILABILITY
 The latest version of the \fBOTPasswd\fR package is available in source form
 at the project website
 .nh
-https://savannah.nongnu.org/projects/otpasswd
+http://otpasswd.thera.be
 .hy 1
 .\"
 .\" End of Manual: otpasswd(1)

docs/otpasswd.1

@@ -1,7 +1,7 @@
 .\"
 .\"   otpasswd(1) - One-Time Password Authentication System
 .\"
-.\"   Copyright (c) 2010 Tomasz bla Fortuna
+.\"   Copyright (c) 2010-2013 Tomasz bla Fortuna
 .\"
 .\"   This file is part of OTPasswd.
 .\"
@@ -19,18 +19,20 @@
 .\"   along with OTPasswd.  If not, see <http://www.gnu.org/licenses/>.
 .\"
 .\"   Author:  R Hannes Beinert & Tomasz bla Fortuna
-.\"   Version: otpasswd v0.7
-.\"   Update:  15-Sep-10
+.\"   Update:  02-Nov-13
 .\"
-.TH OTPASSWD 1 2010-09-15 "OTPasswd v0.7" "OTPasswd User Manual"
+.TH OTPASSWD 1 2013-11-02 "OTPasswd v0.8" "OTPasswd User Manual"
 .\"
+
 .SH NAME
 otpasswd \- One-time password management utility
 .\"
+
 .SH SYNOPSIS
 .B otpasswd
 [\fIoptions\fR]
 .\"
+
 .SH DESCRIPTION
 The \fIotpasswd\fR utility serves as the primary management tool
 for the \fBOTPasswd\fR one-time password authentication package
@@ -247,11 +249,13 @@ Brackets are optional.
 .RE
 .PD
 .\"
+
 .SH SECURITY NOTES
 This section needs to be completed (FIXME).
 Until this section is written, see the docs/security file which
 is distributed with the \fBOTPasswd\fR sources.
 .\"
+
 .SH EXIT STATUS
 \fBotpasswd\fR will return zero on success and non-zero on failure.
 This can be used for scripting
@@ -261,6 +265,7 @@ This can be used for scripting
 .\"   ERRORS             [Typically only in Sections 2, 3]
 .\"   ENVIRONMENT
 .\"
+
 .SH FILES
 .TP
 /etc/otpasswd
@@ -316,6 +321,7 @@ operation.  For more information, see \fBpam_otpasswd\fR(8).
 .\"
 .\"   VERSIONS           [Normally only in Sections 2, 3]
 .\"
+
 .SH COMPATIBILITY
 The \fBOTPasswd\fR authentication system is compatible with the
 "Perfect Paper Passwords" specification version 3 (PPPv3) as
@@ -337,6 +343,7 @@ of the PPP specification.
 .\"   NOTES
 .\"   BUGS
 .\"
+
 .SH EXAMPLES
 Every user must generate a key in order to use \fBOTPasswd\fR.
 Depending on the value of the \fBSALT_DEF\fR parameter in the
@@ -401,13 +408,11 @@ $ rm tmp.latex tmp.pdf
 .RE
 .\"
 .SH SEE ALSO
-\fBotpasswd\fR(7),
 \fBpam_otpasswd\fR(8),
-\fBotpasswd.conf\fR(5),
-\fBotshadow\fR(5),
 \fBotpasswd\fR(5)
 \fBagent_otp\fR(1)
 .\"
+
 .SH DOCUMENTATION
 The documentation for \fBotpasswd\fR is also maintained as a Texinfo manual.
 If the \fBinfo\fR and \fBotpasswd\fR programs are properly installed at your
@@ -439,6 +444,7 @@ NNTP newsreader at <news://news.grc.com/grc.thinktank>.
 .\"
 .\"  *AUTHORS
 .\"
+
 .SH HISTORY
 The creation of this program was inspired by the \fBppp\-pam\fR project
 (http://code.google.com/p/ppp\-pam).
@@ -448,6 +454,7 @@ however ultimately it was decided to do a complete rewrite.
 The two projects share some code, such as locking functions, but nothing more.
 It would be reasonable to think of \fBOTPasswd\fR as a fork of \fBppp\-pam\fR.
 .\"
+
 .SH LICENSE
 Copyright (c) 2009, 2010 Tomasz bla Fortuna
 .PP
@@ -464,6 +471,7 @@ GNU General Public License for more details.
 You should have received a copy of the GNU General Public License
 along with this program in a LICENSE file.
 .\"
+
 .SH AVAILABILITY
 The latest version of the \fBOTPasswd\fR package is available in source form
 at the project website