oysteikt/heimdal
0
0
Fork 0
Code Issues 5 Pull Requests Releases Activity

documentation update

Browse Source 
git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@3338 ec53bebd-3082-4978-b11e-865c3cabbd6b
This commit is contained in:
Assar Westerlund
1997-09-01 23:59:28 +00:00
parent c1a77dad02
commit b15cbefc25
7 changed files with 235 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
doc/ack.texi Normal file
View File

@@ -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.

8
doc/heimdal.texi
View File

@@ -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

8
doc/install.texi
View File

@@ -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.

3
doc/intro.texi
View File

@@ -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

2
doc/kerberos4.texi
View File

@@ -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

40
doc/setup.texi
View File

@@ -3,14 +3,16 @@
A
@cindex realm
realm is an administrative domain. Kerberos realms usually consists of
an Internet domain name in uppercase. Call your realm the same as your
Internet domain name if you do not have strong reasons for not doing so.
It will make life easier for you and everyone else.
realm is an administrative domain. The name of a Kerberos realm is
usually the Internet domain name in uppercase. Call your realm the same
as your Internet domain name if you do not have strong reasons for not
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.

142
doc/whatis.texi Normal file
View File

@@ -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/}.