KerbNet includes software and documentation developed at the Massachusetts Institute of Technology, which includes this copyright information:
Copyright © 1995, 1997 by the Massachusetts Institute of Technology.
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.
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.
KerbNet includes software and documentation developed by OpenVision Technologies, Inc., which includes this copyright notice:
The following copyright and permission notice applies to the OpenVision Kerberos Administration system located in kadmin/create, kadmin/dbutil, kadmin/server, lib/kadm, and portions of lib/rpc:
Copyright, OpenVision Technologies, Inc., 1996, All Rights Reserved WARNING: Retrieving the OpenVision Kerberos Administration system source code, as described below, indicates your acceptance of the following terms. If you do not agree to the following terms, do not retrieve the OpenVision Kerberos administration system. You may freely use and distribute the Source Code and Object Code compiled from it, but this Source Code is provided to you "AS IS" EXCLUSIVE OF ANY WARRANTY, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR ANY OTHER WARRANTY, WHETHER EXPRESS OR IMPLIED. IN NO EVENT WILL OPENVISION HAVE ANY LIABILITY FOR ANY LOST PROFITS, LOSS OF DATA OR COSTS OF PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, OR FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THIS AGREEMENT, INCLUDING, WITHOUT LIMITATION, THOSE RESULTING FROM THE USE OF THE SOURCE CODE, OR THE FAILURE OF THE SOURCE CODE TO PERFORM, OR FOR ANY OTHER REASON.OpenVision retains all rights, title, and interest in the donated Source Code. With respect to OpenVision's copyrights in the donated Source Code, OpenVision also retains rights to derivative works of the Source Code whether created by OpenVision or a third party. OpenVision Technologies, Inc. has donated this Kerberos Administration system to MIT for inclusion in the standard Kerberos 5 distribution. This donation underscores our commitment to continuing Kerberos technology development and our gratitude for the valuable work which has been performed by MIT and the Kerberos community.
KerbNet includes software and documentation developed at the University of California at Berkeley, which includes this copyright notice:
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:
This product includes software developed by the University of California, Berkeley and its contributors.
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.
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.
KerbNet 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 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.e., if the client uses 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 inside firewalls, KerbNet from Cygnus Solutions will play a vital role in the security of your network.
This document is one piece of the document set for KerbNet. The documents, and their intended audiences, are:
Specific Guides for auxiliary KerbNet features that are not supported for all installations are also provided as necessary.
As with any software package that uses a centralized database, the installation procedure is somewhat involved, and requires forethought and planning. Cygnus Solutions has attempted to make this KerbNet 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 Cygnus Solutions 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.
The next chapter describes the decisions you need to make before installing KerbNet.
Chapter three describes installation procedures for each class of Kerberos machines:
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.
Before installing KerbNet, it is necessary to consider the following issues:
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 fubar.org would be in the Kerberos realm FUBAR.ORG.
If you need multiple Kerberos realms, Cygnus Solutions recommends that you use descriptive names which end with your domain name, such as BOSTON.FUBAR.ORG and SAN_FRANCISCO.FUBAR.ORG.
Mapping hostnames onto Kerberos realms is normally not necessary if it
is the same as your domain name. If, however, this is not the case, the
mapping can be done through a set of rules in the krb5.conf
configuration file. 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.
If you choose a name for your Kerberos Realm that is different from your
domain name, you will need to manually update your krb5.conf
file
after finishing with the install script.
The KerbNet System Administrator's Guide contains a thorough
description of the parts of the krb5.conf
file and what may be
specified in each. A sample krb5.conf
file appears in
section krb5.conf. You should be able to use this file, substituting the
relevant information for your Kerberos installation for the samples.
The default ports used by Kerberos are port 88 for the
KDC(1) 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 /etc/services
and krb5.conf
files, and the kdc.conf
file on each KDC. For a more thorough
treatment of port numbers used by the KerbNet programs, refer to
the "Configuring Your Firewall to Work With KerbNet" section
of the KerbNet System Administrator's Guide.
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:
If you have a large and/or complex network, Cygnus Solutions will be happy to work with you to determine the optimal number and placement of your slave KDCs.
Cygnus Solutions recommends that your KDCs have a predefined set of
host aliases, such as kerberos
for the master KDC and
kerberos-1
, kerberos-2
, ... 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.
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. Cygnus Solutions recommends that this be no longer than an hour.
If the propagation time is longer than this maximum reasonable time
(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 run a second
kprop
script to propagate the database to the additional slaves.
(You will need to set this up manually.)
Because of the security considerations, KerbNet applications are very strict about Name Service. It is critical that a host's name resolves to the fully qualified domain name and that the IP address also resolves to the fully qualified domain name. For more information see the section in the KerbNet System Administrator's Guide on Name Services.
The Key Distribution Centers (KDCs) issue Kerberos tickets. Each KDC contains a copy of the Kerberos database.
A master KDC contains the master copy of the Kerberos database, which it propagates to the slave KDCs at regular intervals.
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.
The Admin server is the KDC that contains the master copy of the Kerberos database for your network. The Admin server is a master KDC; all database changes (such as password changes) are made to the copy on the Admin KDC server and then propagated to the other KDCs.
Unless you set up your network to do parallel database propagation, with some slave servers acting as masters to other slave servers, the Admin server will probably be your only master KDC. However, Cygnus Solutions 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 Admin KDC with one of the slaves if necessary. (See section Switching Master and Slave KDCs.) This installation procedure is based on that recommendation.
In order to set up a KDC using the procedure describted in this section, you need to log in as root on the machine you want to make into a KDC.
Because of some specifications that are compiled into the
software, you must install KerbNet in the directory
/usr/cygnus/kerbnet-1.2
. If you extract the tar file from the
top-level directory (/
), the files will end up in this directory.
The installation and configuration process is governed by a shell script
(inst-config
), which asks you for the necessary information and
sets up the KDC for you.
# /usr/cygnus/kerbnet-1.2/install/inst-config
The configuration file krb5.conf
contains information relating to
your Kerberos network, including locations of KDCs and admin servers. A
full description of the krb5.conf
file appears in the
KerbNet System Administrator's Guide. The install script will
create a krb5.conf
file and prompt you for configuration
information. The default location of this file is
/etc/krb5.conf
.
krb5.conf
file; it is best to use the fully-qualified, primary
name of each machine, to avoid possible problems with name resolution.
Cygnus Solutions recommends that you choose a persistent directory name,
and make it a symbolic link to /usr/cygnus/kerbnet-1.2
, so you can
install updates later without requiring users to change their paths.
This document will refer to /usr/cygnus/kerbnet
as the persistent
directory name.
/usr/cygnus/kerbnet
, pointing to /usr/cygnus/kerbnet-1.2
.
If there is already a symbolic link in place, the script will skip this
question. If a symbolic link is in place pointing somewhere else, the
script will ask if you want to update the link to point to
/usr/cygnus/kerbnet-1.2
.
Type yes to create or change the symbolic link.
The /etc/services
directory contains information about the
services available to the machine. The KerbNet system uses
several services, which need to be added to this file before the machine
can use them.
/etc/services
file
at this point. Type Yes or No.
If you say yes, the script will make the appropriate changes to the
file. If you say no, the script will list the changes that are
necessary, but will not edit the file. The rest of the installation
process may not work properly if /etc/services
has not been
updated; if you wish to change the file manually, rather than having the
script make the changes, you should quit the installation process by
typing `^C', and edit the file before continuing with the
installation process.
Just as KerbNet provided its own Kerberos-enhanced versions of
client UNIX network programs, KerbNet also provides
Kerberos-enhanced versions of server UNIX network daemons:
ftpd
, klogind
, kshd
, and telnetd
.
These programs are installed in the directory
/usr/cygnus/kerbnet/sbin
. You may want to add this directory to
root's path.
The script offers you a list of application services to run on the host.
The script asks you if it should update the /etc/inetd.conf
file
to account for the services you just selected.
To enable the applications to run, the appropriate lines must be
inserted into /etc/inetd.conf
. If you tell the install script to
install the KerbNet versions of the telnet
and ftp
services, the script will comment out the old versions of those services
in inetd.conf
. Because KerbNet uses the klogin
and eklogin
service instead of the login
service, and
kshell
instead of the shell
service, it is not necessary
to comment out these lines to use KerbNet. The install script
does not comment out these services to ensure that installation never
results in any denial of existing services. However, if you want to
require Kerberos for remote access to your server (which you will want
to do for a secure server), Cygnus Solutions recommends that you
manually disable the login
and shell
services.
As with the /etc/services
file, you can type No at the prompt
and the install script will give you a list of changes that need to be
made. These changes are not critical for the rest of the installation
process, so you can make them now or when you have finished installing
KerbNet.
The KDC configuration file and the Kerberos database itself contain information that carries over from one KerbNet release to the next; when you re-install the KerbNet software, you want to preserve these files. Therefore, the configuration file and the database should be stored in a directory separate from other KerbNet-related files, and not under the installation directory for any version of this product.
Also to protect your database from the inherent insecurities of distributed filesystetms, the database should be stored on local disk and not accessible via any form of distributed file system.
/var/kerbnet/kdc
, or /etc/KerbNet/kdc
if
your machine has no /var
directory. Enter the Kerberos database
path.
The install script will create the directory you specified and makes
/usr/cygnus/kerbnet-1.2/lib/krb5kdc
a symbolic link to it.
The script will then create the configuration file kdc.conf
and
five Kerberos database-related files in the directory:
principal.db
principal.ok
principal.kadm5
principal.kadm5.lock
.k5.REALM
The stash file is a local copy of the master key that resides in
encrypted form on the KDC's local disk. It is used to authenticate the
KDC to itself automatically before starting the kadmind
and
krb5kdc
daemons (e.g., as part of the machine's boot
sequence). The stash file, like the keytab file (see below) is a
potential point-of-entry for a break-in, and if compromised, would allow
unrestricted access to the Kerberos database. The stash file 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.
This password 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 (e.g., forward, backward, repeated twice, 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 "Cygnus Solutions 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 install script will now create the Kerberos database in the location
you specified. It will add the administrative principal,
admin/admin
, to the database; you can make future alterations to
the database by logging on as this principal.
admin/admin
principal. Enter the password. Re-enter it at the confirmation prompt.
The master (and also each slave KDC) needs a host principal in the Kerberos database. The install script will add this principal and key.
All Kerberos server machines, including the Admin server, need a
keytab file, called /etc/v5srvtab
.(2) The keytab is an encrypted, local,
on-disk copy of the host's key; it serves as the host's password during
authentication transactions. The keytab file, like the stash file, 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, should exist only on the machine's local disk, and should
never be exported as part of a distributed filesystem. The keytab 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.
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.
The install script creates the kadmin
keytab with entries for the principals kadmin/admin
and
kadmin/changepw
; the keytab is stored in
/usr/cygnus/kerbnet-1.2/lib/krb5kdc/kadm5.keytab
.
When the installation is finished, the install script automatically
starts the Kerberos daemons on the Master KDC. Each daemon will fork and
run in the background. If you want these daemons to start up
automatically at boot time, you can add them to the KDC's /etc/rc
or /etc/inittab
file. You need to have a stash file in order to
do this.
The admin server is now installed and ready.
Now that the admin server is installed, you should arrange for the database to be propagated at regular intervals to any slave KDCs you install. (See section Propagate the Database to Each Slave KDC, for more information about database propagation.)
You should also arrange for /usr/cygnus/kerbnet/install/rc.master
to be run at boot time, so that the Kerberos daemons will run when the
machine boots.
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.
In order to set up a KDC using the procedure described in this section, you need to log in as root on the machine you want to make into a KDC.
Once again, note that you must install KerbNet in the directory
/usr/cygnus/kerbnet-1.2
. If you extract the tar file from the
top-level directory (/
), the files will end up in this directory.
# /usr/cygnus/kerbnet-1.2/install/inst-config
The install script creates a krb5.conf
file and prompts you for
configuration information with the first few questions. The information
you enter here should match the information you entered for the admin
server.
Enter the names of your KDCs.
The script asks you which kind of system you want to set up.
/usr/cygnus/kerbnet
pointing to /usr/cygnus/kerbnet-1.2
.
If there is already a symbolic link in place, the script will skip this
question. If a symbolic link is in place pointing somewhere else, the
script will ask if you want to update the link to point to
/usr/cygnus/kerbnet-1.2
.
Type Yes to create the symbolic link.
/etc/services
file
at this point.
Type Yes or No.
If you say yes, it makes the appropriate changes to the file. If
you say no, it will list what changes are necessary. The rest of
the installation process may not work properly if /etc/services
has not been updated; if you do wish to change the file manually, rather
than having the script make the changes, you should exit the install
process by typing `^C' and edit the file manually before continuing
with the installation process.
For each service, type Yes to allow the service to run on the host, or No to not allow it to run.
/etc/inetd.conf
file
to account for the services you just selected. Type Yes or No.
When it changes inetd.conf
, the install script also adds two
lines that are necessary for database propagation. The first line sets
up the kpropd
database propagation daemon. The second line sets
up the eklogin
daemon, allowing Kerberos-authenticated, encrypted
rlogin to the KDC. If you choose to edit inetd.conf
manually,
the script will include these extra lines in the list of changes you
need to make.
/var/kerbnet/kdc
, or /etc/kerbnet/kdc
if your machine has no /var
directory. Enter the Kerberos
database path.
The install script creates the directory you specified and makes
/usr/cygnus/kerbnet-1.2/lib/krb5kdc
a symbolic link to it.
The install script creates the Kerberos database in the location you specified; however, it leaves the database empty. The slave's database receives its information from the admin server's database when database propagation occurs (see section Propagate the Database to Each Slave KDC).
As on the master KDC, the install script creates a stash file when it creates the database. As mentioned above, the stash file is necessary if you want 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 boot the machine or restart a KDC daemon.
admin/admin
principal. Enter the password. Re-enter it at the confirmation prompt.
The install script uses the admin password to communicate with the admin
server. It adds a principal and a key for this KDC to the Kerberos
database. The script also creates a keytab for the slave KDC, so that
the KDC can decrypt tickets. It creates the permissions file
/usr/cygnus/kerbnet-1.2/lib/krb5kdc/kpropd.acl
, which is necessary for
database propagation, and enters the appropriate information in it.
Now that the slave KDCs are able to accept database propagation, you need to propagate the database to each of them.
First, create a dump of the database on the master KDC, as follows. (The lines beginning with => are continuations of the previous line.):
shell% /usr/cygnus/kerbnet-1.2/sbin/kdb5_util dump => /usr/cygnus/kerbnet-1.2/lib/krb5kdc/slave_datatrans shell%
Next, you need to manually propagate the database to each slave KDC, as in the following example. (The lines beginning with => are continuations of the previous line.):
shell% /usr/cygnus/kerbnet-1.2/sbin/kprop -f => /usr/cygnus/kerbnet-1.2/lib/krb5kdc/slave_datatrans => kerberos-1.bleep.com shell% /usr/cygnus/kerbnet-1.2/sbin/kprop -f => /usr/cygnus/kerbnet-1.2/lib/krb5kdc/slave_datatrans => kerberos-2.bleep.com
The install script sets up a script to dump and propagate the database. You will need to set up a cron job to run this script at the intervals you decided on earlier (See section Database Propagation.)
If the install script runs into a problem, it may exit without setting up the propagation script. In that case, you will have to set up a script manually.
The following is an example of a bourne shell script that dumps and propagates the database. (Note that the line that begins with => is a continuation of the previous line. Remember that you need to replace /usr/cygnus/kerbnet with the name of the directory in which you installed KerbNet.)
#!/bin/sh kdclist="kerberos-1.bleep.com kerberos-2.bleep.com" /usr/cygnus/kerbnet/sbin/kdb5_util -R "dump \ /usr/cygnus/kerbnet/lib/krb5kdc/slave_datatrans" for kdc in $kdclist do /usr/cygnus/kerbnet/sbin/kprop -f \ /usr/cygnus/kerbnet/lib/krb5kdc/slave_datatrans $kdc done
krb5kdc
Daemon on Each KDCThe final step in configuring your slave KDCs is to run the KDC daemon:
shell% /usr/cygnus/kerbnet/install/rc.slave
on each of the slave KDCs. (N.B.: Do not run the
kadmind
daemon on the slave KDCs.)
As with the master KDC, you will probably want to add this command to
the KDCs' /etc/rc
or /etc/inittab
files, so they will
start the krb5kdc daemon automatically at boot time.
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. See section Some Advice about Secure Hosts.
If you have KerbNet installed on all of your client machines, Cygnus Solutions 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 KerbNet installed, you can run an insecure server, and still take advantage of KerbNet's single sign-on on capability.
As with installing KDCs, you need to be logged in as root on the machine you are setting up as an application server, in order to perform the installation.
Once again, note that you must install KerbNet in the directory
/usr/cygnus/kerbnet-1.2
. If you extract the tar file from the
top-level directory (/
), the files will end up in this directory.
shell% /usr/cygnus/kerbnet-1.2/install/inst-config
The install script creates a krb5.conf
file and prompts you for
configuration information with the first few questions. The information
you enter here should match the information you entered for the admin
server.
/usr/cygnus/kerbnet
pointing to /usr/cygnus/kerbnet-1.2
.
If there is already a symbolic link in place, the script will skip this
question. If a symbolic link is in place pointing somewhere else, the
script will ask if you want to update the link to point to
/usr/cygnus/kerbnet-1.2
.
Type Yes to create the symbolic link.
/etc/services
file
at this point.
Type Yes or No.
If you say yes, it makes the appropriate changes to the file. If
you say no, it will list the changes that are necessary. The rest
of the installation process may not work properly if
/etc/services
has not been updated; if you wish to change the
file manually, rather than having the script make the changes, you
should type `^C' to exit the installation process and make the
changes manually before continuing with the installation process.
For each service, type Yes to allow the service to run on the host, or No to not allow it to run.
/etc/inetd.conf
file
to account for the services you just selected.
Type Yes or No.
To enable the applications to run, the appropriate lines must be
inserted into /etc/inetd.conf
. If you tell the install script to
install the KerbNet versions of the telnet
and ftp
services, the script will comment out the old versions of those services
in inetd.conf
. Because KerbNet uses the klogin
and eklogin
service instead of the login
service, and
kshell
instead of the shell
service, it is not necessary
to comment out these lines to use KerbNet. The install script
does not comment out these services to ensure that installation never
results in any denial of existing services. However, if you want to
require Kerberos for remote access to your server (which you will want
to do for a secure server), Cygnus Solutions recommends that you
manually disable the login
and shell
services.
As with the /etc/services
file, you can type No and the script
will give you a list of changes that need to be made. These changes are
not critical for the rest of the installation process, so you can make
them either now or when you have finished installing the KerbNet
system.
The install script adds a principal and a key for this server to the database.
The application server is now installed and ready.
If you list telnet
and ftp
among the services you want the
server to run, the install script sets up the server to run the services
"insecurely," so that all users may use these services, whether or not
they are Kerberos-authenticated. If you want the server to be
"secure," (i.e., allow only Kerberos-authenticated users to
have remote access to the server), you should run Telnet and FTP in
"secure" mode.
To run Telnet and FTP securely, change the following lines in
/etc/inetd.conf
From:
ftp stream tcp nowait root /usr/cygnus/kerbnet/sbin/ftpd => ftpd telnet stream tcp nowait root /usr/cygnus/kerbnet/sbin/telnetd => telnetd -a none
To:
ftp stream tcp nowait root /usr/cygnus/kerbnet/sbin/ftpd => ftpd -a telnet stream tcp nowait root /usr/cygnus/kerbnet/sbin/telnetd => telnetd -a valid
A Kerberos application client is a machine that runs Kerberos applications that allow it to form secure connections to other machines, but does not run services allowing other machines to connect to it securely.
As with installing KDCs, you need to be logged in as root on the machine you are setting up as a KerbNet client, in order to perform the installation.
Once again, note that you must install KerbNet in the directory
/usr/cygnus/kerbnet-1.2
. If you extract the tar file from the
top-level directory (/
), the files will end up in this directory.
# /usr/cygnus/kerbnet-1.2/install/inst-config
The install script creates a krb5.conf
file and prompts you for
configuration information with the first few questions. The information
you enter here should match the information you entered for the admin
server.
First, the script prompts you to enter the name of your local realm.
The script prompts you for a list of KDCs.
The script prompts you for the name of the Admin KDC server.
The script asks you which kind of system you want to set up.
The script asks if you want to make a symbolic link
/usr/cygnus/kerbnet
pointing to /usr/cygnus/kerbnet-1.2
.
If there is already a symbolic link in place, the script will skip this
question. If a symbolic link is in place pointing somewhere else, the
script will ask if you want to update the link to point to
/usr/cygnus/kerbnet-1.2
.
The script asks if you want it to update the /etc/services
file
at this point.
If you say yes, it makes the appropriate changes to the file. If you say no, it will list the changes that are necessary.
The client machine is now set up and ready.
The Kerberized client programs are login.krb5
, rlogin
,
telnet
, ftp
, rcp
, rsh
, xdm
,
kinit
, klist
, kdestroy
, kpasswd
, ksu
,
and krdist
. All of these programs are in the directory
/usr/cygnus/kerbnet-1.2/bin
, except for login.krb5
and xdm
,
which are in /usr/cygnus/kerbnet-1.2/sbin
.
You will probably want to tell your users to place the directory
/usr/cygnus/kerbnet/bin
ahead of /bin
and /usr/bin
in
their paths, so they will by default get the KerbNet versions of
rlogin
, telnet
, ftp
, rcp
, and rsh
.
Cygnus Solutions recommends that you use login.krb5
, and
KerbNet xdm
in place of /bin/login
and ordinary
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 kinit
,
klist
, and kdestroy
, and to use the Kerberos programs
ksu
, kpasswd
, and krdist
, in place of their
non-Kerberos counterparts
su
, passwd
, and rdist
.
You will need to edit the xdm
configuration files, which are in
the directory /usr/cygnus/kerbnet-1.2/lib/X11/xdm
, based on your
installation. You will need to add a line of the following form to the
file Xservers
in that directory:
:0 local /usr/bin/X11/X :0
Replace /usr/bin/X11/X
with the path to your X server, and
`:0' with the actual display name, if different.
Additionally, if xdm
will be managing any foreign displays, you
will need a line for each foreign display as well. For example, if
xdm
were managing a display named
daffodil.bleep.com:1
, you would add the
following line:
daffodil.bleep.com:1 foreign
If you will be having xdm
manage multiple displays, you will also
need to add lines to the xdm-config
file for those displays. The
following lines are shipped in the file, for display `:0':
DisplayManager._0.authorize: true DisplayManager._0.setup: /usr/cygnus/kerbnet-1.2/lib/X11/xdm/Xsetup_0 DisplayManager._0.startup: /usr/cygnus/kerbnet-1.2/lib/X11/xdm/GiveConsole DisplayManager._0.reset: /usr/cygnus/kerbnet-1.2/lib/X11/xdm/TakeConsole
The `_0' in these lines translates to display `:0'. Add equivalent lines for other displays, replacing the `_0' with the other display names. Substitute underscores (`_') for the `:' and `.' characters.
If you are installing Xdm on a system, such as Solaris or Linux, that supports shadow passwords, and you want your users to be able to log in with their local passwords as well as their Kerberos passwords, the shadow password file must be kept up to date.
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 Xservers
file described above needs the
-force
option, as in the following example:
:0 local /usr/lpp/X11/bin/X -force :0
Again, replace /usr/lpp/X11/bin/X
with the correct path for your
X server, and `:0' with the actual display name, if different.
You need to make the following changes to files in the directory
/etc/security
. Follow this procedure instead of replacing
/bin/login
with login.krb5
.
In the file login.cfg
, you need to add the following lines under
the "Authentication methods" section
KerbNet: program = /usr/cygnus/kerbnet/sbin/login-auth
In the file /etc/security/user
, add the following lines, under
the `default:' heading:
auth1 = KerbNet auth2 = none SYSTEM = NONE
You can comment out any previous values for auth1
, auth2
,
and SYSTEM
using the `*' 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 `root:' section of /etc/security/user
:
auth1 = SYSTEM SYSTEM = "compat"
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 (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 /etc/environment
and/or
/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 kdestroy
command in their .logout
files.
KerbNet for Windows client installation includes a GUI ticket
management program (called KerbNet
) and a GUI telnet
program. Versions of KerbNet are available for Windows 3.1,
Windows95, and Windows NT. KerbNet for Windows client
installation on Windows NT also includes a GINA.
To install KerbNet clients for Windows, run the setup
program and answer the questions selecting the `compact' or
`typical' installation. For more details and for any other type of
installation see the KerbNet Installation Guide for
Windows NT
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. You may need to set the TZ variable at boot time to get the time zone information passed to correctly.
KerbNet for the Macintosh includes a GUI ticket management program
(called KerbNet config
) and a GUI telnet program. See
KerbNet for Macintosh User's Guide for more information.
To install the KerbNet ticket program and the ktelnet
program, unpack the archive and, if you wish, move the programs into the
folder of your choice.
To set up your configuration, transfer a krb5.conf
file from
another machine, either UNIX or Windows machine, with the correct
`realm' and `kdc' already specified. When transferring the
krb5.conf
file to your Macintosh we recommend using Fetch or some
other application that will translate text files (linefeed to
carriage-return) to Macintosh text format. If necessary, edit the file
using a text editor to make sure the correct `[libdefaults]'
variable are set. Rename the file to krb5.ini
and place it in
the preferences folder under the system folder.
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.
If you already have a KerbNet system installed on a machine, you can run the install script on that machine to install this version of the KerbNet system. The script uses information about your existing setup to create the default options it offers you; some steps of the process are not necessary if there is an existing KerbNet system, so the script does not prompt you for those steps. Otherwise, the installation process is the same for a machine with an existing system as it is for one without an existing system.
This chapter describes how to keep information from your old setup when you reinstall a KerbNet system.
If the install script finds a list of KDCs already in krb5.conf
,
it will show you the list and ask you whether you want to keep that
list. If you type Yes, the list remains unchanged and the script does
not ask you for new KDC names; if you type No, the script prompts you
for a new list of names, as usual.
When you run the install script, it checks to see if a Kerberos database already exists. If it finds a database, the script will ask if you want to delete it. If you say Yes, it deletes the old database and creates a new one as usual. However, you may want to keep the information from your old database. In that case, type No; the install script will exit at this point.
To set up the KDC, retaining the information from the old database:
shell% /usr/cygnus/kerbnet-1.2/sbin/kdb5_util dump => /usr/cygnus/kerbnet-1.2/lib/krb5kdc/dbdump
shell% kill krb5kdc shell% kill kadmind shell%kill krb524d
shell% kdb5_util load /usr/cygnus/kerbnet-1.2/lib/krb5kdc/dbdump
/usr/cygnus/kerbnet-1.2/lib/krb5kdc/kadm5.keytab
, which contains the old kadmin
keys.
kadmin
keytab by typing the following commands:
shell% /usr/cygnus/kerbnet/sbin/kadmin.local kadmin.local: ktadd -k /usr/cygnus/kerbnet/lib/krb5kdc/kadm5.keytab => kadmin/admin kadmin/changepw kadmin.local: quit
admin/admin
principal and that you know its password.
shell% /usr/cygnus/kerbnet-1.2/sbin/krb5kdc shell% /usr/cygnus/kerbnet-1.2/sbin/kadmind
As with a regular installation, you should arrange for automatic database propagation to any slaves, and for the Kerberos daemons to run when the machine boots.
For slave servers, you can delete the old database during installation and propagate it to the slave from the admin server afterwards (assuming you preserved the old information in the admin server's database).
If you used the master password for the old database as the new master password, you can keep the stash file that the install script created. If you used a new password, you will have to manually re-create the stash file so that it contains the current password.
To make a new stash file:
shell% /usr/cygnus/kerbnet-1.2/sbin/kdb5_util stash
kdb5_util
prompts you for it.
If you run the install script for an admin server when you already have KerbNet installed, the script should not extract a host key for the machine, since the already-existing keytab should have the host key in it already. However, if the script cannot find a host key in the keytab, it will extract one, creating it in the database if necessary.
If you update the new database with a dump from your old database, you erase this new principal in the database, but do not change the keytab. Therefore, the host principal in the database (if there is one) has the old key, while the host principal in the keytab has the newly-generated key. These keys do not match, so the server will not be able to authenticate itself.
To correct this problem, you need to add a host principal to the database, delete the outdated host key from the keytab, and then extract the host key to the keytab again.
shell% kadmin.local kadmin.local: addprinc -randkey host/<hostname>@REALM
Here, <hostname>
is the fully-qualified hostname of the machine
you are installing as an admin server, and REALM
is the realm.
The -randkey
option generates a key for the host principal.
shell% kadmin.local kadmin.local: ktremove <hostkey>
where <hostkey>
is the principal that the install script created.
kadmin.local: ktadd host/<hostname>@REALM kadmin.local quit
The principal you add is the same one you added to the Kerberos database. This command extracts (copies) the principal with its key from the database and adds them to the keytab.
If you have run the install script on this machine before, it does not
ask you where you want to store the database and kdc.conf
, but
installs them in the directory you specified the first time you ran the
script.
The install script created the Access Control List, `kadm5.acl'
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
kdc.conf
file. The default file name is `kadm5.acl'. The
format of the file is:
Kerberos principal permissions optional target principal
The Kerberos principal (and optional target principal) can include the
"*" wildcard, so if you want any principal with the instance
"admin" to have full permissions on the database, you could use the
principal "*/admin@REALM
" where "REALM" is your Kerberos
realm.
Note: a common use of an 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
jschmoe
might have a principal for his administrative
use, called jschmoe/admin
. This way,
jschmoe
would obtain jschmoe/admin
tickets only when he actually needs to use those permissions. Refer to
the KerbNet Administrator's Guide or the KerbNet User's
Guide for more detailed explanations of principals and
instances.
The permissions (acls) recognized in the acl file are the following:
To give the principal */admin@BLEEP.COM
(any
principal that has the instance "admin", in the realm
BLEEP.COM) permission to change any attribute on any
principal in the database, you would place the following line in the
file:
*/admin@BLEEP.COM *
To give the principal jschmoe@BLEEP.COM
permission to add, list, and inquire about any principal that has the
instance "root", you would add the following line to the acl file:
jschmoe@BLEEP.COM ali */root@BLEEP.COM
Once your KDCs are set up and running, you are ready to use
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 KerbNet System
Administrator's Guide. The keytab is generated by running kadmin
and issuing the ktadd
command.
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 old master KDC:
kadmind
process.
On the new master KDC:
shell% /usr/cygnus/kerbnet/sbin/kadmin.local kadmin.local: ktadd -k /usr/cygnus/kerbnet/lib/krb5kdc/kadm5.keytab => kadmin/admin kadmin/changepw kadmin.local: quit
kadmind
daemon by typing:
shell% /usr/cygnus/kerbnet/sbin/krb5kdc
krb5.conf
file on every client
machine in your Kerberos realm.)
The default installation uses the default syslog options as described in
the KerbNet System Administrator's Guide. If you are not
running syslog, this may cause krb5kdc
to hang. Change the
`[logging]' section of the krb5.conf file, so that all logs go to a
file see section kdc.conf for an example and KerbNet System
Administrator's Guide for a complete listing of options.
To limit the possibility that your Kerberos database could be compromised, Cygnus Solutions recommends that each KDC be a dedicated host, with limited access and a limited number of users in the password file. 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.
Cygnus Solutions recommends that your KDCs use the following
/etc/inetd.conf
file. (Note: each line beginning with =>
is a continuation of the previous line.):
# # 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> => <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 daytime stream tcp nowait root internal daytime dgram udp nowait root internal # # # Limited Kerberos services # # telnetd is not included because there is no way currently to require # encryption. krb5_prop stream tcp nowait root /usr/cygnus/kerbnet/sbin/kpropd kpropd eklogin stream tcp nowait root /usr/cygnus/kerbnet/sbin/klogind => klogind -5 -c -e
KerbNet can protect your host from certain types of break-ins, but it is possible to install KerbNet 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, Cygnus Solutions recommends that on a
secure host, you disable the standard ftp
, login
,
telnet
, shell
, and exec
services in
/etc/inetd.conf
. We also recommend that secure hosts have an empty
/etc/hosts.equiv
file and that there not be a .rhosts
file
in root
's home directory. You can grant Kerberos-authenticated
root access to specific Kerberos principals by placing those principals
in the file .k5login
in root's home directory.
We recommend that backups of secure machines exclude the keytab file
(/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 KerbNet binaries, should be kept on local disk. The keytab file should be readable only by root.
send-pr
program
is installed in the directory /usr/cygnus/kerbnet/bin
.
Before using send-pr
for the first time, you need to install your
customer support ID into the program, by typing the command:
shell% install-sid customerID
replacing customerID with your customer ID, which your sales representative will supply.
The 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 (e.g., if the engineer
gets hit by a truck), we can find out what the current state is through
the PR number. Cygnus Solutions uses PRMS for almost all of the real
problems we handle.
The send-pr
program will try to intelligently fill in as many
fields as it can. You need to choose the category, class,
severity, and priority of the problem, as well as giving us
as much information as you can about its exact nature.
The PR category will be one of:
kerberos kerbnet doc help-request info-request install query-pr id-request send-pr
In general, if specific knowledge about Kerberos is requried to answer a PR, use the kerberos or doc categories. The install category is for problems retrieving the code off the media (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 kerberos. The help-request and info-request categories are for general questions about your contract, or other issues not necessarily related to KerbNet. Use query-pr to receive a current copy of your Problem Report, id-request if you need a customer ID, and send-pr if you're having trouble using send-pr. If your question is related to KerbNet and you're not sure what the most appropriate category should be, use kerberos. The engineer can change the category if necessary.
The class can be sw-bug, doc-bug, change-request, or support. The first two are exactly as their names imply. The change-request class is to inform us of changes, such as new email addresses or new contact information. The support class is intended for general questions about using the KerbNet clients or libraries.
The severity of the problem indicates the problem's impact on the usability of the KerbNet software package. If a problem is critical, that means the product, component or concept is completely non-operational, or some essential functionality is missing, and no workaround is known. A 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 critical are rated serious when a workaround is known. A non-critical problem is one that is indeed a problem, but one that is having a minimal affect on your ability to use KerbNet. 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 serious.
The priority indicates how urgent this particular problem is in relation to your work. Note that low priority does not imply low importance. Cygnus Solutions considers all problems important, and encourages its customers to be realistic about priority ratings. A priority of high means a solution is needed as soon as possible. A priority of medium means the problem should be solved no later than the next release. A priority of 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 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 release is as labeled on the software that was shipped.
e.g., kerbnet-1.2
. 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 (`diff -c') or unified diffs (`diff -u').
l
A sample filled-out form from a company named "Toasters, Inc." might look like this:
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.2 >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: <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.
l
If the send-pr
program does not work for you, you can use the
following template instead:
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)>
Here is an example of a generic krb5.conf
file:
[libdefaults] ticket_lifetime = 600 default_realm = BLEEP.COM default_tkt_enctypes = des-cbc-crc default_tgs_enctypes = des-cbc-crc [realms] BLEEP.COM = { kdc = kerberos.bleep.com:88 kdc = kerberos-1.bleep.com:88 kdc = kerberos-2.bleep.com:88 admin_server = kerberos.bleep.com:749 default_domain = bleep.com } [domain_realm] bleep.com = BLEEP.COM
l
Here's an example of a generic kdc.conf file:
[kdcdefaults] kdc_ports = 88 [realms] BLEEP.COM = { 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 des-cbc-crc:v4 } [logging] kdc = FILE:/usr/cygnus/kerbnet/lib/krb5kdc/kdc.log admin_server = FILE:/usr/cygnus/kerbnet/lib/krb5kdc/kadmin.log
Currently, KerbNet supports only DES encryption. The encoding
type is des-cbc-crc
. The 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:
Support for additional encryption types is planned in the future.