From: Jeff Bigler Date: Fri, 6 Sep 1996 21:37:49 +0000 (+0000) Subject: Renamed cyg-install.texinfo to install.texinfo. X-Git-Tag: krb5-1.0-beta7~41 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=83f6f4ad74e04cd663f8e8e0ef564bb6ba2217e5;p=krb5.git Renamed cyg-install.texinfo to install.texinfo. Renamed install.texi to install-old.texi. Added include file bug-report.texinfo Made relevant changes in Makefile. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@9047 dc483132-0cff-0310-8789-dd5450dbe970 --- diff --git a/doc/ChangeLog b/doc/ChangeLog index 7f6c416f1..4ee411f5d 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,4 +1,12 @@ Fri Sep 6 12:59:43 1996 Jeff Bigler + + * install.texinfo: new name for cyg-install.texinfo + + * install-old.texi: new name for install.texi (so we know what's + what.) + + * Makefile (install-guide): renamed cyg-install.texinfo to + install.texinfo. * man2ps: shell script to create postscript include files for user's guide. diff --git a/doc/Makefile b/doc/Makefile index 45361be83..78f1be968 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -24,14 +24,14 @@ admin-guide-info:: install-guide-full:: install-guide install-guide-info install-guide-html install-guide:: - $(DVI) cyg-install.texinfo + $(DVI) install.texinfo $(DVIPS) install install-guide-html:: - $(HTML) cyg-install.texinfo + $(HTML) install.texinfo install-guide-info:: - $(INFO) cyg-install.texinfo + $(INFO) install.texinfo user-guide-full:: user-guide user-guide-info user-guide-html @@ -63,6 +63,6 @@ clean-tarfiles:: $(RM) *.tar *.tar.gz *.tgz tgz:: - $(TAR) krb5-docs.tar admin.texinfo build.texinfo copyright.texinfo definitions.texinfo document-list.texinfo glossary.texinfo cyg-install.texinfo texinfo.tex user-guide.texinfo *-guide.ps *.info *.info-? *.html + $(TAR) krb5-docs.tar admin.texinfo build.texinfo copyright.texinfo definitions.texinfo document-list.texinfo glossary.texinfo install.texinfo texinfo.tex user-guide.texinfo *-guide.ps *.info *.info-? *.html $(GZIP) krb5-docs.tar $(MV) krb5-docs.tar.gz krb5-docs.tgz diff --git a/doc/bug-report.texinfo b/doc/bug-report.texinfo new file mode 100644 index 000000000..a1c93c2ff --- /dev/null +++ b/doc/bug-report.texinfo @@ -0,0 +1,8 @@ +In any complex software, there will be bugs. Please send bug reports or +other problems you may uncover to the e-mail address +@b{krb5-bugs@@mit.edu}. Please mention which version of the Kerberos V5 +distribution you are using, and whether you have made any private +changes. Bug reports that include proposed fixes are especially +welcome. If you do include fixes, please send them using either context +diffs or unified diffs (using @samp{diff -c} or @samp{diff -u}, +respectively). diff --git a/doc/cyg-install.texinfo b/doc/cyg-install.texinfo deleted file mode 100644 index 718a91802..000000000 --- a/doc/cyg-install.texinfo +++ /dev/null @@ -1,1367 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c -@c Note: the above texinfo file must include the "doubleleftarrow" -@c definitions added by jcb. -@c %**start of header -@c guide -@setfilename krb5-install.info -@settitle Kerberos V5 Installation Guide -@setchapternewpage odd @c chapter begins on next odd page -@c @setchapternewpage on @c chapter begins on next page -@smallbook @c Format for 7" X 9.25" paper -@c %**end of header - -@paragraphindent 0 -@iftex -@parskip 6pt plus 6pt -@end iftex - -@include definitions.texinfo -@set EDITION b6-1 - -@finalout @c don't print black warning boxes - -@titlepage -@title @value{PRODUCT} Installation Guide -@subtitle Release: @value{RELEASE} -@subtitle Document Edition: @value{EDITION} -@subtitle Last updated: @value{UPDATED} -@author @value{COMPANY} - -@page -@vskip 0pt plus 1filll - -@iftex -@include copyright.texinfo -@end iftex -@end titlepage - -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up - -@ifinfo -This file documents how to install the @value{RELEASE} release of -@value{PRODUCT}. - -@include copyright.texinfo - -@end ifinfo - -@c The master menu is updated using emacs19's M-x texinfo-all-menus-update -@c function. Don't forget to run M-x texinfo-every-node-update after -@c you add a new section or subsection, or after you've rearranged the -@c order of sections or subsections. Also, don't forget to add an @node -@c comand before each @section or @subsection! All you need to enter -@c is: -@c -@c @node New Section Name - -@c @section New Section Name -@c -@c M-x texinfo-every-node-update will take care of calculating the -@c node's forward and back pointers. -@c -@c --------------------------------------------------------------------- - -@menu -* Introduction:: -* Realm Configuration Decisions:: -* Building Kerberos V5:: -* Installing Kerberos V5:: -* Bug Reports for Kerberos V5:: -* Files:: -@end menu - -@node Introduction, Realm Configuration Decisions, Top, Top -@chapter Introduction - -@menu -* What is Kerberos and How Does it Work?:: -* Why Should I use Kerberos?:: -* Please Read the Documentation:: -* Overview of This Guide:: -@end menu - -@node What is Kerberos and How Does it Work?, Why Should I use Kerberos?, Introduction, Introduction -@section What is Kerberos and How Does it Work? - -@value{PRODUCT} is based on the Kerberos authentication system developed -at MIT. Under Kerberos, a client (generally either a user or a service) -sends a request for a ticket to the Key Distribution Center (KDC). The -KDC creates a @dfn{ticket-granting ticket} (TGT) for the client, -encrypts it using the client's password as the key, and sends the -encrypted TGT back to the client. The client then attempts to decrypt -the TGT, using its password. If the client successfully decrypts the -TGT (@i{i.e.}, if the client gave the correct password), it keeps the -decrypted TGT, which indicates proof of the client's identity. - -The TGT, which expires at a specified time, permits the client to obtain -additional tickets, which give permission for specific services. The -requesting and granting of these additional tickets is user-transparent. - -@node Why Should I use Kerberos?, Please Read the Documentation, What is Kerberos and How Does it Work?, Introduction -@section Why Should I use Kerberos? - -Since Kerberos negotiates authenticated, and optionally encrypted, -communications between two points anywhere on the internet, it provides -a layer of security that is not dependent on which side of a firewall -either client is on. Since studies have shown that half of the computer -security breaches in industry happen from @i{inside} firewalls, -@value{PRODUCT} from @value{COMPANY} will play a vital role in the -security of your network. - -@include document-list.texinfo - -@node Please Read the Documentation, Overview of This Guide, Why Should I use Kerberos?, Introduction -@section Please Read the Documentation - -As with any software package that uses a centrallized database, the -installation procedure is somewhat involved, and requires forethought -and planning. @value{COMPANY} has attempted to make this -@value{PRODUCT} Installation Guide as concise as possible, rather than -making it an exhaustive description of the details of Kerberos. -Consequently, everything in this guide appears because @value{COMPANY} -believes that it is important. Please read and follow these -instructions carefully, and if there is anything you do not understand -or are not sure of, please don't hesitate to call us. - -@node Overview of This Guide, , Please Read the Documentation, Introduction -@section Overview of This Guide - -The next chapter describes the decisions you need to make before -installing @value{PRODUCT}. - -Chapter three describes installation procedures for each class of -Kerberos machines: - -@enumerate -@item -Key Distribution Centers (KDCs). - -@enumerate A -@item -The Master KDC. - -@item -Slave KDCs. -@end enumerate - -@item -Client machines (user machines): - -@enumerate A -@item -UNIX client machines. - -@item -Windows machines. - -@item -Macintoshes. -@end enumerate - -@item -application server machines -@end enumerate - -@noindent -Note that a machine can be both a client machine and an application -server. - -Chapter four describes our problem reporting system. - -The appendices give sample configuration files. - -@node Realm Configuration Decisions, Building Kerberos V5, Introduction, Top -@chapter Realm Configuration Decisions - -Before installing @value{PRODUCT}, it is necessary to consider the -following issues: - -@itemize @bullet -@item -The name of your Kerberos realm (or the name of each realm, if you need -more than one). - -@item -How you will map your hostnames onto Kerberos realms. - -@item -Which ports your KDC and and kadmin (database access) services will use. - -@item -How many slave KDCs you need and where they should be located. - -@item -The hostnames of your master and slave KDCs. - -@item -How frequently you will propagate the database from the master KDC to -the slave KDCs. - -@item -Whether you need backward compatibility with Kerberos V4. -@end itemize - -@menu -* Kerberos Realms:: -* Mapping Hostnames onto Kerberos Realms:: -* Ports for the KDC and Admin Services:: -* Slave KDCs:: -* Hostnames for the Master and Slave KDCs:: -* Database Propagation:: -@end menu - -@node Kerberos Realms, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions, Realm Configuration Decisions -@section Kerberos Realms - -Although your Kerberos realm can be any ASCII string, convention is to -make it the same as your domain name, in upper-case letters. For -example, hosts in the domain @value{SECONDDOMAIN} would be in the -Kerberos realm @value{SECONDREALM}. - -If you need multiple Kerberos realms, @value{COMPANY} recommends that -you use descriptive names which end with your domain name, such as -BOSTON.@value{SECONDREALM} and SAN_FRANCISCO.@value{SECONDREALM}. - -@node Mapping Hostnames onto Kerberos Realms, Ports for the KDC and Admin Services, Kerberos Realms, Realm Configuration Decisions -@section Mapping Hostnames onto Kerberos Realms - -Mapping hostnames onto Kerberos realms is done through a set of rules in -the @code{krb5.conf} configuration file. (@xref{krb5.conf}.) You can -specify mappings for an entire domain or subdomain, and/or on a -hostname-by-hostname basis. Since greater specificity takes precedence, -you would do this by specifying the mappings for a given domain or -subdomain and listing the exceptions. - -@node Ports for the KDC and Admin Services, Slave KDCs, Mapping Hostnames onto Kerberos Realms, Realm Configuration Decisions -@section Ports for the KDC and Admin Services - -The default ports used by Kerberos are port 88 for the -KDC@footnote{Kerberos V4 used port 750. If necessary, you can run on -both ports for backward compatibility.} and port 749 for the admin -server. You can, however, choose to run on other ports, as long as they -are specified in each host's @code{/etc/services} and @code{krb5.conf} -files, and the @code{kdc.conf} file on each KDC. Because the kadmin -port was recently assigned, @value{COMPANY} recommands that you specify -it explicitly in your @code{krb5.conf} and @code{kdc.conf} files. For a -more thorough treatment of port numbers used by the @value{PRODUCT} -programs, refer to the ``Configuring Your Firewall to Work With -@value{PRODUCT}'' section of the @cite{@value{PRODUCT} System -Administrator's Guide}. - -@node Slave KDCs, Hostnames for the Master and Slave KDCs, Ports for the KDC and Admin Services, Realm Configuration Decisions -@section Slave KDCs - -Slave KDCs provide an additional source of Kerberos ticket-granting -services in the event of inaccessibility of the master KDC. The number -of slave KDCs you need and the decision of where to place them, both -physically and logically, depend on the specifics of your network. - -All of the Kerberos authentication on your network requires that each -client be able to contact a KDC. Therefore, you need to anticipate any -likely reason a KDC might be unavailable and have a slave KDC to take up -the slack. - -Some considerations include: - -@itemize @bullet -@item -Have at least one slave KDC as a backup, for when the master KDC is -down, is being upgraded, or is otherwise unavailable. - -@item -If your network is split such that a network outage is likely to cause -some segment or segments of the network to become cut off or isolated, -have a slave KDC accessible to each segment. - -@item -If possible, have at least one slave KDC in a different building from -the master, in case of power outages, fires, or other localized -disasters. -@end itemize - -If you have a large and/or complex network, @value{COMPANY} will be -happy to work with you to determine the optimal number and placement of -your slave KDCs. - -@node Hostnames for the Master and Slave KDCs, Database Propagation, Slave KDCs, Realm Configuration Decisions -@section Hostnames for the Master and Slave KDCs - -@value{COMPANY} recommends that your KDCs have a predefined set of -cnames, such as @code{@value{KDCSERVER}} for the master KDC and -@code{@value{KDCSLAVE1}}, @code{@value{KDCSLAVE2}}, @dots{} for the -slave KDCs. This way, if you need to swap a machine, you only need to -change a DNS entry, rather than having to change hostnames. - -@node Database Propagation, , Hostnames for the Master and Slave KDCs, Realm Configuration Decisions -@section Database Propagation - -The Kerberos database resides on the master KDC, and must be propagated -regularly (usually by a cron job) to the slave KDCs. In deciding how -frequently the propagation should happen, you will need to balance the -amount of time the propagation takes against the maximum reasonable -amount of time a user should have to wait for a password change to take -effect. @value{COMPANY} recommends that this be no longer than an hour. - -If the propagation time is longer than this maximum reasonable time -(@i{e.g.,} you have a particularly large database, you have a lot of -slaves, and/or you experience frequent network delays), you may wish to -cut down on your propagation delay by performing the propagation in -parallel. To do this, have the master KDC propagate the database to one -set of slaves, and then have each of these slaves propagate the database -to additional slaves. - -@node Building Kerberos V5, Installing Kerberos V5, Realm Configuration Decisions, Top -@chapter Building @value{PRODUCT} - -@include build.texinfo - -@node Installing Kerberos V5, Bug Reports for Kerberos V5, Building Kerberos V5, Top -@chapter Installing @value{PRODUCT} - -The sections of this chapter describe procedures for installing -@value{PRODUCT} on: - -@enumerate -@item -The KDCs - -@item -Client machines - -@enumerate A -@item -UNIX client machines - -@item -Windows machines - -@item -Macintoshes -@end enumerate - -@item -UNIX Application Servers -@end enumerate - -@menu -* Installing KDCs:: -* Installing and Configuring UNIX Client Machines:: -* UNIX Application Servers:: -@end menu - -@node Installing KDCs, Installing and Configuring UNIX Client Machines, Installing Kerberos V5, Installing Kerberos V5 -@section Installing KDCs - -The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC -contains a copy of the Kerberos database. The master KDC contains the -master copy of the database, which it propagates to the slave KDCs at -regular intervals. All database changes (such as password changes) are -made on the master KDC. - -Slave KDCs provide Kerberos ticket-granting services, but not database -access. This allows clients to continue to obtain tickets when the -master KDC is unavailable. - -@value{COMPANY}'s recommends that you install all of your KDCs to be -able to function as either the master or one of the slaves. This will -enable you to easily switch your master KDC with one of the slaves if -necessary. (@xref{Switching Master and Slave KDCs}.) This installation -procedure is based on that recommendation. - -@menu -* Install the Master KDC:: -* Install the Slave KDCs:: -* Back on the Master KDC:: -* Finish Installing the Slave KDCs:: -* Add Kerberos Principals to the Database:: -* Limit Access to the KDCs:: -* Switching Master and Slave KDCs:: -@end menu - -@node Install the Master KDC, Install the Slave KDCs, Installing KDCs, Installing KDCs -@subsection Install the Master KDC - -This installation procedure will require you to go back and forth a -couple of times between the master KDC and each of the slave KDCs. The -first few steps must be done on the master KDC. - -@menu -* Edit the Configuration Files:: -* Create the Database:: -* Add Administrators to the Acl File:: -* Add Administrators to the Kerberos Database:: -* Create a kadmind Keytab:: -* Start the Kerberos Daemons:: -@end menu - -@node Edit the Configuration Files, Create the Database, Install the Master KDC, Install the Master KDC -@subsubsection Edit the Configuration Files - -Modify the configuration files, @code{/etc/krb5.conf} -(@pxref{krb5.conf}) and @code{@value{ROOTDIR}/lib/krb5kdc/kdc.conf} -(@pxref{kdc.conf}) to reflect the correct information (such as the -hostnames and realm name) for your realm. @value{COMPANY} recommends -that you keep @code{krb5.conf} in @code{/etc}. The @code{krb5.conf} -file may contain a pointer to @code{kdc.conf}, which you need to change -if you want to move @code{kdc.conf} to another location. - -@node Create the Database, Add Administrators to the Acl File, Edit the Configuration Files, Install the Master KDC -@subsubsection Create the Database - -You will use the @code{kdb5_util} command @emph{on the Master KDC} to -create the Kerberos database and the optional stash file. The -@dfn{stash file} is a local copy of the master key that resides in -encrypted form on the KDC's local disk. The stash file is used to -authenticate the KDC to itself automatically before starting the -@code{kadmind} and @code{krb5kdc} daemons (@i{e.g.,} as part of the -machine's boot sequence). The stash file, like the keytab file -(@xref{The Keytab File}) is a potential point-of-entry for a break-in, -and if compromised, would allow unrestricted access to the Kerberos -database. If you choose to install a stash file, it should be readable -only by root, and should exist only on the KDC's local disk. The file -should not be part of any backup of the machine, unless access to the -backup data is secured as tightly as access to the master password -itself. - -Note that @code{kdb5_util} will prompt you for the master key for the -Kerberos database. This key can be any string. A good key is one you -can remember, but that no one else can guess. Examples of bad keys are -words that can be found in a dictionary, any common or popular name, -especially a famous person (or cartoon character), your username in any -form (@i{e.g.}, forward, backward, repeated twice, @i{etc.}), and any of -the sample keys that appear in this manual. One example of a key which -would be good if it did not appear in this manual is ``MITiys4K5!'', -which represents the sentence ``@value{COMPANY} is your source for -Kerberos 5!'' (It's the first letter of each word, substituting the -numeral ``4'' for the word ``for'', and includes the punctuation mark at -the end.) - -The following is an example of how to create a Kerberos database and -stash file on the master KDC, using the @code{kdb5_util} command. (The -line that begins with @result{} is a continuation of the previous line.) -Replace @i{@value{PRIMARYREALM}} with the name of your Kerberos realm. - -@smallexample -@group -@b{shell%} @value{ROOTDIR}/sbin/kdb5_util create -r @value{PRIMARYREALM} -s -@b{kdb5_util: No such file or directory while setting active database to '/krb5/principal' -Initializing database '@value{ROOTDIR}/lib/krb5kdc/principal' for -@result{} realm '@value{PRIMARYREALM}', -master key name 'K/M@@@value{PRIMARYREALM}' -You will be prompted for the database Master Password. -It is important that you NOT FORGET this password.} -@iftex -@b{Enter KDC database master key:} @i{@doubleleftarrow{} Type the master password.} -@b{Re-enter KDC database master key to verify:} @i{@doubleleftarrow{} Type it again.} -@end iftex -@ifinfo -@b{Enter KDC database master key:} @i{<= Type the master password.} -@b{Re-enter KDC database master key to verify:} @i{<= Type it again.} -@end ifinfo -@b{shell%} -@end group -@end smallexample - -This will create five files in the directory specified in your -@code{kdc.conf} file: two Kerberos database files, @code{principal.db}, -and @code{principal.ok}; the Kerberos administrative database file, -@code{principal.kadm5}; the administrative database lock file, -@code{principal.kadm5.lock}; and the stash file, @code{.k5stash}. (The -default directory is @code{@value{ROOTDIR}/lib/krb5kdc}.) If you do not -want a stash file, run the above command without the @code{-s} option. - -@node Add Administrators to the Acl File, Add Administrators to the Kerberos Database, Create the Database, Install the Master KDC -@subsubsection Add Administrators to the Acl File - -Next, you need create an Access Control List (acl) file, and put the -Kerberos principal of at least one of the administrators into it. The -filename should match the value you have set for ``acl_file'' in your -@code{kdc.conf} file. The default file name is @samp{kadm5.acl}. The -format of the file is: - -@smallexample -Kerberos principal permissions optional target principal -@end smallexample - -The Kerberos principal (and optional target principal) can include the -``@b{*}'' wildcard, so if you want any principal with the instance -``admin'' to have full permissions on the database, you could use the -principal ``@code{*/admin@@REALM}'' where ``REALM'' is your Kerberos -realm. - -Note: a common use of an @i{admin} instance is so you can grant -separate permissions (such as administrator access to the Kerberos -database) to a separate Kerberos principal. For example, the user -@code{@value{ADMINUSER}} might have a principal for his administrative -use, called @code{@value{ADMINUSER}/admin}. This way, -@code{@value{ADMINUSER}} would obtain @code{@value{ADMINUSER}/admin} -tickets only when he actually needs to use those permissions. Refer to -the @value{PRODUCT} Administrator's Guide or the @value{PRODUCT} User's -Guide for more detailed explanations of @dfn{principals} and -@dfn{instances}. - -The permissions (acls) recognized in the acl file -are the following: - -@table @b -@itemx a -allows the addition of principals or policies in the database. -@itemx A -prohibits the addition of principals or policies in the database. -@itemx d -allows the deletion of principals or policies in the database. -@itemx D -prohibits the deletion of principals or policies in the database. -@itemx m -allows the modification of principals or policies in the database. -@itemx M -prohibits the modification of principals or policies in the database. -@itemx c -allows the changing of passwords for principals in the database. -@itemx C -prohibits the changing of passwords for principals in the database. -@itemx i -allows inquiries to the database. -@itemx I -prohibits inquiries to the database. -@itemx l -allows the listing of principals or policies in the database. -@itemx L -prohibits the listing of principals or policies in the database. -@itemx * -Short for all privileges (admcil). -@itemx x -Short for all privileges (admcil); identical to ``*''. -@end table - -To give the principal @code{*/admin@@@value{PRIMARYREALM}} permission to -change all of the database permissions on any principal permissions, you -would place the following line in the file: - -@smallexample -*/admin@@@value{PRIMARYREALM} * -@end smallexample - -To give the principal @code{@value{ADMINUSER}@@@value{PRIMARYREALM}} -permission to add, list, and inquire about any principal that has the -instance ``root'', you would add the following line to the acl file: - -@smallexample -@value{ADMINUSER}@@@value{PRIMARYREALM} ali */root@@@value{PRIMARYREALM} -@end smallexample - -@node Add Administrators to the Kerberos Database, Create a kadmind Keytab, Add Administrators to the Acl File, Install the Master KDC -@subsubsection Add Administrators to the Kerberos Database - -Next you need to add administrative principals to the Kerberos database. -(You must add at least one now.) To do this, use @code{kadmin.local} -@emph{on the master KDC}, as in the following example: - -@smallexample -@group -@b{shell%} @value{ROOTDIR}/sbin/kadmin.local -@b{kadmin:} addprinc admin/admin@@@value{PRIMARYREALM} -@b{WARNING: no policy specified for "admin/admin@@@value{PRIMARYREALM}"; -defaulting to no policy.} -@iftex -@b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Enter a password.} -Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{@doubleleftarrow{} Type it again.} -@end iftex -@ifinfo -@b{Enter password for principal admin/admin@@@value{PRIMARYREALM}:} @i{<= Enter a password.} -Re-enter password for principal admin/admin@@@value{PRIMARYREALM}: @i{<= Type it again.} -@end ifinfo -@b{Principal "admin/admin@@@value{PRIMARYREALM}" created. -kadmin:} -@end group -@end smallexample - -@node Create a kadmind Keytab, Start the Kerberos Daemons, Add Administrators to the Kerberos Database, Install the Master KDC -@subsubsection Create a kadmind Keytab - -The kadmind keytab is the key that kadmind will use to decrypt -administrators' Kerberos tickets to determine whether or not it should -give them access to the database. You need to create the kadmin keytab -with entries for the principals @code{kadmin/admin} and -@code{kadmin/changepw}. (These principals are placed in the Kerberos -database automatically when you create it.) To create the kadmin -keytab, run @code{kadmin} and use the @code{ktadd} command, as in the -following example. (The line beginning with @result{} is a continuation -of the previous line.): - -@smallexample -@group -@b{shell%} @value{ROOTDIR}/sbin/kadmin -@b{kadmin:} ktadd -k @value{ROOTDIR}/lib/krb5kdc/kadm5.keytab -@result{} kadmin/admin kadmin/changepw -@b{kadmin: Entry for principal kadmin/admin@@@value{PRIMARYREALM} with - kvno 3, encryption type DES-CBC-CRC added to keytab - WRFILE:@value{ROOTDIR}/lib/krb5kdc/kadm5.keytab. -kadmin:} quit -@b{shell%} -@end group -@end smallexample - -@noindent -As specified in the @samp{-k} argument, @code{ktadd} will save the -extracted keytab as @code{@value{ROOTDIR}/lib/krb5kdc/kadm5.keytab}. -The filename you use must be the one specified in your @code{kdc.conf} -file. - -@need 2000 -@node Start the Kerberos Daemons, , Create a kadmind Keytab, Install the Master KDC -@subsubsection Start the Kerberos Daemons on the Master KDC - -At this point, you are ready to start the Kerberos daemons on the Master -KDC. To do so, type: - -@smallexample -@b{shell%} @value{ROOTDIR}/sbin/krb5kdc -@b{shell%} @value{ROOTDIR}/sbin/kadmind -@end smallexample - -@noindent -Each daemon will fork and run in the background. Assuming you want -these daemons to start up automatically at boot time, you can add them -to the KDC's @code{/etc/rc} or @code{/etc/inittab} file. You need to -have a stash file in order to do this. - -@node Install the Slave KDCs, Back on the Master KDC, Install the Master KDC, Installing KDCs -@subsection Install the Slave KDCs - -You are now ready to start configuring the slave KDCs. Assuming you are -setting the KDCs up so that you can easily switch the master KDC with -one of the slaves, you should perform each of these steps on the master -KDC as well as the slave KDCs, unless these instructions specify -otherwise. - - -@menu -* Create Host Keys for the Slave KDCs:: -* Extract Host Keytabs for the KDCs:: -* Set Up the Slave KDCs for Database Propagation:: -@end menu - -@node Create Host Keys for the Slave KDCs, Extract Host Keytabs for the KDCs, Install the Slave KDCs, Install the Slave KDCs -@subsubsection Create Host Keys for the Slave KDCs - -Each KDC needs a host principal in the Kerberos database. You can enter -these from any host, once the @code{kadmind} daemon is running. For -example, if your master KDC were called -@value{KDCSERVER}.@value{PRIMARYDOMAIN}, and you had two KDC slaves -named @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} and -@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}, you would type the following: - -@smallexample -@group -@b{shell%} @value{ROOTDIR}/sbin/kadmin -@b{kadmin:} addprinc -randpass host/@value{KDCSERVER}.@value{PRIMARYDOMAIN} -@b{WARNING: no policy specified for "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; -defaulting to no policy. -Principal "host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created. -kadmin:} addprinc -randpass host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} -@b{WARNING: no policy specified for "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; -defaulting to no policy. -Principal "host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created.} -@b{kadmin:} addprinc -randpass host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN} -@b{WARNING: no policy specified for "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}"; -defaulting to no policy. -Principal "host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM}" created. -kadmin:} -@end group -@end smallexample - -@noindent -It is not actually necessary to have the master KDC server in the -Kerberos database, but it can be handy if: - -@itemize @bullet -@item -anyone will be logging into the machine as something other than root - -@item -you want to be able to swap the master KDC with one of the slaves if -necessary. -@end itemize - -@node Extract Host Keytabs for the KDCs, Set Up the Slave KDCs for Database Propagation, Create Host Keys for the Slave KDCs, Install the Slave KDCs -@subsubsection Extract Host Keytabs for the KDCs - -Each KDC (including the master) needs a keytab to decrypt tickets. -Ideally, you should extract each keytab locally on its own KDC. If this -is not feasible, you should use an encrypted session to send them across -the network. To extract a keytab on a KDC called -@value{KDCSERVER}.@value{PRIMARYDOMAIN}, you would execute the following -command: - -@smallexample -@group -@b{kadmin:} ktadd host/@value{KDCSERVER}.@value{PRIMARYDOMAIN} -@b{kadmin: Entry for principal host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with - kvno 1, encryption type DES-CBC-CRC added to keytab - WRFILE:/etc/v5srvtab. -kadmin:} -@end group -@end smallexample - -@noindent -Note that the principal must exist in the Kerberos database in order to -extract the keytab. - -@node Set Up the Slave KDCs for Database Propagation, , Extract Host Keytabs for the KDCs, Install the Slave KDCs -@subsubsection Set Up the Slave KDCs for Database Propagation - -The database is propagated from the master KDC to the slave KDCs via the -@code{kpropd} daemon. To set up propagation, create a file on each KDC, -named @code{@value{ROOTDIR}/lib/krb5kdc/kpropd.acl}, containing the -principals for each of the KDCs. -@need 1200 -For example, if the master KDC were -@code{@value{KDCSERVER}.@value{PRIMARYDOMAIN}}, the slave KDCs were -@code{@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}} and -@code{@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}}, and the realm were -@code{@value{PRIMARYREALM}}, then the file's contents would be: - -@smallexample -@group -host/@value{KDCSERVER}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} -host/@value{KDCSLAVE1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} -host/@value{KDCSLAVE2}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} -@end group -@end smallexample - -@need 1000 -Then, add the following lines to @code{/etc/inetd.conf} file on each KDC -(the line beginnng with @result{} is a continuation of the previous -line): - -@smallexample -@group -krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd -eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind -@result{} klogind -k -c -e -@end group -@end smallexample - -@noindent -The first line sets up the @code{kpropd} database propagation daemon. -The second line sets up the @code{eklogin} daemon, allowing -Kerberos-authenticated, encrypted rlogin to the KDC. - -You also need to add the following lines to @code{/etc/services} on each -KDC: - -@smallexample -@group -kerberos 88/udp kdc # Kerberos authentication (udp) -kerberos 88/tcp kdc # Kerberos authentication (tcp) -krb5_prop 754/tcp # Kerberos slave propagation -kerberos-adm 749/tcp # Kerberos 5 admin/changepw (tcp) -kerberos-adm 749/udp # Kerberos 5 admin/changepw (udp) -eklogin 2105/tcp # Kerberos encrypted rlogin -@end group -@end smallexample - -@node Back on the Master KDC, Finish Installing the Slave KDCs, Install the Slave KDCs, Installing KDCs -@subsection Back on the Master KDC - -Now that the slave KDCs are able to accept database propagation, you'll -need to propagate the database to each of them. - -@menu -* Propagate the Database to Each Slave KDC:: -@end menu - -@node Propagate the Database to Each Slave KDC, , Back on the Master KDC, Back on the Master KDC -@subsubsection Propagate the Database to Each Slave KDC - -First, create a dump of the database on the master KDC, as follows: - -@smallexample -@group -@b{shell%} @value{ROOTDIR}/sbin/kdb5_util dump @value{ROOTDIR}/lib/krb5kdc/slave_datatrans -@b{shell%} -@end group -@end smallexample - -Next, you need to manually propagate the database to each slave KDC, as -in the following example. (The lines beginning with @result{} are -continuations of the previous line.): - -@smallexample -@group -@value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/lib/krb5kdc/slave_datatrans -@result{} @value{KDCSLAVE1}.@value{PRIMARYDOMAIN} -@value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/lib/krb5kdc/slave_datatrans -@result{} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN} -@end group -@end smallexample - -You will need a script to dump and propagate the database. The -following is an example of a bourne shell script that will do this. -(Note that the line that begins with @result{} is a continuation of the -previous line. Remember that you need to replace @value{ROOTDIR} with -the name of the directory in which you installed @value{PRODUCT}.) - -@smallexample -@group -#!/bin/sh - -kdclist = "@value{KDCSLAVE1}.@value{PRIMARYDOMAIN} @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}" - -@value{ROOTDIR}/sbin/kdb5_util -R "dump -@result{} @value{ROOTDIR}/lib/krb5kdc/slave_datatrans" - -for kdc in $kdclist -do -@value{ROOTDIR}/sbin/kprop -f @value{ROOTDIR}/lib/krb5kdc/slave_datatrans $kdc -done -@end group -@end smallexample - -@noindent -You will need to set up a cron job to run this script at the intervals -you decided on earlier (@xref{Database Propagation}.) - -@node Finish Installing the Slave KDCs, Add Kerberos Principals to the Database, Back on the Master KDC, Installing KDCs -@subsection Finish Installing the Slave KDCs - -Now that the slave KDCs have copies of the Kerberos database, you can -create stash files for them and start the @code{krb5kdc} daemon. - -@menu -* Create Stash Files on the Slave KDCs:: -* Start the krb5kdc Daemon on Each KDC:: -@end menu - -@node Create Stash Files on the Slave KDCs, Start the krb5kdc Daemon on Each KDC, Finish Installing the Slave KDCs, Finish Installing the Slave KDCs -@subsubsection Create Stash Files on the Slave KDCs - -Create stash files, by issuing the following commands on each slave KDC: - -@smallexample -@group -@b{shell%} kdb5_util stash -@b{kdb5_util: Cannot find/read stored master key while reading master key -kdb5_util: Warning: proceeding without master key} -@iftex -@b{Enter KDC database master key:} @i{@doubleleftarrow{} Enter the database master key.} -@end iftex -@ifinfo -@b{Enter KDC database master key:} @i{<= Enter the database master key.} -@end ifinfo -@b{shell%} -@end group -@end smallexample - -As mentioned above, the stash file is necessary for your KDCs to be able -authenticate to themselves, such as when they reboot. You could run -your KDCs without stash files, but you would then need to type in the -Kerberos database master key by hand every time you start a KDC daemon. - -@node Start the krb5kdc Daemon on Each KDC, , Create Stash Files on the Slave KDCs, Finish Installing the Slave KDCs -@subsubsection Start the krb5kdc Daemon on Each KDC - -The final step in configuing your slave KDCs is to run the KDC daemon: - -@smallexample -@group -@b{shell%} @value{ROOTDIR}/sbin/krb5kdc -@end group -@end smallexample - -As with the master KDC, you will probably want to add this command to -the KDCs' @code{/etc/rc} or @code{/etc/inittab} files, so they will -start the krb5kdc daemon automatically at boot time. - -@node Add Kerberos Principals to the Database, Limit Access to the KDCs, Finish Installing the Slave KDCs, Installing KDCs -@subsection Add Kerberos Principals to the Database - -@need 1800 -Once your KDCs are set up and running, you are ready to use -@code{kadmin} to load principals for your users, hosts, and other -services into the Kerberos database. This procedure is described fully in the -``Adding or Modifying Principals'' section of the @value{PRODUCT} System -Administrator's Guide. (@xref{Create Host Keys for the Slave KDCs} for a -brief description.) The keytab is generated by running @code{kadmin} -and issuing the @code{ktadd} command. - -@node Limit Access to the KDCs, Switching Master and Slave KDCs, Add Kerberos Principals to the Database, Installing KDCs -@subsection Limit Access to the KDCs - -To limit the possibility that your Kerberos database could be -compromised, @value{COMPANY} recommends that each KDC be a dedicated -host, with limited access. If your KDC is also a file server, FTP -server, Web server, or even just a client machine, someone who obtained -root access through a security hole in any of those areas could gain -access to the Kerberos database. - -@need 4700 -@value{COMPANY} recommends that your KDCs use the following -@code{/etc/inetd.conf} file. (Note: each line beginning with @result{} -is a continuation of the previous line.): - -@smallexample -@group -# -# Configuration file for inetd(1M). See inetd.conf(4). -# -# To re-configure the running inetd process, edit this file, then -# send the inetd process a SIGHUP. -# -# Syntax for socket-based Internet services: -# -@result{} -# -# Syntax for TLI-based Internet services: -# -# tli -# -# Ftp and telnet are standard Internet services. -# -# This machine is a secure Kerberos Key Distribution Center (KDC). -# Services are limited. -# -# -# Time service is used for clock synchronization. -# -time stream tcp nowait root internal -time dgram udp wait root internal -# -# Limited Kerberos services -# -krb5_prop stream tcp nowait root @value{ROOTDIR}/sbin/kpropd kpropd -eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind -@result{} klogind -k -c -e -@end group -@end smallexample - -@node Switching Master and Slave KDCs, , Limit Access to the KDCs, Installing KDCs -@subsection Switching Master and Slave KDCs - -You may occasionally want to use one of your slave KDCs as the master. -This might happen if you are upgrading the master KDC, or if your master -KDC has a disk crash. - -Assuming you have configured all of your KDCs to be able to function as -either the master KDC or a slave KDC (as this document recommends), all -you need to do to make the changeover is: - -If the master KDC is still running, do the following on the @emph{old} -master KDC: - -@enumerate -@item -Kill the @code{kadmind} process. - -@item -Disable the cron job that propagates the database. - -@item -Run your database propagation script manually, to ensure that the slaves -all have the latest copy of the database. (@xref{Propagate the Database -to Each Slave KDC}.) -@end enumerate - -On the @emph{new} master KDC: - -@enumerate -@item -Create a database keytab. (@xref{Create a kadmind Keytab}.) - -@item -Start the @code{kadmind} daemon. (@xref{Start the Kerberos Daemons}.) - -@item -Set up the cron job to propagate the database. (@xref{Propagate the -Database to Each Slave KDC}.) - -@item -Switch the cnames of the old and new master KDCs. (If you don't do -this, you'll need to change the @code{krb5.conf} file on every client -machine in your Kerberos realm.) -@end enumerate - -@node Installing and Configuring UNIX Client Machines, UNIX Application Servers, Installing KDCs, Installing Kerberos V5 -@section Installing and Configuring UNIX Client Machines - -Client machine installation is much more straightforward than -installation of the KDCs. - -@menu -* Client Programs:: -* Client Machine Configuration Files:: -@end menu - -@node Client Programs, Client Machine Configuration Files, Installing and Configuring UNIX Client Machines, Installing and Configuring UNIX Client Machines -@subsection Client Programs - -The Kerberized client programs are @code{login.krb5}, @code{rlogin}, -@code{telnet}, @code{ftp}, @code{rcp}, @code{rsh}, @code{kinit}, -@code{klist}, @code{kdestroy}, @code{kpasswd}, @code{ksu}, -@c @code{krb524init}, -and @code{krdist}. All of these programs are in the directory -@code{@value{ROOTDIR}/bin}, except for @code{login.krb5} which is in -@code{@value{ROOTDIR}/sbin}. - -You will probably want to have your users put @code{@value{ROOTDIR}/bin} -ahead of @code{/bin} and @code{/usr/bin} in their paths, so they will by -default get the @value{PRODUCT} versions of @code{rlogin}, -@code{telnet}, @code{ftp}, @code{rcp}, and @code{rsh}. - -@value{COMPANY} recommends that you use @code{login.krb5} in place of -@code{/bin/login} to give your users a single-sign-on system. You will -need to make sure your users know to use their Kerberos passwords when -they log in. - -You will also need to educate your users to use the ticket management -programs @code{kinit}, -@c @code{krb524init}, -@code{klist}, @code{kdestroy}, and to use the Kerberos programs -@c @code{pfrom}, -@code{ksu}, @code{kpasswd}, and @code{krdist}, in place of their -non-Kerberos counterparts -@c @code{from} -@code{su}, @code{passwd}, and @code{rdist}. - -@node Client Machine Configuration Files, , Client Programs, Installing and Configuring UNIX Client Machines -@subsection Client Machine Configuration Files - -Each machine running Kerberos must have a @code{/etc/krb5.conf} file. -(@xref{krb5.conf}) - -@need 4000 -Also, you must add the appropriate Kerberos services to each client -machine's @code{/etc/services} file. If you are using the default -configuration for @value{PRODUCT}, you should be able to just insert the -following code: - -@smallexample -@group -# -# Note --- if you are using Kerberos V4 and you either: -# -# (a) haven't converted all your master or slave KDCs to V5, or -# -# (b) are worried about inter-realm interoperability with other KDC's -# that are still using V4 -# -# you will need to switch the "kerberos" service to port 750 and create a -# "kerberos-sec" service on port 88. -# -kerberos 88/udp kdc # Kerberos V5 KDC -kerberos 88/tcp kdc # Kerberos V5 KDC -klogin 543/tcp # Kerberos authenticated rlogin -kshell 544/tcp cmd # and remote shell -kerberos-adm 749/tcp # Kerberos 5 admin/changepw -kerberos-adm 749/udp # Kerberos 5 admin/changepw -krb5_prop 754/tcp # Kerberos slave propagation -@c kpop 1109/tcp # Pop with Kerberos -eklogin 2105/tcp # Kerberos auth. & encrypted rlogin -krb524 4444/tcp # Kerberos 5 to 4 ticket translator -@end group -@end smallexample - -@noindent As described in the comments in the above code, if your master -KDC or any of your slave KDCs is running Kerberos V4, (or if you will be -authenticating to any Kerberos V4 KDCs in another realm) you will need -to switch the port number for @code{kerberos} to 750 and create a -@code{kerberos-sec} service (tcp and udp) on port 88, so the Kerberos -V4 KDC(s) will continue to work properly. - -@node UNIX Application Servers, , Installing and Configuring UNIX Client Machines, Installing Kerberos V5 -@section UNIX Application Servers - -An application server is a host that provides one or more services over -the network. Application servers can be ``secure'' or ``insecure.'' A -``secure'' host is set up to require authentication from every client -connecting to it. An ``insecure'' host will still provide Kerberos -authentication, but will also allow unauthenticated clients to connect. - -If you have @value{PRODUCT} installed on all of your client machines, -@value{COMPANY} recommends that you make your hosts secure, to take -advantage of the security that Kerberos authentication affords. -However, if you have some clients that do not have @value{PRODUCT} -installed, you can run an insecure server, and still take advantage of -@value{PRODUCT}'s single sign-on on capability. - -@menu -* Server Programs:: -* Server Configuration Files:: -* The Keytab File:: -* Some Advice about Secure Hosts:: -@end menu - -@node Server Programs, Server Configuration Files, UNIX Application Servers, UNIX Application Servers -@subsection Server Programs - -Just as @value{PRODUCT} provided its own Kerberos-enhanced versions of -client UNIX network programs, @value{PRODUCT} also provides -Kerberos-enhanced versions of server UNIX network daemons. These are -@code{ftpd}, @code{klogind}, @code{kshd}, and @code{telnetd}. -@c @code{popper}, -These programs are installed in the directory -@code{@value{ROOTDIR}/sbin}. You may want to add this directory to -root's path. - -@node Server Configuration Files, The Keytab File, Server Programs, UNIX Application Servers -@subsection Server Configuration Files - -For a @emph{secure} server, make the following changes to -@code{/etc/inetd.conf}: - -Find and comment out any lines for the services @code{ftp}, -@code{telnet}, @code{shell}, @code{login}, and @code{exec}. - -@need 1800 -Add the following lines. (Note: each line beginning with @result{} is -a continuation of the previous line.) - -@smallexample -@group -klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind -@result{} klogind -k -c -eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind -@result{} klogind -k -c -e -kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd -@result{} kshd -k -c -A -ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd -@result{} ftpd -a -telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd -@result{} telnetd -a valid -@end group -@end smallexample - -For an @emph{insecure} server, make the following changes instead to -@code{/etc/inetd.conf}: - -@need 1800 -Find and comment out any lines for the services @code{ftp} and -@code{telnet}. - -Add the following lines. (Note: each line beginning with @result{} is -a continuation of the previous line.) -@smallexample -@group -klogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind -@result{} klogind -k -c -eklogin stream tcp nowait root @value{ROOTDIR}/sbin/klogind -@result{} klogind -k -c -e -kshell stream tcp nowait root @value{ROOTDIR}/sbin/kshd -@result{} kshd -k -c -A -ftp stream tcp nowait root @value{ROOTDIR}/sbin/ftpd -@result{} ftpd -telnet stream tcp nowait root @value{ROOTDIR}/sbin/telnetd -@result{} telnetd -a none -@end group -@end smallexample - -@node The Keytab File, Some Advice about Secure Hosts, Server Configuration Files, UNIX Application Servers -@subsection The Keytab File - -All Kerberos server machines need a @dfn{keytab} file, called -@code{/etc/v5srvtab},@footnote{The keytab was called a @dfn{srvtab} in -Kerberos V4. The @code{v5srvtab} file has not been renamed to reflect -the change in terminology.} to authenticate to the KDC. The keytab file -is an encrypted, local, on-disk copy of the host's key. The keytab -file, like the stash file (@ref{Create the Database}) is a potential -point-of-entry for a break-in, and if compromised, would allow -unrestricted access to its host. The keytab file should be readable -only by root, and should exist only on the machine's local disk. The -file should not be part of any backup of the machine, unless access to -the backup data is secured as tightly as access to the machine's root -password itself. - -In order to generate a keytab for a host, the host must have a principal -in the Kerberos database. The procedure for adding hosts to the -database is described fully in the ``Adding or Modifying Principals'' -section of the @cite{@value{PRODUCT} System Administrator's Guide}. -@xref{Create Host Keys for the Slave KDCs} for a brief description.) -The keytab is generated by running @code{kadmin} and issuing the -@code{ktadd} command. - -@need 1100 -For example, to generate a keytab file to allow the host -trillium.@value{PRIMARYDOMAIN} to authenticate for the services -@code{host}, @code{ftp}, and @code{pop}, the administrator -@code{@value{ADMINUSER}} would issue the command (on -trillium.@value{PRIMARYDOMAIN}): - -@smallexample -@group -@b{trillium%} @value{ROOTDIR}/sbin/kadmin -@b{kadmin5:} ktadd host/trillium.@value{PRIMARYDOMAIN} ftp/trillium.@value{PRIMARYDOMAIN} -@result{} pop/trillium.@value{PRIMARYDOMAIN} -@b{kadmin: Entry for principal host/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with -kvno 3, encryption type DES-CBC-CRC added to keytab -WRFILE:/etc/v5srvtab. -kadmin: Entry for principal ftp/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with -kvno 3, encryption type DES-CBC-CRC added to keytab -WRFILE:/etc/v5srvtab. -kadmin: Entry for principal pop/trillium.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with -kvno 3, encryption type DES-CBC-CRC added to keytab -WRFILE:/etc/v5srvtab. -kadmin5:} quit -@b{trillium%} -@end group -@end smallexample - -If you generate the keytab file on another host, you need to get a copy -of the keytab file onto the destination host (@code{trillium}, in the -above example) without sending it unencrypted over the network. If you -have installed the @value{PRODUCT} client programs, you can use -encrypted @code{rcp}. - -@node Some Advice about Secure Hosts, , The Keytab File, UNIX Application Servers -@subsection Some Advice about Secure Hosts - -@value{PRODUCT} can protect your host from certain types of break-ins, -but it is possible to install @value{PRODUCT} and still leave your host -vulnerable to attack. Obviously an installation guide is not the place -to try to include an exhaustive list of countermeasures for every -possible attack, but it is worth noting some of the larger holes and how -to close them. - -As stated earlier in this section, @value{COMPANY} recommends that on a -secure host, you disable the standard @code{ftp}, @code{login}, -@code{telnet}, @code{shell}, and @code{exec} services in -@code{/etc/services}. We also recommend that secure hosts have an empty -@code{/etc/hosts.equiv} file and that there not be a @code{.rhosts} file -in @code{root}'s home directory. You can grant Kerberos-authenticated -root access to specific Kerberos principals by placing those principals -in the file @code{.k5login} in root's home directory. - -We recommend that backups of secure machines exclude the keytab file -(@code{/etc/v5srvtab}). If this is not possible, the backups should at -least be done locally, rather than over a network, and the backup tapes -should be physically secured. - -Finally, the keytab file and any programs run by root, including the -@value{PRODUCT} binaries, should be kept on local disk. The keytab file -should be readable only by root. - -@node Bug Reports for Kerberos V5, Files, Installing Kerberos V5, Top -@chapter Bug Reports for @value{PRODUCT} -@include bug-report.texinfo - -@node Files, , Bug Reports for Kerberos V5, Top -@appendix Files - -@menu -* krb5.conf:: -* kdc.conf:: -@end menu - -@node krb5.conf, kdc.conf, Files, Files -@appendixsec krb5.conf - -Here is an example of a generic @code{krb5.conf} file: - -@smallexample -@group -[libdefaults] - ticket_lifetime = 600 - default_realm = @value{PRIMARYREALM} - default_tkt_enctypes = des-cbc-crc - default_tgs_enctypes = des-cbc-crc - -[realms] - @value{PRIMARYREALM} = @{ - kdc = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:88 - kdc = @value{KDCSLAVE1}.@value{PRIMARYDOMAIN}:88 - kdc = @value{KDCSLAVE2}.@value{PRIMARYDOMAIN}:88 - admin_server = @value{KDCSERVER}.@value{PRIMARYDOMAIN}:749 - default_domain = @value{PRIMARYDOMAIN} - @} - @} - -[domain_realm] - .@value{PRIMARYDOMAIN} = @value{PRIMARYREALM} - @value{PRIMARYDOMAIN} = @value{PRIMARYREALM} -@end group -@end smallexample - -For the KDCs, add a section onto the end of the @code{krb5.conf} file -telling where the @code{kdc.conf} file is located, as in the following -example: - -@smallexample -@group -[kdc] - profile = @value{ROOTDIR}/lib/krb5kdc/kdc.conf - -[logging] - kdc = FILE:/dev/ttyp9 - admin_server = FILE:/dev/ttyp9 - default = FILE:/dev/ttyp9 -@end group -@end smallexample - -@iftex -@vfill -@end iftex -@page - -@node kdc.conf, , krb5.conf, Files -@appendixsec kdc.conf - -Here's an example of a generic kdc.conf file: - -@smallexample -@group -[kdcdefaults] - kdc_ports = 88,750 - -[realms] - @value{PRIMARYREALM} = @{ - profile = /etc/krb5.conf - database_name = @value{ROOTDIR}/lib/krb5kdc/principal - admin_database_name = @value{ROOTDIR}/lib/krb5kdc/principal.kadm5 - admin_database_lockfile = @value{ROOTDIR}/lib/krb5kdc/principal.kadm5.lock - admin_keytab = @value{ROOTDIR}/lib/krb5kdc/kadm5.keytab - acl_file = @value{ROOTDIR}/lib/krb5kdc/kadm5.acl - dict_file = @value{ROOTDIR}/lib/krb5kdc/kadm5.dict - key_stash_file = @value{ROOTDIR}/lib/krb5kdc/.k5.@value{PRIMARYREALM} - kadmind_port = 749 - max_life = 10h 0m 0s - max_renewable_life = 7d 0h 0m 0s - master_key_type = des-cbc-crc - supported_enctypes = des-cbc-crc:normal - @} -@end group -@end smallexample - -To add Kerberos V4 support, change the @code{supported_enctypes} line to: - -@smallexample - supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4 -@end smallexample - -@menu -* Encryption Types and Salt Types:: -@end menu - -@node Encryption Types and Salt Types, , kdc.conf, kdc.conf -@appendixsubsec Encryption Types and Salt Types - -Currently, @value{PRODUCT} supports only DES encryption. The encoding -type is @code{des-cbc-crc}. The @dfn{salt} is additional information -encoded within the key that tells what kind of key it is. The only -salts that you will be likely to encounter are: - -@itemize @bullet -@item @dfn{normal}, which @value{COMPANY} recommends using for all of -your @value{PRODUCT} keys - -@item @dfn{v4}, which is necessary only for compatibility with a v4 KDC - -@item @dfn{afs}, which you will never need to generate, and which you will -encounter only if you dump an AFS database into a Kerberos database -@end itemize - -Support for additional encryption types is planned in the future. - -@contents -@bye diff --git a/doc/install.texi b/doc/install.texi deleted file mode 100644 index 079590824..000000000 --- a/doc/install.texi +++ /dev/null @@ -1,2239 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename install.info -@settitle Kerberos V5 -@c For double-sided printing, uncomment: -@setchapternewpage odd -@c %**end of header - -@set EDITION BETA 6 -@set VERSION BETA 6 -@set UPDATED Mar 20, 1996 - -@ignore -@iftex -@finalout -@end iftex -@end ignore - -@ifinfo -This file documents how to build and install the Kerberos V5 -distribution. - -Copyright (C) 1995, 1996 Massachusetts Institute of Technology. - -All Rights Reserved. - -Export of this software from the United States of America may require a -specific license from the United States Government. It is the -responsibility of any person or organization contemplating export to -obtain any necessary licenses before exporting. - -WITHIN THAT CONSTRAINT, permission to use, copy, modify, and -distribute this software and its documentation for any purpose and -without fee is hereby granted, provided that the above copyright -notice appear in all copies and that both that copyright notice and -this permission notice appear in supporting documentation, and that -the name of M.I.T. not be used in advertising or publicity pertaining -to distribution of the software without specific, written prior -permission. M.I.T. makes no representations about the suitability of -this software for any purpose. It is provided "as is" without express -or implied warranty. - -Athena(r), Hesiod(r), Moira(r), and Discuss(r) are registered trademarks of -the Massachusetts Institute of Technology (MIT). Project Athena, Athena -Dashboard, Athena MUSE, Kerberos, X Window System, and Zephyr are trademarks -of MIT. No commercial use of these trademarks may be made without prior -written permission of MIT. - -All other product names are trademarks of their respective companies. - -@end ifinfo - -@titlepage -@title Kerberos V5 -@subtitle Notes on Building and Installing Kerberos -@subtitle Edition @value{EDITION}, for Kerberos version @value{VERSION} -@subtitle @value{UPDATED} -@author by Theodore Ts'o - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1995, 1996 Massachusetts Institute of Technology - -All Rights Reserved. - -Export of this software from the United States of America may require a -specific license from the United States Government. It is the -responsibility of any person or organization contemplating export to -obtain any necessary licenses before exporting. - -WITHIN THAT CONSTRAINT, permission to use, copy, modify, and -distribute this software and its documentation for any purpose and -without fee is hereby granted, provided that the above copyright -notice appear in all copies and that both that copyright notice and -this permission notice appear in supporting documentation, and that -the name of M.I.T. not be used in advertising or publicity pertaining -to distribution of the software without specific, written prior -permission. M.I.T. makes no representations about the suitability of -this software for any purpose. It is provided "as is" without express -or implied warranty. - -Athena(r), Hesiod(r), Moira(r), and Discuss(r) are registered trademarks of -the Massachusetts Institute of Technology (MIT). Project Athena, Athena -Dashboard, Athena MUSE, Kerberos, X Window System, and Zephyr are trademarks -of MIT. No commercial use of these trademarks may be made without prior -written permission of MIT. - -All other product names are trademarks of their respective companies. - -@end titlepage - -@node Top, Introduction, (dir), (dir) -@comment node-name, next, previous, up - -@ifinfo -This file documents how to build and install the Kerberos V5 -distribution. - -This is edition @value{EDITION}, for Kerberos V5 version @value{VERSION}. - -@end ifinfo - -@c The master menu is updated using emacs19's M-x texinfo-all-menus-update -@c function. Don't forget to run M-x texinfo-every-node-update after -@c you add a new section or subsection, or after you've rearranged the -@c order of sections or subsections. Also, don't forget to add an @node -@c command before each @section or @subsection! All you need to enter -@c is: -@c -@c @node New Section Name - -@c @section New Section Name -@c -@c M-x texinfo-every-node-update will take care of calculating the -@c node's forward and back pointers. -@c - -@menu -* Introduction:: -* How Kerberos Works:: -* Building Kerberos:: -* Installation:: -* Troubleshooting:: - - --- The Detailed Node Listing --- - -How Kerberos Works: A Schematic Description - -* Network Services:: -* Kerberos Tickets:: -* The Kerberos Database:: -* Kerberos Realms:: -* The Ticket-Granting Ticket:: -* Network Services and the Master Database:: -* The User-Kerberos Interaction:: - -Network Services and the Master Database - -* The Keytab File:: - -Building Kerberos - -* Build Requirements:: How much disk space, etc. you need to - build Kerberos. -* Unpacking the Sources:: Preparing the source tree. -* Doing the Build:: Compiling Kerberos. -* Testing the Build:: Making sure Kerberos built correctly. -* Options to Configure:: -* osconf.h:: -* Shared Library Support:: -* OS Incompatibilities:: Special cases to watch for. -* Using Autoconf:: Modifying Kerberos V5's - configuration scripts. - -Doing the Build - -* Building Within a Single Tree:: -* Building with Separate Build Directories:: -* Building using lndir:: - -Testing the Build - -* The DejaGnu Tests:: - -Shared Library Support - -* Shared Library Theory:: -* NetBSD Shared Library Support:: -* AIX Shared Library Support:: -* Solaris 5.3 Shared Library Support:: -* Alpha OSF/1 Shared Library Support:: - -Operating System Incompatibilities - -* Ultrix 4.2/3:: -* Alpha OSF/1 V1.3:: -* Alpha OSF/1 V2.0++:: -* BSDI:: -* Solaris versions 2.0 through 2.3:: -* Solaris 2.X:: -* SGI Irix 5.X:: - -Installation - -* Background:: -* Installation on any Machine:: -* Installing the KDC:: -* Migrating from V4 to V5 Kerberos:: -* A Sample Application:: -* Installing Kerberos Applications:: -* Common Kerberos Service Names:: - -Installation on any Machine - -* Picking a Realm Name:: -* Configuration files:: -* Recommended Programs:: - -Configuration files - -* krb5.conf:: -* Converting V4 configuration files:: -* /etc/services:: - -Installing the KDC - -* kdc.conf:: -* Initializing the KDB:: -* Storing the Master Password:: -* Adding Users to the Database:: -* Starting the Kerberos Server:: -* Setting up Slave Kerberos Servers:: -* Inter-realm Kerberos Operation:: -* The Administration Server:: -* Testing the Kerberos Server:: - -Setting up Slave Kerberos Servers - -* Kerberos Slave Database Propagation:: -* Installing a Slave Server:: - -A Sample Application - -* Installing the Sample Application:: -* Testing the Sample Server:: - -Installing Kerberos Applications - -* Levels of Security:: -* Preparing a Workstation for Kerberos Application Servers:: -* BSD Utilities:: -* Telnet and FTP:: - -BSD Utilities - -* Checksums:: Checksum facility for dealing with active attacks. -* BSD Utility Configuration Example:: Sample @file{inetd.conf} entries for BSD utilities. -@end menu - -@node Introduction, How Kerberos Works, Top, Top -@chapter Introduction - -This document describes the procedures necessary to compile Kerberos V5 -from the source distribution, and then to install it at a particular -site. The reader is assumed to be familiar with C/UNIX development -tools. - -In any complex software, there will be bugs. Please send bug reports -or other problems you may uncover to the e-mail address -@b{krb5-bugs@@mit.edu}. Please mention which version of the Kerberos -V5 distribution you are using, and whether you have made any private -changes. Bug reports that include proposed fixes are especially -welcome. If you do include fixes, please send them using either -context diffs or unified diffs (using @samp{diff -c} or @samp{diff --u}, respectively). - -Please note that there are still a number of aspects of Kerberos V5 -which will likely change before the 1.0 release. -As these changes occur, we will update the documentation accordingly. - -@c As of this release, all the databases, including the aname to localname -@c ones now use version 1.85 of the Berkeley DB code. This may imply -@c database conversions for those running earlier releases of Kerberos -@c V5. We recommend that you dump your database with the old kdb5_edit and -@c restore with the new one. - - -@node How Kerberos Works, Building Kerberos, Introduction, Top -@chapter How Kerberos Works: A Schematic Description - -This section provides a simplified description of a general user's -interaction with the Kerberos system. This interaction happens -transparently--users don't need to know and probably don't care about -what's going on--but Kerberos administrators might find a schematic -description of the process useful. This description glosses over a lot -of details; for more information, see @i{Kerberos: An Authentication -Service for Open Network Systems}, a paper presented at Winter USENIX -1988, in Dallas, Texas. - -@menu -* Network Services:: -* Kerberos Tickets:: -* The Kerberos Database:: -* Kerberos Realms:: -* The Ticket-Granting Ticket:: -* Network Services and the Master Database:: -* The User-Kerberos Interaction:: -@end menu - -@node Network Services, Kerberos Tickets, How Kerberos Works, How Kerberos Works -@section Network Services and Their Client Programs - -In an environment that provides network services, you use @dfn{client} -programs to request service from @dfn{server} programs that are -somewhere on the network. Suppose you have logged in to a workstation -and you want to @samp{rlogin} to another machine. You use the local -@samp{rlogin} client program to contact the remote machine's -@samp{rlogind} daemon. - -@node Kerberos Tickets, The Kerberos Database, Network Services, How Kerberos Works -@section Kerberos Tickets - -Under Kerberos, the @samp{rlogind} daemon allows you to login to a -remote machine if you can provide @samp{rlogind} a Kerberos ticket -which proves your identity. In addition to the ticket, you must also -have possession of the corresponding ticket session key. The -combination of a ticket and the ticket's session key is known as a credential. - -Typically, a client program automatically obtains credentials -identifying the person using the client program. The credentials are -obtained from a Kerberos server that resides somewhere on the network. -A Kerberos server maintains a database of user, server, and password -information. - -@node The Kerberos Database, Kerberos Realms, Kerberos Tickets, How Kerberos Works -@section The Kerberos Database - -Kerberos will give you credentials only if you have an entry in the Kerberos -server's @dfn{Kerberos database}. Your database entry includes your -Kerberos @dfn{principal} (which is often just your username), and -your Kerberos password. Every Kerberos user must have an entry in this -database. - -@node Kerberos Realms, The Ticket-Granting Ticket, The Kerberos Database, How Kerberos Works -@section Kerberos Realms - -Each site (or administrative domain within a site) will have their own -Kerberos database, which contains information about the users and -services for that particular site or administrative domain. -A @dfn{Kerberos Realm} is used to distinguish the users and services in -one particular area of administrative control from another area of -administrative control. - -Each Kerberos realm will have at least one Kerberos server, where the -master Kerberos database for that site or administrative domain is -stored. A Kerberos realm may also have one or more @dfn{slave servers}, -which have read-only copies of the Kerberos database which are -periodically propagated from the master server. For more details on how -this is done, see @ref{Setting up Slave Kerberos Servers}. - -@node The Ticket-Granting Ticket, Network Services and the Master Database, Kerberos Realms, How Kerberos Works -@section The Ticket-Granting Ticket - -The @samp{kinit} command prompts for your password, and if you enter -it successfully, you will obtain a @dfn{ticket-granting ticket} and a -@dfn{ticket session key} which gives you the right to use the ticket. -This combination of the ticket and its associated key is also known as -your @dfn{credentials}. As illustrated below, client programs use -your ticket-granting ticket credentials in order to obtain -client-specific credentials as needed. - -Your credentials are stored in a @dfn{credentials cache}, which is often -simply just a file in @file{/tmp}. The credentials cache is also -referred to as the @dfn{ticket file}, especially in Kerberos V4 -documentation. It should be noted, however, that a credentials cache -does not have to be stored in a file. - -@node Network Services and the Master Database, The User-Kerberos Interaction, The Ticket-Granting Ticket, How Kerberos Works -@section Network Services and the Master Database - -The master database also contains entries for all network services that -require Kerberos authentication. Suppose that your site -has a machine, @samp{laughter.mit.edu}, that requires Kerberos -authentication from anyone who wants to @samp{rlogin} to it. The host's -Kerberos realm is @samp{ATHENA.MIT.EDU}. - -This service must be registered in the Kerberos database, using the -proper service name, which in this case is -@samp{host/laughter.mit.edu@@ATHENA.MIT.EDU}. The @kbd{/} character -separates the various @dfn{components} of the Kerberos principal; the -@kbd{@@} character separates the realm name from the rest of the -principal name. The first component, @samp{host}, denotes the name or -type of the service that is being offered: generic host-level access to -the machine. The second component, @samp{laughter.mit.edu}, names the -specific machine which is offering this service. There will generally -be many different machines, each offering one particular type of -service, and the second component serves to give each one of these -servers a different Kerberos name. - -@menu -* The Keytab File:: -@end menu - -@node The Keytab File, , Network Services and the Master Database, Network Services and the Master Database -@subsection The Keytab File - -For each service, there must also be a @dfn{service key} known only by -Kerberos and the service. On the Kerberos server, the service key is -stored in the Kerberos database. - -On the server host, these service keys are stored in the @dfn{Key -tables}, or @dfn{keytab files}. (Keytab files were previously -referred to as @dfn{srvtab files} in the V4 literature.) The service -keys that are used by services which run as root are often stored in -the file @file{/etc/v5srvtab}. - -@b{WARNING:} This service key is the equivalent of the service's -password, and must be kept secure. Data which is meant to be read only -by the service is encrypted using this key. - -@node The User-Kerberos Interaction, , Network Services and the Master Database, How Kerberos Works -@section The User--Kerberos Interaction - -Suppose that you (in the guise of a general user) walk up to a workstation -intending to login to it, and then @samp{rlogin} to the machine @samp{laughter}. -Here's what happens: - -@enumerate - -@item -You login to the workstation and use the @samp{kinit} command -to get a ticket-granting ticket. -This command prompts you for your Kerberos password. (On some systems -which have a modified @samp{/bin/login} program, this may be done as -part of the login process, not requiring the user to run a separate -program.) - -@enumerate A - -@item -The @samp{kinit} command sends your request to the Kerberos master -server machine. The server software looks for your principal name's -entry in the Kerberos database. - -@item -If this entry exists, the Kerberos server creates and returns a -ticket-granting ticket and the key which allows you to use it, encrypted -by your password. If @samp{kinit} can decrypt the Kerberos reply using -the password you provide, it stores this ticket in a credentials cache -on your local machine for later use. The name of the credentials cache -can be specified in the @samp{KRB5_CCNAME} environment variable. If -this variable is not set, the name of the file will be -@file{/tmp/krb5cc_}, where is your UNIX user-id, represented -in decimal format. -@end enumerate - -@item -Now you use the @samp{rlogin} client to access the machine -@samp{laughter}. - -@example -host% @b{rlogin laughter} -@end example - -@enumerate A - -@item -The @samp{rlogin} client checks your ticket file to see if you -have a ticket for the @samp{host} service for @samp{laughter}. -You don't, so @samp{rlogin} uses the credential cache's ticket-granting -ticket to make a request to the master server's ticket-granting service. - -@item -This ticket-granting service receives the -@samp{host/laughter.mit.edu} request and looks in the master database -for an @samp{host/laughter.mit.edu} entry. If the entry exists, the -ticket-granting service issues you a ticket for that service. That -ticket is also cached in your credentials cache. - -@item -The @samp{rlogin} client now sends that ticket to -the @samp{laughter} @samp{rlogind} service program. The service program -checks the ticket by using its own service key. If the ticket is valid, -it now knows your identity. If the ticket is valid and you are allowed -to login to @samp{laughter} (because the your name matches one in -/etc/passwd, or you are in the @file{.k5login} file), you will find -yourself logged into the machine. - -@end enumerate -@end enumerate - -@node Building Kerberos, Installation, How Kerberos Works, Top -@chapter Building Kerberos - -Starting with the Beta 4 distribution, we are using a new configuration -system, which was built using the Free Software Foundation's -@samp{autoconf} program. This system will hopefully make Kerberos V5 -much simpler to build and reduce the amount of effort required in -porting Kerberos V5 to a new platform. - -@menu -* Build Requirements:: How much disk space, etc. you need to - build Kerberos. -* Unpacking the Sources:: Preparing the source tree. -* Doing the Build:: Compiling Kerberos. -* Testing the Build:: Making sure Kerberos built correctly. -* Options to Configure:: -* osconf.h:: -* Shared Library Support:: -* OS Incompatibilities:: Special cases to watch for. -* Using Autoconf:: Modifying Kerberos V5's - configuration scripts. -@end menu - -@node Build Requirements, Unpacking the Sources, Building Kerberos, Building Kerberos -@section Build Requirements - -In order to build Kerberos V5, you will need approximately 60-70 -megabytes of disk space. The exact amount will vary depending on the -platform and whether the distribution is compiled with debugging symbol -tables or not. - -If you wish to keep a separate @dfn{build tree}, which contains the compiled -@file{*.o} file and executables, separate from your source tree, you -will need a @samp{make} program which supports @samp{VPATH}, or -you will need to use a tool such as @samp{lndir} to produce a symbolic -link tree for your build tree. - -@node Unpacking the Sources, Doing the Build, Build Requirements, Building Kerberos -@section Unpacking the Sources - -The first step in each of these build procedures is to unpack the source -distribution. The Kerberos V5 distribution comes in two compressed tar -files. The first file, which is generally named @file{krb5.src.tar.gz}, -contains the sources for all of Kerberos except for the crypto library, -which is found in the file @file{krb5.crypto.tar.gz}. - -Both files should be unpacked in the same directory, such as -@file{/u1/krb5}. (In the rest of this document, we will assume that you -have chosen to unpack the Kerberos V5 source distribution in this -directory.) - - -@node Doing the Build, Testing the Build, Unpacking the Sources, Building Kerberos -@section Doing the Build - -You have a number of different options in how to build Kerberos. If you -only need to build Kerberos for one platform, using a single directory -tree which contains both the source files and the object files is the -simplest. However, if you need to maintain Kerberos for a large number -of platforms, you will probably want to use separate build trees for -each platform. We recommend that you look at see @ref{OS -Incompatibilities} for notes that we have on particular operating -systems. - -@menu -* Building Within a Single Tree:: -* Building with Separate Build Directories:: -* Building using lndir:: -@end menu - -@node Building Within a Single Tree, Building with Separate Build Directories, Doing the Build, Doing the Build -@subsection Building Within a Single Tree - -If you don't want separate build trees for each architecture, then -use the following abbreviated procedure. - -@enumerate -@item - @code{cd /u1/krb5/src} -@item - @code{./configure} -@item - @code{make} -@end enumerate - -That's it! - -@node Building with Separate Build Directories, Building using lndir, Building Within a Single Tree, Doing the Build -@subsection Building with Separate Build Directories - -If you wish to keep separate build directories for each platform, you -can do so using the following procedure. (Note, this requires that your -@samp{make} program support @samp{VPATH}. GNU's make will provide this -functionality, for example.) If your @samp{make} program does not -support this, see the next section. - -For example, if you wish to create a build directory for @code{pmax} binaries -you might use the following procedure: - -@enumerate -@item -@code{mkdir /u1/krb5/pmax} -@item - @code{cd /u1/krb5/pmax} -@item - @code{../src/configure} -@item - @code{make} -@end enumerate - -@node Building using lndir, , Building with Separate Build Directories, Doing the Build -@subsection Building Using @samp{lndir} - -If you wish to keep separate build directories for each platform, and -you do not have access to a @samp{make} program which supports @samp{VPATH}, -all is not lost. You can use the @samp{lndir} program to create -symbolic link trees in your build directory. - -For example, if you wish to create a build directory for solaris binaries -you might use the following procedure: - -@enumerate -@item - @code{mkdir /u1/krb5/solaris} -@item - @code{cd /u1/krb5/solaris} -@item - @code{/u1/krb5/src/util/lndir `pwd`/../src} -@item - @code{./configure} -@item - @code{make} -@end enumerate - -You must give an absolute pathname to @samp{lndir} because it has a bug that -makes it fail for relative pathnames. Note that this version differs -from the latest version as distributed and installed by the XConsortium -with X11R6. Either version should be acceptable. - -@node Testing the Build, Options to Configure, Doing the Build, Building Kerberos -@section Testing the Build - -The Kerberos V5 distribution comes with built-in regression tests. To -run them, simply type the following command while in the top-level build -directory (i.e., the directory where you sent typed @samp{make} to start -building Kerberos; see @ref{Doing the Build}.): - -@example -% make check -@end example - -@menu -* The DejaGnu Tests:: -@end menu - -@node The DejaGnu Tests, , Testing the Build, Testing the Build -@subsection The DejaGnu Tests - -Some of the built-in regression tests are setup to use the DejaGnu -framework for running tests. These tests tend to be more comprehensive -than the normal built-in tests as they setup test servers and test -client/server activities. - -DejaGnu may be found wherever GNU software is archived. - -Most of the tests are setup to run as a non-privledged user. There are -two series of tests (@samp{rlogind} and @samp{telnetd}) which require -the ability to @samp{rlogin} as root to the local machine. Admittedly, -this does require the use of a @file{.rhosts} file or some other -authenticated means. @footnote{If you are fortunate enough to have a -previous version of Kerberos V5 or V4 installed, and the Kerberos rlogin -is first in your path, you can setup @file{.k5login} or @file{.klogin} -respectively to allow you access.} - -If you cannot obtain root access to your machine, all the other tests -will still run. Note however, with DejaGnu 1.2, the "untested testcases" -will cause the testsuite to exit with a non-zero exit status which -@samp{make} will consider a failure of the testing process. Do not worry -about this, as these tests are the last run when @samp{make check} is -executed from the top level of the build tree. - - -@node Options to Configure, osconf.h, Testing the Build, Building Kerberos -@section Options to Configure - -There are a number of options to @samp{configure} which you can use to -control how the Kerberos distribution is built. The following table -lists the most commonly used options to Kerberos V5's @samp{configure} -program. - -@table @code - -@item --help - -Provides help to configure. This will list the set of commonly used -options for building Kerberos. - -@item --prefix=DIR - -By default, Kerberos will install the package's files rooted at -`/usr/local' as in `/usr/local/bin', `/usr/local/sbin', etc. If you -desire a different location use this option. - -@item --exec-prefix=DIR - -This option allows one to separate the architecture independent programs -from the configuration files and manual pages. - -@item --with-cc=COMPILER - -Use @code{COMPILER} as the C compiler. - -@item --with-ccopts=FLAGS - -Use @code{FLAGS} as the default set of C compiler flags. - -Note that if you use the native Ultrix compiler on a -DECstation you are likely to lose if you pass no flags to cc; md4.c -takes an estimated 3,469 billion years to compile if you provide neither -the @samp{-g} flag nor the @samp{-O} flag to @samp{cc}. - -@item --with-cppopts=CPPOPTS - -Use @code{CPPOPTS} as the default set of C preprocessor flags. The most -common use of this option is to select certain @code{#define}'s for use -with the operating system's include files. - -@item --with-linker=LINKER - -Use @code{LINKER} as the default loader if it should be different from C -compiler as specified above. - -@item --with-ldopts=LDOPTS - -This option allows one to specify optional arguments to be passed to the -linker. This might be used to specify optional library paths. - -@item --with-krb4 - -This option enables Kerberos V4 backwards compatibility using the -builtin Kerberos V4 library. - -@item --with-krb4=KRB4DIR - -This option enables Kerberos V4 backwards compatibility. The directory -specified by @code{KRB4DIR} specifies where the V4 header files should -be found (@file{/KRB4DIR/include}) as well as where the V4 Kerberos -library should be found (@file{/KRB4DIR/lib}). - -@item --without-krb4 - -Disables Kerberos V4 backwards compatibility. This prevents Kerberos V4 -clients from using the V5 services including the KDC. This would be -useful if you know you will never install or need to interact with V4 -clients. - -@item --with-netlib[=libs] - -Allows for suppression of or replacement of network libraries. By -default, Kerberos V5 configuration will look for @code{-lnsl} and -@code{-lsocket}. If your operating system has a broken resolver library -(see @ref{Solaris versions 2.0 through 2.3}) or fails to pass the tests in -@file{src/tests/resolv} you will need to use this option. - -@item --enable-shared - -This option will turn on the building and use of shared library objects -in the Kerberos build. This option is only supported on certain -platforms. - -@item --with-vague-errors - -If enabled, gives vague and unhelpful error messages to the client... er, -attacker. (Needed to meet silly government regulations; most other -sites will want to keep this undefined.) - -@item --with-kdc-kdb-update - -Set this option if you want to allow the KDC to modify the Kerberos -database; this allows the last request information to be updated, as -well as the failure count information. Note that this doesn't work if -you're using slave servers!!! It also causes the database to be -modified (and thus needing to be locked) frequently. Please note that -the implementors do not regularly test this feature. - -@item --with-kdb-db=database - -The configuration process will try to determine a working set of -libraries required to implement the Kerberos database. Configure will -look for interfaces that use or emulate a @samp{ndbm} or @samp{dbm} -library. Failing that, a build in copy of the Berkeley DB code will be -used. You may decide to compile a different interface than the default -by specifying one of "ndbm", "dbm", or "db". - -An important note on platforms where the @samp{ndbm} implementation is -based on @sc{GDBM} (such as the Linux Slackware distribution). @sc{GDBM} -has its own built in file locking which prevents simultaneous access to -the database from two separate processes in which one wants to modify -the database while the otherone only wants to read. (i.e. the KDC and -administrative servers). In this case, you will need to specify the use -of the Berkeley DB. - -@end table - -For example, in order to configure Kerberos on a Solaris machine using -the @samp{suncc} with the optimizer turned on, run the configure -script with the following options: - -@example -% ./configure --with-cc=suncc --with-ccopts=-O -@end example - -@node osconf.h, Shared Library Support, Options to Configure, Building Kerberos -@section @file{osconf.h} - -There is one configuration file which you may wish to edit to control -various compile-time parameters in the Kerberos distribution: -@file{include/krb5/stock/osconf.h}. The list that follows is by no means -complete, just some of the more interesting variables. - -Please note: The former configuration file @file{config.h} no longer -exists as its functionality has been merged into the auto-configuration -process. @xref{Options to Configure}. - - -@table @code - -@item DEFAULT_PROFILE_PATH - -The pathname to the file which contains the profiles for the known -realms, their KDCs, etc. - -The profile file format is no longer the same format as Kerberos V4's -@file{krb.conf} file. - -@item DEFAULT_LNAME_FILENAME - -The pathname to the database that maps authentication names to local -account names. See kdb5_anadd(8). - -@item DEFAULT_KEYTAB_NAME - -The type and pathname to the default server keytab file (the equivalent -of Kerberos V4's @file{/etc/srvtab}). - -@item DEFAULT_KDC_ENCTYPE - -The default encryption type for the KDC. - -@item KDCRCACHE - -The name of the replay cache used by the KDC. - -@item RCTMPDIR - -The directory which stores replay caches. - -@item DEFAULT_KDB_FILE - -The location of the default database - -@end table - -@node Shared Library Support, OS Incompatibilities, osconf.h, Building Kerberos -@section Shared Library Support - -Shared library support is provided for a few operating systems. There -are restrictions as to which compiler to use when using shared -libraries. In all cases, executables linked with the shared libraries in -this build process will have built in the location of the libraries, -therefore obliterating the need for special LD_LIBRARY_PATH, et al environment -variables when using the programs. Except where noted, multiple versions -of the libraries may be installed on the same system and continue to -work. - -Currently the supported platforms are: NetBSD 1.0A, AIX 3.2.5, AIX 4.1, -Solaris 5.3, Alpha OSF/1 >= 2.1, HP-UX >= 9.X. - -To enable shared libraries on the above platforms, run the configure -script with the option @samp{--enable-shared}. - -One special note is that if the Kerberos V4 compatibility is compiled -in, you @b{must not} specify an alternate Kerberos V4 library from the -one in the tree or you will be missing references. - -@menu -* Shared Library Theory:: -* NetBSD Shared Library Support:: -* AIX Shared Library Support:: -* Solaris 5.3 Shared Library Support:: -* Alpha OSF/1 Shared Library Support:: -@end menu - -@node Shared Library Theory, NetBSD Shared Library Support, Shared Library Support, Shared Library Support -@subsection Theory of How Shared Libraries are Used - -An explanation of how shared libraries are implemented on a given -platform is too broad a topic for this manual. Instead this will touch -on some of the issues that the Kerberos V5 tree uses to support version -numbering and alternate install locations. - -Normally when one builds a shared library and then links with it, the -name of the shared library is stored in the object -(i.e. libfoo.so). Most operating systems allows one to change name that -is referenced and we have done so, placing the version number into the -shared library (i.e. libfoo.so.0.1). At link time, one would reference -libfoo.so, but when one executes the program, the shared library loader -would then look for the shared library with the alternate name. Hence -multiple versions of shared libraries may be supported relatively -easily. @footnote{Under AIX for the RISC/6000, multiple versions of -shared libraries are supported by combining two or more versions of the -shared library into one file. The Kerberos build procedure produces -shared libraries with version numbers in the internal module names, so -that the shared libraries are compatible with this scheme. -Unfortunately, combining two shared libraries requires internal -knowledge of the AIX shared library system beyond the scope of this -document. Practicallyspeaking, only one version of AIX shared libraries -can be supported on a system, unless the multi-version library is -constructed by a programmer familiar with the AIX internals.} - -All operating systems (that we have seen) provide a means for programs -to specify the location of shared libraries. On different operating -systems, this is either specified when creating the shared library, and -link time, or both.@footnote{Both are necessary sometimes as the shared -libraries are dependent on other shared libraries} The build process -will hardwire a path to the installed destination. - - -@node NetBSD Shared Library Support, AIX Shared Library Support, Shared Library Theory, Shared Library Support -@subsection NetBSD Shared Library Support - -Shared library support has been tested under NetBSD 1.0A using -GCC 2.4.5. Due to the vagaries of the loader in the operating system, -the library load path needs to be specified in building libraries and in -linking with them. Unless the library is placed in a standard location -to search for libraries, this may make it difficult for developers to -work with the shared libraries. - -@node AIX Shared Library Support, Solaris 5.3 Shared Library Support, NetBSD Shared Library Support, Shared Library Support -@subsection AIX Shared Library Support - - AIX specifies shared library versions by combining multiple -versions into a single file. Because of the complexity of this process, -no automatic procedure for building multi-versioned shared libraries is -provided. Therefore, supporting multiple versions of the Kerberos shared -libraries under AIX will require significant work on the part of a -programmer famiiliar with AIX internals. - - AIX allows a single library to be used both as a static library -and as a shared library. For this reason, the @samp{--enable-shared} -switch to configure builds only shared libraries. On other operating -systems, both shared and static libraries are built when this switch is -specified. As with all other operating systems, only non-shared static -libraries are built when @samp{--enable-shared} is not specified. - - The AIX 3.2.5 linker dumps core trying to build a shared -@samp{libkrb5.a} produced with the GNU C compiler. The native AIX -compiler works fine. In addition, the AIX 4.1 linker is able to build a -shared @samp{libkrb5.a} when GNU C is used. - - -@node Solaris 5.3 Shared Library Support, Alpha OSF/1 Shared Library Support, AIX Shared Library Support, Shared Library Support -@subsection Solaris 5.3 Shared Library Support - -Shared library support only works when using the Sunsoft C compiler. We -are currently using version 3.0.1. - -The path to the shared library must be specified at link time as well as -when creating libraries. - -@node Alpha OSF/1 Shared Library Support, , Solaris 5.3 Shared Library Support, Shared Library Support -@subsection Alpha OSF/1 Shared Library Support - -Shared library support has been tested with V2.1 and higher of the -operating system. Shared libraries may be compiled both with GCC and the -native compiler. - -One of the nice features on this platform is that the paths to the -shared libraries is specified in the library itself without requiring -that one specify the same at link time. - -We are using the @samp{-rpath} option to @samp{ld} to place the library -load path into the executables. The one disadvantage of this is during -testing where we want to make sure that we are using the build tree -instead of a possibly installed library. The loader uses the contents of -@samp{-rpath} before LD_LIBRARY_PATH so we must specify a dummy _RLD_ROOT -and complete LD_LIBRARY_PATH in our tests. - -The one disadvantage with the -method we are using - -@node OS Incompatibilities, Using Autoconf, Shared Library Support, Building Kerberos -@section Operating System Incompatibilities - -This section details operating system incompatibilities with Kerberos V5 -which have been reported to the developers at MIT. If you find additional -incompatibilities, and/or discover work arounds to such problems, please -send a report to @b{krb5-bugs@@mit.edu}. Thanks! - -@menu -* Ultrix 4.2/3:: -* Alpha OSF/1 V1.3:: -* Alpha OSF/1 V2.0++:: -* BSDI:: -* Solaris versions 2.0 through 2.3:: -* Solaris 2.X:: -* SGI Irix 5.X:: -@end menu - -@node Ultrix 4.2/3, Alpha OSF/1 V1.3, OS Incompatibilities, OS Incompatibilities -@subsection Ultrix 4.2/3 - -On the DEC MIPS platform, using the native compiler, @file{md4.c} and -@file{md5.c} can not be compiled with the optimizer set at level 1. -That is, you must specify either @samp{--with-ccopts=-O} and -@samp{--with-ccopts=-g} to configure. If you don't specify either, the -compile will never complete. - -The optimizer isn't hung; it just takes an exponentially long time. -Compiling 6 out of the 48 algorithmic steps takes 3 seconds; compiling 7 -steps takes 9 seconds; compiling 8 steps takes 27 seconds, and so on. -Calculations estimate it will finish in approximately 3,469 billion -years.... - -Using GCC instead of the native compiler will also work fine, both with -or without optimization. - -@node Alpha OSF/1 V1.3, Alpha OSF/1 V2.0++, Ultrix 4.2/3, OS Incompatibilities -@subsection Alpha OSF/1 V1.3 - -Using the native compiler, compiling with the @samp{-O} compiler flag -causes the @code{asn.1} library to be compiled incorrectly. - -Using GCC version 2.6.3 or later instead of the native compiler will also work -fine, both with or without optimization. - -@node Alpha OSF/1 V2.0++, BSDI, Alpha OSF/1 V1.3, OS Incompatibilities -@subsection Alpha OSF/1 V2.0++ - -There used to be a bug when using the native compiler in compiling -@file{md4.c} when compiled without either the @samp{-O} or @samp{-g} -compiler options. We have changed the code and there is no problem -under V2.1, but we do not have access to V2.0 to test and see if the -problem would exist there. (We welcome feedback on this issue). There -was never a problem in using GCC version 2.6.3. - -In version 3.2 and beyond of the operating system, we have not seen any -problems with the native compiler. - -@node BSDI, Solaris versions 2.0 through 2.3, Alpha OSF/1 V2.0++, OS Incompatibilities -@subsection BSDI - -BSDI versions 1.0 and 1.1 reportedly has a bad @samp{sed} which causes -it to go into an infinite loop during the build. The work around is -to use a @samp{sed} from somewhere else, such as GNU. (This may be -true for some versions of other systems derived from BSD 4.4, such as -NetBSD and FreeBSD.) - -@node Solaris versions 2.0 through 2.3, Solaris 2.X, BSDI, OS Incompatibilities -@subsection Solaris versions 2.0 through 2.3 - -The @code{gethostbyname()} routine is broken; it does not return a fully -qualified domain name, even if you are using the Domain Name Service -routines. Since Kerberos V5 uses the fully qualified domain name as the -second component of a service principal (i.e, -@samp{host/tsx-11.mit.edu@@ATHENA.MIT.EDU}), this causes problems for servers -who try to figure out their own fully qualified domain name. - -Workarounds: - -@enumerate - -@item - Supply your own resolver library. (such as bind-4.9.3pl1 availavle -from ftp.vix.com) - -@item - Upgrade to Solaris 2.4 - -@item - Make sure your /etc/nsswitch.conf has `files' before `dns' like: - -@example -hosts: files dns -@end example - -and then in /etc/hosts, make sure there is a line with your -workstation's IP address and hostname, with the fully qualified domain -name first. Example: - -@example -18.172.1.4 dcl.mit.edu dcl -@end example - -Note that making this change may cause other programs in your -environment to break or behave differently. - -@end enumerate - -@node Solaris 2.X, SGI Irix 5.X, Solaris versions 2.0 through 2.3, OS Incompatibilities -@subsection Solaris 2.X - -You @b{must} compile Kerberos V5 without the UCB compatibility -libraries. This means that @file{/usr/ucblib} must not be in the -LD_LIBRARY_PATH environment variable when you compile it. Alternatively -you can use the @code{-i} option to @samp{cc}, by using the specifying -@code{--with-ccopts=-i} option to @samp{configure}. - -@node SGI Irix 5.X, , Solaris 2.X, OS Incompatibilities -@subsection SGI Irix 5.X - -If you are building in a tree separate from the source tree, the vendors -version of make does not work properly with regards to -@samp{VPATH}. It also has problems with standard inference rules in 5.2 -(not tested yet in 5.3) so one needs to use GNU's make. - -Under 5.2, there is a bug in the optional System V @code{-lsocket} -library in which the routine @code{gethostbyname()} is broken. The -system supplied version in @code{-lc} appears to work though so one may -simply specify @code{--with-netlib} option to @samp{configure}. - -In 5.3, @code{gethostbyname()} is no longer present in @code{-lsocket} and -is no longer an issue. - -@node Using Autoconf, , OS Incompatibilities, Building Kerberos -@section Using @samp{Autoconf} - -(If you are not a developer, you can skip this section.) - -In most of the Kerberos V5 source directories, there is a -@file{configure} script which automatically determines the compilation -environment and creates the proper Makefiles for a particular platform. -These @file{configure} files are generated using @samp{autoconf} version -2.4, which can be found in the @file{src/util/autoconf} directory in the -distribution. - -Normal users will not need to worry about running @samp{autoconf}; the -distribution comes with the @file{configure} files already prebuilt. -Developers who wish to modify the @file{configure.in} files should see -@ref{Top, , Overview, autoconf, The Autoconf Manual}. - -Note that in order to run @samp{autoconf}, you must have GNU @samp{m4} -in your path. Before you use the @samp{autoconf} in the Kerberos V5 -source tree, you may also need to run @samp{configure}, and then run -@samp{make} in the @file{src/util/autoconf} directory in order to -properly set up @samp{autoconf}. - -One tool which is provided for the convenience of developers can be -found in @file{src/util/reconf}. This program should be run while the -current directory is the top source directory. It will automatically -rebuild any @file{configure} files which need rebuilding. If you know -that you have made a change that will require that all the -@file{configure} files need to be rebuilt from scratch, specify the -@code{--force} option: - -@example -% cd /u1/krb5/src -% ./util/reconf --force -@end example - -The developmental sources are a raw source tree (before it's been packaged -for public release), without the pre-built @file{configure} files. -In order to build from such a source tree, you must do: - -@example -% cd krb5/util/autoconf -% ./configure -% make -% cd ../.. -% util/reconf -@end example - -Then follow the instructions for building packaged source trees (above). -To install the binaries into a binary tree, do: - -@example -% cd /u1/krb5/src -% make all -% make install DESTDIR=somewhere-else -@end example - -@node Installation, Troubleshooting, Building Kerberos, Top -@chapter Installation - -When you are installing Kerberos for the first time at a site, you must -first decide on the realm name you will use for your site, and select a -machine to host the @dfn{Kerberos server}, which is also known as the -@dfn{KDC} (@dfn{Key Distribution Center}). The KDC must be located on a -secure machine, since its database contains the keys for the entire -realm. It is extremely important that the database be kept secure, if -the realm's Kerberos service is to remain secure. - -Once a KDC is installed and configured, you may then set up one or more -client machines, and one or more application machines. - -@menu -* Background:: -* Installation on any Machine:: -* Installing the KDC:: -* Migrating from V4 to V5 Kerberos:: -* A Sample Application:: -* Installing Kerberos Applications:: -* Common Kerberos Service Names:: -@end menu - -@node Background, Installation on any Machine, Installation, Installation -@section Background Information - -Your system's security is only as good as the security of your -@samp{root} password. You should take other precautions to protect your -system security in addition to installing Kerberos. Kerberos cannot -protect you from someone who is able to steal @samp{root} privileges. -Kerberos also does not protect you from break-ins caused by bugs in your -daemons (e.g., @samp{fingerd} or @samp{sendmail}). On almost all UNIX -systems, if intruders can break in as an ordinary users, they can obtain -superuser privileges by exploiting bugs or imperfect configuration files. - - -@node Installation on any Machine, Installing the KDC, Background, Installation -@section Installation on any Machine - -The following steps must be performed no matter what type of -machine (KDC, Client, or Application server) you are installing. All -machines functioning within the same administrative domain must use the -same Kerberos realm name; and all machines which are using Kerberos must -have the Kerberos configuration files properly installed. - -If you are installing Kerberos on a machine that will act only as a -Kerberos client, this section describes all that you need to do. If you -are installing a KDC, or an Kerberos Application server, you will also -need to complete the procedures detailed in @ref{Installing the KDC}, or -@ref{A Sample Application}, after you finish with the procedures found -in this section. - -@menu -* Picking a Realm Name:: -* Configuration files:: -* Recommended Programs:: -@end menu - -@node Picking a Realm Name, Configuration files, Installation on any Machine, Installation on any Machine -@subsection Picking a Realm Name - -Before you install Kerberos V5 at your site, you have to choose a -@dfn{realm name}, the name that specifies the system's administrative -domain. By convention, we suggest that you use your internet domain -name, in capital letters. (Kerberos realm names are case-sensitive, so -it's important that your realm name be in all upper case.) For example, -if your internet domain is @code{cygnus.com} (so that you have hostnames -such as @code{ftp.cygnus.com} and @code{tweedledum.cygnus.com}), then -your Kerberos realm should be @code{CYGNUS.COM}. Please note that -changing realm names is hard. Get it right the first time. - -@node Configuration files, Recommended Programs, Picking a Realm Name, Installation on any Machine -@comment node-name, next, previous, up@section -@subsection Configuration files - - -@menu -* krb5.conf:: -* Converting V4 configuration files:: -* /etc/services:: -@end menu - -@node krb5.conf, Converting V4 configuration files, Configuration files, Configuration files -@subsubsection The @file{krb5.conf} File - -The @file{krb5.conf} file contains information needed by the Kerberos V5 -library including a system's default Kerberos -realm, and the locations of the Kerberos servers. - -The @file{krb5.conf} uses an INI-style format. Sections are delimited by -square braces; within each section, there are relations where tags can -be assigned to have specific values. Tags can also contain a -subsection, which contains further relations or subsections. A tag can -be assigned to multiple values. - -Create a @file{/etc/krb5.conf} file using the following format: - -@example -[libdefaults] - default_realm = - -[realms] - = @{ - kdc = - admin_server = - default_domain = - @} - -[domain_realm] - <.domain.name> = -@end example - -Where @samp{realm_name} specifies the default realm to be used by that -particular system, and @samp{master_server_name} specifies the machine -name on which you will run the master server. The keywords @samp{kdc} -and @samp{admin_server} lists the location of the realms KDC and -administration servers. - -For example, if your realm name is @samp{ATHENA.MIT.EDU} and your master -server's name is @samp{kerberos.mit.edu}, the file should have these -contents: - -@example -[libdefaults] - default_realm = ATHENA.MIT.EDU - -[realms] - ATHENA.MIT.EDU = @{ - kdc = KERBEROS.MIT.EDU - admin_server = KERBEROS.MIT.EDU - default_domain = MIT.EDU - @} - -[domain_realm] - .mit.edu = ATHENA.MIT.EDU - mit.edu = ATHENA.MIT.EDU -@end example - - -In many situations, the default realm in which a host operates will be -identical to its Internet domain name, with the first component removed -and all letters capitalized. For example, @code{ftp.cygnus.com} is -traditionally in the realm @code{CYGNUS.COM}. -If this is not the case, you will need to establish a translation from -host name or domain name to realm name. This is accomplished with the -@samp{[domain_realm]} stanza. - -Each line of the translation file specifies either a host name or domain -name, and its associated realm: - -@example -[domain_realm] - <.domain.name> = KERBEROS.REALM1 - = KERBEROS.REALM2 -@end example - -For example, to map all hosts in the domain LSC.MIT.EDU to LSC.MIT.EDU -but the host FILMS.LSC.MIT.EDU to MIT.EDU your file would read: -@example -[domain_realm] - .LSC.MIT.EDU = LSC.MIT.EDU - FILMS.LSC.MIT.EDU = MIT.EDU -@end example - -If a particular host name matches both a domain name and a host name in -@samp{[domain_realm]}, the entry containing the host name takes precedence. - -See the @file{[SOURCE_DIR]/config-files/krb5.conf} file for an example -@file{krb5.conf} file. That file has examples of how to provide backup -servers for a given realm (additional lines with the same leading realm -name) and how to designate servers for remote realms. - -@node Converting V4 configuration files, /etc/services, krb5.conf, Configuration files -@subsubsection Conversion of V4 configuration files - -Kerberos V4's @file{krb.conf} and @file{krb.realms} files formats are no -longer used by the V5 library. A @sc{PERL} script has been provided to allow -for "easy" generation of an initial @file{krb5.conf}. It is located in -@file{[SOURCE_DIR]/config-files/convert-config-files}. The produced file -should be checked for errors. - -Note that if you are planning on using certain applications with -Kerberos V4 compatibility compiled in, the V4 library still needs the -files @file{krb.conf} and @file{krb.realms}. - - -@node /etc/services, , Converting V4 configuration files, Configuration files -@subsubsection /etc/services - -All hosts which will use Kerberos will need to have certain ports -defined in the system's @file{/etc/services} file. The file -@file{[SOURCEDIR]/config-files/services.append} contains the entries -which should be appended to the @file{/etc/services} file. Please note -that not all of the entries are required as several of the programs have -defaults built into the programs. This will be documented sometime in -the future. - -If you are using the Network Information Services (NIS) or Yellow -Pages (YP), you will need to add the services in the -@file{services.append} file to the services exported in the NIS or YP -server. - -@node Recommended Programs, , Configuration files, Installation on any Machine -@subsection Recommended Programs - -The following files should be installed on all machines which are -running Kerberos, either as a client, a KDC, or an application server: - -If you used the default @samp{make install} without using the -@samp{--prefix} argument to @file{configure}, then [K_USER] refers to -@file{/usr/local/bin}. - -@itemize @bullet -@item @file{/etc/krb5.conf} --- This files contains information required -by Kerberos V5 giving system defaults as well as locations of Kerberos -servers. -@item @file{[K_USER]/kinit} --- This program allows you to obtain -Kerberos credentials. -@item @file{[K_USER]/kdestroy} --- This program allows you to destroy -Kerberos credentials which are no longer needed. -@item @file{[K_USER]/klist} ---- This program allows you to list the -credentials found in your credentials cache. -@end itemize - -@node Installing the KDC, Migrating from V4 to V5 Kerberos, Installation on any Machine, Installation -@section Installing the KDC - -@menu -* kdc.conf:: -* Initializing the KDB:: -* Storing the Master Password:: -* Adding Users to the Database:: -* Starting the Kerberos Server:: -* Setting up Slave Kerberos Servers:: -* Inter-realm Kerberos Operation:: -* The Administration Server:: -* Testing the Kerberos Server:: -@end menu - -@node kdc.conf, Initializing the KDB, Installing the KDC, Installing the KDC -@subsection The optional @file{kdc.conf} profile - -There is an optional configuration file @file{kdc.conf} that allows one -to specify per-realm configuration data to be used by the Kerberos V5 -Authentication Service and Key Distribution Center. This information -includes database locations, key and per-realm defaults, port numbers, -ticket life times, etc. The location of the configuration file is -@file{/usr/local/lib/krb5kdc/kdc.conf}. - -See the man page or @file{[SOURCEDIR]/config-files/kdc.conf.M} for more -details. - -This document assumes that you do not have the @file{kdc.conf} -configuration file installed. - -Note also that @code{[logging]} subsection to @file{/etc/krb5.conf} can -be used to specify where to syslog messages regarding server activity. - -@node Initializing the KDB, Storing the Master Password, kdc.conf, Installing the KDC -@subsection Initializing the Kerberos Database - -Login to the Kerberos KDC, and use the @samp{su} command to become root. -If you installed the Kerberos administration tools -with the @samp{make install} command and the default pathnames, -they should be in the @file{/usr/local/admin} directory. -If you installed the tools in a different directory, -hopefully you know what it is. -From now on, we will refer to this directory as [ADMIN_DIR]. - -The default database will be located in the directory -@file{/usr/local/lib/krb5kdc} unless changed in the configuration -process. From now on, we will call this [DB_DIR]. - -The @samp{kdb5_create} command creates and initializes the master database. -It asks you to the database's master password. -Do not forget this password. -If you do, the database becomes useless. -(Your realm name should be substituted for [REALMNAME] below.) -@xref{Storing the Master Password} for an alternative way of dealing -with this master password. - -Because the install process does not create [DB_DIR] you need to do so -yourself. - -Use @samp{kdb5_create} as follows: - -@example -# @b{mkdir [DB_DIR]} -# @b{[ADMIN_DIR]/kdb5_create} -Initializing database '[DB_DIR]/principal' for realm '[REALMNAME]', -master key name 'K/M@@[REALMNAME]' -You will be prompted for the database Master Password. -It is important that you NOT FORGET this password. -Enter KDC database master key: @b{<-- [Enter the master password.]} -Re-enter KDC database master key to verify: @b{<-- [Re-enter it.]} -@end example - - -@node Storing the Master Password, Adding Users to the Database, Initializing the KDB, Installing the KDC -@subsection Storing the Master Password - -The @samp{kdb5_stash} command "stashes" the master password in the file -@file{[DB_DIR]/.k5.[REALM.NAME]} so that the Kerberos server can be started -automatically during an unattended reboot of the master server. Other -administrative programs use this hidden password so that they can access -the master database without someone having to manually provide the -master password. This command is an optional one; if you'd rather enter -the master password each time you start the Kerberos server, don't use -@samp{kdb5_stash}. - -On the one hand, if you use @samp{kdb5_stash}, a copy of the master key -will reside on a disk, which may not be acceptable; on the other hand, -if you don't use @samp{kdb5_stash}, the server cannot be started unless -someone is around to type the password manually. - -The command merely prompts for the master password: - -@example -# @b{[ADMIN_DIR]/kdb5_stash} -Enter KDC database master key: @b{<-- [Enter the master password.]} -@end example - -WARNING: If your Kerberos database master key is compromised and the -database is obtained, the security of your entire authentication system -is compromised. (If this happens to you, all of your user's passwords must -be set to new values manually --- i.e., not using Kerberos.) The master -key must be a carefully kept secret. If you keep backups, you must -guard all the master keys you use, in case someone has stolen an old -backup and wants to attack users' whose passwords haven't changed since -the backup was stolen. This is why we provide the option not to store -it on disk. - -@node Adding Users to the Database, Starting the Kerberos Server, Storing the Master Password, Installing the KDC -@subsection Adding Users to the Database - -The @samp{kdb5_edit} program may be used to add new users and services to -the master database, and to modify existing database -information. @xref{The Administration Server} for an alternative method -once the Kerberos environment is up and running. - -For example, to add yourself to the newly created database: (replace -@samp{[USERNAME]} with your username with. - -@example -# @b{[ADMIN_DIR]/kdb5_edit} -kdb5_edit: @b{ank [USERNAME]} -Enter password: @b{<-- [Enter your password.]} -Re-enter password for verification: @b{<-- [Re-enter it.]} -kdb5_edit: @b{quit} -@end example - -The @samp{ank} command is short for "add_new_key"; this command adds a -new user to the database. To see what other commands which @samp{kdb5_edit} -supports, type @kbd{? @key{RET}} at the @samp{kdb5_edit} prompt. - -@node Starting the Kerberos Server, Setting up Slave Kerberos Servers, Adding Users to the Database, Installing the KDC -@subsection Starting the Kerberos Server - -Assuming that you didn't use the @samp{--prefix} argument to -@file{configure}, then [K_SERVER] refers to @file{/usr/local/sbin}. - -In order to start the Kerberos server, simply run it. It will fork and -disassociate from the terminal unless the @samp{-n} argument is used. - -@example -# @b{[K_SERVER]/krb5kdc} -@end example - -If you have used the @samp{kdb5_stash} command to store the master database password, -the server will start automatically. -If you did not use @samp{kdb5_stash}, -use the following command: - -@example -# @b{[K_SERVER]/krb5kdc -m} -@end example - -The server will prompt you to enter the master password before actually -starting itself. - -@node Setting up Slave Kerberos Servers, Inter-realm Kerberos Operation, Starting the Kerberos Server, Installing the KDC -@subsection Setting up Slave Kerberos Servers - -Slave Kerberos servers allow clients to be able to get Kerberos tickets -even when the Master server is not available. Users will not be able to -change their passwords --- changes can only be made to database on the -Master server; however, users will be able to authenticate to -application servers, which is critically important in a distributed -client-server environment. The current implementation of the client code -does not provide load sharing in that the order of servers contacted is -the same as those listed in the @file{krb5.conf} file. - -@menu -* Kerberos Slave Database Propagation:: -* Installing a Slave Server:: -@end menu - -@node Kerberos Slave Database Propagation, Installing a Slave Server, Setting up Slave Kerberos Servers, Setting up Slave Kerberos Servers -@subsubsection Kerberos Slave Database Propagation - -In order to propagate the Kerberos database from the Master server to -the slaves, the @samp{kprop} and @samp{kpropd} client/server programs -are used. Periodically, the Master server will dump the Kerberos -database out into an ASCII format, using the @samp{kdb5_edit} program. -The master server will then run @samp{kprop} to propagate the dumped -database file to each slave server. - -On the slave server, the @samp{kpropd} program is invoked out of -@samp{inetd} server. After @samp{kprop} and @samp{kpropd} have -mutually authenticated with one another, and @samp{kpropd} is satisfied -with the identity of the Master server, then the dumped ASCII database -is transferred to the slave server in an encrypted fashion. After the -database is transfered, @samp{kpropd} will then run @samp{kdb5_edit} -with the appropriate arguments in order to undump the database into a -usable form by the KDC on the slave server. - -@node Installing a Slave Server, , Kerberos Slave Database Propagation, Setting up Slave Kerberos Servers -@subsubsection Installing a Slave Server - -@b{To be written.} - - -@node Inter-realm Kerberos Operation, The Administration Server, Setting up Slave Kerberos Servers, Installing the KDC -@subsection Inter-realm Kerberos Operation - -@b{To be written.} - -@node The Administration Server, Testing the Kerberos Server, Inter-realm Kerberos Operation, Installing the KDC -@subsection The Administration Server - -There is currently an administration server in the Kerberos source tree. -It is, however, very rough, and it will likely be significantly changed -or replaced before the 1.0 release. Hence, this manual does not -document the current administration server. Changes to the database can -be made by logging in to the KDC directly, and using the -@samp{kdb5_edit} program; see @ref{Adding Users to the Database}. - -@node Testing the Kerberos Server, , The Administration Server, Installing the KDC -@subsection Testing the Kerberos Server - -Use the @samp{kinit} command to obtain Kerberos credentials. This command -creates your credentials cache and stores your credentials in it. - -If you used the default @samp{make install} command and directories to -install the Kerberos user utilities, @samp{kinit} will be in the -@file{/usr/local/bin} directory. From now on, we'll refer to the Kerberos user -commands directory as [K_USER]. - -Use @samp{kinit} as follows: - -@example -% @b{[K_USER]/kinit [USERNAME]} -Password for [USERNAME]@@[REALMNAME]: @b{<-- enter your password} -@end example - - -Use the @samp{klist} program to list the contents of your ticket file. - -@example -% @b{[K_USER]/klist} -Ticket cache: /tmp/krb5cc_15806 -Default principal: [USERNAME]@@[REALMNAME] - - Valid starting Expires Service principal -31-Jan-95 21:58:32 1-Feb-95 05:57:39 krbtgt/[REALMMNAME]@@[REALMNAME] - -@end example - -@ignore -@c not yet... -If you have any problems, you can examine the log file -@file{/krb5/kerberos.log} on the Kerberos server machine to see if -there was some sort of error. -@end ignore - -@node Migrating from V4 to V5 Kerberos, A Sample Application, Installing the KDC, Installation -@section Migrating from V4 to V5 Kerberos - -@b{To be written.} A rough idea of the procedure that one may follow is -in @file{[SOURCE_DIR]/kdc/migration.doc}. - -@node A Sample Application, Installing Kerberos Applications, Migrating from V4 to V5 Kerberos, Installation -@section A Sample Application - -This release of Kerberos comes with a sample application server and a -corresponding client program. You will find this software -@file{[K_SERVER]/sserver} and @file{[K_USER]/sclient}, which is the -server's executable, and the client program's executable, respectively. - -The programs are rudimentary. -When they have been installed (the installation procedure is described -in detail later), they work as follows: - -@enumerate - -@item - The user starts @samp{sclient} and provides as arguments -to the command the name of the server machine and an optional port on -which to contact the server. - -@item - @samp{sclient} contacts the server machine and -authenticates the user to @samp{sserver}. - -@item - @samp{sserver} authenticates itself to @samp{sclient} (thus -performing mutual authentication), and -then returns a message to the client program. -This message contains the name of the Kerberos principal that was used -to authenticate to @samp{sserver}. - -@item - @samp{sclient} displays the server's message on the user's -terminal screen. - -@end enumerate - -@menu -* Installing the Sample Application:: -* Testing the Sample Server:: -@end menu - -@node Installing the Sample Application, Testing the Sample Server, A Sample Application, A Sample Application -@subsection Installing the Sample Application - -In general, -you use the following procedure to install a Kerberos-authenticated -server-client system. - -@enumerate - -@item - Add the appropriate entry to the Kerberos database using @samp{kdb_edit} - -@item - Create a @file{/etc/v5srvtab} file for the server machine. - -@item - Install the service program and the @file{/etc/v5srvtab} -file on the server machine. - -@item - Install the client program on the client machine. - -@item - Update the @file{/etc/services} file on the client and server machines. -@end enumerate - -We will use the sample application as an example, although programs -which do not take requests via the @samp{inetd} program may have -slightly different installation procedures. @samp{Inetd} starts -@samp{sserver} each time a client process contacts the server machine. -@samp{sserver} processes the request, terminates, then is restarted -when @samp{inetd} receives another @samp{sserver} request. When you -install the program on the server, you must add a @samp{sample} entry to -the server machine's @file{/etc/inetd.conf} file. - -The following description assumes that you are installing -@samp{sserver} on the machine @samp{jimi.mit.edu}. -Here's the process, step by step: - -@enumerate - -@item - Login as root or @samp{su} to root on the Kerberos server machine. -Use the @samp{kdb5_edit} program to create an entry for -@code{sample} in the Kerberos database: - -@example -# @b{[ADMIN_DIR]/kdb5_edit} -kdb5_edit: @b{add_random_key sample/jimi.mit.edu} -kdb5_edit: @b{quit} -@end example - -(Note: @samp{add_random_key} may be abbreviated as @samp{ark}.) - -@item - Use @samp{kdb5_edit} to create a @file{srvtab} file -for @samp{sserver}'s host machine: - -@example -# @b{[ADMIN_DIR]/kdb5_edit} -kdb5_edit: @b{extract_srvtab jimi.mit.edu sample} -'sample/jimi.mit.edu@@ATHENA.MIT.EDU' added to keytab 'WRFILE:jimi.mit.edu-new-srvtab' -kdb5_edit: @b{quit} -@end example - -(Note: @samp{extract_srvtab} may be abbreviated as @samp{xst}.) - -Transfer the @file{jimi.mit.edu-new-srvtab} file to @samp{jimi.mit.edu} -and install it as @file{/etc/v5srvtab}. - -@b{WARNING}: Note that this file is equivalent to the service's password and -should be treated with care. For example, it could be transferred by -removable media, but should not be sent over an open network in the -clear. This file should installed such that only the root user can read -it. - -@item - Add the following line to the @file{/etc/services} file on -@samp{jimi.mit.edu}, and on all machines that will run the -@samp{sample_client} program: - -@example -sample 906/tcp # Kerberos sample app server -@end example - -@item - Add a line similar to the following line to the @file{/etc/inetd.conf} -file on @samp{sample_server}'s machine: - -@example -sample stream tcp nowait switched root - [K_SERVER]/sserver sample_server -@end example - -where [K_SERVER] should be substituted with -the path to the @samp{sserver} program. -(This @file{inetd.conf} information should be placed on one line.) -You should examine existing lines in @file{/etc/inetd.conf} and use the -same format used by other entries (e.g. for telnet). Most systems do -not have a column for the `switched' keyword, and some do not have a -column for the username (usually `root', as above). - -@item - Restart @samp{inetd} by sending the current @samp{inetd} process -a hangup signal: - -@example -# @b{kill -HUP} @i{process_id_number} -@end example - -@item - The @samp{sserver} is now ready to take @samp{sclient} requests. - -@end enumerate - -@node Testing the Sample Server, , Installing the Sample Application, A Sample Application -@subsection Testing the Sample Server - -Assume that you have installed @samp{sserver} on @samp{jimi.mit.edu}. - -Login to your workstation and use the @samp{kinit} command to -obtain a Kerberos ticket-granting ticket: - -@example -% @b{[K_USER]/kinit [USERNAME]} -Password for [USERNAME]@@[REALMNAME]: @b{<--- Enter your password} -@end example - -Now use the @samp{sclient} program as follows: - -@example -% @b{[K_USER]/sclient jimi} -@end example - -The command should display something like the following: - -@example -sendauth succeeded, reply is: -reply len 29, contents: -You are [USERNAME]@@[REALMNAME] -@end example - -@node Installing Kerberos Applications, Common Kerberos Service Names, A Sample Application, Installation -@section Installing Kerberos Applications - - In addition to the sample application, Kerberos comes with -several servers that can be installed on workstations to provide secure -network services such as FTP, Telnet, and Rlogin. This section -describes these services and how to install them. First, a general -procedure is outlined for configuring a workstation to run Kerberos -application servers. Then, details of the particular configuration -options required by each server are presented. - - -@menu -* Levels of Security:: -* Preparing a Workstation for Kerberos Application Servers:: -* BSD Utilities:: -* Telnet and FTP:: -@end menu - -@node Levels of Security, Preparing a Workstation for Kerberos Application Servers, Installing Kerberos Applications, Installing Kerberos Applications -@subsection Levels of Security - - Before installing Kerberized servers, it is a good idea to -decide on a security policy for your environment. While developing a -comprehensive security policy is beyond the scope of these instructions, -there are several interactions between Kerberos servers and non-Kerberos -servers, as well as different modes in which Kerberos servers can run -that should be considered. In general, there are three levels of -connections: - -@enumerate - -@item -Encrypted Kerberos connections are the most secure services provided by -the Kerberos environment. Only encrypted services provide -confidentiality---encryption is required to make sure a passive -eavesdropper does not collect sensitive data, such as passwords, sent -over connections. Besides providing confidentiality, encryption -provides protection against active attacks. Without encryption or some -other form of integrity, an attacker may be able to insert commands or -change data in an authenticated session. - - -@item -The next level of security is Kerberos-authenticated services without -encryption. Without encryption, there is no confidentiality, and some -active attacks are possible. However, unencrypted services are faster -and are available commercially outside the United States. In addition, -the window of exposure to attack is generally limited to the lifetime of -a session---it is difficult for an attacker who does not have tickets to -start a new session if a Kerberos authentication exchange must take -place at the beginning of every session. - -@item -Passworded services provide the next lower level of security. -Unfortunately, it is all-to-easy for a passive attacker to use software -such as a packet sniffer to find passwords traveling over a network. -Additionally, once an attacker knows a password, they can start -additional sessions at future times until the password is changed from a -secure location. Despite the disadvantages of password-based network -services, there are some common reasons for enabling them. First, most -clients only support password-based services; not everyone has Kerberos -or other cryptographically-secure network services. Second, in some -environments, where the network is secure, passwords may be a reasonable -solution. Also, particularly on public-access systems, it is common to -enable password-based services for normal users, while using more-secure -services such as Kerberos for root logins by administrators. - -@item -The least secure common category of services are trust or host-based -services. These services use an IP address or client-supplied assertion -to provide authentication. Examples of host-based services include -@samp{rlogin}, @samp{rsh}, and the @samp{on} or @samp{rexd} service. It -is generally sufficient to know that a user exists on a target system, -and to know that a host-based or trust-based service is enabled in order -to exploit the service. Whenever possible, these services should be -disabled; there are few situations in which an a security policy is both -compatible with Kerberos and host-based services. -@end enumerate - - Next, decide whether Kerberos V4 compatibility is necessary. -Unencrypted Kerberos V4 services suffer from all the problems of -unencrypted Kerberos V5 services: lack of confidentiality and -susceptibility to active attack. In addition, the lack of a replay cache -in Kerberos V4 makes these active attacks much easier. Also, design bugs -in the Kerberos V4 BSD utilities such as @samp{rlogin}, @samp{rsh} and -@samp{rcp} cause the availability of an unencrypted service to -significantly decrease the security of a system, even if only the -encrypted service is ever used. For example, a system that runs both -encrypted and unencrypted Kerberos V4 @samp{rlogin} servers is less secure -than a system only running the encrypted service, even if users only -ever connect to the encrypted service. - - Therefore, if Kerberos V4 interoperability is desired or required, -try to avoid running unencrypted Kerberos V4 services wherever possible. -In particular, only enable encrypted @samp{rlogin} if at all possible. -Naturally, some environments will require additional Kerberos V4 -functionality, like @samp{rsh}. The Kerberos V5 versions of these services, -with Kerberos V4 interoperability enabled, are not any weaker than their -Kerberos V4 counterparts. So, if the existing Kerberos V4 security policy -allows these services, then enabling them under the Kerberos V5 security -policy should not be a problem. - - In addition, the issue of compatibility with older Kerberos V5 -clients must be considered. For the most part, this compatibility is -automatic, and has few security implications. The major exception to -this is the BSD utilities. Until Kerberos V5 Beta6, these utilities -inherited a few design defects from the Kerberos V4 BSD utilities. In -particular, the presence of an unencrypted service that was never used -adversely effected the security of an encrypted service. The solution -that was adopted preserves compatibility with Kerberos V5 Beta5 clients. -Unfortunately, older clients are incompatible with this scheme. If -interoperability with older clients is necessary, then the new scheme -for checksums can be disabled on the server. If these checksums are -disabled, there is a short window between when a connection is opened -and when the replay cache is updated where an active attack is possible. -Alternatively, sites wishing to enable all security features may wish to -disable compatibility with Kerberos V5 Beta5 BSD utilities. -@xref{Checksums}, for full details. - - In conclusion, as you prepare to install Kerberos application -servers, you should have answers to the following questions: - -@enumerate - -@item -What levels of services are appropriate for your security policy: -encrypted services, authenticated but not encrypted services, -password-based services, or host-based services? - -@item -Do you wish to enable Kerberos V4 compatibility? If so, do you need to -enable unencrypted services? - -@item -Do you need compatibility with Kerberos V5 clients before Beta5 -(released in May, 1995)? Do you wish to disable compatibility with -Beta5 clients for slightly enhanced security? -@end enumerate - - - -@node Preparing a Workstation for Kerberos Application Servers, BSD Utilities, Levels of Security, Installing Kerberos Applications -@subsection Preparing a Workstation for Kerberos Application Servers - - - The following procedure is very similar to the installation -procedure for the sample Kerberos server. @xref{Installing -the Sample Application}. However, instead of using the sample service, -this configuration is designed to set up host-based services. - -The following description assumes that you are installing @samp{sserver} -on the machine @samp{jimi.mit.edu}. Repeat these steps for each -workstation that will be running host-based servers. Note that it is -not necessary to run these procedures on client machines--machines used -only to connect to secure network services, but that do not run any -servers of their own. Here's the process, step by step: - -@enumerate - -@item - Login as root or @samp{su} to root on the Kerberos server machine. -Use the @samp{kdb5_edit} program to create a service entry for -@code{host} in the Kerberos database: - -@example -# @b{[ADMIN_DIR]/kdb5_edit} -kdb5_edit: @b{add_random_key host/jimi.mit.edu} -kdb5_edit: @b{quit} -@end example - -(Note: @samp{add_random_key} may be abbreviated as @samp{ark}.) - -@item - Use @samp{kdb5_edit} to create a @file{srvtab} file -for @samp{sserver}'s host machine: - -@example -# @b{[ADMIN_DIR]/kdb5_edit} -kdb5_edit: @b{extract_srvtab jimi.mit.edu host} -'host/jimi.mit.edu@@ATHENA.MIT.EDU' added to keytab 'WRFILE:jimi.mit.edu-new-srvtab' -kdb5_edit: @b{quit} -@end example - -(Note: @samp{extract_srvtab} may be abbreviated as @samp{xst}. Also, -additional services can be listed after @samp{host} on the -@samp{extract_srvtab} line; for example if the host jimi also runs the -sample server, the @samp{sample} service might have been listed after -host.) - -Transfer the @file{jimi.mit.edu-new-srvtab} file to @samp{jimi.mit.edu} -and install it as @file{/etc/v5srvtab}. - -@b{WARNING}: Note that this file is equivalent to the service's password and -should be treated with care. For example, it could be transferred by -removable media, but should not be sent over an open network in the -clear. This file should be installed such that only the root user can read -it. - -@item -Make sure that the @samp{/etc/services} file has been updated to include -Kerberos services. In particular, look for @samp{klogin}, -@samp{eklogin}, and @samp{kshell}. - -@item -For each server you plan to run, add a line to @file{/etc/inetd.conf}. -The following sections will give details on what this line should look -like for each Kerberos application service. - -@item -Consider removing non-Kerberized services like @samp{rlogin}, -@samp{rsh}, @samp{rexd}, and others, in accordance with the security policy you decided on in the last section. - -@item - Restart @samp{inetd}. On most systems, this is done by sending the current @samp{inetd} process -a hangup signal: - -@example -# @b{kill -HUP} @i{process_id_number} -@end example - -@item -Try using the Kerberos applications to connect to the host. - -@end enumerate - -@node BSD Utilities, Telnet and FTP, Preparing a Workstation for Kerberos Application Servers, Installing Kerberos Applications -@subsection BSD Utilities - - This section describes installing servers for the BSD utilities: -@samp{kshd} and @samp{klogind}. The @samp{klogind} server implements the -protocol used by the Kerberized @samp{rlogin} client. The @samp{kshd} -server implements the protocol used by the @samp{rsh} and @samp{rcp} -clients. - - These daemons take a common set of options to enable support for -different versions of Kerberos. The @samp{-5} option enables Kerberos -V5 support, and the @samp{-4} option enables Kerberos V4 support. At -least one of these options must be supplied or the server will refuse -all connections. Both options can be supplied if compatibility with -both versions of Kerberos is desired. - - Both the @samp{klogind} and @samp{kshd} take an @samp{-e} option -to control encryption; because of the design of the servers, it works -slightly differently. The Kerberos login service listens on two -different ports, one for encrypted connections, and one for unencrypted -connections. Because @samp{klogind} is started by @samp{inetd}, it -needs to know whether it is servicing an encrypted or unencrypted -connection. Thus, the @samp{-e} option tells @samp{klogind} that it is -listening to the encrypted port. Typically, systems that allow both -encrypted and unencrypted logins have two lines in @file{inetd.conf}, -one for the @samp{klogin} service and one for the @samp{eklogin} -service. The line for the @samp{eklogin} service uses the @samp{-e} -option, while the line for the @samp{klogin} service does not. Systems -only supporting encrypted logins simply have the @samp{eklogin} line. - - On the other hand, @samp{kshd} listens to encrypted and -unencrypted requests on the same port; information from the client -identifies the connection's encryption status. So, @samp{kshd} -interprets the @samp{-e} option to mean that encryption is required. If -this option is specified, unencrypted connections are dropped. Thus, -specifying @samp{-e} to @samp{kshd} is like only having a line for -@samp{eklogin}. - -@menu -* Checksums:: Checksum facility for dealing with active attacks. -* BSD Utility Configuration Example:: Sample @file{inetd.conf} entries for BSD utilities. -@end menu - -@node Checksums, BSD Utility Configuration Example, BSD Utilities, BSD Utilities -@subsubsection Checksums - - Under previous versions of Kerberos, it was possible for an active -attacker to change certain information in the initial authentication -exchange without this change being detected. Starting with Kerberos V5, -Beta6, this information is protected by a checksum passed in the -Kerberos authenticator. Ideally, the server could detect the presence -of this checksum and use it if it were present. This way, -administrators could be sure to use new clients that produced the -checksum, while users who were not as concerned about security could use -a wider range of clients. - - This is how the checksum feature works by default. -Unfortunately, clients previous to Kerberos V5, Beta5 used the checksum -field to incorporate semi-random data into the Kerberos authentication -exchange. It is impossible to distinguish these bogus checksums from -checksums that have been produced by modern clients, but modified by an -active attacker. Thus, the checksum feature is incompatible with -previous releases of Kerberos V5. Three modes of operation are provided -to meet the configuration needs of different sites: - -@enumerate - -@item -The @samp{-c} option to both @samp{kshd} and @samp{klogind} requires -that checksums be present and valid. This only works with clients more -recent than Kerberos V5, Beta6. An error will be given when an older -client tries to connect. This option is incompatible with Kerberos V4; -Kerberos V4 clients do not include a checksum. If this option is used -in conjunction with the @samp{-4} option for Kerberos V4 compatibility, -a warning about the configuration error will be logged on each -connection. - -@item -If no checksum-related option is specified, then checksums will be -validated if they are present, but not required. This is compatible with -Kerberos V4 and Kerberos V5 clients as early as Kerberos V5, Beta5. - -@item -If the @samp{-i} option is provided, then checksums are ignored, even if -present. This option is required to maintain compatibility with clients -older than Kerberos V5 Beta5. Site should upgrade to newer clients so -this option is not required. - -@end enumerate - -@node BSD Utility Configuration Example, , Checksums, BSD Utilities -@subsubsection BSD Utility Configuration Example - - This section includes sample entries for @file{/etc/inetd.conf}. -Sample configuration are presented for three systems. Note that while -the examples stretch over multiple lines, an entry for a single service -should be placed on only one line in @file{inetd.conf}. Also, not all -systems have all of the columns shown in the example. @xref{Installing -the Sample Application}, for details on adding services to -@file{inetd.conf}. - - The first system enables all security features. Only Kerberos -V5 encrypted connections are enabled, and checksums are required. -@example -eklogin stream tcp nowait root - [K_SERVER]/klogind klogind -5 -e -c -kshell stream tcp nowait root - [K_SERVER]/kshd kshd -5 -e -c -@end example - - - The second system enables encrypted services for both Kerberos -V5 and Kerberos V4. Checksums are not required, but since no V5 clients -earlier than Beta5 are used, they are not ignored. - -@example -eklogin stream tcp nowait root - [K_SERVER]/klogind klogind -5 -4 -e -kshell stream tcp nowait root - [K_SERVER]/kshd kshd -5 -4 -e -@end example - - - The final example has both encrypted and unencrypted services -enabled for both Kerberos V5 and Kerberos V4. Checksums are disabled to -preserve compatability with older V5 clients. - -@example -eklogin stream tcp nowait root - [K_SERVER]/klogind klogind -5 -4 -i -e -klogin stream tcp nowait root - [K_SERVER]/klogind klogind -5 -4 -i -kshell stream tcp nowait root - [K_SERVER]/kshd kshd -5 -4 -i -@end example - -@node Telnet and FTP, , BSD Utilities, Installing Kerberos Applications -@subsection Telnet and FTP - - The following are example entries for @file{inetd.conf} for the -@samp{telnetd} and @samp{ftpd} servers. @xref{Installing the Sample -Application}, for details on adding services to @file{inetd.conf}. Note -that unlike other @file{inetd.conf} examples in this document, these -line should replace existing lines for password-based services of the -same name. - - The first example only allows encrypted or authenticated connections. - -@example -telnet stream tcp nowait root - [K_SERVER]/telnetd telnetd -a user -ftp stream tcp nowait root - [K_server]/ftpd ftpd -a -@end example - - The second example also allows password-based connections to be -made. - -@example -telnet stream tcp nowait root - [K_SERVER]/telnetd telnetd -ftp stream tcp nowait root - [K_server]/ftpd ftpd -@end example - -@node Common Kerberos Service Names, , Installing Kerberos Applications, Installation -@section Common Kerberos Service Names - -The following service names are used by Kerberos client/server -applications. - -@table @code - -@item host -Used by @samp{telnet}, @samp{rlogin}, @samp{rsh}, @samp{rcp}, @samp{ftp} -and other services which generally give login access to the host. - -@item pop -Used by the Post Office Protocol. - -@item sample -Used by the Kerberos sample applications. - -@end table - -These service names are used as the first component of the server's -principal name, with the second component being the server's fully -qualified domain name, in lower case. - -@node Troubleshooting, , Installation, Top -@chapter Troubleshooting - -@b{To be written.} - -@contents -@bye