Merge branch 'vendor/MDOCML'
[dragonfly.git] / contrib / opie / opie.4
CommitLineData
984263bc
MD
1.\" opie.4: Overview of the OPIE software.
2.\"
3.\" %%% portions-copyright-cmetz-96
4.\" Portions of this software are Copyright 1996-1999 by Craig Metz, All Rights
5.\" Reserved. The Inner Net License Version 2 applies to these portions of
6.\" the software.
7.\" You should have received a copy of the license with this software. If
8.\" you didn't get a copy, you may request one from <license@inner.net>.
9.\"
10.\" Portions of this software are Copyright 1995 by Randall Atkinson and Dan
11.\" McDonald, All Rights Reserved. All Rights under this copyright are assigned
12.\" to the U.S. Naval Research Laboratory (NRL). The NRL Copyright Notice and
13.\" License Agreement applies to this software.
14.\"
15.\" History:
16.\"
17.\" Modified by cmetz for OPIE 2.4. Spelling fixes.
18.\" Modified by cmetz for OPIE 2.2. Removed MJR DES documentation. Removed
19.\" references to the old square brackets challenge delimiters.
20.\" Modified at NRL for OPIE 2.01. Updated UNIX trademark credit.
21.\" Definition of "seed" written by Neil Haller of Bellcore
22.\" Written at NRL for OPIE 2.0.
23.\"
24.\" $FreeBSD: src/contrib/opie/opie.4,v 1.6.2.4 2002/07/15 14:48:43 des Exp $
1de703da 25.\" $DragonFly: src/contrib/opie/opie.4,v 1.2 2003/06/17 04:24:04 dillon Exp $
984263bc
MD
26.\"
27.TH OPIE 4 "January 10, 1995"
28.SH NAME
29.B OPIE \- One-time Passwords In Everything
30.SH DESCRIPTION
31.LP
32OPIE is a package derived from the Bellcore S/Key Version 1 distribution
33that helps to secure a system against replay attacks (see below). It does so
34using a secure hash function and a challenge/response system. It provides
35replacements for the
36.IR login (1),
37.IR su (1),
38and
39.IR ftpd (8)
40programs that use OPIE
41authentication as well as demonstrate how a program might be adapted to use
42OPIE authentication. OPIE was developed at and for the United States Naval
43Research Laboratory (NRL). OPIE is derived in part from Berkeley Standard
44Distribution UNIX and the Bellcore S/Key Version 1 distribution.
45.LP
46From the average user's perspective, OPIE is a nuisance that prevents their
47account from being broken into. The first time a user wishes to use OPIE,
48(s)he needs to use the
49.IR opiepasswd (1)
50command to put an entry for them into
51the OPIE database. The user can then use OPIE to authenticate themselves
52with any program that supports it. If no other clients are being used,
53this means they can use OPIE to
54.I telnet,
55.I rlogin,
56or
57.I ftp
58into the system,
59log in on a terminal port (like a modem), or switch to another user's
60account. When they would normally be asked for a password, they will get
61a challenge from the server. They then need to copy that challenge (or
62re-type, if they don't have the ability to copy and paste through something
63like a window system) to their calculator program, enter their password,
64then copy (or re-type) the response from the calculator as their password.
65While this will seem cumbersome at first, with some practice, it becomes
66easy.
67
68.SH TERMS
69.TP
70.I user name
71The name that the system knows you as. For example, "jdoe".
72.TP
73.I secret password
74A password, usually selected by the user, that is needed to gain access to the
75system. For example, "SEc1_rt".
76.TP
77.I challenge
78A packet of information output by a system when it wishes to authenticate a
79user. In OPIE, this is a three-item group consisting of a hash identifier,
80a sequence number, and a seed. This
81information is needed by the OPIE calculator to generate a proper response.
82For example, "otp-md5 95 wi14321".
83.TP
84.I response
85A packet of information generated from a challenge that is used by a system to
86authenticate a user. In OPIE, this is a group of six words that is generated by
87the calculator given the challenge and the secret password. For example,
88"PUP SOFT ROSE BIAS FLAG END".
89.TP
90.I seed
91A piece of information that is used in conjunction with the secret password
92and sequence number to compute the response. Its purpose is to allow the same
93secret password to be used for multiple sequences, by changing the seed, or
94for authentication to multiple machines by using different seeds.
95.TP
96.I sequence number
97A counter used to keep track of key iterations. In OPIE, each time a successful
98response is received by the system, the sequence number is decremented. For
99example, "95".
100.TP
101.I hash identifier
102A piece of text that identifies the actual algorithm that needs to be used to
103generate a proper response. In OPIE, the only two valid hash identifiers are
104"otp-md4", which selects MD4 hashing, and "otp-md5", which selects MD5.
105
106.SH REPLAY ATTACKS
107When you use a network terminal program like
108.IR telnet (1)
109or even use a modem to log into a
110computer system, you need a user name and a secret password. Anyone who can
111provide those to the system is recognized as you because, in theory, only you
112would have your secret password. Unfortunately, it is now easy to listen in
113on many computer communications media. From modem communication to many
114networks, your password is not usually safe over remote links. If a
115cracker can listen in when you send your password, (s)he then has a copy
116of your password that can be used at any time in the future to access your
117account. On more than one occasion, major sites on the Internet have been
118broken into exactly this way.
119.LP
120All an attacker has to
121do is capture your password once and then replay it to the server when it's
122asked for. Even if the password is communicated between machines in encoded
123or encrypted form, as long as a cracker can get in by simply replaying
124a previously captured communication, you are at risk. Up until very recently,
125Novell NetWare was vulnerable this way. A cracker couldn't find out what your
126password actually is, but (s)he didn't need to -- all that was necessary to
127get into your account was to capture the encrypted password and send that
128back to the server when asked for it.
129
130.SH ONE-TIME PASSWORDS
131One solution to the problem of replay attacks
132is to keep changing the way that a password is being encoded so that what is
133sent over the link to another system can only be used once. If you can do that,
134then a cracker can replay it as many times as (s)he wants -- it's just not
135going to get them anywhere. It's important, however, to make sure you encode
136the password in such a way that the cracker can't use the encoded version to
137figure out what the password is or what a future encoded password will be.
138Otherwise, while still an improvement over no encoding or a fixed encoding,
139you can still be broken into.
140
141.SH THE S/KEY ALGORITHM
142
143A solution to this whole problem was invented by Lamport in 1981. This
144technique was implemented by Haller, Karn, and Walden at Bellcore. They
145created a free software package called "S/Key" that used an algorithm
146called a cryptographic checksum. A cryptographic checksum is a strong one-way
147function such that, knowing the result of such a function, an attacker still
148cannot feasibly determine the input. Further, unlike cyclic redundancy
149checksums (CRCs), cryptographic checksums have few inputs that result in the
150same output.
151.LP
152In S/Key, what changes is the number of
153times the password is run through the secure hash. The password is run through
154the secure hash once, then the output of the hash is run through the secure
155hash again, that output is run through the secure hash again, and so on until
156the number of times the password has been run through the secure hash is equal
157to the desired sequence number. This is much slower than just, say, putting
158the sequence number in before the password and running that through the secure
159hash once, but it gains you one significant benefit. The server machine you
160are trying to connect to has to have some way to determine whether the output
161of that whole mess is right. If it stores it either without any encoding or
162with a normal encoding, a cracker could still get at your password. But if it
163stores it with a secure hash, then how does it account for the response
164changing every time because the sequence number is changing? Also what if you
165can never get to the machine any way that can't be listened in on? How do you
166change your password without sending it over the link?
167.LP
168The clever solution
169devised by Lamport is to keep in mind that the sequence number is
170always decrementing by one and that, in the S/Key system, simply by running any
171response with a sequence number N through the secure hash, you can get the
172response with a sequence number N+1, but you can't go the other way. At any
173given time, call the sequence number of the last valid response that the
174system got N+1 and the sequence number of the response you are giving it N.
175If the password that generated the response for N is the same as the one for
176N+1, then you should be able to run the response for N through the secure hash
177one more time, for a total of N+1 times, and get the same response as you got
178back for N+1. Once you compare the two and find that they are the same, you
179subtract one from N so that, now, the key for N that you just verified becomes
180the new key for N+1 that you can store away to use the next time you need to
181verify a key. This also means that if you need to change your password but
182don't have a secure way to access your machine, all the system really needs to
183have to verify your password is a valid response for one more than the sequence
184number you want to start with.
185.LP
186Just for good measure, each side of
187all of this uses a seed in conjunction with your password when it actually
188generates and verifies the responses. This helps to jumble things up a little
189bit more, just in case. Otherwise, someone with a lot of time and disk space
190on their hands could generate all the responses for a lot of frequent passwords
191and defeat the system.
192.LP
193This is not, by any means, the best explanation of how the S/Key algorithm
194works or some of the more minor details. For that, you should go to some of
195the papers now published on the topic. It is simply a quick-and-dirty
196introduction to what's going on under the hood.
197
198.SH OPIE COMPONENTS
199
200The OPIE distribution has been incorporated into three standard client
201programs:
202.IR login (1),
203.IR su (1),
204and
205.IR ftpd (8),
206.LP
207There are also three programs in the OPIE distribution that are specific to
208the OPIE system:
209.IR opiepasswd (1),
210which allows a user to set and change their
211OPIE password,
212.IR opieinfo (1),
213which allows a user to find out what their current
214sequence number and seed are, and
215.IR opiekey(1),
216which is an OPIE key calculator.
217
218.SH ADDING OPIE TO OTHER PROGRAMS
219
220Adding OPIE authentication to programs other than the ones included as clients
221in the OPIE distribution isn't very difficult. First, you will need to make
222sure that the program includes <stdio.h> somewhere. Then, below the other
223includes such as <stdio.h>, but before variable declarations, you need to
224include <opie.h>. You need to add a variable of type "struct opie" to your
225program, you need to make sure that the buffer that you use to get a password
226from the user is big enough to hold OPIE_RESPONSE_MAX+1 characters, and you
227need to have a buffer in which to store the challenge string that is big enough
228to hold OPIE_CHALLENGE_MAX+1 characters.
229.LP
230When you are ready to output the challenge string and know the user's name,
231you would use a call to opiechallenge. Later, to verify the response received,
232you would use a call to opieverify. For example:
233.sp 0
234
235.sp 0
236 #include <stdio.h>
237.sp 0
238 .
239.sp 0
240 .
241.sp 0
242 #include <opie.h>
243.sp 0
244 .
245.sp 0
246 .
247.sp 0
248 char *user_name;
249.sp 0
250 /* Always remember the trailing null! */
251.sp 0
252 char password[OPIE_RESPONSE_MAX+1];
253.sp 0
254 .
255.sp 0
256 .
257.sp 0
258 struct opie opiedata;
259.sp 0
260 char opieprompt[OPIE_CHALLENGE_MAX+1];
261.sp 0
262 .
263.sp 0
264 .
265.sp 0
266 opiechallenge(&opiedata, user_name, opieprompt);
267.sp 0
268 .
269.sp 0
270 .
271.sp 0
272 if (opieverify(&opiedata, password)) {
273.sp 0
274 printf("Login incorrect");
275.sp 0
276.SH TERMINAL SECURITY AND OPIE
277
278When using OPIE, you need to be careful not to allow your password to be
279communicated over an insecure channel where someone might be able to listen
280in and capture it. OPIE can protect you against people who might get your
281password from snooping on the line, but only if you make sure that the password
282itself never gets sent over the line. The important thing is to always run the
283OPIE calculator on whichever machine you are actually using - never on a machine
284you are connected to by network or by dialup.
285.LP
286You need to be careful about the
287X Window System, because it changes things quite a bit. For instance, if you
288run an xterm (or your favorite equivalent) on another machine and display it
289on your machine, you should not run an OPIE calculator in that window. When you
290type in your secret password, it still gets transmitted over the network to go
291to the machine the xterm is running on. People with machines such as
292X terminals that can only run the calculator over the network are in an
293especially precarious position because they really have no choice. Also, with
294the X Window System, as with some other window system (NeWS as an example),
295it is sometimes possible for people to read your keystrokes and capture your
296password even if you are running the OPIE calculator on your local machine.
297You should always use the best security mechanism available on your system to
298protect your X server, be it XDM-AUTHORIZATION-1, XDM-MAGIC-COOKIE-1, or host
299access control. *Never* just allow any machine to connect to your server
300because, by doing so, you are allowing any machine to read any of your windows
301or your keystrokes without you knowing it.
302
303.SH SEE ALSO
304.BR ftpd (8)
305.BR login (1),
306.BR opie (4),
307.BR opiekeys (5),
308.BR opieaccess (5),
309.BR opiekey (1),
310.BR opieinfo (1),
311.BR opiepasswd (1),
312.sp
313Lamport, L. "Password Authentication with Insecure Communication",
314Communications of the ACM 24.11 (November 1981), pp. 770-772.
315.sp
316Haller, N. "The S/KEY One-Time Password System", Proceedings of the ISOC
317Symposium on Network and Distributed System Security, February 1994,
318San Diego, CA.
319.sp
320Haller, N. and Atkinson, R, "On Internet Authentication", RFC-1704,
321DDN Network Information Center, October 1994.
322.sp
323Rivest, R. "The MD5 Message Digest Algorithm", RFC-1321,
324DDN Network Information Center, April 1992.
325.sp
326Rivest, R. "The MD4 Message Digest Algorithm", RFC-1320,
327DDN Network Information Center, April 1992.
328
329.SH AUTHOR
330Bellcore's S/Key was written by Phil Karn, Neil M. Haller, and John S. Walden
331of Bellcore. OPIE was created at NRL by Randall Atkinson, Dan McDonald, and
332Craig Metz.
333
334S/Key is a trademark of Bell Communications Research (Bellcore).
335UNIX is a trademark of X/Open.
336
337.SH CONTACT
338OPIE is discussed on the Bellcore "S/Key Users" mailing list. To join,
339send an email request to:
340.sp
341skey-users-request@thumper.bellcore.com