NRL OPIE Software Distribution, Release 2.02             Important Information
============================================             =====================

Introduction
============

	"One-time Passwords In Everything" (OPIE) is a freely distributable
software package mostly developed at and for the US Naval Research
Laboratory (NRL). OPIE provides a one-time password system for UNIX-like
operating systems. The system should be secure against the passive attacks
now commonplace on the Internet (see RFC 1704 for more details). The system
is vulnerable to active dictionary attacks, though these are not widespread
at present and can be detected through proper use of system audit
software. The NRL OPIE software is derived in part from and is fully
interoperable with the Bell Communications Research (Bellcore) S/Key Release
1 software. Because Bellcore claims "S/Key" as a trademark for their
software, NRL has been forced to use a different name (we picked "OPIE") for
its software distribution.

	NRL OPIE includes the following additions/modifications to the
original Bellcore S/Key(tm) Version 1 software:

* Just about one-command installation for many common platforms. While we
  still recommend that you follow instructions and test things by hand, the
  more adventurous can install OPIE quickly.

* A modified BSD FTP daemon that does OPIE. The small and simple BSD ftpd(8)
  was deliberately chosen over the wuarchive ftpd(8) because we didn't have 
  the time needed to convince ourselves that the wuarchive ftpd(8) didn't have
  any security holes lurking in its many extra features.

* By default, the "su" binary always gives you an OPIE challenge, even on the   
  console. This was a hole for rlogin/telnet sessions in the original S/Key 
  software.

* MD5 support. MD5 is now the default algorithm, though MD4 is still supported
  by changing a parameter in the Makefile. This change was made because MD5 is
  widely believed to be cryptographically stronger than MD4 (see RFC 1321).

* A more portable version of MD4 has been substituted for the original MD4. 
  This should solve many of the endian problems.

* Most of the system-dependencies have been moved to a new file "opie_cfg.h".

* Configuration options have been moved to the Makefile.

* Isolated system dependencies (e.g. BSDisms) with appropriate #ifdefs.

* Revised the opiekey(1) program to simultaneously support MD4 and MD5, with
  the default algorithm being tunable using the MDX symbol in the Makefile.

* More operating systems are supported by NRL OPIE as of Release 2, but older
  BSD systems that aren't close to being compliant with the POSIX standard are
  no longer supported.

* Transition mechanisms are optional to prevent potential back doors.

* On systems using the /etc/opieaccess transition mechanism, users can choose
  to require the use of OPIE to login to their accounts when it would 
  otherwise be optional.

* Bug fixes

* Cosmetic changes

* Changes to mostly conform with the draft Internet OTP standard.

	Additional modifications from Marcus J. Ranum <mjr@tis.com> are
included in this distribution but are commented out by default or are
protected by "#ifdef MJR" (which is undefined by default). Ranum's changes
are described in the README.MJR file included in this distribution. To
enable those changes, add "-DMJR" to the CFLAGS in the Makefile. NRL has not
tested the changes from Marcus Ranum, and they may need further modification
on some systems. Please consult with him directly if you have questions
about his modifications.

System Requirements
===================

        In order to build and run properly, OPIE requires:

        * A UNIX-like operating system
        * An ANSI C compiler and run-time library
        * POSIX.1- and X/Open XPG-compliance for both (including termios)
        * The BSD sockets API
        * Approximately five megabytes of free disk space

        In practice, we believe that many systems who are close to meeting
these requirements but aren't completely there (for example, SunOS with the
native compiler) will also work. Systems who aren't anywhere near close
(for example, DOS) are not likely to work without major adjustments to the
OPIE code.

Tested Configurations
=====================

	We have tested OPIE on the following platforms:

Hardware		Software		Referred to as	   System
--------		----------------	--------------	   ---------
Sun SPARCStation 20	Solaris 2.4+SunPro C	Solaris		   solaris
Sun 4/300		SunOS 4.1.3+GNU C	SunOS		   sunos
Sun SPARCStation 2	4.4BSD-Encumbered	4.4BSD		   44bsd
486/66 PC		BSDI BSD/OS 1.1	& 2.0	BSD/OS		   bsdos
486/66 PC		Slackware Linux 2.1	Linux		   linux
SGI Indigo^2		IRIX 5.2		IRIX		   irix
HP 9000/750		HP-UX 9.01		HP-UX9		   hpux9
HP 9000/755		HP-UX 10.0		HP-UX10		   hpux10
IBM RS/6000 550		AIX 3.2.5		AIX		   aix

	Additionally, we have recieved information from beta testers from
which we believe OPIE to work on the following additional platforms:

Hardware		Software		Referred to as     System
--------		----------------	--------------	   ---------
486 PC			FreeBSD			FreeBSD		   freebsd
486 PC			NetBSD			NetBSD		   netbsd
Macintosh IIfx          A/UX 3.0                A/UX               aux

	If your system is close to one on this list, you can probably select
the values in the Makefile identified by the "Referred to as" name as
working defaults.

If OPIE Doesn't Work
====================

	If you have installed the OPIE software (either through "make test"
in (7) above or "make install" in (14)), you can run "make uninstall" from the
OPIE software distribution directory. This should remove the OPIE software and
restore the original system programs, but it will not work properly (and can
even result in the total loss of the old system programs -- beware!) if the
installation procedure itself did not work properly.

	NRL OPIE is NOT supported software. We don't promise to support you or
even to acknowledge your mail, but we are interested in bug reports and are
reasonable folks. We also have an interest in seeing OPIE work on as many
systems as we can. However, if your system doesn't meet the basic requirements
for OPIE, this will probably require an unreasonable amount of effort.

	The best bug reports include a diagnosis of the problem and a fix. 
Your bug report can still be valuable if you can at least diagnose what the 
problem is. If you just tell us "it doesn't work", then we won't be able to do
anything to help you.

	Bug reports should be sent by Internet electronic mail to 
<opie-bugs@itd.nrl.navy.mil>. Please include the following information:

* Your name and electronic mail address, in case we need more information.

* Your exact system manufacturer, operating system name (please be more 
  specific than "UNIX" -- most vendors have a name for their particular flavor
  of UNIX), and full version number.

* The exact hardware the system was installed upon.

* Which compiler you used and its version number.

* A clear description of what you did and what bug then appeared.

	If you can provide any of the following things, it will greatly assist
us in fixing the problem and improve the chances that we'll get back to you:

* A diagnosis of what is causing the problem.

* A test case that can repeatably demonstrate the problem.

* A fix for the problem (context diffs are our preferred format).

Thanks!

Gotchas
=======

	While an almost universal "feature", most people remain unaware that
an intruder can log into a system, then log in again by running the "login"
command from a shell. Because the second login is from the local host, the
utmp entry will not show a remote login host anymore. The OPIE replacement
for /bin/login currently carries on this behavior for compatibility reasons.
If you would like to prevent this from happenning, you should change the
permissions of /bin/login from 4511 to 0500, thus preventing unpriveleged
users from executing it. This fix should work on non-OPIE /bin/login programs
as well.

	On 4.3BSDish systems, the supplied /bin/login replacement obtains
the terminal type for the console comes from the console line in the /etc/ttys
file. Several systems contain a default entry in this file that specifies the
console terminal type as "unknown". This is probably not what you want.

	The OPIE FTP daemon responds with two 530 error messages if you have 
not yet logged in and execute a command that will also do a PORT request. This 
is a feature, not a bug, as the FTP client is really sending the server two 
commands (for instance, a PORT and a LIST if you tell your BSD FTP client to do
a DIR command) and the server is responding to each of them with an error. The
stock BSD FTP daemon doesn't check the PORT commands to see if you are logged 
in, so you would only get one error message. This change should not break any
standards-compliant FTP client, but there are a number of brain-damaged GUI
clients that have a track record for not dealing gracefully with any server
other than the stock BSD one.

	The /etc/opieaccess transition mechanism is, by definition, a security
hole in the OPIE software because an attacker could use it to circumvent the
requirement for OPIE authentication. You should compile the software with
support for this file disabled unless you absolutely cannot use the software
without it because of your environment. If you do use this support for
transition purposes, you should move people to OTP authentication as quickly
as possible and rebuild and reinstall OPIE with this transition support
disabled so that you won't have a lurking security hole.

        If this wasn't already clear, do not let your sequence number fall
below about five. If your sequence number reaches zero, your OTP sequence
can only be reset by the superuser. System administrators should make this
caveat known to their users.

	On Solaris 2.x systems (and possibly others) running NIS+, users
should run keylogin(1) manually after login because opielogin(1) does not
do that automatically like the system login(1) program.

	There are reports that some versions of GNU C Compiler (GCC)
(when installed on some systems) use their own termios(4) instead of
the system's termios(4).  This can cause problems.  If you are having
compilation problems that seem to relate to termios and you are using
GCC, you should probably verify that it is using the system's
termios(4) and not some internal-to-GCC termios(4).  One report
indicates that Sun's C compiler works fine with SunOS 4.1.3/4.1.4 on
SPARC, but that some version of GCC on the same system has this
termios(4) problem.  We haven't reproduced these problems ourselves
and hence aren't sure what is happening, but we pass this along for
your information.

Credits
=======

	First and foremost credit goes to Phil Karn, Neil M. Haller, and John
S. Walden of Bellcore for creating the S/Key Version 1 software distribution
and for making its source code freely available to the public. Without their
work, OPIE would not exist.

	The first NRL OPIE distribution included modifications made primarily 
by Dan McDonald <danmcd@itd.nrl.navy.mil> of the U.S. Naval Research 
Laboratory (NRL) during March 1994. The 2nd NRL OPIE distribution, which has a
number of improvements in areas such as portability of software and ease of 
installation, is primarily the work of Ran Atkinson <atkinson@itd.nrl.navy.mil>
and Craig Metz <cmetz@itd.nrl.navy.mil>. Other NRL contributors include Brian 
Adamson <adamson@itd.nrl.navy.mil>, Steve Batsell <batsell@itd.nrl.navy.mil>,
Preston Mullen <mullen@itd.nrl.navy.mil>, Bao Phan <phan@itd.nrl.navy.mil>,
Jim Ramsey <ramsey@itd.nrl.navy.mil>, and Georg Thomas 
<thomas@itd.nrl.navy.mil>. Besides making a number of valuable suggestions and
pointing out a major bug in the software, some fixes to the FTP daemon were
integrated from the wu-ftpd 2.4 fix kit by "Hobbit" <hobbit@avian.org>.
Last, but certainly not least, Wietse Venema <wietse@wzv.win.tue.nl> helped
keep us honest by pointing out several potential security holes in the beta
test version of OPIE 2.0.

	For OPIE 2.01, we would like to also thank John Perkins,
<johnp@zebu.heurikon.com>, Martijn Koster, Lawrie Brown 
<Lawrie.Brown@adfa.oz.au>, and everyone else who reported bugs to opie-bugs.
Without your help, we couldn't squash them for OPIE 2.01.

	This work was sponsored by the Information Security Program
Office (PD 71E), U.S. Space and Naval Warfare Systems Command, Crystal City,
Virginia.

Trademarks
==========
S/Key is a trademark of Bell Communications Research (Bellcore).
UNIX is a trademark of X/Open.
NRL is a trademark of the U. S. Naval Research Laboratory.

All other trademarks are trademarks of their respective owners.

The term "OPIE" is in the public domain and hence cannot be legally 
trademarked by anyone.

Copyrights
==========
Portions of this software are Copyright 1995 by Randall Atkinson and Dan
McDonald, All Rights Reserved. All Rights under this copyright are assigned
to the U.S. Naval Research Laboratory (NRL). The NRL Copyright Notice and
License Agreement applies to this software.

Portions of this software are copyright 1980-1990 Regents of the
University of California, all rights reserved. The Berkeley Software
License Agreement specifies the terms and conditions for redistribution.

Portions of this software are copyright 1990 Bell Communications
Research (Bellcore), all rights reserved.
