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