Add some text I originally wrote for work describing how to use

S/Key.

4 files changed, 308 insertions, 5 deletions

diff --git a/share/doc/handbook/Makefile b/share/doc/handbook/Makefile
index 0a7e06f..369bc85 100644
--- a/share/doc/handbook/Makefile
+++ b/share/doc/handbook/Makefile
@@ -1,4 +1,4 @@
-# $Id: Makefile,v 1.1 1995/09/08 19:34:26 jfieber Exp $
+# $Id: Makefile,v 1.2 1995/09/25 04:53:26 jfieber Exp $
 
 SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml
 SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml dialup.sgml
@@ -6,7 +6,7 @@ SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml glossary.sgml
 SRCS+= handbook.sgml history.sgml hw.sgml install.sgml kerberos.sgml
 SRCS+= kerneldebug.sgml memoryuse.sgml mirrors.sgml nfs.sgml nutshell.sgml 
 SRCS+= porting.sgml ports.sgml ppp.sgml relnotes.sgml scsi.sgml sections.sgml
-SRCS+= slipc.sgml slips.sgml submitters.sgml sup.sgml
+SRCS+= skey.sgml slipc.sgml slips.sgml submitters.sgml sup.sgml
 SRCS+= troubleshooting.sgml userppp.sgml
 
 .include <bsd.sgml.mk>
diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml
index 02417be..b89298c 100644
--- a/share/doc/handbook/handbook.sgml
+++ b/share/doc/handbook/handbook.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: handbook.sgml,v 1.27 1995/09/03 21:12:27 jfieber Exp $ -->
+<!-- $Id: handbook.sgml,v 1.28 1995/09/25 04:53:31 jfieber Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@@ -76,7 +76,7 @@ Web server">.
 
     <chapt><heading>Users, groups and security</heading>
       &crypt;
-      <sect><heading>* S/Key</heading>
+      &skey;
       &kerberos;
       <sect><heading>* Firewalls</heading>
 
diff --git a/share/doc/handbook/sections.sgml b/share/doc/handbook/sections.sgml
index 268fc5b..66c25a3 100644
--- a/share/doc/handbook/sections.sgml
+++ b/share/doc/handbook/sections.sgml
@@ -1,4 +1,4 @@
-<!-- $Id: sections.sgml,v 1.1 1995/09/03 21:12:29 jfieber Exp $ -->
+<!-- $Id: sections.sgml,v 1.2 1995/09/25 04:53:33 jfieber Exp $ -->
 <!-- The FreeBSD Documentation Project -->
 
 <!-- Entities containing all the pieces of the handbook are -->
@@ -32,6 +32,7 @@
 <!ENTITY ppp SYSTEM "ppp.sgml">
 <!ENTITY relnotes SYSTEM "relnotes.sgml">
 <!ENTITY scsi SYSTEM "scsi.sgml">
+<!ENTITY skey SYSTEM "skey.sgml">
 <!ENTITY slipc SYSTEM "slipc.sgml">
 <!ENTITY slips SYSTEM "slips.sgml">
 <!ENTITY submitters SYSTEM "submitters.sgml">
diff --git a/share/doc/handbook/skey.sgml b/share/doc/handbook/skey.sgml
new file mode 100644
index 0000000..7d12862
--- /dev/null
+++ b/share/doc/handbook/skey.sgml
@@ -0,0 +1,302 @@
+<!-- $Id$ -->
+<!-- The FreeBSD Documentation Project -->
+<!--
+Copyright 1995 Massachusetts Institute of Technology
+
+Permission to use, copy, modify, and distribute this software and
+its documentation for any purpose and without fee is hereby
+granted, provided that both the above copyright notice and this
+permission notice appear in all copies, that both the above
+copyright notice and this permission notice appear in all
+supporting documentation, and that the name of M.I.T. not be used
+in advertising or publicity pertaining to distribution of the
+software without specific, written prior permission.  M.I.T. makes
+no representations about the suitability of this software for any
+purpose.  It is provided "as is" without express or implied
+warranty.
+
+THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
+ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
+SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.
+-->
+
+<sect><heading>S/Key<label id="skey"></heading>
+
+<p><em>Contributed by &a.wollman;<newline>25 September 1995.</em>
+
+<p>S/Key is a one-time password scheme based on a one-way hash function
+(in our version, this is MD4 for compatibility; other versions have
+used MD5 and DES-MAC).  S/Key has been a standard part of all FreeBSD
+distributions since version 1.1.5, and is also implemented on a large
+and growing number of other systems.  S/Key is a registered trademark
+of Bell Communications Research, Inc.
+
+<!-- XXX - is there a better word to use than UNIX? -->
+<p>There are three different sorts of passwords which we will talk about
+in the discussion below.  The first is your usual UNIX-style or Kerberos
+password; we'll call this a ``UNIX password''.  The second sort is the
+one-time password which is generated by the S/Key `<tt/key/' program and
+accepted by the `<tt/keyinit/' program and the login prompt; we'll call
+this a ``one-time password''.  The final sort of password is the
+secret password which you give to the `<tt/key/' program (and sometimes the
+`<tt/keyinit/' program) which it uses to generate one-time passwords; we'll
+call it a ``secret password'' or just unqualified ``password''.  
+
+<p>The secret password does not necessarily have anything to do with your
+UNIX password (while they can be the same, this is not recommended).
+While UNIX passwords are limited to eight characters in length, your
+S/Key secret password can be as long as you like; I use seven-word
+phrases.  In general, the S/Key system operates completely
+independently of the UNIX password system.
+
+<p>There are in addition two other sorts of data involved in the S/Key
+system; one is called the ``seed'' or (confusingly) ``key'', and
+consists of two letters and five digits, and the other is the
+``iteration count'' and is a number between 100 and 1.  S/Key
+constructs a one-time password from these components by concatenating
+the seed and the secret password, then applying a one-way hash (the
+RSA Data Security, Inc., MD4 secure hash function) iteration-count
+times, and turning the result into six short English words.  The
+`<tt/login/' and `<tt/su/' programs keep track of the last one-time
+password used, and the user is authenticated if the hash of the
+user-provided password is equal to the previous password.  Because a
+one-way hash function is used, it is not possible to generate future
+one-time passwords having overheard one which was successfully used;
+the iteration count is decremented after each successful login to keep
+the user and login program in sync.  (When you get the iteration count
+down to 1, it's time to reinitialize S/Key.)
+
+<p>There are four programs involved in the S/Key system which we will
+discuss below.  The `<tt/key/' program accepts an iteration count, a
+seed, and a secret password, and generates a one-time password.  The
+`<tt/keyinit/' program is used to initialized S/Key, and to change
+passwords, iteration counts, or seeds; it takes either a secret
+password, or an iteration count, seed, and one-time password.  The
+`<tt/keyinfo/' program examines the <tt>/etc/skeykeys</tt> file and
+prints out the invoking user's current iteration count and seed.
+Finally, the `<tt/login/' and `<tt/su/' programs contain the necessary
+logic to accept S/Key one-time passwords for authentication.  The
+`<tt/login/' program is also capable of disallowing the use of UNIX
+passwords on connections coming from specified addresses.
+
+<p>There are four different sorts of operations we will cover.  The first
+is using the `<tt/keyinit/' program over a secure connection to set up
+S/Key for the first time, or to change your password or seed.  The
+second operation is using the `<tt/keyinit/' program over an insecure
+connection, in conjunction with the `<tt/key/' program over a secure
+connection, to do the same.  The third is using the `<tt/key/' program to
+log in over an insecure connection.  The fourth is using the `<tt/key/'
+program to generate a number of keys which can be written down or
+printed out to carry with you when going to some location without
+secure connections to anywhere (like at a conference).
+
+<sect1><heading>Secure connection initialization</heading>
+
+<p>To initialize S/Key, change your password, or change your seed while
+logged in over a secure connection (e.g., on the console of a machine),
+use the `<tt/keyinit/' command without any parameters while logged in as
+yourself:
+
+<tscreen><verb>
+$ keyinit
+Updating wollman:			) these will not appear if you
+Old key: ha73895			) have not used S/Key before
+Reminder - Only use this method if you are directly connected.
+If you are using telnet or rlogin exit with no password and use keyinit -s.
+Enter secret password:			) I typed my pass phrase here
+Again secret password:			) I typed it again
+
+ID wollman s/key is 99 ha73896		) discussed below
+SAG HAS FONT GOUT FATE BOOM		)
+</verb></tscreen>
+
+<p>There is a lot of information here.  At the `Enter secret password:'
+prompt, you should enter some password or phrase (I use phrases of
+minimum seven words) which will be needed to generate login keys.  The
+line starting `ID' gives the parameters of your particular S/Key
+instance: your login name, the iteration count, and seed.  When
+logging in with S/Key, the system will remember these parameters and
+present them back to you so you don't have to remember them.  The last
+line gives the particular one-time password which corresponds to those
+parameters and your secret password; if you were to re-login
+immediately, this one-time password is the one you would use.
+
+<sect1><heading>Insecure connection initialization</heading>
+
+<p>To initialize S/Key or change your password or seed over an insecure
+connection, you will need to already have a secure connection to some
+place where you can run the `<tt/key/' program; this might be in the form
+of a desk accessory on a Macintosh, or a shell prompt on a machine you
+trust (we'll show the latter).  You will also need to make up an
+iteration count (100 is probably a good value), and you may make up
+your own seed or use a randomly-generated one.  Over on the insecure
+connection (to the machine you are initializing), use the `<tt/keyinit -s/'
+command:
+
+<tscreen><verb>
+$ keyinit -s 
+Updating wollman:
+Old key: kh94741
+Reminder you need the 6 english words from the skey command.
+Enter sequence count from 1 to 9999: 100	) I typed this
+Enter new key [default kh94742]: 
+s/key 100 kh94742
+</verb></tscreen>
+
+To accept the default seed (which the `keyinit' program confusingly
+calls a `key'), press return.  Then move over to your secure
+connection or S/Key desk accessory, and give it the same parameters:
+
+<tscreen><verb>
+$ key 100 kh94742
+Reminder - Do not use this program while logged in via telnet or rlogin.
+Enter secret password: 				) I typed my secret password
+HULL NAY YANG TREE TOUT VETO
+</verb></tscreen>
+
+Now switch back over to the insecure connection, and copy the one-time
+password generated by `<tt/key/' over to the `<tt/keyinit/' program:
+
+<tscreen><verb>
+s/key access password: HULL NAY YANG TREE TOUT VETO
+
+ID wollman s/key is 100 kh94742
+HULL NAY YANG TREE TOUT VETO
+</verb></tscreen>
+
+The rest of the description from the previous section applies here as
+well.
+
+<sect1><heading>Diversion: a login prompt</heading>
+
+<p>Before explaining how to generate one-time passwords, we should go
+over an S/Key login prompt:
+
+<tscreen><verb>
+$ telnet himalia
+Trying 18.26.0.186...
+Connected to himalia.lcs.mit.edu.
+Escape character is '^]'.
+s/key 92 hi52030
+Password:
+</verb></tscreen>
+
+>Note that, before prompting for a password, the login program
+prints out the iteration number and seed which you will need in order
+to generate the appropriate key.  You will also find a useful feature
+(not shown here): if you press return at the password prompt, the
+login program will turn echo on, so you can see what you are typing.
+This can be extremely useful if you are attempting to type in an S/Key
+by hand, such as from a printout.
+
+<p>If this machine were configured to disallow UNIX passwords over a
+connection from my machine, the prompt would have also included the
+annotation `<tt>(s/key required)</tt>', indicating that only S/Key one-time
+passwords will be accepted.
+
+<sect1><heading>Generating a single one-time password</heading>
+
+<p>Now, to generate the one-time password needed to answer this login
+prompt, we use a trusted machine and the `<tt/key/' program.  (There are
+versions of the `<tt/key/' program from DOS and Windows machines, and there
+is an S/Key desk accessory for Macintosh computers as well.)  The
+command-line `<tt/key/' program takes as its parameters the iteration count
+and seed; you can cut-and-paste right from the login prompt starting
+at ``<tt/key/'' to the end of the line.  Thus:
+
+<tscreen><verb>
+$ key 92 hi52030				) pasted from previous section
+Reminder - Do not use this program while logged in via telnet or rlogin.
+Enter secret password: 				) I typed my secret password
+ADEN BED WOLF HAW HOT STUN
+</verb></tscreen>
+
+And in the other window:
+
+<tscreen><verb>
+s/key 92 hi52030				) from previous section
+Password:
+ (turning echo on)
+Password:ADEN BED WOLF HAW HOT STUN
+Last login: Wed Jun 28 15:31:00 from halloran-eldar.l
+[etc.]
+</verb></tscreen>
+
+This is the easiest mechanism <em/if/ you have a trusted machine.
+
+<sect1><heading>Generating multiple one-time passwords</heading>
+
+<p>Sometimes we have to go places where no trusted machines or
+connections are available.  In this case, it is possible to use the
+`<tt/key/' command to generate a number of one-time passwords in the same
+command; these can then be printed out.  For example:
+
+<tscreen><verb>
+$ key -n 25 57 zz99999
+Reminder - Do not use this program while logged in via telnet or rlogin.
+Enter secret password: 
+33: WALT THY MALI DARN NIT HEAD  
+34: ASK RICE BEAU GINA DOUR STAG 
+[...]
+56: AMOS BOWL LUG FAT CAIN INCH  
+57: GROW HAYS TUN DISH CAR BALM  
+</verb></tscreen>
+
+The `<tt/-n 25/' requests twenty-five keys in sequence; the `<tt/57/' indicates
+the <em/ending/ iteration number; and the rest is as before.  Note that
+these are printed out in <em/ending/ order of eventual use.  If you're
+really paranoid, you might want to write the results down by hand;
+otherwise you can cut-and-paste into `<tt/lpr/'.  Note that each line shows
+both the iteration count and the one-time password; you may still find
+it handy to scratch off passwords as you use them.
+
+<sect1><heading>Restricting use of UNIX passwords</heading>
+
+<p>The configuration file <tt>/etc/skey.access</tt> can be used to
+configure restrictions on the use of UNIX passwords based on the host
+name, user name, terminal port, or IP address of a login session.  The
+complete format of the file is documented in the <em/skey.access/(5)
+manual page; there are also some security cautions there which should
+be read before depending on this file for security.
+
+<p>If there is no <tt>/etc/skey.access</tt> file (which is the default
+state as FreeBSD is shipped), then all users will be allowed to use
+UNIX passwords.  If the file exists, however, then all users will be
+required to use S/Key unless explicitly permitted to do otherwise by
+configuration statements in the <tt/skey.access/ file.  In all cases,
+UNIX passwords are permitted on the console.
+
+<p>Here is a sample configuration file which illustrates the three most
+common sorts of configuration statements:
+
+<tscreen><verb>
+permit internet 18.26.0.0 255.255.0.0
+permit user jrl
+permit port ttyd0
+</verb></tscreen>
+
+The first line (`<tt/permit internet/') allows users whose IP source
+address (which is vulnerable to spoofing) matches the specified value
+and mask, to use UNIX passwords.  This should not be considered a
+security mechanism, but rather, a means to remind authorized users
+that they are using an insecure network and need to use S/Key for
+authentication.
+
+<p>The second line (`<tt/permit user/') allows the specified user to
+use UNIX passwords at any time.  Generally speaking, this should only
+be used for people who are either unable to use the `<tt/key/'
+program, like those with dumb terminls, or those who are uneducable.
+
+<p>The third line (`<tt/permit port/') allows all users logging in on
+the specified terminal line to use UNIX passwords; this would be used
+for dial-ups.
+