1 \input texinfo @c -*-texinfo-*-
3 @setfilename install.info
5 @c For double-sided printing, uncomment:
11 @set UPDATED Mar 20, 1996
20 This file documents how to build and install the Kerberos V5
23 Copyright (C) 1995, 1996 Massachusetts Institute of Technology.
27 Export of this software from the United States of America may require a
28 specific license from the United States Government. It is the
29 responsibility of any person or organization contemplating export to
30 obtain any necessary licenses before exporting.
32 WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
33 distribute this software and its documentation for any purpose and
34 without fee is hereby granted, provided that the above copyright
35 notice appear in all copies and that both that copyright notice and
36 this permission notice appear in supporting documentation, and that
37 the name of M.I.T. not be used in advertising or publicity pertaining
38 to distribution of the software without specific, written prior
39 permission. M.I.T. makes no representations about the suitability of
40 this software for any purpose. It is provided "as is" without express
43 Athena(r), Hesiod(r), Moira(r), and Discuss(r) are registered trademarks of
44 the Massachusetts Institute of Technology (MIT). Project Athena, Athena
45 Dashboard, Athena MUSE, Kerberos, X Window System, and Zephyr are trademarks
46 of MIT. No commercial use of these trademarks may be made without prior
47 written permission of MIT.
49 All other product names are trademarks of their respective companies.
55 @subtitle Notes on Building and Installing Kerberos
56 @subtitle Edition @value{EDITION}, for Kerberos version @value{VERSION}
57 @subtitle @value{UPDATED}
58 @author by Theodore Ts'o
61 @vskip 0pt plus 1filll
62 Copyright @copyright{} 1995, 1996 Massachusetts Institute of Technology
66 Export of this software from the United States of America may require a
67 specific license from the United States Government. It is the
68 responsibility of any person or organization contemplating export to
69 obtain any necessary licenses before exporting.
71 WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
72 distribute this software and its documentation for any purpose and
73 without fee is hereby granted, provided that the above copyright
74 notice appear in all copies and that both that copyright notice and
75 this permission notice appear in supporting documentation, and that
76 the name of M.I.T. not be used in advertising or publicity pertaining
77 to distribution of the software without specific, written prior
78 permission. M.I.T. makes no representations about the suitability of
79 this software for any purpose. It is provided "as is" without express
82 Athena(r), Hesiod(r), Moira(r), and Discuss(r) are registered trademarks of
83 the Massachusetts Institute of Technology (MIT). Project Athena, Athena
84 Dashboard, Athena MUSE, Kerberos, X Window System, and Zephyr are trademarks
85 of MIT. No commercial use of these trademarks may be made without prior
86 written permission of MIT.
88 All other product names are trademarks of their respective companies.
92 @node Top, Introduction, (dir), (dir)
93 @comment node-name, next, previous, up
96 This file documents how to build and install the Kerberos V5
99 This is edition @value{EDITION}, for Kerberos V5 version @value{VERSION}.
103 @c The master menu is updated using emacs19's M-x texinfo-all-menus-update
104 @c function. Don't forget to run M-x texinfo-every-node-update after
105 @c you add a new section or subsection, or after you've rearranged the
106 @c order of sections or subsections. Also, don't forget to add an @node
107 @c command before each @section or @subsection! All you need to enter
110 @c @node New Section Name
112 @c @section New Section Name
114 @c M-x texinfo-every-node-update will take care of calculating the
115 @c node's forward and back pointers.
120 * How Kerberos Works::
121 * Building Kerberos::
125 --- The Detailed Node Listing ---
127 How Kerberos Works: A Schematic Description
131 * The Kerberos Database::
133 * The Ticket-Granting Ticket::
134 * Network Services and the Master Database::
135 * The User-Kerberos Interaction::
137 Network Services and the Master Database
143 * Build Requirements:: How much disk space, etc. you need to
145 * Unpacking the Sources:: Preparing the source tree.
146 * Doing the Build:: Compiling Kerberos.
147 * Testing the Build:: Making sure Kerberos built correctly.
148 * Options to Configure::
150 * Shared Library Support::
151 * OS Incompatibilities:: Special cases to watch for.
152 * Using Autoconf:: Modifying Kerberos V5's
153 configuration scripts.
157 * Building Within a Single Tree::
158 * Building with Separate Build Directories::
159 * Building using lndir::
163 * The DejaGnu Tests::
165 Shared Library Support
167 * Shared Library Theory::
168 * NetBSD Shared Library Support::
169 * AIX Shared Library Support::
170 * Solaris 5.3 Shared Library Support::
171 * Alpha OSF/1 Shared Library Support::
173 Operating System Incompatibilities
177 * Alpha OSF/1 V2.0++::
179 * Solaris versions 2.0 through 2.3::
186 * Installation on any Machine::
187 * Installing the KDC::
188 * Migrating from V4 to V5 Kerberos::
189 * A Sample Application::
190 * Installing Kerberos Applications::
191 * Common Kerberos Service Names::
193 Installation on any Machine
195 * Picking a Realm Name::
196 * Configuration files::
197 * Recommended Programs::
202 * Converting V4 configuration files::
208 * Initializing the KDB::
209 * Storing the Master Password::
210 * Adding Users to the Database::
211 * Starting the Kerberos Server::
212 * Setting up Slave Kerberos Servers::
213 * Inter-realm Kerberos Operation::
214 * The Administration Server::
215 * Testing the Kerberos Server::
217 Setting up Slave Kerberos Servers
219 * Kerberos Slave Database Propagation::
220 * Installing a Slave Server::
224 * Installing the Sample Application::
225 * Testing the Sample Server::
227 Installing Kerberos Applications
229 * Levels of Security::
230 * Preparing a Workstation for Kerberos Application Servers::
236 * Checksums:: Checksum facility for dealing with active attacks.
237 * BSD Utility Configuration Example:: Sample @file{inetd.conf} entries for BSD utilities.
240 @node Introduction, How Kerberos Works, Top, Top
241 @chapter Introduction
243 This document describes the procedures necessary to compile Kerberos V5
244 from the source distribution, and then to install it at a particular
245 site. The reader is assumed to be familiar with C/UNIX development
248 In any complex software, there will be bugs. Please send bug reports
249 or other problems you may uncover to the e-mail address
250 @b{krb5-bugs@@mit.edu}. Please mention which version of the Kerberos
251 V5 distribution you are using, and whether you have made any private
252 changes. Bug reports that include proposed fixes are especially
253 welcome. If you do include fixes, please send them using either
254 context diffs or unified diffs (using @samp{diff -c} or @samp{diff
257 Please note that there are still a number of aspects of Kerberos V5
258 which will likely change before the 1.0 release.
259 As these changes occur, we will update the documentation accordingly.
261 @c As of this release, all the databases, including the aname to localname
262 @c ones now use version 1.85 of the Berkeley DB code. This may imply
263 @c database conversions for those running earlier releases of Kerberos
264 @c V5. We recommend that you dump your database with the old kdb5_edit and
265 @c restore with the new one.
268 @node How Kerberos Works, Building Kerberos, Introduction, Top
269 @chapter How Kerberos Works: A Schematic Description
271 This section provides a simplified description of a general user's
272 interaction with the Kerberos system. This interaction happens
273 transparently--users don't need to know and probably don't care about
274 what's going on--but Kerberos administrators might find a schematic
275 description of the process useful. This description glosses over a lot
276 of details; for more information, see @i{Kerberos: An Authentication
277 Service for Open Network Systems}, a paper presented at Winter USENIX
278 1988, in Dallas, Texas.
283 * The Kerberos Database::
285 * The Ticket-Granting Ticket::
286 * Network Services and the Master Database::
287 * The User-Kerberos Interaction::
290 @node Network Services, Kerberos Tickets, How Kerberos Works, How Kerberos Works
291 @section Network Services and Their Client Programs
293 In an environment that provides network services, you use @dfn{client}
294 programs to request service from @dfn{server} programs that are
295 somewhere on the network. Suppose you have logged in to a workstation
296 and you want to @samp{rlogin} to another machine. You use the local
297 @samp{rlogin} client program to contact the remote machine's
298 @samp{rlogind} daemon.
300 @node Kerberos Tickets, The Kerberos Database, Network Services, How Kerberos Works
301 @section Kerberos Tickets
303 Under Kerberos, the @samp{rlogind} daemon allows you to login to a
304 remote machine if you can provide @samp{rlogind} a Kerberos ticket
305 which proves your identity. In addition to the ticket, you must also
306 have possession of the corresponding ticket session key. The
307 combination of a ticket and the ticket's session key is known as a credential.
309 Typically, a client program automatically obtains credentials
310 identifying the person using the client program. The credentials are
311 obtained from a Kerberos server that resides somewhere on the network.
312 A Kerberos server maintains a database of user, server, and password
315 @node The Kerberos Database, Kerberos Realms, Kerberos Tickets, How Kerberos Works
316 @section The Kerberos Database
318 Kerberos will give you credentials only if you have an entry in the Kerberos
319 server's @dfn{Kerberos database}. Your database entry includes your
320 Kerberos @dfn{principal} (which is often just your username), and
321 your Kerberos password. Every Kerberos user must have an entry in this
324 @node Kerberos Realms, The Ticket-Granting Ticket, The Kerberos Database, How Kerberos Works
325 @section Kerberos Realms
327 Each site (or administrative domain within a site) will have their own
328 Kerberos database, which contains information about the users and
329 services for that particular site or administrative domain.
330 A @dfn{Kerberos Realm} is used to distinguish the users and services in
331 one particular area of administrative control from another area of
332 administrative control.
334 Each Kerberos realm will have at least one Kerberos server, where the
335 master Kerberos database for that site or administrative domain is
336 stored. A Kerberos realm may also have one or more @dfn{slave servers},
337 which have read-only copies of the Kerberos database which are
338 periodically propagated from the master server. For more details on how
339 this is done, see @ref{Setting up Slave Kerberos Servers}.
341 @node The Ticket-Granting Ticket, Network Services and the Master Database, Kerberos Realms, How Kerberos Works
342 @section The Ticket-Granting Ticket
344 The @samp{kinit} command prompts for your password, and if you enter
345 it successfully, you will obtain a @dfn{ticket-granting ticket} and a
346 @dfn{ticket session key} which gives you the right to use the ticket.
347 This combination of the ticket and its associated key is also known as
348 your @dfn{credentials}. As illustrated below, client programs use
349 your ticket-granting ticket credentials in order to obtain
350 client-specific credentials as needed.
352 Your credentials are stored in a @dfn{credentials cache}, which is often
353 simply just a file in @file{/tmp}. The credentials cache is also
354 referred to as the @dfn{ticket file}, especially in Kerberos V4
355 documentation. It should be noted, however, that a credentials cache
356 does not have to be stored in a file.
358 @node Network Services and the Master Database, The User-Kerberos Interaction, The Ticket-Granting Ticket, How Kerberos Works
359 @section Network Services and the Master Database
361 The master database also contains entries for all network services that
362 require Kerberos authentication. Suppose that your site
363 has a machine, @samp{laughter.mit.edu}, that requires Kerberos
364 authentication from anyone who wants to @samp{rlogin} to it. The host's
365 Kerberos realm is @samp{ATHENA.MIT.EDU}.
367 This service must be registered in the Kerberos database, using the
368 proper service name, which in this case is
369 @samp{host/laughter.mit.edu@@ATHENA.MIT.EDU}. The @kbd{/} character
370 separates the various @dfn{components} of the Kerberos principal; the
371 @kbd{@@} character separates the realm name from the rest of the
372 principal name. The first component, @samp{host}, denotes the name or
373 type of the service that is being offered: generic host-level access to
374 the machine. The second component, @samp{laughter.mit.edu}, names the
375 specific machine which is offering this service. There will generally
376 be many different machines, each offering one particular type of
377 service, and the second component serves to give each one of these
378 servers a different Kerberos name.
384 @node The Keytab File, , Network Services and the Master Database, Network Services and the Master Database
385 @subsection The Keytab File
387 For each service, there must also be a @dfn{service key} known only by
388 Kerberos and the service. On the Kerberos server, the service key is
389 stored in the Kerberos database.
391 On the server host, these service keys are stored in the @dfn{Key
392 tables}, or @dfn{keytab files}. (Keytab files were previously
393 referred to as @dfn{srvtab files} in the V4 literature.) The service
394 keys that are used by services which run as root are often stored in
395 the file @file{/etc/v5srvtab}.
397 @b{WARNING:} This service key is the equivalent of the service's
398 password, and must be kept secure. Data which is meant to be read only
399 by the service is encrypted using this key.
401 @node The User-Kerberos Interaction, , Network Services and the Master Database, How Kerberos Works
402 @section The User--Kerberos Interaction
404 Suppose that you (in the guise of a general user) walk up to a workstation
405 intending to login to it, and then @samp{rlogin} to the machine @samp{laughter}.
411 You login to the workstation and use the @samp{kinit} command
412 to get a ticket-granting ticket.
413 This command prompts you for your Kerberos password. (On some systems
414 which have a modified @samp{/bin/login} program, this may be done as
415 part of the login process, not requiring the user to run a separate
421 The @samp{kinit} command sends your request to the Kerberos master
422 server machine. The server software looks for your principal name's
423 entry in the Kerberos database.
426 If this entry exists, the Kerberos server creates and returns a
427 ticket-granting ticket and the key which allows you to use it, encrypted
428 by your password. If @samp{kinit} can decrypt the Kerberos reply using
429 the password you provide, it stores this ticket in a credentials cache
430 on your local machine for later use. The name of the credentials cache
431 can be specified in the @samp{KRB5_CCNAME} environment variable. If
432 this variable is not set, the name of the file will be
433 @file{/tmp/krb5cc_<uid>}, where <uid> is your UNIX user-id, represented
438 Now you use the @samp{rlogin} client to access the machine
442 host% @b{rlogin laughter}
448 The @samp{rlogin} client checks your ticket file to see if you
449 have a ticket for the @samp{host} service for @samp{laughter}.
450 You don't, so @samp{rlogin} uses the credential cache's ticket-granting
451 ticket to make a request to the master server's ticket-granting service.
454 This ticket-granting service receives the
455 @samp{host/laughter.mit.edu} request and looks in the master database
456 for an @samp{host/laughter.mit.edu} entry. If the entry exists, the
457 ticket-granting service issues you a ticket for that service. That
458 ticket is also cached in your credentials cache.
461 The @samp{rlogin} client now sends that ticket to
462 the @samp{laughter} @samp{rlogind} service program. The service program
463 checks the ticket by using its own service key. If the ticket is valid,
464 it now knows your identity. If the ticket is valid and you are allowed
465 to login to @samp{laughter} (because the your name matches one in
466 /etc/passwd, or you are in the @file{.k5login} file), you will find
467 yourself logged into the machine.
472 @node Building Kerberos, Installation, How Kerberos Works, Top
473 @chapter Building Kerberos
475 Starting with the Beta 4 distribution, we are using a new configuration
476 system, which was built using the Free Software Foundation's
477 @samp{autoconf} program. This system will hopefully make Kerberos V5
478 much simpler to build and reduce the amount of effort required in
479 porting Kerberos V5 to a new platform.
482 * Build Requirements:: How much disk space, etc. you need to
484 * Unpacking the Sources:: Preparing the source tree.
485 * Doing the Build:: Compiling Kerberos.
486 * Testing the Build:: Making sure Kerberos built correctly.
487 * Options to Configure::
489 * Shared Library Support::
490 * OS Incompatibilities:: Special cases to watch for.
491 * Using Autoconf:: Modifying Kerberos V5's
492 configuration scripts.
495 @node Build Requirements, Unpacking the Sources, Building Kerberos, Building Kerberos
496 @section Build Requirements
498 In order to build Kerberos V5, you will need approximately 60-70
499 megabytes of disk space. The exact amount will vary depending on the
500 platform and whether the distribution is compiled with debugging symbol
503 If you wish to keep a separate @dfn{build tree}, which contains the compiled
504 @file{*.o} file and executables, separate from your source tree, you
505 will need a @samp{make} program which supports @samp{VPATH}, or
506 you will need to use a tool such as @samp{lndir} to produce a symbolic
507 link tree for your build tree.
509 @node Unpacking the Sources, Doing the Build, Build Requirements, Building Kerberos
510 @section Unpacking the Sources
512 The first step in each of these build procedures is to unpack the source
513 distribution. The Kerberos V5 distribution comes in two compressed tar
514 files. The first file, which is generally named @file{krb5.src.tar.gz},
515 contains the sources for all of Kerberos except for the crypto library,
516 which is found in the file @file{krb5.crypto.tar.gz}.
518 Both files should be unpacked in the same directory, such as
519 @file{/u1/krb5}. (In the rest of this document, we will assume that you
520 have chosen to unpack the Kerberos V5 source distribution in this
524 @node Doing the Build, Testing the Build, Unpacking the Sources, Building Kerberos
525 @section Doing the Build
527 You have a number of different options in how to build Kerberos. If you
528 only need to build Kerberos for one platform, using a single directory
529 tree which contains both the source files and the object files is the
530 simplest. However, if you need to maintain Kerberos for a large number
531 of platforms, you will probably want to use separate build trees for
532 each platform. We recommend that you look at see @ref{OS
533 Incompatibilities} for notes that we have on particular operating
537 * Building Within a Single Tree::
538 * Building with Separate Build Directories::
539 * Building using lndir::
542 @node Building Within a Single Tree, Building with Separate Build Directories, Doing the Build, Doing the Build
543 @subsection Building Within a Single Tree
545 If you don't want separate build trees for each architecture, then
546 use the following abbreviated procedure.
550 @code{cd /u1/krb5/src}
559 @node Building with Separate Build Directories, Building using lndir, Building Within a Single Tree, Doing the Build
560 @subsection Building with Separate Build Directories
562 If you wish to keep separate build directories for each platform, you
563 can do so using the following procedure. (Note, this requires that your
564 @samp{make} program support @samp{VPATH}. GNU's make will provide this
565 functionality, for example.) If your @samp{make} program does not
566 support this, see the next section.
568 For example, if you wish to create a build directory for @code{pmax} binaries
569 you might use the following procedure:
573 @code{mkdir /u1/krb5/pmax}
575 @code{cd /u1/krb5/pmax}
577 @code{../src/configure}
582 @node Building using lndir, , Building with Separate Build Directories, Doing the Build
583 @subsection Building Using @samp{lndir}
585 If you wish to keep separate build directories for each platform, and
586 you do not have access to a @samp{make} program which supports @samp{VPATH},
587 all is not lost. You can use the @samp{lndir} program to create
588 symbolic link trees in your build directory.
590 For example, if you wish to create a build directory for solaris binaries
591 you might use the following procedure:
595 @code{mkdir /u1/krb5/solaris}
597 @code{cd /u1/krb5/solaris}
599 @code{/u1/krb5/src/util/lndir `pwd`/../src}
606 You must give an absolute pathname to @samp{lndir} because it has a bug that
607 makes it fail for relative pathnames. Note that this version differs
608 from the latest version as distributed and installed by the XConsortium
609 with X11R6. Either version should be acceptable.
611 @node Testing the Build, Options to Configure, Doing the Build, Building Kerberos
612 @section Testing the Build
614 The Kerberos V5 distribution comes with built-in regression tests. To
615 run them, simply type the following command while in the top-level build
616 directory (i.e., the directory where you sent typed @samp{make} to start
617 building Kerberos; see @ref{Doing the Build}.):
624 * The DejaGnu Tests::
627 @node The DejaGnu Tests, , Testing the Build, Testing the Build
628 @subsection The DejaGnu Tests
630 Some of the built-in regression tests are setup to use the DejaGnu
631 framework for running tests. These tests tend to be more comprehensive
632 than the normal built-in tests as they setup test servers and test
633 client/server activities.
635 DejaGnu may be found wherever GNU software is archived.
637 Most of the tests are setup to run as a non-privledged user. There are
638 two series of tests (@samp{rlogind} and @samp{telnetd}) which require
639 the ability to @samp{rlogin} as root to the local machine. Admittedly,
640 this does require the use of a @file{.rhosts} file or some other
641 authenticated means. @footnote{If you are fortunate enough to have a
642 previous version of Kerberos V5 or V4 installed, and the Kerberos rlogin
643 is first in your path, you can setup @file{.k5login} or @file{.klogin}
644 respectively to allow you access.}
646 If you cannot obtain root access to your machine, all the other tests
647 will still run. Note however, with DejaGnu 1.2, the "untested testcases"
648 will cause the testsuite to exit with a non-zero exit status which
649 @samp{make} will consider a failure of the testing process. Do not worry
650 about this, as these tests are the last run when @samp{make check} is
651 executed from the top level of the build tree.
654 @node Options to Configure, osconf.h, Testing the Build, Building Kerberos
655 @section Options to Configure
657 There are a number of options to @samp{configure} which you can use to
658 control how the Kerberos distribution is built. The following table
659 lists the most commonly used options to Kerberos V5's @samp{configure}
666 Provides help to configure. This will list the set of commonly used
667 options for building Kerberos.
671 By default, Kerberos will install the package's files rooted at
672 `/usr/local' as in `/usr/local/bin', `/usr/local/sbin', etc. If you
673 desire a different location use this option.
675 @item --exec-prefix=DIR
677 This option allows one to separate the architecture independent programs
678 from the configuration files and manual pages.
680 @item --with-cc=COMPILER
682 Use @code{COMPILER} as the C compiler.
684 @item --with-ccopts=FLAGS
686 Use @code{FLAGS} as the default set of C compiler flags.
688 Note that if you use the native Ultrix compiler on a
689 DECstation you are likely to lose if you pass no flags to cc; md4.c
690 takes an estimated 3,469 billion years to compile if you provide neither
691 the @samp{-g} flag nor the @samp{-O} flag to @samp{cc}.
693 @item --with-cppopts=CPPOPTS
695 Use @code{CPPOPTS} as the default set of C preprocessor flags. The most
696 common use of this option is to select certain @code{#define}'s for use
697 with the operating system's include files.
699 @item --with-linker=LINKER
701 Use @code{LINKER} as the default loader if it should be different from C
702 compiler as specified above.
704 @item --with-ldopts=LDOPTS
706 This option allows one to specify optional arguments to be passed to the
707 linker. This might be used to specify optional library paths.
711 This option enables Kerberos V4 backwards compatibility using the
712 builtin Kerberos V4 library.
714 @item --with-krb4=KRB4DIR
716 This option enables Kerberos V4 backwards compatibility. The directory
717 specified by @code{KRB4DIR} specifies where the V4 header files should
718 be found (@file{/KRB4DIR/include}) as well as where the V4 Kerberos
719 library should be found (@file{/KRB4DIR/lib}).
723 Disables Kerberos V4 backwards compatibility. This prevents Kerberos V4
724 clients from using the V5 services including the KDC. This would be
725 useful if you know you will never install or need to interact with V4
728 @item --with-netlib[=libs]
730 Allows for suppression of or replacement of network libraries. By
731 default, Kerberos V5 configuration will look for @code{-lnsl} and
732 @code{-lsocket}. If your operating system has a broken resolver library
733 (see @ref{Solaris versions 2.0 through 2.3}) or fails to pass the tests in
734 @file{src/tests/resolv} you will need to use this option.
736 @item --enable-shared
738 This option will turn on the building and use of shared library objects
739 in the Kerberos build. This option is only supported on certain
742 @item --with-vague-errors
744 If enabled, gives vague and unhelpful error messages to the client... er,
745 attacker. (Needed to meet silly government regulations; most other
746 sites will want to keep this undefined.)
748 @item --with-kdc-kdb-update
750 Set this option if you want to allow the KDC to modify the Kerberos
751 database; this allows the last request information to be updated, as
752 well as the failure count information. Note that this doesn't work if
753 you're using slave servers!!! It also causes the database to be
754 modified (and thus needing to be locked) frequently. Please note that
755 the implementors do not regularly test this feature.
757 @item --with-kdb-db=database
759 The configuration process will try to determine a working set of
760 libraries required to implement the Kerberos database. Configure will
761 look for interfaces that use or emulate a @samp{ndbm} or @samp{dbm}
762 library. Failing that, a build in copy of the Berkeley DB code will be
763 used. You may decide to compile a different interface than the default
764 by specifying one of "ndbm", "dbm", or "db".
766 An important note on platforms where the @samp{ndbm} implementation is
767 based on @sc{GDBM} (such as the Linux Slackware distribution). @sc{GDBM}
768 has its own built in file locking which prevents simultaneous access to
769 the database from two separate processes in which one wants to modify
770 the database while the otherone only wants to read. (i.e. the KDC and
771 administrative servers). In this case, you will need to specify the use
776 For example, in order to configure Kerberos on a Solaris machine using
777 the @samp{suncc} with the optimizer turned on, run the configure
778 script with the following options:
781 % ./configure --with-cc=suncc --with-ccopts=-O
784 @node osconf.h, Shared Library Support, Options to Configure, Building Kerberos
785 @section @file{osconf.h}
787 There is one configuration file which you may wish to edit to control
788 various compile-time parameters in the Kerberos distribution:
789 @file{include/stock/osconf.h}. The list that follows is by no means
790 complete, just some of the more interesting variables.
792 Please note: The former configuration file @file{config.h} no longer
793 exists as its functionality has been merged into the auto-configuration
794 process. @xref{Options to Configure}.
799 @item DEFAULT_PROFILE_PATH
801 The pathname to the file which contains the profiles for the known
802 realms, their KDCs, etc.
804 The profile file format is no longer the same format as Kerberos V4's
805 @file{krb.conf} file.
807 @item DEFAULT_LNAME_FILENAME
809 The pathname to the database that maps authentication names to local
810 account names. See kdb5_anadd(8).
812 @item DEFAULT_KEYTAB_NAME
814 The type and pathname to the default server keytab file (the equivalent
815 of Kerberos V4's @file{/etc/srvtab}).
817 @item DEFAULT_KDC_ENCTYPE
819 The default encryption type for the KDC.
823 The name of the replay cache used by the KDC.
827 The directory which stores replay caches.
829 @item DEFAULT_KDB_FILE
831 The location of the default database
835 @node Shared Library Support, OS Incompatibilities, osconf.h, Building Kerberos
836 @section Shared Library Support
838 Shared library support is provided for a few operating systems. There
839 are restrictions as to which compiler to use when using shared
840 libraries. In all cases, executables linked with the shared libraries in
841 this build process will have built in the location of the libraries,
842 therefore obliterating the need for special LD_LIBRARY_PATH, et al environment
843 variables when using the programs. Except where noted, multiple versions
844 of the libraries may be installed on the same system and continue to
847 Currently the supported platforms are: NetBSD 1.0A, AIX 3.2.5, AIX 4.1,
848 Solaris 5.3, Alpha OSF/1 >= 2.1, HP-UX >= 9.X.
850 To enable shared libraries on the above platforms, run the configure
851 script with the option @samp{--enable-shared}.
853 One special note is that if the Kerberos V4 compatibility is compiled
854 in, you @b{must not} specify an alternate Kerberos V4 library from the
855 one in the tree or you will be missing references.
858 * Shared Library Theory::
859 * NetBSD Shared Library Support::
860 * AIX Shared Library Support::
861 * Solaris 5.3 Shared Library Support::
862 * Alpha OSF/1 Shared Library Support::
865 @node Shared Library Theory, NetBSD Shared Library Support, Shared Library Support, Shared Library Support
866 @subsection Theory of How Shared Libraries are Used
868 An explanation of how shared libraries are implemented on a given
869 platform is too broad a topic for this manual. Instead this will touch
870 on some of the issues that the Kerberos V5 tree uses to support version
871 numbering and alternate install locations.
873 Normally when one builds a shared library and then links with it, the
874 name of the shared library is stored in the object
875 (i.e. libfoo.so). Most operating systems allows one to change name that
876 is referenced and we have done so, placing the version number into the
877 shared library (i.e. libfoo.so.0.1). At link time, one would reference
878 libfoo.so, but when one executes the program, the shared library loader
879 would then look for the shared library with the alternate name. Hence
880 multiple versions of shared libraries may be supported relatively
881 easily. @footnote{Under AIX for the RISC/6000, multiple versions of
882 shared libraries are supported by combining two or more versions of the
883 shared library into one file. The Kerberos build procedure produces
884 shared libraries with version numbers in the internal module names, so
885 that the shared libraries are compatible with this scheme.
886 Unfortunately, combining two shared libraries requires internal
887 knowledge of the AIX shared library system beyond the scope of this
888 document. Practicallyspeaking, only one version of AIX shared libraries
889 can be supported on a system, unless the multi-version library is
890 constructed by a programmer familiar with the AIX internals.}
892 All operating systems (that we have seen) provide a means for programs
893 to specify the location of shared libraries. On different operating
894 systems, this is either specified when creating the shared library, and
895 link time, or both.@footnote{Both are necessary sometimes as the shared
896 libraries are dependent on other shared libraries} The build process
897 will hardwire a path to the installed destination.
900 @node NetBSD Shared Library Support, AIX Shared Library Support, Shared Library Theory, Shared Library Support
901 @subsection NetBSD Shared Library Support
903 Shared library support has been tested under NetBSD 1.0A using
904 GCC 2.4.5. Due to the vagaries of the loader in the operating system,
905 the library load path needs to be specified in building libraries and in
906 linking with them. Unless the library is placed in a standard location
907 to search for libraries, this may make it difficult for developers to
908 work with the shared libraries.
910 @node AIX Shared Library Support, Solaris 5.3 Shared Library Support, NetBSD Shared Library Support, Shared Library Support
911 @subsection AIX Shared Library Support
913 AIX specifies shared library versions by combining multiple
914 versions into a single file. Because of the complexity of this process,
915 no automatic procedure for building multi-versioned shared libraries is
916 provided. Therefore, supporting multiple versions of the Kerberos shared
917 libraries under AIX will require significant work on the part of a
918 programmer famiiliar with AIX internals.
920 AIX allows a single library to be used both as a static library
921 and as a shared library. For this reason, the @samp{--enable-shared}
922 switch to configure builds only shared libraries. On other operating
923 systems, both shared and static libraries are built when this switch is
924 specified. As with all other operating systems, only non-shared static
925 libraries are built when @samp{--enable-shared} is not specified.
927 The AIX 3.2.5 linker dumps core trying to build a shared
928 @samp{libkrb5.a} produced with the GNU C compiler. The native AIX
929 compiler works fine. In addition, the AIX 4.1 linker is able to build a
930 shared @samp{libkrb5.a} when GNU C is used.
933 @node Solaris 5.3 Shared Library Support, Alpha OSF/1 Shared Library Support, AIX Shared Library Support, Shared Library Support
934 @subsection Solaris 5.3 Shared Library Support
936 Shared library support only works when using the Sunsoft C compiler. We
937 are currently using version 3.0.1.
939 The path to the shared library must be specified at link time as well as
940 when creating libraries.
942 @node Alpha OSF/1 Shared Library Support, , Solaris 5.3 Shared Library Support, Shared Library Support
943 @subsection Alpha OSF/1 Shared Library Support
945 Shared library support has been tested with V2.1 and higher of the
946 operating system. Shared libraries may be compiled both with GCC and the
949 One of the nice features on this platform is that the paths to the
950 shared libraries is specified in the library itself without requiring
951 that one specify the same at link time.
953 We are using the @samp{-rpath} option to @samp{ld} to place the library
954 load path into the executables. The one disadvantage of this is during
955 testing where we want to make sure that we are using the build tree
956 instead of a possibly installed library. The loader uses the contents of
957 @samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT
958 and complete LD_LIBRARY_PATH in our tests.
960 The one disadvantage with the
963 @node OS Incompatibilities, Using Autoconf, Shared Library Support, Building Kerberos
964 @section Operating System Incompatibilities
966 This section details operating system incompatibilities with Kerberos V5
967 which have been reported to the developers at MIT. If you find additional
968 incompatibilities, and/or discover work arounds to such problems, please
969 send a report to @b{krb5-bugs@@mit.edu}. Thanks!
974 * Alpha OSF/1 V2.0++::
976 * Solaris versions 2.0 through 2.3::
981 @node Ultrix 4.2/3, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities
982 @subsection Ultrix 4.2/3
984 On the DEC MIPS platform, using the native compiler, @file{md4.c} and
985 @file{md5.c} can not be compiled with the optimizer set at level 1.
986 That is, you must specify either @samp{--with-ccopts=-O} and
987 @samp{--with-ccopts=-g} to configure. If you don't specify either, the
988 compile will never complete.
990 The optimizer isn't hung; it just takes an exponentially long time.
991 Compiling 6 out of the 48 algorithmic steps takes 3 seconds; compiling 7
992 steps takes 9 seconds; compiling 8 steps takes 27 seconds, and so on.
993 Calculations estimate it will finish in approximately 3,469 billion
996 Using GCC instead of the native compiler will also work fine, both with
997 or without optimization.
999 @node Alpha OSF/1 V1.3, Alpha OSF/1 V2.0++, Ultrix 4.2/3, OS Incompatibilities
1000 @subsection Alpha OSF/1 V1.3
1002 Using the native compiler, compiling with the @samp{-O} compiler flag
1003 causes the @code{asn.1} library to be compiled incorrectly.
1005 Using GCC version 2.6.3 or later instead of the native compiler will also work
1006 fine, both with or without optimization.
1008 @node Alpha OSF/1 V2.0++, BSDI, Alpha OSF/1 V1.3, OS Incompatibilities
1009 @subsection Alpha OSF/1 V2.0++
1011 There used to be a bug when using the native compiler in compiling
1012 @file{md4.c} when compiled without either the @samp{-O} or @samp{-g}
1013 compiler options. We have changed the code and there is no problem
1014 under V2.1, but we do not have access to V2.0 to test and see if the
1015 problem would exist there. (We welcome feedback on this issue). There
1016 was never a problem in using GCC version 2.6.3.
1018 In version 3.2 and beyond of the operating system, we have not seen any
1019 problems with the native compiler.
1021 @node BSDI, Solaris versions 2.0 through 2.3, Alpha OSF/1 V2.0++, OS Incompatibilities
1024 BSDI versions 1.0 and 1.1 reportedly has a bad @samp{sed} which causes
1025 it to go into an infinite loop during the build. The work around is
1026 to use a @samp{sed} from somewhere else, such as GNU. (This may be
1027 true for some versions of other systems derived from BSD 4.4, such as
1028 NetBSD and FreeBSD.)
1030 @node Solaris versions 2.0 through 2.3, Solaris 2.X, BSDI, OS Incompatibilities
1031 @subsection Solaris versions 2.0 through 2.3
1033 The @code{gethostbyname()} routine is broken; it does not return a fully
1034 qualified domain name, even if you are using the Domain Name Service
1035 routines. Since Kerberos V5 uses the fully qualified domain name as the
1036 second component of a service principal (i.e,
1037 @samp{host/tsx-11.mit.edu@@ATHENA.MIT.EDU}), this causes problems for servers
1038 who try to figure out their own fully qualified domain name.
1045 Supply your own resolver library. (such as bind-4.9.3pl1 availavle
1049 Upgrade to Solaris 2.4
1052 Make sure your /etc/nsswitch.conf has `files' before `dns' like:
1058 and then in /etc/hosts, make sure there is a line with your
1059 workstation's IP address and hostname, with the fully qualified domain
1060 name first. Example:
1063 18.172.1.4 dcl.mit.edu dcl
1066 Note that making this change may cause other programs in your
1067 environment to break or behave differently.
1071 @node Solaris 2.X, SGI Irix 5.X, Solaris versions 2.0 through 2.3, OS Incompatibilities
1072 @subsection Solaris 2.X
1074 You @b{must} compile Kerberos V5 without the UCB compatibility
1075 libraries. This means that @file{/usr/ucblib} must not be in the
1076 LD_LIBRARY_PATH environment variable when you compile it. Alternatively
1077 you can use the @code{-i} option to @samp{cc}, by using the specifying
1078 @code{--with-ccopts=-i} option to @samp{configure}.
1080 @node SGI Irix 5.X, , Solaris 2.X, OS Incompatibilities
1081 @subsection SGI Irix 5.X
1083 If you are building in a tree separate from the source tree, the vendors
1084 version of make does not work properly with regards to
1085 @samp{VPATH}. It also has problems with standard inference rules in 5.2
1086 (not tested yet in 5.3) so one needs to use GNU's make.
1088 Under 5.2, there is a bug in the optional System V @code{-lsocket}
1089 library in which the routine @code{gethostbyname()} is broken. The
1090 system supplied version in @code{-lc} appears to work though so one may
1091 simply specify @code{--with-netlib} option to @samp{configure}.
1093 In 5.3, @code{gethostbyname()} is no longer present in @code{-lsocket} and
1094 is no longer an issue.
1096 @node Using Autoconf, , OS Incompatibilities, Building Kerberos
1097 @section Using @samp{Autoconf}
1099 (If you are not a developer, you can skip this section.)
1101 In most of the Kerberos V5 source directories, there is a
1102 @file{configure} script which automatically determines the compilation
1103 environment and creates the proper Makefiles for a particular platform.
1104 These @file{configure} files are generated using @samp{autoconf} version
1105 2.4, which can be found in the @file{src/util/autoconf} directory in the
1108 Normal users will not need to worry about running @samp{autoconf}; the
1109 distribution comes with the @file{configure} files already prebuilt.
1110 Developers who wish to modify the @file{configure.in} files should see
1111 @ref{Top, , Overview, autoconf, The Autoconf Manual}.
1113 Note that in order to run @samp{autoconf}, you must have GNU @samp{m4}
1114 in your path. Before you use the @samp{autoconf} in the Kerberos V5
1115 source tree, you may also need to run @samp{configure}, and then run
1116 @samp{make} in the @file{src/util/autoconf} directory in order to
1117 properly set up @samp{autoconf}.
1119 One tool which is provided for the convenience of developers can be
1120 found in @file{src/util/reconf}. This program should be run while the
1121 current directory is the top source directory. It will automatically
1122 rebuild any @file{configure} files which need rebuilding. If you know
1123 that you have made a change that will require that all the
1124 @file{configure} files need to be rebuilt from scratch, specify the
1125 @code{--force} option:
1129 % ./util/reconf --force
1132 The developmental sources are a raw source tree (before it's been packaged
1133 for public release), without the pre-built @file{configure} files.
1134 In order to build from such a source tree, you must do:
1137 % cd krb5/util/autoconf
1144 Then follow the instructions for building packaged source trees (above).
1145 To install the binaries into a binary tree, do:
1150 % make install DESTDIR=somewhere-else
1153 @node Installation, Troubleshooting, Building Kerberos, Top
1154 @chapter Installation
1156 When you are installing Kerberos for the first time at a site, you must
1157 first decide on the realm name you will use for your site, and select a
1158 machine to host the @dfn{Kerberos server}, which is also known as the
1159 @dfn{KDC} (@dfn{Key Distribution Center}). The KDC must be located on a
1160 secure machine, since its database contains the keys for the entire
1161 realm. It is extremely important that the database be kept secure, if
1162 the realm's Kerberos service is to remain secure.
1164 Once a KDC is installed and configured, you may then set up one or more
1165 client machines, and one or more application machines.
1169 * Installation on any Machine::
1170 * Installing the KDC::
1171 * Migrating from V4 to V5 Kerberos::
1172 * A Sample Application::
1173 * Installing Kerberos Applications::
1174 * Common Kerberos Service Names::
1177 @node Background, Installation on any Machine, Installation, Installation
1178 @section Background Information
1180 Your system's security is only as good as the security of your
1181 @samp{root} password. You should take other precautions to protect your
1182 system security in addition to installing Kerberos. Kerberos cannot
1183 protect you from someone who is able to steal @samp{root} privileges.
1184 Kerberos also does not protect you from break-ins caused by bugs in your
1185 daemons (e.g., @samp{fingerd} or @samp{sendmail}). On almost all UNIX
1186 systems, if intruders can break in as an ordinary users, they can obtain
1187 superuser privileges by exploiting bugs or imperfect configuration files.
1190 @node Installation on any Machine, Installing the KDC, Background, Installation
1191 @section Installation on any Machine
1193 The following steps must be performed no matter what type of
1194 machine (KDC, Client, or Application server) you are installing. All
1195 machines functioning within the same administrative domain must use the
1196 same Kerberos realm name; and all machines which are using Kerberos must
1197 have the Kerberos configuration files properly installed.
1199 If you are installing Kerberos on a machine that will act only as a
1200 Kerberos client, this section describes all that you need to do. If you
1201 are installing a KDC, or an Kerberos Application server, you will also
1202 need to complete the procedures detailed in @ref{Installing the KDC}, or
1203 @ref{A Sample Application}, after you finish with the procedures found
1207 * Picking a Realm Name::
1208 * Configuration files::
1209 * Recommended Programs::
1212 @node Picking a Realm Name, Configuration files, Installation on any Machine, Installation on any Machine
1213 @subsection Picking a Realm Name
1215 Before you install Kerberos V5 at your site, you have to choose a
1216 @dfn{realm name}, the name that specifies the system's administrative
1217 domain. By convention, we suggest that you use your internet domain
1218 name, in capital letters. (Kerberos realm names are case-sensitive, so
1219 it's important that your realm name be in all upper case.) For example,
1220 if your internet domain is @code{cygnus.com} (so that you have hostnames
1221 such as @code{ftp.cygnus.com} and @code{tweedledum.cygnus.com}), then
1222 your Kerberos realm should be @code{CYGNUS.COM}. Please note that
1223 changing realm names is hard. Get it right the first time.
1225 @node Configuration files, Recommended Programs, Picking a Realm Name, Installation on any Machine
1226 @comment node-name, next, previous, up@section
1227 @subsection Configuration files
1232 * Converting V4 configuration files::
1236 @node krb5.conf, Converting V4 configuration files, Configuration files, Configuration files
1237 @subsubsection The @file{krb5.conf} File
1239 The @file{krb5.conf} file contains information needed by the Kerberos V5
1240 library including a system's default Kerberos
1241 realm, and the locations of the Kerberos servers.
1243 The @file{krb5.conf} uses an INI-style format. Sections are delimited by
1244 square braces; within each section, there are relations where tags can
1245 be assigned to have specific values. Tags can also contain a
1246 subsection, which contains further relations or subsections. A tag can
1247 be assigned to multiple values.
1249 Create a @file{/etc/krb5.conf} file using the following format:
1253 default_realm = <realm_name>
1257 kdc = <master_server_name>
1258 admin_server = <master_server_name>
1259 default_domain = <domain_name>
1263 <.domain.name> = <realm_name>
1266 Where @samp{realm_name} specifies the default realm to be used by that
1267 particular system, and @samp{master_server_name} specifies the machine
1268 name on which you will run the master server. The keywords @samp{kdc}
1269 and @samp{admin_server} lists the location of the realms KDC and
1270 administration servers.
1272 For example, if your realm name is @samp{ATHENA.MIT.EDU} and your master
1273 server's name is @samp{kerberos.mit.edu}, the file should have these
1278 default_realm = ATHENA.MIT.EDU
1282 kdc = KERBEROS.MIT.EDU
1283 admin_server = KERBEROS.MIT.EDU
1284 default_domain = MIT.EDU
1288 .mit.edu = ATHENA.MIT.EDU
1289 mit.edu = ATHENA.MIT.EDU
1293 In many situations, the default realm in which a host operates will be
1294 identical to its Internet domain name, with the first component removed
1295 and all letters capitalized. For example, @code{ftp.cygnus.com} is
1296 traditionally in the realm @code{CYGNUS.COM}.
1297 If this is not the case, you will need to establish a translation from
1298 host name or domain name to realm name. This is accomplished with the
1299 @samp{[domain_realm]} stanza.
1301 Each line of the translation file specifies either a host name or domain
1302 name, and its associated realm:
1306 <.domain.name> = KERBEROS.REALM1
1307 <host.name> = KERBEROS.REALM2
1310 For example, to map all hosts in the domain LSC.MIT.EDU to LSC.MIT.EDU
1311 but the host FILMS.LSC.MIT.EDU to MIT.EDU your file would read:
1314 .LSC.MIT.EDU = LSC.MIT.EDU
1315 FILMS.LSC.MIT.EDU = MIT.EDU
1318 If a particular host name matches both a domain name and a host name in
1319 @samp{[domain_realm]}, the entry containing the host name takes precedence.
1321 See the @file{[SOURCE_DIR]/config-files/krb5.conf} file for an example
1322 @file{krb5.conf} file. That file has examples of how to provide backup
1323 servers for a given realm (additional lines with the same leading realm
1324 name) and how to designate servers for remote realms.
1326 @node Converting V4 configuration files, /etc/services, krb5.conf, Configuration files
1327 @subsubsection Conversion of V4 configuration files
1329 Kerberos V4's @file{krb.conf} and @file{krb.realms} files formats are no
1330 longer used by the V5 library. A @sc{PERL} script has been provided to allow
1331 for "easy" generation of an initial @file{krb5.conf}. It is located in
1332 @file{[SOURCE_DIR]/config-files/convert-config-files}. The produced file
1333 should be checked for errors.
1335 Note that if you are planning on using certain applications with
1336 Kerberos V4 compatibility compiled in, the V4 library still needs the
1337 files @file{krb.conf} and @file{krb.realms}.
1340 @node /etc/services, , Converting V4 configuration files, Configuration files
1341 @subsubsection /etc/services
1343 All hosts which will use Kerberos will need to have certain ports
1344 defined in the system's @file{/etc/services} file. The file
1345 @file{[SOURCEDIR]/config-files/services.append} contains the entries
1346 which should be appended to the @file{/etc/services} file. Please note
1347 that not all of the entries are required as several of the programs have
1348 defaults built into the programs. This will be documented sometime in
1351 If you are using the Network Information Services (NIS) or Yellow
1352 Pages (YP), you will need to add the services in the
1353 @file{services.append} file to the services exported in the NIS or YP
1356 @node Recommended Programs, , Configuration files, Installation on any Machine
1357 @subsection Recommended Programs
1359 The following files should be installed on all machines which are
1360 running Kerberos, either as a client, a KDC, or an application server:
1362 If you used the default @samp{make install} without using the
1363 @samp{--prefix} argument to @file{configure}, then [K_USER] refers to
1364 @file{/usr/local/bin}.
1367 @item @file{/etc/krb5.conf} --- This files contains information required
1368 by Kerberos V5 giving system defaults as well as locations of Kerberos
1370 @item @file{[K_USER]/kinit} --- This program allows you to obtain
1371 Kerberos credentials.
1372 @item @file{[K_USER]/kdestroy} --- This program allows you to destroy
1373 Kerberos credentials which are no longer needed.
1374 @item @file{[K_USER]/klist} ---- This program allows you to list the
1375 credentials found in your credentials cache.
1378 @node Installing the KDC, Migrating from V4 to V5 Kerberos, Installation on any Machine, Installation
1379 @section Installing the KDC
1383 * Initializing the KDB::
1384 * Storing the Master Password::
1385 * Adding Users to the Database::
1386 * Starting the Kerberos Server::
1387 * Setting up Slave Kerberos Servers::
1388 * Inter-realm Kerberos Operation::
1389 * The Administration Server::
1390 * Testing the Kerberos Server::
1393 @node kdc.conf, Initializing the KDB, Installing the KDC, Installing the KDC
1394 @subsection The optional @file{kdc.conf} profile
1396 There is an optional configuration file @file{kdc.conf} that allows one
1397 to specify per-realm configuration data to be used by the Kerberos V5
1398 Authentication Service and Key Distribution Center. This information
1399 includes database locations, key and per-realm defaults, port numbers,
1400 ticket life times, etc. The location of the configuration file is
1401 @file{/usr/local/lib/krb5kdc/kdc.conf}.
1403 See the man page or @file{[SOURCEDIR]/config-files/kdc.conf.M} for more
1406 This document assumes that you do not have the @file{kdc.conf}
1407 configuration file installed.
1409 Note also that @code{[logging]} subsection to @file{/etc/krb5.conf} can
1410 be used to specify where to syslog messages regarding server activity.
1412 @node Initializing the KDB, Storing the Master Password, kdc.conf, Installing the KDC
1413 @subsection Initializing the Kerberos Database
1415 Login to the Kerberos KDC, and use the @samp{su} command to become root.
1416 If you installed the Kerberos administration tools
1417 with the @samp{make install} command and the default pathnames,
1418 they should be in the @file{/usr/local/admin} directory.
1419 If you installed the tools in a different directory,
1420 hopefully you know what it is.
1421 From now on, we will refer to this directory as [ADMIN_DIR].
1423 The default database will be located in the directory
1424 @file{/usr/local/lib/krb5kdc} unless changed in the configuration
1425 process. From now on, we will call this [DB_DIR].
1427 The @samp{kdb5_create} command creates and initializes the master database.
1428 It asks you to the database's master password.
1429 Do not forget this password.
1430 If you do, the database becomes useless.
1431 (Your realm name should be substituted for [REALMNAME] below.)
1432 @xref{Storing the Master Password} for an alternative way of dealing
1433 with this master password.
1435 Because the install process does not create [DB_DIR] you need to do so
1438 Use @samp{kdb5_create} as follows:
1441 # @b{mkdir [DB_DIR]}
1442 # @b{[ADMIN_DIR]/kdb5_create}
1443 Initializing database '[DB_DIR]/principal' for realm '[REALMNAME]',
1444 master key name 'K/M@@[REALMNAME]'
1445 You will be prompted for the database Master Password.
1446 It is important that you NOT FORGET this password.
1447 Enter KDC database master key: @b{<-- [Enter the master password.]}
1448 Re-enter KDC database master key to verify: @b{<-- [Re-enter it.]}
1452 @node Storing the Master Password, Adding Users to the Database, Initializing the KDB, Installing the KDC
1453 @subsection Storing the Master Password
1455 The @samp{kdb5_stash} command "stashes" the master password in the file
1456 @file{[DB_DIR]/.k5.[REALM.NAME]} so that the Kerberos server can be started
1457 automatically during an unattended reboot of the master server. Other
1458 administrative programs use this hidden password so that they can access
1459 the master database without someone having to manually provide the
1460 master password. This command is an optional one; if you'd rather enter
1461 the master password each time you start the Kerberos server, don't use
1464 On the one hand, if you use @samp{kdb5_stash}, a copy of the master key
1465 will reside on a disk, which may not be acceptable; on the other hand,
1466 if you don't use @samp{kdb5_stash}, the server cannot be started unless
1467 someone is around to type the password manually.
1469 The command merely prompts for the master password:
1472 # @b{[ADMIN_DIR]/kdb5_stash}
1473 Enter KDC database master key: @b{<-- [Enter the master password.]}
1476 WARNING: If your Kerberos database master key is compromised and the
1477 database is obtained, the security of your entire authentication system
1478 is compromised. (If this happens to you, all of your user's passwords must
1479 be set to new values manually --- i.e., not using Kerberos.) The master
1480 key must be a carefully kept secret. If you keep backups, you must
1481 guard all the master keys you use, in case someone has stolen an old
1482 backup and wants to attack users' whose passwords haven't changed since
1483 the backup was stolen. This is why we provide the option not to store
1486 @node Adding Users to the Database, Starting the Kerberos Server, Storing the Master Password, Installing the KDC
1487 @subsection Adding Users to the Database
1489 The @samp{kdb5_edit} program may be used to add new users and services to
1490 the master database, and to modify existing database
1491 information. @xref{The Administration Server} for an alternative method
1492 once the Kerberos environment is up and running.
1494 For example, to add yourself to the newly created database: (replace
1495 @samp{[USERNAME]} with your username with.
1498 # @b{[ADMIN_DIR]/kdb5_edit}
1499 kdb5_edit: @b{ank [USERNAME]}
1500 Enter password: @b{<-- [Enter your password.]}
1501 Re-enter password for verification: @b{<-- [Re-enter it.]}
1505 The @samp{ank} command is short for "add_new_key"; this command adds a
1506 new user to the database. To see what other commands which @samp{kdb5_edit}
1507 supports, type @kbd{? @key{RET}} at the @samp{kdb5_edit} prompt.
1509 @node Starting the Kerberos Server, Setting up Slave Kerberos Servers, Adding Users to the Database, Installing the KDC
1510 @subsection Starting the Kerberos Server
1512 Assuming that you didn't use the @samp{--prefix} argument to
1513 @file{configure}, then [K_SERVER] refers to @file{/usr/local/sbin}.
1515 In order to start the Kerberos server, simply run it. It will fork and
1516 disassociate from the terminal unless the @samp{-n} argument is used.
1519 # @b{[K_SERVER]/krb5kdc}
1522 If you have used the @samp{kdb5_stash} command to store the master database password,
1523 the server will start automatically.
1524 If you did not use @samp{kdb5_stash},
1525 use the following command:
1528 # @b{[K_SERVER]/krb5kdc -m}
1531 The server will prompt you to enter the master password before actually
1534 @node Setting up Slave Kerberos Servers, Inter-realm Kerberos Operation, Starting the Kerberos Server, Installing the KDC
1535 @subsection Setting up Slave Kerberos Servers
1537 Slave Kerberos servers allow clients to be able to get Kerberos tickets
1538 even when the Master server is not available. Users will not be able to
1539 change their passwords --- changes can only be made to database on the
1540 Master server; however, users will be able to authenticate to
1541 application servers, which is critically important in a distributed
1542 client-server environment. The current implementation of the client code
1543 does not provide load sharing in that the order of servers contacted is
1544 the same as those listed in the @file{krb5.conf} file.
1547 * Kerberos Slave Database Propagation::
1548 * Installing a Slave Server::
1551 @node Kerberos Slave Database Propagation, Installing a Slave Server, Setting up Slave Kerberos Servers, Setting up Slave Kerberos Servers
1552 @subsubsection Kerberos Slave Database Propagation
1554 In order to propagate the Kerberos database from the Master server to
1555 the slaves, the @samp{kprop} and @samp{kpropd} client/server programs
1556 are used. Periodically, the Master server will dump the Kerberos
1557 database out into an ASCII format, using the @samp{kdb5_edit} program.
1558 The master server will then run @samp{kprop} to propagate the dumped
1559 database file to each slave server.
1561 On the slave server, the @samp{kpropd} program is invoked out of
1562 @samp{inetd} server. After @samp{kprop} and @samp{kpropd} have
1563 mutually authenticated with one another, and @samp{kpropd} is satisfied
1564 with the identity of the Master server, then the dumped ASCII database
1565 is transferred to the slave server in an encrypted fashion. After the
1566 database is transfered, @samp{kpropd} will then run @samp{kdb5_edit}
1567 with the appropriate arguments in order to undump the database into a
1568 usable form by the KDC on the slave server.
1570 @node Installing a Slave Server, , Kerberos Slave Database Propagation, Setting up Slave Kerberos Servers
1571 @subsubsection Installing a Slave Server
1576 @node Inter-realm Kerberos Operation, The Administration Server, Setting up Slave Kerberos Servers, Installing the KDC
1577 @subsection Inter-realm Kerberos Operation
1581 @node The Administration Server, Testing the Kerberos Server, Inter-realm Kerberos Operation, Installing the KDC
1582 @subsection The Administration Server
1584 There is currently an administration server in the Kerberos source tree.
1585 It is, however, very rough, and it will likely be significantly changed
1586 or replaced before the 1.0 release. Hence, this manual does not
1587 document the current administration server. Changes to the database can
1588 be made by logging in to the KDC directly, and using the
1589 @samp{kdb5_edit} program; see @ref{Adding Users to the Database}.
1591 @node Testing the Kerberos Server, , The Administration Server, Installing the KDC
1592 @subsection Testing the Kerberos Server
1594 Use the @samp{kinit} command to obtain Kerberos credentials. This command
1595 creates your credentials cache and stores your credentials in it.
1597 If you used the default @samp{make install} command and directories to
1598 install the Kerberos user utilities, @samp{kinit} will be in the
1599 @file{/usr/local/bin} directory. From now on, we'll refer to the Kerberos user
1600 commands directory as [K_USER].
1602 Use @samp{kinit} as follows:
1605 % @b{[K_USER]/kinit [USERNAME]}
1606 Password for [USERNAME]@@[REALMNAME]: @b{<-- enter your password}
1610 Use the @samp{klist} program to list the contents of your ticket file.
1613 % @b{[K_USER]/klist}
1614 Ticket cache: /tmp/krb5cc_15806
1615 Default principal: [USERNAME]@@[REALMNAME]
1617 Valid starting Expires Service principal
1618 31-Jan-95 21:58:32 1-Feb-95 05:57:39 krbtgt/[REALMMNAME]@@[REALMNAME]
1624 If you have any problems, you can examine the log file
1625 @file{/krb5/kerberos.log} on the Kerberos server machine to see if
1626 there was some sort of error.
1629 @node Migrating from V4 to V5 Kerberos, A Sample Application, Installing the KDC, Installation
1630 @section Migrating from V4 to V5 Kerberos
1632 @b{To be written.} A rough idea of the procedure that one may follow is
1633 in @file{[SOURCE_DIR]/kdc/migration.doc}.
1635 @node A Sample Application, Installing Kerberos Applications, Migrating from V4 to V5 Kerberos, Installation
1636 @section A Sample Application
1638 This release of Kerberos comes with a sample application server and a
1639 corresponding client program. You will find this software
1640 @file{[K_SERVER]/sserver} and @file{[K_USER]/sclient}, which is the
1641 server's executable, and the client program's executable, respectively.
1643 The programs are rudimentary.
1644 When they have been installed (the installation procedure is described
1645 in detail later), they work as follows:
1650 The user starts @samp{sclient} and provides as arguments
1651 to the command the name of the server machine and an optional port on
1652 which to contact the server.
1655 @samp{sclient} contacts the server machine and
1656 authenticates the user to @samp{sserver}.
1659 @samp{sserver} authenticates itself to @samp{sclient} (thus
1660 performing mutual authentication), and
1661 then returns a message to the client program.
1662 This message contains the name of the Kerberos principal that was used
1663 to authenticate to @samp{sserver}.
1666 @samp{sclient} displays the server's message on the user's
1672 * Installing the Sample Application::
1673 * Testing the Sample Server::
1676 @node Installing the Sample Application, Testing the Sample Server, A Sample Application, A Sample Application
1677 @subsection Installing the Sample Application
1680 you use the following procedure to install a Kerberos-authenticated
1681 server-client system.
1686 Add the appropriate entry to the Kerberos database using @samp{kdb_edit}
1689 Create a @file{/etc/v5srvtab} file for the server machine.
1692 Install the service program and the @file{/etc/v5srvtab}
1693 file on the server machine.
1696 Install the client program on the client machine.
1699 Update the @file{/etc/services} file on the client and server machines.
1702 We will use the sample application as an example, although programs
1703 which do not take requests via the @samp{inetd} program may have
1704 slightly different installation procedures. @samp{Inetd} starts
1705 @samp{sserver} each time a client process contacts the server machine.
1706 @samp{sserver} processes the request, terminates, then is restarted
1707 when @samp{inetd} receives another @samp{sserver} request. When you
1708 install the program on the server, you must add a @samp{sample} entry to
1709 the server machine's @file{/etc/inetd.conf} file.
1711 The following description assumes that you are installing
1712 @samp{sserver} on the machine @samp{jimi.mit.edu}.
1713 Here's the process, step by step:
1718 Login as root or @samp{su} to root on the Kerberos server machine.
1719 Use the @samp{kdb5_edit} program to create an entry for
1720 @code{sample} in the Kerberos database:
1723 # @b{[ADMIN_DIR]/kdb5_edit}
1724 kdb5_edit: @b{add_random_key sample/jimi.mit.edu}
1728 (Note: @samp{add_random_key} may be abbreviated as @samp{ark}.)
1731 Use @samp{kdb5_edit} to create a @file{srvtab} file
1732 for @samp{sserver}'s host machine:
1735 # @b{[ADMIN_DIR]/kdb5_edit}
1736 kdb5_edit: @b{extract_srvtab jimi.mit.edu sample}
1737 'sample/jimi.mit.edu@@ATHENA.MIT.EDU' added to keytab 'WRFILE:jimi.mit.edu-new-srvtab'
1741 (Note: @samp{extract_srvtab} may be abbreviated as @samp{xst}.)
1743 Transfer the @file{jimi.mit.edu-new-srvtab} file to @samp{jimi.mit.edu}
1744 and install it as @file{/etc/v5srvtab}.
1746 @b{WARNING}: Note that this file is equivalent to the service's password and
1747 should be treated with care. For example, it could be transferred by
1748 removable media, but should not be sent over an open network in the
1749 clear. This file should installed such that only the root user can read
1753 Add the following line to the @file{/etc/services} file on
1754 @samp{jimi.mit.edu}, and on all machines that will run the
1755 @samp{sample_client} program:
1758 sample 906/tcp # Kerberos sample app server
1762 Add a line similar to the following line to the @file{/etc/inetd.conf}
1763 file on @samp{sample_server}'s machine:
1766 sample stream tcp nowait switched root
1767 [K_SERVER]/sserver sample_server
1770 where [K_SERVER] should be substituted with
1771 the path to the @samp{sserver} program.
1772 (This @file{inetd.conf} information should be placed on one line.)
1773 You should examine existing lines in @file{/etc/inetd.conf} and use the
1774 same format used by other entries (e.g. for telnet). Most systems do
1775 not have a column for the `switched' keyword, and some do not have a
1776 column for the username (usually `root', as above).
1779 Restart @samp{inetd} by sending the current @samp{inetd} process
1783 # @b{kill -HUP} @i{process_id_number}
1787 The @samp{sserver} is now ready to take @samp{sclient} requests.
1791 @node Testing the Sample Server, , Installing the Sample Application, A Sample Application
1792 @subsection Testing the Sample Server
1794 Assume that you have installed @samp{sserver} on @samp{jimi.mit.edu}.
1796 Login to your workstation and use the @samp{kinit} command to
1797 obtain a Kerberos ticket-granting ticket:
1800 % @b{[K_USER]/kinit [USERNAME]}
1801 Password for [USERNAME]@@[REALMNAME]: @b{<--- Enter your password}
1804 Now use the @samp{sclient} program as follows:
1807 % @b{[K_USER]/sclient jimi}
1810 The command should display something like the following:
1813 sendauth succeeded, reply is:
1814 reply len 29, contents:
1815 You are [USERNAME]@@[REALMNAME]
1818 @node Installing Kerberos Applications, Common Kerberos Service Names, A Sample Application, Installation
1819 @section Installing Kerberos Applications
1821 In addition to the sample application, Kerberos comes with
1822 several servers that can be installed on workstations to provide secure
1823 network services such as FTP, Telnet, and Rlogin. This section
1824 describes these services and how to install them. First, a general
1825 procedure is outlined for configuring a workstation to run Kerberos
1826 application servers. Then, details of the particular configuration
1827 options required by each server are presented.
1831 * Levels of Security::
1832 * Preparing a Workstation for Kerberos Application Servers::
1837 @node Levels of Security, Preparing a Workstation for Kerberos Application Servers, Installing Kerberos Applications, Installing Kerberos Applications
1838 @subsection Levels of Security
1840 Before installing Kerberized servers, it is a good idea to
1841 decide on a security policy for your environment. While developing a
1842 comprehensive security policy is beyond the scope of these instructions,
1843 there are several interactions between Kerberos servers and non-Kerberos
1844 servers, as well as different modes in which Kerberos servers can run
1845 that should be considered. In general, there are three levels of
1851 Encrypted Kerberos connections are the most secure services provided by
1852 the Kerberos environment. Only encrypted services provide
1853 confidentiality---encryption is required to make sure a passive
1854 eavesdropper does not collect sensitive data, such as passwords, sent
1855 over connections. Besides providing confidentiality, encryption
1856 provides protection against active attacks. Without encryption or some
1857 other form of integrity, an attacker may be able to insert commands or
1858 change data in an authenticated session.
1862 The next level of security is Kerberos-authenticated services without
1863 encryption. Without encryption, there is no confidentiality, and some
1864 active attacks are possible. However, unencrypted services are faster
1865 and are available commercially outside the United States. In addition,
1866 the window of exposure to attack is generally limited to the lifetime of
1867 a session---it is difficult for an attacker who does not have tickets to
1868 start a new session if a Kerberos authentication exchange must take
1869 place at the beginning of every session.
1872 Passworded services provide the next lower level of security.
1873 Unfortunately, it is all-to-easy for a passive attacker to use software
1874 such as a packet sniffer to find passwords traveling over a network.
1875 Additionally, once an attacker knows a password, they can start
1876 additional sessions at future times until the password is changed from a
1877 secure location. Despite the disadvantages of password-based network
1878 services, there are some common reasons for enabling them. First, most
1879 clients only support password-based services; not everyone has Kerberos
1880 or other cryptographically-secure network services. Second, in some
1881 environments, where the network is secure, passwords may be a reasonable
1882 solution. Also, particularly on public-access systems, it is common to
1883 enable password-based services for normal users, while using more-secure
1884 services such as Kerberos for root logins by administrators.
1887 The least secure common category of services are trust or host-based
1888 services. These services use an IP address or client-supplied assertion
1889 to provide authentication. Examples of host-based services include
1890 @samp{rlogin}, @samp{rsh}, and the @samp{on} or @samp{rexd} service. It
1891 is generally sufficient to know that a user exists on a target system,
1892 and to know that a host-based or trust-based service is enabled in order
1893 to exploit the service. Whenever possible, these services should be
1894 disabled; there are few situations in which an a security policy is both
1895 compatible with Kerberos and host-based services.
1898 Next, decide whether Kerberos V4 compatibility is necessary.
1899 Unencrypted Kerberos V4 services suffer from all the problems of
1900 unencrypted Kerberos V5 services: lack of confidentiality and
1901 susceptibility to active attack. In addition, the lack of a replay cache
1902 in Kerberos V4 makes these active attacks much easier. Also, design bugs
1903 in the Kerberos V4 BSD utilities such as @samp{rlogin}, @samp{rsh} and
1904 @samp{rcp} cause the availability of an unencrypted service to
1905 significantly decrease the security of a system, even if only the
1906 encrypted service is ever used. For example, a system that runs both
1907 encrypted and unencrypted Kerberos V4 @samp{rlogin} servers is less secure
1908 than a system only running the encrypted service, even if users only
1909 ever connect to the encrypted service.
1911 Therefore, if Kerberos V4 interoperability is desired or required,
1912 try to avoid running unencrypted Kerberos V4 services wherever possible.
1913 In particular, only enable encrypted @samp{rlogin} if at all possible.
1914 Naturally, some environments will require additional Kerberos V4
1915 functionality, like @samp{rsh}. The Kerberos V5 versions of these services,
1916 with Kerberos V4 interoperability enabled, are not any weaker than their
1917 Kerberos V4 counterparts. So, if the existing Kerberos V4 security policy
1918 allows these services, then enabling them under the Kerberos V5 security
1919 policy should not be a problem.
1921 In addition, the issue of compatibility with older Kerberos V5
1922 clients must be considered. For the most part, this compatibility is
1923 automatic, and has few security implications. The major exception to
1924 this is the BSD utilities. Until Kerberos V5 Beta6, these utilities
1925 inherited a few design defects from the Kerberos V4 BSD utilities. In
1926 particular, the presence of an unencrypted service that was never used
1927 adversely effected the security of an encrypted service. The solution
1928 that was adopted preserves compatibility with Kerberos V5 Beta5 clients.
1929 Unfortunately, older clients are incompatible with this scheme. If
1930 interoperability with older clients is necessary, then the new scheme
1931 for checksums can be disabled on the server. If these checksums are
1932 disabled, there is a short window between when a connection is opened
1933 and when the replay cache is updated where an active attack is possible.
1934 Alternatively, sites wishing to enable all security features may wish to
1935 disable compatibility with Kerberos V5 Beta5 BSD utilities.
1936 @xref{Checksums}, for full details.
1938 In conclusion, as you prepare to install Kerberos application
1939 servers, you should have answers to the following questions:
1944 What levels of services are appropriate for your security policy:
1945 encrypted services, authenticated but not encrypted services,
1946 password-based services, or host-based services?
1949 Do you wish to enable Kerberos V4 compatibility? If so, do you need to
1950 enable unencrypted services?
1953 Do you need compatibility with Kerberos V5 clients before Beta5
1954 (released in May, 1995)? Do you wish to disable compatibility with
1955 Beta5 clients for slightly enhanced security?
1960 @node Preparing a Workstation for Kerberos Application Servers, BSD Utilities, Levels of Security, Installing Kerberos Applications
1961 @subsection Preparing a Workstation for Kerberos Application Servers
1964 The following procedure is very similar to the installation
1965 procedure for the sample Kerberos server. @xref{Installing
1966 the Sample Application}. However, instead of using the sample service,
1967 this configuration is designed to set up host-based services.
1969 The following description assumes that you are installing @samp{sserver}
1970 on the machine @samp{jimi.mit.edu}. Repeat these steps for each
1971 workstation that will be running host-based servers. Note that it is
1972 not necessary to run these procedures on client machines--machines used
1973 only to connect to secure network services, but that do not run any
1974 servers of their own. Here's the process, step by step:
1979 Login as root or @samp{su} to root on the Kerberos server machine.
1980 Use the @samp{kdb5_edit} program to create a service entry for
1981 @code{host} in the Kerberos database:
1984 # @b{[ADMIN_DIR]/kdb5_edit}
1985 kdb5_edit: @b{add_random_key host/jimi.mit.edu}
1989 (Note: @samp{add_random_key} may be abbreviated as @samp{ark}.)
1992 Use @samp{kdb5_edit} to create a @file{srvtab} file
1993 for @samp{sserver}'s host machine:
1996 # @b{[ADMIN_DIR]/kdb5_edit}
1997 kdb5_edit: @b{extract_srvtab jimi.mit.edu host}
1998 'host/jimi.mit.edu@@ATHENA.MIT.EDU' added to keytab 'WRFILE:jimi.mit.edu-new-srvtab'
2002 (Note: @samp{extract_srvtab} may be abbreviated as @samp{xst}. Also,
2003 additional services can be listed after @samp{host} on the
2004 @samp{extract_srvtab} line; for example if the host jimi also runs the
2005 sample server, the @samp{sample} service might have been listed after
2008 Transfer the @file{jimi.mit.edu-new-srvtab} file to @samp{jimi.mit.edu}
2009 and install it as @file{/etc/v5srvtab}.
2011 @b{WARNING}: Note that this file is equivalent to the service's password and
2012 should be treated with care. For example, it could be transferred by
2013 removable media, but should not be sent over an open network in the
2014 clear. This file should be installed such that only the root user can read
2018 Make sure that the @samp{/etc/services} file has been updated to include
2019 Kerberos services. In particular, look for @samp{klogin},
2020 @samp{eklogin}, and @samp{kshell}.
2023 For each server you plan to run, add a line to @file{/etc/inetd.conf}.
2024 The following sections will give details on what this line should look
2025 like for each Kerberos application service.
2028 Consider removing non-Kerberized services like @samp{rlogin},
2029 @samp{rsh}, @samp{rexd}, and others, in accordance with the security policy you decided on in the last section.
2032 Restart @samp{inetd}. On most systems, this is done by sending the current @samp{inetd} process
2036 # @b{kill -HUP} @i{process_id_number}
2040 Try using the Kerberos applications to connect to the host.
2044 @node BSD Utilities, Telnet and FTP, Preparing a Workstation for Kerberos Application Servers, Installing Kerberos Applications
2045 @subsection BSD Utilities
2047 This section describes installing servers for the BSD utilities:
2048 @samp{kshd} and @samp{klogind}. The @samp{klogind} server implements the
2049 protocol used by the Kerberized @samp{rlogin} client. The @samp{kshd}
2050 server implements the protocol used by the @samp{rsh} and @samp{rcp}
2053 These daemons take a common set of options to enable support for
2054 different versions of Kerberos. The @samp{-5} option enables Kerberos
2055 V5 support, and the @samp{-4} option enables Kerberos V4 support. At
2056 least one of these options must be supplied or the server will refuse
2057 all connections. Both options can be supplied if compatibility with
2058 both versions of Kerberos is desired.
2060 Both the @samp{klogind} and @samp{kshd} take an @samp{-e} option
2061 to control encryption; because of the design of the servers, it works
2062 slightly differently. The Kerberos login service listens on two
2063 different ports, one for encrypted connections, and one for unencrypted
2064 connections. Because @samp{klogind} is started by @samp{inetd}, it
2065 needs to know whether it is servicing an encrypted or unencrypted
2066 connection. Thus, the @samp{-e} option tells @samp{klogind} that it is
2067 listening to the encrypted port. Typically, systems that allow both
2068 encrypted and unencrypted logins have two lines in @file{inetd.conf},
2069 one for the @samp{klogin} service and one for the @samp{eklogin}
2070 service. The line for the @samp{eklogin} service uses the @samp{-e}
2071 option, while the line for the @samp{klogin} service does not. Systems
2072 only supporting encrypted logins simply have the @samp{eklogin} line.
2074 On the other hand, @samp{kshd} listens to encrypted and
2075 unencrypted requests on the same port; information from the client
2076 identifies the connection's encryption status. So, @samp{kshd}
2077 interprets the @samp{-e} option to mean that encryption is required. If
2078 this option is specified, unencrypted connections are dropped. Thus,
2079 specifying @samp{-e} to @samp{kshd} is like only having a line for
2083 * Checksums:: Checksum facility for dealing with active attacks.
2084 * BSD Utility Configuration Example:: Sample @file{inetd.conf} entries for BSD utilities.
2087 @node Checksums, BSD Utility Configuration Example, BSD Utilities, BSD Utilities
2088 @subsubsection Checksums
2090 Under previous versions of Kerberos, it was possible for an active
2091 attacker to change certain information in the initial authentication
2092 exchange without this change being detected. Starting with Kerberos V5,
2093 Beta6, this information is protected by a checksum passed in the
2094 Kerberos authenticator. Ideally, the server could detect the presence
2095 of this checksum and use it if it were present. This way,
2096 administrators could be sure to use new clients that produced the
2097 checksum, while users who were not as concerned about security could use
2098 a wider range of clients.
2100 This is how the checksum feature works by default.
2101 Unfortunately, clients previous to Kerberos V5, Beta5 used the checksum
2102 field to incorporate semi-random data into the Kerberos authentication
2103 exchange. It is impossible to distinguish these bogus checksums from
2104 checksums that have been produced by modern clients, but modified by an
2105 active attacker. Thus, the checksum feature is incompatible with
2106 previous releases of Kerberos V5. Three modes of operation are provided
2107 to meet the configuration needs of different sites:
2112 The @samp{-c} option to both @samp{kshd} and @samp{klogind} requires
2113 that checksums be present and valid. This only works with clients more
2114 recent than Kerberos V5, Beta6. An error will be given when an older
2115 client tries to connect. This option is incompatible with Kerberos V4;
2116 Kerberos V4 clients do not include a checksum. If this option is used
2117 in conjunction with the @samp{-4} option for Kerberos V4 compatibility,
2118 a warning about the configuration error will be logged on each
2122 If no checksum-related option is specified, then checksums will be
2123 validated if they are present, but not required. This is compatible with
2124 Kerberos V4 and Kerberos V5 clients as early as Kerberos V5, Beta5.
2127 If the @samp{-i} option is provided, then checksums are ignored, even if
2128 present. This option is required to maintain compatibility with clients
2129 older than Kerberos V5 Beta5. Site should upgrade to newer clients so
2130 this option is not required.
2134 @node BSD Utility Configuration Example, , Checksums, BSD Utilities
2135 @subsubsection BSD Utility Configuration Example
2137 This section includes sample entries for @file{/etc/inetd.conf}.
2138 Sample configuration are presented for three systems. Note that while
2139 the examples stretch over multiple lines, an entry for a single service
2140 should be placed on only one line in @file{inetd.conf}. Also, not all
2141 systems have all of the columns shown in the example. @xref{Installing
2142 the Sample Application}, for details on adding services to
2145 The first system enables all security features. Only Kerberos
2146 V5 encrypted connections are enabled, and checksums are required.
2148 eklogin stream tcp nowait root
2149 [K_SERVER]/klogind klogind -5 -e -c
2150 kshell stream tcp nowait root
2151 [K_SERVER]/kshd kshd -5 -e -c
2155 The second system enables encrypted services for both Kerberos
2156 V5 and Kerberos V4. Checksums are not required, but since no V5 clients
2157 earlier than Beta5 are used, they are not ignored.
2160 eklogin stream tcp nowait root
2161 [K_SERVER]/klogind klogind -5 -4 -e
2162 kshell stream tcp nowait root
2163 [K_SERVER]/kshd kshd -5 -4 -e
2167 The final example has both encrypted and unencrypted services
2168 enabled for both Kerberos V5 and Kerberos V4. Checksums are disabled to
2169 preserve compatability with older V5 clients.
2172 eklogin stream tcp nowait root
2173 [K_SERVER]/klogind klogind -5 -4 -i -e
2174 klogin stream tcp nowait root
2175 [K_SERVER]/klogind klogind -5 -4 -i
2176 kshell stream tcp nowait root
2177 [K_SERVER]/kshd kshd -5 -4 -i
2180 @node Telnet and FTP, , BSD Utilities, Installing Kerberos Applications
2181 @subsection Telnet and FTP
2183 The following are example entries for @file{inetd.conf} for the
2184 @samp{telnetd} and @samp{ftpd} servers. @xref{Installing the Sample
2185 Application}, for details on adding services to @file{inetd.conf}. Note
2186 that unlike other @file{inetd.conf} examples in this document, these
2187 line should replace existing lines for password-based services of the
2190 The first example only allows encrypted or authenticated connections.
2193 telnet stream tcp nowait root
2194 [K_SERVER]/telnetd telnetd -a user
2195 ftp stream tcp nowait root
2196 [K_server]/ftpd ftpd -a
2199 The second example also allows password-based connections to be
2203 telnet stream tcp nowait root
2204 [K_SERVER]/telnetd telnetd
2205 ftp stream tcp nowait root
2206 [K_server]/ftpd ftpd
2209 @node Common Kerberos Service Names, , Installing Kerberos Applications, Installation
2210 @section Common Kerberos Service Names
2212 The following service names are used by Kerberos client/server
2218 Used by @samp{telnet}, @samp{rlogin}, @samp{rsh}, @samp{rcp}, @samp{ftp}
2219 and other services which generally give login access to the host.
2222 Used by the Post Office Protocol.
2225 Used by the Kerberos sample applications.
2229 These service names are used as the first component of the server's
2230 principal name, with the second component being the server's fully
2231 qualified domain name, in lower case.
2233 @node Troubleshooting, , Installation, Top
2234 @chapter Troubleshooting