     [file definitions.texinfo not included]

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

Copyright
*********

     [file copyright.texinfo not included]

Introduction
************

As with most software upgrades, PRODUCT is generally backward compatible but not necessarily forward compatible.  The PRODUCT daemons can interoperate with Kerberos V4 clients, but most of the Kerberos V4 daemons can not interoperate with Kerberos V5 clients.  This suggests the following strategy for performing the upgrade:

 1. Upgrade your KDCs.  This must be done first, so that interactions with the Kerberos database, whether by Kerberos V5 clients or by Kerberos V4 clients, will succeed.

 2. Upgrade your servers.  This must be done before upgrading client machines, so that the servers are able to respond to both Kerberos V5 and Kerberos V4 queries.

 3. Upgrade your client machines.  Do this only after your KDCs and application servers are upgraded, so that all of your Kerberos V5 clients will be talking to Kerberos V5 daemons.

Configuration Files
*******************

The Kerberos krb5.conf and KDC kdc.conf configuration files allow additional tags for Kerberos V4 compatibility.

krb5.conf
=========

If you used the defaults, both when you installed Kerberos V4 and when you installed PRODUCT, you should not need to include any of these tags.  However, some or all of them may be necessary for nonstandard installations.

[libdefaults]
-------------

In the [libdefaults] section, the following additional tags may be used:

krb4_srvtab
     Specifies the location of the Kerberos V4 srvtab file.  Default is DefaultKrb4Srvtab.

krb4_config
     Specifies the location of the Kerberos V4 configuration file.  Default is DefaultKrb4Config.

krb4_realms
     Specifies the location of the Kerberos V4 domain/realm translation file.  Default is DefaultKrb4Realms.

[realms]
--------

In the [realms] section, the following Kerberos V4 tags may be used:

default_domain
     Identifies the default domain for hosts in this realm.  This is needed for translating V4 principal names (which do not contain a domain name) to V5 principal names.  The default is your Kerberos realm name, converted to lower case.

v4_instance_convert
     This subsection allows the administrator to configure exceptions to the default_domain mapping rule.  It contains V4 instances (tag name) which should be translated to some specific hostname (tag value) as the second component in a Kerberos V5 principal name.

v4_realm
     This relation allows the administrator to configure a different realm name to be used when converting V5 principals to V4 ones.  This should only be used when running separate V4 and V5 realms, with some external means of password sychronization between the realms.

AFS and the Appdefaults Section
-------------------------------

Many Kerberos 4 sites also run the Andrew File System (AFS).

Modern AFS servers (OpenAFS > 1.2.8) support the AFS 2b token format. This allows AFS to use Kerberos 5 tickets rather than version 4 tickets, enabling cross-realm authentication.  By default, the krb524d service will issue the new AFS 2b tokens.  If you are using old AFS servers, you will need to disable these new tokens. Please see the documentation of the appdefaults section of krb5.conf in the Kerberos Administration guide.

kdc.conf
========

Because Kerberos V4 requires a different type of salt for the encryption type, you will need to change the supported_enctypes line in the [realms] section to:

     supported_enctypes = des-cbc-crc:normal des-cbc-crc:v4

This is the only change needed to the kdc.conf file.

Upgrading KDCs
**************

To convert your KDCs from Kerberos V4 to PRODUCT, do the following:

 1. Install PRODUCT on each KDC, according to the instructions in the PRODUCT Installation Guide, up to the point where it tells you to create the database.

 2. Find the kadmind (V4) daemon process on the master KDC and kill it.  This will prevent changes to the Kerberos database while you convert the database to the new Kerberos V5 format.

 3. Create a dump of the V4 database in the directory where your V5 database will reside by issuing the command:

          % kdb_util dump ROOTDIR/var/krb5kdc/v4-dump

 4. Load the V4 dump into a Kerberos V5 database, by issuing the command:

          % kdb5_util load_v4 v4-dump

 5. Create a Kerberos V5 stash file, if desired, by issuing the command:

          % kdb5_util stash

 6. Proceed with the rest of the PRODUCT installation as described in the PRODUCT Installation Guide.  When you get to the section that tells you to start the krb5kdc and kadmind daemons, first find and kill the Kerberos V4 kerberos daemon on each of the KDCs.  Then start the krb5kdc and kadmind daemons as You will need to specify an argument to the -4 command line option to enable Kerberos 4 compatibility. See the krb5kdc man page for details. directed.  Finally, start the Kerberos V5 to V4 ticket translator daemon, krb524d, by issuing the command:

          % ROOTDIR/sbin/krb524d -m > /dev/null &

     If you have a stash file and you start the krb5kdc and kadmind daemons at boot time, you should add the above line to your /etc/rc (or /etc/rc.local) file on each KDC.

Upgrading Application Servers
*****************************

Install PRODUCT on each application server, according to the instructions in the PRODUCT Installation Guide, with the following exceptions:

  * In the file /etc/services, add or edit the lines described in the PRODUCT Installation Guide, with the following exception:

     in place of:

          kerberos      DefaultPort/udp    kdc    # Kerberos V5 KDC
          kerberos      DefaultPort/tcp    kdc    # Kerberos V5 KDC

     add instead:

          kerberos-sec  DefaultPort/udp    kdc    # Kerberos V5 KDC
          kerberos-sec  DefaultPort/tcp    kdc    # Kerberos V5 KDC

  * Convert your Kerberos V4 srvtab file to Kerberos V5 keytab file as follows:

          # ROOTDIR/sbin/ktutil
          ktutil:  rst /etc/krb-srvtab
          ktutil:  wkt /etc/krb5.keytab
          ktutil:  q
          #

Upgrading Client machines
*************************

Install PRODUCT on each client machine, according to the instructions in the PRODUCT Installation Guide.

Tell your users to add the appropriate directory to their paths.  On UNIX machines, this will probably be BINDIR.

Note that if you upgrade your client machines before all of your application servers are upgraded, your users will need to use the Kerberos V4 programs to connect to application servers that are still running Kerberos V4.  (The one exception is the UNIX version of PRODUCT telnet, which can connect to a Kerberos V4 and Kerberos V5 application servers.)  Users can use either the Kerberos V4 or PRODUCT programs to connect to Kerberos V5 servers.

Firewall Considerations
***********************

PRODUCT uses port DefaultPort, which is the port assigned by the IETF, for KDC requests.  Kerberos V4 used port DefaultSecondPort.  If your users will need to get to any KDCs outside your firewall, you will need to allow TCP and UDP requests on port DefaultPort for your users to get to off-site Kerberos V5 KDCs, and on port DefaultSecondPort for your users to get to off-site Kerberos V4 KDCs.