From cee52a9a943c62d20fd96ed28593bc23bde809bc Mon Sep 17 00:00:00 2001 From: Jeff Bigler <jcb@mit.edu> Date: Fri, 30 Aug 1996 18:45:39 +0000 Subject: [PATCH] New documentation from Cygnus git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@9014 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/admin.texinfo | 2819 +++++++++++++++++++++++++++++++++++++ doc/build.texinfo | 323 +++++ doc/copyright.texinfo | 91 ++ doc/cyg-install.texinfo | 1644 +++++++++++++++++++++ doc/definitions.texinfo | 28 + doc/document-list.texinfo | 21 + doc/glossary.texinfo | 63 + doc/krb425.texinfo | 479 +++++++ doc/man2ps | 42 + doc/send-pr.texinfo | 200 +++ doc/user-guide.texinfo | 1671 ++++++++++++++++++++++ 11 files changed, 7381 insertions(+) create mode 100644 doc/admin.texinfo create mode 100644 doc/build.texinfo create mode 100644 doc/copyright.texinfo create mode 100644 doc/cyg-install.texinfo create mode 100644 doc/definitions.texinfo create mode 100644 doc/document-list.texinfo create mode 100644 doc/glossary.texinfo create mode 100644 doc/krb425.texinfo create mode 100644 doc/man2ps create mode 100644 doc/send-pr.texinfo create mode 100644 doc/user-guide.texinfo diff --git a/doc/admin.texinfo b/doc/admin.texinfo new file mode 100644 index 000000000..c90a0ef13 --- /dev/null +++ b/doc/admin.texinfo @@ -0,0 +1,2819 @@ +\input texinfo @c -*-texinfo-*- +@c Note: the above texinfo file must include the "doubleleftarrow" +@c definitions added by jcb. +@c %**start of header +@c guide +@setfilename kerbnet-admin.info +@settitle Kerb*Net System Administrator's Guide +@c @setchapternewpage odd @c chapter begins on next odd page +@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 0.9 beta + +@finalout @c don't print black warning boxes + +@titlepage +@title @value{PRODUCT} System Administrator's Guide +@subtitle Release: @value{RELEASE} +@subtitle Document Edition: @value{EDITION} +@subtitle Last updated: @value{UPDATED} +@author @value{COMPANY} + +@page +@vskip 0pt plus 1filll + +@include copyright.texinfo +@end titlepage + +@comment node-name, next, previous, up +@node Top, Introduction, (dir), (dir) + +@ifinfo +This document describes how to administrate a @value{PRODUCT} +installation. + +@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 + +@menu +* Introduction:: +* How Kerberos Works:: +* Administrating Kerberos Database Entries:: +* Application Servers:: +* Updates:: +* Backups of Secure Hosts:: +* Support:: +* Appendix:: +@end menu + +@c --------------------------------------------------------------------- + +@node Introduction, How Kerberos Works, Top, Top +@chapter Introduction + +Congratulations on your purchase of @value{PRODUCT}. @value{COMPANY} +believes @value{PRODUCT} provides the best network security available. +Please let us know if we can be of assistance in getting your +installation of @value{PRODUCT} set up and running. + +@menu +* Why Should I use Kerberos?:: +* @value{PRODUCT} Documentation:: +* Overview of This Guide:: +@end menu + +@node Why Should I use Kerberos?, @value{PRODUCT} Documentation, Introduction, 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. + +@node @value{PRODUCT} Documentation, Overview of This Guide, Why Should I use Kerberos?, Introduction +@section @value{PRODUCT} Documentation + +This document is one piece of the document set for @value{PRODUCT}. The +documents, and their intended audiences, are: + +@include document-list.texinfo + +@node Overview of This Guide, , @value{PRODUCT} Documentation, Introduction +@section Overview of This Guide + +The next chapter describes how Kerberos works. + +Chapter three describes administration of the principals in the Kerberos +database. + +Chapter four describes administrative programs for manipulating the +Kerberos database as a whole. + +Chapter five describes issues to consider when adding an application +server to the database. + +Chapter six describes our problem reporting system. + +The appendices include sample configuration files, the list of Kerberos +error messages, and a complete list of the time zones understood by +@code{kadmin}. + +@node How Kerberos Works, Administrating Kerberos Database Entries, Introduction, Top +@chapter How Kerberos Works + +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. This paper can be retreived by FTP from +@code{athena-dist.mit.edu}, in the location: +@code{/pub/ATHENA/kerberos/doc/USENIX.ps}. + +@menu +* Network Services and Their Client Programs:: +* Kerberos Tickets:: +* The Kerberos Database:: +* Kerberos Realms:: +* The Ticket-Granting Ticket:: +* Network Services and the Master Database:: +* The User--Kerberos Interaction:: +* Definitions:: +@end menu + +@node Network Services and Their Client Programs, 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 @dfn{services} 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 a typical UNIX host. 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 and Their Client Programs, How Kerberos Works +@section Kerberos Tickets + +Under Kerberos, the @samp{klogind} daemon allows you to login to a +remote machine if you can provide @samp{klogind} 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} (an identifying string, 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 administrative domain will have its own Kerberos database, which +contains information about the users and services for that particular +site or administrative domain. This administrative domain is the +@dfn{Kerberos realm}. + +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 that are +periodically propagated from the master server. For more details on how +this is done, see the ``Set Up the Slave KDCs for Database Propagation'' +and ``Propagate the Database to Each Slave KDC'' sections of the +@value{PRODUCT} Installation Guide. + +@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. 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 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 +just a file in @code{/tmp}. The credentials cache is also called the +@dfn{ticket file}, especially in Kerberos V4 documentation. Note, +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.@value{PRIMARYDOMAIN}}, that requires Kerberos +authentication from anyone who wants to @samp{rlogin} to it. The host's +Kerberos realm is @samp{@value{PRIMARYREALM}}. + +This service must be registered in the Kerberos database, using the +proper service name, which in this case is the @dfn{principal}: + +@smallexample +host/laughter.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} +@end smallexample + +@noindent +The @samp{/} character separates the Kerberos @dfn{primary} (in this +case, @samp{host}) from the @dfn{instance} (in this case, +@samp{laughter.@value{PRIMARYDOMAIN}}); the @samp{@@} character separates +the realm name (in this case, @samp{@value{PRIMARYREALM}}) from the rest +of the principal. The primary, @samp{host}, denotes the name or type of +the service that is being offered: generic host-level access to the +machine. The instance, @samp{laughter.@value{PRIMARYDOMAIN}}, names the +specific machine that is offering this service. There will generally be +many different machines, each offering one particular type of service, +and the instance serves to give each one of these servers a different +Kerberos principal. + +@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 @dfn{key tables}, +which are files known as @dfn{keytabs}.@footnote{Keytabs were called +@dfn{srvtabs} in Kerberos V4.} For example, the service keys used by +services that run as root are usually stored in the keytab file +@code{/etc/v5srvtab}. @b{N.B.:} 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, Definitions, Network Services and the Master Database, How Kerberos Works +@section The User--Kerberos Interaction + +Suppose that you walk up to a host 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 systems running the @value{PRODUCT} @samp{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_<uid>}, where <uid> is your UNIX user-id, represented +in decimal format. +@end enumerate + +@need 1500 +@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 request for a ticket for +@samp{host/laughter.@value{PRIMARYDOMAIN}}, and looks in the master +database for an entry for @samp{host/laughter.@value{PRIMARYDOMAIN}}. +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{klogind} 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 you are allowed to login to @samp{laughter} (because your +username matches one in /etc/passwd, or your Kerberos principal is in +the appropriate @file{.k5login} file), @code{klogind} will let you +login. +@end enumerate +@end enumerate + +@node Definitions, , The User--Kerberos Interaction, How Kerberos Works +@section Definitions + +Following are definitions of some of the Kerberos terminology. + +@include glossary.texinfo + +@node Administrating Kerberos Database Entries, Application Servers, How Kerberos Works, Top +@chapter Administrating the Kerberos Database + +Your Kerberos database contains all of your realm's Kerberos principals, +their passwords, and other administrative information about each +principal. For the most part, you will use the @code{kdb5_util} program +to manipulate the Kerberos database as a whole, and the @code{kadmin} +program to make changes to the entries in the database. (One notable +exception is that users will use the @code{kpasswd} program to change +their own passwords.) The @code{kadmin} program has its own +command-line interface, to which you type the database administrating +commands. + +@code{Kdb5_util} provides a means to create, delete, load, or dump a +Kerberos database. It also includes a command to stash a copy of the +master database key in a file on a KDC, so that the KDC can authenticate +itself to the @code{kadmind} and @code{krb5kdc} daemons at boot time. + +@code{Kadmin} provides for the maintenance of Kerberos principals, KADM5 +policies, and service key tables (keytabs). It exists as both a +Kerberos client, @code{kadmin}, using Kerberos authentication and an +RPC, to operate securely from anywhere on the network, and as a local +client, @code{kadmin.local}, intended to run directly on the KDC without +Kerberos authentication. Other than the fact that the remote client +uses Kerberos to authenticate the person using it, the functionalities +of the two versions are identical. The local version is necessary to +enable you to set up enough of the database to be able to use the remote +version. It replaces the now obsolete @code{kdb5_edit} (except for +database dump and load, which are provided by @code{kdb5_util}). + +The remote version authenticates to the KADM5 server using the service +principal @code{kadmin/admin}. If the credentials cache contains a +ticket for the @code{kadmin/admin} principal, and the @samp{-c +credentials_cache} option is specified, that ticket is used to +authenticate to KADM5. Otherwise, the @samp{-p} and @samp{-k} options +are used to specify the client Kerberos principal name used to +authenticate. Once kadmin has determined the principal name, it +requests a @code{kadmin/admin} Kerberos service ticket from the KDC, and +uses that service ticket to authenticate to KADM5. + +@menu +* Kadmin Options:: +* Date Format:: +* Principals:: +* Policies:: +* Dumping a Kerberos Database to a File:: +* Restoring a Kerberos Database from a Dump File:: +* Creating a Stash File:: +* Creating and Destroying a Kerberos Database:: +* The KDC Logs:: +@end menu + +@node Kadmin Options, Date Format, Administrating Kerberos Database Entries, Administrating Kerberos Database Entries +@section Kadmin Options + +You can invoke @code{kadmin} with any of the following options: + +@table @b +@item @b{-r} @i{REALM} +Use @i{REALM} as the default Kerberos realm for the database. + +@item @b{-p} @i{principal} +Use the Kerberos principal @i{principal} to authenticate to Kerberos. +If this option is not given, @code{kadmin} will append @code{admin} to +either the primary principal name, the environment variable USER, or to +the username obtained grom @code{getpwuid}, in order of preference. + +@item @b{-k} @i{keytab} +Use the keytab @i{keytab} to decrypt the KDC response instead of +prompting for a password on the TTY. In this case, the principal will +be @samp{host/@i{hostname}}. + +@item @b{-c} @i{credentials cache} +Use @i{credentials_cache} as the credentials cache. The credentials +cache should contain a service ticket for the @code{kadmin/admin} +service, which can be acquired with the @code{kinit} program. If this +option is not specified, @code{kadmin} requests a new service ticket +from the KDC, and stores it in its own temporary ccache. + +@item @b{-w} @i{password} +Use @i{password} as the password instead of prompting for one on the +TTY. Note: placing the password for a Kerberos principal with +administration access into a shell script can be dangerous if +unauthorized users gain read access to the script. + +@item @b{-q} @i{query} +Pass @i{query} directly to @code{kadmin}. This is useful for writing +scripts that pass specific queries to @code{kadmin}. +@end table + +@node Date Format, Principals, Kadmin Options, Administrating Kerberos Database Entries +@section Date Format + +Many of the @code{kadmin} commands take a duration or time as an +argument. The date can appear in a wide variety of formats, such as: + +@smallexample +@group +1 month ago +2 hours ago +400000 seconds ago +last year +this Monday +next Monday +yesterday +tomorrow +now +second Monday +a fortnight ago +3/31/92 10:00:07 PST +January 23, 1987 10:05pm +22:00 GMT +@end group +@end smallexample + +All of these are case-insensitive. The following is a list of all of +the allowable keywords. + +@table @b +@item Months +january, jan, february, feb, march, mar, april, apr, may, june, jun, +july, jul, august, aug, september, sept, sep, october, oct, november, +nov, december, dec + +@item Days +sunday, sun, monday, mon, tuesday, tues, tue, wednesday, wednes, wed, +thursday, thurs, thur, thu, friday, fri, saturday, sat + +@item Units +year, month, fortnight, week, day, hour, minute, min, second, sec + +@item Relative +tomorrow, yesterday, today, now, last, this, next, first, third, fourth, +fifth, sixth, seventh, eighth, ninth, tenth, eleventh, twelfth, ago + +@item Time Zones +@code{kadmin} recognizes abbreviations for most of the world's time +zones. A complete listing appears in @ref{kadmin Time Zones}. + +@item 12-hour Time Delimiters +am, pm +@end table + +@menu +* Principals:: +* Policies:: +* The KDC Logs:: +@end menu + +@node Principals, Policies, Date Format, Administrating Kerberos Database Entries +@section Principals + +Each entry in the Kerberos database contains a Kerberos principal +(@pxref{Definitions}) and the attributes and policies associated with +that principal. + +@menu +* Retrieving Information About a Principal:: +* Privileges:: +* Adding or Modifying Principals:: +* Deleting Principals:: +* Changing Passwords:: +* Renaming Principals:: +@end menu + +@node Retrieving Information About a Principal, Privileges, Principals, Principals +@subsection Retrieving Information About a Principal + +@menu +* Attributes:: +* Retrieving a List of Principals:: +@end menu + +@node Attributes, Retrieving a List of Principals, Retrieving Information About a Principal, Retrieving Information About a Principal +@subsubsection Attributes + +To retrieve a listing of the attributes and/or policies associated with +a principal, use the @code{kadmin} @code{get_principal} command, which +requires the ``inquire'' administrative privilege. The syntax is: + +@smallexample +@b{get_principal} @i{principal} +@end smallexample + +@noindent The @code{get_principal} command has the alias @code{getprinc}. + +For example, suppose you wanted to view the attributes of the principals +@code{@value{RANDOMUSER1}/root@@@value{PRIMARYREALM}} and +@code{systest@@@value{PRIMARYREALM}}. You would type: + +@smallexample +@group +@b{shell%} kadmin +@b{kadmin:} getprinc @value{RANDOMUSER1}/root +@b{Principal: @value{RANDOMUSER1}/admin@@@value{PRIMARYREALM} +Key version: 3 +Maximum life: 1 day 00:00:00 +Maximum renewable life: 7 days 00:00:00 +Master key version: 1 +Expires: Mon Jan 18 22:14:07 EDT 2038 +Password expires: Mon Sep 19 14:40:00 EDT 1996 +Password last changed: Mon Jan 31 02:06:40 EDT 1996 +Last modified: by @value{ADMINUSER}/admin@@@value{PRIMARYREALM} + on Wed Jul 13 18:27:08 EDT 1996 +Attributes: DISALLOW_FORWARDABLE, DISALLOW_PROXIABLE, + REQUIRES_HW_AUTH +Salt type: DEFAULT +kadmin:} +@end group +@end smallexample + +The @code{get_principal} command has a @code{-terse} option, which lists +the fields as a quoted, tab-separated string. For example: + +@smallexample +@group +@b{kadmin:} getprinc -terse systest +@b{systest@@@value{PRIMARYREALM} 3 86400 604800 1 +785926535 753241234 785900000 +@value{RANDOMUSER1}/admin@@@value{PRIMARYREALM} 786100034 0 +0 +kadmin:} +@end group +@end smallexample + +@node Retrieving a List of Principals, , Attributes, Retrieving Information About a Principal +@subsubsection Retrieving a List of Principals + +To generate a listing of principals, use the @code{kadmin} +@code{list_principals} command, which requires the ``list'' privilege. +The syntax is: + +@smallexample +@b{list_principals} [@i{expression}] +@end smallexample + +@noindent where @i{expression} is a shell-style glob expression that can +contain the characters @samp{*}, @samp{?}, @samp{[}, and @samp{]}. All +policy names matching the expression are displayed. The +@code{list_principals} command has the alias @code{listprincs}. For +example: + +@smallexample +@group +@b{kadmin:} listprincs test* +@b{test3@@@value{PRIMARYDOMAIN} +test2@@@value{PRIMARYDOMAIN} +test1@@@value{PRIMARYDOMAIN} +testuser@@@value{PRIMARYDOMAIN} +kadmin:} +@end group +@end smallexample + +@noindent If no expression is provided, all principals are printed. + +@node Privileges, Adding or Modifying Principals, Retrieving Information About a Principal, Principals +@subsection Privileges + +Administrative privileges for the Kerberos database are stored in the +file @code{kadm5.acl}. Each line of the file contains a principal, the +privileges that principal has, and optionally the target to which those +permissions apply. The privileges are represented by single letters; +UPPER-CASE letters represent negative permissions. The permissions are: + +@table @b +@itemx a +allows the addition of principals or policies in the database. +@itemx A +disallows the addition of principals or policies in the database. +@itemx d +allows the deletion of principals or policies in the database. +@itemx D +disallows the deletion of principals or policies in the database. +@itemx m +allows the modification of principals or policies in the database. +@itemx M +disallows the modification of principals or policies in the database. +@itemx c +allows the changing of passwords for principals in the database. +@itemx C +disallows the changing of passwords for principals in the database. +@itemx i +allows inquiries to the database. +@itemx I +disallows inquiries to the database. +@itemx l +allows the listing of principals or policies in the database. +@itemx L +disallows the listing of principals or policies in the database. +@itemx * +All privileges (admcil). +@itemx x +All privileges (admcil); identical to ``*''. +@end table + +Principals in this file can include the @b{*} wildcard. Here is an +example of a @code{kadm5.acl} file. Note that order is important; +permissions are determined by the first matching entry. + +@smallexample +@group +*/admin@@@value{PRIMARYREALM} * +@value{ADMINUSER}/null@@@value{PRIMARYREALM} ADMCIL +@value{ADMINUSER}/*@@@value{PRIMARYREALM} il +@value{RANDOMUSER1}/root@@@value{PRIMARYREALM} cil */root@@@value{PRIMARYREALM} +*/*@@@value{PRIMARYREALM} i +@end group +@end smallexample + +@noindent In the above file, any principal with an @code{admin} instance +has all administrative privileges. The user @code{@value{ADMINUSER}} +has all permissions with his @code{admin} instance, +@code{@value{ADMINUSER}/admin@@@value{PRIMARYREALM}} (matches the first +line). He has no permissions at all with his @code{null} instance, +@code{@value{ADMINUSER}/null@@@value{PRIMARYREALM}} (matches the second +line). He has @i{inquire} and @i{list} permissions with any other +instance (matches the third line). When @code{@value{RANDOMUSER1}} is +using her @code{root} +instance, @code{@value{RANDOMUSER1}/root@@@value{PRIMARYREALM}}, she has +@i{change password}, @i{inquire}, and @i{list} privileges for any other +principal that has the instance @code{root}. Finally, any principal in +the realm @code{@value{PRIMARYREALM}} (except for +@code{@value{ADMINUSER}/null@@@value{PRIMARYREALM}}, as mentioned above) +has @i{inquire} privileges. + +@node Adding or Modifying Principals, Deleting Principals, Privileges, Principals +@subsection Adding or Modifying Principals + +To add a principal to the database, use the kadmin @code{add_principal} +command, which requires the ``add'' administrative privilege. The +syntax is: + +@smallexample +@b{kadmin:} add_principal [@i{options}] @i{principal} +@end smallexample + +To modify attributes of a principal, use the kadmin +@code{modify_principal} command, which requires the ``modify'' +administrative privilege. The syntax is: + +@smallexample +@b{kadmin:} modify_principal [@i{options}] @i{principal} +@end smallexample + +@noindent +@code{add_principal} has the aliases @code{addprinc} and +@code{ank}@footnote{@code{ank} was the short form of the equivalent +command using the deprecated @code{kadmin5} database administrative +tool. It has been kept}. @code{modify_principal} has the alias @code{modprinc}. + +The @code{add_principal} and @code{modify_principal} commands take the +following switches: + +@table @b +@item -salt @i{salttype} +Uses the specified salt for generating the key. The valid salt types +are: + +@itemize @bullet +@item full_name (aliases ``v5_salt'' and ``normal''; this is the default) +@item name_only +@item realm_only +@item no_salt (alias ``v4_salt'') +@end itemize + +@item -clearpolicy +removes the current policy from a principal (@code{modify_principal} +only). + +@item -expire @i{date} +Sets the expiration date of the principal to @i{date}. + +@item -pwexpire @i{date} +Sets the expiration date of the password to @i{date}. + +@item -maxlife @i{maxlife} +Sets the maximum ticket life of the principal to @i{maxlife}. + +@item -kvno @i{number} +Explicity sets the key version number to @i{number}. @value{COMPANY} +does not recommend doing this unless there is a specific reason. + +@item -policy @i{policy} +Sets the policy used by this principal. (@xref{Policies}.) If no +policy is supplied, the principal will have no policy, and @code{kadmin} +will print a warning message. + +@item @{-|+@}allow_postdated +The ``-allow_postdated'' option prohibits this principal from obtaining +postdated tickets. ``+allow_postdated'' clears this flag. In effect, +``-allow_postdated'' sets the KRB5_KDB_DISALLOW_POSTDATED flag on the +principal in the database. + +@item @{-|+@}allow_forwardable +The ``-allow_forwardable'' option prohibits this principal from +obtaining forwardable tickets. ``+allow_forwardable'' clears this flag. +In effect, ``-allow_forwardable'' sets the KRB5_KDB_DISALLOW_FORWARDABLE +flag on the principal in the database. + +@item @{-|+@}allow_renewable +The ``-allow_renewable'' option prohibits this principal from obtaining +renewable tickets. ``+allow_renewable'' clears this flag. In effect, +``-allow_renewable'' sets the KRB5_KDB_DISALLOW_RENEWABLE flag on the +principal in the database. + +@item @{-|+@}allow_proxiable +The ``-allow_proxiable'' option prohibits this principal from obtaining +proxiable tickets. ``+allow_proxiable'' clears this flag. In effect, +``-allow_proxiable'' sets the KRB5_KDB_DISALLOW_PROXIABLE flag. on the +principal in the database. + +@item @{-|+@}allow_dup_skey +The ``-allow_dup_skey'' option disables user-to-user authentication for +this principal by prohibiting this principal from obtaining a session +key for another user. ``+allow_dup_skey'' clears this flag. In effect, +``-allow_dup_skey'' sets the KRB5_KDB_DISALLOW_DUP_SKEY flag on the +principal in the database. + +@item @{-|+@}requires_preauth +The ``+requires_preauth'' option requires this principal to +preauthenticate before being allowed to kinit. -requires_preauth clears +this flag. In effect, +requires_preauth sets the +KRB5_KDB_REQUIRES_PRE_AUTH flag on the principal in the database. + +@item @{-|+@}requires_hwauth +The ``+requires_hwauth'' flag requires the principal to preauthenticate +using a hardware device before being allowed to kinit. +``-requires_hwauth'' clears this flag. In effect, ``+requires_hwauth'' +sets the KRB5_KDB_REQUIRES_HW_AUTH flag on the principal in the +database. + +@item @{-|+@}allow_svr +The ``-allow_svr'' flag prohibits the issuance of service tickets for +this principal. ``+allow_svr'' clears this flag. In effect, +``-allow_svr'' sets the KRB5_KDB_DISALLOW_SVR flag on the principal in +the database. + +@item @{-|+@}allow_tgs_req +The ``-allow_tgs_req'' option specifies that a Ticket-Granting Service +(TGS) request for a service ticket for this principal is not permitted. +You will probably never need to use this option. ``+allow_tgs_req'' +clears this flag. The default is ``+allow_tgs_req''. In effect, +``-allow_tgs_req'' sets the KRB5_KDB_DISALLOW_TGT_BASED flag on the +principal in the database. + +@item @{-|+@}allow_tix +The ``-allow_tix'' option forbids the issuance of any tickets for this +principal. ``+allow_tix'' clears this flag. The default is +``+allow_tix''. In effect, ``-allow_tix'' sets the +KRB5_KDB_DISALLOW_ALL_TIX flag on the principal in the database. + +@item @{-|+@}needchange +The ``+needchange'' option sets a flag in attributes field to force a +password change; ``-needchange'' clears it. The default is +``-needchange''. In effect, ``+needchange'' sets the +KRB5_KDB_REQUIRES_PWCHANGE flag on the principal in the database. + +@item @{-|+@}password_changing_service +The ``+password_changing_service'' option sets a flag in the attributes +field marking this principal as a password change service. (Again, you +will probably never need to use this option.) +``-password_changing_service'' clears the flag. The default is +``-password_changing_service''. In effect, the +``+password_changing_service'' option sets the KRB5_KDB_PWCHANGE_SERVICE +flag on the principal in the database. + +@item -clearpolicy @i{policyname} +Removes the policy @i{policyname} from the principal +(@code{modify_principal} only). + +@item -randkey +Sets the key for the principal to a random value (@code{add_principal} +only). @value{COMPANY} recommends using this option for host keys. + +@item -pw @i{password} +Sets the key of the principal to the specified string and does not +prompt for a password (@code{add_principal} only). @value{COMPANY} does +not recommend using this option. +@end table + +If you want to just use the default values, all you need to do is: + +@smallexample +@group +@b{kadmin:} addprinc @value{RANDOMUSER1} +@b{WARNING: no policy specified for "@value{RANDOMUSER1}@@@value{PRIMARYREALM}"; +defaulting to no policy.} +@iftex +@b{Enter password for principal @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Type the password.} +@b{Re-enter password for principal @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Type it again.} +@end iftex +@ifinfo +@b{Enter password for principal @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<= Type the password.} +@b{Re-enter password for principal @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<=Type it again.} +@end ifinfo +@b{Principal "@value{RANDOMUSER1}@@@value{PRIMARYREALM}" created. +kadmin:} +@end group +@end smallexample + +If, on the other hand, you want to set up an account that expires on +January 1, 2000, that uses a policy called ``stduser'', with a temporary +password (which you want the user to change immediately), you would type +the following. (Note: each line beginning with @result{} is a +continuation of the previous line.) + +@smallexample +@group + +@b{kadmin:} addprinc @value{RANDOMUSER2} -expire "1/1/2000 12:01am EST" -policy stduser +@result{} +needchange +@iftex +@b{Enter password for principal @value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Type the password.} +@b{Re-enter password for principal +@value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Type it again.} +@end iftex +@ifinfo +@b{Enter password for principal @value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{<= Type the password.} +@b{Re-enter password for principal +@value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{<= Type it again.} +@end ifinfo +@b{Principal "@value{RANDOMUSER2}@@@value{PRIMARYREALM}" created. +kadmin:} + +@end group +@end smallexample + +If you will need cross-realm authentication, you need to add principals +for the other realm's TGT to each realm. For example, if you need to do +cross-realm authentication between the realms @value{PRIMARYREALM} and +@value{SECONDREALM}, you would need to add the principals +@samp{krbtgt/@value{SECONDREALM}@@@value{PRIMARYREALM}} and +@samp{krbtgt/@value{PRIMARYREALM}@@@value{SECONDREALM}} to both +databases. You need to be sure the passwords and the key version +numbers (kvno) are the same in both databases. This may require +explicitly setting the kvno with the @samp{-kvno} option. + +@node Deleting Principals, Changing Passwords, Adding or Modifying Principals, Principals +@subsection Deleting Principals + +To delete a principal, use the kadmin @code{delete_principal} command, +which requires the ``delete'' administrative privilege. The syntax is: + +@smallexample +@b{delete_principal} [@b{-force}] @i{principal} +@end smallexample + +@noindent @code{delete_principal} has the alias @code{delprinc}. The +@code{-force} option causes @code{delete_principal} not to ask if you're +sure. For example: + +@smallexample +@group +@b{kadmin:} delprinc @value{RANDOMUSER1} +@b{Are you sure you want to delete the principal +"@value{RANDOMUSER1}@@@value{PRIMARYREALM}"? (yes/no):} yes +@b{Principal "@value{RANDOMUSER1}@@@value{PRIMARYREALM}" deleted. +Make sure that you have removed this principal from +all ACLs before reusing. +kadmin:} +@end group +@end smallexample + +@node Changing Passwords, Renaming Principals, Deleting Principals, Principals +@subsection Changing Passwords + +To change a principal's password use the kadmin @code{change_password} +command, which requires the ``modify'' administrative privilege (unless +the principal is changing his/her own password). The syntax is: + +@smallexample +@b{change_password} [@i{options}] @i{principal} +@end smallexample + +@noindent The @code{change_password} option has the alias @code{cpw}. +@code{change_password} takes the following options: + +@table @b +@item @b{-salt} @i{salttype} +Uses the specified salt for generating the key. Salt types are the same +as for the @code{add_principal} command (@pxref{Adding or Modifying +Principals}). + +@item -randkey +Sets the key of the principal to a random value. + +@item @b{-pw} @i{password} +Sets the password to the string @i{password}. @value{COMPANY} does not +recommend using this option. +@end table + +For example: + +@smallexample +@group +@b{kadmin:} cpw @value{RANDOMUSER2} +@iftex +@b{Enter password for principal @value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Type the new password.} +@b{Re-enter password for principal @value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{@doubleleftarrow{} Type it again.} +@end iftex +@ifinfo +@b{Enter password for principal @value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{<= Type the new password.} +@b{Re-enter password for principal @value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{<= Type it again.} +@end ifinfo +@b{Password for @value{RANDOMUSER2}@@@value{PRIMARYREALM} changed. +kadmin:} +@end group +@end smallexample + +Note that @code{change_password} will not let you change the password to +one that is in the principal's password history. + +@node Renaming Principals, , Changing Passwords, Principals +@subsection Renaming Principals + +To rename a principal, use the kadmin @code{rename_principal} command, +which requires both the ``add'' and ``delete'' administrative +privileges. The syntax is: + +@smallexample +@b{rename_principal} [@b{-force}] @i{old_principal} @i{new_principal} +@end smallexample + +@noindent The @code{rename_principal} command has the alias @code{renprinc}. + +For example: + +@smallexample +@group +@b{kadmin:} renprinc tlyutest test0 +@b{Are you sure you want to rename the principal +"test@@@value{PRIMARYREALM}" to +"test2@@@value{PRIMARYREALM}"? (yes/no):} yes +@b{Principal "test@@@value{PRIMARYREALM}" renamed to +"test2@@@value{PRIMARYREALM}". +Make sure that you have removed "test@@@value{PRIMARYREALM}" from +all ACLs before reusing. +kadmin:} +@end group +@end smallexample + +@node Policies, Dumping a Kerberos Database to a File, Principals, Administrating Kerberos Database Entries +@section Policies + +A policy is a set of rules governing passwords. Policies can dictate +minimum and maximum password lifetimes, minimum number of characters and +character classes a password must contain, and the number of old +passwords kept in the database. + +@menu +* Retrieving Policies:: +* Retrieving the List of Policies:: +* Adding or Modifying Policies:: +* Deleting Policies:: +@end menu + +@node Retrieving Policies, Retrieving the List of Policies, Policies, Policies +@subsection Retrieving Policies + +To retrieve a policy, use the kadmin @code{get_policy} command, which +requires the ``inquire'' administrative privilege. The syntax is: + +@smallexample +@b{get_policy} [@b{-terse}] @i{policy} +@end smallexample + +The @code{get_policy} command has the alias @code{getpol}. For example: + +@smallexample +@group +@b{kadmin:} get_policy admin +@b{Policy: admin +Maximum password life: 180 days 00:00:00 +Minimum password life: 00:00:00 +Minimum password length: 6 +Minimum number of password character classes: 2 +Number of old keys kept: 5 +Reference count: 17 +kadmin:} +@end group +@end smallexample + +@noindent The @dfn{reference count} is the number of principals using +that policy. + +The @code{get_policy} command has a @code{-terse} option, which lists +each field as a quoted, tab-separated string. For example: + +@smallexample +@group +@b{kadmin:} get_policy -terse admin +@b{admin 15552000 0 6 2 5 17 +kadmin:} +@end group +@end smallexample + +@node Retrieving the List of Policies, Adding or Modifying Policies, Retrieving Policies, Policies +@subsection Retrieving the List of Policies + +You can retrieve the list of policies with the kadmin +@code{list_policies} command, which requires the ``list'' privilege. The +syntax is: + +@smallexample +@b{list_policies} [@i{expression}] +@end smallexample + +@noindent where @i{expression} is a shell-style glob expression that can +contain the characters *, ?, and []. All policy names matching the +expression are displayed. The @code{list_policies} command has the alias +@code{listpols}. For example: + +@smallexample +@group +@b{kadmin:} listpols +@b{test-pol +dict-only +once-a-min +test-pol-nopw} + +@b{kadmin:} listpols t* +@b{test-pol +test-pol-nopw +kadmin:} +@end group +@end smallexample + +@node Adding or Modifying Policies, Deleting Policies, Retrieving the List of Policies, Policies +@subsection Adding or Modifying Policies + +To add a new policy, use the kadmin @code{add_policy} command, which +requires the ``add'' administrative privilege. The syntax is: + +@smallexample +@b{add_policy} [@i{options}] @i{policy_name} +@end smallexample + +To modify attributes of a principal, use the kadmin @code{modify_policy} +command, which requires the ``modify'' administrative privilege. The +syntax is: + +@smallexample +@b{modify_policy} [@i{options}] @i{policy_name} +@end smallexample + +@noindent @code{add_policy} has the alias @code{addpol}. +@code{modify_poilcy} has the alias @code{modpol}. + +The @code{add_policy} and @code{modify_policy} commands take the +following switches: + +@table @b +@item -maxlife @i{time} +Sets the maximum lifetime of a password to @i{time}. + +@item -minlife @i{time} +Sets the minimum lifetime of a password to @i{time}. + +@item -minlength @i{length} +Sets the minimum length of a password to @i{length} characters. + +@item -minclasses @i{number} +Requires at least @i{number} of character classes in a password. + +@item -history @i{number} +Sets the number of past keys kept for a principal to @i{number}. +@end table + +@c **** An example here would be nice. **** + +@node Deleting Policies, , Adding or Modifying Policies, Policies +@subsection Deleting Policies + +To delete a policy, use the @code{kadmin} @code{delete_policy} command, +which requires the ``delete'' administrative privilege. The syntax is: + +@smallexample +@b{delete_policy} @i{policy_name} +@end smallexample + +@noindent The @code{delete_policy} command has the alias @code{delpol}. +It prompts for confirmation before deletion. +For example: + +@smallexample +@group +@b{kadmin:} delete_policy guests +@b{Are you sure you want to delete the policy "guests"? +(yes/no):} yes +@b{Policy "guests" deleted. +kadmin:} +@end group +@end smallexample + +Note that you must cancel the policy from all principals before deleting +it. The @code{delete_policy} command will fail if it is in use by any +principals. + +@node Dumping a Kerberos Database to a File, Restoring a Kerberos Database from a Dump File, Policies, Administrating Kerberos Database Entries +@section Dumping a Kerberos Database to a File + +To dump a Kerberos database into a file, use the @code{kdb5_util} +@code{dump} command on one of the KDCs. The syntax is: + +@smallexample +@b{kdb5_util dump} [@b{-old}] [@b{-b6}] [@b{-ov}] [@b{-verbose}] [@i{filename} +[@i{principals...}]] +@end smallexample + +The @code{kdb5_util dump} command takes the following options: + +@table @b +@itemx -old +causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format +(``kdb5_edit load_dump version 2.0''). +@itemx -b6 +causes the dump to be in the Kerberos 5 Beta 6 format (``kdb5_edit +load_dump version 3.0''). +@itemx -ov +causes the dump to be in ovsec_adm_export format. +@itemx -verbose +causes the name of each principal and policy to be printed as it is +dumped. +@end table + +For example: + +@smallexample +@group +@b{shell%} kdb5_util dump dumpfile +@b{shell%} +@end group +@end smallexample + +@smallexample +@group +@b{shell%} kbd5_util dump -verbose dumpfile +@b{kadmin/admin@@@value{PRIMARYREALM} +krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM} +kadmin/history@@@value{PRIMARYREALM} +K/M@@@value{PRIMARYREALM} +kadmin/changepw@@@value{PRIMARYREALM} +shell%} +@end group +@end smallexample + +@noindent +If you specify which principals to dump, you must use the full +principal, as in the following example. (The line beginning with +@result{} is a continuation of the previous line.): + +@smallexample +@group +@b{shell%} kdb5_util dump -verbose dumpfile K/M@@@value{PRIMARYREALM} +@result{} kadmin/admin@@@value{PRIMARYREALM} +@b{kadmin/admin@@@value{PRIMARYREALM} +K/M@@@value{PRIMARYREALM} +shell%} +@end group +@end smallexample + +@noindent +Otherwise, the principals will not match those in the database and will +not be dumped: + +@smallexample +@group +@b{shell%} kdb5_util dump -verbose dumpfile K/M kadmin/admin +@b{shell%} +@end group +@end smallexample + +@noindent +If you do not specify a dump file, @code{kdb5_util} will dump the +database to the standard output. + +@node Restoring a Kerberos Database from a Dump File, Creating a Stash File, Dumping a Kerberos Database to a File, Administrating Kerberos Database Entries +@section Restoring a Kerberos Database from a Dump File + +To restore a Kerberos database dump from a file, use the +@code{kdb5_util} @code{load} command on one of the KDCs. The syntax +is: + +@smallexample +@b{kdb5_util load} [@b{-old}] [@b{-b6}] [@b{-ov}] [@b{-verbose}] [@b{-update}] +@i{dumpfilename} @i{dbname} [@i{admin_dbname}] +@end smallexample + +The @code{kdb5_util load} command takes the following options: + +@table @b +@itemx -old +requires the dump to be in the Kerberos 5 Beta 5 and earlier dump format +(``kdb5_edit load_dump version 2.0''). +@itemx -b6 +requires the dump to be in the Kerberos 5 Beta 6 format (``kdb5_edit +load_dump version 3.0''). +@itemx -ov +requires the dump to be in ovsec_adm_export format. +@itemx -verbose +causes the name of each principal and policy to be printed as it is +dumped. +@itemx -update +causes records from the dump file to be updated in or added to the +existing database. +@end table + +For example: + +@smallexample +@group +@b{shell%} kdb5_util load dumpfile principal +@b{shell%} +@end group +@end smallexample + +@smallexample +@group +@b{shell%} kdb5_util load -update dumpfile principal +@b{shell%} +@end group +@end smallexample + +@noindent +If the database file exists, and the @b{-update} flag was not given, +@code{kdb5_util} will overwrite the existing database. + +@node Creating a Stash File, Creating and Destroying a Kerberos Database, Restoring a Kerberos Database from a Dump File, Administrating Kerberos Database Entries +@section Creating a Stash File + +A stash file allows a KDC to authenticate itself to the database +utilities, such as @code{kadmin}, @code{kadmind}, @code{krb5kdc}, and +@code{kdb5_util}. + +To create a stash file, use the @code{kdb5_util} @code{stash} command. +The syntax is: + +@smallexample +@b{kdb5_util stash} [@b{-f} @i{keyfile}] +@end smallexample + +For example: + +@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{} Type the KDC database master password.} +@end iftex +@ifinfo +@b{Enter KDC database master key:} @i{<= Type the KDC database master password.} +@end ifinfo +@b{shell%} +@end group +@end smallexample + +@noindent +If you do not specify a stash file, @code{kdb5_util} will stash the key +in the file specified in your @code{kdc.conf} file. + +@node Creating and Destroying a Kerberos Database, The KDC Logs, Creating a Stash File, Administrating Kerberos Database Entries +@section Creating and Destroying a Kerberos Database + +If you need to create a new Kerberos database, use the @code{kdb5_util} +@code{create} command. The syntax is: + +@smallexample +@b{kdb5_util create} [@b{-s}] +@end smallexample + +If you specify the @samp{-s} option, @code{kdb5_util} will stash a copy +of the master key in a stash file. (@xref{Creating a Stash File}.) For +example: + +@smallexample +@group +@b{shell%} @value{ROOTDIR}/sbin/kdb5_util -r @value{PRIMARYREALM} create -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 + +@ignore +@node The KDC Logs, , Creating and Destroying a Kerberos Database, Administrating Kerberos Database Entries +@section The KDC Logs + +This will have to wait until the next release. *sigh* +@end ignore + +@node Application Servers, Updates, Administrating Kerberos Database Entries, Top +@chapter Application Servers + +If you need to install the @value{PRODUCT} programs on an application +server, please refer to the @value{PRODUCT} Installation Guide. Once +you have installed the software, you need to add that host to the +Kerberos database (@pxref{Adding or Modifying Principals}), and generate +a @dfn{keytab} for that host, that contains the host's key. You also +need to make sure the host's clock is within your maximum clock skew of +the KDCs. + +@menu +* Keytabs:: +* Clock Skew:: +* Getting DNS Information Correct:: +* Configuring Your Firewall to Work With @value{PRODUCT}:: +* Enabling Users to Connect from Off-Site:: +@end menu + +@node Keytabs, Clock Skew, Application Servers, Application Servers +@section Keytabs + +A @dfn{keytab} is a host's copy of its own keylist, which is analogous +to a user's password. An application server that needs to authenticate +itself to the KDC has to have a keytab that contains its own principal +and key. Just as it is important for users to protect their passwords, +it is equally important for hosts to protect their keytabs. You should +always store keytab files on local disk, and make them readable only by +root, and you should never send a keytab file over a network in the +clear. Ideally, you should run the @code{kadmin} command to extract a +keytab on the host on which the keytab is to reside. + +@menu +* Adding Principals to Keytabs:: +* Removing Principals from Keytabs:: +@end menu + +@node Adding Principals to Keytabs, Removing Principals from Keytabs, Keytabs, Keytabs +@subsection Adding Principals to Keytabs + +To generate a keytab, or to add a principal to an existing keytab, use +the @code{ktadd} command from @code{kadmin}, which requires the +``inquire'' administrative privilege. (If you use the @b{-glob} +@i{princ_exp} option, it also requires the ``list'' administrative +privilege.) The syntax is: + +@smallexample +@b{ktadd} [@b{-k} @i{keytab}] [@b{-q}] [@i{principal} | @b{-glob} @i{princ_exp}] [@i{@dots{}}] +@end smallexample + +The @code{ktadd} command takes the following switches: + +@table @b +@item -k @i{keytab} +use @i{keytab} as the keytab file. Otherwise, @code{ktadd} will use the +default keytab file (@code{/etc/v5srvtab}). + +@item -q +run in quiet mode. This causes @code{ktadd} to display less verbose +information. + +@item @i{principal} | -glob @i{principal expression} +add @i{principal}, or all principals matching @i{principal expression} +to the keytab. The rules for @i{principal expression} are the same as +for the kadmin @code{list_principals} (@pxref{Retrieving a List of +Principals}) command. +@end table + +For example: + +@smallexample +@group +@b{kadmin:} ktadd host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} +@b{kadmin: Entry for principal host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} with + kvno 2, encryption type DES-CBC-CRC added to keytab + WRFILE:/etc/v5srvtab. +kadmin:} +@end group +@end smallexample + +@smallexample +@group +@b{kadmin:} ktadd -k /krb5/kadmind.keytab 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:/krb5/kadmind.keytab. +kadmin:} +@end group +@end smallexample + +@node Removing Principals from Keytabs, , Adding Principals to Keytabs, Keytabs +@subsection Removing Principals from Keytabs + +To remove a principal to an existing keytab, use the kadmin +@code{ktremove} command. The syntax is: + +@smallexample +@b{ktremove} [@b{-k} @i{keytab}] [@b{-q}] @i{principal} [@i{kvno} | @b{all} | @b{old}] +@end smallexample + +The @code{ktremove} command takes the following switches: + +@table @b +@item -k @i{keytab} +use @i{keytab} as the keytab file. Otherwise, @code{ktremove} will use +the default keytab file (@code{/etc/v5srvtab}). + +@item -q +run in quiet mode. This causes @code{ktremove} to display less verbose +information. + +@item @i{principal} +the principal to remove from the keytab. (Required.) + +@item @i{kvno} +remove all entries for the specified principal whose Key Version Numbers +match @i{kvno}. + +@item all +remove all entries for the specified principal + +@item old +remove all entries for the specified principal except those with the +highest kvno. +@end table + +For example: + +@smallexample +@group +@b{kadmin:} ktremove -k /krb5/kadmind.keytab kadmin/admin +@b{kadmin: Entry for principal kadmin/admin with kvno 3 removed + from keytab WRFILE:/krb5/kadmind.keytab. +kadmin:} +@end group +@end smallexample + +@node Clock Skew, Getting DNS Information Correct, Keytabs, Application Servers +@section Clock Skew + +In order to prevent intruders from resetting their system clocks in +order to continue to use expired tickets, @value{PRODUCT} is set up to +reject ticket requests from any host whose clock is not within the +specified maximum clock skew of the KDC (as specified in the +@code{kdc.conf} file). Similarly, hosts are configured to reject +responses from any KDC whose clock is not within the specified maximum +clock skew of the host (as specified in the @code{krb5.conf} file). The +default value for maximum clock skew is 300 seconds (five minutes). + +@value{COMPANY} suggests that you add a line to client machines' +@code{/etc/rc} files to synchronize the machine's clock to your KDC at +boot time. On UNIX hosts, assuming you had a kdc called +@code{@value{KDCSERVER}} in your realm, this would be: + +@smallexample +gettime -s @value{KDCSERVER} +@end smallexample + +If the host is not likely to be rebooted frequently, you may also want +to set up a cron job that adjusts the time on a regular basis. + +@node Getting DNS Information Correct, Configuring Your Firewall to Work With @value{PRODUCT}, Clock Skew, Application Servers +@section Getting DNS Information Correct + +Several aspects of Kerberos rely on name service. In order for Kerberos +to provide its high level of security, it is less forgiving of name +service problems than some other parts of your network. It is important +that your Distributed Name Service (DNS) entries and your hosts have the +correct information. + +Each host's canonical name must be the fully-qualified host name +(including the domain), and each host's IP address must reverse-resolve +to the canonical name. + +Other than the @code{localhost} entry, make all entries in each +machine's @code{/etc/hosts} file in the following form: + +@smallexample +IP address fully-qualified hostname aliases +@end smallexample + +Here is a sample @code{/etc/hosts} file: + +@smallexample +@group +# this is a comment +127.0.0.1 localhost localhost@@@value{PRIMARYDOMAIN} +@value{RANDOMHOST1IP} @value{RANDOMHOST1}.@value{PRIMARYDOMAIN} trillium wake-robin +@end group +@end smallexample + +Additionally, on Solaris machines, you need to be sure the ``hosts'' +entry in the file @code{/etc/nsswitch.conf} includes the source ``dns'' +as well as ``file''. + +Finally, each host's keytab file must include a host/key pair for the +host's canonical name. You can list the keys in a keytab file by +issuing the command @code{klist -k}. For example: + +@smallexample +@group +viola# klist -k +Keytab name: /etc/v5srvtab +KVNO Principal +---- ------------------------------------------------------------ + 1 host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} +@end group +@end smallexample + +If you telnet to the host with a fresh credentials cache (ticket file), +and then @code{klist}, the host's service principal should be +@i{host/fully-qualified-hostname@@REALM_NAME}. + +@node Configuring Your Firewall to Work With @value{PRODUCT}, Enabling Users to Connect from Off-Site, Getting DNS Information Correct, Application Servers +@section Configuring Your Firewall to Work With @value{PRODUCT} + +If you need off-site users to be able to get Kerberos tickets in your +realm, they must be able to get to your KDC. This requires either that +you have a slave KDC outside your firewall, or you configure your +firewall to allow UDP requests into to at least one of your KDCs, on +whichever port the KDC is running. (The default is port 88; other ports +may be specified in the KDC's kdc.conf file.) Similarly, if you need +off-site users to be able to change their passwords in your realm, they +must be able to get to your Kerberos admin server. The default port for +the admin server is 749. + +If your on-site users inside your firewall will need to get to KDCs in +other realms, you will also need to configure your firewall to allow +outgoing TCP and UDP requests to port 88. Additionally, if they will +need to get to any Kerberos V4 KDCs, you may also need to allow TCP and +UDP requests to port 750. If your on-site users inside your firewall +will need to get to Kerberos admin servers in other realms, you will +also need to allow outgoing TCP and UDP requests to port 749. + +If any of your KDCs is outside your firewall, you will need to allow +@code{kprop} requests to get through to the remote KDC. @code{Kprop} +uses the krb5_prop service on port 754 (tcp). + +If you need your off-site users to have access to machines inside your +firewall, you need to allow TCP connections from their off-site hosts on +the appropriate ports for the programs they will be using. The +following lines from @code{/etc/services} show the default port numbers +for the @value{PRODUCT} programs: + +@smallexample +@group +ftp 21/tcp # Kerberos ftp and telnet use the +telnet 23/tcp # default ports +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 + +By default, @value{PRODUCT} @code{telnet} and @code{ftp} use the same +ports as the standard @code{telnet} and @code{ftp} programs, so if you +already allow telnet and ftp connections through your firewall, the +@value{PRODUCT} versions will get through as well. If you do not +already allow telnet and ftp connections through your firewall, but need +your users to be able to use @value{PRODUCT} telnet and ftp, you can +either allow ftp and telnet connections on the standard ports, or switch +these programs to non-default port numbers and allow ftp and telnet +connections on those ports to get through. + +@value{PRODUCT} @code{rlogin} uses the @code{klogin} service, which by +default uses port 543. Encrypted @value{PRODUCT} rlogin uses uses the +@code{eklogin} service, which by default uses port 2105. + +@value{PRODUCT} @code{rsh} uses the @code{kshell} service, which by +default uses port 544. However, the server must be able to make a TCP +connection from the kshell port to an arbitrary port on the client, so +if your users are to be able to use @code{rsh} from outside your +firewall, the server they connect to must be able to send outgoing +packets to arbitrary port numbers. Similarly, if your users need to run +@code{rsh} from inside your firewall to hosts outside your firewall, the +outside server needs to be able to connect to an arbitrary port on the +machine inside your firewall. Because @value{PRODUCT} @code{rcp} and +@code{krdist} use @code{rsh}, the same issues apply to these programs. +If you need to use @code{rsh} (or @code{rcp} or @code{krdist}) through +your firewall and are concerned with the security implications of +allowing connections to arbitrary ports, @value{COMPANY} suggests that +you have rules that specifically name these applications and, if +possible, list the allowed hosts. + +A reasonably good cookbook for configuring firewalls is available by FTP +from @code{ftp.livingston.com}, in the location: +@code{/pub/firewall/firewall-1.1.ps.Z}. The book @cite{UNIX System +Security}, by David Curry, is also a good starting point. + +@ignore +@node Enabling Users to Connect from Off-Site, , Configuring Your Firewall to Work With @value{PRODUCT}, Application Servers +@section Enabling Users to Connect from Off-Site + +This will have to wait until the next release. *sigh* +@end ignore + +@node Updates, Backups of Secure Hosts, Application Servers, Top +@chapter Updates + +Because the directory into which @value{PRODUCT} installs itself +contains the release name, it is easy to install a new release of +@value{PRODUCT}, and to de-install an old one. If you have a problem +with a new release, it is equally easy to revert to the earlier release. +These procedures will also work if you are updating from any other +version of Kerberos V5. + +@menu +* Updating KDCs:: +* Updating Application Servers:: +@end menu + +@node Updating KDCs, Updating Application Servers, Updates, Updates +@section Updating KDCs + +To update a KDC from an earlier version of @value{PRODUCT} or of +Kerberos V5, you need to do the following: + +@enumerate +@item +Install the new software. +@item +Copy your @code{kdc.conf} file and stash file from the old installation +to the new one. For example, if you were upgrading from @value{PRODUCT} +version @value{PREVRELEASE} to version @value{RELEASE}, you would have +to copy these files from the directory @value{PREVINSTALLDIR} to the +directory @value{INSTALLDIR}. Be sure the new copy of the stash file +has the correct name. (The default is @code{.k5stash}, unless you have +specified something different in your @code{kdc.conf} file.) +@item +Create a dump of the old database, using whichever old command you used +with that release (@i{e.g.,} the @code{kdb5_dump} command). +@item +Load the dumpfile into the new database in the new location, using the +@code{kdb5_util} @code{load} command. Be sure to give @code{load} +the argument for the correct dump format. +@item +Change any symbolic links you have (@i{e.g.}, +@code{/usr/@value{LCPRODUCT}}) so that they point to the new +installation. +@end enumerate +@c Reference to upgrading from Kerberos V4 document, once it's written. + +@node Updating Application Servers, , Updating KDCs, Updates +@section Updating Clients and Application Servers + +To update a client or application server, you need only to install the +new release and change any symbolic links to point to the new programs. +Other than any functionality changes in the programs, the upgrade should +be completely user-transparent. +@c Reference to upgrading from Kerberos V4 document, once it's written. + +@node Backups of Secure Hosts, Support, Updates, Top +@chapter Backups of Secure Hosts + +When you back up a secure host, you should exclude the host's keytab +file from the backup. If someone obtained a copy of the keytab from a +backup, that person could make any host masquerade as the host whose +keytab was compromised. This could be particularly dangerous if the +compromised keytab was from one of your KDCs. If the machine has a disk +crash and the keytab file is lost, it is easy to generate another keytab +file. (@xref{Adding Principals to Keytabs}.) If you are unable to +exclude particular files from backups, you should ensure that the +backups are kept as secure as the host's root password. + +@menu +* Backing Up the Kerberos Database:: +@end menu + +@node Backing Up the Kerberos Database, , Backups of Secure Hosts, Backups of Secure Hosts +@section Backing Up the Kerberos Database + +It is possible that the Kerberos database could be corrupted. If this +happens on one of the slave KDCs, you might never notice, since the next +automatic propagation of the database would install a fresh copy. +However, if it happens to the master KDC, the corrupted database would +be propagated to all of the slaves during the next propagation. For +this reason, @value{COMPANY} recommends that you back up your Kerberos +database regularly. Because the master KDC is continuously dumping the +database to a file in order to propagate it to the slave KDCs, it is a +simple matter to have a cron job periodically copy the dump file to a +secure machine elsewhere on your network. (Of course, it is important +to make the host where these backups are stored as secure as your KDCs, +and to encrypt its transmission across your network.) Then if your +database becomes corrupted, you can load the most recent dump onto the +master KDC. (@xref{Restoring a Kerberos Database from a Dump File}.) + +@node Support, Appendix, Backups of Secure Hosts, Top +@chapter Support + +@menu +* Supported Functionalities:: +* Using sendpr:: +@end menu + +@node Supported Functionalities, Using sendpr, Support, Support +@section Supported Functionalities + +@node Using sendpr, , Supported Functionalities, Support +@section Using sendpr + +@include send-pr.texinfo + +@node Appendix, , Support, Top +@appendix Appendix + +@menu +* Files:: +* krb5.conf:: +* kdc.conf:: +* Errors:: +* kadmin Time Zones:: +@end menu + +@node Files, krb5.conf, Appendix, Appendix +@appendixsec Files + +@node krb5.conf, kdc.conf, Files, Appendix +@appendixsec krb5.conf + +Normally, you should install your @code{krb5.conf} file in the directory +@code{/etc}. However, note that you can override this default through +the environment variable @samp{KRB5_CONFIG}. + +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} + +[logging] + kdc = FILE:/dev/ttyp9 + admin_server = FILE:/dev/ttyp9 + default = FILE:/dev/ttyp9 +@end group +@end smallexample + +@iftex +@vfill +@end iftex +@page + +Here is an example of a more extensive @code{krb5.conf} file, which +includes a second Kerberos realm and authentication to Kerberos V4 as +well as V5 KDCs in the realm @code{@value{PRIMARYREALM}}: + +@smallexample +@group +[libdefaults] + ticket_lifetime = 600 + default_realm = @value{PRIMARYREALM} + default_tkt_enctypes = des-cbc-crc + default_tgs_enctypes = des-cbc-crc + krb4_srvtab = /etc/srvtab + krb4_config = /usr/krb4/lib/krb.conf + krb4_realms = /usr/krb4/lib/krb.realms + +[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} + v4_instance_convert = @{ + bleep = @value{PRIMARYDOMAIN} + @} + @} + @value{SECONDREALM} = @{ + kdc = @value{KDCSERVER}.@value{SECONDDOMAIN} + kdc = @value{KDCSLAVE1}.@value{SECONDDOMAIN} + admin_server = @value{KDCSERVER}.@value{SECONDDOMAIN} + @} + +[domain_realm] + .@value{PRIMARYDOMAIN} = @value{PRIMARYREALM} + @value{PRIMARYDOMAIN} = @value{PRIMARYREALM} + .@value{SECONDDOMAIN} = @value{SECONDREALM} + @value{SECONDDOMAIN} = @value{SECONDREALM} +@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] + admin_server = FILE:@value{ROOTDIR}/lib/krb5kdc/kadmind.log + kdc = FILE:@value{ROOTDIR}/lib/krb5kdc/kdc.log + default = CONSOLE +@end group +@end smallexample + +@iftex +@vfill +@end iftex +@page + +@node kdc.conf, Errors, krb5.conf, Appendix +@appendixsec kdc.conf + +Normally, you should install your @code{kdc.conf} file in the directory +@code{@value{ROOTDIR}/lib/krb5kdc}. However, note that you can override +this default by a pointer in the KDC's @code{krb5.conf} file, or through +the environment variable @samp{KRB5_KDC_PROFILE}. + +Here's an example of a @code{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 + +@node Errors, kadmin Time Zones, kdc.conf, Appendix +@appendixsec Kerberos Error Messages + +@menu +* Kerberos V5 Library Error Codes:: +* Kerberos V5 Database Library Error Codes:: +* Kerberos V5 Magic Numbers Error Codes:: +* ASN.1 Error Codes:: +* GSSAPI Error Codes:: +@end menu + +@node Kerberos V5 Library Error Codes, Kerberos V5 Database Library Error Codes, Errors, Errors +@appendixsubsec Kerberos V5 Library Error Codes + +This is the Kerberos v5 library error code table. Protocol error codes +are ERROR_TABLE_BASE_krb5 + the protocol error code number; other error +codes start at ERROR_TABLE_BASE_krb5 + 128. + +@c error table numbering starts at 0 +@enumerate 0 +@item +KRB5KDC_ERR_NONE: No error +@item +KRB5KDC_ERR_NAME_EXP: Client's entry in database has expired +@item +KRB5KDC_ERR_SERVICE_EXP: Server's entry in database has expired +@item +KRB5KDC_ERR_BAD_PVNO: Requested protocol version not supported +@item +KRB5KDC_ERR_C_OLD_MAST_KVNO: Client's key is encrypted in an old master +key +@item +KRB5KDC_ERR_S_OLD_MAST_KVNO: Server's key is encrypted in an old master +key +@item +KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN: Client not found in Kerberos database +@item +KRB5KDC_ERR_S_PRINCIPAL_UNKNOWN: Server not found in Kerberos database +@item +KRB5KDC_ERR_PRINCIPAL_NOT_UNIQUE: Principal has multiple entries in +Kerberos database +@item +KRB5KDC_ERR_NULL_KEY: Client or server has a null key +@item +KRB5KDC_ERR_CANNOT_POSTDATE: Ticket is ineligible for postdating +@item +KRB5KDC_ERR_NEVER_VALID: Requested effective lifetime is negative or +too short +@item +KRB5KDC_ERR_POLICY: KDC policy rejects request +@item +KRB5KDC_ERR_BADOPTION: KDC can't fulfill requested option +@item +KRB5KDC_ERR_ETYPE_NOSUPP: KDC has no support for encryption type +@item +KRB5KDC_ERR_SUMTYPE_NOSUPP: KDC has no support for checksum type +@item +KRB5KDC_ERR_PADATA_TYPE_NOSUPP: KDC has no support for padata type +@item +KRB5KDC_ERR_TRTYPE_NOSUPP: KDC has no support for transited type +@item +KRB5KDC_ERR_CLIENT_REVOKED: Clients credentials have been revoked +@item +KRB5KDC_ERR_SERVICE_REVOKED: Credentials for server have been revoked +@item +KRB5KDC_ERR_TGT_REVOKED: TGT has been revoked +@item +KRB5KDC_ERR_CLIENT_NOTYET: Client not yet valid - try again later +@item +KRB5KDC_ERR_SERVICE_NOTYET: Server not yet valid - try again later +@item +KRB5KDC_ERR_KEY_EXP: Password has expired +@item +KRB5KDC_ERR_PREAUTH_FAILED: Preauthentication failed +@item +@iftex +KRB5KDC_ERR_PREAUTH_REQUIRED: Additional pre-auth@-en@-ti@-ca@-tion required +@end iftex +@ifinfo +KRB5KDC_ERR_PREAUTH_REQUIRED: Additional preauthentication required +@end ifinfo +@item +KRB5KDC_ERR_SERVER_NOMATCH: Requested server and ticket don't match +@item +KRB5PLACEHOLD_27: KRB5 error code 27 +@item +KRB5PLACEHOLD_28: KRB5 error code 28 +@item +KRB5PLACEHOLD_29: KRB5 error code 29 +@item +KRB5PLACEHOLD_30: KRB5 error code 30 +@item +KRB5KRB_AP_ERR_BAD_INTEGRITY: Decrypt integrity check failed +@item +KRB5KRB_AP_ERR_TKT_EXPIRED: Ticket expired +@item +KRB5KRB_AP_ERR_TKT_NYV: Ticket not yet valid +@item +KRB5KRB_AP_ERR_REPEAT: Request is a replay +@item +KRB5KRB_AP_ERR_NOT_US: The ticket isn't for us +@item +KRB5KRB_AP_ERR_BADMATCH: Ticket/authenticator don't match +@item +KRB5KRB_AP_ERR_SKEW: Clock skew too great +@item +KRB5KRB_AP_ERR_BADADDR: Incorrect net address +@item +KRB5KRB_AP_ERR_BADVERSION: Protocol version mismatch +@item +KRB5KRB_AP_ERR_MSG_TYPE: Invalid message type +@item +KRB5KRB_AP_ERR_MODIFIED: Message stream modified +@item +KRB5KRB_AP_ERR_BADORDER: Message out of order +@item +KRB5KRB_AP_ERR_ILL_CR_TKT: Illegal cross-realm ticket +@item +KRB5KRB_AP_ERR_BADKEYVER: Key version is not available +@item +KRB5KRB_AP_ERR_NOKEY: Service key not available +@item +KRB5KRB_AP_ERR_MUT_FAIL: Mutual authentication failed +@item +KRB5KRB_AP_ERR_BADDIRECTION: Incorrect message direction +@item +KRB5KRB_AP_ERR_METHOD: Alternative authentication method required +@item +KRB5KRB_AP_ERR_BADSEQ: Incorrect sequence number in message +@item +KRB5KRB_AP_ERR_INAPP_CKSUM: Inappropriate type of checksum in message +@item +KRB5PLACEHOLD_51: KRB5 error code 51 +@item +KRB5PLACEHOLD_52: KRB5 error code 52 +@item +KRB5PLACEHOLD_53: KRB5 error code 53 +@item +KRB5PLACEHOLD_54: KRB5 error code 54 +@item +KRB5PLACEHOLD_55: KRB5 error code 55 +@item +KRB5PLACEHOLD_56: KRB5 error code 56 +@item +KRB5PLACEHOLD_57: KRB5 error code 57 +@item +KRB5PLACEHOLD_58: KRB5 error code 58 +@item +KRB5PLACEHOLD_59: KRB5 error code 59 +@item +KRB5KRB_ERR_GENERIC: Generic error (see e-text) +@item +KRB5KRB_ERR_FIELD_TOOLONG: Field is too long for this implementation +@item +KRB5PLACEHOLD_62: KRB5 error code 62 +@item +KRB5PLACEHOLD_63: KRB5 error code 63 +@item +KRB5PLACEHOLD_64: KRB5 error code 64 +@item +KRB5PLACEHOLD_65: KRB5 error code 65 +@item +KRB5PLACEHOLD_66: KRB5 error code 66 +@item +KRB5PLACEHOLD_67: KRB5 error code 67 +@item +KRB5PLACEHOLD_68: KRB5 error code 68 +@item +KRB5PLACEHOLD_69: KRB5 error code 69 +@item +KRB5PLACEHOLD_70: KRB5 error code 70 +@item +KRB5PLACEHOLD_71: KRB5 error code 71 +@item +KRB5PLACEHOLD_72: KRB5 error code 72 +@item +KRB5PLACEHOLD_73: KRB5 error code 73 +@item +KRB5PLACEHOLD_74: KRB5 error code 74 +@item +KRB5PLACEHOLD_75: KRB5 error code 75 +@item +KRB5PLACEHOLD_76: KRB5 error code 76 +@item +KRB5PLACEHOLD_77: KRB5 error code 77 +@item +KRB5PLACEHOLD_78: KRB5 error code 78 +@item +KRB5PLACEHOLD_79: KRB5 error code 79 +@item +KRB5PLACEHOLD_80: KRB5 error code 80 +@item +KRB5PLACEHOLD_81: KRB5 error code 81 +@item +KRB5PLACEHOLD_82: KRB5 error code 82 +@item +KRB5PLACEHOLD_83: KRB5 error code 83 +@item +KRB5PLACEHOLD_84: KRB5 error code 84 +@item +KRB5PLACEHOLD_85: KRB5 error code 85 +@item +KRB5PLACEHOLD_86: KRB5 error code 86 +@item +KRB5PLACEHOLD_87: KRB5 error code 87 +@item +KRB5PLACEHOLD_88: KRB5 error code 88 +@item +KRB5PLACEHOLD_89: KRB5 error code 89 +@item +KRB5PLACEHOLD_90: KRB5 error code 90 +@item +KRB5PLACEHOLD_91: KRB5 error code 91 +@item +KRB5PLACEHOLD_92: KRB5 error code 92 +@item +KRB5PLACEHOLD_93: KRB5 error code 93 +@item +KRB5PLACEHOLD_94: KRB5 error code 94 +@item +KRB5PLACEHOLD_95: KRB5 error code 95 +@item +KRB5PLACEHOLD_96: KRB5 error code 96 +@item +KRB5PLACEHOLD_97: KRB5 error code 97 +@item +KRB5PLACEHOLD_98: KRB5 error code 98 +@item +KRB5PLACEHOLD_99: KRB5 error code 99 +@item +KRB5PLACEHOLD_100: KRB5 error code 100 +@item +KRB5PLACEHOLD_101: KRB5 error code 101 +@item +KRB5PLACEHOLD_102: KRB5 error code 102 +@item +KRB5PLACEHOLD_103: KRB5 error code 103 +@item +KRB5PLACEHOLD_104: KRB5 error code 104 +@item +KRB5PLACEHOLD_105: KRB5 error code 105 +@item +KRB5PLACEHOLD_106: KRB5 error code 106 +@item +KRB5PLACEHOLD_107: KRB5 error code 107 +@item +KRB5PLACEHOLD_108: KRB5 error code 108 +@item +KRB5PLACEHOLD_109: KRB5 error code 109 +@item +KRB5PLACEHOLD_110: KRB5 error code 110 +@item +KRB5PLACEHOLD_111: KRB5 error code 111 +@item ++ +KRB5PLACEHOLD_112: KRB5 error code 112 +@item +KRB5PLACEHOLD_113: KRB5 error code 113 +@item +KRB5PLACEHOLD_114: KRB5 error code 114 +@item +KRB5PLACEHOLD_115: KRB5 error code 115 +@item +KRB5PLACEHOLD_116: KRB5 error code 116 +@item +KRB5PLACEHOLD_117: KRB5 error code 117 +@item +KRB5PLACEHOLD_118: KRB5 error code 118 +@item +KRB5PLACEHOLD_119: KRB5 error code 119 +@item +KRB5PLACEHOLD_120: KRB5 error code 120 +@item +KRB5PLACEHOLD_121: KRB5 error code 121 +@item +KRB5PLACEHOLD_122: KRB5 error code 122 +@item +KRB5PLACEHOLD_123: KRB5 error code 123 +@item +KRB5PLACEHOLD_124: KRB5 error code 124 +@item +KRB5PLACEHOLD_125: KRB5 error code 125 +@item +KRB5PLACEHOLD_126: KRB5 error code 126 +@item +KRB5PLACEHOLD_127: KRB5 error code 127 +@item +KRB5_ERR_RCSID: $Id$ +@item +KRB5_LIBOS_BADLOCKFLAG: Invalid flag for file lock mode +@item +KRB5_LIBOS_CANTREADPWD: Cannot read password +@item +KRB5_LIBOS_BADPWDMATCH: Password mismatch +@item +KRB5_LIBOS_PWDINTR: Password read interrupted +@item +KRB5_PARSE_ILLCHAR: Illegal character in component name +@item +KRB5_PARSE_MALFORMED: Malformed representation of principal +@item +KRB5_CONFIG_CANTOPEN: Can't open/find configuration file +@item +KRB5_CONFIG_BADFORMAT: Improper format of configuration file +@item +KRB5_CONFIG_NOTENUFSPACE: Insufficient space to return complete +information +@item +KRB5_BADMSGTYPE: Invalid message type specified for encoding +@item +KRB5_CC_BADNAME: Credential cache name malformed +@item +KRB5_CC_UNKNOWN_TYPE: Unknown credential cache type +@item +KRB5_CC_NOTFOUND: Matching credential not found +@item +KRB5_CC_END: End of credential cache reached +@item +KRB5_NO_TKT_SUPPLIED: Request did not supply a ticket +@item +KRB5KRB_AP_WRONG_PRINC: Wrong principal in request +@item +KRB5KRB_AP_ERR_TKT_INVALID: Ticket has invalid flag set +@item +KRB5_PRINC_NOMATCH: Requested principal and ticket don't match +@item +KRB5_KDCREP_MODIFIED: KDC reply did not match expectations +@item +KRB5_KDCREP_SKEW: Clock skew too great in KDC reply +@item +KRB5_IN_TKT_REALM_MISMATCH: Client/server realm mismatch in initial +ticket request +@item +KRB5_PROG_ETYPE_NOSUPP: Program lacks support for encryption type +@item +KRB5_PROG_KEYTYPE_NOSUPP: Program lacks support for key type +@item +KRB5_WRONG_ETYPE: Requested encryption type not used in message +@item +KRB5_PROG_SUMTYPE_NOSUPP: Program lacks support for checksum type +@item +KRB5_REALM_UNKNOWN: Cannot find KDC for requested realm +@item +KRB5_SERVICE_UNKNOWN: Kerberos service unknown +@item +KRB5_KDC_UNREACH: Cannot contact any KDC for requested realm +@item +KRB5_NO_LOCALNAME: No local name found for principal name +@item +KRB5_MUTUAL_FAILED: Mutual authentication failed +@item +KRB5_RC_TYPE_EXISTS: Replay cache type is already registered +@item +KRB5_RC_MALLOC: No more memory to allocate (in replay cache code) +@item +KRB5_RC_TYPE_NOTFOUND: Replay cache type is unknown +@item +KRB5_RC_UNKNOWN: Generic unknown RC error +@item +KRB5_RC_REPLAY: Message is a replay +@item +KRB5_RC_IO: Replay I/O operation failed XXX +@item +KRB5_RC_NOIO: Replay cache type does not support non-volatile storage +@item +KRB5_RC_PARSE: Replay cache name parse/format error +@item +KRB5_RC_IO_EOF: End-of-file on replay cache I/O +@item +KRB5_RC_IO_MALLOC: No more memory to allocate (in replay cache I/O +code) +@item +KRB5_RC_IO_PERM: Permission denied in replay cache code +@item +KRB5_RC_IO_IO: I/O error in replay cache i/o code +@item +KRB5_RC_IO_UNKNOWN: Generic unknown RC/IO error +@item +KRB5_RC_IO_SPACE: Insufficient system space to store replay information +@item +KRB5_TRANS_CANTOPEN: Can't open/find realm translation file +@item +KRB5_TRANS_BADFORMAT: Improper format of realm translation file +@item +KRB5_LNAME_CANTOPEN: Can't open/find lname translation database +@item +KRB5_LNAME_NOTRANS: No translation available for requested principal +@item +KRB5_LNAME_BADFORMAT: Improper format of translation database entry +@item +KRB5_CRYPTO_INTERNAL: Cryptosystem internal error +@item +KRB5_KT_BADNAME: Key table name malformed +@item +KRB5_KT_UNKNOWN_TYPE: Unknown Key table type +@item +KRB5_KT_NOTFOUND: Key table entry not found +@item +KRB5_KT_END: End of key table reached +@item +KRB5_KT_NOWRITE: Cannot write to specified key table +@item +KRB5_KT_IOERR: Error writing to key table +@item +KRB5_NO_TKT_IN_RLM: Cannot find ticket for requested realm +@item +KRB5DES_BAD_KEYPAR: DES key has bad parity +@item +KRB5DES_WEAK_KEY: DES key is a weak key +@item +KRB5_BAD_ENCTYPE: Bad encryption type +@item +KRB5_BAD_KEYSIZE: Key size is incompatible with encryption type +@item +KRB5_BAD_MSIZE: Message size is incompatible with encryption type +@item +KRB5_CC_TYPE_EXISTS: Credentials cache type is already registered. +@item +KRB5_KT_TYPE_EXISTS: Key table type is already registered. +@item +KRB5_CC_IO: Credentials cache I/O operation failed XXX +@item +KRB5_FCC_PERM: Credentials cache file permissions incorrect +@item +KRB5_FCC_NOFILE: No credentials cache file found +@item +KRB5_FCC_INTERNAL: Internal file credentials cache error +@item +KRB5_CC_WRITE: Error writing to credentials cache file +@item +KRB5_CC_NOMEM: No more memory to allocate (in credentials cache code) +@item +KRB5_CC_FORMAT: Bad format in credentials cache +@item +KRB5_INVALID_FLAGS: Invalid KDC option combination (library internal +error) [for dual tgt library calls] +@item +KRB5_NO_2ND_TKT: Request missing second ticket [for dual tgt library +calls] +@item +KRB5_NOCREDS_SUPPLIED: No credentials supplied to library routine +@item +KRB5_SENDAUTH_BADAUTHVERS: Bad sendauth version was sent +@item +KRB5_SENDAUTH_BADAPPLVERS: Bad application version was sent (via +sendauth) +@item +KRB5_SENDAUTH_BADRESPONSE: Bad response (during sendauth exchange) +@item +KRB5_SENDAUTH_REJECTED: Server rejected authentication (during sendauth +exchange) +@item +KRB5_PREAUTH_BAD_TYPE: Unsupported preauthentication type +@item +KRB5_PREAUTH_NO_KEY: Required preauthentication key not supplied +@item +KRB5_PREAUTH_FAILED: Generic preauthentication failure +@item +KRB5_RCACHE_BADVNO: Unsupported replay cache format version number +@item +KRB5_CCACHE_BADVNO: Unsupported credentials cache format version number +@item +KRB5_KEYTAB_BADVNO: Unsupported key table format version number +@item +KRB5_PROG_ATYPE_NOSUPP: Program lacks support for address type +@item +KRB5_RC_REQUIRED: Message replay detection requires rcache parameter +@item +KRB5_ERR_BAD_HOSTNAME: Hostname cannot be canonicalized +@item +KRB5_ERR_HOST_REALM_UNKNOWN: Cannot determine realm for host +@item +KRB5_SNAME_UNSUPP_NAMETYPE: Conversion to service principal undefined +for name type +@item +KRB5KRB_AP_ERR_V4_REPLY: Initial Ticket response appears to be Version +4 error +@item +KRB5_REALM_CANT_RESOLVE: Cannot resolve KDC for requested realm +@item +KRB5_TKT_NOT_FORWARDABLE: Requesting ticket can't get forwardable +tickets +@item +KRB5_FWD_BAD_PRINCIPAL: Bad principal name while trying to forward +credentials +@item +KRB5_GET_IN_TKT_LOOP: Looping detected inside krb5_get_in_tkt +@item +KRB5_CONFIG_NODEFREALM: Configuration file does not specify default +realm +@item +KRB5_SAM_UNSUPPORTED: Bad SAM flags in obtain_sam_padata +@end enumerate + +@node Kerberos V5 Database Library Error Codes, Kerberos V5 Magic Numbers Error Codes, Kerberos V5 Library Error Codes, Errors +@appendixsubsec Kerberos V5 Database Library Error Codes + +This is the Kerberos v5 database library error code table. + +@c error table numbering starts at 0 +@enumerate 0 +@item +KRB5_KDB_RCSID: $Id$ +@item +KRB5_KDB_INUSE: Entry already exists in database +@item +KRB5_KDB_UK_SERROR: Database store error +@item +KRB5_KDB_UK_RERROR: Database read error +@item +KRB5_KDB_UNAUTH: Insufficient access to perform requested operation +@item +KRB5_KDB_NOENTRY: No such entry in the database +@item +KRB5_KDB_ILL_WILDCARD: Illegal use of wildcard +@item +KRB5_KDB_DB_INUSE: Database is locked or in use--try again later +@item +KRB5_KDB_DB_CHANGED: Database was modified during read +@item +KRB5_KDB_TRUNCATED_RECORD: Database record is incomplete or corrupted +@item +KRB5_KDB_RECURSIVELOCK: Attempt to lock database twice +@item +KRB5_KDB_NOTLOCKED: Attempt to unlock database when not locked +@item +KRB5_KDB_BADLOCKMODE: Invalid kdb lock mode +@item +KRB5_KDB_DBNOTINITED: Database has not been initialized +@item +KRB5_KDB_DBINITED: Database has already been initialized +@item +KRB5_KDB_ILLDIRECTION: Bad direction for converting keys +@item +KRB5_KDB_NOMASTERKEY: Cannot find master key record in database +@item +KRB5_KDB_BADMASTERKEY: Master key does not match database +@item +KRB5_KDB_INVALIDKEYSIZE: Key size in database is invalid +@item +KRB5_KDB_CANTREAD_STORED: Cannot find/read stored master key +@item +KRB5_KDB_BADSTORED_MKEY: Stored master key is corrupted +@item +KRB5_KDB_CANTLOCK_DB: Insufficient access to lock database +@item +KRB5_KDB_DB_CORRUPT: Database format error +@item +KRB5_KDB_BAD_VERSION: Unsupported version in database entry +@item +KRB5_KDB_BAD_SALTTYPE: Unsupported salt type +@item +KRB5_KDB_BAD_ENCTYPE: Unsupported encryption type +@end enumerate + +@node Kerberos V5 Magic Numbers Error Codes, ASN.1 Error Codes, Kerberos V5 Database Library Error Codes, Errors +@appendixsubsec Kerberos V5 Magic Numbers Error Codes + +This is the Kerberos v5 magic numbers error code table. + +@c error table numbering starts at 0 +@enumerate 0 +@item +KV5M_NONE: Kerberos V5 magic number table +@item +KV5M_PRINCIPAL: Bad magic number for krb5_principal structure +@item +KV5M_DATA: Bad magic number for krb5_data structure +@item +KV5M_KEYBLOCK: Bad magic number for krb5_keyblock structure +@item +KV5M_CHECKSUM: Bad magic number for krb5_checksum structure +@item +KV5M_ENCRYPT_BLOCK: Bad magic number for krb5_encrypt_block structure +@item +KV5M_ENC_DATA: Bad magic number for krb5_enc_data structure +@item +@iftex +KV5M_CRYPTOSYSTEM_ENTRY: Bad magic number for krb5_cryp@-to@-sys@-tem_entry +structure +@end iftex +@ifinfo +KV5M_CRYPTOSYSTEM_ENTRY: Bad magic number for krb5_cryptosystem_entry +structure +@end ifinfo +@item +KV5M_CS_TABLE_ENTRY: Bad magic number for krb5_cs_table_entry structure +@item +@iftex +KV5M_CHECKSUM_ENTRY: Bad magic number for krb5_check@-sum_en@-try structure +@end iftex +@ifinfo +KV5M_CHECKSUM_ENTRY: Bad magic number for krb5_checksum_entry structure +@end ifinfo +@item +KV5M_AUTHDATA: Bad magic number for krb5_authdata structure +@item +KV5M_TRANSITED: Bad magic number for krb5_transited structure +@item +KV5M_ENC_TKT_PART: Bad magic number for krb5_enc_tkt_part structure +@item +KV5M_TICKET: Bad magic number for krb5_ticket structure +@item +KV5M_AUTHENTICATOR: Bad magic number for krb5_authenticator structure +@item +KV5M_TKT_AUTHENT: Bad magic number for krb5_tkt_authent structure +@item +KV5M_CREDS: Bad magic number for krb5_creds structure +@item +KV5M_LAST_REQ_ENTRY: Bad magic number for krb5_last_req_entry structure +@item +KV5M_PA_DATA: Bad magic number for krb5_pa_data structure +@item +KV5M_KDC_REQ: Bad magic number for krb5_kdc_req structure +@item +KV5M_ENC_KDC_REP_PART: Bad magic number for @* +krb5_enc_kdc_rep_part structure +@item +KV5M_KDC_REP: Bad magic number for krb5_kdc_rep structure +@item +KV5M_ERROR: Bad magic number for krb5_error structure +@item +KV5M_AP_REQ: Bad magic number for krb5_ap_req structure +@item +KV5M_AP_REP: Bad magic number for krb5_ap_rep structure +@item +KV5M_AP_REP_ENC_PART: Bad magic number for @* +krb5_ap_rep_enc_part structure +@item +KV5M_RESPONSE: Bad magic number for krb5_response structure +@item +KV5M_SAFE: Bad magic number for krb5_safe structure +@item +KV5M_PRIV: Bad magic number for krb5_priv structure +@item +KV5M_PRIV_ENC_PART: Bad magic number for krb5_priv_enc_part structure +@item +KV5M_CRED: Bad magic number for krb5_cred structure +@item +KV5M_CRED_INFO: Bad magic number for krb5_cred_info structure +@item +KV5M_CRED_ENC_PART: Bad magic number for krb5_cred_enc_part structure +@item +KV5M_PWD_DATA: Bad magic number for krb5_pwd_data structure +@item +KV5M_ADDRESS: Bad magic number for krb5_address structure +@item +KV5M_KEYTAB_ENTRY: Bad magic number for krb5_keytab_entry structure +@item +KV5M_CONTEXT: Bad magic number for krb5_context structure +@item +KV5M_OS_CONTEXT: Bad magic number for krb5_os_context structure +@item +KV5M_ALT_METHOD: Bad magic number for krb5_alt_method structure +@item +KV5M_ETYPE_INFO_ENTRY: Bad magic number for @* +krb5_etype_info_entry structure +@item +KV5M_DB_CONTEXT: Bad magic number for krb5_db_context structure +@item +KV5M_AUTH_CONTEXT: Bad magic number for krb5_auth_context structure +@item +KV5M_KEYTAB: Bad magic number for krb5_keytab structure +@item +KV5M_RCACHE: Bad magic number for krb5_rcache structure +@item +KV5M_CCACHE: Bad magic number for krb5_ccache structure +@item +KV5M_PREAUTH_OPS: Bad magic number for krb5_preauth_ops +@item +KV5M_SAM_CHALLENGE: Bad magic number for krb5_sam_challenge +@item +KV5M_SAM_KEY: Bad magic number for krb5_sam_key +@item +KV5M_ENC_SAM_RESPONSE_ENC: Bad magic number for @* +krb5_enc_sam_response_enc +@item +KV5M_SAM_RESPONSE: Bad magic number for krb5_sam_response +@item +KV5M_PREDICTED_SAM_RESPONSE: Bad magic number for +krb5_predicted_sam_response +@item +KV5M_PASSWD_PHRASE_ELEMENT: Bad magic number for passwd_phrase_element +@end enumerate + +@node ASN.1 Error Codes, GSSAPI Error Codes, Kerberos V5 Magic Numbers Error Codes, Errors +@appendixsubsec ASN.1 Error Codes + +@c error table numbering starts at 0 +@enumerate 0 +@item +ASN1_BAD_TIMEFORMAT: ASN.1 failed call to system time library +@item +ASN1_MISSING_FIELD: ASN.1 structure is missing a required field +@item +ASN1_MISPLACED_FIELD: ASN.1 unexpected field number +@item +ASN1_TYPE_MISMATCH: ASN.1 type numbers are inconsistent +@item +ASN1_OVERFLOW: ASN.1 value too large +@item +ASN1_OVERRUN: ASN.1 encoding ended unexpectedly +@item +ASN1_BAD_ID: ASN.1 identifier doesn't match expected value +@item +ASN1_BAD_LENGTH: ASN.1 length doesn't match expected value +@item +ASN1_BAD_FORMAT: ASN.1 badly-formatted encoding +@item +ASN1_PARSE_ERROR: ASN.1 parse error +@end enumerate + +@node GSSAPI Error Codes, , ASN.1 Error Codes, Errors +@appendixsubsec GSSAPI Error Codes + +Generic GSSAPI Errors: + +@c error table numbering starts at 0 +@enumerate 0 +@item +G_BAD_SERVICE_NAME: No @ in SERVICE-NAME name string +@item +G_BAD_STRING_UID: STRING-UID-NAME contains nondigits +@item +G_NOUSER: UID does not resolve to username +@item +G_VALIDATE_FAILED: Validation error +@item +G_BUFFER_ALLOC: Couldn't allocate gss_buffer_t data +@item +G_BAD_MSG_CTX: Message context invalid +@item +G_WRONG_SIZE: Buffer is the wrong size +@item +G_BAD_USAGE: Credential usage type is unknown +@item +G_UNKNOWN_QOP: Unknown quality of protection specified +@item +G_BAD_HOSTNAME: Hostname in SERVICE-NAME string could not be +canonicalized +@end enumerate + +Kerberos 5 GSSAPI Errors: + +@c error table numbering starts at 0 +@enumerate 0 +@item +KG_CCACHE_NOMATCH: Principal in credential cache does not match desired +name +@item +KG_KEYTAB_NOMATCH: No principal in keytab matches desired name +@item +KG_TGT_MISSING: Credential cache has no TGT +@item +KG_NO_SUBKEY: Authenticator has no subkey +@item +KG_CONTEXT_ESTABLISHED: Context is already fully established +@item +KG_BAD_SIGN_TYPE: Unknown signature type in token +@item +KG_BAD_LENGTH: Invalid field length in token +@item +KG_CTX_INCOMPLETE: Attempt to use incomplete security context +@item +KG_CONTEXT: Bad magic number for krb5_gss_ctx_id_t +@item +KG_CRED: Bad magic number for krb5_gss_cred_id_t +@item +KG_ENC_DESC: Bad magic number for krb5_gss_enc_desc +@end enumerate + +@node kadmin Time Zones, , Errors, Appendix +@appendixsec kadmin Time Zones + +This is a complete listing of the time zones recognized by the +@code{kadmin} command. + +@table @b +@itemx gmt +Greenwich Mean Time +@itemx ut, utc +Universal Time (Coordinated). +@itemx wet +Western European Time. (Same as GMT.) +@itemx bst +British Summer Time. (1 hour ahead of GMT.) +@itemx wat +West Africa Time. (1 hour behind GMT.) +@itemx at +Azores Time. (2 hours behind GMT.) +@itemx bst +Brazil Standard Time. (3 hours behind GMT.) Note that the abbreviation +BST also stands for British Summer Time. +@itemx gst +Greenland Standard Time. (3 hours behind GMT.) Note that the +abbreviation GST also stands for Guam Standard Time. +@itemx nft +Newfoundland Time. (3.5 hours behind GMT.) +@itemx nst +Newfoundland Standard Time. (3.5 hours behind GMT.) +@itemx ndt +Newfoundland Daylight Time. (2.5 hours behind GMT.) +@itemx ast +Atlantic Standard Time. (4 hours behind GMT.) +@itemx adt +Atlantic Daylight Time. (3 hours behind GMT.) +@itemx est +Eastern Standard Time. (5 hours behind GMT.) +@itemx edt +Eastern Daylight Time. (4 hours behind GMT.) +@itemx cst +Central Standard Time. (6 hours behind GMT.) +@itemx cdt +Central Daylight Time. (5 hours behind GMT.) +@itemx mst +Mountain Standard Time. (7 hours behind GMT.) +@itemx mdt +Mountain Daylight Time. (6 hours behind GMT.) +@itemx pst +Pacific Standard Time. (8 hours behind GMT.) +@itemx pdt +Pacific Daylight Time. (7 hours behind GMT.) +@itemx yst +Yukon Standard Time. (9 hours behind GMT.) +@itemx ydt +Yukon Daylight Time. (8 hours behind GMT.) +@itemx hst +Hawaii Standard Time. (10 hours behind GMT.) +@itemx hdt +Hawaii Daylight Time. (9 hours behind GMT.) +@itemx cat +Central Alaska Time. (10 hours behind GMT.) +@itemx ahst +Alaska-Hawaii Standard Time. (10 hours behind GMT.) +@itemx nt +Nome Time. (11 hours behind GMT.) +@itemx idlw +International Date Line West Time. (12 hours behind GMT.) +@itemx cet +Central European Time. (1 hour ahead of GMT.) +@itemx met +Middle European Time. (1 hour ahead of GMT.) +@itemx mewt +Middle European Winter Time. (1 hour ahead of GMT.) +@itemx mest +Middle European Summer Time. (2 hours ahead of GMT.) +@itemx swt +Swedish Winter Time. (1 hour ahead of GMT.) +@itemx sst +Swedish Summer Time. (1 hours ahead of GMT.) +@itemx fwt +French Winter Time. (1 hour ahead of GMT.) +@itemx fst +French Summer Time. (2 hours ahead of GMT.) +@itemx eet +Eastern Europe Time; Russia Zone 1. (2 hours ahead of GMT.) +@itemx bt +Baghdad Time; Russia Zone 2. (3 hours ahead of GMT.) +@itemx it +Iran Time. (3.5 hours ahead of GMT.) +@itemx zp4 +Russia Zone 3. (4 hours ahead of GMT.) +@itemx zp5 +Russia Zone 4. (5 hours ahead of GMT.) +@itemx ist +Indian Standard Time. (5.5 hours ahead of GMT.) +@itemx zp6 +Russia Zone 5. (6 hours ahead of GMT.) +@itemx nst +North Sumatra Time. (6.5 hours ahead of GMT.) Note that the +abbreviation NST is also used for Newfoundland Stanard Time. +@itemx sst +South Sumatra Time; Russia Zone 6. (7 hours ahead of GMT.) Note that +SST is also Swedish Summer Time. +@itemx wast +West Australian Standard Time. (7 hours ahead of GMT.) +@itemx wadt +West Australian Daylight Time. (8 hours ahead of GMT.) +@itemx jt +Java Time. (7.5 hours ahead of GMT.) +@itemx cct +China Coast Time; Russia Zone 7. (8 hours ahead of GMT.) +@itemx jst +Japan Standard time; Russia Zone 8. (9 hours ahead of GMT.) +@itemx kst +Korean Standard Time. (9 hours ahead of GMT.) +@itemx cast +Central Australian Standard Time. (9.5 hours ahead of GMT.) +@itemx cadt +Central Australian Daylight Time. (10.5 hours ahead of GMT.) +@itemx east +Eastern Australian Standard Time. (10 hours ahead of GMT.) +@itemx eadt +Eastern Australian Daylight Time. (11 hours ahead of GMT.) +@itemx gst +Guam Standard Time; Russia Zone 9. (10 hours ahead of GMT.) +@itemx kdt +Korean Daylight Time. (10 hours ahead of GMT.) +@itemx nzt +New Zealand Time. (12 hours ahead of GMT.) +@itemx nzst +New Zealand Standard Time. (12 hours ahead of GMT.) +@itemx nzdt +New Zealand Daylight Time. (13 hours ahead of GMT.) +@itemx idle +International Date Line East. (12 hours ahead of GMT.) +@end table + +@contents +@bye diff --git a/doc/build.texinfo b/doc/build.texinfo new file mode 100644 index 000000000..f20ee91e5 --- /dev/null +++ b/doc/build.texinfo @@ -0,0 +1,323 @@ +\input texinfo @c -*-texinfo-*- +@c +@c NOTE: add /bin/login and xdm to client machine section +@c +@c Note: the above texinfo file must include the "doubleleftarrow" +@c definitions added by jcb. +@c %**start of header +@c guide +@setfilename Kerberos-Build.info +@settitle Guide to Building Kerberos +@c @setchapternewpage odd @c chapter begins on next odd page +@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 0.1 alpha + +@c @finalout @c don't print black warning boxes + +@titlepage +@title Guide to Building @value{PRODUCT} +@subtitle Release: @value{RELEASE} +@subtitle Document Edition: @value{EDITION} +@subtitle Last updated: @value{UPDATED} +@author @value{COMPANY} + +@page +@vskip 0pt plus 1filll + +@include copyright.texinfo +@end titlepage + +@node Top, Top, (dir), (dir) +@comment node-name, next, previous, up + +@ifinfo +This file describes how to build @value{PRODUCT}, and how to build +software using the @value{PRODUCT} libraries. + +@include copyright.texinfo +@end ifinfo + +@menu +* Compiling @value{PRODUCT}:: +@end menu + +@node Top, Compiling @value{PRODUCT}, (dir), (dir) +@top Guide to Building @value{PRODUCT} + +@menu +* Compiling @value{PRODUCT}:: +@end menu +@end ifinfo + +@node Compiling @value{PRODUCT}, , Top, Top +@chapter Compiling @value{PRODUCT} + +@value{PRODUCT} is supplied in source form for a number of reasons: +@itemize @bullet +@item You can examine the source yourself, and verify the behavior of +the system to your satisfaction. This is especially important with +security software. +@item You can make your own changes (of course, we recommend having us +make the changes, so that we can support them in the future.) +@end itemize + +@value{PRODUCT} is a large package. In order to efficiently manage sources across a +large number of platforms, we've used certain tools that you may be +unfamilar with, and we explain them here. + +@menu +* Requirements:: Requirements +* Setup:: Setting Up the files +* Testing:: Testing the release +* Constructing an Install Kit:: Constructing a tar file or package +@end menu + +@node Requirements, Setup, Compiling @value{PRODUCT}, Compiling @value{PRODUCT} +@section Requirements + +At the very minimum, you need a Unix-like operating system with a C +compiler. (The MacOS and Windows ports are not discussed here.) While an +ANSI C compiler is preferred, mostly because it is likely to be a more +recent compiler, the build process checks for particular features and +works around them in most cases. We of course recommend gcc, but we test +the compilation with both gcc and the "native" or OS-vendor supplied +compiler whenever possible. + +You also need a version of @code{make}. We recommend GNU make, but +again, we test with the vendor-supplied one as well. Most native +implementations of make are sufficient to build @value{PRODUCT} directly in the +source tree. Having a seperate build tree is far more convenient, and is +what we recommend; this usually needs GNU make because of the variation +in support of @samp{VPATH}. + +If you're only going to compile the unchanged source, or are only going +to change C files, you should be set. If you're going to change some +part of the build process (any of the @file{Makefile}s -- more specifically, +any of the @file{configure.in} or @file{Makefile.in} files that generate +them) you're +going to need a recent version of GNU m4. + +@node Setup, Testing, Requirements, Compiling @value{PRODUCT} +@section Setup + +We recommend a directory structure as follows: +@table @file +@item krb5 +is the source tree itself. +@item src +is a symlink farm pointing into the source tree. +@item @var{platform} +is a directory for a particular build platform. It may be more +convenient for you to name these by hostname, but if you're keeping the +trees around for any length of time it is better to label them by vendor +and version. +@end table + +Given the above structure, unpack the tar file of sources. + +If you don't have GNU m4, or are not planning to change anything, +simply +@example + mv krb5 src +@end example + +If you are likely to be changing build-related information, then the +procedure +@example + % mkdir src + % cd src + % ../krb5/util/lndir ../krb5 +@end example +@noindent will produce the symlink farm, then +@example + % rm Makefile + % cd util/autoconf + % ./configure + % make + % cd ../.. + % util/reconf + % cd .. +@end example +The reconf step will take a while, as it regenerates the build +scripts. If you change @file{aclocal.m4}, @file{Makefile.in}, or +@file{configure.in}, you can +rerun @file{util/reconf} (causing it to rebuild only those things that +need to.) If you're just making changes to a @file{Makefile.in} or +@file{configure.in} +in one directory, the make rules will take care of rerunning @file{autoconf} to +rebuild them directly. + +In order to build a particular platform, simply +@example + % mkdir platform + % cd platform + % ../src/configure --@var{configure options} + % make all @{@var{MAKE OPTIONS}@} + % make check + % make install +@end example + +If @samp{cc} isn't a working compiler (stock Solaris, for example) you should +also do a +@example + setenv CC gcc +@end example +before running configure. + +@menu +* Make Options:: +* Configure Options:: +@end menu + +@node Make Options, Configure Options, Setup, Setup +@subsection Make Options + +@var{MAKE OPTIONS} include +@itemize @bullet +@item @code{CC=@var{compiler}} +@item @code{CCOPTS=@var{compiler flags}} +@end itemize +which get automatically propagated to all subdirectories. + + +@node Configure Options, , Make Options, Setup +@subsection Configure Options + +@var{configure options} include +@table @code +@item --with-dbm + Use native @code{dbm} for the key database. +@item --without-dbm + Use included version of Berkeley @code{db}. This is the default, but +not yet recommended. In a future release, after @code{db} is more +thoroughly tested, a conversion tool will be supplied. +@item --with-dbm-lname + Use native @code{dbm} for @code{aname} to @code{lname} conversion +database. This optional database is most useful when users have +principals in multiple realms that have common access. +@item --without-dbm-lname + Use included version of Berkeley @code{db}. This is the default, but +not yet recommended. In a future release, after @code{db} is more +thoroughly tested, a conversion tool will be supplied. +@item --enable-athena + If V4 compatibility is also enabled (the default), construct +@code{kadmin.v4}, the @value{PRODUCT} V4 compatible Kerberos +Administration Server, and @code{krb524}, the conversion tools to allow +users to generate V4 tickets from V5 tickets. For further details, see +the @ref{@value{PRODUCT} V4 Compatibility,,@value{PRODUCT} V4 Backward +Compatibility Support,@value{PRODUCT}-inst-man,Cygnus Network Security +-- Version 5}. + +It also causes @code{KRB5_ATHENA_COMPAT} to be defined, which may have affects +in future releases, but is currently unused. + +@item --prefix @var{pathname} + Specify that the installed tree be rooted at @var{pathname}. The MIT +default is to use @file{/krb5} but +@item --without-krb4 + Don't include any Kerberos V4 backwards compatibility support in +applications, and don't build the V4 libraries either. +@item --with-krb4 + @value{PRODUCT} V4 libraries (enhanced for compatibility use) are included as part of +the @value{PRODUCT} V5 source tree. By default, or with this option, these are built +and installed in @file{libkrb4.a} and are used in various utilities. +@item --with-krb4=@var{KRB4DIR} + Enable V4 backwards compatibility support, but use existing Kerberos +libraries as preinstalled in @var{KRB4DIR}. Generally not used now that +the V4 libraries are included. +@item --with-cc=@var{COMPILER} + Select compiler to use, and write it into the constructed +@code{Makefile}s as the default value of @code{CC}. +@item --with-linker=@var{LINKER} + Select linker to use, and write it into the constructed +@code{Makefile}s as the default value of @code{LD}. Useful for building +with Purify. +@item --with-ccopts=@var{CCOPTS} + Select compiler command line options, and write it into the constructed +@code{Makefile}s as the default value of @code{CCOPTS}. Useful for +building with debugging or optimization. +@item --with-cppopts=@var{CPPOPTS} + Select compiler preprocessor command line options, and write it into +the constructed @code{Makefile}s as the default value of +@code{CPPOPTS}. Useful for setting flags. +@item --with-netlib=@var{libs} + Use user defined resolve library. Normally the resolver is part of the +C library, but on SunOS systems using NIS, you may need to specify +@code{-lresolv} in order to get a proper domain name resolver. +@item --enable-shared + Construct @value{PRODUCT} V5 shared libraries. Not supported on all systems. +@item --with-shared + Use constructed shared (default) libraries. +@item --without-shared + Don't use any shared libraries when building @value{PRODUCT}. +@item --without-afs + The default, indicating that you don't have afs libraries to build +with and therefore can't to build @code{asetkey}, @code{aklog}, and +@code{kascvt}. +@item --with-afs=@var{AFSDIR} + Use preinstalled AFS library tree located under @var{AFSDIR} to build +the TransArc AFS support and conversion tools. These require V4 +compatibility to operate, and work in conjunction with @code{krb524d}. +@item --enable-telnet-encryption + Use non-standard encryption in telnet. The telnet implementation +provides for the use of DES in a stream mode to encrypt the connection, +but there are some user interface issues that may make it less +safe. Always verify using @kbd{^[ enc status RET} that it was +successful, rather than trusting the message which may have been +inserted by an attacker. For this and other reasons, the encryption mode +is not an Internet Standard as of October 1995, but work is expected in +the coming year to change that. +@item --disable-telnet-encryption + Don't enable the non-standard telnet encryption mode described above. +@end table + +@node Testing, Constructing an Install Kit, Setup, Compiling @value{PRODUCT} +@section Testing + +After running @code{make all} successfully, you should run the +collection of built in test cases. Running @code{make check} will run a +number of built in tests of +@itemize @bullet +@item +raw database code +@item +raw encryption code +@item +various Kerberos V5 interfaces including @code{kdb5} +@end itemize + +If you have @code{runtest} from the DejaGnu package +@footnote{@code{prep.ai.mit.edu:/pub/gnu/dejagnu-1.2.tar.gz} as of this +writing} installed, this will also run a set of live application tests, +creating a test realm, starting a Kerberos server, @code{kadmind}, and +clients, and testing their features the way a human would use them. The +end summary should list no unexpected failures. + +If you do find problems, you can get more specific detail by changing to +the @file{tests/dejagnu} directory and running @code{runtest} with the +@samp{-d} option, and examining the @file{dbg.log} file produced. (This +will not be necessary with any platform supported by @value{COMPANY}.) + +@node Constructing an Install Kit, , Testing, Compiling @value{PRODUCT} +@section Constructing an Install Kit + +Currently install kits are constructed by creating an install directory +and running @code{make install DESTDIR=@var{install directory}}, then +using @samp{tar cf} to produce a tar file. In the future, there will be +direct make targets to support construction of @code{tar} files and +@sc{svr4} packages. + +@contents +@c second page break makes sure right-left page alignment works right +@c with a one-page toc, even though we don't have setchapternewpage odd. +@c end of texinfo file +@bye diff --git a/doc/copyright.texinfo b/doc/copyright.texinfo new file mode 100644 index 000000000..83ab0e798 --- /dev/null +++ b/doc/copyright.texinfo @@ -0,0 +1,91 @@ +Copyright @copyright{} 1993, 1994, 1995, 1996 @value{COMPANY}. +@iftex +@vskip 12pt +@hrule +@vskip 12pt +@end iftex + +@value{PRODUCT} includes documentation and software developed at the +Massachusetts Institute of Technology, which includes this copyright +information: + +Copyright @copyright{} 1995 by the Massachusetts Institute of Technology. + +@quotation +Export of software employing encryption from the United States of +America is assumed to require a specific license from the United States +Government. It is the responsibility of any person or organization +contemplating export to obtain such a license before exporting. +@end quotation + +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. + +@iftex +@vskip 12pt +@hrule +@vskip 12pt +@end iftex + +@value{PRODUCT} includes documentation and software developed at the +University of California at Berkeley, which includes this copyright +notice: + +Copyright @copyright{} 1983 Regents of the University of California.@* +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: +@enumerate +@item +Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. +@item +Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the +documentation and/or other materials provided with the distribution. +@item +All advertising materials mentioning features or use of this software +must display the following acknowledgement: +@quotation +This product includes software developed by the University of +California, Berkeley and its contributors. +@end quotation +@item +Neither the name of the University nor the names of its contributors +may be used to endorse or promote products derived from this software +without specific prior written permission. +@end enumerate + +@iftex +@vskip 12pt +@hrule +@vskip 12pt +@end iftex + +Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notices and this permission notice are +preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. diff --git a/doc/cyg-install.texinfo b/doc/cyg-install.texinfo new file mode 100644 index 000000000..60532eb04 --- /dev/null +++ b/doc/cyg-install.texinfo @@ -0,0 +1,1644 @@ +\input texinfo @c -*-texinfo-*- +@c +@c NOTE: add /bin/login and xdm to client machine section +@c +@c Note: the above texinfo file must include the "doubleleftarrow" +@c definitions added by jcb. +@c %**start of header +@c guide +@setfilename KerbNet-Install.info +@settitle Kerb*Net 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 0.91 beta + +@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 + +@include copyright.texinfo +@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:: +* Installing @value{PRODUCT}:: +* Support:: +* Files:: +@end menu + +@node Introduction, Realm Configuration Decisions, Top, Top +@chapter Introduction + +Congratulations on your purchase of @value{PRODUCT}. @value{COMPANY} +believes @value{PRODUCT} provides the best network security available. +Please let us know if we can be of assistance in getting your +installation of @value{PRODUCT} set up and running. + +@menu +* What is Kerberos and How Does it Work?:: +* Why Should I use Kerberos?:: +* @value{PRODUCT} Documentation:: +* 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?, @value{PRODUCT} 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. + +@node @value{PRODUCT} Documentation, Please Read the Documentation, Why Should I use Kerberos?, Introduction +@section @value{PRODUCT} Documentation + +This document is one piece of the document set for @value{PRODUCT}. The +documents, and their intended audiences, are: + +@include document-list.texinfo + +@node Please Read the Documentation, Overview of This Guide, @value{PRODUCT} Documentation, 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, Installing @value{PRODUCT}, 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{PRIMARYDOMAIN} would be in the +Kerberos realm @value{PRIMARYREALM}. + +If you need multiple Kerberos realms, @value{COMPANY} recommends that +you use descriptive names which end with your domain name, such as +BOSTON.@value{PRIMARYREALM} and SAN_FRANCISCO.@value{PRIMARYREALM}. + +@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 Installing @value{PRODUCT}, Support, Realm Configuration Decisions, 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:: +* Installing and Configuring Windows Client Machines:: +* Installing and Configuring Macintosh Client Machines:: +* UNIX Application Servers:: +@end menu + +@node Installing KDCs, Installing and Configuring UNIX Client Machines, Installing @value{PRODUCT}, Installing @value{PRODUCT} +@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 +* Unpack the tar file:: +* 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 Unpack the tar file, Edit the Configuration Files, Install the Master KDC, Install the Master KDC +@subsubsection Unpack the tar file + +Unpack the tar file on each KDC. Because of some specifications that +are compiled into the software, you must install @value{PRODUCT} in the +directory @code{@value{INSTALLDIR}}. If you extract the tar file from +the top-level directory (@code{/}), the files will end up in this +directory. Installation into other locations is not supported in this +release, but is planned for future releases. + +@value{COMPANY} recommends that you choose a persistent directory name, +and make it a symbolic link to @code{@value{INSTALLDIR}}, so +you can install updates later without requiring users to change their +paths. This document will refer to @code{@value{ROOTDIR}} as the +persistent directory name. + +@node Edit the Configuration Files, Create the Database, Unpack the tar file, 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 ``CSiys4K5!'', +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 +* Copy the Software onto the Slave KDCs:: +* Create Host Keys for the Slave KDCs:: +* Extract Host Keytabs for the KDCs:: +* Set Up the Slave KDCs for Database Propagation:: +@end menu + +@node Copy the Software onto the Slave KDCs, Create Host Keys for the Slave KDCs, Install the Slave KDCs, Install the Slave KDCs +@subsubsection Copy the Software onto the Slave KDCs + +Unpack the tar file on each slave KDC as you did on the master. Once +again, note that you must install @value{PRODUCT} in the directory +@code{@value{INSTALLDIR}}. If you extract the tar file from the +top-level directory (@code{/}), the files will end up in this directory. +As with the master KDC, make the symbolic link to +@code{@value{INSTALLDIR}} with the persistent name you chose earlier. +Once you have unpacked the tar file, replace the configuration files, +@code{krb5.conf} (@pxref{krb5.conf}) and @code{kdc.conf} +(@pxref{kdc.conf}) with those you edited on the master KDC. + +@node Create Host Keys for the Slave KDCs, Extract Host Keytabs for the KDCs, Copy the Software onto 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: +# <service_name> <socket_type> <proto> <flags> <user> +@result{} <server_pathname> <args> +# +# Syntax for TLI-based Internet services: +# +# <service_name> tli <proto> <flags> <user> <server_pathname> <args> +# +# 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, Installing and Configuring Windows Client Machines, Installing KDCs, Installing @value{PRODUCT} +@section Installing and Configuring UNIX Client Machines + +Client machine installation is much more straightforward than +installation of the KDCs. + +@menu +* Unpack the tar File:: +* Client Programs:: +* Client Machine Configuration Files:: +@end menu + +@node Unpack the tar File, Client Programs, Installing and Configuring UNIX Client Machines, Installing and Configuring UNIX Client Machines +@subsection Unpack the tar File + +Install @value{PRODUCT} in @code{@value{ROOTDIR}}. If you extract the +tar file from the top level directory (@code{/}), the files will end up +in this directory. + +@node Client Programs, Client Machine Configuration Files, Unpack the tar File, 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{xdm}, +@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} and @code{xdm}, +which are 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}, and +@value{PRODUCT} @code{xdm} in place of @code{/bin/login} and ordinary +@code{xdm}, 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}. + +@menu +* Configuring the X Display Manager (Xdm):: +* Additional Xdm Configuration for AIX Machines:: +@end menu + +@node Configuring the X Display Manager (Xdm), Additional Xdm Configuration for AIX Machines, Client Programs, Client Programs +@subsubsection Configuring the X Display Manager (Xdm) + +You will need to edit the @code{xdm} configuration files slightly, based +on your installation. The files are in the directory +@code{@value{ROOTDIR}/lib/X11/xdm}. You will need to add a line of the +following form to the file @code{Xservers} in that directory: + +@smallexample +:0 local /usr/bin/X11/X :0 +@end smallexample + +@noindent +Replace @code{/usr/bin/X11/X} with the path to your X server, and +@samp{:0} with the actual display name, if different. + +If you will be having @code{xdm} manage multiple displays, you will need +to add lines to the @code{xdm-config} file for those displays. The +following lines are shipped in the file, for display @samp{:0}: + +@smallexample +@group +DisplayManager._0.authorize: true +DisplayManager._0.setup: @value{ROOTDIR}/lib/X11/xdm/Xsetup_0 +DisplayManager._0.startup: @value{ROOTDIR}/lib/X11/xdm/GiveConsole +DisplayManager._0.reset: @value{ROOTDIR}/lib/X11/xdm/TakeConsole +@end group +@end smallexample + +The @samp{_0} in these lines translates to display @samp{:0}. Add +equivalent lines for other displays. Replace the @samp{_0} with the +other display names, substituting underscores (@samp{_}) for the +@samp{:} and @samp{.} characters. + +@node Additional Xdm Configuration for AIX Machines, , Configuring the X Display Manager (Xdm), Client Programs +@subsubsection Additional Xdm Configuration for AIX Machines + +If you have machines running AIX, you will need to do some additional +configuration. Also note that under AIX, multiple non-network logins +(on the console or via a serial port) will all use the same ticket file. + +For AIX, the line in the @code{Xservers} file described above needs the +@code{-force} option, as in the following example: + +@smallexample +:0 local /usr/lpp/X11/bin/X -force :0 +@end smallexample + +@noindent +Again, replace @code{/usr/lpp/X11/bin/X} with the correct path for your +X server, and @samp{:0} with the actual display name, if different. + +Also, you need to make the following changes to files in the directory +@code{/etc/security}. + +In the file @code{login.cfg}, you need to add the following lines under +the ``Authentication methods'' section + +@smallexample +@group +@value{CPRODUCT}: + program = @value{ROOTDIR}/sbin/login-auth +@end group +@end smallexample + +In the file @code{/etc/security/user}, add the following lines, under +the @samp{default:} heading: + +@smallexample +@group +auth1 = @value{CPRODUCT} +auth2 = none +SYSTEM = NONE +@end group +@end smallexample + +@noindent +You can comment out any previous values for @code{auth1}, @code{auth2}, +and @code{SYSTEM} using the @samp{*} character. + +Additionally, assuming you want to allow root to log in to the machine +locally (instead of using Kerberos), you also need to add the following +lines to the @samp{root:} section of @code{/etc/security/user}: + +@smallexample +@group +auth1 = SYSTEM +SYSTEM = "compat" +@end group +@end smallexample + +@noindent +You will also need to do the same for any other user who needs to log in +locally. + +Note that if Kerberos authentication succeeds, but the native login +program is unable to log the user in (@i{e.g.}, if it can't find the +user's shell), the ticket file may not be destroyed. + +You may also want to edit the @code{/etc/environment} and/or +@code{/etc/TIMEZONE} files to get any desired variables into the user's +environment. + +Finally, because the AIX login program does not destroy tickets +automatically upon completion, users need to put the @code{kdestroy} +command in their @code{.logout} files. + +@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 Installing and Configuring Windows Client Machines, Installing and Configuring Macintosh Client Machines, Installing and Configuring UNIX Client Machines, Installing @value{PRODUCT} +@section Installing and Configuring Windows Client Machines + +@value{PRODUCT} for Windows includes a GUI ticket management program +(called @code{@value{CPRODUCT}}), a GUI telnet program, and a +command-line telnet program that runs from within the @samp{Command +Prompt}. The command-line program is included because encryption and +ticket forwarding are not available for the GUI program in this release. +The GUI programs are available for Windows 3.1, Windows95, and Windows +NT. The command-line program is available only for Windows95 and +Windows NT. + +@menu +* Install the Executables:: +* Install the @code{krb5.conf} file:: +* Install an @code{\etc\passwd} file:: +* Check the Clock and Time Zone:: +* Create the Directory @code{\tmp}:: +* Set the Ticket File Location:: +@end menu + +@node Install the Executables, Install the @code{krb5.conf} file, Installing and Configuring Windows Client Machines, Installing and Configuring Windows Client Machines +@subsection Install the Executables + +To install the ticket management program and the GUI telnet program, +simply run the @code{setup} program and answer the questions. To +install the command-line telnet program, copy the @code{telnet.exe} and +@code{cygwin.dll} programs into the directory of your choice. + +@node Install the @code{krb5.conf} file, Install an @code{\etc\passwd} file, Install the Executables, Installing and Configuring Windows Client Machines +@subsection Install the @code{krb5.conf} file + +Install the same @code{krb5.conf} file (@xref{krb5.conf}) you use on +your UNIX client machines. The GUI programs will accept any path and +filename for the configuration file; however, the command-line telnet +program requires that the file be @code{\etc\krb5.conf}. Once you have +installed the file, run the @code{@value{CPRODUCT}} program and enter +the path and filename into the @samp{Configuration File} box under the +@samp{Options} menu (under @samp{File}). + +@node Install an @code{\etc\passwd} file, Check the Clock and Time Zone, Install the @code{krb5.conf} file, Installing and Configuring Windows Client Machines +@subsection Install an @code{\etc\passwd} file + +@need 1100 +For the command-line telnet program, you need to install an +@code{\etc\passwd} file containing the usernames of the users who will +be running the program. Each username must on its own line, with a +colon at the end, as in the following example: + +@smallexample +@group +@value{RANDOMUSER1}: +@value{RANDOMUSER2}: +cbrown: +@end group +@end smallexample + +@node Check the Clock and Time Zone, Create the Directory @code{\tmp}, Install an @code{\etc\passwd} file, Installing and Configuring Windows Client Machines +@subsection Check the Clock and Time Zone + +Make sure the clock and time zone are set correctly, and that the time +is within the maximum clock skew of the KDC. The default maximum clock +skew is five minutes. + +@node Create the Directory @code{\tmp}, Set the Ticket File Location, Check the Clock and Time Zone, Installing and Configuring Windows Client Machines +@subsection Create the Directory @code{\tmp} + +If you are using the command-line telnet program, make sure the +directory @code{\tmp} exists, since this is where it needs the default +ticket files need to be stored. + +@node Set the Ticket File Location, , Create the Directory @code{\tmp}, Installing and Configuring Windows Client Machines +@subsection Set the Ticket File Location + +From the @code{@value{CPRODUCT}} program, enter the path and filename +for the ticket file location into the @samp{Credentials Cache Location} +box under the @samp{Options} menu. Again, the GUI programs will accept +any path and filename; however, the command-line telnet program requires +that this be @code{\tmp\krb5cc_0}. + +@node Installing and Configuring Macintosh Client Machines, UNIX Application Servers, Installing and Configuring Windows Client Machines, Installing @value{PRODUCT} +@section Installing and Configuring Macintosh Client Machines + +@value{PRODUCT} for the Macintosh includes a GUI ticket management program +(called @code{@value{CPRODUCT} config}) and a GUI telnet program. + +@menu +* Unpack the Executables:: +* Set Up your Configuration:: +* Set the Clock and Time Zone:: +@end menu + +@node Unpack the Executables, Set Up your Configuration, Installing and Configuring Macintosh Client Machines, Installing and Configuring Macintosh Client Machines +@subsection Unpack the Executables + +To install the @code{@value{CPRODUCT} config} program and the +@code{telnet} program, simply unpack the archive and answer the +questions. Then move the programs into the folder of your choice. + +@node Set Up your Configuration, Set the Clock and Time Zone, Unpack the Executables, Installing and Configuring Macintosh Client Machines +@subsection Set Up your Configuration + +To set up your configuration, run the @code{@value{CPRODUCT} config} +program and enter the information from your site's @code{krb5.conf} +file. Enter the hostname or IP address and realm for each KDC under the +Server section. If the KDC is an admin server, check the ``Admin +server'' box. Enter any domain/realm mappings in the Domain/Hostname +section. + +@node Set the Clock and Time Zone, , Set Up your Configuration, Installing and Configuring Macintosh Client Machines +@subsection Set the Clock and Time Zone + +Make sure the clock and time zone are set correctly, and that the time +is within the maximum clock skew of the KDC. The default maximum clock +skew is five minutes. + +@node UNIX Application Servers, , Installing and Configuring Macintosh Client Machines, Installing @value{PRODUCT} +@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 Support, Files, Installing @value{PRODUCT}, Top +@chapter Support + +If you have problems installing @value{PRODUCT}, please use the +@code{send-pr} program to fill out a Problem Report. + +@include send-pr.texinfo + +@node Files, , Support, 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/definitions.texinfo b/doc/definitions.texinfo new file mode 100644 index 000000000..25e30cb2b --- /dev/null +++ b/doc/definitions.texinfo @@ -0,0 +1,28 @@ +@set ADMINUSER joeadmin +@set COMPANY Cygnus Support +@set KDCSERVER kerberos +@set KDCSLAVE1 @value{KDCSERVER}-1 +@set KDCSLAVE2 @value{KDCSERVER}-2 +@set PRIMARYDOMAIN mit.edu +@set PRIMARYREALM ATHENA.MIT.EDU +@set PRODUCT Kerberos V5 +@set CPRODUCT Kerberos +@set LCPRODUCT krb5 +@set RANDOMHOST1 daffodil +@set RANDOMHOST1IP 18.72.0.44 +@set RANDOMHOST2 trillium +@set RANDOMHOST2IP 253.46.124.7 +@set RANDOMUSER johndoe +@set RANDOMUSER1 jennifer +@set RANDOMUSER2 david +@set RELEASE beta 7 +@set PREVRELEASE beta 6 +@set INSTALLDIR /usr/@value{LCPRODUCT} +@set PREVINSTALLDIR @value{INSTALLDIR} +@set ROOTDIR /usr/@value{LCPRODUCT} +@set BINDIR @value{ROOTDIR}/bin +@set SECONDDOMAIN fubar.org +@set SECONDREALM FUBAR.ORG +@set UPDATED @today + + diff --git a/doc/document-list.texinfo b/doc/document-list.texinfo new file mode 100644 index 000000000..0c0620dc9 --- /dev/null +++ b/doc/document-list.texinfo @@ -0,0 +1,21 @@ +@itemize @bullet +@item +@b{@value{PRODUCT} Installation Guide}: a concise guide for installing +@value{PRODUCT}. Kerberos administrators (particularly whoever will be +making site-wide decisions about the installation) and the system +administrators who will be installing the software should read this +guide. + +@item +@b{@value{PRODUCT} System Administrator's Guide}: a sysadmin's guide to +administering a Kerberos installation. The System Administrator's Guide +describes the administration software and suggests policies and +procedures for administering a Kerberos installation. Anyone who will +have administrative access to your Kerberos database should read this +guide. + +@item +@b{@value{PRODUCT} UNIX User's Guide}: a guide to using the Kerberos +UNIX client programs. All users on UNIX systems should read this guide, +particularly the ``Tutorial'' section. +@end itemize diff --git a/doc/glossary.texinfo b/doc/glossary.texinfo new file mode 100644 index 000000000..5fbaa634a --- /dev/null +++ b/doc/glossary.texinfo @@ -0,0 +1,63 @@ +@table @b +@item client +an entity that can obtain a ticket. This entity is usually either a +user or a host. + +@item host +a computer that can be accessed over a network. + +@item Kerberos +in Greek mythology, the three-headed dog that guards the entrance to the +underworld. In the computing world, Kerberos is a network security +package that was developed at MIT. + +@item KDC +Key Distribution Center. A machine that issues Kerberos tickets. + +@item keytab +a @b{key tab}le file containing one or more keys. A host or service +uses a @dfn{keytab} file in much the same way as a user uses his/her +password. + +@item principal +a string that names a specific entity to which a set of credentials may +be assigned. It generally has three parts: + +@table @b +@item primary +the first part of a Kerberos @i{principal}. In the case of a user, it +is the username. In the case of a service, it is the name of the +service. + +@item instance +the second part of a Kerberos @i{principal}. It gives information that +qualifies the primary. The instance may be null. In the case of a +user, the instance is often used to describe the intended use of the +corresponding credentials. In the case of a host, the instance is the +fully qualified hostname. + +@item realm +the logical network served by a single Kerberos database and a set of +Key Distribution Centers. By convention, realm names are generally all +uppercase letters, to differentiate the realm from the internet domain. +@end table + +@noindent +The typical format of a typical Kerberos principal is +primary/instance@@REALM. + +@item service +any program or computer you access over a network. Examples of services +include ``host'' (a host, @i{e.g.}, when you use @code{telnet} and +@code{rsh}), ``ftp'' (FTP), ``krbtgt'' (authentication; +cf. @i{ticket-granting ticket}), and ``pop'' (email). + +@item ticket +a temporary set of electronic credentials that verify the identity of a +client for a particular service. + +@item TGT +Ticket-Granting Ticket. A special Kerberos ticket that permits the +client to obtain additional Kerberos tickets within the same Kerberos +realm. +@end table diff --git a/doc/krb425.texinfo b/doc/krb425.texinfo new file mode 100644 index 000000000..0c34315bd --- /dev/null +++ b/doc/krb425.texinfo @@ -0,0 +1,479 @@ +\input texinfo @c -*-texinfo-*- +@c Note: the above texinfo file must include the "doubleleftarrow" +@c definitions added by jcb. +@c %**start of header +@c guide +@setfilename Kerb*Net-Upgrading.info +@settitle Upgrading to Kerb*Net from Kerberos V4 +@c @setchapternewpage odd @c chapter begins on next odd page +@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 0.1 alpha + +@c @finalout @c don't print black warning boxes + +@titlepage +@title Upgrading to @value{PRODUCT} from Kerberos V4 +@subtitle Release: @value{RELEASE} +@subtitle Document Edition: @value{EDITION} +@subtitle Last updated: @value{UPDATED} +@author @value{COMPANY} + +@page + +@vskip 0pt plus 1filll + +@include copyright.texinfo +@end titlepage + + +@node Upgrading to @value{PRODUCT} from Kerberos V4, Installing @value{PRODUCT} at Your Site +@top Upgrading to @value{PRODUCT} from Kerberos V4 + +@ifinfo +This document describes how to convert to @value{PRODUCT} from Kerberos V4. + +@include copyright.texinfo +@end ifinfo + +@menu +* Installing CNS:: Installing CNS at Your Site +@end menu + +@node Installing @value{PRODUCT} at Your Site +@chapter Installing @value{PRODUCT} at Your Site + +@value{COMPANY} developed Cygnus Network Security (CNS) to provide strong +system access security, with minimal impact on users' ease of access. +Using Kerberos Version 5 encryption and client-server technology, CNS +assures that user identities can be checked securely without +transmitting passwords in clear over the Net. CNS is useful in closing +up several large security holes: eavesdroppers recording login names and +passwords as your users log in from remote locations; and active attacks +based on providing a fake TCP/IP source address (IP address spoofing). + +Introducing CNS to an existing site involves more planning and execution +than installing the average software package. CNS software is required +on both ends of the remote login connections, and remote users must +change their habits. + +To install CNS and make it useful, you have to: + +@itemize @bullet +@item +Install and configure the CNS software on the machines at your site. +@item +Set up a CNS Key Distribution Center server machine. +@item +[Optional] Set up one or more slave servers for reliability. +@item +Install and configure CNS client software on the machines from which +your remote users log in. +@item +Add users and their passwords to your CNS server. (If you are converting +from a CNS V4 system or a Transarc AFS "KAserver" system, there are +tools to migrate the user entries and passwords directly.) +@item +Inform your users about CNS. +@item +[Optional] Turn off ordinary @code{rlogin}, @code{telnet}, @code{ftp}, and +@code{rsh} services so that users are @emph{required} to use CNS rather +than potentially exposing their passwords. +@end itemize + +This manual covers only basic installation and configuration of the CNS +software. See the @ref{Top,,Administration Tools,kerbman,Cygnus Network +Security User and Administrator Documentation for CNS Version 5}, manual +for more detailed information. + + +@menu +* What:: Contents of the CNS V5 distribution. +* Where:: Where programs should be installed +* Config Files:: Configuration Files affected +* quick start:: Getting Started from an existing Realm +* AFS enhancements:: Using CNS V5 with AFS +* kprop:: Redundant Slave Servers +* interrealm:: Arranging Interrealm Authentication +* CNS V4 Compatibility:: CNS V4 Backward Compatibility Support +@end menu + +@node What, Where, Installing @value{PRODUCT} at Your Site, Installing @value{PRODUCT} at Your Site +@section Contents of the CNS V5 distribution. + +A collection of programs are included in CNS. The categories are +@itemize @bullet +@item user programs +such as @code{kinit}, @code{klist}, @code{kdestroy}, @code{kpasswd}, +@code{krb524init} +@item replacement programs +such as @code{rlogin}, @code{rcp}, @code{rsh}, @code{telnet}, +@code{ftp}, @code{ksu} +@item demos +such as @code{sim_client}, @code{sclient}, @code{uuclient}, @code{gss-client} +@item administration tools +such as @code{kdb5_anadd}, @code{kdb5_convert}, @code{kdb5_create}, +@code{kdb5_destroy}, @code{kdb5_edit}, +@code{kdb5_stash}, and the client program @code{kadmin5} +@item programming support +such as include files and libraries for writing kerberized +@footnote{The verb @dfn{to kerberize} means to modify (usually an +application) to use Kerberos for authentication and possibly encryption.} +applications. +@item documentation +in the form of man pages. +@item kerberized application servers +such as @code{ftpd}, @code{krlogind}, @code{krshd}, @code{popper}, +@code{telnetd}, @code{sim_server}, @code{sserver}, +@code{uuserver} +@item kerberos management servers +such as @code{kadmind5}, @code{kpropd}, @code{krb524d}, @code{krb5kdc}, +@code{v4kadmind} +@end itemize + +@node Where, Config Files, What, Installing @value{PRODUCT} at Your Site +@section Where programs should be installed + +Cygnus releases unpack in directories named +@file{/usr/cygnus/@var{package}-@var{release}}. It is suggested that a +user-convenience +symlink be placed in @file{/usr/cygnus} pointing from @var{package} to +@var{package}-@var{release}, for example from @file{cns5} to +@file{cns5-95q2}, to simplify +upgrades (a new release can be installed in the new directory, tested +there, and then the symlink can be moved to make the code available by +default to the user community.) + +It should be noted that while the programs simply need to be on +reliable storage (possibly read-only, but protected from network +replacement) the @file{lib/krb5kdc} directory should be local to the security +server and not visible to other machines at all. One approach that +permits sharing is to create a symlink from @file{lib/krb5kdc} to a +local directory, perhaps in @file{/var}. +@example +mkdir /var/krb5kdc +chmod 700 /var/krb5kdc +ln -s /var/krb5kdc /usr/cygnus/cns5/lib/krb5kdc +@end example + +Also, @file{/usr/cygnus/cns5/lib/krb5.conf} is a fallback location for a +common config file -- @file{/etc/krb5.conf} is examined instead if present, and +the user can override by setting the environment variable @samp{KRB5_CONFIG}. +Since @file{/etc} is usually local, if you want to avoid maintaining +@file{krb.conf} files on all machines, one approach is to create a +@file{/usr/cygnus/krb.conf} and make a symlink to it from the release +directory. You still need to remember to recreate the symlink when you +install a new release. + +@node Config Files, quick start, Where, Installing @value{PRODUCT} at Your Site +@section Configuration Files affected + +A number of files should be adjusted for kerberos use. +@table @file +@item /etc/services +needs to contain additional entries for kerberos and application servers. +@item /etc/inetd.conf +needs to contain lines for the new kerberized services +@item /etc/rc.local +(or equivalent) needs to contain commands to start up long-running +kerberos servers (@code{kadmind5}, @code{krb5kdc}, and @code{krb524d}) +@end table + +@node quick start, AFS enhancements, Config Files, Installing @value{PRODUCT} at Your Site +@section Getting Started from an existing Realm +If you're converting from a V4 realm, you can do +@example + @dots{}/admin/kdb5_convert +@end example +directly from an existing database, or +@example + /usr/kerberos/bin/kdb_util dump v4db + @dots{}/admin/kdb5_convert -f v4db +@end example +to make a slave dump file and work from that (useful if you've got a +V4 system with slave servers and want to add a V5 slave on a trial +basis.) + +If you're creating a V5 realm from scratch, you need to +@example + .../admin/kdb5_create +@end example +and possibly +@example + .../admin/kdb5_stash +@end example + +The config files for this release are completely different from the V4 +config files; they're much more like windows @code{.ini} files, and are +called @dfn{profiles}. The default location (which can be adjusted via the +@samp{KRB_CONF} environment variable) is @file{/etc/krb5.conf}. An example file +follows. You'll need to change the @code{default_realm} and add a @dfn{stanza} +(like the CYGNUS.COM=@{...@} section) for your realm. + +@example +[libdefaults] + ticket_lifetime = 600 + default_realm = ATHENA.MIT.EDU + +[realms] + ATHENA.MIT.EDU = @{ + kdc = KERBEROS-2.MIT.EDU:750 + kdc = KERBEROS.MIT.EDU + kdc = KERBEROS-1.MIT.EDU + admin_server = KERBEROS.MIT.EDU + default_domain = MIT.EDU + @} + CYGNUS.COM = @{ + kdc = KERBEROS.CYGNUS.COM + kdc = KERBEROS-1.CYGNUS.COM + @} + +[domain_realm] + .mit.edu = ATHENA.MIT.EDU + mit.edu = ATHENA.MIT.EDU + .media.mit.edu = MEDIA-LAB.MIT.EDU + media.mit.edu = MEDIA-LAB.MIT.EDU + .ucsc.edu = CATS.UCSC.EDU +@end example + + +@node AFS enhancements, kprop, quick start, Installing @value{PRODUCT} at Your Site +@section Using CNS V5 with AFS + +It is possible to run a TransArc AFS cell off of CNS5 security servers, +instead of using the "KAserver". There are a few tools that help (note +that because they use TransArc libraries which we are not licensed to +distribute, you'll need to compile these yourself.) + +@menu +* asetkey:: asetkey +@end menu + +@node asetkey, , AFS enhancements, AFS enhancements +@subsection asetkey + +The asetkey program is a replacement for the existing setkey or asetkey +program which informs an AFS file server of the keys it uses. The steps +to get the keys into a V5 database are: + +@example +% kdb5_edit +kdb5_edit: av4k afs/@var{cell.name} +kdb5_edit: xst @var{cell.name} afs +@end example + +which should create a @file{@var{cell.name}-new-srvtab} which should be +securely moved to the afs server and placed in @file{/etc/v5srvtab}. + +To double check, +@example +% klist -k @var{cell.name}-new-srvtab +@end example + +and find out what the key version number is (I use 1 in the example +below, it may be larger if you've changed the key since creating it.) + +Then, running +@example +% asetkey add 1 /etc/v5srvtab afs/@var{cell.name} +@end example + +(where 1 is the key version number, and @samp{afs/@var{cell.name}} is the +principal for the server [which will get converted by @file{krb524d} to +@samp{afs.@var{cell.name}}]) will initialize the afs key list. +@example +% asetkey list +@end example + +should show the current list. + +If you're using @code{cklog} for interrealm AFS, you may need to duplicate +the @samp{afs/@var{cell.name}@@@var{REALM}} key as @samp{afs@@@var{REALM}}. + +@node kprop, interrealm, AFS enhancements, Installing @value{PRODUCT} at Your Site +@section Redundant Slave Servers + +CNS V5 supports redundant @dfn{slave} servers. The @dfn{master} server +has the primary copy of the database; the slaves get periodic updates of +that database, usually every few hours. Clients are normally configured +to talk to the master first, and to timeout and talk to a slave if the +master is unreachable. It is sometimes useful to have geographically +seperated slaves, and to have clients configured (via @file{krb5.conf}) +to talk to the nearest one instead. Note that all password changes and +other administrative operations must go through the master server. + +@enumerate +@item +On both the master and slave, add the following line to @file{/etc/services}: +@example +krb5_prop 754/tcp # Kerberos slave propagation +@end example +@end enumerate + +On the slave, +@enumerate +@item +Add the principal name for the master to the @sc{acl} for @code{kpropd}. +@example + echo host/@var{master.host.name}@@@var{REALM} > /usr/cygnus/cns5/lib/krb5kdc/kpropd.acl +@end example + +@item +Add a line to @file{/etc/inetd.conf} that enables the receiving @code{kpropd}. +@example +krb5_prop stream tcp nowait root /usr/cygnus/cns5/sbin/kpropd kpropd +@end example + +@end enumerate + +@enumerate +On the master: +@item +Be sure that the master has a @file{v5srvtab} (created with +@example + sbin/kdb5_edit + ark host/@var{master.host.name} + xst @var{master.host.name} host + mv @var{master.host.name}-new-srvtab /etc/v5srvtab +@end example +you've probably already done this.) + +@item +Create an initial database dump for transfer to the slave. +@example + echo ddb /usr/cygnus/cns5/lib/krb5kdc/slave_datatrans | admin/kdb5_edit + sbin/kprop slavehost +@end example + +@item +Back on the slave, securely install the stash file, and start the kdc: +@example + rcp -xp root@@@var{master}:/.k5.@var{REALM} /.k5.@var{REALM} + sbin/krb5kdc +@end example + +@item +On any clients, add an addition +@example + kdc = @var{master.host.name} +@end example +line to the @samp{REALM} entry in the @samp{[realms]} section of +@file{krb5.conf}. + +@end enumerate + +For continued operation, +@enumerate +@item +Run @file{sbin/krb5kdc} on the slave (usually from @file{/etc/rc.local}). +@item +On the master, Periodically (using the @code{cron} facility) run +@example + echo ddb /usr/cygnus/cns5/lib/krb5kdc/slave_datatrans | admin/kdb5_edit + sbin/kprop @var{slave.host.name} +@end example +@end enumerate + +Note that the first time through, the master will indicates success, but +the slave server may indicate failure. Once a database has actually +propagated once, it will work correctly. + +@node interrealm, CNS V4 Compatibility, kprop, Installing @value{PRODUCT} at Your Site +@section Arranging Interrealm Authentication + +Kerberos V4 supports simple automatic cross-realm +authentication. Given two realms @var{REALM1} and @var{REALM2}, the +administrators +agree on a common key, and then create +@example + krbtgt.@var{REALM2} (in the @var{REALM1} database) + krbtgt.@var{REALM1} (in the @var{REALM2} database.) +@end example +At this point, a user with tickets @var{user@@REALM1} can get tickets for +servers in @var{REALM2} automatically, and is authenticated as +@var{user@@REALM1}, +not as simply @var{user}. + +Kerberos V5 uses the same mechanism with different names. +@example + krbtgt/@var{REALM2} (in the @var{REALM1} database) + krbtgt/@var{REALM1} (in the @var{REALM2} database.) +@end example + +If you convert a V4 database with interrealm keys, you'll +automatically get working keys for V5 interrealm use as well. If +you're doing a new V5 database, +@example + % kdb5_edit + kdb5_edit: ank krbtgt/@var{REALM2} +@end example +(and the corresponding @samp{krbtgt/@var{REALM1}} on the other server) is +sufficient. If you need to do interrealm using V4 backwards +compatibility, even though this is a new V5 realm, you should create the +keys as V4 keys instead: +@example + % kdb5_edit + kdb5_edit: av4k krbtgt/@var{REALM2} +@end example + +@node CNS V4 Compatibility, , interrealm, Installing @value{PRODUCT} at Your Site +@section CNS V4 Backward Compatibility Support + +CNS V5 has a variety of forms of support for the continued use of CNS V4 +clients and servers. This permits gradually phasing out older software, +and gives time for the user community to adjust to new tools. + + +@menu +* V4 servers:: Servers that support V4 clients +* krb524d:: krb524d +* v4kadmind:: Version 4 Adminstration Server +@end menu + +@node V4 servers, krb524d, CNS V4 Compatibility, CNS V4 Compatibility +@subsection Servers that support V4 clients + +The @code{rlogind} and @code{telnetd} servers can accept authentication +from CNS V4 clients. To enable this, it is sufficient for the servers to +be able to find a CNS V4 srvtab with the correct key. + +Normally the servers will look in @file{/etc/krb-srvtab}, but this can +be changed in the @file{krb5.conf} file by setting the variable +@code{krb5_srvtab} in the @code{[libdefaults]} stanza to a filename. + +@node krb524d, v4kadmind, V4 servers, CNS V4 Compatibility +@subsection krb524d + +If you're using Kerberos V4 backwards compatibility, it may be easier to +have users get V5 tickets and then convert them to V4 tickets when +needed. (For example, only V5 tickets can be forwarded, but the +forwarded ticket could be used to get a local V4 ticket.) + +@node v4kadmind, , krb524d, CNS V4 Compatibility +@subsection Version 4 Adminstration Server + +Many existing clients support password change functions using the old V4 +administrative protocol. @code{v4kadmind} provides this V4 interface to +a V5 database. This also provides an easy path to incrementally update +from V4 to V5. Simply convert the database, move or link the @sc{acl} +files from @file{/usr/kerberos/lib/admin_acl.@var{tag}} to +@file{/usr/cygnus/cns5/lib/krb5kdc/v4acl.@var{tag}}@footnote{@var{tag} +can be one of @code{add}, @code{del}, @code{get}, or @code{mod}.} and +run @code{v4kadmind}. + + + + +@contents +@c second page break makes sure right-left page alignment works right +@c with a one-page toc, even though we don't have setchapternewpage odd. +@c end of texinfo file +@bye diff --git a/doc/man2ps b/doc/man2ps new file mode 100644 index 000000000..33162d402 --- /dev/null +++ b/doc/man2ps @@ -0,0 +1,42 @@ +#!/bin/sh + +com=`basename $0` +files=$* +docdir=`pwd` +mandir=$docdir/man + +cd $mandir + +for file in $files +do + troff -C -man -Tps $mandir/man?/$file.? | grops -g > $file.ps + + pages=`grep '%%Pages\:' $file.ps | awk '{print $2}'` + pp=$(($pages - 1)) + + echo $file': '$pages' pages' + + if [ -e csplit ]; then + csplit -k $file.ps /Page:/ \{$pp\} + + counter=0 + + for number in `ls xx*` + do + cat xx00 > $docdir/$file$counter.ps + echo '.7 dup scale' >> $docdir/$file$counter.ps + cat $number >> $docdir/$file$counter.ps + if [ $counter != $pages ]; + then + echo '%%Trailer' >> $docdir/$file$counter.ps + echo 'end' >> $docdir/$file$counter.ps + echo '%%EOF' >> $docdir/$file$counter.ps + fi + counter=$(($counter + 1)) + done + + rm $file.ps $docdir/$file'0.ps' xx* + else + echo "Can't find the csplit command. You'll have to split $file.ps manually." + fi +done diff --git a/doc/send-pr.texinfo b/doc/send-pr.texinfo new file mode 100644 index 000000000..f83af4f31 --- /dev/null +++ b/doc/send-pr.texinfo @@ -0,0 +1,200 @@ +The @code{send-pr} program is installed in the directory +@code{@value{ROOTDIR}/bin}. + +@need 1100 +Before using @code{send-pr} for the first time, you need to install your +customer support ID into the program, by typing the command: + +@smallexample +@b{shell%} install-sid @i{customerID} +@end smallexample + +@noindent replacing @i{customerID} with your customer ID, which your +sales representative will supply. + +The @code{send-pr} program enters the problem report into our Problem +Report Management System (PRMS), which automatically assigns it to the +engineer best able to help you with problems in the assigned category. +The engineer will work with you via email, telephone, or both, and all +email related to this Problem Report will be tracked by PRMS for future +reference. If the engineer does not reply to you after a certain time, +a reminder is automatically generated. If you need to talk to someone +else in our organization about the problem (@i{e.g.}, if the engineer +gets hit by a truck), we can find out what the current state is through +the PR number. @value{COMPANY} uses PRMS for almost all of the real +problems we handle. + +The @code{send-pr} program will try to intelligently fill in as many +fields as it can. You need to choose the @dfn{category}, @dfn{class}, +@dfn{severity}, and @dfn{priority} of the problem, as well as giving us +as much information as you can about its exact nature. + +@need 1000 +The PR @b{category} will be one of: + +@smallexample +@group +kerberos kerbnet doc help-request +info-request install query-pr id-request +send-pr +@end group +@end smallexample + +In general, if specific knowledge about Kerberos is requried to answer a +PR, use the @i{kerberos} or @i{doc} categories. The @i{install} +category is for problems retrieving the code off the media (@i{e.g.}, +the data on a tape seems to be corrupted.) Questions about the +installation procedures described in this document would fall under the +category @i{kerberos}. The @i{help-request} and @i{info-request} +categories are for general questions about your contract, or other +issues not necessarily related to @value{PRODUCT}. Use @i{query-pr} to +receive a current copy of your Problem Report, @i{id-request} if you +need a customer ID, and @i{send-pr} if you're having trouble using +send-pr. If your question is related to @value{PRODUCT} and you're not +sure what the most appropriate category should be, use @i{kerberos}. +The engineer can change the category if necessary. + +The @b{class} can be @dfn{sw-bug}, @dfn{doc-bug}, @dfn{change-request}, +or @dfn{support}. The first two are exactly as their names imply. The +@i{change-request} class is to inform us of changes, such as new email +addresses or new contact information. The @i{support} class is intended +for general questions about using the @value{PRODUCT} clients or +libraries. + +The @b{severity} of the problem indicates the problem's impact on the +usability of the @value{PRODUCT} software package. If a problem is +@dfn{critical}, that means the product, component or concept is +completely non-operational, or some essential functionality is missing, +and no workaround is known. A @dfn{serious} problem is one in which the +product, component or concept is not working properly or significant +functionality is missing. Problems that would otherwise be considered +@i{critical} are rated @i{serious} when a workaround is known. A +@dfn{non-critical} problem is one that is indeed a problem, but one that +is having a minimal affect on your ability to use @value{PRODUCT}. +@i{E.g.}, The product, component or concept is working in general, but +lacks features, has irritating behavior, does something wrong, or +doesn't match its documentation. The default severity is @i{serious}. + +The @b{priority} indicates how urgent this particular problem is in +relation to your work. Note that low priority does not imply low +importance. @value{COMPANY} considers all problems important, and +encourages its customers to be realistic about priority ratings. A +priority of @dfn{high} means a solution is needed as soon as possible. +A priority of @dfn{medium} means the problem should be solved no later +than the next release. A priority of @dfn{low} means the problem should +be solved in a future release, but it is not important to your work how +soon this happens. The default priority is @i{medium}. + +Note that a given severity does not necessarily imply a given priority. +For example, a non-critical problem might still have a high priority if +you are faced with a hard deadline. Conversely, a serious problem might +have a low priority if the feature it is disabling is one that you do +not need. + +The @b{release} is as labeled on the software that was shipped. +@i{e.g.}, @code{kerbnet-@value{RELEASE}}. It is important that you tell +us which release you are using, and whether or not you have made any +private changes. + +Bug reports that include proposed fixes are especially welcome. If you +include proposed fixes, please send them using either context diffs +(@samp{diff -c}) or unified diffs (@samp{diff -u}). + +@iftex +@vfill +@end iftex + +@page +A sample filled-out form from a company named ``Toasters, Inc.'' might +look like this: + +@smallexample +@group +To: bugs@@cygnus.com +Subject: "KDC reply did not match expectations" error +From: joe.smith@@toasters.com +Reply-To: joe.smith@@toasters.com +X-send-pr-version: 3.97-96q1 + +>Submitter-Id: toastersinc +>Confidential: yes +>Originator: Joe Smith (+1 415 903 1400) +>Organization: +----- +Joe Smith joe.smith@@toasters.com +Toasters, Inc. + ``The best UI in the world'' + +>Synopsis: "KDC reply did not match expectations" error message +>Severity: non-critical +>Priority: low +>Category: kerberos +>Class: sw-bug +>Release: kerbnet-1.0 +>Environment: +NetBSD viola 1.1 NetBSD 1.1 (ATHENAADP) #0: Tue May 21 00:31:42 EDT 1996 +i386 +System: Intel P166 +Architecture: NetBSD + +>Description: + <description of problem goes here> + Getting "KDC reply did not match expectations" message. This + does not seem to be affecting anything else. + +>How-To-Repeat: + <A code sample is worth a thousand words.> + <If the Problem Report is marked ``Confidential: yes'',> + <it will not be available to anyone but our engineers,> + <please contact us if you are concerned about sensitive source> + <code.> + It happens when I type kinit. + +>Fix: + <If you have already found a correct way to stop this problem,> + <please let us know!> + None. Sorry. +@end group +@end smallexample + +@iftex +@vfill +@end iftex + +@page +If the @code{send-pr} program does not work for you, you can use the +following template instead: + +@smallexample +@group +To: bugs@@cygnus.com +Subject: +From: +Reply-To: +X-send-pr-version: none (typed manually) + +>Submitter-Id: +>Originator: +>Organization: + <organization of PR author (multiple lines)> +>Confidential: <[ yes | no ] (one line)> +>Synopsis: <synopsis of the problem (one line)> +>Severity: <[ non-critical | serious | critical ] (one line)> +>Priority: <[ low | medium | high ] (one line)> +>Category: <name of the product (one line)> +>Class: <[ sw-bug | doc-bug | change-request | support ] (one line)> +>Release: cns-9?q? +>Environment: + <machine, os, target, libraries (multiple lines)> +System: +Architecture: + + +>Description: + <precise description of the problem (multiple lines)> +>How-To-Repeat: + <code/input/activities to reproduce the problem (multiple lines)> +>Fix: + <how to correct or work around the problem, if known (multiple lines)> +@end group +@end smallexample diff --git a/doc/user-guide.texinfo b/doc/user-guide.texinfo new file mode 100644 index 000000000..d62664ccd --- /dev/null +++ b/doc/user-guide.texinfo @@ -0,0 +1,1671 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@c guide +@setfilename KerbNet-User.info +@settitle Kerb*Net UNIX User's 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 0.9 beta + +@finalout @c don't print black warning boxes + +@titlepage +@title @value{PRODUCT} UNIX User's Guide +@subtitle Release: @value{RELEASE} +@subtitle Document Edition: @value{EDITION} +@subtitle Last updated: @value{UPDATED} +@author @value{COMPANY} + +@page +@vskip 0pt plus 1filll + +@include copyright.texinfo +@end titlepage + +@comment node-name, next, previous, up +@node Top, Introduction, (dir), (dir) + +@ifinfo +This file describes how to use the @value{PRODUCT} client programs. + +@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 comand before each @section or @subsection! All you need to enter +@c is: +@c + +@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:: +* @value{PRODUCT} Tutorial:: +* @value{PRODUCT} Reference:: +* Kerberos Glossary:: +@end menu + +@node Introduction, @value{PRODUCT} Tutorial, Top, Top +@chapter Introduction + +@value{PRODUCT} is based on the Kerberos V5 authentication system +developed at MIT. Kerberos is named for the three-headed watchdog from +Greek mythology, who guarded the entrance to the underworld. + +Under Kerberos, a client (generally either a user or a service) sends a +request for a ticket to the @i{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. + +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{COMPANY}'s @value{PRODUCT} plays a vital role in maintaining your +nework security. + +The @value{PRODUCT} package is designed to be easy to use. Most of the +commands are nearly identical to UNIX network programs you are already +used to. @value{PRODUCT} is a @dfn{single-sign-on} system, which means +that you have to type your password only once per session, and Kerberos +does the authenticating and encrypting transparently. + +@iftex +@vfil +@end iftex +@need 2000 +@menu +* What is a Ticket?:: +* What is a Kerberos Principal?:: +@end menu + +@node What is a Ticket?, What is a Kerberos Principal?, Introduction, Introduction +@section What is a Ticket? + +Your Kerberos @dfn{credentials}, or ``@dfn{tickets}'', are a set of +electronic information that can be used to verify your identity. Your +Kerberos tickets may be stored in a file, or they may exist only in +memory. + +The first ticket you obtain is a @dfn{ticket-granting ticket}, which +permits you to obtain additional tickets. These additional tickets give +you permission for specific services. The requesting and granting of +these additional tickets happens transparently. + +A good analogy for the ticket-granting ticket is a three-day ski pass +that is good at four different resorts. You show the pass at whichever +resort you decide to go to (until it expires), and you receive a lift +ticket for that resort. Once you have the lift ticket, you can ski all +you want at that resort. If you go to another resort the next day, you +once again show your pass, and you get an additional lift ticket for the +new resort. The difference is that the @value{PRODUCT} programs notice +that you have the weekend ski pass, and get the lift ticket for you, so +you don't have to perform the transactions yourself. + +@iftex +@vfil +@end iftex +@need 2000 +@node What is a Kerberos Principal?, , What is a Ticket?, Introduction +@section What is a Kerberos Principal? + +A Kerberos @dfn{principal} is a unique identity to which Kerberos can +assign tickets. By convention, a principal is divided into three parts: +the @dfn{primary}, the @dfn{instance}, and the @dfn{realm}. The format +of a typical Kerberos V5 principal is @code{primary/instance@@REALM}. + +@itemize @bullet +@item The @dfn{primary} is the first part of the principal. In the case +of a user, it's the same as your username. For a host, the primary is +the word @code{host}. + +@item The @dfn{instance} is an optional string that qualifies the +primary. The instance is separated from the primary by a slash +(@code{/}). In the case of a user, the instance is usually null, but a +user might also have an additional principal, with an instance called +@samp{admin}, which he/she uses to administrate a database. The +principal @code{@value{RANDOMUSER1}@@@value{PRIMARYREALM}} is completely +separate from the principal +@code{@value{RANDOMUSER1}/admin@@@value{PRIMARYREALM}}, with a separate +password, and separate permissions. In the case of a host, the instance +is the fully qualified hostname, e.g., +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}. + +@item The @dfn{realm} is your Kerberos realm. In most cases, your +Kerberos realm is your domain name, in upper-case letters. For example, +the machine @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} would be in +the realm @code{@value{PRIMARYREALM}}. +@end itemize + +@node @value{PRODUCT} Tutorial, @value{PRODUCT} Reference, Introduction, Top +@chapter @value{PRODUCT} Tutorial + +This tutorial is intended to familiarize you with the @value{PRODUCT} +client programs. We will represent your prompt as ``@code{shell%}''. +So an instruction to type the ``@kbd{ls}'' command would be represented as +follows: + +@need 600 +@smallexample +@group +@b{shell%} ls +@end group +@end smallexample + +In these examples, we will use sample usernames, such as +@code{@value{RANDOMUSER1}} and @code{@value{RANDOMUSER2}}, sample +hostnames, such as @code{@value{RANDOMHOST1}} and +@code{@value{RANDOMHOST2}}, and sample domain names, such as +@code{@value{PRIMARYDOMAIN}} and @code{@value{SECONDDOMAIN}}. When you +see one of these, substitute your username, hostname, or domain name +accordingly. + +@menu +* Setting Up to Use @value{PRODUCT}:: +* Ticket Management:: +* Password Management:: +* @value{PRODUCT} Applications:: +@end menu + +@node Setting Up to Use @value{PRODUCT}, Ticket Management, @value{PRODUCT} Tutorial, @value{PRODUCT} Tutorial +@section Setting Up to Use @value{PRODUCT} + +Your system administrator will have installed the @value{PRODUCT} +programs in whichever directory makes the most sense for your system. +We will use @code{@value{ROOTDIR}} throughout this guide to refer to the +top-level directory @value{PRODUCT} directory. We will therefor use +@code{@value{BINDIR}} to denote the location of the @value{PRODUCT} user +programs. In your installation, the directory name may be different, +but whatever the directory name is, you should make sure it is included +in your path. You will probably want to put it @i{ahead of} the +directories @code{/bin} and @code{/usr/bin} so you will get the +@value{PRODUCT} network programs, rather than the standard UNIX +versions, when you type their command names. + +@node Ticket Management, Password Management, Setting Up to Use @value{PRODUCT}, @value{PRODUCT} Tutorial +@section Ticket Management + +On many systems, Kerberos is built into the login program, and you get +tickets automatically when you log in. Other programs, such as +@code{rsh}, @code{rcp}, @code{telnet}, and @code{rlogin}, can forward +copies of your tickets to the remote host. Most of these programs also +automatically destroy your tickets when they exit. However, +@value{COMPANY} recommends that you explicitly destroy your Kerberos +tickets when you are through with them, just to be sure. One way to +help ensure that this happens is to add the @code{kdestroy} command to +your @code{.logout} file. Additionally, if you are going to be away +from your machine and are concerned about an intruder using your +permissions, it is safest to either destroy all copies of your tickets, +or use a screensaver that locks the screen. + +@need 2000 +@menu +* Obtaining Tickets with kinit:: +* Viewing Your Tickets with klist:: +* Destroying Your Tickets with kdestroy:: +@end menu + +@node Obtaining Tickets with kinit, Viewing Your Tickets with klist, Ticket Management, Ticket Management +@subsection Obtaining Tickets with kinit + +If your site is using the @value{PRODUCT} login program, you will get +Kerberos tickets automatically when you log in. If your site uses a +different login program, you may need to explicitly obtain your Kerberos +tickets, using the @code{kinit} program. Similarly, if your Kerberos +tickets expire, use the @code{kinit} program to obtain new ones. + +@need 1500 +To use the @code{kinit} program, simply type @kbd{kinit} and then type +your password at the prompt. For example, Jennifer (whose username is +@code{@value{RANDOMUSER1}}) works for Bleep, Inc. (a fictitious company +with the domain name @code{@value{PRIMARYDOMAIN}} and the Kerberos realm +@code{@value{PRIMARYREALM}}). She would type: + +@smallexample +@group +@b{shell%} kinit +@b{Password for @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<-- [Type @value{RANDOMUSER1}'s password here.]} +@b{shell%} +@end group +@end smallexample + +@need 1000 +If you type your password incorrectly, kinit will give you the following +error message: + +@smallexample +@group +@b{shell%} kinit +@b{Password for @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<-- [Type the wrong password here.]} +@b{kinit: Password incorrect} +@b{shell%} +@end group +@end smallexample + +@noindent and you won't get Kerberos tickets. + +@noindent Notice that @code{kinit} assumes you want tickets for your own +username in your default realm. +@need 1500 +Suppose Jennifer's friend David is visiting, and he wants to borrow a +window to check his mail. David needs to get tickets for himself in his +own realm, @value{SECONDREALM}.@footnote{Note: the realm +@value{SECONDREALM} must be listed in your computer's Kerberos +configuration file, @code{/etc/krb5.conf}.} He would type: + +@smallexample +@group +@b{shell%} kinit @value{RANDOMUSER2}@@@value{SECONDREALM} +@b{Password for @value{RANDOMUSER2}@@@value{SECONDREALM}:} @i{<-- [Type @value{RANDOMUSER2}'s password here.]} +@b{shell%} +@end group +@end smallexample + +@noindent David would then have tickets which he could use to log onto +his own machine. Note that he typed his password locally on Jennifer's +machine, but it never went over the network. Kerberos on the local host +performed the authentication to the KDC in the other realm. + +@need 1000 +If you want to be able to forward your tickets to another host, you need +to request @dfn{forwardable} tickets. You do this by specifying the +@kbd{-f} option: + +@smallexample +@group +@b{shell%} kinit -f +@b{Password for @value{RANDOMUSER1}@@@value{PRIMARYREALM}:} @i{<-- [Type your password here.]} +@b{shell%} +@end group +@end smallexample + +@noindent +Note that @code{kinit} does not tell you that it obtained forwardable +tickets; you can verify this using the @code{klist} command +(@pxref{Viewing Your Tickets with klist}). + +Normally, your tickets are good for your system's default ticket +lifetime, which is ten hours on many systems. You can specify a +different ticket lifetime with the @samp{-l} option. Add the letter +@samp{s} to the value for seconds, @samp{m} for minutes, @samp{h} for +hours, or @samp{d} for days. +@need 1500 +For example, to obtain forwardable tickets for +@code{@value{RANDOMUSER2}@@@value{SECONDREALM}} that would be good for +three hours, you would type: + +@smallexample +@group +@b{shell%} kinit -f -l 3h @value{RANDOMUSER2}@@@value{SECONDREALM} +@b{Password for @value{RANDOMUSER2}@@@value{SECONDREALM}:} @i{<-- [Type @value{RANDOMUSER2}'s password here.]} +@b{shell%} +@end group +@end smallexample + +@noindent +You cannot mix units; specifying a lifetime of @samp{3h30m} would result +in an error. Note also that most systems specify a maximum ticket +lifetime. If you request a longer ticket lifetime, it will be +automatically truncated to the maximum lifetime. + +@iftex +@vfil +@end iftex +@need 3000 +@node Viewing Your Tickets with klist, Destroying Your Tickets with kdestroy, Obtaining Tickets with kinit, Ticket Management +@subsection Viewing Your Tickets with klist + +The @code{klist} command shows your tickets. When you first obtain +tickets, you will have only the ticket-granting ticket. (@xref{What is +a Ticket?}.) The listing would look like this: + +@smallexample +@group +@b{shell%} klist +Ticket cache: /tmp/krb5cc_ttypa +Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM} + +Valid starting Expires Service principal +06/07/96 19:49:21 06/08/96 05:49:19 krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM} +@b{shell%} +@end group +@end smallexample + +@noindent +The ticket cache is the location of your ticket file. In the above +example, this file is named @code{/tmp/krb5cc_ttypa}. The default +principal is your kerberos @dfn{principal}. (@pxref{What is a Kerberos +Principal?}) + +The ``valid starting'' and ``expires'' fields describe the period of +time during which the ticket is valid. The @dfn{service principal} +describes each ticket. The ticket-granting ticket has the primary +@code{krbtgt}, and the instance is the realm name. + +@need 2000 +Now, if @value{RANDOMUSER1} connected to the machine +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, and then typed +@kbd{klist} again, she would have gotten the following result: + +@smallexample +@group +@b{shell%} klist +Ticket cache: /tmp/krb5cc_ttypa +Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM} + +Valid starting Expires Service principal +06/07/96 19:49:21 06/08/96 05:49:19 krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM} +06/07/96 20:22:30 06/08/96 05:49:19 host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} +@b{shell%} +@end group +@end smallexample + +@noindent +Here's what happened: when @value{RANDOMUSER1} used telnet to connect +to the host @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, the telnet +program presented her ticket-granting ticket to the KDC and requested a +host ticket for the host +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}. The KDC sent the host +ticket, which telnet then presented to the host +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, and she was allowed to +log in without typing her password. +@iftex +@vfil +@end iftex + +@need 3000 +Suppose your Kerberos tickets allow you to log into a host in another +domain, such as @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, which +is also in another Kerberos realm, @code{@value{SECONDREALM}}. If you +telnet to this host, you will receive a ticket-granting ticket for the +realm @code{@value{SECONDREALM}}, plus the new @code{host} ticket for +@code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}. @kbd{klist} will now +show: + +@smallexample +@group +@b{shell%} klist +Ticket cache: /tmp/krb5cc_ttypa +Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM} + +Valid starting Expires Service principal +06/07/96 19:49:21 06/08/96 05:49:19 krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM} +06/07/96 20:22:30 06/08/96 05:49:19 host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} +06/07/96 20:24:18 06/08/96 05:49:19 krbtgt/@value{SECONDREALM}@@@value{PRIMARYREALM} +06/07/96 20:24:18 06/08/96 05:49:19 host/@value{RANDOMHOST2}.@value{SECONDDOMAIN}@@@value{PRIMARYREALM} +@b{shell%} +@end group +@end smallexample + +You can use the @code{-f} option to view the @dfn{flags} that apply to +your tickets. The flags are: + +@table @b +@itemx F +@b{F}orwardable +@itemx f +@b{f}orwarded +@itemx P +@b{P}roxiable +@itemx p +@b{p}roxy +@itemx D +post@b{D}ateable +@itemx d +post@b{d}ated +@itemx R +@b{R}enewable +@itemx I +@b{I}nitial +@itemx i +@b{i}nvalid +@end table + +@need 1500 +Here is a sample listing. In this example, the user @value{RANDOMUSER1} +obtained her initial tickets (@samp{I}), which are forwardable +(@samp{F}) and postdated (@samp{d}) but not yet validated (@samp{i}). +(@xref{kinit Reference} for more information about postdated tickets.) + +@smallexample +@group +@b{shell%} klist -f +@b{Ticket cache: /tmp/krb5cc_320 +Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM} + +Valid starting Expires Service principal +31 Jul 96 19:06:25 31 Jul 96 19:16:25 krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM} + Flags: FdiI +shell%} +@end group +@end smallexample + +@need 1500 +In the following example, the user @value{RANDOMUSER2}'s tickets were +forwarded (@samp{f}) to this host from another host. The tickets are +reforwardable (@samp{F}). + +@smallexample +@group +@b{shell%} klist -f +@b{Ticket cache: /tmp/krb5cc_p11795 +Default principal: @value{RANDOMUSER2}@@@value{SECONDREALM} + +Valid starting Expires Service principal +07/31/96 11:52:29 07/31/96 21:11:23 krbtgt/@value{SECONDREALM}@@@value{SECONDREALM} + Flags: Ff +07/31/96 12:03:48 07/31/96 21:11:23 host/@value{RANDOMHOST2}.@value{SECONDDOMAIN}@@@value{SECONDREALM} + Flags: Ff +shell%} +@end group +@end smallexample + +@iftex +@vfil +@end iftex +@need 2000 +@node Destroying Your Tickets with kdestroy, , Viewing Your Tickets with klist, Ticket Management +@subsection Destroying Your Tickets with kdestroy + +Your Kerberos tickets are proof that you are indeed yourself, and +tickets can be stolen. If this happens, the person who has them can +masquerade as you until they expire. For this reason, you should +destroy your Kerberos tickets when you are away from your computer. + +@need 1000 +Destroying your tickets is easy. Simply type @kbd{kdestroy}. + +@smallexample +@group +@b{shell%} kdestroy +@b{shell%} +@end group +@end smallexample + +@need 1500 +If @code{kdestroy} fails to destroy your tickets, it will beep and give +an error message. For example, if @code{kdestroy} can't find any +tickets to destroy, it will give the following message: + +@smallexample +@group +@b{shell%} kdestroy +@b{kdestroy: No credentials cache file found while destroying cache +Ticket cache NOT destroyed! +shell%} +@end group +@end smallexample + +@iftex +@vfil +@end iftex +@need 2000 +@node Password Management, @value{PRODUCT} Applications, Ticket Management, @value{PRODUCT} Tutorial +@section Password Management + +Your password is the only way Kerberos has of verifying your identity. +If someone finds out your password, that person can masquerade as +you---send email that comes from you, read, edit, or delete your files, +or log into other hosts as you---and no one will be able to tell the +difference. For this reason, it is important that you choose a good +password (@pxref{Password Advice}), and keep it secret. If you need to +give access to your account to someone else, you can do so through +Kerberos. (@xref{Granting Access to Your Account}.) You should +@i{never} tell your password to anyone, including your system +administrator, for any reason. You should change your password +frequently, particularly any time you think someone may have found out +what it is. + +@iftex +@vfil +@end iftex +@need 2000 +@menu +* Changing Your Password:: +* Password Advice:: +* Granting Access to Your Account:: +@end menu + +@node Changing Your Password, Password Advice, Password Management, Password Management +@subsection Changing Your Password + +@need 2500 +To change your Kerberos password, use the @code{kpasswd} command. It +will ask you for your old password (to prevent someone else from walking +up to your computer when you're not there and changing your password), +and then prompt you for the new one twice. (The reason you have to type +it twice is to make sure you have typed it correctly.) For example, +user @code{@value{RANDOMUSER2}} would do the following: + +@smallexample +@group +@b{shell%} kpasswd +@b{Old password for @value{RANDOMUSER2}:} @i{<- Type your old password.} +@b{New Password for @value{RANDOMUSER2}:} @i{<- Type your new password.} +@b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:} @i{<- Type the new password again.} +@b{Password changed.} +@b{shell%} +@end group +@end smallexample + +@need 1800 +If @value{RANDOMUSER2} typed the incorrect old password, he would get +the following message: + +@smallexample +@group +@b{shell%} kpasswd +@b{Old password for @value{RANDOMUSER2}:} @i{<- Type the incorrect old password.} +@b{Incorrect old password. +shell%} +@end group +@end smallexample + +@need 2500 +If you make a mistake and don't type the new password the same way +twice, @code{kpasswd} will ask you to try again: + +@smallexample +@group +@b{shell%} kpasswd +@b{Old password for @value{RANDOMUSER2}:} @i{<- Type the old password.} +@b{New Password for @value{RANDOMUSER2}:} @i{<- Type the new password.} +@b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:} @i{<- Type a different new password.} +@b{Mismatch - try again +New Password for @value{RANDOMUSER2}:} @i{<- Type the new password.} +@b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:} @i{<- Type the same new password.} +@b{Password changed. +shell%} +@end group +@end smallexample + +Once you change your password, it takes some time for the change to +propagate through the system. Depending on how your system is set up, +this might be anywhere from a few minutes to an hour or more. If you +need to get new Kerberos tickets shortly after changing your password, +try the new password. If the new password doesn't work, try again using +the old one. +@iftex +@vfil +@end iftex + +@need 2000 +@node Password Advice, Granting Access to Your Account, Changing Your Password, Password Management +@subsection Password Advice + +Your password can include almost any character you can type (except +control keys and the ``enter'' key). A good password is one you can +remember, but that no one else can easily guess. Examples of @i{bad} +passwords are words that can be found in a dictionary, any common or +popular name, especially a famous person (or cartoon character), your +name or username in any form (@i{e.g.}, forward, backward, repeated +twice, @i{etc.}), your spouse's, child's, or pet's name, your birth +date, your social security number, and any sample password that appears +in this (or any other) manual. + +@need 2200 +@value{COMPANY} recommends that your password be at least 6 characters +long, and contain UPPER- and lower-case letters, numbers, and/or +punctuation marks. Some passwords that would be good if they weren't +listed in this manual include: + +@itemize @bullet +@item some initials, like ``GykoR-66.'' for ``Get your kicks on Route +66.'' + +@item an easy-to-pronounce nonsense word, like ``slaRooBey'' or +``krang-its'' + +@item a misspelled phrase, like ``2HotPeetzas!'' or ``ItzAGurl!!!'' +@end itemize + +@noindent Note: don't actually use any of the above passwords. They're +only meant to show you how to make up a good password. Passwords that +appear in a manual are the first ones intruders will try. +@iftex +@vfil +@end iftex + +@need 3800 +@value{PRODUCT} allows your system administrators to automatically +reject bad passwords, based on whatever criteria they choose. For +example, if the user @code{@value{RANDOMUSER1}} chose a bad password, +Kerberos would give an error message like the following: + +@smallexample +@group +@b{shell%} kpasswd +@b{Old password for @value{RANDOMUSER1}:} @i{<- Type your old password here.} +@b{New Password for @value{RANDOMUSER1}:} @i{<- Type an insecure new password.} +@b{Verifying, please re-enter New Password for @value{RANDOMUSER1}:} @i{<- Type it again.} + +ERROR: Insecure password not accepted. Please choose another. + +kpasswd: Insecure password rejected while attempting to change password. +Please choose another password. + +@b{New Password for @value{RANDOMUSER1}:} @i{<- Type a good password here.} +@b{Verifying, please re-enter New Password for @value{RANDOMUSER2}:} @i{<- Type it again.} +@b{Password changed. +shell%} +@end group +@end smallexample + +@noindent Your system administrators can choose the message that is +displayed if you choose a bad password, so the message you see may be +different from the above example. + +@iftex +@vfil +@end iftex +@need 2000 +@node Granting Access to Your Account, , Password Advice, Password Management +@subsection Granting Access to Your Account + +@need 1800 +If you need to give someone access to log into your account, you can do +so through Kerberos, without telling the person your password. Simply +create a file called @code{.k5login} in your home directory. This file +should contain the Kerberos principal (@xref{What is a Kerberos +Principal?}) of each person to whom you wish to give access. Each +principal must be on a separate line. Here is a sample @code{.k5login} +file: + +@smallexample +@group +@value{RANDOMUSER1}@@@value{PRIMARYREALM} +@value{RANDOMUSER2}@@@value{SECONDREALM} +@end group +@end smallexample + +@noindent This file would allow the users @code{@value{RANDOMUSER1}} and +@code{@value{RANDOMUSER2}} to use your user ID, provided that they had +Kerberos tickets in their respective realms. If you will be logging +into other hosts across a network, you will want to include your own +Kerberos principal in your @code{.k5login} file on each of these hosts. + +@need 1000 +Using a @code{.k5login} file is much safer than giving out your +password, because: + +@itemize @bullet +@item You can take access away any time simply by removing the principal +from your @code{.k5login} file. + +@item Although the user has full access to your account on one +particular host (or set of hosts if your @code{.k5login} file is shared, +@i{e.g.}, over NFS), that user does not inherit your network privileges. + +@item Kerberos keeps a log of who obtains tickets, so a system +administrator could find out, if necessary, who was capable of using +your user ID at a particular time. +@end itemize + +One common application is to have a @code{.k5login} file in +@code{root}'s home directory, giving root access to that machine to the +Kerberos principals listed. This allows system administrators to allow +users to become root locally, or to log in remotely as @code{root}, +without their having to give out the root password, and without anyone +having to type the root password over the network. + +@iftex +@vfil +@end iftex +@need 2000 + +@node @value{PRODUCT} Applications, , Password Management, @value{PRODUCT} Tutorial +@section @value{PRODUCT} Applications + +@value{PRODUCT} is a @dfn{single-sign-on} system. This means that you +only have to type your password once, and the @value{PRODUCT} programs +do the authenticating (and optionally encrypting) for you. The way this +works is that Kerberos has been built into each of a suite of network +programs. For example, when you use a @value{PRODUCT} program to +connect to a remote host, the program, the KDC, and the remote host +perform a set of rapid negotiations. When these negotiations are +completed, your program has proven your identity on your behalf to the +remote host, and the remote host has granted you access, all in the +space of a few seconds. + +The @value{PRODUCT} applications are versions of existing UNIX network +programs with the Kerberos features added. + +@iftex +@vfil +@end iftex +@need 2000 +@menu +* Overview of Additional Features:: +* telnet:: +* rlogin:: +* FTP:: +* rsh:: +* rcp:: +* ksu:: +@end menu + +@node Overview of Additional Features, telnet, @value{PRODUCT} Applications, @value{PRODUCT} Applications +@subsection Overview of Additional Features + +The @value{PRODUCT} @dfn{network programs} are those programs that +connect to another host somewhere on the internet. These programs +include @code{rlogin}, @code{telnet}, @code{ftp}, @code{rsh}, +@code{rcp}, @code{krdist}, and @code{ksu}. These programs have all of +the original features of the corresponding non-Kerberos @code{rlogin}, +@code{telnet}, @code{ftp}, @code{rsh}, @code{rcp}, @code{rdist}, and +@code{su} programs, plus additional features that transparently use your +Kerberos tickets for negotiating authentication and optional encryption +with the remote host. In most cases, all you'll notice is that you no +longer have to type your password, because Kerberos has already proven +your identity. + +The @value{PRODUCT} network programs allow you the options of forwarding +your tickets to the remote host (if you obtained forwardable tickets +with the @code{kinit} program; @pxref{Obtaining Tickets with kinit}), and +encrypting data transmitted between you and the remote host. + +This section of the tutorial assumes you are familiar with the +non-Kerberos versions of these programs, and highlights the Kerberos +functions added in the @value{PRODUCT} package. + +@iftex +@vfil +@end iftex +@need 2000 +@node telnet, rlogin, Overview of Additional Features, @value{PRODUCT} Applications +@subsection telnet + +The @value{PRODUCT} @code{telnet} command works exactly like the +standard UNIX telnet program, with the following Kerberos options added: + +@table @kbd +@itemx -f, --forward +forwards a copy of your tickets to the remote host. + +@itemx --noforward +turns off forwarding of tickets to the remote host. (This option +overrides any forwarding specified in your machine's configuration +files.) + +@itemx -F, --forwardable +forwards a copy of your tickets to the remote host, and marks them +re-forwardable from the remote host. + +@itemx --noforwardable +makes any forwarded tickets nonforwardable. (This option overrides any +forwardability specified in your machine's configuration files.) + +@itemx -k @i{realm} +requests tickets for the remote host in the specified realm, instead of +determining the realm itself. + +@itemx -K +uses your tickets to authenticate to the remote host, but does not log +you in. + +@itemx -a +attempt automatic login using your tickets. @code{telnet} will assume +the same username unless you explicitly specify another. + +@itemx -x, --encrypt +turns on encryption. + +@itemx --noencrypt +turns off encryption. +@end table + +@iftex +@vfil +@end iftex + +@need 4000 +For example, if @code{@value{RANDOMUSER2}} wanted to use the standard +UNIX telnet to connect to the machine +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, he would type: + +@smallexample +@group +@b{shell%} telnet @value{RANDOMHOST1}.@value{PRIMARYDOMAIN} +@b{Trying 128.0.0.5 ... +Connected to @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}. +Escape character is '^]'. + +NetBSD/i386 (@value{RANDOMHOST1}) (ttyp3) + +login:} @value{RANDOMUSER2} +@b{Password:} @i{<- @value{RANDOMUSER2} types his password here} +@b{Last login: Fri Jun 21 17:13:11 from @value{RANDOMHOST2}.@value{SECONDDOMAIN} +Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 + The Regents of the University of California. All rights reserved. + +NetBSD 1.1: Tue May 21 00:31:42 EDT 1996 + +Welcome to NetBSD! +shell%} +@end group +@end smallexample + +@noindent Note that the machine +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} asked for +@code{@value{RANDOMUSER2}}'s password. When he typed it, his password +was sent over the network unencrypted. If an intruder were watching +network traffic at the time, that intruder would know +@code{@value{RANDOMUSER2}}'s password. + +@iftex +@vfil +@end iftex +@need 4000 +If, on the other hand, @code{@value{RANDOMUSER1}} wanted to use the +@value{PRODUCT} telnet to connect to the machine +@code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, she could forward a +copy of her tickets, request an encrypted session, and log on as herself +as follows: + +@smallexample +@group +@b{shell%} telnet -a -f -x @value{RANDOMHOST2}.@value{SECONDDOMAIN} +@b{Trying 128.0.0.5... +Connected to @value{RANDOMHOST2}.@value{SECONDDOMAIN}. +Escape character is '^]'. +[ Kerberos V5 accepts you as ``@value{RANDOMUSER1}@@@value{SECONDDOMAIN}'' ] +[ Kerberos V5 accepted forwarded credentials ] +NetBSD 1.1: Tue May 21 00:31:42 EDT 1996 + +Welcome to NetBSD! +shell%} +@end group +@end smallexample + +@noindent Note that @code{@value{RANDOMUSER1}}'s machine used Kerberos +to authenticate her to @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, +and logged her in automatically as herself. She had an encrypted +session, a copy of her tickets already waiting for her, and she never +typed her password. + +If you forwarded your Kerberos tickets, @code{telnet} automatically +destroys them when it exits. The full set of options to @value{PRODUCT} +@code{telnet} are discussed in the Reference section of this manual. +(@pxref{telnet Reference}) + +@iftex +@vfil +@end iftex +@need 2000 +@node rlogin, FTP, telnet, @value{PRODUCT} Applications +@subsection rlogin + +@need 1000 +The @value{PRODUCT} @code{rlogin} command works exactly like the +standard UNIX rlogin program, with the following Kerberos options added: + +@table @kbd +@itemx -f, --forward +forwards a copy of your tickets to the remote host. + +@itemx --noforward +turns off forwarding of tickets to the remote host. (This option +overrides any forwarding specified in your machine's configuration +files.) + +@itemx -F, --forwardable +forwards a copy of your tickets to the remote host, and marks them +re-forwardable from the remote host. + +@itemx --noforwardable +makes any forwarded tickets nonforwardable. (This option overrides any +forwardability specified in your machine's configuration files.) + +@itemx -k @i{realm} +requests tickets for the remote host in the specified realm, instead of +determining the realm itself. + +@itemx -x, --encrypt +turns on encryption. + +@itemx --noencrypt +turns off encryption. +@end table + +@need 3000 +For example, if @code{@value{RANDOMUSER2}} wanted to use the standard +UNIX rlogin to connect to the machine +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}, he would type: + +@smallexample +@group +@b{shell%} rlogin @value{RANDOMHOST1}.@value{PRIMARYDOMAIN} -l @value{RANDOMUSER2} +@b{Password:} @i{<- @value{RANDOMUSER2} types his password here} +@b{Last login: Fri Jun 21 10:36:32 from :0.0 +Copyright (c) 1980, 1983, 1986, 1988, 1990, 1991, 1993, 1994 + The Regents of the University of California. All rights reserved. + +NetBSD 1.1: Tue May 21 00:31:42 EDT 1996 + +Welcome to NetBSD! +shell%} +@end group +@end smallexample + +@noindent Note that the machine +@code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} asked for +@code{@value{RANDOMUSER2}}'s password. When he typed it, his password +was sent over the network unencrypted. If an intruder were watching +network traffic at the time, that intruder would know +@code{@value{RANDOMUSER2}}'s password. + +@iftex +@vfil +@end iftex +@need 4000 +If, on the other hand, @code{@value{RANDOMUSER1}} wanted to use +@value{PRODUCT} rlogin to connect to the machine +@code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, she could forward a +copy of her tickets, mark them as not forwardable from the remote host, +and request an encrypted session as follows: + +@smallexample +@group +@b{shell%} rlogin @value{RANDOMHOST2}.@value{SECONDDOMAIN} -f -x +@b{This rlogin session is using DES encryption for all data transmissions. +Last login: Thu Jun 20 16:20:50 from @value{RANDOMHOST1} +SunOS Release 4.1.4 (GENERIC) #2: Tue Nov 14 18:09:31 EST 1995 +Not checking quotas. Try quota.real if you need them. +shell%} +@end group +@end smallexample + +@noindent Note that @code{@value{RANDOMUSER1}}'s machine used Kerberos +to authenticate her to @code{@value{RANDOMHOST2}.@value{SECONDDOMAIN}}, +and logged her in automatically as herself. She had an encrypted +session, a copy of her tickets were waiting for her, and she never typed +her password. + +If you forwarded your Kerberos tickets, @code{rlogin} automatically +destroys them when it exits. The full set of options to @value{PRODUCT} +@code{rlogin} are discussed in the Reference section of this manual. +(@pxref{rlogin Reference}) + +@iftex +@vfil +@end iftex +@need 2000 +@node FTP, rsh, rlogin, @value{PRODUCT} Applications +@subsection FTP + +@need 1000 +The @value{PRODUCT} @code{FTP} program works exactly like the standard +UNIX FTP program, with the following Kerberos features added: + +@table @kbd +@itemx -k @i{realm} +requests tickets for the remote host in the specified realm, instead of +determining the realm itself. + +@itemx -forward +requests that your tickets be forwarded to the remote host. The +@kbd{-forward} argument must be the last argument on the command line. + +@itemx protect @i{level} +(issued at the @code{ftp>} prompt) sets the protection level. ``Clear'' +is no protection; ``safe'' ensures data integrity by verifying the +checksum, and ``private'' encrypts the data. Encryption also ensures +data integrity. +@end table + +@need 5000 +For example, suppose @code{@value{RANDOMUSER1}} wants to get her +@code{RMAIL} file from the directory @code{~@value{RANDOMUSER1}/Mail}, +on the host @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}}. She wants +to encrypt the file transfer. The exchange would look like the +following: + +@smallexample +@group +@b{shell%} ftp @value{RANDOMHOST1}.@value{PRIMARYDOMAIN} +Connected to @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}. +220 @value{RANDOMHOST1}.@value{PRIMARYDOMAIN} FTP server (Version 5.60) ready. +334 Using authentication type GSSAPI; ADAT must follow +GSSAPI accepted as authentication type +GSSAPI authentication succeeded +Name (@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}:@value{RANDOMUSER1}): +232 GSSAPI user @value{RANDOMUSER1}@@@value{PRIMARYREALM} is authorized as @value{RANDOMUSER1} +230 User @value{RANDOMUSER1} logged in. +Remote system type is UNIX. +Using binary mode to transfer files. +ftp> protect private +200 Protection level set to Private. +ftp> cd ~@value{RANDOMUSER1}/MAIL +250 CWD command successful. +ftp> get RMAIL +227 Entering Passive Mode (128,0,0,5,16,49) +150 Opening BINARY mode data connection for RMAIL (361662 bytes). +226 Transfer complete. +361662 bytes received in 2.5 seconds (1.4e+02 Kbytes/s) +ftp> quit +@b{shell%} +@end group +@end smallexample + +The full set of options to @value{PRODUCT} @code{FTP} are discussed +in the Reference section of this manual. (@pxref{FTP Reference}) + +@iftex +@vfil +@end iftex +@need 2000 +@node rsh, rcp, FTP, @value{PRODUCT} Applications +@subsection rsh + +@need 1000 +The @value{PRODUCT} @code{rsh} program works exactly like the standard +UNIX rlogin program, with the following Kerberos features added: + +@table @kbd +@itemx -f, --forward +forwards a copy of your tickets to the remote host. + +@itemx --noforward +turns off forwarding of tickets to the remote host. (This option +overrides any forwarding specified in your machine's configuration +files.) + +@itemx -F, --forwardable +forwards a copy of your tickets to the remote host, and marks them +re-forwardable from the remote host. + +@itemx --noforwardable +makes any forwarded tickets nonforwardable. (This option overrides any +forwardability specified in your machine's configuration files.) + +@itemx -k @i{realm} +requests tickets for the remote host in the specified realm, instead of +determining the realm itself. + +@itemx -x, --encrypt +turns on encryption. + +@itemx --noencrypt +turns off encryption. +@end table + +@need 1800 +For example, if your Kerberos tickets allowed you to run programs on the +host @code{@value{RANDOMHOST2}@@@value{SECONDDOMAIN}} as root, you could +run the @samp{date} program as follows: + +@smallexample +@group +@b{shell%} rsh @value{RANDOMHOST2}.@value{SECONDDOMAIN} -l root -x date +@b{This rsh session is using DES encryption for all data transmissions. +Fri Jun 21 17:06:12 EDT 1996 +shell%} +@end group +@end smallexample + +If you forwarded your Kerberos tickets, @code{rsh} automatically +destroys them when it exits. The full set of options to @value{PRODUCT} +@code{rsh} are discussed in the Reference section of this manual. +(@pxref{rsh Reference}) + +@iftex +@vfil +@end iftex +@need 2000 +@node rcp, ksu, rsh, @value{PRODUCT} Applications +@subsection rcp + +@need 1000 +The @value{PRODUCT} @code{rcp} program works exactly like the standard +UNIX rcp program, with the following Kerberos features added: + +@table @kbd +@itemx -k @i{realm} +requests tickets for the remote host in the specified realm, instead of +determining the realm itself. + +@itemx -x, --encrypt +turns on encryption. +@end table + + +@need 1500 +For example, if you wanted to copy the file @code{/etc/motd} from the +host @code{@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}} into the current +directory, via an encrypted connection, you would simply type: + +@smallexample +@b{shell%} rcp -x @value{RANDOMHOST1}.@value{PRIMARYDOMAIN}:/etc/motd . +@end smallexample + +The @kbd{rcp} program negotiates authentication and encryption +transparently. The full set of options to @value{PRODUCT} @code{rcp} +are discussed in the Reference section of this manual. (@pxref{rcp +Reference}) + +@iftex +@vfil +@end iftex +@need 2000 +@node ksu, , rcp, @value{PRODUCT} Applications +@subsection ksu + +The @value{PRODUCT} @code{ksu} program replaces the standard UNIX su +program. @code{ksu} first authenticates you to Kerberos. Depending on +the configuration of your system, @code{ksu} may ask for your Kerberos +password if authentication fails. @emph{Note that you should never type +your password if you are remotely logged in using an unencrypted +connection.} + +Once @code{ksu} has authenticated you, if your Kerberos principal +appears in the target's @code{.k5login} file (@pxref{Granting Access to +Your Account}) or in the target's @code{.k5users} file (see below), it +switches your user ID to the target user ID. + +@need 2000 +For example, @code{@value{RANDOMUSER2}} has put +@code{@value{RANDOMUSER1}}'s Kerberos principal in his @code{.k5login} +file. If @code{@value{RANDOMUSER1}} uses @code{ksu} to become +@code{@value{RANDOMUSER2}}, the exchange would look like this. (To +differentiate between the two shells, @code{@value{RANDOMUSER1}}'s +prompt is represented as @code{@value{RANDOMUSER1}%} and +@code{@value{RANDOMUSER2}}'s prompt is represented as +@code{@value{RANDOMUSER2}%}.) + +@smallexample +@group +@b{@value{RANDOMUSER1}%} ksu @value{RANDOMUSER2} +@b{Account @value{RANDOMUSER2}: authorization for @value{RANDOMUSER1}@@@value{PRIMARYREALM} successful +Changing uid to @value{RANDOMUSER2} (3382) +@value{RANDOMUSER2}%} +@end group +@end smallexample + +@noindent +Note that the new shell has a copy of @code{@value{RANDOMUSER1}}'s +tickets. The ticket filename contains @code{@value{RANDOMUSER2}}'s UID +with @samp{.1} appended to it: + +@smallexample +@group +@b{@value{RANDOMUSER2}%} klist +@b{Ticket cache: /tmp/krb5cc_3382.1 +Default principal: @value{RANDOMUSER1}@@@value{PRIMARYREALM} + +Valid starting Expires Service principal +31 Jul 96 21:53:01 01 Aug 96 07:52:53 krbtgt/@value{PRIMARYREALM}@@@value{PRIMARYREALM} +31 Jul 96 21:53:39 01 Aug 96 07:52:53 host/@value{RANDOMHOST1}.@value{PRIMARYDOMAIN}@@@value{PRIMARYREALM} +@value{RANDOMUSER2}%} +@end group +@end smallexample + +@need 2500 +If @code{@value{RANDOMUSER1}} had not appeared in +@code{@value{RANDOMUSER2}}'s @code{.k5login} file (and the system was +configured to ask for a password), the exchange would have looked like +this (assuming @code{@value{RANDOMUSER2}} has taken appropriate +precautions in protecting his password): + +@smallexample +@group +@b{@value{RANDOMUSER1}%} ksu @value{RANDOMUSER2} +@b{WARNING: Your password may be exposed if you enter it here and are logged + in remotely using an unsecure (non-encrypted) channel. +Kerberos password for @value{RANDOMUSER2}@@@value{PRIMARYREALM}:} @i{<- @code{@value{RANDOMUSER1}} types the wrong password here.} +@b{ksu: Password incorrect +Authentication failed. +@value{RANDOMUSER1}%} +@end group +@end smallexample + +Now, suppose @code{@value{RANDOMUSER2}} did not want to give +@code{@value{RANDOMUSER1}} full access to his account, but wanted to +give her permission to list his files and use the "more" command to view +them. He could create a @code{.k5users} file giving her permission to +run only those specific commands. + +@need 3500 +The @code{.k5users} file is like the @code{.k5login} file, except that +each principal is optionally followed by a list of commands. @code{ksu} +will let those principals execute only the commands listed, using the +@kbd{-e} option. @code{@value{RANDOMUSER2}}'s @code{.k5users} file +might look like the following: + +@smallexample +@group +@value{RANDOMUSER1}@@@value{PRIMARYREALM} /bin/ls /usr/bin/more +@value{ADMINUSER}@@@value{PRIMARYREALM} /bin/ls +@value{ADMINUSER}/admin@@@value{PRIMARYREALM} * +@value{RANDOMUSER2}@@@value{SECONDREALM} +@end group +@end smallexample + +@noindent The above @code{.k5users} file would let +@code{@value{RANDOMUSER1}} run only the commands @code{/bin/ls} and +@code{/usr/bin/more}. It would let @code{@value{ADMINUSER}} run only +the command @code{/bin/ls} if he had regular tickets, but if he had +tickets for his @code{admin} instance, +@code{@value{ADMINUSER}/admin@@@value{PRIMARYREALM}}, he would be able +to execute any command. The last line gives @code{@value{RANDOMUSER2}} +in the realm @value{SECONDREALM} permission to execute any command. +(@i{I.e.}, having only a Kerberos principal on a line is equivalent to +giving that principal permission to execute @code{*}.) This is so that +@value{RANDOMUSER2} can allow himself to execute commands when he logs +in, using Kerberos, from a machine in the realm @value{SECONDREALM}. + +@need 2500 +Then, when @code{@value{RANDOMUSER1}} wanted to list his home directory, +she would type: + +@smallexample +@group +@b{@value{RANDOMUSER1}%} ksu @value{RANDOMUSER2} -e ls ~@value{RANDOMUSER2} +@b{Authenticated @value{RANDOMUSER1}@@@value{PRIMARYREALM} +Account @value{RANDOMUSER2}: authorization for @value{RANDOMUSER1}@@@value{PRIMARYREALM} for execution of + /bin/ls successful +Changing uid to @value{RANDOMUSER2} (3382) +Mail News Personal misc bin +@value{RANDOMUSER1}%} +@end group +@end smallexample + +@noindent If @code{@value{RANDOMUSER1}} had tried to give a different +command to @code{ksu}, it would have prompted for a password as with the +previous example. + +Note that unless the @code{.k5users} file gives the target permission to +run any command, the user must use @code{ksu} with the @kbd{-e} +@i{command} option. + +@need 1000 +The @code{ksu} options you are most likely to use are: + +@table @kbd +@itemx -n @i{principal} +specifies which Kerberos principal you want to use for @code{ksu}. +(@i{e.g.}, the user @code{@value{ADMINUSER}} might want to use his +@code{admin} instance. @xref{What is a Ticket?}.) + +@itemx -c +specifies the location of your Kerberos credentials cache (ticket file). + +@itemx -C +specifies the location you want the Kerberos credentials cache (ticket +file) to be for the target user ID. + +@itemx -k +tells @code{ksu} not to destroy your Kerberos tickets when @code{ksu} is +finished. + +@itemx -f +requests forwardable tickets. (@xref{Obtaining Tickets with kinit}.) This +is only applicable if @code{ksu} needs to obtain tickets. + +@itemx -l @i{lifetime} +sets the ticket lifetime. (@xref{Obtaining Tickets with kinit}.) This is +only applicable if @code{ksu} needs to obtain tickets. + +@itemx -z +tells @code{ksu} to copy your Kerberos tickets only if the UID you are +switching is the same as the Kerberos primary (either yours or the one +specified by the @kbd{-n} option). + +@itemx -Z +tells @code{ksu} not to copy any Kerberos tickets to the new UID. + +@itemx -e @i{command} +tells @code{ksu} to execute @i{command} and then exit. See the +description of the @code{.k5users} file above. + +@itemx -a @i{text} +(at the end of the command line) tells @code{ksu} to pass everything +after @samp{-a} to the target shell. +@end table + +The full set of options to @value{PRODUCT} @code{ksu} are discussed +in the Reference section of this manual. (@pxref{ksu Reference}) + +@node @value{PRODUCT} Reference, Kerberos Glossary, @value{PRODUCT} Tutorial, Top +@chapter @value{PRODUCT} Reference + +This section will include copies of the manual pages for the +@value{PRODUCT} client programs. You can read the manual entry for any +command by typing @code{man} @i{command}, where @i{command} is the name +of the command for which you want to read the manual entry. For +example, to read the @code{kinit} manual entry, you would type: + +@smallexample +@b{shell%} man kinit +@end smallexample + +Note: To be able to view the @value{PRODUCT} manual pages on line, you +may need to add the directory @code{@value{ROOTDIR}/man} to your MANPATH +environment variable. (Remember to replace @code{@value{ROOTDIR}} with +the top-level directory in which @value{PRODUCT} is installed.) For +example, if you had the the following line in your @code{.login} +file@footnote{The MANPATH variable may be specified in a different +initialization file, depending on your operating system. Some of the +files in which you might specify environment variables include +@code{.login}, @code{.profile}, or @code{.cshrc}.}: + +@smallexample +setenv MANPATH /usr/local/man:/usr/man +@end smallexample + +@noindent +and the @value{PRODUCT} man pages were in the directory +@code{/usr/@value{LCPRODUCT}/man}, you would change the line to the following: + +@smallexample +setenv MANPATH /usr/@value{LCPRODUCT}/man:/usr/local/man:/usr/man +@end smallexample + +@ifinfo +Note to info users: the manual pages are not available within this info +tree. You can read them from emacs with the command: + +@smallexample +M-x manual-entry @emph{command} +@end smallexample +@end ifinfo + +@page + +@menu +* kinit Reference:: +* klist Reference:: +* kdestroy Reference:: +* kpasswd Reference:: +* telnet Reference:: +* rlogin Reference:: +* FTP Reference:: +* rsh Reference:: +* rcp Reference:: +* ksu Reference:: +* krdist Reference:: +@end menu + +@node kinit Reference, klist Reference, @value{PRODUCT} Reference, @value{PRODUCT} Reference +@section kinit Reference + +@iftex +@special{psfile=kinit1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{kinit}} +@page + +@special{psfile=kinit2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{kinit}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry kinit} to read this manual page. +@end ifinfo + +@node klist Reference, kdestroy Reference, kinit Reference, @value{PRODUCT} Reference +@section klist Reference + +@iftex +@special{psfile=klist1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{klist}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry klist} to read this manual page. +@end ifinfo + +@node kdestroy Reference, kpasswd Reference, klist Reference, @value{PRODUCT} Reference +@section kdestroy Reference + +@iftex +@special{psfile=kdestroy1.ps voffset=-1115 hoffset=-60} +@centerline{Reference Manual for @code{kdestroy}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry kdestroy} to read this manual page. +@end ifinfo + +@node kpasswd Reference, telnet Reference, kdestroy Reference, @value{PRODUCT} Reference +@section kpasswd Reference + +@iftex +@special{psfile=kpasswd1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{kpasswd}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry kpasswd} to read this manual page. +@end ifinfo + +@node telnet Reference, rlogin Reference, kpasswd Reference, @value{PRODUCT} Reference +@section telnet Reference + +@iftex +@special{psfile=telnet1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet3.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet4.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet5.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet6.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet7.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet8.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet9.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page + +@special{psfile=telnet10.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{telnet}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry telnet} to read this manual page. +@end ifinfo + +@node rlogin Reference, FTP Reference, telnet Reference, @value{PRODUCT} Reference +@section rlogin Reference + +@iftex +@special{psfile=rlogin1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{rlogin}} +@page + +@special{psfile=rlogin2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{rlogin}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry rlogin} to read this manual page. +@end ifinfo + +@node FTP Reference, rsh Reference, rlogin Reference, @value{PRODUCT} Reference +@section FTP Reference + +@iftex +@special{psfile=ftp1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page + +@special{psfile=ftp2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page + +@special{psfile=ftp3.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page + +@special{psfile=ftp4.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page + +@special{psfile=ftp5.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page + +@special{psfile=ftp6.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page + +@special{psfile=ftp7.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page + +@special{psfile=ftp8.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{FTP}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry FTP} to read this manual page. +@end ifinfo + +@node rsh Reference, rcp Reference, FTP Reference, @value{PRODUCT} Reference +@section rsh Reference + +@iftex +@special{psfile=rsh1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{rsh}} +@page + +@special{psfile=rsh2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{rsh}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry rsh} to read this manual page. +@end ifinfo + +@node rcp Reference, ksu Reference, rsh Reference, @value{PRODUCT} Reference +@section rcp Reference + +@iftex +@special{psfile=rcp1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{rcp}} +@page + +@special{psfile=rcp2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{rcp}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry rcp} to read this manual page. +@end ifinfo + +@node ksu Reference, krdist Reference, rcp Reference, @value{PRODUCT} Reference +@section ksu Reference + +@iftex +@special{psfile=ksu1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{ksu}} +@page + +@special{psfile=ksu2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{ksu}} +@page + +@special{psfile=ksu3.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{ksu}} +@page + +@special{psfile=ksu4.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{ksu}} +@page + +@special{psfile=ksu5.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{ksu}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry ksu} to read this manual page. +@end ifinfo + +@node krdist Reference, , ksu Reference, @value{PRODUCT} Reference +@section krdist Reference + +@iftex +@special{psfile=krdist1.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{krdist}} +@page + +@special{psfile=krdist2.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{krdist}} +@page + +@special{psfile=krdist3.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{krdist}} +@page + +@special{psfile=krdist4.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{krdist}} +@page + +@special{psfile=krdist5.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{krdist}} +@page + +@special{psfile=krdist6.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{krdist}} +@page + +@special{psfile=krdist7.ps voffset=-1115 hoffset=-40} +@centerline{Reference Manual for @code{krdist}} +@page +@end iftex +@ifinfo +Type @kbd{M-x manual-entry krdist} to read this manual page. +@end ifinfo + +@node Kerberos Glossary, , @value{PRODUCT} Reference, Top +@appendix Kerberos Glossary + +@include glossary.texinfo + +@contents +@bye -- 2.26.2