/usr/share/doc/libotpw-dev/otpw.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<TITLE>OTPW – a one-time password login package</TITLE>
<META NAME="keywords" CONTENT="computer security, S/KEY, Ssh,
secure login, password sniffing, eavesdropping, OTPW">
<META NAME="description" CONTENT="Free implementation of a one-time
password scheme allowing remote access from untrusted terminals.">
<META http-equiv=Content-Type content="text/html; charset=UTF-8">
<link rel="stylesheet" href="file:/usr/share/doc/libpam-otpw/default.css"
      type="text/css">
</HEAD>

<BODY>
<H1>OTPW – A one-time password login package</H1>

<P><A HREF="https://www.cl.cam.ac.uk/~mgk25/">Markus Kuhn</A>, Computer
Laboratory, University of Cambridge

<P><A HREF="https://www.cl.cam.ac.uk/~mgk25/otpw.html">Latest release</A>:
Version 1.5, 2014-08-07

<H2 id="abstract">Abstract</H2>

<P>The OTPW package consists of the one-time-password generator
<CITE>otpw-gen</CITE> plus two verification routines
<CITE>otpw_prepare()</CITE> and <CITE>otpw_verify()</CITE> that can
easily be added to programs such as <CITE>login</CITE> or
<CITE>ftpd</CITE> on POSIX systems. For platforms that support the
Pluggable Authentication Method (PAM) interface, a suitable wrapper is
included as well. Login software extended this way will allow
reasonably secure user authentication over insecure network lines. The
user carries a password list on paper. The scheme is designed to be
robust against theft of the paper list and race-for-the-last-letter
attacks. Cryptographic hash values of the one-time passwords are
stored for verification, either in the user’s home directory or in
a dedicated system directory.

<H2 id="intro">Introduction</H2>

<P>A well-known classic vulnerability of the Internet application
protocol suite is the frequent cleartext transfer of passwords in the
telnet, rsh, and ftp protocols. Modern replacements for these
protocols such as <A HREF="http://www.cs.hut.fi/~ylo/">Tatu
Ylönen</A>’s <A
HREF="http://www.ietf.org/html.charters/secsh-charter.html">Secure
Shell</A> allow comfortable and secure remote sessions and file
transfers over network connection that are not trusted to provide
confidentiality.

<P>However, traveling computer users often want to connect to their
home system via untrusted terminals at conference hotels, other
universities, and airports, where trusted encryption software is not
available. Even Secure Shell does not protect against keyboard
eavesdropping software on the untrusted terminal. A loss of
confidentiality is often acceptable in these situations for the
session content, but not for reusable login passwords.
One-time-password schemes avoid the transmission of authentication
secrets that are of any value after they have been used. This provides
a reasonable level of protection against the widely encountered
password sniffing attacks. The goal of a one-time-password login
scheme is merely to provide a significant increase of security over
the classic telnet/rlogin login procedure. It does
<STRONG>not</STRONG> aim to protect from sophisticated active attacks
such as session hijacking, host emulation, man-in-the-middle, etc.
against which ssh and SSL based protocols should be used if this level
of protection is required.

<P>A widely known one-time-password scheme is <A
HREF="ftp://ftp.cert.dfn.de/pub/tools/password/SKey/">S/KEY</A>
[Hal94, HM96]. OTPW is not compatible with and is not derived from
either S/KEY or <A HREF=
"http://www.inner.net/pub/opie/">OPIE</A>. It is a
completely independent and different design, which I believe fulfils
my functional and security requirements better.

<H2 id="operation">How it works</H2>

<P>One-time password authentication with the OTPW package is
accomplished via a file containing hash values of passwords. Depending
on the installation option chosen, this can either be a
file <CITE>~john/.otpw</CITE> located in the user’s home directory, or
it can be a file <CITE>~otpw/john</CITE> in the home directory of a
dedicated pseudo user “otpw”. In the latter case, the otpw-gen tool
for generating new passwords must be owned by pseudo user “otpw” and
have the SETUID bit set. As long as users do not have such a hash
file, the one-time-password facility is not active for them.

<P>A user who wants to setup the one-time-password capability just
executes the <CITE>otpw-gen</CITE> program. The program will ask for a
<EM>prefix password</EM> that the user has to select and memorize and
it will then write to standard output a password list such as:

<PRE>
  OTPW list generated 2003-08-31 21:06 on trillium.cl.cam.ac.uk

  000 IZdB bqyH  006 rF62 k6zi  012 JCFe 6at3  018 uaYT azuu  024 Nt7n b=fQ
  001 yCSo /VQs  007 Phvb =6ZW  013 8Pm7 DbYJ  019 OdAk H62c  025 /pOm :ZEA
  002 mESf +nWK  008 J9fH iXrn  014 MAds 6TTS  020 Aj6W 9O4P  026 DhCc yrPY
  003 x4vX HXr2  009 DGPC amts  015 B=xZ waPx  021 MzUP Ahsc  027 UWTe G3Fh
  004 A5z9 japt  010 s6cr xwZ5  016 sCgq Da5Y  022 Q=XK 4I7w  028 xszW Ha9L
  005 YCcA k29/  011 inn6 Rsa/  017 m8za o/HB  023 umS= gYoU  029 +HmG Rr6P

              !!! REMEMBER: Enter the PREFIX PASSWORD first !!!
</PRE>

<P>Normally the output of <CITE>otpw-gen</CITE> should be sent directly to
the printer as in

<PRE>
  otpw-gen | lpr
</PRE>

<P>or should be first formatted with an ASCII to PostScript converter
where necessary.

<P>Fetch the printed list immediately from the printer, fold it, and
keep it with you. The list shows the machine name and the creation
time to allow users to find the latest list for the right machine. It
does not show the user’s name, because nobody is supposed to have the
list of anyone else, but printer drivers such as <CITE>a2ps</CITE>
might add it. Only a single list is required for a set of networked
machines on which the user has a common home directory.

<P>By default, <CITE>otpw-gen</CITE> generates 60 lines of output. Use
the command line options <SAMP>-h</SAMP> <VAR>lines</VAR>,
<SAMP>-w</SAMP> <VAR>columns</VAR>, and
<SAMP>-s</SAMP> <VAR>pages</VAR> to specify the length of the
output. No more than 1000 passwords will be generated at a time.

<P>Where one-time-password authentication is used, the password prompt
will be followed by a 3-digit password number. Enter first the prefix
password that was given to <CITE>otpw-gen</CITE>, followed directly
(without hitting return between) by the password with the requested
number from the printed password list:

<PRE>
  login: <B>kuhn</B>
  Password 019: <B>geHeimOdAkH62c</B>
</PRE>

<P>In this example, <SAMP>geHeim</SAMP> was the prefix password. The
spaces in the password list are just there to increase readability and
can be dropped.

<P>A clever attacker might observe the password being entered and
might try to use the fact that computers can send data much faster
than users can finish entering passwords. In the several hundred
milliseconds that the user needs to press the return key after the
last character, an attacker could on a parallel connection to the same
machine send the code of the return key faster than the user.

<P>To prevent such a race-for-the-last-key attack, any login attempt
that is taking place concurrently with another attempt will require
three one-time passwords to be entered:

<PRE>
  login: <B>kuhn</B>
  Password 022/000/004: <B>geHeimQ=XK4I7wIZdBbqyHA5z9japt</B>
</PRE>

<P>This might look inconvenient at first, but remember that three
passwords will only be requested when someone tries to login
simultaneously, which in itself should already cause suspicion. The
three requested passwords are randomly selected but they will never
include the single password that was requested in the first of the
concurrent login attempts. Only the first requested single password
will be locked, not any of the requested triples. This way, the
three-password method ensures that an attacker cannot disable the OTPW
mechanism by locking all passwords. The triple challenge ensures that
many ten thousand network connections would be necessary to perform a
race attack on the same password triple, which is not practical. The
OTPW package creates a symbolic link <SAMP>.otpw.lock</SAMP> in the
user’s home directory to lock the first requested password while its
input is pending. If a system crash created a stale lock, it will be
removed after 24 hours.

<P>The <SAMP>.otpw</SAMP> file looks like

<PRE>
  OTPW1
  30 3 12 8
  ---------------
  ---------------
  023vf+Uvbg7AqjC
  025Mm+mJWbStzL5
  024aPEXvP3pgUYa
  008r3b5efMVT%IU
  002AQ63iP8ymMWq
  005:PcEr:LoieKO
  ---------------
  0135:Gw==tjv=rA
  020rQQ2C2SQP%EU
  02197Jh5deXd8ga
  016qN9qPHh4CNz6
  010BcqejWc+kI6i
  027hkkmBcMZYxgg
  029tkB6Wm5yS=F7
  003BpcMoM=YwTPY
  018f=4hAXWpwetr
  014jiOz/aMow83k
  0099gRB2+8QX8BC
  012QBhdmm7k=Hqs
  007g6zMK%Ryp6hZ
  015XsTSUVUYTJ+8
  017uxVFK6BikgpV
  ---------------
  0067t5Z8SIdz/6h
  026CN/JqBQJLKZE
  028V5hj+3wYkFHq
  011VooKgV4PAJRD
  0016AtPvgkVe+Rw
</PRE>

<P>The first line identifies the file format. The second line shows the

<UL>

<LI>number of originally generated password entries,

<LI>digits per password number (3),

<LI>characters per base-64 encoded hash value (12),

<LI>characters per one-time password.

</UL>

<P>Every subsequent line is a password number followed by the <A HREF=
"http://www.esat.kuleuven.ac.be/~bosselae/ripemd160.html">RIPEMD-160</A>
hash value of the prefix password concatenated with one of the printed
one-time passwords. Only the first 12×6 = 72 bits of the hash value
encoded in the same modified base-64 encoding that was used to
generate the passwords is stored there. As soon as a one-time password
has been entered correctly, the corresponding <SAMP>.otpw</SAMP> line
will be overwritten with hyphens to prevent any reuse of this
password.

<H2 id="install">Installation</H2>

<P>Get the OTPW package <SAMP>otpw-*.*.tar.gz</SAMP> from <A
HREF="https://www.cl.cam.ac.uk/~mgk25/download/">
https://www.cl.cam.ac.uk/~mgk25/download/</A> or use
<pre>
  git clone https://www.cl.cam.ac.uk/~mgk25/git/otpw
</pre>

<P>First have a look into <SAMP>otpw.c</SAMP>
and <SAMP>otpw-gen.c</SAMP> where some system parameters can be
changed. The only item there really worth being checked carefully is
<SAMP>entropy_cmds</SAMP>. It contains a list of shell commands, whose
output is used to initialize the random number generator
in <CITE>otpw-gen</CITE>. Make sure that at least most of these shell
commands actually do work on your system and produce an output that is
extremely difficult to predict for potential attackers. If your
operating system has a <SAMP>/dev/random</SAMP> or
<SAMP>/dev/urandom</SAMP> device that gives access to a good true
random number generator, then make sure that a command reads and
outputs about 20 bytes from there. In <SAMP>entropy_env</SAMP>, some
environment variables (e.g., <SAMP>PATH</SAMP>) can be set for these
shell commands.

<P>Just start <CITE>make</CITE> to compile the <CITE>otpw-gen</CITE>
and <CITE>demologin</CITE> programs. While <CITE>otpw-gen</CITE> can
directly be made available to the user, <CITE>demologin</CITE> is only
an example of the modifications that you have to make to your login
program to support one-time passwords using OTPW.

<P>The login program has to call

<PRE>
  #include "otpw.h"

  struct challenge ch;
  struct passwd *pwd;

  otpw_prepare(&amp;ch, pwd);
</PRE>

<P>after the user name has been entered and the POSIX password
database entry has been read into <SAMP>*pwd</SAMP>. The routine will
select a challenge password, which will be stored in
<SAMP>ch.challenge</SAMP>, and will lock it if necessary. If this was
not possible, for instance because the user has no unused passwords
left, then <SAMP>ch.challenge</SAMP> will be an empty string.
Otherwise, <SAMP>ch.challenge</SAMP> should be displayed to the user
in some way before the password prompt. After the password has been
entered, call

<PRE>
  result = otpw_verify(&amp;ch, password);
</PRE>

<P>and if <SAMP>result == OTPW_OK</SAMP> then accept the user as
authorized, otherwise do not. It is very important that
<SAMP>otpw_verify()</SAMP> is always called after
<SAMP>otpw_prepare()</SAMP> has returned successfully (i.e., with a
non-empty <SAMP>ch.challenge</SAMP> string), as otherwise a stale lock
might remain set. In <SAMP>otpw_prepare()</SAMP>, the current working
directory will be changed to the user’s home directory, and
<SAMP>otpw_verify()</SAMP> expects that it is still there. If after
<SAMP>otpw_verify()</SAMP> has returned, the condition
<SAMP>ch.entries > 2 * ch.remaining</SAMP> is true and half of all
passwords have been used, the user should be remembered to generate a
new password list by executing <CITE>otpw-gen</CITE>. The security of
OTPW is increased if a new password list is created long before all
passwords on the old list have been used.

<P>Both routines can be called with the <SAMP>root</SAMP> user id and
they will temporarily change the effective user-id to that of the user
in order to access the password file in the home directory. OTPW does
not use any of the POSIX advisory file locking system calls, as those
often do not work reliably over network file systems.

<H3 id="pam">PAM installation</H3>

<P>If your system supports Pluggable Authentication Modules
[Mor01,XSSO], then simply compile the shared library
<CITE>pam_otpw.so</CITE> and copy it to the directory in which other
PAM modules reside (under Linux usually <SAMP>/lib/security/</SAMP>).
Then edit the PAM configuration file for the application in which you
want to use OTPW, as described in your <A
HREF="http://www.linux-pam.org/Linux-PAM-html/Linux-PAM_SAG.html">PAM
System Administrators’ Guide</A>. The <CITE>pam_otpw.so</CITE>
provides both an authentication and a session component. The
authentication component asks for and verifies a one-time password,
the session component prints after each successful login a reminder on
how many unused passwords you have left.

<P>To use both components when loggin into your system via Secure
Shell, you might have to add in <SAMP>/etc/pam.d/sshd</SAMP> the lines
<PRE>
  auth            required        pam_otpw.so
  session         optional        pam_otpw.so
</PRE>

<P>With <SAMP>OpenSSH 5.9p1</SAMP> for example, you need to make sure
that it has PAM support compiled in, and you will need
in <SAMP>/etc/ssh/sshd_config</SAMP> the lines
<PRE>
  UsePrivilegeSeparation            no
  UsePAM                            yes
  ChallengeResponseAuthentication   yes
</PRE>

<P>To force OpenSSH to use PAM authentication (instead of its own
hostbased or publickey methods, which it normally tries first), use
“<SAMP>ssh -o PreferredAuthentications=keyboard-interactive</SAMP>”.

<h3>Pseudo user setup</h3>

<p>Starting with otpw-1.5, if you would like to keep the password hash
files out of the reach of your users, you can create a pseudo user
“otpw” (uid < 1000) and an associated home directory where the
password files will be stored. On Ubuntu Linux, for example, the steps
necessary for such a setup might be
<pre>
  $ adduser --system --gecos 'OTPW pseudouser' --home /var/lib/otpw otpw
  $ chown otpw /usr/bin/otpw-gen && chmod u+s /usr/bin/otpw-gen
</pre>

<H2 id="rationale">Design rationale</H2>

<P>Unlike S/KEY [Hal94, HM96], OTPW is not based on the Lamport scheme
[Lam77] in which every one-time password is the one-way hash value of
its successor. Password lists based on the Lamport scheme have the
problem that if the attacker can see one of the last passwords on the
list, then all previous passwords can be calculated from it. We also
do not store the encrypted passwords as suggested by Rubin [Rub96], in
order to keep the host free of files with secrets. Both proposals
aimed to save memory in the host system. Instead, we store the one-way
hash value of every single password in a potentially widely readable
file in the user’s home directory. For instance, hash values of 300
passwords (a typical A4 page) require only a four kilobyte long
<SAMP>.otpw</SAMP> file, a typically negligible amount of storage
space.

<P>The passwords are carefully generated random numbers. The random
number generator is based on the RIPEMD-160 secure hash function
[DBP96, ISO03]. The random number generator is seeded by hashing
together the output of various shell commands. These provide
unpredictability in the form of a system random number seed, access
times of important system files, usage history of the host, and more.
The random state is the 160-bit output of the hash function. The
random state is iterated after each use by concatenating the old state
with the current high-resolution timer output and hashing the result
again. The first 72 bits of the hash output are encoded with a
modified base64 [FB96] scheme to produce readable passwords, while the
remaining 88 bits represent the undisclosed internal state of the
random number generator.

<P>In many fonts, the characters <SAMP>0O</SAMP> or <SAMP>1lI</SAMP>
are difficult to distinguish, therefore the modified base64 encoding
replaces the three characters <SAMP>01l</SAMP> by <SAMP>:=%</SAMP>. If
for instance a zero is confused with a capital <SAMP>O</SAMP> by the
user, the password verification routine will automatically correct for
this.

<P>S/KEY uses sequences of short English words as passwords. OTPW uses
by default a base64 encoding instead, because that allows more
passwords to be printed on a single page, with the same password
entropy. In addition, an average human spy needs over 30 seconds to
write a 12-character random string into short-term memory, which
provides a good protection against brief looks that an attacker might
have on a password list. Lists of short words on the other hand are
much faster to memorize. OTPW can handle arbitrary password generation
algorithms, as long as the length of the password is fixed. In the
current version, <SAMP>otpw-gen</SAMP> can generate both base-64
encoded (option <samp>-p</samp>) and 4-letter-word encoded (option
<samp>-p1</samp>) passwords with a user-specified entropy (option
<samp>-e</samp>).

<P>The prefix password ensures that neither stealing the password list
nor eavesdropping the line alone can provide unauthorized access.
Admittedly, the security obtained by OTPW is not comparable with that
of a challenge-response system in which the user has a PIN protected
special calculator that generates the response. On the other hand, a
piece of paper is much more portable, much more robust, and much
cheaper than a special calculator. OTPW was designed for the large
user base, for which an extra battery-powered device is inconvenient
or not cost effective and who therefore still use normal Unix
passwords everywhere.

<P>In contrast to the suggestion made in RFC 1938, OTPW does not lock
more than one one-time password at a time. If we did this, an attacker
could easily exhaust our list of unlocked passwords and force us to
either not login at all or use the normal Unix login password.
Therefore, OTPW locks only one single password and for all further
logins a triple-challenge is issued. If more than 100 unused passwords
remain available, then there are over a million different challenges
and an attacker has very little chance to perform a successful race
attack while the authorized user finishes password entry.

<P>The RIPEMD-160 routine was provided by Antoon Bosselaers
(Katholieke Universiteit Leuven). Steven Murdoch wrote significant
parts of the PAM wrapper and prepared a test setup. Also thanks to Kan
Zhang, Piete Brooks and David Wheeler for useful suggestions.

<H2 id="bugs">Known problems</H2>

<UL>

<LI id="opensshbug">The OTPW PAM module exposes a <a
href="http://bugzilla.mindrot.org/show_bug.cgi?id=632">bug</a> in <a
href="http://www.openssh.com/">OpenSSH</a> 3.6.1–5.9 (and possibly many
other versions) under Linux:

<p><b>Observation:</b> If the ssh user aborts the keyboard-interactive
password entry, for example by pressing Ctrl-C, then OTPW will not
remove its <samp>~/.otpw.lock</samp> file. As a result, the user will
get a triple-password request prompted at the next login attempt.

<p><b>Analysis:</b> Debugging the sshd process with a breakpoint at
the start of <SAMP>pam_end()</SAMP> shows that when ssh aborts the
connection while sshd is inside the “conversation function” that sshd
provides to the PAM system, then the conversation function never
returns to PAM. Instead sshd calls <SAMP>pam_end()</SAMP> directly
from inside the conversation function. This is in violation of <em><a
href="http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam_appl.html">The
Linux-PAM application developers’ guide</a></em> (draft 0.73,
2000-12-02), which states in <a
href="http://www.kernel.org/pub/linux/libs/pam/Linux-PAM-html/pam_appl-3.html#ss3.2">section
3.2.1</a>, page 14 that “should an error occur the application should
[...] simply return PAM_CONV_ERR”. Linux-PAM keeps in
<SAMP>pamh->caller_is</SAMP> track of whether the calling thread was
supposed to come from the application (caller_is=2) or from the PAM
module (caller_is=1). (See
<samp>Linux-PAM-0.75/libpam/pam_private.h</samp> for the relevant
macros.) The incorrect call of <SAMP>pam_end()</SAMP> simply results
in an error message by Linux-PAM, because Linux-PAM thinks based on
its <SAMP>pamh->caller_is=1</SAMP> value that <SAMP>pam_end()</SAMP>
was accidentally called by the module. As a result, none of the PAM
data structures are cleaned up, one side effect of which is that the
OTPW lock file remains in place. Sshd reacts on the failure of
<SAMP>pam_end()</SAMP> with the syslog message “Cannot release PAM
authentication[4]: System error”. Another security-relevant side
effect is that the memory scrubbing that PAM normally applies
carefully to any password buffers never takes place!

<p><b>Workaround:</b> None. This needs to be fixed urgently by the
OpenSSH developers, as it also breaks the proper deallocation of
buffers with secrets.

</UL>

<H2 id="license">License</H2>

<p>OTPW – A one-time password login package

<p>Copyright &#xa9; 1998–2014 Markus Kuhn

<p>This program is free software; you can redistribute it and/or
modify it under the terms of the <a
href="http://www.gnu.org/licenses/gpl.txt">GNU General Public
License</a> as published by the <a href="http://www.fsf.org/">Free
Software Foundation</a>; either version 2 of the License, or (at your
option) any later version.

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

<H2 id="refs">References</H2>

<P>[Lam77] &nbsp; Leslie Lamport: <CITE>Password Authentication with Insecure
Communication</CITE>, Communications of the ACM, Vol 24, No 11,
November 1981, pp 770–772

<P>[Hal94] &nbsp; Neil Haller, <CITE><A
HREF="ftp://cag.lcs.mit.edu/pub/dm/papers/haller:skey.ps.gz">The S/KEY
One-Time Password System</A></CITE>, Proceedings of the ISOC Symposium
on Network and Distributed System Security, February 1994, San Diego,
CA.

<P>[HM96] &nbsp; Neil Haller, Craig Metz: <CITE><A HREF=
"http://www.ietf.org/rfc/rfc1938.txt"> A One-Time Password
System</A></CITE>, RFC 1938, May 1996.

<P>[Rub96] &nbsp; Aviel D. Rubin: <CITE><A
HREF="http://www.cs.nyu.edu/~rubin/one-time.ps.gz">Independent
One-Time Passwords</A></CITE>, USENIX Journal of Computer Systems,
February, 1996.

<P>[DBP96] &nbsp; H. Dobbertin, A. Bosselaers, B. Preneel: <CITE><A
HREF="ftp://ftp.esat.kuleuven.ac.be/pub/COSIC/bosselae/ripemd/ripemd160.ps.gz">
RIPEMD-160, a strengthened version of RIPEMD</A></CITE>, Fast Software
Encryption, LNCS 1039, D. Gollmann, Ed., Springer-Verlag,
1996, pp. 71-82.

<P>[ISO03] &nbsp; ISO/IEC 10118-3, <CITE>Information technology — Security
techniques — Hash-functions — Part 3: Dedicated hash-functions</CITE>,
International Organization for Standardization, Geneva, 2003.

<P>[FB96] &nbsp; Ned Freed, Nathaniel S. Borenstein: <CITE><A HREF=
"http://www.ietf.org/rfc/rfc2045.txt">Multipurpose Internet Mail
Extensions (MIME) – Part One: Format of Internet Message
Bodies</A></CITE>, RFC 2045, November 1996.

<P>[Mor01] &nbsp; Andrew G. Morgan:
<A HREF="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM</A>.

<P>[XSSO] &nbsp; <A
HREF="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open Single
Sign-On Service (XSSO) – Pluggable Authentication</A>. June 1997.

<P><A HREF= "https://www.cl.cam.ac.uk/~mgk25/">Markus Kuhn</A>
<p class=footdate>created 1997-11-25 –
last modified 2014-08-07 –
https://www.cl.cam.ac.uk/~mgk25/otpw.html
</BODY>
</HTML>
libotpw-dev 1.5-1 / usr / share / doc / libotpw-dev / otpw.html
