Initial import of OPIE v2.3 from

	ftp://ftp.nrl.navy.mil/pub/security/opie/

1 files changed, 346 insertions, 0 deletions

diff --git a/contrib/opie/opie.4 b/contrib/opie/opie.4
new file mode 100644
index 0000000..97eb73d
--- /dev/null
+++ b/contrib/opie/opie.4
@@ -0,0 +1,346 @@
+.\" opie.4: Overview of the OPIE software.
+.\"
+.\" %%% portions-copyright-cmetz
+.\" Portions of this software are Copyright 1996 by Craig Metz, All Rights
+.\" Reserved. The Inner Net License Version 2 applies to these portions of
+.\" the software.
+.\" You should have received a copy of the license with this software. If
+.\" you didn't get a copy, you may request one from <license@inner.net>.
+.\"
+.\" 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.
+.\"
+.\"	History:
+.\"
+.\"     Modified by cmetz for OPIE 2.2. Removed MJR DES documentation. Removed
+.\"         references to the old square brackets challenge delimiters.
+.\"     Modified at NRL for OPIE 2.01. Updated UNIX trademark credit.
+.\"	Definition of "seed" written by Neil Haller of Bellcore
+.\"	Written at NRL for OPIE 2.0.
+.\"
+.TH OPIE 4 "January 10, 1995"
+.SH NAME
+.B OPIE \- One-time Passwords In Everything
+.SH DESCRIPTION
+.LP
+OPIE is a package derived from the Bellcore S/Key Version 1 distribution
+that helps to secure a system against replay attacks (see below). It does so
+using a secure hash function and a challenge/response system. It provides
+replacements for the 
+.IR login (1),
+.IR su (1), 
+and 
+.IR ftpd (8) 
+programs that use OPIE
+authentication as well as demonstrate how a program might be adapted to use
+OPIE authentication. OPIE was developed at and for the United States Naval
+Research Laboratory (NRL). OPIE is derived in part from Berkeley Standard
+Distribution UNIX and the Bellcore S/Key Version 1 distribution.
+.LP
+From the average user's perspective, OPIE is a nuisance that prevents their
+account from being broken into. The first time a user wishes to use OPIE,
+(s)he needs to use the 
+.IR opiepasswd (1) 
+command to put an entry for them into
+the OPIE database. The user can then use OPIE to authenticate themselves
+with any program that supports it. If no other clients are being used,
+this means they can use OPIE to 
+.I telnet,
+.I rlogin, 
+or 
+.I ftp
+into the system,
+log in on a terminal port (like a modem), or switch to another user's
+account. When they would normally be asked for a password, they will get
+a challenge from the server. They then need to copy that challenge (or
+re-type, if they don't have the ability to copy and paste through something
+like a window system) to their calculator program, enter their password,
+then copy (or re-type) the response from the calculator as their password.
+While this will seem cumbersome at first, with some practice, it becomes
+easy.
+
+.SH TERMS
+.TP 
+.I user name
+The name that the system knows you as. For example, "jdoe".
+.TP
+.I secret password
+A password, usually selected by the user, that is needed to gain access to the 
+system. For example, "SEc1_rt".
+.TP
+.I challenge
+A packet of information output by a system when it wishes to authenticate a 
+user. In OPIE, this is a three-item group consisting of a hash identifier,
+a sequence number, and a seed. This 
+information is needed by the OPIE calculator to generate a proper response. 
+For example, "otp-md5 95 wi14321".
+.TP
+.I response
+A packet of information generated from a challenge that is used by a system to 
+authenticate a user. In OPIE, this is a group of six words that is generated by
+the calculator given the challenge and the secret password. For example, 
+"PUP SOFT ROSE BIAS FLAG END".
+.TP
+.I seed
+A piece of information that is used in conjunction with the secret password
+and sequence numer to compute the response. Its purpose is to allow the same
+secret password to be used for multiple sequences, by changing the seed, or
+for authentication to multiple machines by using different seeds.
+.TP
+.I sequence number
+A counter used to keep track of key iterations. In OPIE, each time a successful
+response is received by the system, the sequence number is decremented. For 
+example, "95".
+.TP
+.I hash identifier
+A piece of text that identifies the actual algorithm that needs to be used to 
+generate a proper response. In OPIE, the only two valid hash identifiers are 
+"otp-md4", which selects MD4 hashing, and "otp-md5", which selects MD5.
+
+.SH REPLAY ATTACKS
+When you use a network terminal program like 
+.IR telnet (1)
+or even use a modem to log into a
+computer system, you need a user name and a secret password. Anyone who can 
+provide those to the system is recognized as you because, in theory, only you 
+would have your secret password. Unfortunately, it is now easy to listen in
+on many computer communications media. From modem communication to many 
+networks, your password is not usually safe over remote links. If a
+cracker can listen in when you send your password, (s)he then has a copy
+of your password that can be used at any time in the future to access your
+account. On more than one occasion, major sites on the Internet have been
+broken into exactly this way. 
+.LP
+All an attacker has to
+do is capture your password once and then replay it to the server when it's
+asked for. Even if the password is communicated between machines in encoded
+or encrypted form, as long as a cracker can get in by simply replaying
+a previously captured communication, you are at risk. Up until very recently,
+Novell NetWare was vulnerable this way. A cracker couldn't find out what your
+password actually is, but (s)he didn't need to -- all that was necessary to
+get into your account was to capture the encrypted password and send that
+back to the server when asked for it.
+
+.SH ONE-TIME PASSWORDS
+One solution to the problem of replay attacks
+is to keep changing the way that a password is being encoded so that what is
+sent over the link to another system can only be used once. If you can do that,
+then a cracker can replay it as many times as (s)he wants -- it's just not
+going to get them anywhere. It's important, however, to make sure you encode
+the password in such a way that the cracker can't use the encoded version to
+figure out what the password is or what a future encoded password will be.
+Otherwise, while still an improvement over no encoding or a fixed encoding,
+you can still be broken into. 
+
+.SH THE S/KEY ALGORITHM
+
+A solution to this whole problem was invented by Lamport in 1981. This
+technique was implemented by Haller, Karn, and Walden at Bellcore. They
+They created a free software package called "S/Key" that used an algorithm
+called a cryptographic checksum. A cryptographic checksum is a strong one-way
+function such that, knowing the result of such a function, an attacker still
+cannot feasably determine the input. Further, unlike cyclic redundancy
+checksums (CRCs), cryptographic checksums have few inputs that result in the
+same output.
+.LP
+In S/Key, what changes is the number of
+times the password is run through the secure hash. The password is run through
+the secure hash once, then the output of the hash is run through the secure
+hash again, that output is run through the secure hash again, and so on until
+the number of times the password has been run through the secure hash is equal 
+to the desired sequence number. This is much slower than just, say, putting
+the sequence number in before the password and running that through the secure
+hash once, but it gains you one significant benefit. The server machine you
+are trying to connect to has to have some way to determine whether the output
+of that whole mess is right. If it stores it either without any encoding or
+with a normal encoding, a cracker could still get at your password. But if it
+stores it with a secure hash, then how does it account for the response 
+changing every time because the sequence number is changing? Also what if you 
+can never get to the machine any way that can't be listened in on? How do you
+change your password without sending it over the link?
+.LP
+The clever solution
+devised by Lamport is to keep in mind that the sequence number is
+always decrementing by one and that, in the S/Key system, simply by running any
+response with a sequence number N through the secure hash, you can get the
+response with a sequence number N+1, but you can't go the other way. At any
+given time, call the sequence number of the last valid response that the 
+system got N+1 and the sequence number of the response you are giving it N.
+If the password that generated the response for N is the same as the one for
+N+1, then you should be able to run the response for N through the secure hash
+one more time, for a total of N+1 times, and get the same response as you got
+back for N+1. Once you compare the two and find that they are the same, you
+subtract one from N so that, now, the key for N that you just verified becomes
+the new key for N+1 that you can store away to use the next time you need to
+verify a key. This also means that if you need to change your password but
+don't have a secure way to access your machine, all the system really needs to
+have to verify your password is a valid response for one more than the sequence
+number you want to start with.
+.LP
+Just for good measure, each side of
+all of this uses a seed in conjunction with your password when it actually 
+generates and verifies the responses. This helps to jumble things up a little
+bit more, just in case. Otherwise, someone with a lot of time and disk space
+on their hands could generate all the responses for a lot of frequent passwords
+and defeat the system.
+.LP
+This is not, by any means, the best explanation of how the S/Key algorithm
+works or some of the more minor details. For that, you should go to some of
+the papers now published on the topic. It is simply a quick-and-dirty
+introduction to what's going on under the hood.
+
+.SH OPIE COMPONENTS
+
+Included in the OPIE distribution are three OPIE client programs: 
+.IR opielogin (1),
+.IR opiesu (1), 
+and 
+.IR opieftpd (8). 
+These three programs are modified versions of the
+freely available 4.3BSD Net/2 versions of 
+.IR login (1), 
+.IR su (1), 
+and 
+.IR ftpd (8),
+respectively. Although most of the modifications actually done to them are so
+that they will work on as many machines as possible, they also have been
+modified to support OPIE for authentication. As you will see from the source, 
+it is not very difficult to add support for OPIE to other programs.
+.LP
+There are also three programs in the OPIE distribution that are specific to
+the OPIE system: 
+.IR opiepasswd (1),
+which allows a user to set and change their
+OPIE password, 
+.IR opieinfo (1),
+which allows a user to find out what their current
+sequence number and seed are, and 
+.IR opiekey(1),
+which is an OPIE key calculator.
+
+.LP ADDING OPIE TO OTHER PROGRAMS
+
+Adding OPIE authentication to programs other than the ones included as clients
+in the OPIE distribution isn't very difficult. First, you will need to make
+sure that the program includes <stdio.h> somewhere. Then, below the other
+includes such as <stdio.h>, but before variable declarations, you need to
+include "opie.h". You need to add a variable of type "struct opie" to your
+program, you need to make sure that the buffer that you use to get a password
+from the user is big enough to hold OPIE_RESPONSE_MAX+1 characters, and you
+need to have a buffer in which to store the challenge string that is big enough
+to hold OPIE_PROMPT_MAX+1 characters.
+.LP
+When you are ready to output the challenge string and know the user's name,
+you would use a call to opiechallenge. Later, to verify the response received,
+you would use a call to opieverify. For example:
+.sp 0
+
+.sp 0
+	#include <stdio.h>
+.sp 0
+		.
+.sp 0
+		.
+.sp 0
+	#include "opie.h"
+.sp 0
+		.
+.sp 0
+		.
+.sp 0
+	char *user_name;
+.sp 0
+	/* Always remember the trailing null! */
+.sp 0
+	char password[OPIE_RESPONSE_MAX+1];
+.sp 0
+		.
+.sp 0
+		.
+.sp 0
+	struct opie opiedata;
+.sp 0
+	char opieprompt[OPIE_PROMPT_MAX+1];
+.sp 0
+		.
+.sp 0
+		.
+.sp 0
+	opiechallenge(&opiedata, user_name, &opieprompt);
+.sp 0
+		.
+.sp 0
+		.
+.sp 0
+	if (opieverify(&opiedata, password)) {
+.sp 0
+		printf("Login incorrect");
+.sp 0
+.SH TERMINAL SECURITY AND OPIE
+
+When using OPIE, you need to be careful not to allow your password to be
+communicated over an insecure channel where someone might be able to listen
+in and capture it. OPIE can protect you against people who might get your
+password from snooping on the line, but only if you make sure that the password
+itself never gets sent over the line. The important thing is to always run the
+OPIE calculator on whichever machine you are actually using - never on a machine
+you are connected to by network or by dialup. 
+.LP
+You need to be careful about the
+X Window System, because it changes things quite a bit. For instance, if you
+run an xterm (or your favorite equivalent) on another machine and display it
+on your machine, you should not run an OPIE calculator in that window. When you
+type in your secret password, it still gets transmitted over the network to go
+to the machine the xterm is running on. People with machines such as
+X terminals that can only run the calculator over the network are in an
+especially precarious position because they really have no choice. Also, with
+the X Window System, as with some other window system (NeWS as an example),
+it is sometimes possible for people to read your keystrokes and capture your
+password even if you are running the OPIE calculator on your local machine.
+You should always use the best security mechanism available on your system to
+protect your X server, be it XDM-AUTHORIZATION-1, XDM-MAGIC-COOKIE-1, or host
+access control. *Never* just allow any machine to connect to your server
+because, by doing so, you are allowing any machine to read any of your windows
+or your keystrokes without you knowing it.
+
+.SH SEE ALSO
+.BR opie (4),
+.BR opiekeys (5),
+.BR opieaccess (5),
+.BR opiekey (1),
+.BR opieinfo (1),
+.BR opiepasswd (1),
+.BR opielogin (1),
+.BR opieftpd (8)
+.sp
+Lamport, L. "Password Authentication with Insecure Communication",
+Communications of the ACM 24.11 (November 1981), pp. 770-772.
+.sp
+Haller, N. "The S/KEY One-Time Password System", Proceedings of the ISOC
+Symposium on Network and Distributed System Security, February 1994, 
+San Diego, CA.
+.sp
+Haller, N. and Atkinson, R, "On Internet Authentication", RFC-1704,
+DDN Network Information Center, October 1994.
+.sp
+Rivest, R. "The MD5 Message Digest Algorithm", RFC-1321,
+DDN Network Information Center, April 1992.
+.sp
+Rivest, R. "The MD4 Message Digest Algorithm", RFC-1320,
+DDN Network Information Center, April 1992.
+
+.SH AUTHOR
+Bellcore's S/Key was written by Phil Karn, Neil M. Haller, and John S. Walden
+of Bellcore. OPIE was created at NRL by Randall Atkinson, Dan McDonald, and
+Craig Metz.
+
+S/Key is a trademark of Bell Communications Research (Bellcore).
+UNIX is a trademark of X/Open.
+
+.SH CONTACT
+OPIE is discussed on the Bellcore "S/Key Users" mailing list. To join,
+send an email request to:
+.sp
+skey-users-request@thumper.bellcore.com