documentation update

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@3338 ec53bebd-3082-4978-b11e-865c3cabbd6b

doc/ack.texi

@@ -0,0 +1,41 @@
+@node  Acknowledgments, , Kerberos 4 issues, Top
+@comment  node-name,  next,  previous,  up
+@appendix Acknowledgments
+
+Eric Young wrote ``libdes''.
+
+The University of California at Berkeley initially wrote @code{telnet},
+and @code{telnetd}.  The authentication and encryption code of
+@code{telnet} and @code{telnetd} was added by David Borman (then of Cray
+Research, Inc).  The encryption code was removed when this was exported
+and then added back by Juha Eskelinen, @email{esc@@magic.fi}.
+
+The @code{popper} was also a Berkeley program initially.
+
+Some of the functions in @file{libroken} also come from Berkeley by way
+of NetBSD/FreeBSD.
+
+@code{editline} was written by Simmule Turner and Rich Salz.
+
+Bugfixes, documentation, encouragement, and code has been contributed by:
+@table @asis
+@item Derrick J Brashear
+@email{shadow@@dementia.org}
+@item Ken Hornstein
+@email{kenh@@cmf.nrl.navy.mil}
+@item Johan Ihr<68>n
+@email{johani@@pdc.kth.se}
+@item Love H<>rnquist-<2D>strand
+@email{e96_lho@@e.kth.se}
+@item Magnus Ahltorp
+@email{map@@stacken.kth.se}
+@item Marc Eichin
+@email{eichin@@cygnus.com}
+@item Marc Horowitz
+@email{marc@@cygnus.com}
+@item Luke Howard
+@email{lukeh@@xedoc.com.au}
+@item and we hope that those not mentioned here will forgive us.
+@end table
+
+All bugs were introduced by ourselves.

doc/heimdal.texi

@@ -14,10 +14,12 @@
 @syncodeindex pg cp
 @c %**end of header
 
-@dircategory Kerberos
+@ifinfo
+@dircategory Heimdal
 @direntry
 * Heimdal: (heimdal).           The Kerberos 5 distribution from KTH
 @end direntry
+@end ifinfo
 
 @c title page
 @titlepage
@@ -212,9 +214,11 @@ to the following restrictions:
 
 @menu
 * Introduction::                
+* What is Kerberos?::           
 * Building and Installing::     
 * Setting up a realm::          
 * Kerberos 4 issues::           
+* Acknowledgments::             
 
  --- The Detailed Node Listing ---
 
@@ -229,9 +233,11 @@ Kerberos 4 issues
 @end menu
 
 @include intro.texi
+@include whatis.texi
 @include install.texi
 @include setup.texi
 @include kerberos4.texi
+@include ack.texi
 
 @c @shortcontents
 @contents

doc/install.texi

@@ -1,4 +1,4 @@
-@node Building and Installing, Setting up a realm, Introduction, Top
+@node Building and Installing, Setting up a realm, What is Kerberos?, Top
 @comment  node-name,  next,  previous,  up
 @chapter Building and Installing
 
@@ -19,6 +19,8 @@ A compiler that supports a ``loose'' ANSI C mode, such as @code{gcc}.
 @item
 lex or flex
 @item
+awk
+@item
 yacc or bison
 @item
 a socket library
@@ -44,6 +46,10 @@ Kerberos 4 support in the applications (telnet, rsh, popper, etc) and
 the KDC. If you keep libraries and headers in different places, you can
 instead give the path to each with the @kbd{--with-krb4-lib=@file{dir}},
 and @kbd{--with-krb4-include=@file{dir}} options.
+
+You will need a fairly recent version of our Kerberos 4 distribution for
+@code{rshd} and @code{popper} to support version 4 clients.
+
 @item @kbd{--enable-kaserver}
 Enables experimental kaserver support in the KDC. This is the protocol
 used by ``KDC'' in AFS. Requires Kerberos 4 support.

doc/intro.texi

@@ -1,4 +1,5 @@
-@node Introduction, Building and Installing, Top, Top
+@node Introduction, What is Kerberos?, Top, Top
+@c @node Introduction, What is Kerberos?, Top, Top
 @comment  node-name,  next,  previous,  up
 @chapter Introduction
 

doc/kerberos4.texi

@@ -1,4 +1,4 @@
-@node Kerberos 4 issues, , Setting up a realm, Top
+@node Kerberos 4 issues, Acknowledgments, Setting up a realm, Top
 @comment  node-name,  next,  previous,  up
 @chapter Kerberos 4 issues
 

doc/setup.texi

@@ -3,14 +3,16 @@
 
 A
 @cindex realm
-realm is an administrative domain.  Kerberos realms usually consists of
+realm is an administrative domain.  The name of a Kerberos realm is
-an Internet domain name in uppercase. Call your realm the same as your
+usually the Internet domain name in uppercase.  Call your realm the same
-Internet domain name if you do not have strong reasons for not doing so.
+as your Internet domain name if you do not have strong reasons for not
-It will make life easier for you and everyone else.
+doing so.  It will make life easier for you and everyone else.
+
+@section Configuration file
 
 To setup a realm you will first have to create a configuration file:
 @file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many
-configuration options, some which are described here.
+configuration options, some of which are described here.
 
 There is a sample @file{krb5.conf} supplied with the distribution.
 
@@ -70,6 +72,8 @@ with contents similar to the following.
 If you use a realm name equal to your domain name, you can omit the
 @samp{libdefaults}, and @samp{domain_realm}, sections.
 
+@section Creating the database
+
 The database library will look for the database in @file{/var/heimdal},
 so you should probably create that directory.
 
@@ -96,6 +100,7 @@ Default renewable ticket life: [7 days]
 kdb_edit> ank me
 Max ticket life [1 day]: 
 Max renewable ticket [7 days]: 
+Flags [client, server, postdate, renewable, proxiable, forwardable]: 
 Password:
 Verifying password - Password:
 @end example
@@ -113,3 +118,28 @@ Credentials cache: /tmp/krb5cc_3008
   Issued           Expires          Principal
 Aug 25 07:25:55  Aug 25 17:25:55  krbtgt/MY.REALM@@MY.REALM
 @end example
+
+@section keytabs
+
+To extract a service ticket from the database and put it in a keytab you
+need to first create the principal in the database with @samp{ank}
+(entering @kbd{random} and then extract it with @samp{ext_keytab}.
+
+@example
+# kdb_edit
+kdb_edit> ank host/my.host.name
+Max ticket life [1 day]: 
+Max renewable life [1 week]: 
+Flags [client, server, postdate, renewable, proxiable, forwardable]: 
+Password:
+Verifying password - Password:
+kdb_edit> ext host/my.host.name
+# ktutil list
+Version  Type  Principal
+     0     1   host/my.host.name@@MY.REALM
+@end example
+
+@section Testing clients and servers
+
+Now you should be able to run all the clients and servers.  Refer to the
+appropriate man pages for information on how to use them.

doc/whatis.texi

@@ -0,0 +1,142 @@
+@node What is Kerberos?, Building and Installing, Introduction, Top
+@chapter What is Kerberos?
+
+@quotation
+@flushleft
+        Now this Cerberus had three heads of dogs,
+        the tail of a dragon, and on his back the
+        heads of all sorts of snakes.
+        --- Pseudo-Apollodorus Library 2.5.12
+@end flushleft
+@end quotation
+
+Kerberos is a system for authenticating users and services on a network.
+It is built upon the assumption that the network is ``unsafe''.  For
+example, data sent over the network can be eavesdropped and altered, and
+addresses can also be faked.  Therefore they cannot be used for
+authentication purposes.
+@cindex authentication
+
+Kerberos is a trusted third-party service.  That means that there is a
+third party (the kerberos server) that is trusted by all the entities on
+the network (users and services, usually called @dfn{principals}).  All
+principals share a secret password (or key) with the kerberos server and
+this enables principals to verify that the messages from the kerberos
+server are authentic.  Thus trusting the kerberos server, users and
+services can authenticate each other.
+
+@section Basic mechanism
+
+@ifinfo
+THIS IS INFO
+@end ifinfo
+
+@ifinfo
+@macro sub{arg}
+<\arg\>
+@end macro
+@end ifinfo
+
+@tex
+@def@xsub#1{$_{#1}$}
+@global@let@sub=@xsub
+@end tex
+
+In Kerberos, principals use @dfn{tickets} to prove that they are who
+they claim to be. In the following example, @var{A} is the initiator of
+the authentication exchange, usually a user, and @var{B} is the service
+that @var{A} wishes to use.
+
+To obtain a ticket for a specific service, @var{A} sends a ticket
+request to the kerberos server. The request basically contains @var{A}'s
+and @var{B}'s names. The kerberos server checks that both @var{A} and
+@var{B} are valid principals.
+
+Having verified the validity of the principals, it creates a packet
+containing @var{A}'s and @var{B}'s names, @var{A}'s network address
+(@var{A@sub{addr}}), the current time (@var{t@sub{issue}}), the lifetime
+of the ticket (@var{life}), and a secret @dfn{session key}
+@cindex session key
+(@var{K@sub{AB}}). This packet is encrypted with @var{B}'s secret key
+(@var{K@sub{B}}).  The actual ticket (@var{T@sub{AB}}) looks like this:
+(@{@var{A}, @var{B}, @var{A@sub{addr}}, @var{t@sub{issue}}, @var{life},
+@var{K@sub{AB}}@}@var{K@sub{B}}).
+
+The reply to @var{A} consists of the ticket (@var{T@sub{AB}}), @var{B}'s
+name, the current time, the lifetime of the ticket, and the session key, all
+encrypted in @var{A}'s secret key (@{@var{B}, @var{t@sub{issue}},
+@var{life}, @var{K@sub{AB}}, @var{T@sub{AB}}@}@var{K@sub{A}}). @var{A}
+decrypts the reply and retains it for later use.
+
+@sp 1
+
+Before sending a message to @var{B}, @var{A} creates an authenticator
+consisting of @var{A}'s name, @var{A}'s address, the current time, and a
+``checksum'' chosen by @var{A}, all encrypted with the secret session
+key (@{@var{A}, @var{A@sub{addr}}, @var{t@sub{current}},
+@var{checksum}@}@var{K@sub{AB}}). This is sent together with the ticket
+received from the kerberos server to @var{B}.  Upon reception, @var{B}
+decrypts the ticket using @var{B}'s secret key.  Since the ticket
+contains the session key that the authenticator was encrypted with,
+@var{B} can now also decrypt the authenticator. To verify that @var{A}
+really is @var{A}, @var{B} now has to compare the contents of the ticket
+with that of the authenticator. If everything matches, @var{B} now
+considers @var{A} as properly authenticated.
+
+@c (here we should have some more explanations)
+
+@section Different attacks
+
+@subheading Impersonating A
+
+An impostor, @var{C} could steal the authenticator and the ticket as it
+is transmitted across the network, and use them to impersonate
+@var{A}. The address in the ticket and the authenticator was added to
+make it more difficult to perform this attack.  To succeed @var{C} will
+have to either use the same machine as @var{A} or fake the source
+addresses of the packets. By including the time stamp in the
+authenticator, @var{C} does not have much time in which to mount the
+attack.
+
+@subheading Impersonating B
+
+@var{C} can hijack @var{B}'s network address, and when @var{A} sends
+her credentials, @var{C} just pretend to verify them. @var{C} can't
+be sure that she is talking to @var{A}.
+
+@section Defense strategies
+
+It would be possible to add a @dfn{replay cache}
+@cindex replay cache
+to the server side.  The idea is to save the authenticators sent during
+the last few minutes, so that @var{B} can detect when someone is trying
+to retransmit an already used message. This is somewhat impractical
+(mostly regarding efficiency), and is not part of Kerberos 4; MIT
+Kerberos 5 contains it.
+
+To authenticate @var{B}, @var{A} might request that @var{B} sends
+something back that proves that @var{B} has access to the session
+key. An example of this is the checksum that @var{A} sent as part of the
+authenticator. One typical procedure is to add one to the checksum,
+encrypt it with the session key and send it back to @var{A}.  This is
+called @dfn{mutual authentication}.
+
+The session key can also be used to add cryptographic checksums to the
+messages sent between @var{A} and @var{B} (known as @dfn{message
+integrity}).  Encryption can also be added (@dfn{message
+confidentiality}). This is probably the best approach in all cases.
+@cindex integrity
+@cindex confidentiality
+
+@section Further reading
+
+The original paper on Kerberos from 1988 is @cite{Kerberos: An
+Authentication Service for Open Network Systems}, by Jennifer Steiner,
+Clifford Neuman and Jeffrey I. Schiller.
+
+A less technical description can be found in @cite{Designing an
+Authentication System: a Dialogue in Four Scenes} by Bill Bryant, also
+from 1988.
+
+These and several other documents can be found on our web-page at
+@url{http://www.pdc.kth.se/kth-krb/}.