     [file definitions.texinfo not included]

Upgrading to PRODUCT from Kerberos V4
*************************************

This document describes how to convert to PRODUCT from Kerberos V4.

     [file copyright.texinfo not included]

Installing PRODUCT at Your Site
*******************************

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:

  * Install and configure the CNS software on the machines at your site.

  * Set up a CNS Key Distribution Center server machine.

  * [Optional] Set up one or more slave servers for reliability.

  * Install and configure CNS client software on the machines from which your remote users log in.

  * 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.)

  * Inform your users about CNS.

  * [Optional] Turn off ordinary rlogin, telnet, ftp, and rsh services so that users are required to use CNS rather than potentially exposing their passwords.

This manual covers only basic installation and configuration of the CNS software.  See the Administration Tools (Cygnus Network Security User and Administrator Documentation for CNS Version 5), manual for more detailed information.

Contents of the CNS V5 distribution.
====================================

A collection of programs are included in CNS. The categories are

  * user programs such as kinit, klist, kdestroy, kpasswd, krb524init

  * replacement programs such as rlogin, rcp, rsh, telnet, ftp, ksu

  * demos such as sim_client, sclient, uuclient, gss-client

  * administration tools such as kdb5_anadd, kdb5_convert, kdb5_create, kdb5_destroy, kdb5_edit, kdb5_stash, and the client program kadmin5

  * programming support such as include files and libraries for writing kerberized (The verb to kerberize means to modify (usually an application) to use Kerberos for authentication and possibly encryption.) applications.

  * documentation in the form of man pages.

  * kerberized application servers such as ftpd, krlogind, krshd, popper, telnetd, sim_server, sserver, uuserver

  * kerberos management servers such as kadmind5, kpropd, krb524d, krb5kdc, v4kadmind

Where programs should be installed
==================================

Cygnus releases unpack in directories named /usr/cygnus/PACKAGE-RELEASE. It is suggested that a user-convenience symlink be placed in /usr/cygnus pointing from PACKAGE to PACKAGE-RELEASE, for example from cns5 to 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 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 lib/krb5kdc to a local directory, perhaps in /var.

     mkdir /var/krb5kdc
     chmod 700 /var/krb5kdc
     ln -s /var/krb5kdc /usr/cygnus/cns5/lib/krb5kdc

Also, /usr/cygnus/cns5/lib/krb5.conf is a fallback location for a common config file -- /etc/krb5.conf is examined instead if present, and the user can override by setting the environment variable KRB5_CONFIG. Since /etc is usually local, if you want to avoid maintaining krb.conf files on all machines, one approach is to create a /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.

Configuration Files affected
============================

A number of files should be adjusted for kerberos use.

/etc/services
     needs to contain additional entries for kerberos and application servers.

/etc/inetd.conf
     needs to contain lines for the new kerberized services

/etc/rc.local
     (or equivalent) needs to contain commands to start up long-running kerberos servers (kadmind5, krb5kdc, and krb524d)

Getting Started from an existing Realm
======================================

If you're converting from a V4 realm, you can do

     	.../admin/kdb5_convert

directly from an existing database, or

     	/usr/kerberos/bin/kdb_util dump v4db
     	.../admin/kdb5_convert -f v4db

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

     	.../admin/kdb5_create

and possibly

     	.../admin/kdb5_stash

The config files for this release are completely different from the V4 config files; they're much more like windows .ini files, and are called profiles. The default location (which can be adjusted via the KRB_CONF environment variable) is /etc/krb5.conf. An example file follows. You'll need to change the default_realm and add a stanza (like the CYGNUS.COM={...} section) for your realm.

     [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

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.)

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:

     % kdb5_edit
     kdb5_edit: av4k afs/CELL.NAME
     kdb5_edit: xst CELL.NAME afs

which should create a CELL.NAME-new-srvtab which should be securely moved to the afs server and placed in /etc/v5srvtab.

To double check,

     % klist -k CELL.NAME-new-srvtab

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

     % asetkey add 1 /etc/v5srvtab afs/CELL.NAME

(where 1 is the key version number, and afs/CELL.NAME is the principal for the server [which will get converted by krb524d to afs.CELL.NAME]) will initialize the afs key list.

     % asetkey list

should show the current list.

If you're using cklog for interrealm AFS, you may need to duplicate the afs/CELL.NAME@REALM key as afs@REALM.

Redundant Slave Servers
=======================

CNS V5 supports redundant slave servers. The 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 krb5.conf) to talk to the nearest one instead. Note that all password changes and other administrative operations must go through the master server.

 1. On both the master and slave, add the following line to /etc/services:

          krb5_prop       754/tcp                         # Kerberos slave propagation

On the slave,

 1. Add the principal name for the master to the ACL for kpropd.

           echo host/MASTER.HOST.NAME@REALM > /usr/cygnus/cns5/lib/krb5kdc/kpropd.acl

 2. Add a line to /etc/inetd.conf that enables the receiving kpropd.

          krb5_prop stream tcp nowait root /usr/cygnus/cns5/sbin/kpropd kpropd

     On the master:

 1. Be sure that the master has a v5srvtab (created with

          	sbin/kdb5_edit
          		ark host/MASTER.HOST.NAME
          		xst MASTER.HOST.NAME host
          	mv MASTER.HOST.NAME-new-srvtab /etc/v5srvtab

     you've probably already done this.)

 2. Create an initial database dump for transfer to the slave.

           echo ddb /usr/cygnus/cns5/lib/krb5kdc/slave_datatrans | admin/kdb5_edit
           sbin/kprop slavehost

 3. Back on the slave, securely install the stash file, and start the kdc:

          	rcp -xp root@MASTER:/.k5.REALM /.k5.REALM
          	sbin/krb5kdc

 4. On any clients, add an addition

          	kdc = MASTER.HOST.NAME

     line to the REALM entry in the [realms] section of krb5.conf.

For continued operation,

 1. Run sbin/krb5kdc on the slave (usually from /etc/rc.local).

 2. On the master, Periodically (using the cron facility) run

            echo ddb /usr/cygnus/cns5/lib/krb5kdc/slave_datatrans | admin/kdb5_edit
            sbin/kprop SLAVE.HOST.NAME

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.

Arranging Interrealm Authentication
===================================

Kerberos V4 supports simple automatic cross-realm authentication. Given two realms REALM1 and REALM2, the administrators agree on a common key, and then create

     	krbtgt.REALM2 (in the REALM1 database)
     	krbtgt.REALM1 (in the REALM2 database.)

At this point, a user with tickets USER@REALM1 can get tickets for servers in REALM2 automatically, and is authenticated as USER@REALM1, not as simply USER.

Kerberos V5 uses the same mechanism with different names.

     	krbtgt/REALM2 (in the REALM1 database)
     	krbtgt/REALM1 (in the REALM2 database.)

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,

     	% kdb5_edit
     	kdb5_edit: ank krbtgt/REALM2

(and the corresponding krbtgt/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:

     	% kdb5_edit
     	kdb5_edit: av4k krbtgt/REALM2

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.

Servers that support V4 clients
-------------------------------

The rlogind and 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 /etc/krb-srvtab, but this can be changed in the krb5.conf file by setting the variable krb5_srvtab in the [libdefaults] stanza to a filename.

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.)

Version 4 Adminstration Server
------------------------------

Many existing clients support password change functions using the old V4 administrative protocol. 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 ACL files from /usr/kerberos/lib/admin_acl.TAG to /usr/cygnus/cns5/lib/krb5kdc/v4acl.TAG (TAG can be one of add, del, get, or mod.)  and run v4kadmind.