Merge branch 'vendor/OPENSSL'
[dragonfly.git] / contrib / opie / README
1 OPIE Software Distribution, Release 2.4                   Important Information
2 =======================================                   =====================
3
4 Introduction
5 ============
6
7         "One-time Passwords In Everything" (OPIE) is a freely distributable
8 software package originally developed at and for the US Naval Research
9 Laboratory (NRL). Recent versions are the result of a cooperative effort
10 between of NRL, several of the original NRL authors, The Inner Net, and many
11 other contributors from the Internet community.
12
13         OPIE is an implementation of the One-Time Password (OTP) System that
14 is being considered for the Internet standards-track. OPIE provides a one-time
15 password system. The system should be secure against the passive attacks
16 now commonplace on the Internet (see RFC 1704 for more details). The system
17 is vulnerable to active dictionary attacks, though these are not widespread
18 at present and can be detected through proper use of system audit
19 software. 
20
21         OPIE is primarily written for UNIX-like operating systems, but
22 we are working to make applicable portions portable to other operating systems.
23 The OPIE software is derived in part from and is fully interoperable with the
24 Bell Communications Research (Bellcore) S/Key Release 1 software. Because
25 Bellcore claims "S/Key" as a trademark for their software, NRL was forced to
26 use a different name (we picked "OPIE") for this software distribution.
27
28         OPIE includes the following additions/modifications to the
29 original Bellcore S/Key(tm) Version 1 software:
30
31 * Just about three command installation (unpack the software, run the
32   configure script, and run make install). While we still recommend that you
33   follow instructions and test things by hand, the more adventurous can
34   install OPIE quickly.
35
36 * A modified BSD FTP daemon that does OTP.
37
38 * A version of su that uses OTP by default. 
39
40 * MD5 support. MD5 is now the default algorithm, though MD4 is still supported
41   by changing a parameter in the Makefile. This change was made because MD5 is
42   widely believed to be cryptographically stronger than MD4 (see RFC 1321).
43
44 * A more portable version of MD4 has been substituted for the original MD4. 
45   This should solve the endian problems that were in S/Key.
46
47 * Most of the system-dependencies have been moved to a new file "opie_cfg.h".
48
49 * Configuration options have been moved to the Makefile.
50
51 * Isolated system dependencies (e.g. BSDisms) with appropriate #ifdefs.
52
53 * Revised the opiekey(1) program to simultaneously support MD4 and MD5, with
54   the default algorithm being tunable using the MDX symbol in the Makefile.
55
56 * More operating systems are supported by recent versions of OPIE, but older
57   BSD systems that aren't close to being compliant with the POSIX standard are
58   no longer supported.
59
60 * Transition mechanisms are optional to prevent potential back doors.
61
62 * On systems using the /etc/opieaccess transition mechanism, users can choose
63   to require the use of OPIE to login to their accounts when it would 
64   otherwise be optional.
65
66 * Bug fixes
67
68 * Cosmetic changes
69
70 * Prompts (optionally) identify specifically what kind of entry (system
71   password, secret pass phrase, or OTP response) is allowed.
72
73 * Changes to mostly conform with the draft Internet OTP standard.
74
75 A Glance at What's New
76 ======================
77
78     2.4 TEST VERSION -- NOT FOR REDISTRIBUTION
79
80     Merged in opieauto, which is disabled by default.
81
82     Lots of documentation updates.
83
84     Portability and bug fixes.
85
86     2.32 January 1, 1998.
87
88     Indicate support for extended responses in challenges and check for such
89 indication before generating any extended responses.
90
91     Lots of portability and bug fixes.
92
93     2.31 March 20, 1997.
94
95     Removed active attack protection support due to patent problems.
96
97     Removed the supplemental key file; it did more harm than good.
98
99     Moved user locks to a separate directory.
100
101     Moved user-serviceable configuration options to the configure script.
102
103     Lots of portability and bug fixes.
104
105     2.3 September 22, 1996
106
107     Autoconf is now the only supported configuration method.
108
109     Lots of internal functions got re-written in ways that will make some
110 planned future changes easier.
111
112     OTP extended responses, such as automatic re-initialization.
113
114     Support for a supplemental key file that stores information that was not
115 in the original /etc/skeykeys file. This allows OPIE to store extra data needed
116 for things like the OTP re-initialization extended response without breaking
117 interoperability with other S/Key derived programs. This file is named
118 "/etc/opiekeys.ext" by default. Unlike the standard key file, it MUST NOT be
119 world readable.
120
121     OPIE should better support some of the native "features" of drain bamaged
122 OSs such as AIX, HP-UX, and Solaris.
123
124     OPIE's utmp/wtmp handling has been completely re-written. This should solve
125 many of the utmp/wtmp problems people have been having.
126
127     Lots of cleanups.
128
129     Bug fixes.
130
131     2.22 May 3, 1996.
132
133     More minor bug fixes. OPIE once again works on Solaris 2.x.
134
135     2.21 April 27, 1996.
136
137     Minor bug fixes.
138
139     2.2 April 11, 1996.
140
141     opiesubr.c, opiesubr2.c, and a few other functions moved into a
142 subdirectory and split into files with fine granularity. Ditto with missing
143 function replacements. This subdirectory structure changes a lot of things
144 around and more splitting like this should be expected in the near future.
145
146     Added opiegenerator() library function that should make it very easy to
147 create OTP clients using the OPIE library (this function is subject to change:
148 there are a few problems remaining to be solved). Just about re-wrote
149 opiegetpass() to use raw I/O and got most of the OPIE programs actually using
150 that function. Autoconf build fixes. Lots of bug fixes. Lots of portability
151 fixes. Function declarations should be ANSI style for ANSI compilers. Several
152 fixes to bring OPIE in line with the latest OTP spec. MJR DES key crunch
153 de-implemented.
154
155     Added sample programs: opiegen (client) and opieserv (server).
156
157     Probably broke non-autoconf support along the way :(. I've tried to bring
158 this back in sync, but it may still be broken.
159
160     2.11 December 27, 1995.
161
162     Minor bug fixes.
163
164     2.10 December 26, 1995.
165
166     Optional autoconf support. opieinfo is now a normal program. Bugs fixed --
167 should work much better on SunOS, HP-UX, and AIX.
168
169     2.01 -- 2.04
170
171     Bug fix releases.
172
173     2.00
174
175     Initial release of OPIE 2.0.
176
177 System Requirements
178 ===================
179
180         In order to build and run properly, OPIE requires:
181
182         * A UNIX-like operating system
183         * An ANSI C compiler and run-time library
184         * POSIX.1- and X/Open XPG-compliance (including termios)
185         * The BSD sockets API
186         * Approximately five megabytes of free disk space
187
188         In practice, we believe that many systems who are close to meeting
189 these requirements but aren't completely there (for example, SunOS with the
190 native compiler) will also work. Systems who aren't anywhere near close
191 (for example, DOS) are not likely to work without major adjustments to the
192 OPIE code.
193
194 If OPIE Doesn't Work
195 ====================
196
197         Under NO circumstances should you send trouble reports directly to the
198 authors or contributors. They WILL BE IGNORED.
199
200         Make sure you have the latest version of OPIE. The latest version is
201 available by HTTP at:
202
203         http://www.inner.net/pub/opie
204
205         (sorry, but anonymous FTP is no longer available)
206
207         If you have installed the OPIE software (either through "make test"
208 in (7) above or "make install" in (14)), you can run "make uninstall" from the
209 OPIE software distribution directory. This should remove the OPIE software and
210 restore the original system programs, but it will not work properly (and can
211 even result in the total loss of the old system programs -- beware!) if the
212 installation procedure itself did not work properly.
213
214         If you are running a release version, try installing the latest public
215 test version (look around). These frequently have already fixed the problem
216 you are seeing, but may have new problems of their own (that's why they're
217 test versions!). Similarly, if you are running a test version, try installing
218 the latest released version.
219
220         OPIE is NOT supported software. We don't promise to support you or
221 even to acknowledge your mail, but we are interested in bug reports and are
222 reasonable folks. We also have an interest in seeing OPIE work on as many
223 systems as we can. However, if your system doesn't meet the basic requirements
224 for OPIE, this will probably require an unreasonable amount of effort.
225
226         The best bug reports include a diagnosis of the problem and a fix. 
227 Your bug report can still be valuable if you can at least diagnose what the 
228 problem is. If you just tell us "it doesn't work," then we won't be able to
229 do anything to help you.
230
231         We've received a number of bug reports from people that look
232 interesting, only to find when we try to follow up on them that the user
233 either has an invalid return address or never bothered to respond to our
234 followup. Please make sure that bug reports you send us have an electronic
235 mail address that we can reply to somewhere in them (if necessary, just
236 put it in the message body). If we send you a response and you are unable
237 to invest the time to work with us to solve the problem, please tell us --
238 few things are more irritating than when someone sends us information
239 about a bug that we'd like to fix and then is never heard from again.
240
241         We try to respond to all properly submitted bug reports. Improperly
242 submitted bug reports will be responded to only if we have time left after
243 responding to properly submitted bug reports. We deliberately ignore bug
244 "reports" sent to mailing lists or USENET news groups instead of or before
245 our bug report address. At the least, the latter practice is lacking in
246 courtesy.
247
248         The file BUG-REPORT contains our bug reporting form. Please use it
249 and follow the submission instructions in that file. We are going to switch
250 to machine-parsed bug report processing sometime in the near future to make
251 it easier to coordinate bug hunting.
252
253 Gotchas
254 =======
255
256         Solaris 2.x is just a lose. It does a lot of nonstandard and downright
257 broken things. If you want OPIE to be reliable on your box, upgrade to OpenBSD
258 or Linux.
259
260         While an almost universal "feature", most people remain unaware that
261 an intruder can log into a system, then log in again by running the "login"
262 command from a shell. Because the second login is from the local host, the
263 utmp entry will not show a remote login host anymore. The OPIE replacement
264 for /bin/login currently carries on this behavior for compatibility reasons.
265 If you would like to prevent this from happening, you should change the
266 permissions of /bin/login to 0100, thus preventing unprivileged users from
267 executing it. This fix should work on non-OPIE /bin/login programs as well.
268
269         On 4.3BSDish systems, the supplied /bin/login replacement obtains
270 the terminal type for the console comes from the console line in the /etc/ttys
271 file. Several systems contain a default entry in this file that specifies the
272 console terminal type as "unknown". This is probably not what you want.
273
274         The OPIE FTP daemon responds with two 530 error messages if you have 
275 not yet logged in and execute a command that will also do a PORT request. This 
276 is a feature, not a bug, as the FTP client is really sending the server two 
277 commands (for instance, a PORT and a LIST if you tell your BSD FTP client to do
278 a DIR command) and the server is responding to each of them with an error. The
279 stock BSD FTP daemon doesn't check the PORT commands to see if you are logged 
280 in, so you would only get one error message. This change should not break any
281 standards-compliant FTP client, but there are a number of brain-damaged GUI
282 clients that have a track record for not dealing gracefully with any server
283 other than the stock BSD one.
284
285         The /etc/opieaccess transition mechanism is, by definition, a security
286 hole in the OPIE software because an attacker could use it to circumvent the
287 requirement for OPIE authentication. You should compile the software with
288 support for this file disabled unless you absolutely cannot use the software
289 without it because of your environment. If you do use this support for
290 transition purposes, you should move people to OTP authentication as quickly
291 as possible and rebuild and reinstall OPIE with this transition support
292 disabled so that you won't have a lurking security hole.
293
294         If this wasn't already clear, do not let your sequence number fall
295 below about ten. If your sequence number reaches zero, your OTP sequence
296 can only be reset by the superuser. System administrators should make this
297 caveat known to their users.
298
299         On Solaris 2.x systems (and possibly others) running NIS+, users
300 should run keylogin(1) manually after login because opielogin(1) does not
301 do that automatically like the system login(1) program.
302
303         There are reports that some versions of GNU C Compiler (GCC)
304 (when installed on some systems) use their own termios(4) instead of
305 the system's termios(4).  This can cause problems.  If you are having
306 compilation problems that seem to relate to termios and you are using
307 GCC, you should probably verify that it is using the system's
308 termios(4) and not some internal-to-GCC termios(4).  One report
309 indicates that Sun's C compiler works fine with SunOS 4.1.3/4.1.4 on
310 SPARC, but that some version of GCC on the same system has this
311 termios(4) problem.  We haven't reproduced these problems ourselves
312 and hence aren't sure what is happening, but we pass this along for
313 your information. (This may have something to do with the use of GNU
314 libc)
315
316         If a user has a valid entry in the opiekeys database but has an
317 asterisk in their traditional password entry, they will not be able to
318 log in via opielogin, but opielogin will decrement their sequence number
319 if a valid response is received.
320
321         On some systems, the OPIE login program does not always display
322 a "login:" prompt the first time. There is a race condition in many older
323 telnetds that is probably the cause of this problem. This should be fixed by
324 replacing your telnetd with the latest version of the stock telnetd 
325 (ftp.cray.com:/src/telnet). 
326
327         The standard HPUX compiler is severely drain bamaged. One of the
328 worst parts is that it sometimes won't grok a symbol definition with forward
329 slashes in them properly and can choke badly on the definition of the key
330 file's location. If this happens to you, install and use GCC. (This problem
331 may or may not also come up with the optional HP ANSI C compiler -- we don't
332 know for sure what compilers have this problem).
333
334         As of OPIE 2.2, the seed is converted to lower case and its length is
335 checked in order to comply with the OTP specification. If any of your users
336 have seeds that use capital letters or are too long, they need to run the OPIE
337 2.2 opiepasswd program to re-initialize their sequence to one with a different
338 seed.
339
340         opielogin is a replacement for /bin/login. It is NOT an OPIE "shell."
341 You can use it as one, but don't be surprised if it doesn't behave the way
342 you expect -- we've seen various reports of success and failure when used this
343 way. An OPIE "shell" is on the TODO list.
344
345         Clients that use opiegen() will automatically send a re-initialization
346 extended response if the sequence number falls below ten. If the server does
347 not support this, the user will need to log in using opiekey and reset his
348 sequence manually (using opiepasswd).
349
350         For reasons that remain very unclear, Solaris passes the login name
351 from getty/telnetd to login by stuffing it in the terminal input buffer
352 instead of passing it on the command line like every other *IX. This is just
353 plain broken. Solaris has other problems with its telnetd and getty; you may
354 want to consider getting the telnet(d) sources (ftp.cray.com:/src/telnet)
355 and reasonable getty sources (try sunsite.unc.edu:/pub/Linux/system/Serial, at
356 least one of agetty, mingetty, and getty_ps should work) and replacing the
357 Solaris versions with these. OPIE should work *much* more happily with these
358 programs than the ones that come with Solaris. However, there could be negative
359 side effects -- this is not a procedure recommended for the faint of heart.
360
361         OPIE is a lot more fussy than it used to be about lock files and where
362 it puts them. The lock file directory must be a directory used only for OPIE
363 lock files. It must be a directory, owned by the superuser, and must be mode
364 0700.
365
366         opieauto is a potential security hole. It opens a limited window of
367 exposure by transmitting and storing information that can be used to
368 generate one or more OTPs earlier than the current sequence number. Every
369 effort has been made to limit the potential for compromise to the user-
370 specified window. However, an attacker with superuser priveleges or access to
371 your account on the client system can still generate OTPs based on the
372 information cached via opieauto. In practice, there are other ways for such an
373 an attacker to get your entire secret pass phrase, so this is probably not
374 creating a significant new security problem. However, because of this
375 potential for problems and because opieauto uses system features that are not
376 present on all systems, opieauto support is not compiled in by default and
377 must be specifically enabled at compile time.
378
379         Many users are running OPIE with the key file on a shared NFS volume
380 in order to use OTP as a single-login system for a cluster of machines. OPIE
381 was NOT designed to be operated this way, though it does seem to work. If it
382 fails or if this proves insecure, this is not OPIE's fault. Note that, if you
383 do this, you probably want to share the OPIE lock files too.
384
385 Gripes
386 ======
387
388         Is it too much to ask that certain OS vendors just do the right thing
389 and not "fix" what isn't broken? (Look at all the ifdefs in the OPIE code and
390 the answer is clear)
391
392         utmp and wtmp handling in OPIE has been a very, very sore subject.
393 Every vendor does things differently, and, of course, most of them swear they
394 are complying to some or other "standard." My (cmetz) conclusion is that the
395 only thing that is standard about utmp and wtmp handling is that it will be
396 nonstandard on any given system. I've tried a lot of things and I've wasted
397 *a lot* of time on trying to make utmp and wtmp handling work for everybody;
398 my conclusion is that it will never happen. While I am still interested in
399 hearing about fixes for utmp/wtmp on systems where they don't work, I'm not
400 likely to go out of my way to fix utmp/wtmp handling. If you want it fixed,
401 the best way to do it is to fix it yourself and contribute a patch. As long as
402 the patch is reasonable, it will be included in the next release. If you can't
403 wait, use the --disable-utmp option.
404
405 Credits
406 =======
407
408         First and foremost credit goes to Phil Karn, Neil M. Haller, and John
409 S. Walden of Bellcore for creating the S/Key Version 1 software distribution
410 and for making its source code freely available to the public. Without their
411 work, OPIE would not exist. Neil has also invested a good amount of his time 
412 in the development of a standard for One-Time Passwords so that packages like
413 OPIE can interoperate.
414
415         The first NRL OPIE distribution included modifications made primarily 
416 by Dan McDonald of the U.S. Naval Research Laboratory (NRL) during March 1994.
417 The 2nd NRL OPIE distribution, which has a number of improvements in areas
418 such as portability of software and ease of installation, is primarily the
419 work of Ran Atkinson and Craig Metz. Other NRL contributors include Brian 
420 Adamson, Steve Batsell, Preston Mullen, Bao Phan, Jim Ramsey, and Georg Thomas.
421
422         Some of version 2.2 was developed at NRL and released as a work in
423 progress. Most of the release version was developed by Craig Metz (also of
424 NRL), others at The Inner Net, and contributors from the Internet community.
425 Versions beyond 2.2 were developed outside NRL, so don't blame them if they
426 don't work (But please credit them when it does. Without the NRL effort, there
427 wouldn't be an OPIE).
428
429         We would like to also thank everyone who helped us by by beta testing,
430 reporting bugs, suggesting improvements, and/or sending us patches. We
431 appreciate your contributions -- they have helped to make OPIE more of a
432 community effort. These contributors include:
433
434         Mowgli Assor
435         Lawrie Brown
436         Andrew Davis
437         Taso N. Devetzis
438         Carson Gaspar
439         Dennis Glatting
440         Ben Golding
441         Axel Grewe
442         "Hobbit"
443         Kojima Hajime
444         Darren Hosking
445         Matt Hucke
446         Kenji Kamizono
447         Charles Karney
448         Jeff Kletsky
449         Peter Koch
450         Martijn Koster
451         Osamu Kurati
452         Ayamura Kikuchi
453         Ronald van der Meer
454         Bret Musser
455         Hiroshi Nakano
456         Ikuo Nakagawa
457         Angelo Neri
458         C. R. Oldham
459         Ossama Othman
460         D. Jason Penney
461         John Perkins
462         Steve Price
463         Jim Simmons
464         Steve Simmons
465         Brad Smith
466         Werner Wiethege
467         Ken-ichi Yamasaki
468         Wietse Venema
469
470         OPIE development at NRL was sponsored by the Information Security
471 Program Office (PD 71E), U.S. Space and Naval Warfare Systems Command, Crystal
472 City, Virginia.
473
474         If you have problems with OPIE, please follow the instructions under
475 "If OPIE Doesn't Work." Under NO circumstances should you send trouble
476 reports directly to the authors or contributors. They WILL BE IGNORED.
477
478 Trademarks
479 ==========
480 S/Key is a trademark of Bell Communications Research (Bellcore).
481 UNIX is a trademark of X/Open.
482 NRL is a trademark of the U. S. Naval Research Laboratory.
483
484 All other trademarks are trademarks of their respective owners.
485
486 The term "OPIE" is in the public domain and hence cannot be legally 
487 trademarked by anyone. Please do not abuse it.
488
489 Copyrights
490 ==========
491 %%% portions-copyright-cmetz-96
492 Portions of this software are Copyright 1996-1999 by Craig Metz, All Rights
493 Reserved. The Inner Net License Version 2 applies to these portions of
494 the software.
495 You should have received a copy of the license with this software. If
496 you didn't get a copy, you may request one from <license@inner.net>.
497
498 Portions of this software are Copyright 1995 by Randall Atkinson and Dan
499 McDonald, All Rights Reserved. All Rights under this copyright are assigned
500 to the U.S. Naval Research Laboratory (NRL). The NRL Copyright Notice and
501 License Agreement applies to this software.
502
503 Portions of this software are copyright 1980-1990 Regents of the
504 University of California, all rights reserved. The Berkeley Software
505 License Agreement specifies the terms and conditions for redistribution.
506
507 Portions of this software are copyright 1990 Bell Communications Research
508 (Bellcore), all rights reserved.