README revision 22347
1OPIE Software Distribution, Release 2.3 Important Information 2======================================= ===================== 3 4Introduction 5============ 6 7 "One-time Passwords In Everything" (OPIE) is a freely distributable 8software package originally developed at and for the US Naval Research 9Laboratory (NRL). Recent versions are the result of a cooperative effort 10between of NRL, several of the original NRL authors, The Inner Net, and many 11other contributors from the Internet community. 12 13 OPIE is an implementation of the One-Time Password (OTP) System that 14is being considered for the Internet standards-track. OPIE provides a one-time 15password system. The system should be secure against the passive attacks 16now commonplace on the Internet (see RFC 1704 for more details). The system 17is vulnerable to active dictionary attacks, though these are not widespread 18at present and can be detected through proper use of system audit 19software. 20 21 OPIE is primarily written for UNIX-like operating systems, but 22we are working to make applicable portions portable to other operating systems. 23The OPIE software is derived in part from and is fully interoperable with the 24Bell Communications Research (Bellcore) S/Key Release 1 software. Because 25Bellcore claims "S/Key" as a trademark for their software, NRL was forced to 26use a different name (we picked "OPIE") for this software distribution. 27 28 OPIE includes the following additions/modifications to the 29original 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 75A Glance at What's New 76====================== 77 78 2.3 September 22, 1996 79 80 Autoconf is now the only supported configuration method. 81 82 Lots of internal functions got re-written in ways that will make some 83planned future changes easier. 84 85 OTP extended responses, such as automatic re-initialization. 86 87 Support for a supplemental key file that stores information that was 88not in the original /etc/skeykeys file. This allows OPIE to store extra data 89needed for things like the OTP re-initialization extended response without 90breaking interoperability with other S/Key derived programs. This file is 91named "/etc/opiekeys.ext" by default. Unlike the standard key file, it MUST 92NOT be world readable. 93 94 OPIE should better support some of the native "features" of drain 95bamaged OSs such as AIX, HP-UX, and Solaris. 96 97 OPIE's utmp/wtmp handling has been completely re-written. This should 98solve many of the utmp/wtmp problems people have been having. 99 100 Lots of cleanups. 101 102 Bug fixes. 103 104 2.22 May 3, 1996. 105 106 More minor bug fixes. OPIE once again works on Solaris 2.x. 107 108 2.21 April 27, 1996. 109 110 Minor bug fixes. 111 112 2.2 April 11, 1996. 113 114 opiesubr.c, opiesubr2.c, and a few other functions moved into 115a subdirectory and split into files with fine granularity. Ditto with 116missing function replacements. This subdirectory structure changes a lot 117of things around and more splitting like this should be expected in the 118near future. 119 120 Added opiegenerator() library function that should make it very easy 121to create OTP clients using the OPIE library (this function is subject to 122change: there are a few problems remaining to be solved). Just about re-write 123opiegetpass() to use raw I/O and got most of the OPIE programs actually using 124that function. Autoconf build fixes. Lots of bug fixes. Lots of portability 125fixes. Function declarations should be ANSI style for ANSI compilers. Several 126fixes to bring OPIE in line with the latest OTP spec. MJR DES key crunch 127de-implemented. 128 129 Added sample programs: opiegen (client) and opieserv (server). 130 131 Probably broke non-autoconf support along the way :(. I've tried to 132bring this back in sync, but it may still be broken. 133 134 2.11 December 27, 1995. 135 136 Minor bug fixes. 137 138 2.10 December 26, 1995. 139 140 Optional autoconf support. opieinfo is now a normal program. 141Bugs fixed -- should work much better on SunOS, HP-UX, and AIX. 142 143System Requirements 144=================== 145 146 In order to build and run properly, OPIE requires: 147 148 * A UNIX-like operating system 149 * An ANSI C compiler and run-time library 150 * POSIX.1- and X/Open XPG-compliance (including termios) 151 * The BSD sockets API 152 * Approximately five megabytes of free disk space 153 154 In practice, we believe that many systems who are close to meeting 155these requirements but aren't completely there (for example, SunOS with the 156native compiler) will also work. Systems who aren't anywhere near close 157(for example, DOS) are not likely to work without major adjustments to the 158OPIE code. 159 160If OPIE Doesn't Work 161==================== 162 163 First and foremost, make sure you have the latest version of OPIE. The 164latest version is available by anonymous FTP at: 165 166 ftp://ftp.nrl.navy.mil/pub/security/opie 167 and 168 ftp://ftp.inner.net/pub/opie 169 170 If you have installed the OPIE software (either through "make test" 171in (7) above or "make install" in (14)), you can run "make uninstall" from the 172OPIE software distribution directory. This should remove the OPIE software and 173restore the original system programs, but it will not work properly (and can 174even result in the total loss of the old system programs -- beware!) if the 175installation procedure itself did not work properly. 176 177 OPIE is NOT supported software. We don't promise to support you or 178even to acknowledge your mail, but we are interested in bug reports and are 179reasonable folks. We also have an interest in seeing OPIE work on as many 180systems as we can. However, if your system doesn't meet the basic requirements 181for OPIE, this will probably require an unreasonable amount of effort. 182 183 The best bug reports include a diagnosis of the problem and a fix. 184Your bug report can still be valuable if you can at least diagnose what the 185problem is. If you just tell us "it doesn't work," then we won't be able to 186do anything to help you. 187 188 We've received a number of bug reports from people that look 189interesting, only to find when we try to follow up on them that the user 190either has an invalid return address or never bothered to respond to our 191followup. Please make sure that bug reports you send us have an electronic 192mail address that we can reply to somewhere in them (if necessary, just 193put it in the message body). If we send you a response and you are unable 194to invest the time to work with us to solve the problem, please tell us -- 195few things are more irritating than when someone sends us information 196about a bug that we'd like to fix and then is never heard from again. 197 198 We try to respond to all properly submitted bug reports. Improperly 199submitted bug reports will be responded to only if we have time left after 200responding to properly submitted bug reports. We deliberately ignore bug 201"reports" sent to mailing lists or USENET news groups instead of or before 202our bug report address. At the least, the latter practice is lacking in 203courtesy. 204 205 The file BUG-REPORT contains our bug reporting form. Please use it 206and follow the submission instructions in that file. We are going to switch 207to machine-parsed bug report processing sometime in the near future to make 208it easier to coordinate bug hunting. 209 210Gotchas 211======= 212 213 While an almost universal "feature", most people remain unaware that 214an intruder can log into a system, then log in again by running the "login" 215command from a shell. Because the second login is from the local host, the 216utmp entry will not show a remote login host anymore. The OPIE replacement 217for /bin/login currently carries on this behavior for compatibility reasons. 218If you would like to prevent this from happening, you should change the 219permissions of /bin/login to 0100, thus preventing unprivileged users from 220executing it. This fix should work on non-OPIE /bin/login programs as well. 221 222 On 4.3BSDish systems, the supplied /bin/login replacement obtains 223the terminal type for the console comes from the console line in the /etc/ttys 224file. Several systems contain a default entry in this file that specifies the 225console terminal type as "unknown". This is probably not what you want. 226 227 The OPIE FTP daemon responds with two 530 error messages if you have 228not yet logged in and execute a command that will also do a PORT request. This 229is a feature, not a bug, as the FTP client is really sending the server two 230commands (for instance, a PORT and a LIST if you tell your BSD FTP client to do 231a DIR command) and the server is responding to each of them with an error. The 232stock BSD FTP daemon doesn't check the PORT commands to see if you are logged 233in, so you would only get one error message. This change should not break any 234standards-compliant FTP client, but there are a number of brain-damaged GUI 235clients that have a track record for not dealing gracefully with any server 236other than the stock BSD one. 237 238 The /etc/opieaccess transition mechanism is, by definition, a security 239hole in the OPIE software because an attacker could use it to circumvent the 240requirement for OPIE authentication. You should compile the software with 241support for this file disabled unless you absolutely cannot use the software 242without it because of your environment. If you do use this support for 243transition purposes, you should move people to OTP authentication as quickly 244as possible and rebuild and reinstall OPIE with this transition support 245disabled so that you won't have a lurking security hole. 246 247 If this wasn't already clear, do not let your sequence number fall 248below about ten. If your sequence number reaches zero, your OTP sequence 249can only be reset by the superuser. System administrators should make this 250caveat known to their users. 251 252 On Solaris 2.x systems (and possibly others) running NIS+, users 253should run keylogin(1) manually after login because opielogin(1) does not 254do that automatically like the system login(1) program. 255 256 There are reports that some versions of GNU C Compiler (GCC) 257(when installed on some systems) use their own termios(4) instead of 258the system's termios(4). This can cause problems. If you are having 259compilation problems that seem to relate to termios and you are using 260GCC, you should probably verify that it is using the system's 261termios(4) and not some internal-to-GCC termios(4). One report 262indicates that Sun's C compiler works fine with SunOS 4.1.3/4.1.4 on 263SPARC, but that some version of GCC on the same system has this 264termios(4) problem. We haven't reproduced these problems ourselves 265and hence aren't sure what is happening, but we pass this along for 266your information. (This may have something to do with the use of GNU 267libc) 268 269 If a user has a valid entry in the opiekeys database but has an 270asterisk in their traditional password entry, they will not be able to 271log in via opielogin, but opielogin will decrement their sequence number 272if a valid response is received. 273 274 On some systems, the OPIE login program does not always display 275a "login:" prompt the first time. We think that this has something to do 276with the telnet daemon on those systems. (This is common on SunOS) You should 277be able to fix this by upgrading to the latest version of telnetd. 278 279 The standard HPUX compiler is severely drain bamaged. One of the 280worst parts is that it sometimes won't grok a symbol definition with forward 281slashes in them properly and can choke badly on the definition of the key 282file's location. If this happens to you, install and use GCC. (This problem 283may or may not also come up with the optional HP ANSI C compiler -- we don't 284know for sure what compilers have this problem). 285 286 As of OPIE 2.2, the seed is converted to lower case and its length is 287checked in order to comply with the OTP specification. If any of your users 288have seeds that use capital letters or are too long, they need to run the OPIE 2892.2 opiepasswd program to re-initialize their sequence to one with a different 290seed. 291 292 opielogin is a replacement for /bin/login. It is NOT an OPIE "shell." 293You can use it as one, but don't be surprised if it doesn't behave the way 294you expect. An OPIE "shell" is on the TODO list. 295 296 Clients that use opiegen() will automatically send a re-initialization 297extended response if the sequence number falls below ten. If the server does 298not support this, the user will need to log in using opiekey and reset his 299sequence manually (using opiepasswd). 300 301Gripes 302====== 303 304 Is it too much to ask that certain OS vendors just do the right thing 305and not fix what isn't broken? (Look at all the ifdefs in the OPIE code and 306the answer is clear) 307 308Credits 309======= 310 311 First and foremost credit goes to Phil Karn, Neil M. Haller, and John 312S. Walden of Bellcore for creating the S/Key Version 1 software distribution 313and for making its source code freely available to the public. Without their 314work, OPIE would not exist. Neil has also invested a good amount of his time 315in the development of a standard for One-Time Passwords so that packages like 316OPIE can interoperate. 317 318 The first NRL OPIE distribution included modifications made primarily 319by Dan McDonald of the U.S. Naval Research Laboratory (NRL) during March 1994. 320The 2nd NRL OPIE distribution, which has a number of improvements in areas 321such as portability of software and ease of installation, is primarily the 322work of Ran Atkinson and Craig Metz. Other NRL contributors include Brian 323Adamson, Steve Batsell, Preston Mullen, Bao Phan, Jim Ramsey, and Georg Thomas. 324 325 Some of version 2.2 was developed at NRL and released as a work in 326progress. Most of the release version was developed by Craig Metz (also of 327NRL), others at The Inner Net, and contributors from the Internet community. 328Versions beyond 2.2 were developed outside NRL, so don't blame them if they 329don't work (But please credit them when it does. Without the NRL effort, there 330wouldn't be an OPIE). 331 332 We would like to also thank everyone who helped us by by beta testing, 333reporting bugs, suggesting improvements, and/or sending us patches. We 334appreciate your contributions -- they have helped to make OPIE more of a 335community effort. These contributors include: 336 337 Mowgli Assor 338 Lawrie Brown 339 Axel Grewe 340 "Hobbit" 341 Darren Hosking 342 Martijn Koster 343 Osamu Kurati 344 Ayamura Kikuchi 345 Ikuo Nakagawa 346 Angelo Neri 347 D. Jason Penney 348 John Perkins 349 Jim Simmons 350 Werner Wiethege 351 Wietse Venema 352 353 OPIE development at NRL was sponsored by the Information Security 354Program Office (PD 71E), U.S. Space and Naval Warfare Systems Command, Crystal 355City, Virginia. 356 357 If you have problems with OPIE, please follow the instructions under 358"If OPIE Doesn't Work." Under NO circumstances should you send trouble 359reports directly to the authors or contributors. 360 361Trademarks 362========== 363S/Key is a trademark of Bell Communications Research (Bellcore). 364UNIX is a trademark of X/Open. 365NRL is a trademark of the U. S. Naval Research Laboratory. 366 367All other trademarks are trademarks of their respective owners. 368 369The term "OPIE" is in the public domain and hence cannot be legally 370trademarked by anyone. 371 372Copyrights 373========== 374%%% portions-copyright-cmetz 375Portions of this software are Copyright 1996 by Craig Metz, All Rights 376Reserved. The Inner Net License Version 2 applies to these portions of 377the software. 378You should have received a copy of the license with this software. If 379you didn't get a copy, you may request one from <license@inner.net>. 380 381Portions of this software are Copyright 1995 by Randall Atkinson and Dan 382McDonald, All Rights Reserved. All Rights under this copyright are assigned 383to the U.S. Naval Research Laboratory (NRL). The NRL Copyright Notice and 384License Agreement applies to this software. 385 386Portions of this software are copyright 1980-1990 Regents of the 387University of California, all rights reserved. The Berkeley Software 388License Agreement specifies the terms and conditions for redistribution. 389 390Portions of this software are copyright 1990 Bell Communications Research 391(Bellcore), all rights reserved. 392