diff --git a/doc/ack.texi b/doc/ack.texi new file mode 100644 index 000000000..cc6ec5083 --- /dev/null +++ b/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én +@email{johani@@pdc.kth.se} +@item Love Hörnquist-Å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. diff --git a/doc/heimdal.texi b/doc/heimdal.texi index 53122b1c2..9a6ac2892 100644 --- a/doc/heimdal.texi +++ b/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 diff --git a/doc/install.texi b/doc/install.texi index c27da1976..45f350c4d 100644 --- a/doc/install.texi +++ b/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. diff --git a/doc/intro.texi b/doc/intro.texi index 3ad385090..ffd0cd44d 100644 --- a/doc/intro.texi +++ b/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 diff --git a/doc/kerberos4.texi b/doc/kerberos4.texi index 736efc1cb..7158ed0ce 100644 --- a/doc/kerberos4.texi +++ b/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 diff --git a/doc/setup.texi b/doc/setup.texi index 1bfd64fa3..e10ca6ad3 100644 --- a/doc/setup.texi +++ b/doc/setup.texi @@ -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. diff --git a/doc/whatis.texi b/doc/whatis.texi new file mode 100644 index 000000000..dfbe7aefa --- /dev/null +++ b/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/}.